跳到主要内容

Bright Data tools

@mastra/brightdata 包将 Bright Data SDK 封装为与 Mastra 兼容的 Tool。它提供网页搜索和网页抓取的工厂函数。每个函数都会返回一个通过 createTool() 创建的 Tool，其中包含完整的 Zod 输入/输出 Schema。

搜索 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 环境变量。

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