Tools Bright Data

Le package @mastra/brightdata encapsule le SDK Bright Data sous la forme de Tools compatibles avec Mastra. Il expose des fonctions de fabrique pour la recherche et la récupération web. Chaque fonction renvoie un Tool créé avec createTool(), qui comprend des schémas Zod complets d'entrée et de sortie.

Le Tool de recherche repose sur SERP API de Bright Data, et le Tool de récupération sur Web Unlocker. Tous deux contournent la détection des bots et les CAPTCHA.

Installation

npm

npm install @mastra/brightdata zod

pnpm

pnpm add @mastra/brightdata zod

Yarn

yarn add @mastra/brightdata zod

Bun

bun add @mastra/brightdata zod

Démarrage rapide

Utilisez createBrightDataTools() pour obtenir les deux Tools avec une configuration commune :

src/mastra/tools/index.ts

import { createBrightDataTools } from '@mastra/brightdata'

const { webSearch, webFetch } = createBrightDataTools()
// Or pass an explicit API key:
// const { webSearch, webFetch } = createBrightDataTools({ apiKey: 'brd-...' })

Chaque Tool peut également être créé séparément :

src/mastra/tools/index.ts

import { createBrightDataSearchTool, createBrightDataFetchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()
const fetchTool = createBrightDataFetchTool({ apiKey: 'brd-...' })

Par défaut, tous les Tools lisent BRIGHTDATA_API_TOKEN dans l'environnement. Vous pouvez transmettre explicitement { apiKey } pour remplacer cette valeur.

Configuration

Toutes les fonctions de fabrique acceptent BrightDataClientOptions de @brightdata/sdk :

apiKey?:

string

Token d'API Bright Data. Utilise par défaut la variable d'environnement BRIGHTDATA_API_TOKEN.

Les champs supplémentaires pris en charge par le constructeur bdclient (tels que timeout, webUnlockerZone, serpZone et rateLimit) peuvent être transmis au moyen du même objet d'options.

createBrightDataTools()

Renvoie un objet contenant les deux Tools avec une configuration commune.

import { createBrightDataTools } from '@mastra/brightdata'

const tools = createBrightDataTools({ apiKey: 'brd-...' })
// tools.webSearch, tools.webFetch

Renvoie : { webSearch, webFetch }

createBrightDataSearchTool()

Crée un Tool qui effectue des recherches sur Google au moyen de SERP API de Bright Data. Renvoie les résultats organiques analysés.

Identifiant du Tool : brightdata-search

import { createBrightDataSearchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()

Entrée

query:

string

Requête de recherche.

country?:

string

Code pays à deux lettres pour les résultats géociblés (par exemple, us ou gb).

start?:

number

Décalage des résultats pour la pagination. Par exemple, 10 renvoie la deuxième page de 10 résultats.

Sortie

query:

string

Requête de recherche originale.

results:

SearchResult[]

Résultats de recherche organiques. Les entrées dépourvues de lien ou de titre sont filtrées.

SearchResult

link:

string

URL du résultat.

title:

string

Titre du résultat.

description:

string

Extrait du résultat.

currentPage:

number

Numéro de page renvoyé par SERP API. La valeur par défaut est 1 lorsque la réponse en amont omet cette valeur ou renvoie une valeur non positive.

createBrightDataFetchTool()

Crée un Tool qui récupère une page web au moyen de Web Unlocker de Bright Data et renvoie son contenu au format Markdown.

Identifiant du Tool : brightdata-fetch

import { createBrightDataFetchTool } from '@mastra/brightdata'

const fetchTool = createBrightDataFetchTool()

Entrée

url:

string

URL à récupérer. Doit être une URL HTTP ou HTTPS valide.

Sortie

url:

string

URL d'entrée.

content:

string

Contenu de la page au format Markdown.

Exemple avec un Agent

L'exemple suivant présente un Agent de recherche qui combine la recherche et la récupération :

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createBrightDataTools } from '@mastra/brightdata'

const { webSearch, webFetch } = createBrightDataTools()

const agent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'You are a research assistant. Use the search tool to find relevant pages, then use the fetch tool to read full Markdown content from the best results.',
  tools: {
    webSearch,
    webFetch,
  },
})

Variables d'environnement

Variable	Description
BRIGHTDATA_API_TOKEN	Votre token d'API Bright Data. Utilisé par défaut lorsque apiKey n'est pas transmis à une fonction de fabrique.

Voir aussi

• createTool()
• Bright Data SERP API
• Bright Data Web Unlocker
• SDK Bright Data pour Node.js