Créer un assistant de recherche IA avec Firecrawl et l’AI SDK

Créer un nouveau projet Next.js

Commencez par créer une nouvelle application Next.js, puis accédez au répertoire du projet :

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

Lorsque vous y êtes invité, sélectionnez les options suivantes :

• TypeScript : Oui
• ESLint : Oui
• Tailwind CSS : Oui
• App Router : Oui
• Utiliser le répertoire src/ : Non
• Alias d’importation : Oui (@/*)

Installer les dépendances

Installer les packages de l’AI SDK

L’AI SDK est une boîte à outils TypeScript qui fournit une API unifiée pour interagir avec différents fournisseurs de LLM :

npm i ai @ai-sdk/react zod

Ces packages fournissent :

• ai : SDK principal avec diffusion (streaming), appel d’outils et gestion des réponses
• @ai-sdk/react : hooks React comme useChat pour créer des interfaces de conversation
• zod : validation de schémas pour les paramètres d’outils

En savoir plus sur ai-sdk.dev/docs.

Installer AI Elements

AI Elements propose des composants d’interface prêts à l’emploi pour les applications d’IA. Exécutez la commande suivante pour générer tous les composants nécessaires :

npx ai-elements@latest

Cela met en place AI Elements dans votre projet, notamment les composants de conversation, l’affichage des messages, les champs de saisie de invites et les visualisations d’appels d’outils.

Documentation : ai-sdk.dev/elements/overview.

Installer le fournisseur OpenAI

Installez le fournisseur OpenAI pour vous connecter aux modèles d’OpenAI :

npm install @ai-sdk/openai

Créer l’interface de chat front-end

Créez la page principale dans app/page.tsx et copiez le code depuis l’onglet Code ci-dessous. Il s’agira de l’interface de chat permettant aux utilisateurs d’interagir avec l’assistant IA.

Comprendre le Frontend

Le frontend utilise les composants AI Elements pour fournir une interface de chat complète :

Fonctionnalités principales :

• Affichage de la conversation : Le composant Conversation gère automatiquement le défilement et l’affichage des messages
• Rendu des messages : Chaque partie d’un message est affichée selon son type (texte, raisonnement, appels d’outils)
• Visualisation des outils : Les appels d’outils s’affichent dans des sections repliables présentant les entrées et les sorties
• Contrôles interactifs : les utilisateurs peuvent activer/désactiver la recherche sur le web, choisir des modèles et joindre des fichiers
• Actions sur les messages : Copier et réessayer les actions pour les messages de l’assistant

Ajouter la prise en charge du rendu de Markdown

Pour garantir que le Markdown renvoyé par le LLM s’affiche correctement, ajoutez l’import suivant à votre fichier app/globals.css :

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

Cela importe les styles nécessaires pour afficher le contenu Markdown dans les réponses de messages.

Créer la route d’API de base

Créez l’endpoint de l’API de chat dans app/api/chat/route.ts. Cette route gérera les messages entrants et diffusera les réponses de l’IA.

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

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

// Autorise les réponses en streaming jusqu'à 5 minutes
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.",
  });

  // renvoie les sources et le raisonnement au client
  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

Cette route basique :

• Reçoit des messages depuis le frontend
• Utilise le modèle OpenAI choisi par l’utilisateur
• Diffuse les réponses en continu au client
• N’inclut pas encore d’outils — nous les ajouterons ensuite

Configurer les variables d’environnement

Créez un fichier .env.local à la racine de votre projet :

touch .env.local

Ajoutez votre clé API OpenAI :

OPENAI_API_KEY=sk-your-openai-api-key

La variable OPENAI_API_KEY est nécessaire au fonctionnement du modèle d’IA.

Tester le chat de base

Vous pouvez maintenant tester le chatbot de l’AI SDK sans intégrer Firecrawl. Lancez le serveur de développement :

npm run dev

Ouvrez localhost:3000 dans votre navigateur et testez les fonctionnalités de chat de base. L’assistant devrait répondre aux messages, mais il n’aura pas encore de capacités d’exploration web ni de recherche.

Ajouter des outils Firecrawl

Passons maintenant à l’amélioration de l’assistant en lui ajoutant des fonctionnalités de scraping et de recherche sur le web grâce à Firecrawl.

Installer le SDK Firecrawl

Firecrawl convertit les sites web en formats prêts pour les LLM, avec des fonctions de scraping et de recherche :

npm i firecrawl

Créer le fichier des outils

Créez un dossier lib et ajoutez-y un fichier tools.ts :

mkdir lib && touch lib/tools.ts

Ajoutez le code suivant pour définir les outils d’extraction web et de recherche :

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('Aperçu du contenu scrapé :', 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('Recherche :', 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('Résultats de recherche :', results.length);
    return { results };
  },
});

Comprendre les outils

Outil d’extraction de site web :

• Accepte une URL en entrée (validée par un schéma Zod)
• Utilise la méthode scrape de Firecrawl pour récupérer la page en Markdown
• N’extrait que le contenu principal afin de réduire la consommation de jetons
• Renvoie le contenu extrait pour que l’IA l’analyse

Outil de recherche web :

• Accepte une requête de recherche avec des filtres optionnels
• Utilise la méthode search de Firecrawl pour trouver des pages web pertinentes
• Prend en charge des filtres avancés comme l’emplacement, la plage temporelle et les catégories de contenu
• Renvoie des résultats structurés avec des titres, des URL et des descriptions

En savoir plus sur les outils : ai-sdk.dev/docs/foundations/tools.

Mettre à jour la route d’API avec les outils Firecrawl

Mettez maintenant à jour votre app/api/chat/route.ts pour inclure les outils Firecrawl que nous venons de créer.

Principales modifications par rapport à la route de base :

• Importer stepCountIs depuis l’AI SDK
• Importer les outils Firecrawl depuis @/lib/tools
• Ajouter l’objet tools avec les outils scrapeWebsite et searchWeb
• Ajouter stopWhen: stepCountIs(5) pour limiter le nombre d’étapes d’exécution
• Définir toolChoice sur “auto” lorsque la recherche web est activée, “none” sinon

En savoir plus sur streamText : ai-sdk.dev/docs/reference/ai-sdk-core/stream-text.

Ajoutez votre clé API Firecrawl

Mettez à jour votre fichier .env.local pour y inclure votre clé d’API Firecrawl :

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

Récupérez votre clé API Firecrawl sur firecrawl.dev.

Tester l’application entière

Redémarrez votre serveur de développement :

npm run dev

Ouvrez localhost:3000 et testez l’assistant amélioré :

1. Activez le bouton “Search” pour activer la recherche web
2. Demandez : “What are the latest features from firecrawl.dev?”
3. Observez l’IA appeler l’outil searchWeb ou scrapeWebsite
4. Suivez l’exécution de l’outil dans l’UI avec les entrées et sorties
5. Lisez l’analyse de l’IA basée sur les données collectées