> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Tools Bright Data

Le package `@mastra/brightdata` encapsule le [SDK Bright Data](https://github.com/brightdata/bright-data-sdk-node) 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()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool), qui comprend des schémas Zod complets d'entrée et de sortie.

Le Tool de recherche repose sur [SERP API](https://brightdata.com/products/serp-api) de Bright Data, et le Tool de récupération sur [Web Unlocker](https://brightdata.com/products/web-unlocker). Tous deux contournent la détection des bots et les CAPTCHA.

## Installation

**npm**:

```sh
npm install @mastra/brightdata zod
```

**pnpm**:

```sh
pnpm add @mastra/brightdata zod
```

**Yarn**:

```sh
yarn add @mastra/brightdata zod
```

**Bun**:

```sh
bun add @mastra/brightdata zod
```

## Démarrage rapide

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

```typescript
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 :

```typescript
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.

```typescript
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`

```typescript
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.

**results.link** (`string`): URL du résultat.

**results.title** (`string`): Titre du résultat.

**results.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`

```typescript
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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool)
- [Bright Data SERP API](https://brightdata.com/products/serp-api)
- [Bright Data Web Unlocker](https://brightdata.com/products/web-unlocker)
- [SDK Bright Data pour Node.js](https://github.com/brightdata/bright-data-sdk-node)