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

# Bright Data tools

`@mastra/brightdata` 包将 [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) 封装为与 Mastra 兼容的 Tool。它提供网页搜索和网页抓取的工厂函数。每个函数都会返回一个通过 [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool) 创建的 Tool，其中包含完整的 Zod 输入/输出 Schema。

搜索 Tool 由 Bright Data 的 [SERP API](https://brightdata.com/products/serp-api) 提供支持，抓取 Tool 则由 [Web Unlocker](https://brightdata.com/products/web-unlocker) 提供支持。两者都能绕过机器人检测和 CAPTCHA。

## 安装

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

## 快速开始

使用 `createBrightDataTools()` 通过共享配置获取这两个 Tool：

```typescript
import { createBrightDataTools } from '@mastra/brightdata'

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

也可以分别创建每个 Tool：

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

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

默认情况下，所有 Tool 都会从环境中读取 `BRIGHTDATA_API_TOKEN`。你可以显式传入 `{ apiKey }` 来覆盖它。

## 配置

所有工厂函数都接受来自 `@brightdata/sdk` 的 `BrightDataClientOptions`：

**apiKey** (`string`): Bright Data API token。未提供时使用 BRIGHTDATA\_API\_TOKEN 环境变量。

`bdclient` 构造函数支持的其他字段（例如 `timeout`、`webUnlockerZone`、`serpZone` 和 `rateLimit`）也可以通过同一个选项对象传入。

## `createBrightDataTools()`

返回一个对象，其中包含使用共享配置的两个 Tool。

```typescript
import { createBrightDataTools } from '@mastra/brightdata'

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

**返回：** `{ webSearch, webFetch }`

## `createBrightDataSearchTool()`

创建一个通过 Bright Data SERP API 搜索 Google 的 Tool。返回解析后的自然搜索结果。

**Tool ID：** `brightdata-search`

```typescript
import { createBrightDataSearchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()
```

### 输入

**query** (`string`): 搜索查询。

**country** (`string`): 用于按地理位置定向结果的两位国家/地区代码（例如 us 或 gb）。

**start** (`number`): 用于分页的结果偏移量。例如，10 会返回每页 10 条结果时的第二页。

### 输出

**query** (`string`): 原始搜索查询。

**results** (`SearchResult[]`): 自然搜索结果。缺少链接或标题的条目会被过滤掉。

**results.link** (`string`): 结果 URL。

**results.title** (`string`): 结果标题。

**results.description** (`string`): 结果摘要。

**currentPage** (`number`): SERP API 返回的页码。如果上游响应省略该值或返回非正数，则默认为 1。

## `createBrightDataFetchTool()`

创建一个通过 Bright Data Web Unlocker 抓取网页，并以 Markdown 格式返回页面内容的 Tool。

**Tool ID：** `brightdata-fetch`

```typescript
import { createBrightDataFetchTool } from '@mastra/brightdata'

const fetchTool = createBrightDataFetchTool()
```

### 输入

**url** (`string`): 要抓取的 URL。必须是有效的 HTTP 或 HTTPS URL。

### 输出

**url** (`string`): 输入 URL。

**content** (`string`): Markdown 格式的页面内容。

## Agent 示例

以下示例演示了一个结合搜索与抓取功能的研究 Agent：

```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,
  },
})
```

## 环境变量

| 变量                     | 描述                                                 |
| ---------------------- | -------------------------------------------------- |
| `BRIGHTDATA_API_TOKEN` | 你的 Bright Data API token。未向工厂函数传入 `apiKey` 时用作默认值。 |

## 相关内容

- [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool)
- [Bright Data SERP API](https://brightdata.com/products/serp-api)
- [Bright Data Web Unlocker](https://brightdata.com/products/web-unlocker)
- [Bright Data SDK for Node.js](https://github.com/brightdata/bright-data-sdk-node)