跳至主要內容

Bright Data tools

@mastra/brightdata 套件將 Bright Data SDK 包裝成與 Mastra 相容的 Tool。它公開用於網絡搜尋和網頁擷取的工廠函數。每個函數都會傳回一個以 createTool() 建立並包含完整 Zod 輸入／輸出 Schema 的 Tool。

搜尋 Tool 由 Bright Data 的 SERP API 支援，而擷取 Tool 則由 Web Unlocker 支援。兩者都可繞過機械人偵測和 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 } 來覆寫。

配置
配置 的直接連結

所有工廠函數都接受來自 @brightdata/sdk 的 BrightDataClientOptions：

apiKey?:

string
Bright Data API token。回退至 BRIGHTDATA_API_TOKEN 環境變數。

你可以透過同一個 options 物件傳入 bdclient 建構函數支援的其他欄位（例如 timeout、webUnlockerZone、serpZone 和 rateLimit）。

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 傳入工廠函數時，會用作預設值。
On this page