Intégrer Mastra à Bright Data pour des agents IA conscients du web

Dans ce tutoriel, vous apprendrez :

• Ce qu’est Mastra en tant que solution de création d’agents IA et ce qu’il apporte.
• Pourquoi les agents IA Mastra deviennent bien plus puissants lorsqu’ils peuvent explorer le web.
• Comment créer un agent IA Mastra avec accès au web grâce à l’intégration des outils Bright Data.
• (Optionnel) Comment connecter Mastra au Bright Data Web MCP.

Plongeons dans le vif du sujet !

Qu’est-ce que Mastra ?

Mastra est un framework TypeScript moderne pour créer des agents et applications alimentés par l’IA. Il fournit une API pour construire et gérer des agents, des workflows, le RAG, la mémoire, le MCP et l’observabilité dans un système unifié.

Mastra est open source et largement adopté, avec plus de 23 800 étoiles GitHub. Cela témoigne d’une forte confiance de la communauté et d’une croissance rapide de l’écosystème.

Les principales fonctionnalités offertes par la solution sont :

• Agents : créez des agents IA autonomes qui raisonnent, utilisent des outils et itèrent pour accomplir des tâches complexes définies par l’utilisateur.
• Workflows : orchestrez des processus en plusieurs étapes à l’aide d’une exécution structurée basée sur des graphes, avec des embranchements, des étapes parallèles et une logique déterministe contrôlée.
• RAG : connectez les agents à des sources de connaissances externes pour des réponses ancrées et contextualisées via des pipelines de génération augmentée par récupération.
• Mémoire : maintenez le contexte à court et long terme pour que les agents puissent se souvenir des conversations et améliorer la continuité entre les interactions.
• Outils : étendez les capacités des agents avec des API externes, des fonctions et des intégrations, permettant des actions réelles et un accès dynamique aux données.
• MCP : intégrez des serveurs Model Context Protocol pour exposer et consommer des outils, des agents et des ressources structurées à travers les systèmes.
• Observabilité : suivez, évaluez et déboguez le comportement des agents à l’aide de journaux, de traces, de métriques et d’outils d’évaluation des performances.

Pour en savoir plus, consultez la documentation officielle.

Pourquoi étendre les agents IA Mastra avec des outils de recherche web et de scraping

Mastra est un framework riche pour créer des applications et agents pilotés par l’IA. Cependant, même les systèmes d’IA bien conçus peuvent dériver ou produire des résultats de mauvaise qualité lorsqu’ils s’appuient sur des informations obsolètes ou incomplètes.

C’est une limitation fondamentale des LLM, qui sont entraînés sur des données statiques et manquent donc de conscience en temps réel. Par conséquent, ils peuvent halluciner ou prendre des décisions basées sur un contexte obsolète, réduisant la précision et la fiabilité.

Pour résoudre ce problème, les applications d’IA ont besoin d’accéder à une infrastructure de données web en temps réel. C’est précisément là qu’intervient Bright Data !

La solution : les outils Bright Data pour Mastra

Bright Data prend en charge Mastra via les outils officiels suivants :

• webSearch : effectue des recherches web sur des moteurs comme Google, Bing, Yandex et autres. Il renvoie des résultats SERP structurés en format JSON, prêts pour les agents IA. Propulsé par l’API SERP de Bright Data.
• webFetch : récupère le contenu de n’importe quelle page web via l’API Web Unlocker de Bright Data. Il contourne les protections anti-bot et les systèmes CAPTCHA pour accéder aux données web en direct depuis n’importe quel domaine.

Grâce à cette intégration open-source, les applications Mastra accèdent à une infrastructure de données web de niveau production. Cela permet aux agents de découvrir de nouvelles sources, de récupérer des informations en temps réel et de combler l’écart entre les données d’entraînement et la réalité actuelle.

Ce qui distingue Bright Data, c’est son vaste réseau mondial de plus de 400 millions d’IP résidentielles couvrant 195 pays. Il permet une simultanéité illimitée tout en maintenant une disponibilité de 99,99 % et un taux de succès de 99,95 %.

Comment créer un agent IA Mastra connecté à Bright Data pour l’accès aux données web

Cette section étape par étape vous guidera dans la configuration d’un nouvel agent IA Mastra intégré aux outils Bright Data.

Suivez les instructions ci-dessous !

Prérequis

Pour suivre ce tutoriel, assurez-vous d’avoir :

• Git installé localement.
• Node.js v22.13.0 ou version ultérieure installée (la dernière version LTS est recommandée).
• Une clé API d’un fournisseur de modèles d’IA pris en charge par Mastra (dans ce cas, nous utiliserons une clé API OpenAI).
• Un compte Bright Data avec une clé API configurée. Pour créer un compte Bright Data et configurer une clé API, suivez le guide de la documentation officielle.

Étape #1 : Initialiser un nouveau projet Mastra

Remarque : si vous disposez déjà d’un projet Mastra, vous pouvez ignorer cette étape.

Commencez par créer un nouveau projet Mastra appelé mastra-bright-data-web-access-agent à l’aide de l’utilitaire create-mastra :

npx create-mastra@latest mastra-bright-data-web-access-agent

Lorsque vous y êtes invité, sélectionnez votre fournisseur d’IA.

Dans ce cas, choisissez « OpenAI », puis sélectionnez l’option pour saisir une clé API manuellement. Collez votre clé API OpenAI lorsque vous y êtes invité :

Ensuite, vous serez invité à activer l’observabilité Mastra. Choisissez selon votre préférence, puis continuez avec les invites de configuration restantes.

Une fois la configuration terminée, naviguez dans le répertoire de votre projet :

cd mastra-bright-data-web-access-agent

Vous devriez maintenant voir une structure de projet similaire à celle-ci :

mastra-bright-data-web-access-agent/    
├── .agents/           # Répertoire interne Mastra pour les agent skills, etc.
├── node_modules/
└── src/
│    └── mastra/
│        ├── index.ts              # Point d'entrée qui initialise la configuration Mastra
│        ├── agents/
│        │   └── weather-agent.ts  # Définit l'agent IA météo par défaut
│        ├── scorers/
│        │   └── weather-scorer.ts  # Logique de scoring pour évaluer les sorties de l'agent
│        ├── tools/
│        │   └── weather-tool.ts    # Intégrations d'outils externes utilisés par l'agent
│        └── workflows/
│            └── weather-workflow.ts  # Logique combinant outils et agents
├── .env               # Variables d'environnement (clés API, secrets, etc.)
├── .gitignore            
├── AGENTS.md          # Documentation décrivant les agents disponibles et leur comportement
├── package-lock.json     
├── package.json          
├── README.md          # Documentation principale du projet
└── skills-lock.json  

Le dossier contient le projet d’agent IA météo Mastra par défaut. Il s’agit d’un modèle minimal conçu pour démontrer comment créer des agents, des outils, des scorers et des workflows dans Mastra.

Explorez les fichiers et familiarisez-vous avec eux. Par exemple, ouvrez le fichier .env. Vous devriez voir votre clé API OpenAI configurée lors de l’installation. Envisagez également de lancer l’agent avec :

npm run dev

Bien joué ! Votre projet Mastra est maintenant configuré et prêt à être étendu avec les outils Bright Data.

Étape #2 : Installer et configurer les outils Bright Data

Commencez par installer les outils Mastra Bright Data ainsi que la dépendance zod requise :

npm install @mastra/brightdata zod

Le package @mastra/brightdata encapsule le SDK JavaScript de Bright Data et expose ses méthodes de scraping et de recherche web comme outils compatibles Mastra.

Le SDK JavaScript de Bright Data nécessite la variable d’environnement BRIGHTDATA_API_TOKEN pour fonctionner. Ajoutez-la à votre fichier .env :

BRIGHTDATA_API_TOKEN="<YOUR_BRIGHT_DATA_API_KEY>"

Remplacez l’espace réservé <YOUR_BRIGHT_DATA_API_KEY> par votre clé API Bright Data réelle. La clé API est utilisée par le SDK pour authentifier les requêtes vers les API Bright Data.

Une fois configurés, les outils @mastra/brightdata pourront se connecter à votre compte Bright Data. Lors de la première utilisation, le SDK Bright Data provisionne automatiquement les API requises dans votre tableau de bord Bright Data, y compris les zones d’API Web Unlocker et d’API SERP requises :

Étape #3 : Ajouter les outils Bright Data

À ce stade, vous avez installé les outils Mastra Bright Data. Vous devez maintenant les configurer et les exposer à votre agent IA.

Pour ce faire, créez un nouveau fichier web-access.ts dans src/mastra/tools/ :

// src/mastra/tools/web-access.ts

import { createBrightDataTools } from '@mastra/brightdata'

// créez les outils de recherche web et de récupération web avec les options du client BrightData
export const { webSearch, webFetch } = createBrightDataTools({
  verbose: true, // activer la journalisation détaillée pour le débogage
})

Ce code appelle createBrightDataTools() du package @mastra/brightdata avec une configuration personnalisée. Notez que la clé API Bright Data requise est automatiquement lue depuis la variable d’environnement BRIGHTDATA_API_TOKEN. De même, les noms de zones sont automatiquement déduits ou créés par défaut. Si nécessaire, vous pouvez configurer explicitement la clé API et les zones via des options supplémentaires dans createBrightDataTools().

La fonction createBrightDataTools() génère deux outils compatibles Mastra :

• webSearch : utilise l’API SERP de Bright Data pour activer les capacités de recherche web de votre agent IA.
• webFetch : appelle l’API Web Unlocker de Bright Data pour récupérer et scraper du contenu depuis n’importe quel site web.

Remarque : vous pouvez également créer et configurer ces outils individuellement avec createBrightDataSearchTool() et createBrightDataFetchTool(). C’est l’approche recommandée si vous préférez un contrôle plus granulaire.

L’exportation de ces outils vous permet de les importer ultérieurement dans la définition de votre agent pour activer l’accès web. Parfait ! Les outils Bright Data sont maintenant prêts à être utilisés dans un agent IA Mastra.

Étape #4 : Créer l’agent IA d’accès web

Il est maintenant temps de créer un agent Mastra connecté aux outils Bright Data. Pour ce faire, ajoutez un fichier web-access-agent.ts dans le chemin src/mastra/agents/ et remplissez-le comme suit :

// src/mastra/agents/web-access-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { webFetch, webSearch } from '../tools/web-access'

export const webAccessAgent = new Agent({
  id: 'web-access-agent',
  name: 'Web Access Agent',
  instructions: `
    You are a helpful, general-purpose assistant with Bright Data web access capabilities.

    Goals:
    - Answer user questions by combining reasoning with fresh, tool-based information.
    - Prefer tools when information may be outdated or when factual accuracy is required.
    - Clearly reference tool outputs so users can trace where information comes from.

    Tool usage guidelines:
    - Start with the webSearch tool to gather relevant sources and context.
    - Use the webFetch tool to retrieve and analyze detailed content from specific pages.
`,
  model: 'openai/gpt-5-mini',
  tools: {
    webFetch,
    webSearch,
  },
  memory: new Memory(),
})

Ce snippet définit un agent IA Mastra avec des capacités de recherche web et de scraping supportées par Bright Data. Il permet à l’agent de récupérer des informations en ligne fraîches et de scraper des pages web. Notez qu’il inclut également le support de la mémoire, afin que l’agent puisse maintenir le contexte entre les interactions.

Fantastique ! L’agent IA Mastra propulsé par Bright Data est prêt.

Étape #5 : Ajouter l’agent à l’index

La dernière étape pour compléter l’application Mastra est d’enregistrer le webAccessAgent dans le fichier src/mastra/index.ts :

// src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import { Observability, MastraStorageExporter, MastraPlatformExporter, SensitiveDataFilter } from '@mastra/observability'
import { webAccessAgent } from './agents/web-access-agent'

export const mastra = new Mastra({
  agents: { webAccessAgent },
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    }
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(),
          new MastraPlatformExporter(),
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(),
        ],
      },
    },
  }),
})

Le snippet ci-dessus initialise une application Mastra en enregistrant l’agent IA Web Access précédemment défini. Il configure ensuite un stockage composite afin que la mémoire de l’agent soit persistée dans un fichier mastra.db local à l’aide d’un store LibSQL. Il active également la journalisation structurée via Pino et configure l’observabilité avec des exporteurs et un filtrage des données sensibles pour la surveillance et la traçabilité.

Remarque : pour garder votre application Mastra légère, envisagez de supprimer les outils, workflows et scorers météo initiaux.

Étape #6 : Tester l’agent d’accès web

Lancez votre application Mastra avec :

npm run dev

Vous devriez voir une sortie similaire à celle-ci :

Cela indique que le serveur Mastra local fonctionne à http://localhost:4111. Ouvrez cette URL dans votre navigateur, et vous devriez voir le tableau de bord Mastra :

Naviguez vers la section « Outils », et vous verrez les deux outils Bright Data exposés depuis src/mastra/tools/web-access.ts :

Ensuite, allez sur la page Agents et cliquez sur l’entrée « Web Access Agent » :

Cela ouvrira l’interface de chat de l’agent, où vous pouvez interagir avec lui. Pour vérifier les capacités d’exploration web de l’agent, lancez une invite comme :

Recherche les dernières actualités boursières sur Google. Sélectionne les articles les plus pertinents, extrais et analyse leur contenu, puis renvoie un rapport Markdown structuré résumant les informations clés, avec des liens pour en savoir plus.

Lancez-le et vous devriez voir une sortie comme celle-ci :

Notez que Mastra a appelé les outils de recherche web trois fois pour effectuer des requêtes Google pertinentes. Ceux-ci renvoient des résultats SERP structurés en JSON, scrapés depuis Google :

À partir de ces résultats, l’agent sélectionne les liens les plus pertinents et utilise webFetch pour scraper leur contenu. Enfin, il agrège tout dans un rapport Markdown structuré résumant les actualités boursières du jour.

Et voilà ! Grâce à l’intégration Bright Data, votre agent IA Mastra dispose désormais de capacités de recherche web et de scraping de niveau entreprise, permettant des réponses mieux ancrées. Essayez différentes invites et testez tous les scénarios et cas d’usage pris en charge !

[Bonus] Connecter un agent IA Mastra au Bright Data Web MCP

N’oubliez pas que Mastra prend également en charge l’intégration MCP. Vous pouvez donc connecter votre agent IA Mastra au Bright Data Web MCP.

Le serveur Web MCP fournit accès à plus de 70 outils pour la recherche web, le scraping, l’extraction de données, la récupération de flux de données et l’automatisation du navigateur. N’oubliez pas qu’il est accompagné d’un forfait gratuit (5 000 requêtes/mois).

Pour utiliser MCP dans Mastra, installez d’abord la dépendance requise :

npm install @mastra/mcp@latest

Ensuite, ajoutez un fichier src/mastra/mcp/bright-data-mcp-client.ts contenant :

// src/mastra/mcp/bright-data-mcp-client.ts

import { MCPClient } from '@mastra/mcp'

export const brightDataMcpClient = new MCPClient({
  id: 'bright-data-mcp-client',
  servers: {
    'bright-data': {
      command: 'npx',
      args: ['-y', '@brightdata/mcp'],
      env: {
       'API_TOKEN': process.env.BRIGHTDATA_API_TOKEN || '',
       'PRO_MODE': 'true' // supprimer pour activer le mode gratuit
      },
    },
  },
})

Cela lance le MCP Bright Data via le package @brightdata/mcp. Le serveur authentifie la connexion à votre compte à l’aide de la variable d’environnement API_TOKEN, qui doit être définie sur votre clé API Bright Data via BRIGHTDATA_API_TOKEN dans le fichier .env.

Notez que le paramètre 'PRO_MODE': 'true' est optionnel. Lorsqu’il est activé, il donne accès à l’ensemble complet de 70+ outils, mais peut également entraîner des frais basés sur l’utilisation.

Dans votre fichier d’agent Mastra, utilisez les outils d’un serveur MCP en important le MCPClient et en appelant .listTools() dans le paramètre tools :

// src/mastra/agents/web-access-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { brightDataMcpClient } from '../mcp/bright-data-mcp-client'

export const webAccessAgent = new Agent({
  id: 'web-access-agent',
  name: 'Web Access Agent',
  // omis pour plus de concision...
  tools: {
    ...await brightDataMcpClient.listTools(),
  },
  memory: new Memory(),
})

Si vous lancez maintenant l’application Mastra, vous verrez les outils Bright Data Web MCP :

Web MCP expose plus de 70 outils en mode Pro, ou les 5 outils disponibles en mode Rapid (niveau gratuit).

Mission accomplie ! Votre agent IA Mastra est maintenant connecté à l’infrastructure Bright Data via MCP.

Conclusion

Dans cet article de blog, vous avez compris ce qu’est Mastra et les fonctionnalités clés qu’il offre. En particulier, vous avez vu comment et pourquoi l’étendre à l’aide des outils officiels Bright Data ou via Web MCP.

Cette intégration amène les agents Mastra à un tout nouveau niveau. Les agents IA peuvent désormais effectuer des recherches web, découvrir et extraire des données structurées, et interagir avec des sites web réels.

Créez un compte Bright Data gratuit dès aujourd’hui et commencez à intégrer nos outils de données web prêts pour l’IA !