Vercel AI SDK: el toolkit LLM para TypeScript que no te ata a ningún proveedor

La mayoría de los equipos que arman su primera función de LLM en una app de TypeScript se pasan la primera semana reinventando una infraestructura que nadie debería tener que escribir: parsear Server-Sent Events a mano, montar el bucle de tool calls, exprimir el texto del modelo para sacarle JSON y luego escribir código que repare la respuesta cuando no viene como debe. El Vercel AI SDK, el paquete «ai» en npm, resume todo eso en una sola superficie tipada que sirve para Anthropic, OpenAI, Google y decenas de proveedores más. Es el camino de menor fricción para meter funciones de LLM en un stack Next.js, y es por donde arranco cuando quiero cubrir mucho terreno rápido. Lo que sigue es la versión honesta: dónde brilla, dónde se le ven las costuras a la abstracción y cómo combinarlo con el SDK nativo cuando esas costuras importan.

01 · Qué es en realidad

El AI SDK son dos cosas bajo un mismo nombre. El core («ai») es un toolkit del lado del servidor, independiente del framework, con un puñado de funciones («generateText», «streamText», «generateObject», «streamObject» y un runtime de tool calls) que reciben un handle de modelo y devuelven resultados tipados. La capa de UI («@ai-sdk/react» y compañía) trae hooks como «useChat» y «useCompletion» que enganchan un endpoint con streaming a tus componentes casi sin código de pegamento.

La pieza que lo independiza del proveedor es el paquete de proveedor. Instalas «@ai-sdk/anthropic», «@ai-sdk/openai» o «@ai-sdk/google», y cada uno exporta una factory que produce un «LanguageModel» que las funciones del core saben entender. Cambiar de proveedor es modificar una sola línea ahí donde haces la llamada. El resto de tu código no se toca.

import { generateText } from "ai"
import { anthropic } from "@ai-sdk/anthropic"

const { text } = await generateText({
  model: anthropic("claude-opus-4-8"),
  prompt: "Resume este changelog en tres bullets.",
})

02 · Por qué se gana un lugar en el stack

Apenas lo adoptas se te van dos dolores de cabeza, y son justo los dos que más tiempo te roban en un primer build.

El primero es el streaming. Hacerlo a mano implica parsear un byte stream de SSE en el servidor, re-trocearlo y renderizar los tokens según van llegando al cliente sin que se te pierda ni se te duplique ninguno. «streamText» devuelve un stream que puedes pasar directo a la respuesta de un Route Handler de Next.js, y «useChat» lo consume en el cliente con el estado de carga y de error ya resueltos.

// app/api/chat/route.ts
import { streamText, convertToModelMessages } from "ai"
import { anthropic } from "@ai-sdk/anthropic"

export async function POST(req: Request) {
  const { messages } = await req.json()
  const result = streamText({
    model: anthropic("claude-opus-4-8"),
    messages: convertToModelMessages(messages),
  })
  return result.toUIMessageStreamResponse()
}

El segundo es la salida estructurada. Lo difícil de sacarle datos a un modelo nunca fue conseguir JSON. Es conseguir JSON correcto, siempre, respetando las restricciones de cada campo. «generateObject» recibe un schema de Zod, valida la salida del modelo contra ese schema y te entrega un objeto tipado. Sin «JSON.parse», sin try/catch envolviendo un string, sin tener que blindarte por si "el modelo lo metió dentro de un fence de markdown".

• Describes la forma una sola vez, en Zod.
• El SDK la traduce al mecanismo de salida estructurada del proveedor.
• A cambio recibes un valor tipado en tiempo de compilación y validado en runtime.

03 · Arranque rápido: instalar y primeras llamadas

Para empezar, instala el core y un solo proveedor, nada más. Pon la key del proveedor como variable de entorno. El paquete la lee solo, así que no le pasas la key desde el código.

npm install ai @ai-sdk/anthropic zod
# .env.local
# ANTHROPIC_API_KEY=sk-ant-...

Este es el camino de la salida estructurada, que es el que más uso. Un clasificador que te devuelve un veredicto tipado en lugar de un párrafo que después tocaría parsear:

import { generateObject } from "ai"
import { anthropic } from "@ai-sdk/anthropic"
import { z } from "zod"

const { object } = await generateObject({
  model: anthropic("claude-opus-4-8"),
  schema: z.object({
    risk: z.enum(["low", "medium", "high"]),
    reason: z.string(),
  }),
  prompt: `Evalúa el riesgo de seguridad de este cambio de dependencia:\n${diff}`,
})

// object.risk es "low" | "medium" | "high", tipado y validado.
if (object.risk === "high") flagForReview(object.reason)

04 · Tool calls sin escribir el bucle

Cuando un modelo necesita hacer algo, como buscar un registro, llamar a una API o correr un cálculo, le das tools y dejas que las llame. Montar esto a mano es un bucle: llamas al modelo, miras si pidió usar una tool, ejecutas la tool, le devuelves el resultado y repites hasta que el modelo deja de pedir. El AI SDK corre ese bucle por ti. Defines las tools con un schema de Zod y una función «execute», pones «stopWhen» para acotar los pasos y llamas a «generateText».

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

const { text } = await generateText({
  model: anthropic("claude-opus-4-8"),
  stopWhen: stepCountIs(5),
  tools: {
    getInvoice: tool({
      description: "Busca una factura por id.",
      inputSchema: z.object({ id: z.string() }),
      execute: async ({ id }) => db.invoice(id),
    }),
  },
  prompt: "¿Cuál es el total de la factura INV-204?",
})

Un par de cosas que conviene tener claras:

1. La función «execute» es tu código, así que la frontera de seguridad corre por tu cuenta. Valida las entradas, acota las credenciales y trata cada tool como una superficie de ataque, porque el prompt injection va a tantear tus tools, no solo tu chat.
2. «stopWhen» no es opcional, aunque el tipo lo permita. Sin un tope de pasos, un modelo que se confunde puede quedarse en bucle y quemar tokens. Ponlo.
3. Las tools y la salida estructurada se llevan bien. Puedes correr un paso de tool calls y forzar la respuesta final a un schema en la misma llamada.

05 · Cuándo usarlo frente a las alternativas

La decisión casi nunca es "AI SDK o nada". Es "AI SDK o el SDK nativo del proveedor", y el eje es cobertura contra profundidad.

Usa el AI SDK cuando

• Estás en una app Next.js / React y quieres chat o completions con streaming enganchados a la UI con el mínimo de código de pegamento.
• Quieres portabilidad entre proveedores: hacer un A/B entre dos modelos, tener fallback de un proveedor a otro o dejar la puerta abierta para cambiar más adelante.
• Tus necesidades son el 90% de siempre: generar texto, extracción estructurada, clasificación, enrutamiento y tool calls.

Quédate (o cae) en el SDK nativo de Anthropic cuando

• Dependes de funciones propias del proveedor que la abstracción no expone con limpieza: prompt caching con breakpoints explícitos, thinking extendido/adaptativo, o control fino de los headers del request.
• Estás construyendo un producto de un solo proveedor y la capa de portabilidad es pura indirección que nunca le vas a sacar provecho.
• Necesitas un comportamiento que va por delante del ciclo de releases del SDK. Una capacidad nueva del proveedor suele aterrizar antes en el SDK nativo.

En un build muy centrado en Anthropic muchas veces uso los dos a la vez: el AI SDK para la parte ancha (la UI de chat, los endpoints comunes) y el «@anthropic-ai/sdk» oficial para las rutas donde los headers de caching o la config de thinking deciden el costo y la latencia. Conviven sin problema. No hay ninguna regla que diga que un codebase tiene que elegir uno solo.

06 · Los tradeoffs honestos

Toda abstracción sobre muchos proveedores paga la cobertura con algo de profundidad, y el AI SDK no es la excepción. Conocer las grietas de antemano te ahorra una tarde de frustración.

• Lo propio de cada proveedor se escapa. El prompt caching, el thinking extendido y ciertas semánticas de las tools viven detrás de «providerOptions», una válvula de escape tipada que solo deja pasar lo que le mandes, y algunas ni siquiera aparecen hasta que un release las pone al día. Cuando una función es clave para el costo o la calidad, comprueba que funcione de punta a punta a través del SDK antes de montarlo todo encima.
• Estás siguiendo un paquete que se mueve rápido. El paquete «ai» avanza a buen ritmo, y sus versiones mayores han rehecho las APIs de mensajes y de streaming más de una vez. Fija tu versión, lee las notas de migración antes de actualizar y no des por hecho que un snippet de un blog viejo todavía compila.
• La abstracción de proveedor puede ocultarte el costo. Como cambiar de modelo es una sola línea, es fácil apuntar producción a un modelo más caro sin enterarte. El SDK no te va a gestionar presupuestos ni fallbacks entre proveedores. Eso es tarea de un gateway, no de una librería cliente.
• El debug cruza una frontera. Cuando un request se porta raro, ahora tienes que razonar sobre tu código, la capa de traducción del AI SDK y la API del proveedor al mismo tiempo. Conecta el tracing pronto para poder ver el request real que el SDK terminó enviando.

El Vercel AI SDK es la forma más rápida que conozco de poner una función de LLM real en producción dentro de una app de TypeScript, y para los casos comunes es genuinamente la herramienta correcta, no un mal menor. Trátalo como el default por cobertura y pásate al SDK nativo en el puñado de rutas donde una función del proveedor decide el resultado. Construye primero el camino testeable de la salida estructurada, define tus topes de pasos y tu frontera de seguridad con intención, y te quedas con casi todo el valor y muy poco del dolor.