Blog

Cómo Usar Vercel AI SDK: Guía Para Principiantes

Rebecca Kovács

Rebecca Kovács

10 June 2025

Cómo Usar Vercel AI SDK: Guía Para Principiantes

Bienvenido a la guía definitiva para principiantes del Vercel AI SDK. En un mundo donde la inteligencia artificial está transformando rápidamente el panorama digital, la capacidad de integrar la IA en aplicaciones web ha pasado de ser una especialización de nicho a una competencia central para los desarrolladores modernos. Esta guía está diseñada para llevarte de ser un principiante curioso a un desarrollador capaz de aplicaciones de IA.

Durante mucho tiempo, tender un puente entre un potente Modelo de Lenguaje Grande (LLM) y una interfaz web amigable para el usuario fue una tarea compleja. Los desarrolladores tenían que lidiar con APIs de proveedores dispares, gestionar estados intrincados e implementar manualmente características como la transmisión de respuestas. El Vercel AI SDK fue creado para resolver exactamente estos problemas. Es un kit de herramientas basado en TypeScript que proporciona una capa de abstracción unificada y elegante sobre las complejidades de construir experiencias impulsadas por IA.

Esto no es solo un inicio rápido. A lo largo de este tutorial, construiremos un chatbot de IA completo y con muchas funciones desde cero utilizando Next.js y el modelo Gemini de Google. Iremos mucho más allá de un simple ejemplo de "hola mundo". Aprenderás:

Al final de esta guía completa, no solo tendrás un chatbot avanzado y funcional, sino también el conocimiento conceptual profundo necesario para construir con confianza tus propias aplicaciones únicas y potentes impulsadas por IA con el Vercel AI SDK.

💡
¿Quieres una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje en conjunto con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Capítulo 1: Fundamentos y Configuración

Toda gran estructura necesita una base sólida. En este capítulo, configuraremos nuestro entorno de desarrollo, instalaremos las herramientas necesarias y pondremos nuestras claves API en orden. También nos tomaremos un momento para comprender el "por qué" detrás de cada elección que hagamos.

Prerrequisitos

Antes de escribir una sola línea de código, asegurémonos de que tu caja de herramientas esté lista.

  1. Navega a Google AI Studio.
  2. Inicia sesión con tu cuenta de Google.
  3. Haz clic en "Obtener clave API" y luego en "Crear clave API en un nuevo proyecto".
  4. Copia la clave generada y guárdala en un lugar seguro por ahora. Trata esta clave como una contraseña; nunca la expongas públicamente.

Paso 1: Inicializando el Proyecto Next.js

Usaremos Next.js, el principal framework de React para construir aplicaciones de grado de producción. Su paradigma App Router se integra perfectamente con la naturaleza centrada en el servidor de las aplicaciones de IA.

Abre tu terminal y ejecuta este comando para crear un nuevo proyecto:

npx create-next-app@latest vercel-ai-tutorial

El instalador te hará varias preguntas. Utiliza estas configuraciones para seguir sin problemas:

Una vez que la instalación esté completa, navega al directorio de tu proyecto recién creado:

cd vercel-ai-tutorial

Paso 2: Instalando el Vercel AI SDK

Ahora, agreguemos los paquetes del AI SDK a nuestro proyecto.

npm install ai @ai-sdk/react @ai-sdk/google zod

Analicemos qué hace cada uno de estos paquetes:

Paso 3: Asegurando tu Clave API

Nunca codifiques una clave API directamente en el código de tu aplicación. Es un riesgo de seguridad importante. El estándar profesional es usar variables de entorno. Next.js tiene soporte integrado para esto con archivos .env.local.

Crea el archivo en la raíz de tu proyecto:

touch .env.local

Ahora, abre este nuevo archivo y agrega tu clave de Google AI:

# .env.local
# Este archivo es para desarrollo local y NO debe ser enviado a git.
GOOGLE_GENERATIVE_AI_API_KEY=TU_CLAVE_API_GOOGLE_AI

Reemplaza TU_CLAVE_API_GOOGLE_AI con la clave que copiaste anteriormente. Next.js carga automáticamente este archivo y hace que la clave esté disponible en el servidor, que es exactamente donde la necesitamos.

Capítulo 2: Construyendo la Estructura Principal del Chatbot

Con nuestro proyecto configurado, es hora de construir los componentes centrales de nuestra aplicación: el endpoint de API del lado del servidor que habla con la IA y la UI del lado del cliente con la que los usuarios interactuarán.

La Arquitectura Cliente-Servidor de una Aplicación de IA

Nuestro chatbot tendrá dos partes principales:

  1. Una Ruta API del Lado del Servidor (/api/chat/route.ts): Este es un entorno seguro que se ejecuta en un servidor. Su trabajo principal es recibir el historial de chat del navegador del usuario, agregar nuestra clave API secreta, reenviar la solicitud al servicio de Google AI y luego transmitir la respuesta de vuelta al usuario. Mantener esta lógica en el servidor es crítico para la seguridad, ya que asegura que nuestra clave API nunca esté expuesta al público.
  2. Una UI del Lado del Cliente (page.tsx): Este es el componente de React que se ejecuta en el navegador del usuario. Es responsable de renderizar el historial de chat, capturar la entrada del usuario y enviar esa entrada a nuestra ruta API.

Esta separación es fundamental para construir aplicaciones web seguras y de alto rendimiento.

Paso 4: Creando el Manejador de la Ruta API

Creemos el endpoint del lado del servidor. En tu directorio src/app, crea una nueva carpeta api, y dentro de ella, otra carpeta chat. Finalmente, crea un archivo llamado route.ts dentro de la carpeta chat.

La ruta final debería ser src/app/api/chat/route.ts.

Rellena este archivo con el siguiente código:

// src/app/api/chat/route.ts

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

// Configuración específica de Vercel para permitir la transmisión de respuestas por hasta 30 segundos
export const maxDuration = 30;

// El manejador principal de la ruta API
export async function POST(req: Request) {
  try {
    // Extraer el array `messages` del cuerpo de la solicitud
    const { messages } = await req.json();

    // Llamar al proveedor de IA con el historial de la conversación
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // El array `messages` proporciona al modelo contexto para la conversación
      messages,
    });

    // Responder con una respuesta de transmisión (streaming)
    return result.toDataStreamResponse();
  } catch (error) {
    // Es una buena práctica manejar posibles errores
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'An unknown error occurred' }), { status: 500 });
  }
}

Analicemos este archivo crucial:

Paso 5: Diseñando la Interfaz de Usuario

Ahora la parte divertida: construir la UI. Gracias al paquete @ai-sdk/react, esto es sorprendentemente simple. Abre el archivo principal de la página en src/app/page.tsx y reemplaza todo su contenido con lo siguiente:

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // Una referencia al contenedor desplazable de mensajes
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Efecto para desplazarse al final del contenedor de mensajes cada vez que los mensajes cambian
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Contenedor de mensajes */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* Mostrar avatar del usuario */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* Burbuja de mensaje */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'Tú' : 'Asistente de IA'}</span>
              {m.content}
            </div>

            {/* Mostrar avatar de la IA */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">IA</div>
            )}
          </div>
        ))}
      </div>

      {/* Formulario de entrada */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Pregúntame algo..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Enviar
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

Este es una cantidad significativa de código, pero la mayor parte es para crear una UI pulida con Tailwind CSS. Centrémonos en la lógica:

Paso 6: Ejecuta tu Aplicación

Ahora has construido un chatbot de IA completo y bien estructurado. ¡Vamos a ponerlo en marcha!

npm run dev

Navega a http://localhost:3000 en tu navegador. Deberías ser recibido por una interfaz de chat pulida. Hazle una pregunta. Verás tu mensaje aparecer instantáneamente, y la respuesta de la IA se transmitirá token por token.

Capítulo 3: Capacidades Avanzadas - Dando Superpoderes a tu Chatbot

Nuestro chatbot es inteligente, pero su conocimiento está limitado a sus datos de entrenamiento. No puede acceder a información en vivo ni realizar acciones en el mundo real. En este capítulo, le daremos "Herramientas" para superar estas limitaciones.

¿Qué son las Herramientas?

Una Herramienta es una función que defines y que el LLM puede elegir ejecutar. Describes la herramienta al modelo, y cuando este cree que la herramienta es necesaria para responder a la consulta de un usuario, pausará su generación de texto y, en su lugar, generará un objeto especial de "llamada a herramienta". Tu código luego ejecuta la función con los argumentos proporcionados por el modelo, y el resultado se envía de vuelta al modelo. El modelo luego usa esta nueva información para generar su respuesta final y más precisa.

Potenciemos nuestro chatbot con dos herramientas:

  1. Una herramienta para obtener el clima actual de una ubicación.
  2. Una herramienta para convertir temperaturas de Fahrenheit a Celsius.

Esto permitirá a nuestro bot responder preguntas como "¿Cuál es el clima en Londres en Celsius?"—una tarea que requiere múltiples pasos y datos externos.

Paso 7: Actualizando la API para Soportar Herramientas

Necesitamos definir nuestras herramientas en la llamada streamText en el servidor. Abre src/app/api/chat/route.ts y modifícalo para incluir la nueva definición de tools.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // Define las herramientas que el modelo puede usar
    tools: {
      getWeather: tool({
        description: 'Obtiene el clima actual para una ubicación específica. Siempre devuelve la temperatura en Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('La ciudad y el estado, por ejemplo, San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // En una aplicación real, obtendrías datos de una API de clima real
          console.log(`Obteniendo clima para ${location}`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Soleado', 'Nublado', 'Lluvioso'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Convierte una temperatura de Fahrenheit a Celsius.',
        parameters: z.object({
          temperature: z.number().describe('La temperatura en Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Convirtiendo ${temperature}°F a Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Analicemos el objeto tools:

Paso 8: Habilitando Llamadas a Herramientas de Varios Pasos en la UI

Definir las herramientas en el servidor no es suficiente. Por defecto, cuando el modelo realiza una llamada a una herramienta, la conversación se detiene. Necesitamos decirle a nuestro hook useChat que envíe automáticamente el resultado de esa llamada a la herramienta de vuelta al modelo para que pueda continuar su razonamiento y formular una respuesta final.

Esto es increíblemente simple. En src/app/page.tsx, actualiza la inicialización del hook useChat:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Le dice al hook que envíe automáticamente los resultados de las herramientas de vuelta al modelo
    experimental_sendExtraToolMessages: true,
  });
  // ... resto del componente
}

Eso es todo. La propiedad experimental_sendExtraToolMessages: true activa el flujo de uso de herramientas de varios pasos.

Paso 9: Una Mejor UI para Invocaciones de Herramientas

Nuestra UI actual solo muestra m.content. Cuando se llama a una herramienta, la información interesante está en una propiedad diferente del objeto message. Creemos un componente dedicado para renderizar las llamadas a herramientas de manera agradable.

Primero, actualicemos el bucle principal de mensajes en src/app/page.tsx para renderizar estas invocaciones.

// src/app/page.tsx

// ... dentro de la sentencia return del componente Chat
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... avatares ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'Tú' : 'Asistente de IA'}</span>

        {/* Renderizar invocaciones de herramientas */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Llamada a Herramienta: `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... avatares ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">IA</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

También he agregado un simple indicador de escritura que aparece mientras el asistente está pensando. Necesitarás agregar un poco de CSS para ello. En tu archivo src/app/globals.css, agrega:

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

Ahora, ejecuta la aplicación de nuevo. Pregúntale: "¿Cuál es el clima en Nueva York en Celsius?" Verás una fascinante cadena de eventos desarrollarse en tu UI:

  1. El modelo primero llamará a la herramienta getWeather. Verás la llamada a la herramienta renderizada en la UI.
  2. El resultado (una temperatura aleatoria en Fahrenheit) se envía de vuelta al modelo.
  3. El modelo, sabiendo que necesita Celsius, llamará entonces a la herramienta convertFahrenheitToCelsius, usando la temperatura del resultado de la primera herramienta como su entrada.
  4. Finalmente, con la temperatura en Celsius en mano, generará una respuesta en lenguaje natural respondiendo a tu pregunta original.

Este es el poder de construir Agentes de IA, y el Vercel AI SDK hace que esta compleja orquestación sea notablemente sencilla.

Capítulo 4: ¿Hacia Dónde Ir Desde Aquí?

Has construido con éxito un chatbot avanzado impulsado por IA. Has pasado de un lienzo en blanco a una aplicación con muchas funciones que puede transmitir respuestas, manejar estados de carga y error, y aprovechar herramientas para interactuar con datos externos de manera multi-paso.

Esta guía te ha proporcionado una base sólida, pero es solo el comienzo. El Vercel AI SDK tiene aún más que ofrecer. Aquí tienes algunos caminos para tu exploración continua:

El futuro del desarrollo web es inteligente, interactivo y personalizado. Con el Vercel AI SDK, ahora posees las herramientas y el conocimiento para estar a la vanguardia de esta revolución. ¡Feliz construcción!

💡
¿Quieres una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje en conjunto con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar