Guía completa de Vercel AI SDK — Una API unificada para OpenAI, Anthropic y Gemini (2026)

"Lancé sobre la API de OpenAI, pero quiero probar también Claude y Gemini" — y te pasas dos horas reescribiendo la misma lógica contra tres SDK diferentes, traduciendo a mano formatos de petición y respuesta. El Vercel AI SDK (desde 2026 simplemente "AI SDK") reduce todo eso a "un import, una función, todos los proveedores". Es una librería open source en TypeScript con más de 20 millones de descargas mensuales; el AI SDK 6 trae Agents, MCP, aprobación de herramientas y DevTools, y a fecha de mayo de 2026 es el estándar de facto para una interfaz LLM unificada.

Vamos al grano: si en 2026 estás llamando a LLMs desde una web app o un proyecto Node.js, el AI SDK es el default correcto, punto. Las únicas razones para escribir directamente contra el SDK de OpenAI o Anthropic son "código heredado" o "funciones de vanguardia específicas del proveedor (computer use de Anthropic, etc.)". Para todo lo demás, el AI SDK te da "cambio fácil de proveedor, un tercio de la implementación, seguridad de tipos e integración con React" con una ventaja abrumadora.

Mi opinión personal por delante: el verdadero valor del AI SDK es la libertad frente al vendor lock-in. ¿OpenAI sube precios? Tres líneas y cambias a Anthropic. ¿Gemini saca un modelo nuevo? Lo pruebas en un solo sitio. Todo en un único codebase. Como cubrimos en Qué es una API de IA, la realidad de 2026 es que "usar varios modelos para tareas diferentes" ya es el default — y el AI SDK lleva el coste de cambiar a casi cero. Este artículo cubre qué es el AI SDK, por qué usarlo, una guía rápida de 5 minutos, salida estructurada, tool calling y agentes, integración con React, cambio de proveedor y tres trampas de producción — todo basado en el AI SDK 6 a fecha de mayo de 2026.

1. Qué es el AI SDK — "OpenAI/Anthropic/Gemini con una sola API"

El AI SDK es una librería open source en TypeScript creada por Vercel. GitHub: vercel/ai, licencia Apache 2.0, más de 20 millones de descargas mensuales en mayo de 2026. La construye Vercel, pero no exige Vercel para correr — funciona en Cloudflare Workers, AWS Lambda, Deno, tu propio Node.js o el navegador.

La idea central es ser una "capa adaptadora para cambiar de proveedor LLM". Por ejemplo:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Tell me today\'s weather',
});

Cambiar esto a Anthropic implica solo tres líneas:

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';  // ← changed

const { text } = await generateText({
  model: anthropic('claude-opus-4-7'),  // ← changed
  prompt: 'Tell me today\'s weather',
});

El código que llama no cambia en absoluto. Eso es lo que significa "una API para todos los proveedores" en la práctica. Cada proveedor tiene su propio formato de mensajes, secuencias de parada, esquemas de herramientas, ubicación del system prompt y forma del JSON de respuesta — y el AI SDK absorbe todo eso por debajo.

2. Por qué usar el AI SDK — 3 razones prácticas

Tres razones concretas: "cambio fácil, un tercio de la implementación y seguridad de tipos".

Cuándo el AI SDK no encaja: 1) cuando necesitas usar una función puntera específica de un proveedor (computer use de Anthropic, etc.) recién salida, antes de que el AI SDK la envuelva; 2) cuando trabajas solo en Python (el AI SDK es solo TypeScript); 3) cuando ya tienes una base sobre el SDK de OpenAI que funciona y no hay motivo para reescribir. Fuera de eso, el default en 2026 es el AI SDK.

3. En marcha en 5 minutos — de generateText a streamText

Configuración mínima en tres pasos. Demo sobre Node.js / Next.js.

# Step 1: install
npm install ai @ai-sdk/openai
# env: OPENAI_API_KEY=sk-...

# Step 2: create a file (app/api/chat/route.ts or index.ts)

// Step 3: code
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text, usage } = await generateText({
  model: openai('gpt-5'),
  system: 'You are a careful, helpful assistant.',
  prompt: 'List three benefits of the AI SDK.',
});

console.log(text);
console.log(`tokens: ${usage.totalTokens}`);

Eso es sin streaming, texto completo devuelto. Lo ejecutas y la respuesta cae en text en segundos. usage te da el conteo de tokens automáticamente — la disciplina de coste de el artículo sobre ahorro de tokens encaja directo.

Pasar a streaming (UX tipo máquina de escribir) es simplemente renombrar la función a streamText:

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = streamText({
  model: openai('gpt-5'),
  prompt: 'List three benefits of the AI SDK.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);  // emit token by token
}

Con el SDK crudo de OpenAI estarías escribiendo a mano parseo SSE, concatenación de chunks y detección de fin de stream (30 a 50 líneas). Con el AI SDK es un único bucle for-await. El mismo código corre contra Anthropic y Gemini sin cambios.

4. Salida estructurada — JSON con tipos seguros vía generateObject

Pídele "JSON" a un LLM y de vez en cuando te lo devolverá envuelto en un bloque de código Markdown, con comentarios o con la estructura sutilmente alterada. generateObject ataca esto de raíz: defines la forma con un esquema Zod y el AI SDK se encarga del parseo, la validación y los reintentos automáticamente.

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-5'),
  schema: z.object({
    title: z.string(),
    tags: z.array(z.string()).max(5),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    summary: z.string().max(200),
  }),
  prompt: 'Analyze the article: "AI SDK 6 has..." [body]',
});

// object.title, object.tags etc are typed
console.log(object.tags);  // string[]

La verdadera victoria: "el tipo de object lo determina `z.infer<typeof schema>`". TypeScript lo infiere, así que escribir object. en tu IDE autocompleta title / tags / sentiment / summary. La validación en runtime corre dentro del SDK — las violaciones de esquema disparan reintentos automáticos. La clase de incidente "la IA devolvió un JSON malo, falló el parseo" prácticamente desaparece.

5. Tool calling y agentes — el corazón del AI SDK 6

La frontera del desarrollo con IA en 2026 son "los agentes que llaman herramientas", y el mayor salto del AI SDK 6 está justo aquí. Con tools y stopWhen consigues directamente bucles del tipo "llama herramienta → la IA decide → llama la siguiente".

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

const { text, steps } = await generateText({
  model: anthropic('claude-opus-4-7'),
  tools: {
    weather: tool({
      description: 'Get the weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => {
        // real API call
        return { temp: 22, condition: 'sunny' };
      },
    }),
    convertToFahrenheit: tool({
      description: 'Convert Celsius to Fahrenheit',
      inputSchema: z.object({ celsius: z.number() }),
      execute: async ({ celsius }) => celsius * 9/5 + 32,
    }),
  },
  stopWhen: stepCountIs(5),  // cap the loop at 5 steps
  prompt: 'What is the weather in Tokyo, in Fahrenheit?',
});

La IA ahora encadena por su cuenta "weather('Tokyo') → convertToFahrenheit(22)", los ejecuta e integra los resultados. steps expone el historial de ejecución paso a paso.

El AI SDK 6 también ofrece una clase ToolLoopAgent con un estilo orientado a objetos (equivalente a generateText + stopWhen). Añade aprobación de ejecución de herramientas (un humano confirma antes de que se ejecuten) e integración completa con MCP (Model Context Protocol). Conectar un servidor MCP (mira Qué es MCP) son tres líneas en mayo de 2026.

6. Integración con React — un chat UI en 10 líneas con useChat

La otra estrella del AI SDK son los Hooks de React. Con useChat, una UI tipo ChatGPT son 10 líneas de código.

'use client';
import { useChat } from '@ai-sdk/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();
  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>{m.role}: {m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

El lado servidor (Next.js API Route):

// app/api/chat/route.ts
import { streamText, convertToModelMessages } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: openai('gpt-5'),
    messages: convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse();
}

Solo con eso obtienes conexión SSE, gestión del estado de los mensajes, loading y manejo de errores — todo automático. El useChat del AI SDK 6 además gestiona de forma nativa la UI de aprobación de herramientas (el usuario hace clic para aprobar "¿debo ejecutar esta herramienta?"). También vienen hooks para Vue (useChat de @ai-sdk/vue), Svelte y Solid.

7. Cambiar de proveedor — Claude, GPT y Gemini en 3 líneas

Los principales proveedores soportados oficialmente por el AI SDK en mayo de 2026:

Cambiar implica un import y una línea de modelo. El AI SDK 5 añadió un proveedor global que permite especificar el modelo por su ID en string (por ejemplo, 'openai/gpt-5'). Combínalo con la comparativa de fechas de corte de conocimiento de los LLM y precios de Claude vs ChatGPT para elegir modelos por "coste, rendimiento y requisitos regionales" con criterio.

8. Tres trampas de producción

El AI SDK es cómodo, pero hay tres trampas con las que se topa todo equipo en producción. Conocerlas de antemano evita el 80% de los incidentes.

Una nota más: el AI SDK es "un adaptador de LLM", no "un revendedor de coste de LLM". La API key de cada proveedor es tu responsabilidad y la facturación va directa a ti. Como cubrimos en Qué es una API de IA, los costes los facturan directamente OpenAI/Anthropic/Google. El AI SDK en sí es gratis; solo pagas los LLM que uses.

Resumen

"¿Cómo debería llamar a los LLM desde una web app?" — a fecha de mayo de 2026, la decisión de diseño ha convergido en "el AI SDK, punto". Más de 20 millones de descargas mensuales, el AI SDK 6 trae Agents, MCP, aprobación de herramientas y DevTools, y puedes llamar a OpenAI/Anthropic/Google/Mistral/xAI o LLM locales desde el mismo codebase. Tres cosas a la vez: "libertad frente al vendor lock-in", "un tercio del coste de implementación" y "salida estructurada con tipos seguros".

Empezar es sencillo: 1) npm install ai @ai-sdk/openai, 2) configura la API key, 3) una línea de generateText({ model, prompt }). Cuando eso corre, vas añadiendo capas: streamText para streaming, generateObject para JSON, tools para agentes, useChat para UI. Antes de pasar a producción, interioriza las tres trampas (diferencias entre proveedores, facturación por aborto de stream, sobrecarga de inferencia de tipos).

Relacionados: Qué es una API de IA (básico), La IA recomienda Vercel, Qué es MCP, Ahorro de tokens.

FAQ

P. ¿Tengo que desplegar en Vercel para usarlo?
R. No. El AI SDK es una librería pura de TypeScript — funciona en Cloudflare Workers, AWS Lambda, Deno, tu propio servidor Node.js o el navegador. "Built by Vercel" no significa "solo Vercel".

P. ¿Cuesta algo?
R. El AI SDK en sí es totalmente gratis, con licencia tipo MIT. El coste es únicamente el uso de la API del proveedor de LLM al que llamas (OpenAI/Anthropic/etc.). El SDK no añade ningún margen.

P. ¿En qué se diferencia de LangChain o LlamaIndex?
R. Roles distintos. El AI SDK es un "adaptador fino para llamar a LLMs" optimizado para integrarse en web apps. LangChain es un framework completo para "RAG y workflows de agentes". Reparto práctico: "TypeScript + integrar en una UI web" → AI SDK; "Python + pipelines de agentes complejos" → LangChain.

P. ¿Es difícil migrar desde código existente con el SDK de OpenAI?
R. Para llamadas simples a openai.chat.completions.create, son unos 10 minutos de reescritura — sustitúyelo por generateText y pasa messages. Las funciones complejas (function calling, vision) requieren una pequeña conversión de formato, pero la documentación incluye guías de migración.

P. ¿Funciona con LLM locales (Ollama)?
R. Sí. El paquete @ai-sdk/openai-compatible te permite atacar cualquier endpoint compatible con la API de OpenAI — Ollama, LM Studio, vLLM o tu propio servidor. El flujo "desarrollo en LLM locales y despliegue en la nube" se reduce a cambiar una sola baseURL.