DEV Community: Antonio Manuel Pérez López

Construyendo Interfaces Conversacionales. Parte 3

Antonio Manuel Pérez López — Sat, 30 Aug 2025 17:38:55 +0000

El productor del stream: Creando el endpoint de la API

Podrás encontrar el código de este artículo en: https://github.com/aperezl/ai-fullstack-serie/tree/chatbot-part3

Toda interfaz de chat necesita un backend que genere las respuestas. Siguiendo nuestro análisis teórico, crearemos un Route Handler en Next.js que actúa como el "productor" del stream de datos que useChat consumirá.

Paso 1: Crear el archivo de la API

Dentro del directorio src/app/, crea una nueva estructura de carpetas api/chat/ y, dentro de ella, un archivo route.ts.

/
|- app/
|  |- api/
|  |  |- chat/
|  |  |  |- route.ts  <-- Nuestro nuevo endpoint
|  |- page.tsx
...

Paso 2: Implementar la lógica del route handler

Abre src/app/api/chat/route.ts y añade el siguiente código. Este código es el corazón de nuestro backend conversacional.

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

// Permite que las respuestas en streaming se ejecuten por hasta 30 segundos
export const maxDuration = 30;

// Definimos un schema de Zod para validar el cuerpo de la petición
const PostBodySchema = z.object({
  messages: z.array(z.any()), // Por ahora, aceptamos cualquier objeto de mensaje
});

export async function POST(req: Request) {
  try {
    // Extraer y validar el cuerpo de la petición
    const body = await req.json();
    const validation = PostBodySchema.safeParse(body);

    if (!validation.success) {
      return new Response(JSON.stringify(validation.error.flatten()), { status: 400 });
    }

    const { messages }: { messages: UIMessage[] } = validation.data;

    // Instanciar el modelo de IA
    const model = google('gemini-2.0-flash-001');

    // Preparar el prompt con un mensaje de sistema para guiar al LLM
    const systemPrompt = `Eres un asistente de código experto llamado "CodeGenius".
    Tu especialidad es analizar fragmentos de código y explicar su funcionamiento de forma clara, concisa y pedagógica.
    Cuando un usuario te envíe un snippet, tu tarea es:
    1. Identificar el lenguaje de programación.
    2. Explicar el propósito general del código.
    3. Describir la función de cada línea o bloque de código importante.
    4. Mantén tus explicaciones orientadas a un desarrollador que busca entender rápidamente el código.
    5. No generes código nuevo a menos que se te pida explícitamente. Céntrate en la explicación.`;

    // Llamar a streamText del Vercel AI SDK
    const result = await streamText({
      model: model,
      system: systemPrompt,
      messages: convertToModelMessages(messages),
    });

    // Devolver la respuesta como un stream que el hook `useChat` puede consumir
    return result.toUIMessageStreamResponse()

  } catch (error) {
    // Manejo de errores en el servidor
    console.error("Error en la API de chat:", error);
    const errorMessage = error instanceof Error ? error.message : "Un error inesperado ha ocurrido.";
    return new Response(errorMessage, { status: 500 });
  }
}

Análisis del código:

Validación de Entrada: Aunque useChat envía un cuerpo predecible, un endpoint de API público nunca debe confiar ciegamente en la entrada. Usamos Zod para una validación mínima, que podríamos hacer más estricta si fuera necesario.
convertToModelMessages: Esta función es un helper crucial. El formato de mensaje que useChat utiliza en el frontend (UIMessage) contiene metadatos adicionales para la UI. Esta función lo traduce al formato limpio que el modelo de IA (streamText) espera, asegurando una correcta comunicación.
system Prompt: Aquí es donde inyectamos la "personalidad" y las directrices a nuestro agente. Este es un ejemplo de prompt engineering fundamental para guiar el comportamiento del LLM.
result.toUIMessageStreamResponse(): Como discutimos en la teoría, esta es la función que serializa el stream de salida del AI SDK en una respuesta HTTP que el frontend puede interpretar correctamente.

Instalando y creando componentes de chatbot

Con el backend listo, ahora nos centramos en el frontend. Usaremos shadcn/ui para acelerar la creación de una interfaz pulida. Es un conjunto de componentes reutilizables que se instalan directamente en tu proyecto, dándote control total sobre su código.

Paso 1: Inicializar shadcn/ui

Si aún no lo has hecho en tu proyecto, ejecuta el siguiente comando en la raíz y sigue las instrucciones. Acepta los valores por defecto, que son una excelente base.

npx shadcn@latest init

Paso 2: Instalar los componentes de UI necesarios

Instalaremos los bloques de construcción para nuestra interfaz de chat:

npx shadcn@latest add card input button avatar scroll-area

Esto añadirá los componentes a tu directorio src/components/ui/, listos para ser utilizados.

$ npx shadcn@latest add card input button avatar scroll-area
√ You need to create a components.json file to add components. Proceed? ... yes
√ Which color would you like to use as the base color? » Neutral
✔ Writing components.json.
✔ Checking registry.
✔ Installing dependencies.
✔ Created 5 files:
  - src\components\ui\card.tsx
  - src\components\ui\input.tsx
  - src\components\ui\button.tsx
  - src\components\ui\avatar.tsx
  - src\components\ui\scroll-area.tsx

Paso 3: Crear el componente principal del chatbot

Con el backend listo para servir respuestas, nos enfocamos en el frontend. En lugar de construir un único componente monolítico, adoptaremos un enfoque más modular y escalable. Dividiremos la interfaz de chat en componentes más pequeños y especializados, cada uno con una única responsabilidad. Esta práctica no solo hace que el código sea más fácil de leer y mantener, sino que también fomenta la reutilización.

Crearemos un componente Chatbot.tsx que encapsulará toda la lógica y la vista de nuestra conversación. Para esto necesitamos instalar @ai-sdk/react, que nos ofrecerá una capa de abstracción con nuestro frontend.

pnpm add @ai-sdk/react

La nueva estructura de nuestros componentes de chat será la siguiente:

/
|- components/
|  |- ui/
|  |  |- Chatbot/
|  |  |  |- Chatbot.tsx         <-- Componente Orquestador Principal
|  |  |  |- ChatbotHeader.tsx   <-- Cabecera del Chat
|  |  |  |- ChatbotMessages.tsx <-- Contenedor de la lista de mensajes
|  |  |  |- ChatbotMessage.tsx  <-- Componente para un mensaje individual
|  |  |  |- ChatbotInput.tsx    <-- Formulario de entrada de texto
|  |  |  |- ChatbotLoading.tsx  <-- Indicador de "escribiendo..."
|- hooks/
|  |- useCustomChat.ts         <-- Hook personalizado para la lógica del chat

Comenzaremos por la lógica, encapsulándola en un hook personalizado, para luego construir los componentes de UI que la consumirán.

A. Encapsulando la lógica: El hook useCustomChat

Para mantener nuestros componentes de UI limpios y centrados exclusivamente en la presentación, extraemos toda la lógica de interacción con el Vercel AI SDK a un hook personalizado.

Crea el archivo src/hooks/useCustomChat.ts:

// src/hooks/useCustomChat.ts
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, UIMessage } from "ai";
import {
  useState,
  ChangeEvent,
  FormEvent,
  useCallback,
  useMemo,
} from "react";

interface UseCustomChatProps {
  api: string;
}

interface UseCustomChatResult {
  input: string;
  setInput: React.Dispatch<React.SetStateAction<string>>;
  messages: UIMessage[];
  sendMessage: (message: UIMessage) => void;
  status: string;
  handleInputChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
  handleSubmit: (e: FormEvent<HTMLFormElement>) => void;
}

export const useCustomChat = ({ api }: UseCustomChatProps): UseCustomChatResult => {
  const [input, setInput] = useState('');

  const chat = useChat({
    transport: useMemo(() => new DefaultChatTransport({ api }), [api]),
  });

  const handleInputChange = useCallback(
    (e: ChangeEvent<HTMLTextAreaElement>) => {
      setInput(e.target.value);
    },
    [setInput]
  );

  const handleSubmit = useCallback(
    (e: FormEvent<HTMLFormElement>) => {
      e.preventDefault();
      const trimmedInput = input.trim();
      if (trimmedInput) {
        chat.sendMessage({ text: trimmedInput });
        setInput("");
      }
    },
    [chat.sendMessage, input, setInput]
  );

  return {
    input,
    setInput,
    messages: chat.messages,
    sendMessage: chat.sendMessage,
    status: chat.status,
    handleInputChange,
    handleSubmit,
  };
};

Análisis del hook:

Abstracción: Este hook actúa como una fachada. Internamente utiliza useChat del Vercel AI SDK, pero expone una interfaz simplificada y adaptada a nuestras necesidades.
Gestión de estado centralizada: Maneja el estado del input y se encarga de la lógica de handleInputChange y handleSubmit.
Rendimiento: El uso de useCallback para las funciones handleInputChange y handleSubmit y useMemo para el transport previene que se recreen innecesariamente en cada renderizado, optimizando el rendimiento del componente que lo use.
Interfaz clara: Devuelve un objeto con todo lo que nuestros componentes de UI necesitarán: el estado actual (input, messages, status) y las funciones para interactuar con él (handleInputChange, handleSubmit).

B. Creando los componentes de la interfaz

Ahora, creamos los componentes visuales, que serán "tontos" en el sentido de que solo recibirán props y renderizarán la UI, sin contener lógica de negocio.

1. El mensaje individual (ChatbotMessage.tsx y ChatbotLoading.tsx)

Primero, el componente para mostrar un mensaje, distinguiendo entre el usuario y el asistente.

// src/components/ui/Chatbot/ChatbotMessage.tsx
import { cn } from "@/lib/utils"
import { UIMessage } from "@ai-sdk/react"
interface ChatMessageProps {
  message: UIMessage
}

export function ChatBotMessage({ message }: ChatMessageProps) {
  const isUser = message.role === "user"

  return (
    <div className={cn("flex gap-3", isUser ? "justify-end" : "justify-start")}>
      {!isUser && (
        <div className="w-8 h-8 bg-yellow-500 rounded-full flex items-center justify-center flex-shrink-0 mt-1">
          <span className="text-slate-900 font-bold text-xs">AI</span>
        </div>
      )}

      <div
        className={cn(
          "max-w-[80%] rounded-lg px-4 py-2 break-words",
          isUser ? "bg-yellow-500 text-slate-900" : "bg-slate-700 text-white",
        )}
      >
        <p className="whitespace-pre-wrap leading-relaxed">

          {message.parts.map((part, index) =>
            part.type === 'text' ? <span key={index}>{part.text}</span> : null,
          )}
        </p>
      </div>

      {isUser && (
        <div className="w-8 h-8 bg-slate-500 rounded-full flex items-center justify-center flex-shrink-0 mt-1">
          <span className="text-white font-bold text-xs">TÚ</span>
        </div>
      )}
    </div>
  )
}

Y un componente simple para mostrar una animación de carga mientras el asistente responde.

// src/components/ui/Chatbot/ChatbotLoading.tsx
export function ChatbotLoading() {
  return (
    <div className="flex gap-3 justify-start">
      <div className="w-8 h-8 bg-yellow-500 rounded-full flex items-center justify-center flex-shrink-0 mt-1">
        <span className="text-slate-900 font-bold text-xs">AI</span>
      </div>

      <div className="bg-slate-700 rounded-lg px-4 py-2">
        <div className="flex gap-1">
          <div className="w-2 h-2 bg-slate-400 rounded-full animate-bounce"></div>
          <div className="w-2 h-2 bg-slate-400 rounded-full animate-bounce" style={{ animationDelay: "0.1s" }}></div>
          <div className="w-2 h-2 bg-slate-400 rounded-full animate-bounce" style={{ animationDelay: "0.2s" }}></div>
        </div>
      </div>
    </div>
  )
}

2. El contenedor de mensajes (ChatbotMessages.tsx)

Este componente se encarga de renderizar la lista de mensajes, el estado de carga y un mensaje de bienvenida si la conversación aún no ha comenzado. También gestiona el autoscroll.

// src/components/ui/Chatbot/ChatbotMessages.tsx
"use client"

import { ChatBotMessage } from "./ChatbotMessage"
import { ChatbotLoading } from "./ChatbotLoading"
import { useEffect, useRef } from "react"
import { UIMessage } from "ai"

interface ChatMessagesProps {
  messages: UIMessage[]
  isLoading: boolean
}

export function ChatbotMessages({ messages, isLoading }: ChatMessagesProps) {
  const messagesEndRef = useRef<HTMLDivElement>(null)

  const scrollToBottom = () => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" })
  }

  useEffect(() => {
    scrollToBottom()
  }, [messages])

  return (
    <div className="flex-1 overflow-y-auto p-4">
      {messages.length === 0 && (
        <div className="flex items-center justify-center h-full">
          <div className="text-center">
            <div className="w-16 h-16 bg-yellow-500 rounded-full flex items-center justify-center mx-auto mb-4">
              <span className="text-slate-900 font-bold text-xl">AI</span>
            </div>
            <h2 className="text-white text-xl font-semibold mb-2">¡Hola! Soy tu asistente AI</h2>
            <p className="text-slate-300">Pregúntame lo que quieras y te ayudaré</p>
          </div>
        </div>
      )}

      {messages.map((message) => (
        <ChatBotMessage key={message.id} message={message} />
      ))}

      {isLoading && <ChatbotLoading />}
      <div ref={messagesEndRef} />
    </div>
  )
}

3. La cabecera y la entrada de texto (ChatbotHeader.tsx, ChatbotInput.tsx)

Creamos componentes dedicados para la cabecera y el área de entrada. ChatbotInput es especialmente interesante, ya que maneja su propia lógica de UI, como el auto-ajuste de la altura del textarea y el envío con la tecla "Enter".

// src/components/ui/Chatbot/ChatbotHeader.tsx
export function ChatbotHeader() {
  return (
    <div className="bg-slate-700 border-b border-slate-600 p-4">
      <div className="flex items-center gap-3">
        <div className="w-8 h-8 bg-yellow-500 rounded-full flex items-center justify-center">
          <span className="text-slate-900 font-bold text-sm">AI</span>
        </div>
        <div>
          <h1 className="text-white font-semibold">Asistente AI</h1>
          <p className="text-slate-300 text-sm">Siempre listo para ayudarte</p>
        </div>
      </div>
    </div>
  )
}

// src/components/ui/Chatbot/ChatbotInput.tsx
"use client"

import type React from "react"

import { type FormEvent, useRef, useEffect } from "react"
import { Button } from "@/components/ui/button"
import { Send } from "lucide-react"

interface ChatInputProps {
  input: string
  handleInputChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void
  handleSubmit: (e: FormEvent<HTMLFormElement>) => void
  isLoading: boolean
}

export function ChatbotInput({ input, handleInputChange, handleSubmit, isLoading }: ChatInputProps) {
  const textareaRef = useRef<HTMLTextAreaElement>(null)

  // Auto-resize textarea
  useEffect(() => {
    const textarea = textareaRef.current
    if (textarea) {
      textarea.style.height = "auto"
      textarea.style.height = `${Math.min(textarea.scrollHeight, 120)}px`
    }
  }, [input])

  useEffect(() => {
    if (!isLoading) {
      textareaRef.current?.focus()
    }
  }, [isLoading])

  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    if (input.trim() && !isLoading) {
      handleSubmit(e)
    }
  }

  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
    if (e.key === "Enter" && !e.shiftKey) {
      e.preventDefault()
      if (input.trim() && !isLoading) {
        e.currentTarget.form?.requestSubmit()
      }
    }
  }

  return (
    <div className="border-t border-slate-600 bg-slate-700 p-4">
      <form onSubmit={onSubmit} className="flex gap-2 items-center">
        <div className="flex-1">
          <textarea
            ref={textareaRef}
            value={input}
            onChange={handleInputChange}
            onKeyDown={handleKeyDown}
            placeholder="Escribe tu mensaje aquí..."
            className="w-full bg-slate-600 text-white placeholder-slate-400 border border-slate-500 rounded-lg px-4 py-3 resize-none focus:outline-none focus:ring-2 focus:ring-yellow-500 focus:border-transparent min-h-[48px] max-h-[120px] no-scrollbar"
            disabled={isLoading}
            rows={1}
          />
        </div>
        <Button
          type="submit"
          disabled={!input.trim() || isLoading}
          className="bg-yellow-500 hover:bg-yellow-600 text-slate-900 font-semibold px-4 py-3 disabled:opacity-50 disabled:cursor-not-allowed"
        >
          <Send className="w-4 h-4" />
        </Button>
      </form>
    </div>
  )
}

C. Ensamblando el componente principal: Chatbot.tsx

Finalmente, creamos el componente Chatbot.tsx, que actúa como el orquestador. Su trabajo es:

Llamar a nuestro hook useCustomChat para obtener el estado y los manejadores de eventos.
Pasar esos datos como props a los componentes hijos (ChatbotMessages y ChatbotInput).
Estructurar el layout general de la interfaz de chat.

Crea el archivo src/components/ui/Chatbot/Chatbot.tsx:

// src/components/ui/Chatbot/Chatbot.tsx
"use client"

import { ChatbotMessages } from "./ChatbotMessages"
import { ChatbotInput } from "./ChatbotInput"
import { ChatbotHeader } from "./ChatbotHeader"
import { useCustomChat } from "@/hooks/useCustomChat";

export function Chatbot() {
  const {
    input,
    messages,
    status,
    handleInputChange,
    handleSubmit
  } = useCustomChat({ api: `/api/chat` });

  return (
    <div className="flex flex-col h-full bg-slate-600">
      <ChatbotHeader />
      <div className="flex-1 flex flex-col min-h-0">
        <ChatbotMessages messages={messages} isLoading={status !== 'ready'} />
        <ChatbotInput
          input={input}
          handleInputChange={handleInputChange}
          handleSubmit={handleSubmit}
          isLoading={status !== 'ready'}
        />
      </div>
    </div>
  )
}

Análisis del componente principal:

Orquestación pura: Observa qué tan limpio y declarativo es este componente. No contiene lógica compleja. Su única misión es conectar la lógica del hook con los componentes de presentación.
Flujo de datos unidireccional: Los datos (messages, input, status) fluyen desde el hook hacia abajo, a los componentes hijos. Las acciones del usuario (handleSubmit, handleInputChange) se propagan hacia arriba, al hook, que actualiza el estado, provocando un nuevo renderizado. Este es un patrón central en React que facilita el razonamiento sobre la aplicación.
Claridad estructural: Al ver este archivo, entendemos de inmediato la estructura de la interfaz: una cabecera, un área de mensajes y un área de entrada. La complejidad de cada parte está encapsulada en su propio módulo.

* Mapeo de `status`: El estado `status` que nos da `useChat` (y que nuestro hook expone) se traduce a un booleano `isLoading`. Esto es una pequeña adaptación para que los componentes hijos solo necesiten saber si algo está cargando o no, simplificando sus props.

El ensamblaje final: Integrando el chat en la página

El último paso es colocar nuestro nuevo componente Chatbot en la página principal.

Modifica app/page.tsx para que se vea así:

// app/page.tsx
import { Chat } from "@/components/Chat";

export default function HomePage() {
  return (
    <div className="bg-gray-100 min-h-screen flex items-center justify-center">
      <Chat />
    </div>
  );
}

Conclusión de la práctica

Hemos construido una aplicación de chat completa, en tiempo real y robusta. Al separar el backend (el productor del stream) del frontend (el consumidor), hemos creado un sistema desacoplado y mantenible.

En la sección final, pondremos a prueba el ejemplo completo, analizaremos los resultados y solidificaremos nuestra comprensión del flujo de datos en una aplicación de chat con IA.

Con el endpoint de la API y el componente de la interfaz de usuario construidos, ahora tenemos un sistema completo y funcional. Esta sección se centra en ejecutar la aplicación, probar su funcionalidad y analizar en detalle el ciclo de vida de una interacción para consolidar los conceptos teóricos y prácticos que hemos abordado.

Ejecutar la aplicación

Abre tu terminal en la raíz del proyecto y ejecuta el comando de desarrollo:

pnpm dev

Navega en tu navegador a http://localhost:3000. Deberías ver la interfaz de nuestro "AI Code Assistant".

Prueba de escenario: Analizando un snippet de código

Vamos a realizar una prueba de extremo a extremo para observar el sistema en acción.

Interacción:

Copia el siguiente snippet de código TypeScript:

const memoize = <T extends (...args: any[]) => any>(fn: T): T => {
  const cache = new Map<string, ReturnType<T>>();
  return ((...args: Parameters<T>): ReturnType<T> => {
    const key = JSON.stringify(args);
    if (cache.has(key)) {
      return cache.get(key)!;
    }
    const result = fn(...args);
    cache.set(key, result);
    return result;
  }) as T;
};

Pega el código en el campo de entrada del chat.
Haz clic en el botón de enviar.

Observaciones en tiempo real:

Instantáneamente, el snippet que pegaste aparecerá en la ventana del chat, alineado a la derecha, con tu avatar. Esto es la UI optimista de useChat en acción. El hook no espera la confirmación del servidor para actualizar la conversación local.
El campo de entrada y el botón de enviar se deshabilitarán inmediatamente. El botón mostrará la animación de pulso que definimos. Esto corresponde al estado status: 'awaiting_response'.
Después de un breve momento (el Time To First Token de Gemini), el avatar de la IA aparecerá a la izquierda, seguido del texto de la respuesta. El texto no aparecerá de golpe. Verás cómo se escribe en la pantalla, token por token. Este es el streaming en acción. El estado ha transicionado a status: 'streaming'.
Mientras el texto se está streameando, la ventana de chat se desplazará automáticamente hacia abajo para mantener visible el final de la respuesta.
Una vez que Gemini haya completado su explicación, el stream se cerrará. El campo de entrada y el botón se volverán a habilitar. El estado ha vuelto a status: 'ready'.

Análisis del tráfico de red (para el experto curioso):

Si abres las Herramientas de Desarrollador de tu navegador y vas a la pestaña de Red (Network), verás la petición POST a /api/chat.

Pestaña "Headers": Verás que es una petición POST estándar. En la sección "Request Payload", verás el array de messages que useChat ha enviado, incluyendo tu snippet de código.
Pestaña "Response": Esta es la parte interesante. En lugar de ver un JSON completo, verás una respuesta que se va actualizando con el tiempo. Los navegadores modernos tienen herramientas para inspeccionar estos streams (a veces bajo pestañas como "EventStream" o "Streaming"). Aquí es donde puedes ver los fragmentos (chunks) del protocolo del Vercel AI SDK llegando uno por uno.

Esta inspección confirma nuestro modelo mental: useChat maneja la orquestación en el cliente, y nuestro backend se dedica exclusivamente a producir un stream de datos que el cliente consume y renderiza de forma incremental.

Desafío de experto: Manejo de estado y contexto

Ahora que el sistema funciona, considera estas preguntas, que son típicas de un desarrollador senior llevando esto a producción:

¿Qué sucede si el usuario envía un segundo snippet de código? Pruébalo. Verás que la conversación continúa. useChat automáticamente incluye el historial completo (tu primer snippet, la explicación de la IA, tu segundo snippet) en la siguiente petición. Gemini usará este contexto. Podrías preguntarle: "¿Puedes comparar la complejidad de este segundo snippet con el primero?". El LLM tendrá el contexto para responder.
¿Cuál es el límite de este contexto? Los modelos tienen un límite de tokens de contexto. Si la conversación se alarga demasiado, la petición a la API fallará o el modelo empezará a "olvidar" el principio de la conversación. En un capítulo posterior sobre optimización, abordaremos estrategias para manejar historiales largos, como el resumen de conversaciones o el uso de ventanas deslizantes (sliding window).
¿Cómo podríamos persistir la conversación? Actualmente, si refrescas la página, la conversación se pierde. La persistencia implicaría almacenar el array de messages (p. ej., en localStorage para una solución simple, o en una base de datos para una solución robusta) y pasarlo como initialMessages al hook useChat al cargar la página. Esto también lo exploraremos en futuros capítulos.

Conclusión del capítulo 2

En este capítulo, hemos dado un salto cualitativo desde una interacción de "pregunta-respuesta" a un diálogo dinámico y en tiempo real. Hemos construido una aplicación de chat que no solo funciona, sino que está basada en una arquitectura moderna y eficiente, ideal para las demandas de las aplicaciones de IA.

Hemos dominado los siguientes conceptos clave:

Arquitectura cliente-servidor para streaming: Entendemos el rol de cada parte: el frontend como consumidor y renderizador de un stream, y el backend como el productor agnóstico al proveedor.
Gestión de estado complejo con useChat: Hemos aprovechado una abstracción de alto nivel para manejar la UI optimista, los estados de carga/error y la actualización incremental de la interfaz, simplificando enormemente nuestro código de cliente.
Prompt engineering básico: Hemos visto cómo un "system prompt" bien definido puede guiar eficazmente el comportamiento de un LLM para una tarea específica, estableciendo una persona y unas reglas claras.

La interfaz conversacional es el lienzo sobre el cual pintaremos funcionalidades de IA cada vez más sofisticadas. Con esta base sólida, estamos preparados para el siguiente gran desafío: dotar a nuestro agente de conocimiento externo. En el Capítulo 3, nos sumergiremos en el mundo del Retrieval-Augmented Generation (RAG), enseñando a nuestro chatbot a responder preguntas basándose en una base de conocimiento privada.

Puedes encontrar el código de esta sección en: https://github.com/aperezl/ai-fullstack-serie/tree/chatbot-part3

Construyendo Interfaces Conversacionales. Parte 2

Antonio Manuel Pérez López — Sat, 30 Aug 2025 17:26:32 +0000

Refactorizando nuestro proyecto

Podrás encontrar el código de este artículo en: https://github.com/aperezl/ai-fullstack-serie/tree/chatbot-part1

En la primera parte, nos sumergimos en la mecánica del diálogo en tiempo real con LLMs, diseccionando el useChat y el protocolo de streaming que lo sustenta. Logramos una prueba de concepto funcional, pero incompleta. Nuestra aplicación, en su estado actual, es un único fichero page.tsx que no puede crecer.

Antes de añadir más complejidad a nuestra lógica de chat,tenemos que dar un paso atrás. El código que funciona no siempre es el código correcto. Este capítulo está dedicado a la refactorización: transformaremos nuestra aplicación de una sola página en una estructura modular y navegable. Este no es un simple ejercicio de limpieza; es la construcción de un andamiaje robusto que nos permitirá añadir nuevas secciones y funcionalidades complejas sin incurrir en deuda técnica.

Abordaremos los siguientes pasos, explicando el "porqué" de cada decisión:

Estructura de Componentes: Crearemos una organización de ficheros lógica para nuestros componentes de UI.
Layout Persistente: Implementaremos una barra de navegación lateral que se mantenga constante a través de las diferentes secciones de la aplicación.
Gestión de Rutas: Reorganizaremos nuestras páginas para reflejar una estructura de navegación coherente, sentando las bases para futuras expansiones.
Página de Inicio (Hub): Crearemos un punto de entrada claro que sirva como un índice para las distintas funcionalidades de la aplicación.

Este proceso es el equivalente a cimentar el terreno antes de construir un rascacielos. Es un trabajo fundamental que garantiza la estabilidad y mantenibilidad del proyecto a largo plazo.

Nuestros primeros componentes

Una aplicación que crece necesita una distinción clara entre las "páginas" (vistas de ruta) y los "componentes" (bloques de UI reutilizables). El primer paso lógico es crear un directorio /components en la raíz de /src.

Nuestro primer componente será la pieza central de nuestra nueva arquitectura de layout: la barra de navegación lateral o Sidebar. Para los iconos, nos apoyaremos en lucide-react, una excelente librería de iconos SVG, ligera y fácilmente "tree-shakable" (solo se incluye en el bundle final el código de los iconos que realmente usamos).

npm i lucide-react

Ahora, creemos el fichero /src/components/Sidebar.tsx:

// src/components/Sidebar.tsx
"use client"

import Link from "next/link"
import { usePathname } from "next/navigation"
import { Home, BookOpen, MessageCircle } from "lucide-react"

const navigation = [
  { name: "Home", href: "/", icon: Home },
  { name: "Fundamental", href: "/fundamental", icon: BookOpen },
  { name: "Chatbot", href: "/chatbot", icon: MessageCircle },
]

export function Sidebar() {
  const pathname = usePathname()

  return (
    <div className="w-64 bg-slate-700 text-white flex flex-col">
      <div className="p-6">
        <h1 className="text-xl font-bold text-yellow-500">ai-fullstack-serie</h1>
      </div>

      <nav className="flex-1 px-4 space-y-2">
        {navigation.map((item) => {
          const isActive = pathname === item.href
          return (
            <Link
              key={item.name}
              href={item.href}
              className={`flex items-center px-4 py-3 text-sm font-medium rounded-lg transition-colors ${isActive ? "bg-yellow-500 text-slate-900" : "text-slate-300 hover:bg-slate-600 hover:text-white"
                }`}
            >
              <item.icon className="mr-3 h-5 w-5" />
              {item.name}
            </Link>
          )
        })}
      </nav>
    </div>
  )
}

Análisis del componente:

"use client": Esta directiva es crucial. Marca este componente como un "Client Component". Es un requisito indispensable porque estamos utilizando el hook usePathname, que necesita acceder al estado del navegador (la URL actual) y no puede ejecutarse en el servidor.
usePathname(): Este hook de Next.js nos devuelve la ruta actual de la URL. Es la herramienta que nos permite saber qué enlace de la navegación debe aparecer como activo, una pieza fundamental para la UX.
Estructura de Datos nav: Definir los enlaces en un array de objetos es una práctica limpia. Permite iterar y renderizar los elementos de navegación de forma dinámica, facilitando la adición o eliminación de enlaces en el futuro.
Estilado Condicional: La lógica isActive ? '...' : '...' dentro del className es un patrón estándar en Tailwind CSS para aplicar estilos dinámicamente. En este caso, resalta el enlace activo, proporcionando feedback visual inmediato al usuario.

Integración en un Layout persistente

Con nuestro componente Sidebar listo, necesitamos un lugar donde pueda vivir de forma permanente, sin tener que ser re-renderizado en cada cambio de página. El fichero /src/app/layout.tsx es el lugar designado por Next.js para esta tarea. Actúa como la plantilla raíz que envuelve a toda la aplicación.

Modificamos el RootLayout para adoptar una estructura de dos columnas:

// src/app/layout.tsx
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import { Sidebar } from "@/components/Sidebar"

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        <div className="flex h-screen bg-gray-50">
          <Sidebar />
          <main className="flex-1 overflow-auto bg-slate-800">{children}</main>
        </div>
      </body>
    </html>
  );
}

Análisis del Layout:

Estructura flex: El div contenedor principal usa flex y h-screen para establecer un layout que ocupa toda la altura de la ventana.
Componente Sidebar Estático: Colocamos <Sidebar /> directamente dentro de este div. Al estar fuera del componente {children}, Next.js entiende que es parte del layout persistente. No se desmontará ni se volverá a montar durante las navegaciones entre páginas, conservando su estado.
Contenido Dinámico {children}: La prop children es donde Next.js renderizará el contenido de la página activa (por ejemplo, page.tsx). Al envolverlo en un tag <main> con flex-1, nos aseguramos de que ocupe todo el espacio restante.

Reorganización de rutas

Nuestra lógica del generador de títulos virales inicial vivía en la raíz (/app/page.tsx). Con la nueva estructura, esta página se convertirá en la sección "Fundamental". El App Router de Next.js funciona basado en directorios, por lo que la reorganización es intuitiva:

Movemos el contenido de /src/app/page.tsx a un nuevo fichero en /src/app/fundamental/page.tsx.

Este simple cambio de ubicación de ficheros actualiza la ruta de la aplicación. La lógica de chat ahora será accesible en http://localhost:3000/fundamental.

Creación de un nuevo punto de entrada

La ruta raíz (/) ahora está vacía. La convertiremos en un "hub" o página de inicio que dirija al usuario a las diferentes secciones de nuestra aplicación en crecimiento.

Creamos el nuevo fichero /src/app/page.tsx:

// src/app/page.tsx
import Link from "next/link"
import { BookOpen, MessageCircle, LucideIcon } from "lucide-react"

type Card = {
  title: string
  Icon: LucideIcon
  path: string
}

const items: Card[] = [
  {
    title: 'Fundamentos modernos y primera interacción con IA.',
    Icon: BookOpen,
    path: '/fundamental'
  },
  {
    title: 'Construyendo Interfaces Conversacionales (Chatbots)',
    Icon: MessageCircle,
    path: '/chatbot'
  }
]

const ItemComponent = ({ title, Icon, path }: Card) => (
  <Link href={path} className="block">
    <div className="flex items-center space-x-3 mb-4">
      <div className="p-2 bg-yellow-500/20 rounded-lg">
        <Icon className="h-6 w-6 text-yellow-400" />
      </div>
      <h3 className="text-xl font-semibold text-white">{title}</h3>
    </div>
  </Link>
)

export default function Home() {
  return (
    <div className="p-8 bg-slate-800 min-h-screen">
      <div className="flex flex-col mb-8 w-full items-center">
        <h1 className="text-3xl font-bold text-white mb-2">Serie: Aplicación FullStack</h1>
        <p className="text-slate-300">Explora las diferentes secciones de la aplicación</p>
      </div>
      <div className="flex flex-col p-6 w-full items-center">
        <div className="p-6">
          {items.map((item, index) => <ItemComponent key={index} {...item} />)}
        </div>
      </div>
    </div>
  )
}

Este componente es un Server Component por defecto, simple y eficiente. Su único propósito es presentar las secciones disponibles, actuando como un mapa del sitio funcional.

Conclusiones

No hemos escrito una sola línea nueva de lógica de IA en este capítulo, y sin embargo, el avance ha sido monumental. Hemos transformado un script aislado en el esqueleto de una aplicación real.

Mediante los componentes, la creación de un layout persistente y la organización de nuestras rutas, hemos establecido un patrón de desarrollo escalable. Ahora tenemos un sistema donde añadir una nueva sección (/chatbot, por ejemplo) es tan simple como crear una nueva carpeta y su correspondiente page.tsx, sabiendo que la navegación y la estructura general ya están resueltas.

Con esta fundación sólida en su sitio, estamos preparados para volver a la carga. En el próximo capítulo, construiremos la interfaz de usuario de nuestra sección /chatbot, aprovechando la robusta arquitectura que hemos establecido hoy.

Puedes encontrar el código de esta sección en: https://github.com/aperezl/ai-fullstack-serie/tree/chatbot-part1

Construyendo Interfaces Conversacionales. Parte 1

Antonio Manuel Pérez López — Sat, 30 Aug 2025 17:22:28 +0000

Introducción: El Diálogo como Interfaz Primaria

En el capítulo anterior, establecimos una comunicación unidireccional y transaccional con la IA: enviamos un prompt, recibimos una respuesta estructurada. Este es un patrón potente, pero fundamentalmente análogo a una llamada a una API REST tradicional. Sin embargo, el verdadero poder de los Modelos de Lenguaje Grandes (LLMs) se desata en el diálogo. La capacidad de mantener el contexto, refinar preguntas y construir sobre interacciones previas es lo que transforma una simple herramienta en un colaborador inteligente.

Este capítulo se adentra en la construcción de la piedra angular de las aplicaciones de IA modernas: la interfaz de chat. Para un desarrollador experimentado, el desafío no radica en renderizar una lista de mensajes, sino en gestionar el complejo ciclo de vida de una conversación en tiempo real. Abordaremos:

La Gestión de Estado Asíncrona: Una conversación con un LLM es inherentemente asíncrona y de larga duración. ¿Cómo mantenemos una UI receptiva y evitamos condiciones de carrera mientras esperamos y procesamos un stream de datos?
La Experiencia de Usuario (UX) del Streaming: La percepción de velocidad es a menudo más importante que la velocidad real. El streaming de tokens es la técnica fundamental para mitigar la latencia de los LLMs. Analizaremos cómo funciona a nivel de protocolo y cómo implementarlo eficazmente.
La Sincronización Cliente-Servidor: ¿Cómo se comunican el frontend y el backend para mantener un flujo de conversación coherente y eficiente?

Para resolver estos desafíos, nos apoyaremos en una de las herramientas más potentes del Vercel AI SDK: el hook useChat. Pero no nos limitaremos a usarlo; desentrañaremos su funcionamiento interno para que puedas entender, extender y, si es necesario, replicar su comportamiento.

useChat: Abstracción y Control del Ciclo de Vida Conversacional

A primera vista, useChat puede parecer un simple hook de React que gestiona un array de mensajes. En realidad, es un motor de estado sofisticado, diseñado específicamente para el ciclo de vida de una conversación con IA. Su propósito principal es abstraer la complejidad de la comunicación en streaming y la gestión de estado asociada.

La Máquina de Estado Interna

useChat gestiona una máquina de estado con transiciones bien definidas. Como desarrollador senior, es crucial entender estos estados para construir UIs robustas:

status: 'idle' (o 'ready'): El estado inicial. El sistema está a la espera de la entrada del usuario. El formulario de envío está habilitado.
status: 'awaiting_response' (o 'submitted'): El usuario ha enviado un mensaje. La petición fetch ha sido enviada al servidor, pero aún no hemos recibido el primer fragmento (chunk) de datos. La UI debería mostrar un indicador de carga y deshabilitar el formulario. useChat ya ha añadido el mensaje del usuario a la lista de mensajes (UI optimista).
status: 'streaming': El servidor ha respondido y estamos recibiendo activamente el stream de datos. A medida que llegan los fragmentos, el hook actualiza el contenido del último mensaje (el del asistente) en el array de mensajes, provocando re-renderizados incrementales.
status: 'error': La petición fetch falló o el stream se interrumpió con un error. El hook expone el objeto error, permitiéndonos mostrar un mensaje adecuado.
status: 'idle' (o 'ready'): El stream ha finalizado con éxito. El mensaje del asistente está completo. El sistema vuelve al estado de reposo, listo para la siguiente interacción.

Comprender este flujo es clave. Por ejemplo, saber que el mensaje del usuario se añade de forma optimista nos permite diseñar UIs que se sienten instantáneamente receptivas.

El Contrato del Hook

useChat expone una API concisa pero poderosa:

messages: El array de mensajes de la conversación. Esta es la fuente de verdad para tu UI. Cada objeto tiene un id, role ('user', 'assistant', 'system'), y content.
sendMessage(message, options): La función para enviar un nuevo mensaje. Esta es la acción que inicia la transición de 'idle' a 'awaiting_response'.
stop(): Función para abortar la petición fetch en curso, terminando el stream prematuramente.
resumeStream(): Función para reanudar una respuesta de transmisión interrumpida, útil para reintentos tras un error.

Lo que useChat hace por nosotros es orquestar la compleja interacción entre la acción del usuario (sendMessage), la comunicación de red (el fetch en segundo plano) y la actualización del estado de React (setMessages).

El Protocolo de Streaming: Una Conversación a Nivel de Red

Para entender useChat a fondo, debemos entender el "lenguaje" que habla con el backend. El Vercel AI SDK no solo streamea texto plano; utiliza un protocolo específico basado en ReadableStream para enviar fragmentos de datos estructurados.

Cuando nuestro Route Handler en Next.js devuelve result.toUIMessageStreamResponse(), está creando una respuesta HTTP con un cuerpo que es un stream. El hook useChat en el cliente sabe cómo leer e interpretar este stream. Cada fragmento (chunk) del stream no es solo texto, sino un pequeño objeto JSON codificado que sigue un formato específico.

Un fragmento típico puede contener:

Tipo de dato: Indica si el fragmento es texto, una llamada a una herramienta (lo veremos más adelante), datos personalizados, etc.
Contenido: El payload real del fragmento.

Ejemplo simplificado del flujo de datos en el stream:

`'0:"Hello"'` (El primer fragmento de texto)
`'0:","'` (Un segundo fragmento)
`'0:" world!"'` (Un tercer fragmento)
`'2:{"tool_calls": ...}'` (Un fragmento que indica una llamada a una herramienta)
`'1:{"finish_reason": "stop"}'` (Un fragmento de metadatos al final)

El hook useChat recibe estos fragmentos, los decodifica y actualiza el estado messages en consecuencia. Por ejemplo, concatena los fragmentos de texto al content del último mensaje del asistente. Este protocolo es lo que permite al AI SDK soportar funcionalidades avanzadas como Generative UI y tool_calls dentro del mismo stream.

Anatomía de la API de Chat: El Servidor como Orquestador del Stream

El backend es el responsable de "producir" el stream que useChat consume. Un Route Handler de Next.js para una API de chat tiene una estructura muy particular.

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

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

  const result = streamText({
    model: google('gemini-2.5-pro'),
    messages: convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse();
}

Análisis de la Arquitectura del Endpoint:

No es un Endpoint REST Tradicional: Este endpoint no devuelve un objeto JSON completo con res.json(). Su propósito es devolver un objeto Response cuyo cuerpo es un ReadableStream.
streamText como Productor: La función streamText del AI SDK es la que orquesta la llamada al proveedor de LLM (Google en este caso). Crucialmente, no espera a que Gemini termine. En cuanto Gemini empieza a devolver tokens, streamText los empaqueta en el formato de protocolo que vimos antes y los empieza a escribir en su propio stream.
toUIMessageStreamResponse() como Serializador: Esta función es la que toma el stream interno del AI SDK y lo convierte en una Response HTTP válida. Se encarga de establecer las cabeceras correctas (Content-Type, Transfer-Encoding: chunked, etc.) para que el navegador entienda que debe mantener la conexión abierta y leer el cuerpo de la respuesta de forma incremental.

Diagrama de Flujo Completo:

[Client Component (UI)]
      |
      +-- (1) El usuario envía mensaje. Se llama a sendMessage()
      |
[useChat Hook]
      |
      +-- (2) Añade mensaje de usuario a `messages` (UI optimista)
      |
      +-- (3) Realiza un `fetch` a `/api/chat` con el historial de mensajes
      |
      . . . . . . . . . . . . . . . . . . . . . . . . . . . (Red)
      |
[Next.js Route Handler (`/api/chat`)]
      |
      +-- (4) Recibe la petición y extrae `messages`
      |
      +-- (5) Llama a `streamText()` con los mensajes
      |
[Vercel AI SDK (Servidor)]
      |
      +-- (6) Llama a la API de Google Gemini (inicia el stream)
      |
      +-- (7) A medida que llegan tokens de Gemini, los empaqueta en el protocolo del SDK
      |
[Next.js Route Handler]
      |
      +-- (8) `toUIMessageStreamResponse()` devuelve el stream al cliente
      |
      . . . . . . . . . . . . . . . . . . . . . . . . . . . (Red)
      |
[useChat Hook]
      |
      +-- (9) Lee los fragmentos del stream de respuesta
      |
      +-- (10) Decodifica y actualiza el último mensaje del asistente en `messages`
      |
[Client Component (UI)]
      |
      +-- (11) Se re-renderiza con el contenido actualizado del mensaje

Este ciclo se repite para cada fragmento hasta que el stream finaliza.

Conclusión Teórica

Hemos diseccionado el mecanismo de una interfaz conversacional moderna. Lejos de ser una simple vista de "preguntas y respuestas", es un sistema en tiempo real que depende de una estrecha colaboración entre el cliente y el servidor, orquestada por un protocolo de streaming bien definido.

El hook useChat no es magia; es una abstracción de cliente bien diseñada que oculta la complejidad del manejo de streams y la gestión de estado, permitiéndonos centrarnos en construir la UI. Su contraparte en el servidor, streamText, actúa como el productor de ese stream, aislando nuestra lógica de las particularidades de la API de cada proveedor de LLM.

Con este modelo mental de la arquitectura cliente-servidor para conversaciones en streaming, estamos listos para pasar a la práctica y construir nuestra propia interfaz de chat, manejando todos los estados y ofreciendo una experiencia de usuario fluida y profesional.

Fundamentos modernos y primera interacción con IA. Parte 3

Antonio Manuel Pérez López — Thu, 28 Aug 2025 08:31:32 +0000

Uniendo las piezas: Creando la interfaz de usuario

En esta sección final, construiremos la interfaz de usuario (UI) que consumirá nuestra Server Action generateClickbaitTitles. Aplicaremos los patrones de composición de componentes de React que discutimos en la teoría, creando una experiencia de usuario fluida a pesar de la potencial latencia de la llamada a la IA. Nuestra UI será un Client Component, ya que necesita manejar el estado del formulario, la entrada del usuario y la respuesta de la acción.

Podrás encontrar el código de este artículo en: https://github.com/aperezl/ai-fullstack-serie/tree/fundamentals-ai-part3

Paso 1: Crear el componente de la página principal

Vamos a modificar el archivo src/app/page.tsx para que contenga nuestro formulario y el área de visualización de resultados.

Reemplaza el contenido de src/app/page.tsx con el siguiente código:

// src/app/page.tsx
'use client';

import { useState } from 'react';
import { generateClickbaitTitles } from '@/lib/ai/actions';
import type { z } from 'zod';
import type { AITitlesOutputSchema } from '@/lib/validations/schemas';

// Definimos un tipo local para el estado de los resultados
type TitlesData = z.infer<typeof AITitlesOutputSchema>;

export default function HomePage() {
  // Estado para manejar el estado de carga de la Server Action
  const [isLoading, setIsLoading] = useState<boolean>(false);
  // Estado para almacenar los títulos generados por la IA
  const [titlesData, setTitlesData] = useState<TitlesData | null>(null);
  // Estado para manejar cualquier error devuelto por la acción
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    setIsLoading(true);
    setError(null);
    setTitlesData(null);

    const formData = new FormData(event.currentTarget);
    const articleUrl = formData.get('articleUrl') as string;

    const result = await generateClickbaitTitles({ articleUrl });

    if (result.success) {
      setTitlesData(result.data);
    } else {
      setError(result.error);
    }

    setIsLoading(false);
  };

  return (
    <main className="container mx-auto max-w-2xl px-4 py-12">
      <h1 className="text-4xl font-bold text-center mb-8 text-amber-400">
        Generador de títulos virales con IA
      </h1>
      <div className='p-5 border-2 rounded-2xl bg-slate-700 border-slate-500'>
        <form onSubmit={handleSubmit} className="flex flex-col gap-4">
          <label htmlFor="articleUrl" className="font-semibold">
            URL del Artículo
          </label>
          <input
            id="articleUrl"
            name="articleUrl"
            type="url"
            required
            placeholder="https://ejemplo.com/mi-articulo-genial"
            className="p-2 border rounded-md shadow-sm bg-slate-300 text-gray-900 focus:ring-amber-400"
            disabled={isLoading}
          />
          <button
            type="submit"
            className="bg-amber-400 text-gray-900 font-bold py-2 px-4 rounded-md hover:bg-amber-500 disabled:bg-gray-400 transition-colors"
            disabled={isLoading}
          >
            {isLoading ? 'Generando...' : 'Generar Títulos'}
          </button>
        </form>

        {/* Sección de Resultados y Errores */}
        <div className="mt-10">
          {error && (
            <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded-md" role="alert">
              <strong className="font-bold">Error: </strong>
              <span className="block sm:inline">{error}</span>
            </div>
          )}

          {titlesData && (
            <div className="bg-slate-300 text-gray-800 p-6 rounded-lg shadow-md">
              <h2 className="text-xl font-semibold mb-4">Sugerencias de Títulos:</h2>
              <ul className="list-disc list-inside space-y-2">
                {titlesData.titles.map((title, index) => (
                  <li key={index} className="text-shadow-md">
                    {title}
                  </li>
                ))}
              </ul>
            </div>
          )}

          {isLoading && (
            <div className="text-center pt-8">
              <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-amber-400 mx-auto"></div>
              <p className="mt-4 text-gray-200">La IA está pensando... por favor espera.</p>
            </div>
          )}
        </div>
      </div>
    </main>
  );
}

Paso 2: Añadir estilos básicos

Para que el spinner de carga funcione, añade la animación spin a tu globals.css si no estuviera ya definida por Tailwind CSS.

// src/app/globals.css
@import "tailwindcss";

:root {
  --background: #1d293d;
  --foreground: #ffffff;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;
    --foreground: #ededed;
  }
}

body {
  background: var(--background);
  color: var(--foreground);
  font-family: Arial, Helvetica, sans-serif;
}

@keyframes spin {
  from {
    transform: rotate(0deg);
  }

  to {
    transform: rotate(360deg);
  }
}

.animate-spin {
  animation: spin 1s linear infinite;
}

Análisis del componente de UI

'use client': Es la primera y más importante línea. Declara la frontera entre el servidor y el cliente. Todo este archivo y sus dependencias (excluyendo las Server Actions) se ejecutarán en el navegador.

Manejo de estado (useState):

isLoading: Un booleano simple pero efectivo para gestionar el estado de la UI durante la petición. Deshabilita el formulario para prevenir envíos duplicados y muestra un indicador de carga.
titlesData: Almacena la respuesta exitosa. Su tipo, TitlesData, se infiere directamente de nuestro schema AITitlesOutputSchema, manteniendo la consistencia de tipos de extremo a extremo.
error: Almacena el mensaje de error de la Server Action, permitiéndonos mostrar feedback útil al usuario.

Invocación de la Server Action:

La línea const result = await generateClickbaitTitles({ articleUrl }); es donde ocurre la magia.

Invocación Directa: Observa que no hay fetch, no hay URLs de API, no hay useEffect. Importamos generateClickbaitTitles como si fuera una función local y la llamamos directamente. Next.js y React se encargan de la comunicación de red por debajo. Esto es una de las mayores ventajas de la arquitectura del App Router.
Manejo de la Respuesta: El objeto discriminado que diseñamos en nuestra Server Action ({ success, data | error }) hace que el manejo de la respuesta en el cliente sea limpio, predecible y seguro.

Renderizado condicional:

La UI reacciona a los diferentes estados (isLoading, error, titlesData) para mostrar siempre la información más relevante: el formulario, un spinner, un mensaje de error o los resultados. Este es un patrón fundamental en el desarrollo de UIs modernas y robustas.

1.12 Ejecución y verificación final

Guarda todos los archivos y ejecuta tu aplicación de desarrollo:

pnpm dev

Navega a http://localhost:3000. Deberías ver el formulario.

Prueba los siguientes escenarios:

Caso de éxito: Introduce una URL válida (ej. https://vercel.com/blog/ai-sdk-5) y haz clic en "Generar Títulos". Verás el spinner.

Después de unos segundos, aparecerán los tres títulos generados por Gemini.

Error de validación: Intenta enviar una URL inválida (ej. texto-invalido). La Server Action devolverá el error de validación de Zod, y lo verás mostrado en la UI.

Este error también aparece si hay un problema de comunicación con el proveedor o si la API_KEY es incorrecta. En un entorno de producción debería tener un sistema de logs que recojan toda esta información, pero de momento podemos consultar la terminal para detectar el error.

Estado de carga: En una conexión lenta (puedes simularlo en las herramientas de desarrollador de tu navegador), verás que el formulario se deshabilita y el spinner se muestra hasta que la respuesta llega.

Conclusión del capítulo 1

¡Felicidades! Has construido y desplegado tu primera aplicación de IA Full-Stack completa. Aunque la funcionalidad es simple, la arquitectura subyacente es increíblemente potente y escalable.

Repasemos los logros clave de este capítulo desde una perspectiva senior:

Arquitectura sólida: Has implementado una separación clara entre la lógica de servidor (Server Action) y la presentación (Client Component), utilizando el paradigma de Next.js App Router.
Contratos de datos inquebrantables: Has utilizado Zod para definir esquemas que garantizan la integridad de los datos desde la entrada del usuario hasta la salida de la IA, previniendo una clase entera de errores de runtime.
Interacción robusta con la IA: Has utilizado generateObject del Vercel AI SDK para asegurar que la respuesta del LLM sea siempre estructurada y validada, eliminando la fragilidad del parseo manual de JSON.
Experiencia de usuario consciente: Has manejado los estados de carga y error, proporcionando feedback claro al usuario, un aspecto crucial cuando se trabaja con operaciones asíncronas potencialmente lentas.

Has sentado los cimientos. Cada uno de los conceptos que hemos implementado aquí —Server Actions, validación con Zod, streaming (que exploraremos a fondo), y la abstracción del SDK— será una pieza fundamental en los sistemas más complejos que construiremos en los próximos capítulos.

Puedes encontrar el código de esta sección en: https://github.com/aperezl/ai-fullstack-serie/tree/fundamentals-ai-part3

Ahora que dominas la interacción básica, estás listo para llevar tus aplicaciones al siguiente nivel: la conversación en tiempo real.

Fundamentos modernos y primera interacción con IA. Parte 2

Antonio Manuel Pérez López — Wed, 27 Aug 2025 10:04:39 +0000

De la teoría al terminal: configurando nuestro entorno de desarrollo

La teoría nos ha proporcionado el mapa; ahora es el momento de trazar el territorio. En esta sección, traduciremos los conceptos arquitectónicos en una estructura de proyecto tangible. Configuraremos nuestro entorno, instalaremos las dependencias clave y estableceremos una base de código limpia y organizada, lista para la integración de la lógica de IA.

Podrás encontrar el código de este artículo en: https://github.com/aperezl/ai-fullstack-serie/tree/fundamentals-ai-part2

Prerrequisitos:

Node.js v18 o superior.
Una clave de API para Google AI Studio (Gemini).

Paso 1: Inicialización del proyecto Next.js

Comenzamos creando un nuevo proyecto Next.js utilizando el App Router. Abre tu terminal y ejecuta:

npx create-next-app@latest ai-fullstack-serie --typescript --tailwind --eslint
cd ai-fullstack-serie

Durante la instalación se nos harán preguntas sobre la configuración que queremos, podemos elegirla a nuestro gusto.

$ npx create-next-app@latest ia-fullstack-serie --typescript --tailwind --eslint
√ Would you like your code inside a `src/` directory? ... No / Yes
√ Would you like to use App Router? (recommended) ... No / Yes
√ Would you like to use Turbopack for `next dev`? ... No / Yes
√ Would you like to customize the import alias (`@/*` by default)? ... No / Yes

Esta será la raíz de nuestro proyecto durante toda esta serie de artículos.

Paso 2: Instalación de dependencias esenciales

Instalaremos las bibliotecas que formarán el núcleo de nuestra interacción con la IA y la validación de datos.

pnpm install ai @ai-sdk/google zod

ai: El paquete principal del Vercel AI SDK.
@ai-sdk/google: El proveedor específico para los modelos Gemini de Google.
zod: Nuestra biblioteca de validación y definición de esquemas.

Paso 3: Configuración de variables de entorno

La seguridad de las claves de API es primordial. Crearemos un archivo .env.local en la raíz del proyecto para almacenar nuestras credenciales de forma segura. Este archivo nunca debe ser versionado en Git.

touch .env.local

Abre .env.local y añade tu clave de API de Google:

GOOGLE_GENERATIVE_AI_API_KEY="TU_API_KEY_DE_GEMINI_AQUI"

El Vercel AI SDK detectará automáticamente esta variable de entorno.

Para obtener nuestra API_KEY de Google Gemini tendrémos que ir a Google AI Studio y seleccionar la opción Get API key

Posteriormente pulsamos sobre Crear clave de API

Ejercicio 1: Creando una arquitectura de ficheros escalable

Una decisión temprana que distingue a un proyecto senior es su estructura de directorios. En lugar de colocar toda la lógica en app/, adoptaremos una estructura más modular y mantenible.

Crea los siguientes directorios dentro del proyecto:

/
|- src
|  |- app/
|  |- components/
|    |- ui/      # Para componentes de UI reusables (ej. shadcn/ui)
|  |- features/  # Para "vertical slices" o funcionalidades completas
|  |- lib/
|    |- ai/      # Lógica relacionada con la IA
|    |- utils.ts # Funciones de utilidad generales
|    |- validations/ # Esquemas de Zod
|- .env.local
|- next.config.mjs
|- package.json
...

Justificación de la arquitectura:

lib/: Contiene la lógica de negocio central y compartida. lib/ai albergará nuestras Server Actions que interactúan con los LLMs. lib/validations contendrá todos nuestros esquemas de Zod, centralizando la "fuente de verdad" de nuestras estructuras de datos.
features/: Para funcionalidades más grandes y autocontenidas. Por ejemplo, si construimos un dashboard de análisis, todo lo relacionado (componentes, hooks, API routes) podría vivir en features/analytics/. Por ahora lo dejaremos vacío.
components/ui/: Un lugar estándar para componentes de UI atómicos y reutilizables, compatible con la instalación por defecto de shadcn/ui, que usaremos más adelante.

Esta separación de responsabilidades (Separation of Concerns) es fundamental. Nuestra lógica de IA (lib/ai) no sabe nada sobre la UI que la consume, lo que la hace reutilizable y fácil de testear.

Ejercicio 2: Implementando nuestra primera Server Action con IA

Ahora, construiremos la pieza central de este capítulo: una Server Action que encapsula una llamada a Gemini, validada de principio a fin.

Paso 1: Definir los "contratos" con Zod

Antes de escribir la lógica, definimos las estructuras de datos. Crea el archivo src/lib/validations/schemas.ts:

import { z } from 'zod';

// Esquema para la entrada de nuestra Server Action
export const GenerateTitlesInputSchema = z.object({
  articleUrl: z
    .string()
    .url({ message: "Por favor, introduce una URL válida." })
    .min(10, { message: "La URL parece demasiado corta." }),
});

// Esquema para la salida que esperamos del LLM
export const AITitlesOutputSchema = z.object({
  titles: z
    .array(z.string().min(10, { message: "El título es demasiado corto." }))
    .length(3, { message: "Esperábamos exactamente 3 títulos." })
    .describe("Un array de 3 títulos clickbait para el artículo."),
});

Hemos definido dos contratos claros: uno para la entrada que nuestra UI debe proporcionar y otro para la salida que exigimos al LLM. El uso de .describe() será crucial en capítulos posteriores para guiar al modelo.

Paso 2: Crear la Server Action

Ahora, la lógica principal. Crea el archivo src/lib/ai/actions.ts:

'use server';

import { google } from '@ai-sdk/google';
import { generateObject } from 'ai';
import { GenerateTitlesInputSchema, AITitlesOutputSchema } from '@/src/lib/validations/schemas';
import { z } from 'zod';
import { revalidatePath } from 'next/cache';

// Derivamos el tipo de la salida de la IA a partir del schema de Zod
type AITitles = z.infer<typeof AITitlesOutputSchema>;

// Definimos los tipos auxiliares.
export type GenerateTitlesSuccess = {
  success: true;
  data: AITitles;
};

export type GenerateTitlesError = {
  success: false;
  error: string;
};

export type GenerateTitlesResponse = GenerateTitlesSuccess | GenerateTitlesError;

export async function generateClickbaitTitles(
  input: z.infer<typeof GenerateTitlesInputSchema>
): Promise<GenerateTitlesResponse> {
  try {
    // 1. Validar la entrada con nuestro schema. Falla rápido si no es válida.
    const validation = GenerateTitlesInputSchema.safeParse(input);
    if (!validation.success) {
      return {
        success: false,
        error: validation.error.flatten().fieldErrors.articleUrl?.[0] || 'Entrada inválida.'
      };
    }

    const { articleUrl } = validation.data;

    // Hacemos fetch a la URL, el contenido HTML de esa petición será lo que analicemos
    const response = await fetch(articleUrl)
    const articleContent = await response.text()

    // 2. Instanciar el modelo y preparar el prompt
    const model = google('gemini-2.0-flash-001');

    const prompt = `
      Eres un experto en SEO y marketing digital con 20 años de experiencia,
      especializado en crear titulares virales.
      Analiza el siguiente contenido de un artículo y genera exactamente
      3 títulos clickbait optimizados para redes sociales.
      Los títulos deben ser provocativos, cortos y generar curiosidad.
      No añadas ninguna explicación, solo devuelve el objeto JSON con la estructura requerida.
      Contenido del artículo: "${articleContent}"
    `;

    // 3. Llamar a la IA con generateObject para obtener una salida estructurada
    const { object } = await generateObject({
      model: model,
      schema: AITitlesOutputSchema, // Le decimos a la IA la "forma" que debe tener su respuesta
      prompt: prompt,
    });

    // La validación contra AITitlesOutputSchema ya la hace 'generateObject' por nosotros.
    // Si la forma no es correcta, la función lanzará un error que capturaremos.

    revalidatePath('/'); // Opcional: Invalida el caché de la página si es necesario.

    return { success: true, data: object };

  } catch (e) {
    console.error(e);
    // Para un sistema en producción, aquí registraríamos el error en un servicio de logging.
    return {
      success: false,
      error: 'Ha ocurrido un error al contactar con la IA. Por favor, inténtalo de nuevo.'
    };
  }
}

Análisis del código experto:

'use server': Directiva que define este archivo como un módulo de Server Actions, ejecutable en el servidor.
generateObject vs generateText: Elegimos generateObject deliberadamente. En lugar de pedir al LLM que devuelva un string JSON y luego hacer JSON.parse (lo que es frágil), le pasamos nuestro AITitlesOutputSchema. El AI SDK se encarga de instruir al modelo para que genere una salida que se ajuste a ese esquema y la valida por nosotros. Esto es infinitamente más robusto.
Validación de Entrada Explícita: Usamos safeParse al principio. Un principio de diseño senior es "confía pero verifica", incluso en las fronteras internas de nuestro propio sistema.
Manejo de Errores: El bloque try...catch no es opcional. Las llamadas a la red y a la IA pueden fallar por múltiples razones. Devolvemos un objeto discriminado ({ success: true | false, ... }) que la UI podrá manejar de forma predecible.
Prompt Engineering: El prompt es detallado y asigna un rol (persona) al LLM. Le damos instrucciones claras y negativas ("No añadas ninguna explicación") para acotar su comportamiento.

Conclusiones de la práctica

Hemos construido el motor de nuestra primera funcionalidad de IA. Es importante destacar lo que hemos logrado: una función de backend (generateClickbaitTitles) completamente autocontenida, segura en sus tipos, robusta frente a errores y totalmente desacoplada de la interfaz de usuario.

Esta Server Action está ahora lista para ser importada y utilizada desde cualquier Client Component en nuestra aplicación, como si fuera una función local. Hemos sentado las bases arquitectónicas correctas.

Puedes encontrar el código de esta sección en: https://github.com/aperezl/ai-fullstack-serie/tree/fundamentals-ai-part2

Con el backend listo, en la siguiente sección construiremos la interfaz de usuario que consumirá esta lógica y presentará los resultados al usuario final.

Fundamentos modernos y primera interacción con IA. Parte 1

Antonio Manuel Pérez López — Tue, 26 Aug 2025 21:28:01 +0000

Más allá de la aplicación web tradicional

Como desarrollador con décadas de experiencia, he sido testigo y protagonista de la evolución de la web: desde los monolitos renderizados en servidor, pasando por la revolución de las SPAs (Single-Page Applications) con AJAX, hasta el auge de los frameworks de componentes como React. Cada etapa trajo consigo nuevos patrones de diseño, desafíos de rendimiento y abstracciones. Hoy, nos encontramos en el umbral de una transformación de similar magnitud: la era de las aplicaciones de IA nativas.

Este capítulo no pretende enseñarte a programar (seguramente no sería un buen ejemplo a seguir). Su objetivo es investigar un nuevo modelo mental arquitectónico. Las aplicaciones que integraremos con Inteligencia Artificial Generativa no son simplemente aplicaciones tradicionales con una API de LLM atornillada. Requieren un enfoque fundamentalmente diferente en cuanto a la renderización, el manejo del estado, la validación de datos y la comunicación entre cliente y servidor. Las herramientas que hemos elegido —Next.js con App Router, TypeScript en su máxima expresión y el Vercel AI SDK— no son meras preferencias, sino decisiones arquitectónicas deliberadas que responden a los desafíos únicos de este nuevo paradigma.

Abordaremos tres pilares fundamentales:

La arquitectura de renderizado de Next.js: Cómo los React Server Components (RSC) nos permiten crear interfaces más rápidas y seguras, un requisito indispensable para las costosas y, a menudo, lentas inferencias de los modelos de IA.
TypeScript como contrato de sistema: Cómo usamos tipos avanzados y validación con Zod no solo para la seguridad, sino para definir un "contrato" estricto con una entidad no determinista como es un LLM.
Vercel AI SDK como capa de comunicación: Cómo una capa de abstracción bien diseñada nos permite mantener la agilidad y evitar el acoplamiento a un único proveedor de IA en un ecosistema que evoluciona a una velocidad vertiginosa.

Prepárate para reevaluar algunos patrones establecidos y adoptar un nuevo conjunto de herramientas mentales. Empecemos.

Arquitectura avanzada en Next.js: El paradigma de los React Server Components (RSC)

El App Router de Next.js no es una simple mejora sobre el Pages Router; es un cambio de paradigma completo que devuelve gran parte de la lógica de renderizado al servidor, donde siempre debió estar para ciertas tareas. Para nosotros, como arquitectos de aplicaciones de IA, esto tiene implicaciones profundas.

El dúo dinámico: Server Components vs. Client Components

El modelo mental clave a interiorizar es que, por defecto, todo es un Server Component. Un RSC es un fragmento de UI que se ejecuta exclusivamente en el servidor, una única vez durante el ciclo de vida de la petición. Su resultado es una descripción de la UI (un formato intermedio similar a HTML) que se envía al cliente.

Características clave de los Server Components (RSC):

Javascript de cliente cero: No envían ni una sola línea de su propio código JavaScript al navegador. Esto resulta en un TTI (Time to Interactive) drásticamente reducido.
Acceso directo al backend: Pueden acceder directamente a recursos del servidor (bases de datos, sistemas de archivos, APIs internas, variables de entorno secretas) sin necesidad de una capa de API intermedia. Esto es revolucionario para la IA, ya que nos permite obtener contexto o ejecutar lógica de backend directamente desde el componente que lo necesita.
Renderizado asíncrono: Pueden ser funciones async. Esto permite realizar operaciones de datos (ej. fetch, consultas a BBDD) y esperar su resolución antes de completar el renderizado.

Por otro lado, cuando necesitamos interactividad (manejar eventos, estado, hooks de ciclo de vida), marcamos un componente con la directiva "use client". Esto no convierte solo a ese componente en un Client Component, sino que establece una frontera: ese componente y todos los que importe (que no sean a su vez RSC) formarán parte del bundle de JavaScript que se envía al cliente para su hidratación.

Patrones de composición para aplicaciones de IA

La maestría no reside en saber qué es un RSC o un Client Component, sino en saber cómo combinarlos. Para las aplicaciones de IA, estos patrones son cruciales:

Patrón de "Cáscara Estática, Contenido Dinámico" (Static Shell, Dynamic Content): La estructura principal de la aplicación (layout, navegación, cabeceras) se define como RSCs. Son estáticos, se cargan instantáneamente y no cambian. Dentro de esta cáscara, las áreas interactivas (como una ventana de chat o un formulario de prompt) se definen como Client Components. Esto nos da lo mejor de ambos mundos: una carga inicial ultrarrápida y una interactividad rica donde se necesita.
Streaming de UI con Suspense: Las respuestas de los LLMs pueden tardar varios segundos en empezar a generarse (Time To First Token). Hacer que el usuario espere a que toda la página cargue es inaceptable. Los RSC se integran nativamente con Suspense. Podemos envolver un componente RSC que realiza una llamada a un LLM en un Suspense con un fallback (p. ej., un spinner). Next.js enviará inmediatamente el HTML de la página con el spinner, y cuando la llamada al LLM resuelva, streameará la UI resultante para reemplazar el spinner, sin necesidad de una recarga de página.
Server Actions: Mutaciones sin API boilerplate: Son funciones asíncronas que se definen en el servidor (en un RSC o en un archivo con "use server") pero que se pueden invocar directamente desde un Client Component. Simplifican radicalmente las mutaciones de datos. En nuestro contexto, una Server Action es la forma perfecta de manejar el envío de un prompt desde un formulario en un Client Component a nuestra lógica de backend que llamará a la IA, sin tener que escribir manualmente un fetch a un endpoint de API.

Diagrama arquitectónico conceptual:

Dominar esta arquitectura es el primer paso para construir aplicaciones de IA que sean robustas y ofrezcan una experiencia de usuario excepcional.

TypeScript para expertos: Blindando la interfaz con la IA

Si tienes experiencia en javascript seguro que has visto cómo los sistemas de tipos han pasado de ser una curiosidad académica a una herramienta indispensable en sistemas a gran escala. En el desarrollo de IA, TypeScript trasciende la mera seguridad de tipos para convertirse en una herramienta de diseño de contratos. Nuestra interacción con un LLM es, por naturaleza, una comunicación con un sistema no determinista. Nuestro trabajo como ingenieros es imponer determinismo y estructura sobre esa interacción.

Inferencia y genéricos para abstracciones reutilizables

No nos detendremos en la sintaxis básica. En cambio, nos centraremos en cómo los genéricos avanzados nos permiten construir abstracciones robustas. Por ejemplo, podemos crear una función de envoltura para las llamadas a la IA que maneje la validación, el logging y los errores de forma genérica, sin importar la forma (schema) de la respuesta esperada:

async function safeAICall<T extends z.ZodType>(
  prompt: string,
  schema: T
): Promise<{ success: true, data: z.infer<T> } | { success: false, error: string }> {
  // ... lógica de llamada a la IA ...
  // ... validación de la respuesta contra el schema ...
  // Devolvemos un tipo discriminado seguro
}

Este patrón nos permite manejar diferentes "formas" de respuesta de la IA de una manera completamente type-safe.

Zod: El contrato inmutable entre humano y máquina

zod es la pieza central de nuestra estrategia de validación. Lo tratamos como la única fuente de verdad para la estructura de los datos que fluyen hacia y desde el LLM.

Definición del Schema: Un schema de Zod es más que una validación; es una declaración de intenciones. Define la estructura exacta que esperamos.
Inferencia de tipos (z.infer): La magia de Zod reside en z.infer<typeof miSchema>. Esto nos permite derivar automáticamente un tipo de TypeScript estático a partir de un validador de runtime. Se acabaron las definiciones de tipos duplicadas y la desincronización entre la validación y el tipado estático.
El Método .describe(): A menudo subestimado, el método .describe() es crucial en el desarrollo con IA. Cuando en capítulos posteriores pidamos al LLM que genere JSON estructurado, las descripciones que proporcionamos en el schema de Zod actúan como "hints" o instrucciones para el modelo, mejorando drásticamente la calidad y fiabilidad de su salida.

Flujo de datos validado:

Este doble filtro, en la entrada y en la salida, es nuestra principal línea de defensa contra respuestas inesperadas o malformadas del LLM, garantizando que el resto de nuestra aplicación siempre opere sobre datos predecibles y seguros.

Vercel AI SDK Core: La capa de comunicación unificada

El ecosistema de la IA generativa está en un estado de cambio constante. Los modelos se actualizan, nuevos proveedores emergen y los precios fluctúan. Acoplar nuestra lógica de negocio directamente a la API de un proveedor específico (sea OpenAI, Google, Anthropic, etc.) es una receta para la obsolescencia técnica y la rigidez.

El Vercel AI SDK nos proporciona una capa de abstracción esencial que nos aísla de esta complejidad.

El principio "proveedor agnóstico"

La belleza del AI SDK radica en su simplicidad. Cambiar de un modelo de Google a uno de Anthropic (suponiendo capacidades similares) es, idealmente, un cambio de una sola línea:

// De:
const model = google('gemini-2.5-pro');
// A:
const model = anthropic('claude-3-opus-20240229');

Esta abstracción nos permite experimentar, comparar y pivotar entre proveedores con un coste de ingeniería mínimo, una capacidad estratégica en este campo.

Anatomía de `generateText`

generateText es nuestra herramienta de trabajo fundamental para interacciones simples y no conversacionales. Su firma encapsula los elementos esenciales de una llamada a un LLM:

const { text, usage, finishReason } = await generateText({
  model: google('gemini-2.5-pro'),
  system: 'Eres un asistente experto en literatura del Siglo de Oro.',
  prompt: 'Analiza la métrica del primer soneto de Garcilaso.',
});

model: La instancia del modelo que hemos elegido, abstraída por el SDK.
system: El "system prompt" es nuestra oportunidad para dar al modelo una personalidad, un contexto y unas reglas de comportamiento generales que aplicarán a toda la interacción. Es una de las herramientas más potentes del prompt engineering.
prompt: La instrucción específica para esta llamada.

El objeto devuelto nos da no solo el text generado, sino también metadatos valiosos como usage (el recuento de tokens, crucial para el control de costes) y finishReason (por qué el modelo dejó de generar texto).

El poder del streaming con `streamText`

Para cualquier aplicación interactiva, el streaming no es una opción, es una necesidad. streamText es la contraparte asíncrona de generateText. En lugar de esperar a que la respuesta completa esté disponible, nos devuelve un AsyncIterable que podemos consumir a medida que los "tokens" llegan desde el servidor.

Esto se integra perfectamente con la arquitectura de RSC y Suspense que discutimos. En el backend, un Route Handler puede usar streamText y devolver el stream directamente. En el frontend, el hook useChat (que veremos en el próximo capítulo) consumirá este stream para renderizar la respuesta de forma progresiva, mejorando drásticamente la experiencia de usuario percibida.

Conclusiones de la parte teórica

Hemos sentado las bases. No hemos escrito una aplicación de IA completa todavía, pero hemos hecho algo más importante: hemos establecido una arquitectura robusta y un modelo mental preparado para los desafíos que nos esperan.

Hemos entendido que la combinación de renderizado en servidor (RSC) para la estructura, validación estricta de contratos (TypeScript/Zod) para los datos y una capa de comunicación agnóstica (Vercel AI SDK) para la lógica de IA, nos proporciona la flexibilidad, seguridad y rendimiento necesarios para construir aplicaciones de IA de nivel profesional.

Con estos cimientos en su sitio, estamos listos para construir nuestra primera aplicación interactiva. En los próximos capítulos, tomaremos estos conceptos y los aplicaremos para crear un chatbot en tiempo real, manejando el streaming de principio a fin.