> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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/zh-HK/reference/tools/create-tool) 建立並包含完整 Zod 輸入／輸出 Schema 的 Tool。

搜尋 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 環境變數。

你可以透過同一個 options 物件傳入 `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/zh-HK/reference/tools/create-tool)
- [Bright Data SERP API](https://brightdata.com/products/serp-api)
- [Bright Data Web Unlocker](https://brightdata.com/products/web-unlocker)
- [適用於 Node.js 的 Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node)