Vercel AI SDK no es solo una librería de chat. Bien usado, es la capa TypeScript que conecta UI, streaming, tools, MCP, salida estructurada, agentes y observabilidad sin casarte con un único proveedor de modelos.
Vercel AI SDK es un toolkit TypeScript para construir productos de IA con streaming, chat UI, tool calling, salida estructurada, agentes y proveedores intercambiables. Su valor real aparece cuando dejas de tratarlo como un wrapper de fetch y lo usas como contrato entre frontend, backend, tools y observabilidad.
TL;DR
La keyword principal es Vercel AI SDK agentes Next.js. La intención de búsqueda en español es práctica: montar un chat o agente en Next.js que pueda transmitir tokens, llamar herramientas, validar JSON, integrarse con MCP y medirse en producción.
Mi postura: AI SDK encaja muy bien si tu producto ya vive en TypeScript/Next.js y necesitas velocidad de iteración. No sustituye una arquitectura de permisos, persistencia ni evaluación; solo hace que la parte LLM tenga menos pegamento accidental.
Qué es Vercel AI SDK y qué no es
Vercel AI SDK es una capa común para hablar con modelos, producir streams, definir tools, validar entradas y salidas, renderizar mensajes en UI y conectar proveedores. Su promesa no es que el modelo razone mejor, sino que tu aplicación tenga una interfaz estable para cambiar de modelo, añadir herramientas y operar el flujo sin reescribir media app.
No es una base de datos, no es un sistema de permisos y no es una cola duradera. Si el agente necesita memoria, auditoría, trazabilidad de negocio o jobs largos, debes diseñar esas piezas aparte. El SDK puede orquestar llamadas y streams; la responsabilidad del producto sigue siendo tuya.
El error habitual es empezar por el chat visual. El orden profesional es distinto: caso de uso, contrato de mensajes, tools permitidas, política de aprobación, límites de coste, persistencia, métricas y solo después UI.
Arquitectura mínima para llevar Vercel AI SDK de demo a producto: UI de chat, route handler, agente, tools tipadas, MCP, datos y métricas.
Arquitectura mínima en Next.js
El patrón base en App Router es sencillo: el cliente usa useChat, el servidor expone un route.ts, el handler convierte mensajes de UI a mensajes de modelo, streamText genera la respuesta y el resultado vuelve como stream compatible con la UI. Esa cadena parece trivial, pero define el contrato de producción.
En el cliente, no trates messages como texto plano. AI SDK trabaja con partes: texto, tool calls, aprobaciones, errores y metadatos. Si renderizas solo message.content, perderás estados importantes. En aplicaciones reales, la UI debe saber si una herramienta está esperando aprobación, si falló o si produjo salida utilizable.
En el servidor, la frontera importante es el route handler. Ahí defines modelo, system prompt, tools, límites de pasos, timeouts, abort signals, logging y tags de coste. Si esa lógica queda repartida entre componentes, server actions y helpers ocultos, luego no podrás auditar por qué el agente hizo algo.
app/api/chat/route.ts
import { convertToModelMessages, streamText, stepCountIs, tool } from "ai";
import { z } from "zod";
const tools = {
buscarDocs: tool({
description: "Busca documentación interna del producto",
inputSchema: z.object({ query: z.string().min(3) }),
outputSchema: z.object({ resumen: z.string(), fuentes: z.array(z.string()) }),
execute: async ({ query }) => searchDocs(query),
}),
};
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: "openai/gpt-4.1",
system: "Responde como asistente técnico. Cita fuentes internas cuando uses tools.",
messages: await convertToModelMessages(messages),
tools,
stopWhen: stepCountIs(5),
});
return result.toUIMessageStreamResponse();
}
Salida estructurada con Zod
import { generateText, Output } from "ai";
import { z } from "zod";
const { output } = await generateText({
model: "openai/gpt-4.1",
output: Output.object({
schema: z.object({
riesgo: z.enum(["bajo", "medio", "alto"]),
motivo: z.string(),
acciones: z.array(z.string()),
}),
}),
prompt: "Evalua este cambio antes de permitir que el agente lo aplique...",
});
Streaming: dónde se gana y dónde se rompe
¿Te está sirviendo? Hay una dosis cada semana
Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
El streaming mejora percepción de velocidad, pero también cambia cómo piensas estados. Un endpoint clásico falla o responde. Un stream puede empezar bien, llamar una tool, pedir aprobación, emitir texto parcial, fallar en una tool y aun así dejar una conversación recuperable.
Lo que conviene comprobar
Para un chat de soporte interno, streaming de texto basta. Para un agente que ejecuta herramientas, necesitas mostrar estados de tool, no solo palabras. El usuario debe entender si el agente está buscando, esperando permiso, ejecutando una acción o resumiendo resultados.
Mi regla: cualquier tool que tarde más de dos segundos debe producir estado visible. Cualquier tool que cambie datos debe dejar rastro. Cualquier salida que se use en automatización debe validarse con schema antes de aceptarla.
Tools: contratos pequeños, permisos explícitos
Las tools son la frontera de seguridad del agente. En AI SDK se definen con inputSchema y, cuando tiene sentido, outputSchema. Eso obliga a describir qué puede pedir el modelo y qué devuelve tu sistema. Si una tool acepta string libre para ejecutar acciones, no tienes una tool: tienes un agujero con buena DX.
Empieza con tools de lectura: buscar documentación, consultar tickets, recuperar métricas. Después añade mutaciones pequeñas: crear borrador, abrir issue, proponer patch. Las acciones irreversibles necesitan aprobación humana o una política automática muy estrecha.
Las herramientas deben ser aburridas. Una tool buena hace una cosa, valida input, aplica permisos del usuario real, registra llamada, devuelve salida acotada y falla con errores interpretables. El modelo no debería decidir permisos por contexto conversacional.
MCP sin convertirlo en barra libre
AI SDK puede consumir tools de servidores MCP, lo cual es útil si ya tienes conectores estandarizados. Pero MCP no elimina el problema de confianza. Un servidor remoto puede exponer muchas capacidades y el agente puede combinarlas de formas que no habías previsto.
Para producción prefiero allowlists de tools, scopes por entorno y separación entre lectura y escritura. Un agente que resume documentación no necesita la misma superficie que un agente que abre pull requests o toca datos de cliente.
La buena arquitectura trata MCP como un catálogo de capacidades, no como permiso universal. Descubrir herramientas dinámicamente es cómodo; aprobar cuáles entran en producción sigue siendo una decisión de ingeniería.
Agentes: ToolLoopAgent no arregla un mal proceso
El salto de streamText a un agente aparece cuando quieres varios pasos: pensar, llamar tools, observar resultados, decidir si continuar y terminar. En AI SDK, el patrón de agente evita que escribas tú el bucle manual, pero no decide por ti cuándo parar ni qué acciones son seguras.
Define stopWhen con intención. Un límite de pasos demasiado alto puede consumir coste y tiempo sin mejorar respuesta. Un límite demasiado bajo corta workflows legítimos. Para empezar, usa pocos pasos, mide trayectorias reales y sube solo si hay evidencia.
No llames agente a cualquier chat con tools. Un agente de producto debe tener objetivo, herramientas, estado observable, política de error, evaluación y dueño. Si no puedes explicar esos puntos, lo que tienes es una demo con autonomía estética.
Structured output: cuándo validar JSON
Salida estructurada es la pieza que más rápido mejora calidad cuando el resultado alimenta otro sistema. Si el modelo decide prioridad, riesgo, campos de una tarea, clasificación o acciones siguientes, no aceptes markdown: pide objeto validado con schema.
Esto no garantiza verdad, pero sí garantiza forma. La verdad se verifica con datos, tests o revisión. La forma se valida con Zod y tipos. Mezclar ambas cosas es una fuente clásica de bugs: un JSON válido puede ser una decisión equivocada.
Úsalo para contratos internos: decision, confidence, citations, next\_actions, requires\_approval. Si el objeto no pasa schema, la app debe pedir aclaración o degradar, no inventar campos.
Observabilidad y coste
El valor de AI SDK en producción aumenta cuando lo conectas con métricas: modelo, tokens, latencia, tool calls, pasos, errores, finish reason, usuario, feature y coste estimado. Sin eso, solo sabrás que el chat 'a veces va lento' o que la factura subió.
Vercel AI Gateway puede ayudar con routing, visibilidad y control de proveedores si tu despliegue ya está en Vercel. LiteLLM o gateways propios encajan mejor cuando necesitas una capa multi-cloud o políticas internas más fuertes. La decisión no es religiosa: elige el punto donde puedes medir y gobernar mejor.
La métrica de negocio no es tokens por respuesta. Es tareas resueltas con intervención aceptable. Un agente barato que obliga a revisar todo puede salir caro. Un agente caro que elimina una hora semanal de trabajo repetitivo puede ser rentable.
Checklist de producción
- Define una keyword técnica interna para cada flujo: soporte, análisis, extracción, copilot interno o agente de operaciones.
- Separa rutas de chat humano, generación estructurada y ejecución de acciones.
- Usa schemas para tool input, tool output y objetos que consumirá otro sistema.
- Aplica permisos fuera del prompt: usuario, tenant, recurso y acción.
- Añade aprobación para tools de escritura, pagos, despliegues, borrados o datos sensibles.
- Registra modelo, coste, latencia, pasos, tools, errores y usuario.
- Persistencia: guarda mensajes y eventos importantes, no solo el texto visible.
- Evalúa conversaciones reales antes de subir límites de pasos o tools.
- Documenta fallback: modelo alternativo, modo lectura, respuesta parcial o escalado humano.
Cuándo elegir AI SDK frente a OpenAI Agents SDK, LangGraph o Cloudflare Agents SDK
Elige Vercel AI SDK si tu producto está en TypeScript/Next.js y quieres integrar UI, streaming, tools y proveedores con baja fricción. Es especialmente fuerte cuando el frontend y el backend del producto se mueven juntos.
Elige OpenAI Agents SDK si priorizas un stack centrado en OpenAI con tracing, guardrails y handoffs muy integrados. Elige LangGraph si necesitas orquestación explícita de grafos, checkpoints y workflows complejos en Python. Elige Cloudflare Agents SDK si el problema principal es runtime stateful con Durable Objects, WebSockets y scheduling cerca de la edge.
La comparación honesta: AI SDK es probablemente la vía más directa para productos web TypeScript. No es necesariamente la mejor para workflows duraderos, agentes con estado complejo o entornos donde el frontend no importa.
Plan de adopción en cinco días
- Día 1: monta un chat mínimo con
useChaty un route handler, sin tools. Mide latencia y errores. - Día 2: añade una sola tool de lectura con
inputSchema, permisos y logging. - Día 3: introduce salida estructurada para una decisión que hoy parseas desde texto.
- Día 4: añade una tool con
needsApprovaly diseña la UI de aprobación. - Día 5: conecta métricas de coste, pasos y errores; decide si necesitas MCP, gateway o agente multi-step.
Conclusión
Vercel AI SDK merece atención porque resuelve una parte concreta del problema: unir aplicaciones TypeScript con modelos, streams, tools y UI sin escribir pegamento distinto para cada proveedor. Eso es mucho, pero no es todo.
La guía corta es esta: usa AI SDK para acelerar la capa de interacción con modelos; diseña tú la seguridad, persistencia, observabilidad y evaluación. Si esas cuatro piezas no existen, el SDK solo hará que llegues más rápido a una demo difícil de operar.
Preguntas frecuentes
¿Qué es Vercel AI SDK?
Vercel AI SDK es un toolkit TypeScript para construir aplicaciones y agentes de IA con generación de texto, streaming, chat UI, tool calling, salida estructurada y múltiples proveedores de modelos.
¿Vercel AI SDK sirve solo para Next.js?
No. Tiene integración muy buena con Next.js, pero el core puede usarse en otros entornos TypeScript y frameworks compatibles.
¿Cuándo usar streamText?
Usa streamText para experiencias interactivas donde el usuario necesita ver progreso, chat o respuesta incremental, especialmente en UI web.
¿Cuándo usar salida estructurada?
Usa salida estructurada cuando otro sistema vaya a consumir el resultado: clasificaciones, decisiones, extracción de datos, acciones siguientes o contratos de automatización.
¿AI SDK reemplaza a MCP?
No. MCP expone herramientas y contexto; AI SDK puede consumir esas tools y conectarlas al flujo de la app, pero sigues necesitando permisos, allowlists y observabilidad.
¿Necesito AI Gateway?
No siempre. Es útil si quieres routing, observabilidad y control de proveedores en Vercel. Si ya tienes gateway propio, evalúa si añade valor o duplica capas.
Cómo llevar Vercel AI SDK a producción en Next.js
- Elegir el flujo. Decide si estás construyendo chat, extracción estructurada, agente multi-step o automatización con aprobación humana.
- Crear el route handler. Centraliza modelo, mensajes, tools, límites de pasos, timeouts y logging en un endpoint revisable.
-
Diseñar tools pequeñas. Define
inputSchema,outputSchema, permisos reales y errores interpretables para cada tool. - Añadir streaming UI. Renderiza partes de mensaje, estados de tool y aprobaciones; no trates la respuesta como texto plano.
- Validar contratos. Usa salida estructurada para decisiones que alimentan código, base de datos o workflows.
- Integrar MCP con allowlist. Conecta solo tools necesarias y separa lectura de escritura por entorno y permiso.
- Medir operación. Registra coste, latencia, pasos, tool calls, errores y resultado de negocio antes de ampliar autonomía.
Regla operativa
Activa la automatización donde el comentario pueda cambiar una decisión técnica, no donde solo vaya a producir ruido revisable.
- AI SDK documentation
- AI SDK Next.js App Router
- AI SDK tools and tool calling
- AI SDK structured data
- AI SDK agents
- AI SDK UI chatbot
- AI SDK MCP tools
- Vercel AI Gateway
- vercel/ai GitHub repository
OpenAI Agents SDK: MCP, guardrails y tracingMCP outputSchema y structuredContentLiteLLM Proxy: gateway IA, costes y modelosCloudflare Agents SDK: agentes statefulLangGraph: agentes Python con estado
Recibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Top comments (0)