ai-sdk

Visión general de la skill ai-sdk

Qué te ayuda a hacer esta skill ai-sdk

La skill ai-sdk es una guía práctica para desarrolladores que trabajan con AI SDK de Vercel, especialmente cuando necesitas ayuda actualizada y sensible a la versión en lugar de consejos genéricos sobre LLM. Su función real es ayudarte a elegir la forma de API correcta, verificar sintaxis moderna y evitar patrones obsoletos al añadir chat, streaming, tools, generación estructurada, embeddings o agents a una app.

Quién debería instalar esta skill ai-sdk

Los perfiles para los que mejor encaja incluyen:

• Desarrolladores full-stack que estén evaluando ai-sdk for Full-Stack Development
• Equipos que migran código antiguo de AI SDK a APIs más nuevas
• Desarrolladores que usan generateText, streamText, tools, ToolLoopAgent o useChat
• Cualquiera que esté comparando la configuración de providers entre OpenAI, Anthropic, Google y acceso mediante gateway
• Builders que quieren menos intentos fallidos que con un simple prompt de "escríbeme código de IA"

Por qué esta skill es más útil que un prompt genérico

Su principal diferencia es que la skill advierte explícitamente que el conocimiento interno del modelo sobre AI SDK suele estar desactualizado. En vez de confiar en la memoria, te orienta a la documentación local del paquete, a inspeccionar el código fuente y a consultar referencias concretas como cambios habituales de API, uso de gateway, devtools y patrones de agents con type safety. Eso hace que esta ai-sdk skill sea más fiable para decidir si instalarla y para implementaciones reales que un prompting convencional.

Qué importa más antes de adoptarla

Lo que los usuarios suelen querer aclarar primero:

• si conviene instalar solo ai al principio
• cómo elegir más adelante paquetes de provider sin sobreinstalar
• qué APIs han cambiado recientemente
• si los ejemplos de useChat que circulan online siguen siendo válidos
• cómo depurar tool loops y ejecuciones en streaming
• si el SDK encaja con rutas de servidor, interfaces React o ambos

Si esos son tus bloqueos, esta página te ahorrará tiempo.

Cómo usar la skill ai-sdk

Empieza con la ruta mínima de instalación de ai-sdk

Usa primero el paso de instalación más pequeño posible:

pnpm add ai

La orientación del repositorio aquí es intencional: instala primero solo el paquete base ai. No añadas de inmediato @ai-sdk/openai, @ai-sdk/react u otros paquetes de provider/cliente hasta que tu caso de uso realmente lo requiera. Esto reduce suposiciones erróneas y mantiene tu implementación alineada con la documentación actual.

Si vas a instalar la propia skill de GitHub dentro del flujo de tu agent, usa:

npx skills add vercel/ai --skill ai-sdk

Verifica la documentación local antes de pedir código

El patrón de uso clave no es "preguntar desde la memoria". Es este:

1. Confirmar que existe node_modules/ai/docs/.
2. Buscar en node_modules/ai/docs/ y node_modules/ai/src/.
3. Solo después recurrir a ai-sdk.dev o a las referencias del repo.

Este es el comportamiento práctico más importante de la ai-sdk guide, porque las APIs de AI SDK evolucionan rápido y muchos ejemplos públicos se quedan atrás.

Lee primero estos archivos

Si quieres orientarte rápido, empieza en este orden:

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

Por qué este orden funciona:

• SKILL.md te da las condiciones de activación y el flujo de trabajo
• common-errors.md te ayuda a detectar pronto trampas por renombres de API
• ai-gateway.md te ayuda a conseguir rápido un modelo funcionando
• devtools.md mejora la depuración una vez que el código ya corre
• type-safe-agents.md importa cuando los tipos de UI y agent deben quedar alineados

Conoce la deriva actual de la API antes de escribir código

Un gran freno de adopción es copiar ejemplos antiguos. Las referencias señalan varios cambios que afectan materialmente al ai-sdk usage:

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• parameters en tools → inputSchema
• algunos patrones antiguos de generación de objetos han cambiado
• useChat ha cambiado de forma significativa y debe verificarse antes de reutilizarlo

Si en tu primer prompt a la skill incluyes la versión actual de tu paquete y cualquier código heredado, obtendrás mucha mejor ayuda para migración.

Usa AI Gateway cuando necesites un primer resultado rápido

Para muchos equipos, la ruta más rápida es una configuración basada en gateway. La skill incluye una referencia útil para Vercel AI Gateway, donde se puede seleccionar un modelo con un string como:

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

Esto resulta útil cuando tu decisión depende menos del wiring del SDK del provider y más de validar rápido el comportamiento del producto.

Antes de fijar cualquier model ID en el código, consulta la lista actual de modelos. La referencia advierte explícitamente que no conviene confiar en la memoria para los nombres de modelos.

Qué información darle a la skill ai-sdk

Dale a la skill suficiente contexto para que pueda elegir la forma correcta del paquete y el patrón de API adecuado. Una buena petición suele incluir:

• runtime: Next.js, Node.js, Vercel, edge/serverless, etc.
• objetivo: chat UI, agent, RAG, extracción estructurada, tool calling
• versiones actuales de los paquetes
• si necesitas streaming
• preferencia de provider o uso de gateway
• requisitos de frontend como hooks de React o uso solo en servidor
• cualquier código que falle y el texto exacto del error

Entrada débil:

• "Help me use AI SDK"

Entrada sólida:

• "I have a Next.js app router project on AI SDK 6, need streaming chat with tool calling, want to start with gateway, and my old useChat code no longer works. Show the minimal server route and UI shape."

El segundo prompt permite a la skill acotar mejor la documentación correcta y los nombres modernos de la API.

Convierte un objetivo difuso en un mejor prompt para ai-sdk

Una buena fórmula:

• contexto de la app
• experiencia de usuario deseada
• estado actual de la implementación
• restricciones
• formato de salida esperado

Ejemplo:

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

Esto funciona mejor que pedir simplemente "un agent", porque le da a la skill la estructura suficiente para evitar scaffolding genérico.

Elige el flujo adecuado para trabajos habituales

Usa la skill de forma distinta según la tarea:

• Para una primera instalación: pide el conjunto mínimo de paquetes y una única request funcional
• Para migración: pega el código antiguo y pide renombres de API y cambios de comportamiento
• Para tool calling: pide la forma del schema de tools y las condiciones de parada
• Para chat en frontend: pide específicamente los patrones actuales de useChat
• Para depuración: pregunta cómo inspeccionar ejecuciones con DevTools y dónde se almacenan los traces

Es en este prompting orientado a tareas donde la ai-sdk skill aporta más valor que una lectura rápida del repo.

Usa DevTools cuando el código ya corre pero el comportamiento es incorrecto

Cuando el código compila pero el modelo se comporta de forma inesperada, la referencia de DevTools tiene mucho valor. Captura llamadas del SDK, steps e interacciones con tools en:

.devtools/generations.json

Esto resulta especialmente útil para:

• loops ocultos de tool calls
• salidas estructuradas mal formadas
• desajustes entre prompt y tools
• comportamientos de streaming confusos
• inspección de tokens y steps durante ejecuciones de agents

Para decidir si adoptarlo, esto importa porque reduce el coste de depuración después de la instalación inicial.

Usa patrones de agents con type safety cuando importe el renderizado de la UI

Si estás construyendo una UI respaldada por agents, la referencia de agents con type safety es una señal clara de que la skill sirve para algo más que ejemplos de juguete. Muestra un patrón en el que las definiciones de agents exportan tipos UIMessage inferidos, haciendo que el renderizado con useChat sea más fiable.

Esto es especialmente relevante para ai-sdk for Full-Stack Development, donde la configuración del agent en backend y el renderizado de mensajes en frontend deben mantenerse alineados.

Casos prácticos en los que no encaja

No elijas esta skill si lo que necesitas principalmente es:

• documentación de SDKs específicos de un provider no relacionada con el paquete ai
• consejos generales de prompt engineering sin trabajo de implementación
• guía de aplicaciones de IA orientada primero a Python
• teoría general de LLM independiente del framework

Esta skill encaja mejor cuando tu pregunta trata específicamente de implementar o depurar AI SDK en una stack JavaScript/TypeScript.

Preguntas frecuentes sobre la skill ai-sdk

¿Esta skill ai-sdk es buena para principiantes?

Sí, si ya te manejas con JavaScript o TypeScript básicos. La skill es amigable para principiantes en el sentido de que acota los primeros pasos, pero asume que puedes editar archivos del proyecto, instalar paquetes y seguir las convenciones del framework.

¿La skill ai-sdk sustituye la lectura de la documentación?

No. Se aprovecha mejor como una capa de orientación que te dice dónde mirar y en qué patrones modernos confiar. Su valor principal es reducir desvíos equivocados, no sustituir la documentación fuente.

¿Cuál es la advertencia más importante antes de una instalación de ai-sdk?

No confíes en ejemplos antiguos ni en la memoria del modelo sobre la sintaxis de AI SDK. El repositorio insiste repetidamente en comprobar primero la documentación instalada y el código fuente. No es una advertencia menor; es algo central para una ai-sdk install e implementación correctas.

¿Debería instalar todos los paquetes de providers desde el principio?

Normalmente no. Empieza con ai y añade paquetes de provider o cliente solo cuando tu caso de uso lo requiera. Así mantienes la elección de dependencias como una decisión deliberada y evitas arrastrar suposiciones obsoletas a tu configuración.

¿Esto es sobre todo para aplicaciones de chat?

No. El chat es un caso de uso frecuente, pero la skill también encaja con generación estructurada, tool calling, agents, embeddings, acceso a modelos mediante gateway y respuestas de servidor en streaming.

¿En qué se diferencia de pedirle a un LLM que escriba código con AI SDK?

Un prompt genérico puede generar APIs obsoletas con total seguridad. Esta skill es mejor porque empuja un flujo de verificación: documentación local, referencias actuales, trampas de migración conocidas y lectura dirigida de archivos. Eso mejora la confianza y reduce retrabajo.

¿Ayuda con React y useChat?

Sí, pero con una cautela: useChat ha cambiado bastante. Trata los snippets antiguos con desconfianza y usa la skill para verificar la forma actual antes de copiar ejemplos de UI.

¿Cuándo no debería usar esta guía ai-sdk?

Sáltatela si tu problema es sobre todo facturación del vendor, estrategia de evaluación de modelos o integración con plataformas no JS. Úsala cuando tu bloqueo esté en un detalle actual de implementación de AI SDK.

Cómo mejorar el uso de la skill ai-sdk

Da contexto con versiones, no solo objetivos

La forma más rápida de mejorar los resultados es incluir versiones exactas, especialmente de ai y de cualquier paquete relacionado. Muchos fallos vienen de pedir "código de AI SDK" sin indicar si estás en una versión reciente o migrando código antiguo.

Pide primero slices mínimos que funcionen

Mejor que "constrúyeme toda mi app de agents":

• "show the smallest generateText example"
• "add one tool"
• "then stream it"
• "then wire useChat"

Este flujo incremental hace que la ai-sdk guide sea mucho más efectiva, porque cada paso puede contrastarse con la documentación actual antes de que la complejidad se acumule.

Muestra los errores tal cual

Si algo falla, incluye el error exacto y el snippet relevante. La referencia common-errors.md existe porque muchos problemas vienen de nombres de API casi correctos. Un único error preciso suele indicar a la skill si estás usando documentación antigua, imports de paquetes incorrectos u opciones desactualizadas.

Indica si quieres gateway o configuración directa del provider

Gran parte de la ambigüedad desaparece si especificas una de estas opciones desde el principio:

• "Use Vercel AI Gateway first"
• "Use direct OpenAI provider package"
• "Keep provider choice abstract for now"

Eso cambia los comandos de instalación, la selección del modelo y la estructura de los ejemplos.

Sé explícito sobre runtime y límites del framework

Para obtener una ayuda más sólida sobre ai-sdk usage, indica:

• solo servidor o cliente + servidor
• Next.js App Router u otro framework
• runtime edge o Node
• nivel de exigencia de TypeScript
• si las tools llaman a APIs internas o a servicios externos

Estos detalles afectan a cómo se ve un código "correcto".

Modos de fallo habituales que conviene vigilar

Los principales enemigos de la calidad son:

• depender de ejemplos antiguos de useChat
• copiar nombres de opciones ya deprecated
• fijar model IDs antiguos en el código
• instalar demasiados paquetes demasiado pronto
• pedir código de agents sin definir tools ni condiciones de parada
• depurar con console.log en lugar de traces de ejecución

Si evitas esto, la ai-sdk skill se vuelve mucho más fiable.

Pide a la skill que compare dos rutas de implementación

Una táctica muy útil es pedir una decisión, no solo código. Por ejemplo:

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

Este tipo de prompt produce mejor orientación de adopción que "enséñame la documentación".

Itera después de la primera respuesta con evidencias

Tras la primera respuesta, mejora la calidad respondiendo con uno de estos elementos:

• árbol actual de archivos
• lista de paquetes instalados
• request exacta que falla
• extracto capturado de .devtools/generations.json
• un extracto local de node_modules/ai/docs/

Esa iteración basada en evidencias es la mejor manera de convertir la ai-sdk skill de una guía general en ayuda real de nivel implementación.