メインコンテンツへ移動

Bright Data Tools

@mastra/brightdata パッケージは、Bright Data SDK を Mastra 互換の Tool としてラップします。Web 検索と Web ページ取得のファクトリ関数を公開しています。各関数は、完全な Zod 入出力スキーマを含む createTool() で作成された Tool を返します。

検索 Tool は Bright Data の SERP API を、取得 Tool は Web Unlocker を利用します。どちらも Bot 検出と CAPTCHA を回避します。

インストール
インストールへの直接リンク

npm install @mastra/brightdata zod

クイックスタート
クイックスタートへの直接リンク

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

src/mastra/tools/index.ts
import { createBrightDataTools } from '@mastra/brightdata'

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

各 Tool を個別に作成することもできます。

src/mastra/tools/index.ts
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()
createbrightdatatoolsへの直接リンク

共有設定を使用する両方の Tool を含むオブジェクトを返します。

import { createBrightDataTools } from '@mastra/brightdata'

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

戻り値： { webSearch, webFetch }

createBrightDataSearchTool()
createbrightdatasearchtoolへの直接リンク

Bright Data の SERP API を介して Google を検索する Tool を作成します。解析済みのオーガニック検索結果を返します。

Tool ID： brightdata-search

import { createBrightDataSearchTool } from '@mastra/brightdata'

const searchTool = createBrightDataSearchTool()

入力
入力への直接リンク

query:

string
検索クエリ。

country?:

string
地域を指定した検索結果に使用する 2 文字の国コード（us や gb など）。

start?:

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

出力
出力への直接リンク

query:

string
元の検索クエリ。

results:

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

link:

string
結果の URL。

title:

string
結果のタイトル。

description:

string
結果のスニペット。

currentPage:

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

createBrightDataFetchTool()
createbrightdatafetchtoolへの直接リンク

Bright Data の Web Unlocker を介して Web ページを取得し、そのページコンテンツを Markdown として返す Tool を作成します。

Tool ID： brightdata-fetch

import { createBrightDataFetchTool } from '@mastra/brightdata'

const fetchTool = createBrightDataFetchTool()

入力
入力への直接リンク

url:

string
取得する URL。有効な HTTP または HTTPS URL である必要があります。

出力
出力への直接リンク

url:

string
入力 URL。

content:

string
Markdown 形式のページコンテンツ。

Agent の例
Agent の例への直接リンク

次の例は、検索と取得を組み合わせた調査 Agent を示しています。

src/mastra/agents/index.ts
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_TOKENBright Data API トークン。ファクトリ関数に apiKey を渡さない場合のデフォルトとして使用されます。
On this page