Criando um Assistente de Pesquisa com IA usando Firecrawl e AI SDK

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

• TypeScript: Sim
• ESLint: Sim
• Tailwind CSS: Sim
• App Router: Sim
• Usar diretório src/: Não
• Alias de importação: Sim (@/*)

​

Instalar pacotes do AI SDK

npm i ai @ai-sdk/react zod

• ai: SDK principal com streaming, chamamento de ferramentas e tratamento de respostas
• @ai-sdk/react: Hooks do React como useChat para criar interfaces de chat
• zod: Validação de esquemas para entradas de ferramentas

​

Instalar o AI Elements

npx ai-elements@latest

​

Instalar o provedor OpenAI

npm install @ai-sdk/openai

• Prévia
• Código

​

Entendendo o Frontend

• Exibição da conversa: O componente Conversation lida automaticamente com a rolagem e a exibição das mensagens
• Renderização de mensagens: Cada parte da mensagem é renderizada conforme seu tipo (texto, raciocínio, chamadas de ferramentas)
• Visualização de ferramentas: As chamadas de ferramenta são exibidas em seções recolhíveis que mostram entradas e saídas
• Controles interativos: os usuários podem ativar/desativar a pesquisa na web, escolher modelos e anexar arquivos
• Ações de mensagem: opções de copiar e tentar novamente para mensagens do assistente

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

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

// Permite respostas em streaming por até 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:
      "Você é um assistente útil que pode responder perguntas e ajudar com tarefas.",
  });

  // envia fontes e raciocínio de volta para o cliente
  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

• Recebe mensagens do frontend
• Usa o modelo da OpenAI selecionado pelo usuário
• Transmite as respostas de volta para o cliente
• Ainda não inclui ferramentas — vamos adicioná-las em seguida

​

Instalar o SDK do Firecrawl

npm i @mendable/firecrawl-js

​

Crie o arquivo de ferramentas

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: 'Extrair conteúdo de qualquer URL',
  inputSchema: z.object({
    url: z.string().url().describe('A URL a ser extraída')
  }),
  execute: async ({ url }) => {
    console.log('Extraindo:', url);
    const result = await firecrawl.scrape(url, {
      formats: ['markdown'],
      onlyMainContent: true,
      timeout: 30000
    });
    console.log('Prévia do conteúdo extraído:', result.markdown?.slice(0, 200) + '...');
    return { content: result.markdown };
  }
});

export const searchWebTool = tool({
  description: 'Buscar na web usando Firecrawl',
  inputSchema: z.object({
    query: z.string().describe('A consulta de busca'),
    limit: z.number().optional().describe('Número de resultados'),
    location: z.string().optional().describe('Localização para resultados regionalizados'),
    tbs: z.string().optional().describe('Filtro de tempo (qdr:h, qdr:d, qdr:w, qdr:m, qdr:y)'),
    sources: z.array(z.enum(['web', 'news', 'images'])).optional().describe('Tipos de resultado'),
    categories: z.array(z.enum(['github', 'research', 'pdf'])).optional().describe('Categorias 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 || 'Sem título',
      url: item.url || '',
      description: item.description || '',
    }));

    console.log('Resultados da busca:', results.length);
    return { results };
  },
});

​

Entendendo as Ferramentas

• Aceita uma URL como entrada (validada por um esquema Zod)
• Usa o método scrape do Firecrawl para obter a página em markdown
• Extrai apenas o conteúdo principal para reduzir o uso de tokens
• Retorna o conteúdo extraído para a IA analisar

• Aceita uma consulta com filtros opcionais
• Usa o método search do Firecrawl para encontrar páginas relevantes
• Suporta filtros avançados, como localização, intervalo de tempo e categorias de conteúdo
• Retorna resultados estruturados com títulos, URLs e descrições

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.",
    // Adicione as ferramentas do Firecrawl aqui
    tools: {
      scrapeWebsite: scrapeWebsiteTool,
      searchWeb: searchWebTool,
    },
    stopWhen: stepCountIs(5),
    toolChoice: webSearch ? "auto" : "none",
  });

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

• Importe stepCountIs do AI SDK
• Importe as ferramentas do Firecrawl de @/lib/tools
• Adicione o objeto tools com as ferramentas scrapeWebsite e searchWeb
• Adicione stopWhen: stepCountIs(5) para limitar as etapas de execução
• Defina toolChoice como “auto” quando a pesquisa na web estiver ativada e “none” caso contrário

npm run dev

1. Ative o botão “Search” para habilitar a pesquisa na web
2. Pergunte: “Quais são os recursos mais recentes do firecrawl.dev?”
3. Observe enquanto a IA chama a ferramenta searchWeb ou scrapeWebsite
4. Veja a execução da ferramenta na UI com entradas e saídas
5. Leia a análise da IA com base nos dados extraídos