Un cliente de fintech me llamó a finales de 2023, con pánico genuino en la voz, porque su equipo de desarrollo había pasado seis semanas construyendo una interfaz de chat en streaming sobre la API de OpenAI y seguía roto en Safari móvil. Race conditions. Problemas de chunking de tokens. La UI se congelaba a mitad de la respuesta. Seis semanas. Miré su base de código y era exactamente lo que esperarías: una implementación ReadableStream hecha a mano, una capa de gestión de estado personalizada para los tokens en streaming, lógica de reintentos copiada de una respuesta de Stack Overflow de hace tres años. Todo estaba sostenido con cinta.
Reescribí el núcleo de ello usando Vercel AI SDK en aproximadamente dos días. El streaming funcionó. Safari móvil funcionó. El cliente dejó de llamar.
Eso no es un pitch. Es solo lo que pasó. Y es por eso que quiero recorrer qué hace realmente este SDK, dónde genuinamente te ahorra tiempo, y dónde todavía te golpearás con paredes.
Qué es Realmente Vercel AI SDK
La gente escucha "Vercel AI SDK" y asume que está bloqueado en la infraestructura de Vercel. No lo está. Puedes ejecutarlo en cualquier servidor Node.js, incluyendo tu propio VPS, Railway, Render, donde sea. Lo que realmente es: una librería TypeScript que abstrae las partes más desordenadas de construir características impulsadas por LLM en una aplicación web.
Hay dos paquetes principales que usarás. ai es el runtime central. @ai-sdk/openai (o @ai-sdk/anthropic, @ai-sdk/google, etc.) son los adaptadores de proveedores. El SDK utiliza una interfaz unificada, así que cambiar de GPT-4o a Claude 3.5 Sonnet es genuinamente un cambio de una línea en la mayoría de los casos. Lo he probado. Funciona.
Los Primitivos Centrales
Tres cosas están en el corazón del SDK:
- streamText, transmite una respuesta de texto token por token, ideal para interfaces de chat
- generateText, espera la respuesta completa, bueno para trabajos en segundo plano o cuando no necesitas UX de streaming
- generateObject, devuelve JSON estructurado validado contra un esquema de Zod, que es donde las cosas se ponen realmente interesantes
streamText es lo que la mayoría de las personas quiere primero. Maneja las tuberías de ReadableStream, la codificación y el chunking. ¿Ese pesadilla de fintech de seis semanas que mencioné? Eso es exactamente lo que streamText habría resuelto el primer día.
Configurándolo Sin Perder la Razón
Asumiendo que estás en Next.js 14 o 15 con el App Router (que probablemente estés si estás leyendo esto en 2025), la configuración es genuinamente rápida.
- Instala los paquetes: npm install ai @ai-sdk/openai
- Crea un manejador de ruta en app/api/chat/route.ts
- Importa streamText y tu proveedor, pasa tu modelo y mensajes, devuelve el resultado como StreamingTextResponse
- En el cliente, usa el hook useChat del paquete ai/react
Eso es todo. Tendrás un chat con streaming funcional en menos de una hora si conoces Next.js razonablemente bien. El hook useChat gestiona el array de mensajes, el estado de carga, el binding del campo de entrada, y las actualizaciones de streaming. No escribes nada de eso tú mismo.
Lo que agregaría inmediatamente a cualquier configuración de producción: un prompt del sistema adecuado, limitación de velocidad (uso Upstash para esto, su limitador de velocidad respaldado por Redis funciona bien con Edge Functions), y algún tipo de registro de uso de tokens. El SDK expone datos de uso en el objeto de respuesta, así que puedes registrar tokens de prompt y tokens de finalización en tu base de datos sin ninguna llamada API adicional.
generateObject Es la Característica en la que Estás Durmiendo
Opinión honesta: streamText obtiene toda la atención pero generateObject es la que ha cambiado cómo arquitecto características de IA.
La idea es simple. Defines un esquema Zod, lo pasas a generateObject, y el SDK instruye al modelo para devolver JSON que se conforme a él. Obtienes un objeto tipado, no una cadena que tengas que analizar y rezar.
Seahawk tuvo un proyecto el año pasado para una empresa de administración de propiedades. Querían extraer datos estructurados de documentos de arrendamiento cargados, nombres de inquilinos, montos de alquiler, cláusulas de ruptura, fechas de renovación. El enfoque antiguo habría sido: solicitar al modelo, obtener texto, escribir un parser de regex, llorar. Con generateObject, definimos un LeaseSchema con Zod, y el modelo devolvió datos limpios tipados en cada ejecución. Estábamos colocando arrendamientos extraídos en una tabla Postgres en una semana.
Lo que confunde a la gente: no todos los modelos soportan salida estructurada igualmente bien. GPT-4o y Claude 3.5 Sonnet la manejan de forma confiable. Algunos modelos más pequeños o antiguos alucinarán campos o ignorarán el esquema completamente. Cíñete a los modelos estrella para este, al menos hasta que hayas validado tu caso de uso.
Llamadas a herramientas: dónde reside el verdadero poder
Si generateObject está subutilizado, las llamadas a herramientas se entienden activamente mal. La mayoría de los desarrolladores piensan que "llamadas a herramientas" significa que la IA puede navegar por internet o ejecutar código. A veces lo hace. Pero en la práctica, las herramientas son solo funciones que defines y que el modelo puede elegir invocar durante una respuesta.
Cómo pensarlo
Digamos que estás construyendo un bot de soporte para un producto SaaS. El usuario pregunta "¿cuál es mi plan de suscripción actual?". El modelo no puede saberlo. Pero puedes definir una herramienta getUserSubscription que toma un ID de usuario y devuelve los datos del plan desde tu base de datos. El modelo reconoce la intención, llama a la herramienta, obtiene los datos de vuelta, e los incorpora en la respuesta. El usuario solo ve una respuesta coherente.
El parámetro tools del SDK en streamText y generateText toma un objeto donde cada clave es un nombre de herramienta, y cada valor tiene una description (que el modelo usa para decidir cuándo llamarla), un schema parameters (Zod de nuevo), y una función execute. La función execute se ejecuta del lado del servidor, de forma segura, lejos del cliente.
He construido agentes de múltiples pasos de esta manera. El SDK soporta maxSteps para que el modelo pueda encadenar llamadas a herramientas, llamar una herramienta, usar el resultado, llamar otra herramienta, sintetizar todo, responder. No es magia. Aún necesitas pensar cuidadosamente sobre tus descripciones de herramientas y tu system prompt. Pero el cableado se maneja todo por ti.
Middleware, envolvimiento y el modelo de canalización
Una cosa que no aprecié hasta que leí más a fondo la documentación: el SDK tiene un concepto de middleware que te permite envolver llamadas de modelo para agregar logging, caching, o comportamiento personalizado sin tocar tu código de funciones real.
wrapLanguageModel toma un modelo y un objeto middleware. Puedes interceptar solicitudes antes de que lleguen a la API, modificar parámetros, cachear respuestas. Usé esto en una herramienta de generación de contenido que construimos para una editorial; su caso de uso tenía muchos prompts repetidos (el mismo resumen de artículo siendo solicitado varias veces al día), y cacheamos respuestas en Redis usando la capa de middleware. El costo bajó aproximadamente 35% en el primer mes.
Este es el tipo de cosa que normalmente acoplarías de forma incómoda alrededor del exterior de tus llamadas a API. Tenerlo como un concepto de primera clase en el SDK significa que es composable y testeable.
Qué No Hace (Sé Honesto Contigo Mismo)
Bien. Déjame ahorrarte algo de dolor.
El SDK no maneja la memoria ni el historial de conversaciones a largo plazo por ti. useChat mantiene el array de mensajes en el estado del cliente, pero en el momento en que el usuario recarga, desaparece. Si necesitas conversaciones persistentes, tienes que construirlo tú mismo. Postgres o MongoDB para almacenar mensajes, fetch en mount para rehidratar el chat, nada de eso se proporciona. En realidad, este es el comportamiento correcto. El SDK no debería ser dueño de tu capa de datos. Pero los principiantes a menudo lo esperan.
Tampoco maneja inputs multimodales de forma nativa de una manera que abstraiga toda la complejidad. Puedes pasar URLs de imágenes en el array de mensajes y modelos como GPT-4o los manejarán bien, pero construir un flujo de carga de imágenes adecuado con vista previa, compresión y almacenamiento sigue siendo tu trabajo. Uso Uploadthing cuando estoy en Next.js, toma aproximadamente 30 minutos conectarlo.
RAG (generación aumentada con recuperación) tampoco está incluido. No hay búsqueda vectorial incorporada, no hay pipeline de embeddings, no hay lógica de chunking. Para eso recurres a algo como pgvector en Postgres o un servicio dedicado como Pinecone. El SDK maneja la llamada al LLM. El resto de la arquitectura de recuperación es tuya para construir.
Desplegándolo: Vercel vs Cualquier Otro Lugar
Sí, el SDK funciona mejor en Vercel. StreamingTextResponse funciona con Vercel Edge Runtime de forma inmediata, y los cold starts en Edge Functions son mucho más bajos que en funciones serverless de Node.js. Si tus respuestas de chat se sienten lentas, la latencia hasta el primer token importa mucho, y Edge la reduce.
Pero lo he desplegado en Railway (Node.js, no Edge) y funciona bien. Solo usas Response con headers de streaming apropiados en lugar de los helpers específicos de Vercel, y los documentos del SDK lo cubren. No dejes que "Vercel AI SDK" te haga pensar que estás atrapado.
Una cosa que genuinamente recomendaría: mantén tus manejadores de rutas de IA delgados. No hagas consultas a bases de datos, comprobaciones de autenticación y llamadas a LLM todo en una función. El middleware (middleware de Next.js, no el middleware del SDK) debe manejar la autenticación antes de que la solicitud llegue a tu ruta de IA. Mantiene las cosas rápidas, mantiene las cosas depurables.
FAQ
¿El SDK de Vercel AI es gratuito?
El SDK en sí es de código abierto y gratuito. Lo que pagas son las APIs de los modelos subyacentes: OpenAI, Anthropic, Google, el que sea que estés llamando. Esos costos corren por tu cuenta. El SDK no añade ningún margen.
¿Puedo usarlo con modelos que no sean OpenAI?
Sí, y esta es una de sus fortalezas genuinas. Hay adaptadores oficiales para Anthropic, Google (Gemini), Mistral, Groq, Cohere y más. La comunidad también ha creado adaptadores para Ollama si quieres ejecutar modelos locales. La interfaz unificada significa que tu código de funcionalidades no cambia cuando cambias de proveedor.
¿Funciona con React Server Components?
Parcialmente. generateText y generateObject pueden ejecutarse en Server Components sin problemas, son simplemente funciones asincrónicas. streamText con el hook useChat requiere estado del lado del cliente, así que esa parte vive en un Client Component. Esta es la arquitectura estándar de Next.js y no debería causarte problemas si entiendes el límite.
¿Cómo manejo los errores cuando la API se cae?
El SDK lanza errores tipados que puedes capturar y manejar. En la práctica, envuelvo mis llamadas a LLM en un try/catch y devuelvo un mensaje de fallback elegante en lugar de dejar que el error del stream burbujee hacia la UI como una respuesta parcial rota. La documentación del SDK sobre manejo de errores cubre los tipos de error en detalle y vale la pena leer antes de ir a producción.
¿Cuál es la situación con el límite de tokens?
El SDK no gestiona los límites de la ventana de contexto por ti. Si estás construyendo una conversación de larga duración y no recortas el historial de mensajes, alcanzarás la ventana de contexto del modelo y obtendrás un error. Una solución simple: mantén los últimos N mensajes (normalmente hago 20) más un prompt del sistema fijado. Lo suficientemente bueno para la mayoría de aplicaciones de chat.
---
Mira, el Vercel AI SDK no es un milagro. Es una abstracción bien diseñada sobre algunos trabajos de fontanería genuinamente tediosos. Maneja el streaming correctamente, te da salidas estructuradas tipadas, hace que las llamadas de herramientas sean accesibles, y funciona entre proveedores. Para el 80% del trabajo de características de IA que asumo, es el punto de partida correcto.
El cliente de fintech, por cierto, se puso en vivo con el chat reconstruido dos semanas después de que lo reescribiera. Sin problemas en Safari móvil. Sin condiciones de carrera. Seis semanas se convirtieron en dos días. A veces la abstracción correcta vale mucho.
Lectura relacionada: Seguridad headless vs WordPress en 2026: por qué Next.js y Astro, headless, y Astro.