尧图网页设计 
Mastra 集成 Bright Data为 AI Agent 打造可穿透反爬的搜索与网页抓取工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/brightdata是 Mastra 官方生态中对接 Bright Data 的集成包为 Agent 提供webSearchSERP 搜索与webFetch网页抓取两个开箱即用的工具底层由 Bright Data 的 SERP API 与 Web Unlocker 驱动可绕过机器人检测与 CAPTCHA适合需要实时检索网页、读取被普通爬虫拦截的站点的研究型 Agent。读完本文你将掌握该包的安装、配置、两个工具的参数语义以及其在 Mastra Agent 中的接入方式与底层调用机制。一、这个集成解决什么问题普通爬虫或搜索引擎 API 在面对 Google 搜索结果页以及启用了 Cloudflare、Akamai 等反爬保护的目标网站时经常返回验证码页面或直接拒绝访问。mastra/brightdata的思路是把这两件脏活外包给 Bright DataSERP API代理 Google 搜索请求返回解析好的自然搜索结果链接、标题、摘要并对搜索结果应用 Bright Data 的代理/反检测能力Web Unlocker抓取任意 URL自动处理机器人检测、CAPTCHA、指纹识别等反爬手段把页面内容以 Markdown 形式返回给 Agent。因此这两个工具特别适合先搜到页面、再读取正文的两段式研究流程。从包描述见 package.json与 README 可以确认这正是该集成的核心定位。二、安装与前置准备在 Mastra 项目中安装npm install mastra/brightdata包以mastra/core1.0.0-0 2.0.0-0和zod3.0.0为 peer 依赖要求 Node.js22.13.0并作为 ESM 模块发布type: module同时提供require的 CJS 产物见 package.json。使用前需要两样东西Bright Data API Token从 Bright Data 控制台获取Zone区域配置工具默认使用两个内置 zone——SERP 搜索默认sdk_serpWeb Unlocker 抓取默认sdk_unlocker定义见 client.ts一般无需改动。三、快速开始把搜索与抓取能力挂到 Agent 上README 给出的核心用法是调用createBrightDataTools()一次性拿到两个工具然后注入 Agent 的toolsimport { createBrightDataTools } from mastra/brightdata; import { Agent } from mastra/core/agent; const { webSearch, webFetch } createBrightDataTools(); export const researchAgent new Agent({ id: research-agent, name: Research Agent, model: openai/gpt-5.6-sol, instructions: Search for relevant pages, then fetch the best sources before answering., tools: { webSearch, webFetch }, });其中createBrightDataTools(config?)的源码实现非常简单见 tools.tsexport function createBrightDataTools(config?: BrightDataClientOptions) { return { webSearch: createBrightDataSearchTool(config), webFetch: createBrightDataFetchTool(config), }; }也就是说它等价于分别调用createBrightDataSearchTool()与createBrightDataFetchTool()config会被透传给底层两个工具。也可以在同一个 Agent 里只挂其中一个工具import { createBrightDataSearchTool } from mastra/brightdata; export const searchOnlyAgent new Agent({ id: search-only-agent, name: Search Only Agent, model: openai/gpt-5.6-sol, instructions: Always use the web search tool to answer questions., tools: { webSearch: createBrightDataSearchTool() }, });3.1 模型说明示例中的model字段如openai/gpt-5.6-sol为 README 中的示意值实际应替换为你账户中可用的模型标识如anthropic/claude-sonnet-4-6等并保证对应的模型提供方凭证已配置。四、工具一webSearchGoogle 搜索工具 ID 为brightdata-search功能描述为搜索 Google 并返回解析后的自然搜索结果link/title/description底层走 SERP API 绕过机器人检测支持国家与语言定向以及基于结果偏移的分页见 search.ts。4.1 输入参数inputSchema参数类型必填约束与默认值说明querystring是—搜索关键词会被trim()后作为q参数countrystring否两位字母代码如us、gb不匹配则校验失败用于地理定向映射到 Google 的gl参数languagestring否两位字母代码如en、es、fr不匹配则校验失败本地化搜索结果语言映射到hl参数默认enstartnumber否非负整数结果偏移量用于分页如10表示取第 2 页的 10 条结果映射到start参数输入校验由 search.ts 中的 zod schema 完成country与language都必须匹配/^[a-z]{2}$/i两位字母start必须为int().nonnegative()。4.2 输出结构outputSchema{ query: string; // 原始查询词 results: Array{ // 解析后的自然搜索结果 link: string; // 结果 URL title: string; // 结果标题 description: string; // 结果摘要 }; currentPage: number; // 当前页号缺失或非法时回退为 1 }4.3 底层请求如何构造webSearch执行时会调用客户端client.search.google(query, { country, language, start })。从源码看请求 URL 是这样拼出来的client.ts 的buildGoogleSearchUrl目标为https://www.google.com/search默认format为json时追加brd_json1请求 Bright Data 返回结构化 JSONSERP以便工具解析出organic数组hl恒为语言参数默认engl仅在国家参数存在时设置start仅在有分页需求时设置请求体以format: json、method: GET、zone默认sdk_serp发送。搜索测试见 search.test.ts验证了完整映射query→q、country→gl、language→hl、start→start也验证了最小输入仅query时 URL 只含q与hlen不带gl/start。解析逻辑会把响应中的organic数组过滤为{ link, title, description }列表缺失link或title的条目会被丢弃响应缺失organic时结果为空数组current_page非法0 或缺失时回退为1。这些边界行为均有对应测试覆盖见 search.test.ts。五、工具二webFetch网页抓取工具 ID 为brightdata-fetch功能描述为抓取网页并返回 Markdown 内容底层走 Web Unlocker可绕过机器人检测与 CAPTCHA包括普通爬虫无法访问的页面见 fetch.ts。5.1 输入与输出// 输入 { url: string } // 必须为合法 URLzod 的 z.string().url() // 输出 { url: string; content: string } // content 为页面的 Markdown 内容5.2 底层请求如何构造webFetch执行时调用client.scrapeUrl(input.url, { dataFormat: markdown })最终请求体为fetch.test.ts 断言了精确的请求体{ data_format: markdown, format: raw, method: GET, url: https://example.com, zone: sdk_unlocker }注意与搜索工具的差异抓取走raw格式返回原始文本而不是 JSON 解析data_format为markdownzone 默认sdk_unlocker。六、配置详解客户端选项、环境变量与默认值两个工具以及createBrightDataTools()都接受可选的BrightDataClientOptions见 client.ts配置项类型默认值说明apiKeystring取BRIGHTDATA_API_TOKEN环境变量无则抛出Bright Data API token is requiredtimeoutnumber120_000120 秒请求超时非正数或非有限数时回退默认值serpZonestring取BRIGHTDATA_SERP_ZONE再回退sdk_serp搜索请求使用的 zonewebUnlockerZonestring取BRIGHTDATA_WEB_UNLOCKER_ZONE再回退sdk_unlocker抓取请求使用的 zone6.1 配置优先级从 client.ts 的实现看优先级为显式配置 环境变量 内置默认值const apiKey config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN; const serpZone config?.serpZone ?? process.env.BRIGHTDATA_SERP_ZONE ?? DEFAULT_SERP_ZONE; const webUnlockerZone config?.webUnlockerZone ?? process.env.BRIGHTDATA_WEB_UNLOCKER_ZONE ?? DEFAULT_WEB_UNLOCKER_ZONE;客户端测试见 client.test.ts逐一验证了无 token 时报错、config 优先于环境变量、zone 可分别通过 config 或环境变量覆盖。6.2 显式传参示例import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools({ apiKey: process.env.BRIGHTDATA_API_TOKEN, serpZone: my_custom_serp_zone, webUnlockerZone: my_custom_unlocker_zone, timeout: 60_000, });也可以只传一部分例如只覆盖serpZone而让抓取继续走默认 zone。6.3 环境变量清单export BRIGHTDATA_API_TOKENyour_api_token export BRIGHTDATA_SERP_ZONEsdk_serp # 可选 export BRIGHTDATA_WEB_UNLOCKER_ZONEsdk_unlocker # 可选七、底层原理一次请求的完整链路该集成不再依赖brightdata/sdk运行时客户端而是用标准fetch直连 Bright Data REST 接口详见 client.ts 与 changelog 中 #16630 的说明——这一改造同时修复了 Bun 环境下的兼容问题。一次调用链路如下构造请求体toRequestBody()组装{ url, zone, format, method }搜索默认format: json抓取默认format: raw并带上data_format: markdown发起请求requestBrightData()向https://api.brightdata.com/request发送POST请求头为Authorization: Bearer apiKey与Content-Type: application/json超时控制用AbortControllersetTimeout实现超时后抛出Request timed out after msms错误映射401/403→invalid API key or insufficient permissions400→bad request: 响应文本其他非 2xx →request failed with status status: 响应文本响应解析format: json时把响应文本JSON.parse后返回否则原样返回文本scrapeUrl对非字符串响应会JSON.stringify清理工具执行完毕后调用closeClient()做 best-effort 清理且保证close()抛错也不会掩盖主流程错误见 client.ts 的closeClient与 client.test.ts。八、搜索参数的语言校验细节client.search.google()在发请求前还会多做两步防御见 client.tslanguage必须匹配/^[a-z]{2}$/i否则直接抛错且不发请求测试以1_为例验证不会打到网络合法时统一toLowerCase()归一化如EN→en保证hlen这类 URL 参数大小写一致。此外只有format为json时才追加brd_json1请求方若显式指定format: raw则可拿到真实的原始 SERP 文本见 client.test.ts。九、测试与验证方式该集成自带完整 vitest 测试套件位于 integrations/brightdata/src/tests可在本地运行cd integrations/brightdata pnpm test测试覆盖了四个层面tools.test.tscreateBrightDataTools返回两个工具且 ID、描述、输入/输出 schema 齐全client.test.tsAPI key 来源与优先级、zone 覆盖、语言校验与归一化、brd_json逻辑、401 错误映射、closeClient行为search.test.ts参数映射、最小输入、organic缺失/脏数据处理、current_page回退、错误透传fetch.test.ts请求体精确断言data_format: markdown、zone: sdk_unlocker、错误透传。十、实战建议与注意事项两段式研究流程在 Agent 的instructions中明确先用webSearch找到候选页面再用webFetch读取正文再作答能让模型按序使用工具减少盲目抓取分页技巧start每次递增 1010、20…结合输出里的currentPage可以设计多轮深度搜索的工作流超时调整Web Unlocker 处理复杂反爬页面可能耗时较长默认 120 秒通常够用若你的场景页面较轻可通过timeout收紧以降低等待zone 自定义如果你在 Bright Data 控制台创建了专属 zone用于配额统计或独立配置务必通过serpZone/webUnlockerZone或对应环境变量覆盖默认值否则请求会落在默认 zone 上凭证安全优先使用环境变量注入BRIGHTDATA_API_TOKEN避免把 token 硬编码进源码或提交到仓库错误处理工具的错误已归一化为可读信息key 无效、400 请求错误、超时等在 Agent 上层做try/catch或重试时可直接依赖这些信息。十一、小结mastra/brightdata以极少的配置成本把搜索 抓取两大联网能力以标准 Mastra Tool 的形式注入 AgentwebSearch负责从 Google 获取结构化自然搜索结果webFetch负责用 Web Unlocker 穿透反爬读取正文二者共享一套基于fetch的轻量客户端与统一的配置优先级。其核心实现集中在 integrations/brightdata/src 的client.ts、search.ts、fetch.ts三个文件中配合 测试套件 即可完整掌握其行为边界适合作为 Mastra 研究型、检索增强型 Agent 的联网底座。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 集成 Bright Data：为 AI Agent 打造可穿透反爬的搜索与网页抓取工具
Mastra 集成 Bright Data为 AI Agent 打造可穿透反爬的搜索与网页抓取工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/brightdata是 Mastra 官方生态中对接 Bright Data 的集成包为 Agent 提供webSearchSERP 搜索与webFetch网页抓取两个开箱即用的工具底层由 Bright Data 的 SERP API 与 Web Unlocker 驱动可绕过机器人检测与 CAPTCHA适合需要实时检索网页、读取被普通爬虫拦截的站点的研究型 Agent。读完本文你将掌握该包的安装、配置、两个工具的参数语义以及其在 Mastra Agent 中的接入方式与底层调用机制。一、这个集成解决什么问题普通爬虫或搜索引擎 API 在面对 Google 搜索结果页以及启用了 Cloudflare、Akamai 等反爬保护的目标网站时经常返回验证码页面或直接拒绝访问。mastra/brightdata的思路是把这两件脏活外包给 Bright DataSERP API代理 Google 搜索请求返回解析好的自然搜索结果链接、标题、摘要并对搜索结果应用 Bright Data 的代理/反检测能力Web Unlocker抓取任意 URL自动处理机器人检测、CAPTCHA、指纹识别等反爬手段把页面内容以 Markdown 形式返回给 Agent。因此这两个工具特别适合先搜到页面、再读取正文的两段式研究流程。从包描述见 package.json与 README 可以确认这正是该集成的核心定位。二、安装与前置准备在 Mastra 项目中安装npm install mastra/brightdata包以mastra/core1.0.0-0 2.0.0-0和zod3.0.0为 peer 依赖要求 Node.js22.13.0并作为 ESM 模块发布type: module同时提供require的 CJS 产物见 package.json。使用前需要两样东西Bright Data API Token从 Bright Data 控制台获取Zone区域配置工具默认使用两个内置 zone——SERP 搜索默认sdk_serpWeb Unlocker 抓取默认sdk_unlocker定义见 client.ts一般无需改动。三、快速开始把搜索与抓取能力挂到 Agent 上README 给出的核心用法是调用createBrightDataTools()一次性拿到两个工具然后注入 Agent 的toolsimport { createBrightDataTools } from mastra/brightdata; import { Agent } from mastra/core/agent; const { webSearch, webFetch } createBrightDataTools(); export const researchAgent new Agent({ id: research-agent, name: Research Agent, model: openai/gpt-5.6-sol, instructions: Search for relevant pages, then fetch the best sources before answering., tools: { webSearch, webFetch }, });其中createBrightDataTools(config?)的源码实现非常简单见 tools.tsexport function createBrightDataTools(config?: BrightDataClientOptions) { return { webSearch: createBrightDataSearchTool(config), webFetch: createBrightDataFetchTool(config), }; }也就是说它等价于分别调用createBrightDataSearchTool()与createBrightDataFetchTool()config会被透传给底层两个工具。也可以在同一个 Agent 里只挂其中一个工具import { createBrightDataSearchTool } from mastra/brightdata; export const searchOnlyAgent new Agent({ id: search-only-agent, name: Search Only Agent, model: openai/gpt-5.6-sol, instructions: Always use the web search tool to answer questions., tools: { webSearch: createBrightDataSearchTool() }, });3.1 模型说明示例中的model字段如openai/gpt-5.6-sol为 README 中的示意值实际应替换为你账户中可用的模型标识如anthropic/claude-sonnet-4-6等并保证对应的模型提供方凭证已配置。四、工具一webSearchGoogle 搜索工具 ID 为brightdata-search功能描述为搜索 Google 并返回解析后的自然搜索结果link/title/description底层走 SERP API 绕过机器人检测支持国家与语言定向以及基于结果偏移的分页见 search.ts。4.1 输入参数inputSchema参数类型必填约束与默认值说明querystring是—搜索关键词会被trim()后作为q参数countrystring否两位字母代码如us、gb不匹配则校验失败用于地理定向映射到 Google 的gl参数languagestring否两位字母代码如en、es、fr不匹配则校验失败本地化搜索结果语言映射到hl参数默认enstartnumber否非负整数结果偏移量用于分页如10表示取第 2 页的 10 条结果映射到start参数输入校验由 search.ts 中的 zod schema 完成country与language都必须匹配/^[a-z]{2}$/i两位字母start必须为int().nonnegative()。4.2 输出结构outputSchema{ query: string; // 原始查询词 results: Array{ // 解析后的自然搜索结果 link: string; // 结果 URL title: string; // 结果标题 description: string; // 结果摘要 }; currentPage: number; // 当前页号缺失或非法时回退为 1 }4.3 底层请求如何构造webSearch执行时会调用客户端client.search.google(query, { country, language, start })。从源码看请求 URL 是这样拼出来的client.ts 的buildGoogleSearchUrl目标为https://www.google.com/search默认format为json时追加brd_json1请求 Bright Data 返回结构化 JSONSERP以便工具解析出organic数组hl恒为语言参数默认engl仅在国家参数存在时设置start仅在有分页需求时设置请求体以format: json、method: GET、zone默认sdk_serp发送。搜索测试见 search.test.ts验证了完整映射query→q、country→gl、language→hl、start→start也验证了最小输入仅query时 URL 只含q与hlen不带gl/start。解析逻辑会把响应中的organic数组过滤为{ link, title, description }列表缺失link或title的条目会被丢弃响应缺失organic时结果为空数组current_page非法0 或缺失时回退为1。这些边界行为均有对应测试覆盖见 search.test.ts。五、工具二webFetch网页抓取工具 ID 为brightdata-fetch功能描述为抓取网页并返回 Markdown 内容底层走 Web Unlocker可绕过机器人检测与 CAPTCHA包括普通爬虫无法访问的页面见 fetch.ts。5.1 输入与输出// 输入 { url: string } // 必须为合法 URLzod 的 z.string().url() // 输出 { url: string; content: string } // content 为页面的 Markdown 内容5.2 底层请求如何构造webFetch执行时调用client.scrapeUrl(input.url, { dataFormat: markdown })最终请求体为fetch.test.ts 断言了精确的请求体{ data_format: markdown, format: raw, method: GET, url: https://example.com, zone: sdk_unlocker }注意与搜索工具的差异抓取走raw格式返回原始文本而不是 JSON 解析data_format为markdownzone 默认sdk_unlocker。六、配置详解客户端选项、环境变量与默认值两个工具以及createBrightDataTools()都接受可选的BrightDataClientOptions见 client.ts配置项类型默认值说明apiKeystring取BRIGHTDATA_API_TOKEN环境变量无则抛出Bright Data API token is requiredtimeoutnumber120_000120 秒请求超时非正数或非有限数时回退默认值serpZonestring取BRIGHTDATA_SERP_ZONE再回退sdk_serp搜索请求使用的 zonewebUnlockerZonestring取BRIGHTDATA_WEB_UNLOCKER_ZONE再回退sdk_unlocker抓取请求使用的 zone6.1 配置优先级从 client.ts 的实现看优先级为显式配置 环境变量 内置默认值const apiKey config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN; const serpZone config?.serpZone ?? process.env.BRIGHTDATA_SERP_ZONE ?? DEFAULT_SERP_ZONE; const webUnlockerZone config?.webUnlockerZone ?? process.env.BRIGHTDATA_WEB_UNLOCKER_ZONE ?? DEFAULT_WEB_UNLOCKER_ZONE;客户端测试见 client.test.ts逐一验证了无 token 时报错、config 优先于环境变量、zone 可分别通过 config 或环境变量覆盖。6.2 显式传参示例import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools({ apiKey: process.env.BRIGHTDATA_API_TOKEN, serpZone: my_custom_serp_zone, webUnlockerZone: my_custom_unlocker_zone, timeout: 60_000, });也可以只传一部分例如只覆盖serpZone而让抓取继续走默认 zone。6.3 环境变量清单export BRIGHTDATA_API_TOKENyour_api_token export BRIGHTDATA_SERP_ZONEsdk_serp # 可选 export BRIGHTDATA_WEB_UNLOCKER_ZONEsdk_unlocker # 可选七、底层原理一次请求的完整链路该集成不再依赖brightdata/sdk运行时客户端而是用标准fetch直连 Bright Data REST 接口详见 client.ts 与 changelog 中 #16630 的说明——这一改造同时修复了 Bun 环境下的兼容问题。一次调用链路如下构造请求体toRequestBody()组装{ url, zone, format, method }搜索默认format: json抓取默认format: raw并带上data_format: markdown发起请求requestBrightData()向https://api.brightdata.com/request发送POST请求头为Authorization: Bearer apiKey与Content-Type: application/json超时控制用AbortControllersetTimeout实现超时后抛出Request timed out after msms错误映射401/403→invalid API key or insufficient permissions400→bad request: 响应文本其他非 2xx →request failed with status status: 响应文本响应解析format: json时把响应文本JSON.parse后返回否则原样返回文本scrapeUrl对非字符串响应会JSON.stringify清理工具执行完毕后调用closeClient()做 best-effort 清理且保证close()抛错也不会掩盖主流程错误见 client.ts 的closeClient与 client.test.ts。八、搜索参数的语言校验细节client.search.google()在发请求前还会多做两步防御见 client.tslanguage必须匹配/^[a-z]{2}$/i否则直接抛错且不发请求测试以1_为例验证不会打到网络合法时统一toLowerCase()归一化如EN→en保证hlen这类 URL 参数大小写一致。此外只有format为json时才追加brd_json1请求方若显式指定format: raw则可拿到真实的原始 SERP 文本见 client.test.ts。九、测试与验证方式该集成自带完整 vitest 测试套件位于 integrations/brightdata/src/tests可在本地运行cd integrations/brightdata pnpm test测试覆盖了四个层面tools.test.tscreateBrightDataTools返回两个工具且 ID、描述、输入/输出 schema 齐全client.test.tsAPI key 来源与优先级、zone 覆盖、语言校验与归一化、brd_json逻辑、401 错误映射、closeClient行为search.test.ts参数映射、最小输入、organic缺失/脏数据处理、current_page回退、错误透传fetch.test.ts请求体精确断言data_format: markdown、zone: sdk_unlocker、错误透传。十、实战建议与注意事项两段式研究流程在 Agent 的instructions中明确先用webSearch找到候选页面再用webFetch读取正文再作答能让模型按序使用工具减少盲目抓取分页技巧start每次递增 1010、20…结合输出里的currentPage可以设计多轮深度搜索的工作流超时调整Web Unlocker 处理复杂反爬页面可能耗时较长默认 120 秒通常够用若你的场景页面较轻可通过timeout收紧以降低等待zone 自定义如果你在 Bright Data 控制台创建了专属 zone用于配额统计或独立配置务必通过serpZone/webUnlockerZone或对应环境变量覆盖默认值否则请求会落在默认 zone 上凭证安全优先使用环境变量注入BRIGHTDATA_API_TOKEN避免把 token 硬编码进源码或提交到仓库错误处理工具的错误已归一化为可读信息key 无效、400 请求错误、超时等在 Agent 上层做try/catch或重试时可直接依赖这些信息。十一、小结mastra/brightdata以极少的配置成本把搜索 抓取两大联网能力以标准 Mastra Tool 的形式注入 AgentwebSearch负责从 Google 获取结构化自然搜索结果webFetch负责用 Web Unlocker 穿透反爬读取正文二者共享一套基于fetch的轻量客户端与统一的配置优先级。其核心实现集中在 integrations/brightdata/src 的client.ts、search.ts、fetch.ts三个文件中配合 测试套件 即可完整掌握其行为边界适合作为 Mastra 研究型、检索增强型 Agent 的联网底座。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考