Vercel AI SDK v7 a examen: excelente capa de aplicación TypeScript, no una plataforma AI completa
Vercel AI SDK es un toolkit TypeScript independiente del proveedor para funciones AI en aplicaciones web y Node.js. AI SDK Core normaliza generación, salida estructurada y tools; AI SDK UI ofrece hooks y un protocolo de datos; los paquetes de provider traducen las llamadas a cada API. El repositorio actual exige Node.js 22 o posterior y usa licencia Apache 2.0.
La referencia de esta revisión es [email protected], publicado el 19 de agosto de 2026. Vercel mantiene a la vez ramas v5 y v6. Un tutorial puede haber sido correcto y no describir la API v7. Los agentes actuales usan ToolLoopAgent y stopWhen; useChat adoptó una arquitectura de transporte en v5 y dejó de administrar internamente el input. El lockfile manda.
Conviene separar productos. El SDK open source puede llamar directamente a un provider. Vercel AI Gateway es un servicio alojado de routing, facturación y presupuestos. AI Elements es una librería opcional de componentes basada en shadcn/ui. Hosting y Observability de Vercel Cloud también son servicios aparte. Mezclarlos oculta flujo de datos, precio y dependencia.
Estado en 2026
| Elemento | Estado verificado | Impacto |
|---|---|---|
| Versión principal | [email protected] (2026-08-19) | fijar major |
| Runtime | Node.js 22+ | comprobar runtime |
| Licencia | Apache-2.0 | términos aparte |
| Core API | generateText / streamText / tools | comportamiento distinto |
| Agent API | ToolLoopAgent; 20 steps par défaut | presupuesto explícito |
| UI | React / Vue / Svelte / Angular | auth/estado propios |
| Ruta por defecto | Gateway dans les exemples actuels | provider directo posible |
| Telemetría | OpenTelemetry expérimental opt-in | exportación sensible |
Qué pertenece al SDK y qué es independiente
| Capa | Qué aporta | Límite propio |
|---|---|---|
| AI SDK Core | generation, stream, tools, structured output | semántica y uso del provider |
| Provider packages | API adapter / special options | versión y paridad |
| AI SDK UI | hooks / transports / rich streams | auth, persistencia, errores |
| ToolLoopAgent | loop / approval / stop | no es runtime durable |
| MCP | tools / resources / prompts | confianza y autorización |
| AI Elements | optional UI components | no es Core |
| AI Gateway | hosted route / budget / fallback | plano de datos separado |
| Vercel Cloud | hosting / observability | servicio independiente |
Abstracción de proveedores, streaming y agentes
La abstracción funciona bien en el denominador común: texto, mensajes, tool calls, resultados estructurados y uso normalizado. No convierte modelos en equivalentes. Reasoning, tokens en caché, archivos, imágenes, hosted tools, rechazos de seguridad, identificadores, errores y opciones cambian por proveedor. Conserve providerMetadata, finish reason sin normalizar y warnings en las pruebas. Sin matriz de capacidades, la interfaz portable solo aplaza las diferencias hasta producción.
El streaming tiene dos capas. streamText produce partes de modelo y herramientas en el servidor; el transporte de AI SDK UI las lleva al cliente como mensajes ricos. El flujo de texto es simple, pero no puede transportar tool calls, usage ni finish reasons. Producción requiere estados explícitos para cancelación, retry, resultado parcial, eventos duplicados, desconexión, reconexión y error. Recibir el primer token no prueba que estado final y factura coincidan.
ToolLoopAgent facilita el bucle, pero no es un runtime duradero. Termina cuando el modelo deja de pedir herramientas, falta execute, se necesita aprobación o actúa una condición de parada. Veinte pasos por defecto pueden ser excesivos. Defina un límite menor por tarea, timeout global, AbortSignal, presupuesto de tokens/dinero y permisos de tools. Pagos, aprobaciones y sincronizaciones repetibles deben seguir un workflow determinista; reserve el agente para decisiones ambiguas.
Flujo de migración y evaluación para producción
- Fijar Node.js,
ai, UI y providers en lockfile; registrar major y release notes. - Inventariar prompts, mensajes, opciones, schemas, stream, retries, almacenamiento y billing.
- Crear matriz de tool calling, structured output, reasoning, archivos, safety, usage, contexto y región.
- Preparar golden set redactado y ataques de injection, argumentos inválidos, permisos denegados y acciones duplicadas.
- Envolver generateText/streamText en un adapter fino; mantener visibles las opciones específicas.
- Añadir auth de servidor, tenant authorization, allowlist, approvals, idempotencia, timeouts y presupuestos.
- Observar métricas normalizadas y warnings/finish reasons raw; no exportar payload sensible sin política.
- Hacer shadow y luego canary; comparar calidad, integridad streaming, tools, latencia y factura.
- Probar abort, desconexión, retry y fallo Gateway/provider; guardar el adapter antiguo hasta practicar rollback.
- Repetir regresión al cambiar major, adapter, model, prompt, tool o política de routing.
Qué medir antes de cambiar de proveedor
| Métrica | Prueba | Importancia |
|---|---|---|
| Answer quality | rubric + blind pairwise | API no es modelo |
| Structured output | schema + semantic accuracy | JSON válido puede fallar |
| Tool behavior | selection / args / approval / duplicates | riesgo de efectos |
| Stream integrity | first/final/order/reconnect/cancel | cliente y servidor divergen |
| Latency | p50/p95 first + complete | routing cambia UX |
| Cost | tokens + invoice | contabilidad distinta |
| Safety | injection / exfiltration / permission | output no confiable |
| Reliability | timeout / error / rollback | importan los fallos |
Una migración no empieza cambiando imports. Inventaríe llamadas, system prompts, mensajes, schemas, eventos streaming, retries, campos de uso y opciones específicas. Guarde traces representativos después de eliminar datos sensibles. El golden set debe incluir consultas normales, contexto largo, idiomas, refusals, argumentos malformados, tools paralelas, error del provider, stream interrumpido, preguntas imposibles y prompt injection. Ejecute camino antiguo y nuevo con idénticos inputs y capture resultados normalizados y raw.
Separe métricas: calidad, schema válido, selección correcta de tool, ejecución y fidelidad final no son una sola nota. Añada tiempo al primer evento, latencia total, tokens input/output/cache, coste de factura, cancelación y finalización del stream. En agentes mida pasos, tool calls repetidas, aprobaciones, timeouts y efectos duplicados. Empiece con shadow traffic, continúe con canary por tenant o porcentaje y conserve adapter y versión de protocolo anteriores hasta ensayar rollback.
La integración OpenTelemetry es útil, pero oficialmente experimental y opt-in por llamada mediante experimental_telemetry. Puede incluir prompts, texto de respuesta, tool calls y atributos. Trátela como exportación de datos: redacte valores, limite cardinalidad, sampling, retención y acceso. La Observability alojada de Vercel es otro producto; instalar ai no crea automáticamente una suite de evaluación, almacén de trazas ni proceso de incidentes.
Seguridad, privacidad, coste y dependencia
| Riesgo | Control | Límite residual |
|---|---|---|
| Prompt injection | instruction/data separation + allowlist | model may follow hostile content |
| Unauthorized action | server identity/tenant authorization | schema is not access control |
| Duplicate action | idempotency + transaction log | retry may repeat |
| Runaway cost | stopWhen + time/token/step budget | 20 steps is not a business budget |
| Telemetry leak | redact/sample/retention/access | prompts can be exported |
| Gateway drift | pin provider/model/region | fallback changes reproducibility |
| Version mismatch | pin every AI SDK package | old tutorials remain visible |
| False portability | capability matrix/regression | common type ≠ same semantics |
Vercel AI SDK frente a alternativas
| Opción | Elegir si | Diferencia |
|---|---|---|
| Vercel AI SDK v7 | TypeScript streaming / multi-provider UI | strong ergonomics; governance external |
| OpenAI Node SDK | OpenAI-native features | minimal translation; provider coupling |
| LangChain JS | integrations / middleware / agents | larger abstraction surface |
| LangGraph JS | durable state / checkpoints / interrupts | more orchestration; better resume |
| OpenAI Agents SDK TS | handoffs / guardrails / tracing | agent and OpenAI centered |
| Custom/provider SDK | one provider / full protocol control | build UI, tools, portability |
| AI SDK + Gateway | unified budget / routing / fallback | adds Vercel data plane |
La seguridad se construye por encima del SDK. Zod o JSON Schema valida la forma del argumento, no el derecho del usuario a reembolsar, consultar otro tenant o enviar correo. Resuelva identidad y tenant en servidor, autorice cada invocación, minimice credenciales, valide outputs y audite. Los efectos necesitan idempotency key y las acciones críticas aprobación humana. Documentos recuperados, páginas web, MCP y outputs previos son datos no confiables con posible prompt injection.
El routing y fallback automáticos de Gateway elevan disponibilidad, pero pueden cambiar comportamiento, procesador, región y precio. Para compliance o reproducibilidad, fije provider/model/region o limite rutas. Como fotografía fechada, la página de febrero de 2026 indicaba créditos mensuales gratuitos, PAYG sin markup de tokens y BYOK sin tarifa Gateway; verifique siempre la página viva. La conexión directa reduce esa frontera Vercel, pero exige presupuestos, fallback y uso consolidados propios.
Nuestro veredicto: AI SDK v7 es una gran capa de aplicación para equipos TypeScript que entregan una UI streaming y comparan varios modelos. Tipos, protocolo y primitives reducen glue code. No es el centro ideal de procesos multiagente largos y reanudables; LangGraph o un motor de workflows ofrece mejor durabilidad. Si predominan features nativas de un proveedor, su SDK directo resulta más transparente. El motivo de adopción es ergonomía, no una promesa de seguridad, portabilidad u operaciones gratuitas.
Preguntas frecuentes
¿Es gratis y open source?
El SDK es Apache-2.0. Providers, modelos, AI Gateway, Vercel Cloud y otros servicios tienen precios y condiciones propias.
¿Debo alojar en Vercel?
No. Es una librería TypeScript para Node.js. Gateway es un default cómodo en ejemplos actuales, no un requisito.
¿Cuál es la versión actual?
El 20-08-2026 la principal es [email protected]; v5/v6 reciben mantenimiento, por eso debe comprobar el lockfile.
¿Gateway forma parte del SDK open source?
No. Es un servicio alojado de routing y facturación; el SDK también llama directamente a providers.
¿ToolLoopAgent es seguro por sí solo?
No. Requiere authorization, allowlist, approval, idempotencia, timeout, stop conditions, audit y pruebas adversariales.
¿La abstracción garantiza la misma salida?
No. Normaliza formas comunes; comportamiento, opciones, uso, errores, safety y features difieren.
¿Text stream o UI message stream?
Texto sirve para una interfaz básica; tools, usage, finish reason y rich parts requieren el protocolo UI.
¿Telemetry puede enviar prompts?
Sí, según configuración. Defina redaction, sampling, retención y acceso antes del opt-in experimental.
¿Cuándo elegir LangGraph?
Cuando ejecución durable, estado persistente, interrupts, tareas largas y reanudación son requisitos principales.
¿Cómo migrar sin romper chat?
Version pin, golden/failure suite, shadow, canary, contrato streaming y adapter de rollback probado.
Fuentes y verificación
- AI SDK repository
- AI SDK releases
- Apache 2.0 license
- Core: generateText and streamText
- Tool calling
- ToolLoopAgent reference
- AI SDK UI transports
- AI SDK stream protocol
- MCP integration
- OpenTelemetry integration
- Vercel AI Gateway overview
- AI Gateway pricing
- AI Elements component library
- LangGraph JavaScript overview
- OpenAI Node SDK
- OpenAI Agents SDK for TypeScript
Revisión independiente del 20 de agosto de 2026. Versiones, providers, defaults y precios cambian rápido; verifique paquetes instalados y páginas oficiales actuales.