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

# Bright Data Tools

`@mastra/brightdata` 套件會將 [Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) 包裝為相容於 Mastra 的 Tool。它提供網頁搜尋與網頁擷取的 factory function。每個函式都會回傳以 [`createTool()`](https://mastra.zisheng.pro/zh-TW/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)。兩者都能避開 bot 偵測與 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 }` 來覆寫此值。

## 設定

所有 factory function 都接受來自 `@brightdata/sdk` 的 `BrightDataClientOptions`：

**apiKey** (`string`): Bright Data API token。未設定時會使用 BRIGHTDATA\_API\_TOKEN 環境變數。

`bdclient` constructor 支援的其他欄位（例如 `timeout`、`webUnlockerZone`、`serpZone` 與 `rateLimit`）也能透過同一個 options 物件傳入。

## `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` 傳給 factory function，則預設使用此值。 |

## 相關內容

- [`createTool()`](https://mastra.zisheng.pro/zh-TW/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 Node.js SDK](https://github.com/brightdata/bright-data-sdk-node)