跳至主要內容

Bright Data Tools

@mastra/brightdata 套件會將 Bright Data SDK 包裝為相容於 Mastra 的 Tool。它提供網頁搜尋與網頁擷取的 factory function。每個函式都會回傳以 createTool() 建立的 Tool，並包含完整的 Zod 輸入／輸出 schema。

搜尋 Tool 以 Bright Data 的 SERP API 為基礎，擷取 Tool 則使用 Web Unlocker。兩者都能避開 bot 偵測與 CAPTCHA。

安裝
「安裝」的直接連結

npm install @mastra/brightdata zod

快速開始
「快速開始」的直接連結

使用 createBrightDataTools() 以共用設定取得兩個 Tool：

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 } 來覆寫此值。

設定
「設定」的直接連結

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

apiKey?:

string
Bright Data API token。未設定時會使用 BRIGHTDATA_API_TOKEN 環境變數。

bdclient constructor 支援的其他欄位（例如 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
用於地理位置指定結果的雙字母國家程式碼（例如 us 或 gb）。

start?:

number
分頁的結果位移量。例如，10 會回傳每頁 10 筆結果的第二頁。

輸出
「輸出」的直接連結

query:

string
原始搜尋查詢。

results:

SearchResult[]
自然搜尋結果。缺少連結或標題的項目會被篩除。
SearchResult

link:

string
結果 URL。

title:

string
結果標題。

description:

string
結果摘要。

currentPage:

number
SERP API 回傳的頁碼。若上游回應省略此值或回傳非正數，則預設為 1。

createBrightDataFetchTool()
「createbrightdatafetchtool」的直接連結

建立一個透過 Bright Data Web Unlocker 擷取網頁，並以 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_TOKEN你的 Bright Data API token。若未將 apiKey 傳給 factory function，則預設使用此值。
On this page