Cómo crear un asistente de investigación con IA usando Firecrawl y el AI SDK

Crear un nuevo proyecto de Next.js

Empieza creando una nueva aplicación de Next.js y navega al directorio del proyecto:

npx create-next-app@latest ai-sdk-firecrawl && cd ai-sdk-firecrawl

Cuando se te solicite, selecciona las siguientes opciones:

• TypeScript: Sí
• ESLint: Sí
• Tailwind CSS: Sí
• App Router: Sí
• Usar directorio src/: No
• Alias de importación: Sí (@/*)

Instalar las dependencias

Instalar paquetes del AI SDK

El AI SDK es un conjunto de herramientas de TypeScript que proporciona una API unificada para trabajar con distintos proveedores de LLM:

npm i ai @ai-sdk/react zod

Estos paquetes ofrecen:

• ai: SDK principal con streaming, invocación de herramientas y manejo de respuestas
• @ai-sdk/react: Hooks de React como useChat para crear interfaces de chat
• zod: Validación de esquemas para entradas de herramientas

Más información en ai-sdk.dev/docs.

Instalar AI Elements

AI Elements proporciona componentes de UI prediseñados para aplicaciones de IA. Ejecuta el siguiente comando para generar todos los componentes necesarios:

npx ai-elements@latest

Esto configura AI Elements en tu proyecto, incluidos componentes de conversación, visualización de mensajes, campos de entrada de prompts y representaciones de llamadas a herramientas.

Documentación: ai-sdk.dev/elements/overview.

Instalar el proveedor de OpenAI

Instala el proveedor de OpenAI para conectarte con los modelos de OpenAI:

npm install @ai-sdk/openai

Construye la interfaz de chat del frontend

Crea la página principal en app/page.tsx y copia el código de la pestaña Code que aparece a continuación. Esta será la interfaz de chat donde los usuarios interactúan con el asistente de IA.

Entendiendo el Frontend

El frontend usa componentes de AI Elements para proporcionar una interfaz de chat completa:

Características principales:

• Visualización de la conversación: El componente Conversation gestiona automáticamente el desplazamiento y la presentación de los mensajes
• Representación de mensajes: Cada parte del mensaje se representa según su tipo (texto, razonamiento, llamadas a herramientas)
• Visualización de herramientas: Las llamadas a herramientas se muestran con secciones plegables que muestran entradas y salidas
• Controles interactivos: Los usuarios pueden activar o desactivar la búsqueda web, elegir modelos y adjuntar archivos
• Acciones de mensaje: Acciones de copiar y reintentar para los mensajes del asistente

Agregar compatibilidad con el renderizado de Markdown

Para asegurarte de que el markdown del LLM se renderice correctamente, añade la siguiente importación a tu archivo app/globals.css:

@source "../node_modules/streamdown/dist/index.js";

Esto importa los estilos necesarios para mostrar contenido Markdown en las respuestas de los mensajes.

Crear la ruta básica de API

Crea el endpoint de la API de chat en app/api/chat/route.ts. Esta ruta gestionará los mensajes entrantes y transmitirá respuestas de la IA.

import { streamText, UIMessage, convertToModelMessages } from "ai";
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

// Permitir respuestas de streaming hasta por 5 minutos
export const maxDuration = 300;

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

  const result = streamText({
    model: openai(model),
    messages: convertToModelMessages(messages),
    system:
      "You are a helpful assistant that can answer questions and help with tasks.",
  });

  // enviar fuentes y razonamiento de vuelta al cliente
  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

Esta ruta básica:

• Recibe mensajes del frontend
• Usa el modelo de OpenAI seleccionado por el usuario
• Transmite respuestas al cliente
• Aún no incluye herramientas; las añadiremos a continuación

Configurar las variables de entorno

Crea un archivo .env.local en la raíz de tu proyecto:

touch .env.local

Añade tu clave de la API de OpenAI:

OPENAI_API_KEY=sk-your-openai-api-key

Se requiere la variable OPENAI_API_KEY para que el modelo de IA funcione.

Prueba el chat básico

Ahora puedes probar el chatbot del SDK de IA sin la integración con Firecrawl. Inicia el servidor de desarrollo:

npm run dev

Abre localhost:3000 en tu navegador y prueba la funcionalidad básica del chat. El asistente debería responder a los mensajes, pero aún no tendrá capacidades de scraping web ni de búsqueda.

Agregar herramientas de Firecrawl

Ahora vamos a mejorar el asistente con capacidades de scraping web y búsqueda usando Firecrawl.

Instalar el SDK de Firecrawl

Firecrawl convierte sitios web en formatos listos para LLM con funciones de scraping y búsqueda:

npm i firecrawl

Crea el archivo de herramientas

Crea una carpeta lib y añade un archivo tools.ts dentro:

mkdir lib && touch lib/tools.ts

Agrega el siguiente código para definir las herramientas de web scraping y búsqueda:

import { Firecrawl } from "firecrawl";
import { tool } from "ai";
import { z } from "zod";

const firecrawl = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY });

export const scrapeWebsiteTool = tool({
  description: 'Scrape content from any website URL',
  inputSchema: z.object({
    url: z.string().url().describe('The URL to scrape')
  }),
  execute: async ({ url }) => {
    console.log('Scraping:', url);
    const result = await firecrawl.scrape(url, {
      formats: ['markdown'],
      onlyMainContent: true,
      timeout: 30000
    });
    console.log('Scraped content preview:', result.markdown?.slice(0, 200) + '...');
    return { content: result.markdown };
  }
});

export const searchWebTool = tool({
  description: 'Search the web using Firecrawl',
  inputSchema: z.object({
    query: z.string().describe('The search query'),
    limit: z.number().optional().describe('Number of results'),
    location: z.string().optional().describe('Location for localized results'),
    tbs: z.string().optional().describe('Time filter (qdr:h, qdr:d, qdr:w, qdr:m, qdr:y)'),
    sources: z.array(z.enum(['web', 'news', 'images'])).optional().describe('Result types'),
    categories: z.array(z.enum(['github', 'research', 'pdf'])).optional().describe('Filter categories'),
  }),
  execute: async ({ query, limit, location, tbs, sources, categories }) => {
    console.log('Searching:', query);
    const response = await firecrawl.search(query, {
      ...(limit && { limit }),
      ...(location && { location }),
      ...(tbs && { tbs }),
      ...(sources && { sources }),
      ...(categories && { categories }),
    }) as { web?: Array<{ title?: string; url?: string; description?: string }> };

    const results = (response.web || []).map((item) => ({
      title: item.title || item.url || 'Untitled',
      url: item.url || '',
      description: item.description || '',
    }));

    console.log('Search results:', results.length);
    return { results };
  },
});

Entender las herramientas

Herramienta de extracción de sitios web:

• Acepta una URL como entrada (validada por un esquema de Zod)
• Usa el método scrape de Firecrawl para obtener la página en Markdown
• Extrae solo el contenido principal para reducir el uso de tokens
• Devuelve el contenido extraído para que la IA lo analice

Herramienta de búsqueda web:

• Acepta una consulta de búsqueda con filtros opcionales
• Usa el método search de Firecrawl para encontrar páginas web relevantes
• Admite filtros avanzados como ubicación, rango de tiempo y categorías de contenido
• Devuelve resultados estructurados con títulos, URL y descripciones

Más información sobre las herramientas: ai-sdk.dev/docs/foundations/tools.

Actualiza la ruta de la API con las herramientas de Firecrawl

Ahora actualiza tu app/api/chat/route.ts para incluir las herramientas de Firecrawl que acabamos de crear.

Cambios clave respecto a la ruta básica:

• Importa stepCountIs del AI SDK
• Importa las herramientas de Firecrawl desde @/lib/tools
• Agrega el objeto tools con las herramientas scrapeWebsite y searchWeb
• Agrega stopWhen: stepCountIs(5) para limitar los pasos de ejecución
• Establece toolChoice en “auto” cuando la búsqueda web esté habilitada; en “none” en caso contrario

Más información sobre streamText: ai-sdk.dev/docs/reference/ai-sdk-core/stream-text.

Añade tu clave de API de Firecrawl

Actualiza tu archivo .env.local para incluir tu clave de la API de Firecrawl:

OPENAI_API_KEY=sk-your-openai-api-key
FIRECRAWL_API_KEY=fc-your-firecrawl-api-key

Obtén tu clave de la API de Firecrawl en firecrawl.dev.

Prueba la aplicación completa

Reinicia el servidor de desarrollo:

npm run dev

Abre localhost:3000 y prueba el asistente mejorado:

1. Activa el botón “Search” para habilitar la búsqueda web
2. Pregunta: “¿Cuáles son las funciones más recientes de firecrawl.dev?”
3. Observa cómo la IA invoca la herramienta searchWeb o scrapeWebsite
4. Mira la ejecución de la herramienta en la interfaz con sus entradas y salidas
5. Lee el análisis de la IA basado en los datos extraídos