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

# Bright Data Tools

`@mastra/brightdata` パッケージは、[Bright Data SDK](https://github.com/brightdata/bright-data-sdk-node) を Mastra 互換の Tool としてラップします。Web 検索と Web ページ取得のファクトリ関数を公開しています。各関数は、完全な Zod 入出力スキーマを含む [`createTool()`](https://mastra.zisheng.pro/ja/reference/tools/create-tool) で作成された Tool を返します。

検索 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
```

## クイックスタート

共有設定で両方の Tool を取得するには、`createBrightDataTools()` を使用します。

```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 トークン。指定がない場合は BRIGHTDATA\_API\_TOKEN 環境変数を使用します。

`bdclient` コンストラクターがサポートする追加フィールド（`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`): 地域を指定した検索結果に使用する 2 文字の国コード（us や gb など）。

**start** (`number`): ページネーション用の結果オフセット。たとえば 10 を指定すると、10 件単位の結果の 2 ページ目を返します。

### 出力

**query** (`string`): 元の検索クエリ。

**results** (`SearchResult[]`): オーガニック検索結果。リンクまたはタイトルがない項目は除外されます。

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

**results.title** (`string`): 結果のタイトル。

**results.description** (`string`): 結果のスニペット。

**currentPage** (`number`): SERP API から返されたページ番号。上流のレスポンスで値が省略されているか、正でない値が返された場合のデフォルトは 1 です。

## `createBrightDataFetchTool()`

Bright Data の Web Unlocker を介して Web ページを取得し、そのページコンテンツを 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 トークン。ファクトリ関数に `apiKey` を渡さない場合のデフォルトとして使用されます。 |

## 関連項目

- [`createTool()`](https://mastra.zisheng.pro/ja/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)