Vercel AI SDK 6: Framework de Agentes TypeScript-First

Qué Trae AI SDK 6

Vercel AI SDK 6, lanzado en diciembre de 2025, es la sexta versión mayor del toolkit líder de TypeScript para construir aplicaciones AI. Con más de 20 millones de descargas mensuales en npm, el SDK provee una API unificada para conectarse a cualquier proveedor de AI -- OpenAI, Anthropic, Google, xAI, Ollama y más -- a través de una interfaz única y agnóstica al modelo. La versión 6 representa el cambio arquitectónico más grande desde el inicio del SDK, introduciendo primitivos de agente de primera clase, soporte estable de MCP y DevTools dedicadas para depurar flujos de trabajo AI.

La característica principal es la abstracción Agent. En v6, Agent es una interfaz en vez de una clase, y ToolLoopAgent provee la implementación de producción por defecto. Defines un agente una vez con su modelo, instrucciones y herramientas, y lo reutilizas en toda tu aplicación -- en rutas API, Server Actions, trabajos en segundo plano y UIs de streaming. El agente maneja el ciclo completo de ejecución de herramientas: llama al LLM, ejecuta las llamadas de herramientas solicitadas, agrega resultados a la conversación y repite hasta que se alcanza una condición de parada.

Otras adiciones importantes incluyen aprobación human-in-the-loop vía el flag needsApproval, salidas estructuradas estables con tool calling, integración nativa de cliente MCP para conectarse a cualquier servidor MCP, y AI SDK DevTools para inspeccionar uso de tokens, flujos de ejecución y requests crudos del proveedor. La versión 6 también reemplaza endpoints REST /api/chat con Server Actions nativos, eliminando boilerplate y habilitando type safety de punta a punta entre llamadas al modelo del lado del servidor y componentes React del lado del cliente.

Guía de Migración v5 a v6

Actualizar de AI SDK 5 a 6 está simplificado por el codemod oficial. Ejecuta npx @ai-sdk/codemod v6 para migrar automáticamente la mayoría de los cambios breaking. El codemod maneja actualizaciones de rutas de importación, parámetros renombrados y reemplazos de APIs deprecadas. AI SDK 7 luego salió estable el 25 de junio de 2026 (npm [email protected]), extendiendo el SDK a una plataforma de agentes completa con aprobaciones de herramientas, workflows durables, soporte de MCP Apps y modalidades realtime/audio/video; una vez en v6, ejecuta npx @ai-sdk/codemod v7 para subir -- ten en cuenta que v7 requiere Node.js 22+, es solo ESM y renombra onFinish a onEnd.

El cambio breaking más significativo es el reemplazo de Experimental_Agent con ToolLoopAgent. El parámetro system se renombra a instructions, y el stopWhen por defecto cambia de stepCountIs(1) a stepCountIs(20). Si tu código v5 dependía del comportamiento de agente de un solo paso, debes setear explícitamente stopWhen: stepCountIs(1) en v6.

// v5 (deprecated)
import { Experimental_Agent } from 'ai';

const agent = new Experimental_Agent({
  model: openai('gpt-5.5'),
  system: 'You are a helpful assistant.',
  tools: { myTool },
  stopWhen: stepCountIs(1)
});

// v6 (current)
import { ToolLoopAgent } from 'ai';

const agent = new ToolLoopAgent({
  model: openai('gpt-5.5'),
  instructions: 'You are a helpful assistant.',
  tools: { myTool },
  // Default: stopWhen: stepCountIs(20)
});

Otros puntos de migración: las rutas REST /api/chat deberían migrar a Server Actions para type safety. La función experimental_createMCPClient ahora es la estable createMCPClient. Las importaciones de proveedores no cambian. El hook useChat ahora se conecta a Server Actions por defecto, pero el soporte de endpoints REST se preserva para compatibilidad.

La Abstracción Agent y ToolLoopAgent

La innovación central de AI SDK 6 es tratar a los agentes como primitivos reutilizables y componibles. La interfaz Agent define el contrato: un modelo, instrucciones, herramientas y una condición de parada. ToolLoopAgent implementa esta interfaz con un loop de razonamiento y acción listo para producción.

A diferencia de llamadas generateText() de un solo disparo, un ToolLoopAgent puede invocar herramientas, recolectar resultados, razonar sobre ellos, invocar más herramientas y repetir hasta que se alcance la condición de parada. Esto habilita flujos de trabajo autónomos multi-paso: agentes de investigación que buscan, resumen y sintetizan; agentes de código que planifican, implementan y testean.

import { ToolLoopAgent, generateText, streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { tool } from 'ai';
import { z } from 'zod';

const researchAgent = new ToolLoopAgent({
  model: anthropic('claude-sonnet-5'),
  instructions: 'You are a research assistant. Search for information, analyze results, and provide comprehensive answers.',
  tools: {
    search: tool({
      description: 'Search the web for information',
      parameters: z.object({
        query: z.string().describe('Search query'),
      }),
      execute: async ({ query }) => {
        // Your search implementation
        return await searchWeb(query);
      },
    }),
    analyze: tool({
      description: 'Analyze a text document',
      parameters: z.object({
        text: z.string(),
        focus: z.string().describe('Analysis focus area'),
      }),
      execute: async ({ text, focus }) => {
        return await analyzeText(text, focus);
      },
    }),
  },
  // Runs up to 10 reasoning steps
  stopWhen: stepCountIs(10),
});

// Use the same agent for text generation
const result = await generateText({ agent: researchAgent, prompt: 'Compare React and Vue in 2026' });

// Or for streaming
const stream = await streamText({ agent: researchAgent, prompt: 'Analyze the latest AI trends' });

También puedes implementar la interfaz Agent directamente para abstracciones personalizadas. Esto es útil para agentes que colaboran con otros agentes, agentes que cambian de modelo a mitad de conversación según la complejidad de la tarea, o agentes con sistemas de memoria personalizados.

Aprobación Human-in-the-Loop de Herramientas

AI SDK 6 introduce needsApproval como propiedad de primera clase en las definiciones de herramientas. Esto habilita seguridad human-in-the-loop para operaciones sensibles sin construir infraestructura de aprobación personalizada. Cuando una herramienta requiere aprobación, el agente pausa la ejecución y presenta la llamada de herramienta al usuario para revisión.

Hay dos modos: aprobación estática (siempre requiere aprobación con needsApproval: true) y aprobación dinámica (condicionalmente requiere aprobación basada en los parámetros de entrada de la herramienta). La aprobación dinámica es poderosa para seguridad graduada: pagos pequeños se ejecutan automáticamente, pagos grandes requieren revisión humana.

import { streamText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

// Server Action
export async function chat(messages) {
  'use server';
  return streamText({
    model: openai('gpt-5.5'),
    messages,
    tools: {
      // Static: always requires approval
      deleteUser: tool({
        description: 'Delete a user account',
        parameters: z.object({ userId: z.string() }),
        needsApproval: true,
        execute: async ({ userId }) => {
          return await deleteUserAccount(userId);
        },
      }),
      // Dynamic: approval only for amounts over 1000
      processPayment: tool({
        description: 'Process a payment',
        parameters: z.object({
          amount: z.number(),
          recipient: z.string(),
        }),
        needsApproval: async ({ amount }) => amount > 1000,
        execute: async ({ amount, recipient }) => {
          return { status: 'processed', amount, recipient };
        },
      }),
    },
  });
}

En el frontend, el hook useChat expone el estado de aprobación solicitada. Verificas las aprobaciones de herramientas pendientes y renderizas botones de aprobar/rechazar. La función addToolApprovalResponse de useChat envía la decisión del usuario de vuelta al servidor.

Integración Nativa de Cliente MCP

AI SDK 6 viene con soporte estable de MCP a través de createMCPClient(). Esta función se conecta a cualquier servidor MCP y hace sus herramientas disponibles a través de la misma interfaz que las herramientas nativas del AI SDK. Puedes mezclar herramientas MCP con herramientas definidas en el SDK en un solo agente.

El cliente MCP soporta tanto transporte Stdio (para servidores locales) como Streamable HTTP (para servidores remotos). Una vez conectado, accedes a las herramientas del servidor vía client.tools() y las pasas directamente a tu agente o llamadas generateText()/streamText(). La integración es transparente -- el modelo AI no ve diferencia entre herramientas MCP y nativas.

import { createMCPClient, generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

// Connect to a local MCP server via Stdio
const githubClient = await createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github'],
    env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
  },
});

// Connect to a remote MCP server via Streamable HTTP
const dbClient = await createMCPClient({
  transport: {
    type: 'streamable-http',
    url: 'https://mcp.internal.company.com/db',
    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
  },
});

// Combine MCP tools with native tools
const result = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: {
    ...await githubClient.tools(),
    ...await dbClient.tools(),
    myCustomTool: tool({ /* ... */ }),
  },
  prompt: 'Check the latest PR on my repo and query the database for related issues',
});

// Clean up connections
await githubClient.close();
await dbClient.close();

DevTools para Depuración de Agentes

AI SDK DevTools provee visibilidad completa sobre llamadas LLM y ejecución de agentes. Lanza el visor con npx @ai-sdk/devtools y abre http://localhost:4983. Cada paso de cada llamada se registra: mensajes de entrada, texto de salida, configuración del modelo, uso de tokens, tiempos, llamadas de herramientas, resultados y requests/responses HTTP crudos del proveedor.

Para loops de agente multi-paso, DevTools muestra cada iteración como un paso separado dentro del run. Puedes ver exactamente qué herramientas llamó el agente en cada paso, qué resultados se retornaron y cómo el agente razonó sobre ellos antes de decidir la siguiente acción.

DevTools se integra con flujos de trabajo de desarrollo de Next.js. Next.js 16.2 incluye Agent DevTools para depurar integraciones AI directamente desde el servidor de desarrollo. La herramienta combinada provee observabilidad de punta a punta desde el componente React renderizando la respuesta streaming hasta el request HTTP crudo enviado al proveedor del modelo.

UI Streaming en Next.js con useChat y useCompletion

El hook useChat es la interfaz principal para construir UIs de chat con AI SDK 6. Gestiona el ciclo de vida completo de la conversación: anexar mensajes del usuario, streaming de respuestas del asistente token por token, mantener el historial de conversación y manejar errores. En v6, useChat se conecta directamente a Server Actions habilitando type safety de punta a punta.

El hook useCompletion maneja completaciones de texto de prompt único para autocompletado, resumen y sugerencias inline. Ambos hooks soportan todas las características del AI SDK incluyendo tool calls, salida estructurada y aprobación human-in-the-loop. El streaming es impulsado por la API ReadableStream de Node.js.

// app/actions.ts - Server Action
'use server';
import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

export async function chat(messages) {
  return streamText({
    model: anthropic('claude-sonnet-5'),
    messages,
  });
}

// app/page.tsx - Client Component
'use client';
import { useChat } from '@ai-sdk/react';
import { chat } from './actions';

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: chat, // Direct Server Action reference
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="Ask something..." />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}

Cambio de Proveedor: Claude, GPT, Gemini, Ollama

AI SDK 6 es agnóstico al modelo por diseño. Cada proveedor sigue la misma interfaz: importas el paquete del proveedor, pasas un string de modelo, y el objeto modelo retornado funciona con generateText(), streamText(), generateObject() y ToolLoopAgent sin ningún cambio de código. Cambiar de Claude a GPT a Gemini requiere cambiar exactamente dos líneas de código.

import { generateText } from 'ai';

// Anthropic Claude
import { anthropic } from '@ai-sdk/anthropic';
const result1 = await generateText({ model: anthropic('claude-sonnet-5'), prompt: 'Hello' });

// OpenAI GPT
import { openai } from '@ai-sdk/openai';
const result2 = await generateText({ model: openai('gpt-5.5'), prompt: 'Hello' });

// Google Gemini
import { google } from '@ai-sdk/google';
const result3 = await generateText({ model: google('gemini-3.1-pro-preview'), prompt: 'Hello' });

// Ollama (self-hosted)
import { ollama } from 'ollama-ai-provider';
const result4 = await generateText({ model: ollama('llama3.3'), prompt: 'Hello' });

// Any OpenAI-compatible endpoint
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
const custom = createOpenAICompatible({ baseURL: 'https://my-server.com/v1' });
const result5 = await generateText({ model: custom('my-model'), prompt: 'Hello' });

El Vercel AI Gateway agrega ruteo de modelos, controles de costos y cadenas de fallback sobre el sistema de proveedores del SDK. Rutea requests a diferentes modelos según complejidad de la tarea, establece límites de gasto por modelo y configura fallback automático a modelos más baratos cuando los proveedores principales experimentan downtime. El gateway es opcional.

Desde junio de 2026, el AI Gateway soporta más de 50 modelos incluyendo Claude Opus 4.8 (agregado el 28 de mayo de 2026), Claude Fable 5 (agregado el 9 de junio de 2026), GPT-5.5 (dos variantes: GPT-5.5 y GPT-5.5 Pro), DeepSeek V4 (Pro y Flash, con ventana de contexto de 1M tokens), GPT Image 2 y Kimi K2.6 de Moonshot AI para tareas de coding de larga duración. El proveedor Voyage AI (@ai-sdk/voyage) agrega capacidades de embeddings y reranking de Voyage AI directamente a través de la interfaz del SDK, habilitando búsqueda semántica y pipelines RAG sin llamadas HTTP separadas. El ecosistema creciente de proveedores significa que AI SDK 6 cubre cada familia de modelos importante para generación de texto, generación de imágenes, embeddings y reranking en una sola API unificada. En junio de 2026, Azure se agregó como proveedor adicional para DeepSeek V4 Pro y Flash en el Gateway, dando a esos modelos otra ruta automática de failover. Nota de seguridad (abril 2026): Vercel reveló acceso no autorizado a sus sistemas internos vía una herramienta AI de terceros comprometida (brecha OAuth de Context.ai). Las API keys deben rotarse si fueron usadas antes del 19 de abril de 2026.

Desplegando en la Infraestructura Agéntica de Vercel

Las cargas de trabajo de agentes tienen requerimientos fundamentalmente diferentes a las aplicaciones web tradicionales. Necesitan ejecución de larga duración para razonamiento multi-paso, primitivos de orquestación para flujos de pausa/reanudación, ruteo de modelos para optimización de costos, entornos sandboxeados para ejecución de código y resistencia a abuso para agentes públicos.

La plataforma incluye cuatro componentes clave: AI Gateway para ruteo de modelos, rate limiting y controles de costos. Fluid Compute optimizado para cargas de trabajo AI con escalado dinámico. Workflows y Queues para orquestación de pausa/reanudación sin perder estado. Sandbox para entornos de ejecución de código aislados.

Más del 30% de los despliegues semanales en Vercel ahora son iniciados por agentes de código, un aumento del 1,000% en seis meses. Esto ha impulsado optimizaciones de plataforma para patrones de agentes -- tiempos de ejecución de funciones más largos, infraestructura streaming-first y medición de tokens incorporada. Puedes desplegar agentes AI SDK 6 en otras plataformas (AWS Lambda, Cloudflare Workers, Node.js self-hosted), pero Vercel provee la integración más estrecha.

Comparación: AI SDK 6 vs LangChain JS vs Mastra

El panorama de frameworks AI de TypeScript en 2026 tiene tres contendientes principales. Vercel AI SDK 6 sobresale en UI streaming e integración con React/Next.js. LangChain JS ofrece el ecosistema más amplio para pipelines RAG complejos. Mastra, que usa primitivos de AI SDK internamente, provee la abstracción de agente más limpia con orquestación de workflows incorporada.

Mastra usa primitivos de AI SDK internamente para interacciones con LLM. Para chat streaming puro en Next.js, AI SDK 6 solo provee el camino más directo. Para sistemas multi-agente complejos con memoria y RAG, considera Mastra sobre AI SDK. Para equipos Python-first, LangChain JS es la opción pragmática pese al bundle más grande. Ver también las guías de Claude Agent SDK y AI Full-Stack.