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

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

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

​

Instalar paquetes del AI SDK

npm i ai @ai-sdk/react zod

• 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

​

Instalar AI Elements

npx ai-elements@latest

​

Instalar el proveedor de OpenAI

npm install @ai-sdk/openai

• Previsualización
• Código

​

Entendiendo el Frontend

• 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 mensajes: Copiar y reintentar en mensajes del asistente

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:
      "Eres un asistente útil que puede responder preguntas y ayudar con tareas.",
  });

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

• 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

​

Instalar el SDK de Firecrawl

npm i @mendable/firecrawl-js

​

Crea el archivo de herramientas

mkdir lib && touch lib/tools.ts

import FirecrawlApp from "@mendable/firecrawl-js";
import { tool } from "ai";
import { z } from "zod";

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

export const scrapeWebsiteTool = tool({
  description: 'Extraer contenido de cualquier URL de sitio web',
  inputSchema: z.object({
    url: z.string().url().describe('La URL a extraer')
  }),
  execute: async ({ url }) => {
    console.log('Extrayendo:', url);
    const result = await firecrawl.scrape(url, {
      formats: ['markdown'],
      onlyMainContent: true,
      timeout: 30000
    });
    console.log('Vista previa del contenido extraído:', result.markdown?.slice(0, 200) + '...');
    return { content: result.markdown };
  }
});

export const searchWebTool = tool({
  description: 'Buscar en la web usando Firecrawl',
  inputSchema: z.object({
    query: z.string().describe('La consulta de búsqueda'),
    limit: z.number().optional().describe('Número de resultados'),
    location: z.string().optional().describe('Ubicación para resultados localizados'),
    tbs: z.string().optional().describe('Filtro de tiempo (qdr:h, qdr:d, qdr:w, qdr:m, qdr:y)'),
    sources: z.array(z.enum(['web', 'news', 'images'])).optional().describe('Tipos de resultados'),
    categories: z.array(z.enum(['github', 'research', 'pdf'])).optional().describe('Categorías de filtro'),
  }),
  execute: async ({ query, limit, location, tbs, sources, categories }) => {
    console.log('Buscando:', 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 || 'Sin título',
      url: item.url || '',
      description: item.description || '',
    }));

    console.log('Resultados de búsqueda:', results.length);
    return { results };
  },
});

​

Entender las herramientas

• 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

• 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

import { streamText, UIMessage, stepCountIs, convertToModelMessages } from "ai";
import { createOpenAI } from "@ai-sdk/openai";
import { scrapeWebsiteTool, searchWebTool } from "@/lib/tools";

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

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.",
    // Agrega aquí las herramientas de Firecrawl
    tools: {
      scrapeWebsite: scrapeWebsiteTool,
      searchWeb: searchWebTool,
    },
    stopWhen: stepCountIs(5),
    toolChoice: webSearch ? "auto" : "none",
  });

  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

• 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

npm run dev

1. Activa el botón “Search” para habilitar la búsqueda en la 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