Vercel AI SDK: cómo montar agentes en Next.js con streaming, tools y MCP

Checklist

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.

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();
}

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...",
});

¿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.

Puntos a revisar

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.

Checklist

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.

Checklist

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.

Checklist

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.

Fuentes y referencias

• 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

También te puede interesar

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.