尧图网页设计 
Mastra × Bright Data 集成指南为 AI Agent 注入绕过反爬的搜索与网页抓取能力【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读mastra/brightdata是 Mastra 生态中专门封装 Bright Data 能力的官方工具集成包它把 Bright Data 的SERP API搜索引擎结果页与Web Unlocker网页解锁器包装成两个开箱即用的 Mastra Agent 工具brightdata-search与brightdata-fetch。借助 Bright Data 的代理基础设施这两个工具可以绕过常见的机器人检测bot detection与 CAPTCHA让 Agent 在普通爬虫无法访问的站点上完成搜索与内容抓取。读完本文你将掌握该集成包的安装配置、两个工具的参数契约、底层 HTTP 调用原理、输入校验加固逻辑以及如何在真实 Agent 中组合出搜索→筛选→抓取→回答的完整研究链路。一、集成包概览从 Changelog 看能力演进mastra/brightdata的版本历史见 CHANGELOG.md清晰记录了该集成从诞生到加固的完整轨迹版本关键变化0.2.0首次引入brightdata-search与brightdata-fetch两个工具分别基于 Bright Data 的 SERP API 与 Web Unlocker开箱即可绕过机器人检测与 CAPTCHA0.2.1将底层运行时客户端替换为基于fetch的 REST 调用修复了工具在 Bun 运行时下不可用的问题同时对搜索入参做加固见第五节0.2.4针对 2026-06-17 的 easy-day-js 供应链事件进行安全修复发布干净的版本以取代声明了恶意依赖的受损版本0.3.1更新 README 信息并从 npm 发布物中移除CHANGELOG.md以缩减包体积其中 0.2.0 的发布说明直接给出了集成包的定位与最小用法——两个工具的组合正是研究型 Agent的核心能力对。后续 0.2.1 的两次补丁Bun 兼容 入参校验则体现了该集成在真实运行环境中的两个关键设计决策我们将在后文结合源码逐一展开。二、安装与快速开始2.1 安装包名发布在 npm 上依赖mastra/core与zodzod 用于工具输入输出 Schema 定义npm install mastra/brightdata zod从 package.json 可以看到该包以 ESM/CJS 双格式发布dist/index.js与dist/index.cjs要求 Node.js22.13.0并以mastra/core 1.0.0-0 2.0.0-0、zod 3.0.0作为 peer 依赖。2.2 快速开始通过一个入口函数即可同时拿到两个工具// src/mastra/tools/index.ts import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools(); // 也可以显式传入 API Key // const { webSearch, webFetch } createBrightDataTools({ apiKey: brd-... });也可以按需单独创建每个工具// src/mastra/tools/index.ts import { createBrightDataSearchTool, createBrightDataFetchTool } from mastra/brightdata; const searchTool createBrightDataSearchTool(); const fetchTool createBrightDataFetchTool({ apiKey: brd-... });默认情况下所有工具都会从环境变量BRIGHTDATA_API_TOKEN读取令牌显式传入{ apiKey }可以覆盖环境变量。工具的全部导出入口集中在 index.tsgetBrightDataClient、createBrightDataSearchTool、createBrightDataFetchTool与createBrightDataTools。三、配置项详解所有工厂函数createBrightDataTools、createBrightDataSearchTool、createBrightDataFetchTool都接受同一个BrightDataClientOptions配置对象。其完整字段定义位于 client.ts配置项类型默认值说明apiKeystringBRIGHTDATA_API_TOKEN环境变量Bright Data API 令牌缺省时回退到环境变量二者皆无则抛出错误timeoutnumber120_000120 秒单次请求超时时间毫秒非有限正数时回退到默认值serpZonestringsdk_serpSERP 搜索使用的 Bright Data zone 名称可通过BRIGHTDATA_SERP_ZONE环境变量覆盖webUnlockerZonestringsdk_unlockerWeb Unlocker 抓取使用的 zone 名称可通过BRIGHTDATA_WEB_UNLOCKER_ZONE环境变量覆盖配置解析顺序遵循显式配置优先于环境变量、环境变量优先于内置默认值的层级。zone 的取值解析逻辑见 client.ts而BRIGHTDATA_SERP_ZONE/BRIGHTDATA_WEB_UNLOCKER_ZONE这两个环境变量均有对应的单元测试覆盖见 client.test.ts。四、两个核心工具4.1createBrightDataSearchTool()Google 自然搜索结果工具 IDbrightdata-search该工具通过 Bright Data 的 SERP API 发起 Google 搜索并返回解析后的自然结果link / title / description用于让 Agent 先找到相关页面。其输入输出 Schema 由 zod 定义在 search.ts。输入参数参数类型必填说明querystring是搜索关键词countrystring否两位国家代码用于地理定向结果如us、gb需匹配/^[a-z]{2}$/ilanguagestring否语言代码如en、es、fr用于本地化 Google 结果同样要求两位字母startnumber否结果偏移量用于分页例如传10表示取每页 10 条时的第二页输出结构{ query: string; // 原始查询词 results: Array{ // 自然搜索结果缺失 link 或 title 的条目会被过滤 link: string; title: string; description: string; }; currentPage: number; // SERP API 返回的页码上游缺省或非正数时默认为 1 }输出解析层对上游数据做了相当多的防御性处理search.ts当响应体是 JSON 编码的字符串时先JSON.parse再读取organic数组对每个条目做类型守卫并trim字符串字段link或title为空则剔除该条目current_page缺失、非法或非正数时回退为1。4.2createBrightDataFetchTool()Web Unlocker 网页抓取工具 IDbrightdata-fetch该工具通过 Bright Data 的 Web Unlocker 抓取任意网页并返回 Markdown 格式的正文内容用于让 Agent 在定位到相关页面后精读全文。其 Schema 定义见 fetch.ts。输入参数参数类型必填说明urlstring是要抓取的 URL必须是合法的 HTTP/HTTPS 地址zod 的z.string().url()校验输出结构{ url: string; // 原始输入 URL content: string; // 页面内容Markdown }该工具在调用底层scrapeUrl时固定传入dataFormat: markdownfetch.ts因此 Agent 拿到的始终是便于 LLM 阅读的 Markdown而非原始 HTML。4.3 组合入口createBrightDataTools()createBrightDataTools(config?)一次性返回{ webSearch, webFetch }两个工具共享同一份配置对象tools.ts。其行为在 tools.test.ts 中有完整验证返回对象同时包含两个工具、各自的 ID 与描述、以及完整输入输出 Schema。五、源码级原理fetch 直连与入参加固CHANGELOG 中 0.2.1 版本的两条补丁恰好揭示了该集成在实现层面的两个核心决策以下结合源码逐一展开。5.1 为什么改用 fetch 直连Bun 兼容修复0.2.1 的补丁说明写道Fix Bright Data tools under Bun by replacing the SDK runtime client with fetch-based REST callsPR #16630。也就是说早期版本依赖 Bright Data 官方 SDK 的运行时客户端但该客户端在 Bun 运行时下存在兼容问题修复方案是不再依赖 SDK 运行时而是直接用标准fetch调用 Bright Data 的 REST 接口。从 client.ts 可以看到这个请求核心函数requestBrightData的实现请求端点固定为https://api.brightdata.com/request使用POST方法Authorization: Bearer apiKey的鉴权头请求体包含zone目标 zone、method、url、formatraw或json以及可选的country和data_format基于AbortController实现超时控制超时抛出Request timed out after ${timeout}ms响应码映射为语义化错误401/403抛invalid API key or insufficient permissions400抛bad request附带响应体其余非 2xx 抛带状态码的通用错误format: json时自动JSON.parse返回结构化数据raw时原样返回文本。这一实现使集成不再依赖任何非标准运行时 API天然兼容 Node 与 Bun。测试 client.test.ts 还专门验证了 401 响应会被映射为invalid API key or insufficient permissions。5.2 搜索入参的三重加固PR #173410.2.1 的第二条补丁对搜索输入做了系统性加固可以拆成三个层次两位字母代码校验country与language在进入请求前必须匹配/^[a-z]{2}$/i。校验在两层同时生效——工具层由 zod 的.regex(/^[a-z]{2}$/i, ...)在 Schema 处拦截search.ts客户端层在search.google调用前再次校验client.ts后者还会在请求发出前就抛出错误避免无效请求打到上游client.test.ts 验证了fetch不会被调用。语言代码小写归一化getBrightDataClient().search.google()会把传入的language统一toLowerCase()后再拼入 URLclient.ts测试用例验证了EN会被归一化为enclient.test.ts。brd_json1的条件化结构化 JSON 参数brd_json1只有在搜索format为json时才拼入 URLclient.ts。这样当调用方显式要求raw格式时能拿到真正未经结构化处理的原始 SERP 响应——测试 client.test.ts 验证了format: raw时 URL 中不包含brd_json。5.3 一次调用对应的完整链路以brightdata-search为例一次工具调用在内部的完整链路是tool.execute(input) → getBrightDataClient(config) // 解析 apiKey、zone、timeout → client.search.google(query, options) // 校验并归一化 language → buildGoogleSearchUrl(query, options) // 拼出 q / brd_json / hl / gl / start 参数 → requestBrightData(apiKey, body) // fetch POST https://api.brightdata.com/request → 解析 organic 数组、过滤脏数据 → closeClient(client) // finally 中尽力清理不掩盖主错误其中closeClient采用 best-effort 清理策略即便close()抛错也会被吞掉绝不掩盖工具本身的真实错误client.ts测试见 client.test.ts。测试 search.test.ts 还验证了一次成功执行恰好只产生一次上游请求。六、在 Agent 中使用研究型 Agent 实战把两个工具组合进 Agent即可得到一个完整的搜索→抓取→回答研究链路。CHANGELOG 0.2.0 的发布示例与官方文档brightdata.mdx给出的标准写法如下// src/mastra/agents/index.ts import { Agent } from mastra/core/agent; import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools(); export const researchAgent 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或通过{ apiKey }显式传入并按需配置BRIGHTDATA_SERP_ZONE/BRIGHTDATA_WEB_UNLOCKER_ZONE。Agent 拿到两个工具后会自行决定何时调用brightdata-search定位候选页面、何时调用brightdata-fetch抓取目标页正文——由于底层由 Bright Data 的 SERP API 与 Web Unlocker 支撑对普通爬虫设置反爬的站点也能正常取数。七、环境变量速查变量说明BRIGHTDATA_API_TOKENBright Data API 令牌未向工厂函数传apiKey时作为默认凭据BRIGHTDATA_SERP_ZONE覆盖 SERP 搜索使用的 zone默认sdk_serpBRIGHTDATA_WEB_UNLOCKER_ZONE覆盖 Web Unlocker 抓取使用的 zone默认sdk_unlocker其中BRIGHTDATA_API_TOKEN缺失时会直接抛出错误Bright Data API token is required. Pass{ apiKey }or setBRIGHTDATA_API_TOKENenv var.见 client.ts。八、工程实践要点凭据管理生产环境优先使用BRIGHTDATA_API_TOKEN环境变量仅在需要多账户隔离或动态注入时用{ apiKey }显式传参。配置优先级为apiKey配置 环境变量 内置默认值。时区与目标定制通过countrygl参数与languagehl参数做地理定向与本地化搜索两者都必须使用两位字母代码且语言代码会自动归一化为小写。分页start偏移量用于翻页如每页 10 条时start: 10取第二页currentPage字段可帮助 Agent 感知当前所处页码。超时控制默认 120 秒的请求超时可通过timeout配置调整超时与鉴权失败都会抛出语义化错误便于 Agent 自行重试或上报。安全治理0.2.4 版本曾因 2026-06-17 的 easy-day-js 供应链事件发布过安全修复版本PR #18056。升级集成包时建议关注此类安全补丁版本并将依赖锁定到已修复的干净版本。包体积自 0.3.1 起CHANGELOG.md不再随包发布PR #22737files仅保留dist目录见 package.json。九、验证与测试证据该集成的行为均有完整单测背书相关测试文件可直接作为行为契约参考client.test.tsapiKey 解析优先级、zone 覆盖、语言校验与小写归一化、brd_json条件化、401 错误映射、closeClient容错search.test.ts工具 ID/Schema、参数映射到请求体与 URL、脏数据过滤、页码回退、错误透传、请求次数fetch.test.tsdata_format: markdown与zone: sdk_unlocker的请求体构造、Markdown 内容回传tools.test.tscreateBrightDataTools返回双工具及其完整 Schema。结合 README.md 与官方集成文档 brightdata.mdx 阅读可以快速上手并深入理解本集成的全部行为细节。【免费下载链接】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/mastra导读mastra/brightdata是 Mastra 生态中专门封装 Bright Data 能力的官方工具集成包它把 Bright Data 的SERP API搜索引擎结果页与Web Unlocker网页解锁器包装成两个开箱即用的 Mastra Agent 工具brightdata-search与brightdata-fetch。借助 Bright Data 的代理基础设施这两个工具可以绕过常见的机器人检测bot detection与 CAPTCHA让 Agent 在普通爬虫无法访问的站点上完成搜索与内容抓取。读完本文你将掌握该集成包的安装配置、两个工具的参数契约、底层 HTTP 调用原理、输入校验加固逻辑以及如何在真实 Agent 中组合出搜索→筛选→抓取→回答的完整研究链路。一、集成包概览从 Changelog 看能力演进mastra/brightdata的版本历史见 CHANGELOG.md清晰记录了该集成从诞生到加固的完整轨迹版本关键变化0.2.0首次引入brightdata-search与brightdata-fetch两个工具分别基于 Bright Data 的 SERP API 与 Web Unlocker开箱即可绕过机器人检测与 CAPTCHA0.2.1将底层运行时客户端替换为基于fetch的 REST 调用修复了工具在 Bun 运行时下不可用的问题同时对搜索入参做加固见第五节0.2.4针对 2026-06-17 的 easy-day-js 供应链事件进行安全修复发布干净的版本以取代声明了恶意依赖的受损版本0.3.1更新 README 信息并从 npm 发布物中移除CHANGELOG.md以缩减包体积其中 0.2.0 的发布说明直接给出了集成包的定位与最小用法——两个工具的组合正是研究型 Agent的核心能力对。后续 0.2.1 的两次补丁Bun 兼容 入参校验则体现了该集成在真实运行环境中的两个关键设计决策我们将在后文结合源码逐一展开。二、安装与快速开始2.1 安装包名发布在 npm 上依赖mastra/core与zodzod 用于工具输入输出 Schema 定义npm install mastra/brightdata zod从 package.json 可以看到该包以 ESM/CJS 双格式发布dist/index.js与dist/index.cjs要求 Node.js22.13.0并以mastra/core 1.0.0-0 2.0.0-0、zod 3.0.0作为 peer 依赖。2.2 快速开始通过一个入口函数即可同时拿到两个工具// src/mastra/tools/index.ts import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools(); // 也可以显式传入 API Key // const { webSearch, webFetch } createBrightDataTools({ apiKey: brd-... });也可以按需单独创建每个工具// src/mastra/tools/index.ts import { createBrightDataSearchTool, createBrightDataFetchTool } from mastra/brightdata; const searchTool createBrightDataSearchTool(); const fetchTool createBrightDataFetchTool({ apiKey: brd-... });默认情况下所有工具都会从环境变量BRIGHTDATA_API_TOKEN读取令牌显式传入{ apiKey }可以覆盖环境变量。工具的全部导出入口集中在 index.tsgetBrightDataClient、createBrightDataSearchTool、createBrightDataFetchTool与createBrightDataTools。三、配置项详解所有工厂函数createBrightDataTools、createBrightDataSearchTool、createBrightDataFetchTool都接受同一个BrightDataClientOptions配置对象。其完整字段定义位于 client.ts配置项类型默认值说明apiKeystringBRIGHTDATA_API_TOKEN环境变量Bright Data API 令牌缺省时回退到环境变量二者皆无则抛出错误timeoutnumber120_000120 秒单次请求超时时间毫秒非有限正数时回退到默认值serpZonestringsdk_serpSERP 搜索使用的 Bright Data zone 名称可通过BRIGHTDATA_SERP_ZONE环境变量覆盖webUnlockerZonestringsdk_unlockerWeb Unlocker 抓取使用的 zone 名称可通过BRIGHTDATA_WEB_UNLOCKER_ZONE环境变量覆盖配置解析顺序遵循显式配置优先于环境变量、环境变量优先于内置默认值的层级。zone 的取值解析逻辑见 client.ts而BRIGHTDATA_SERP_ZONE/BRIGHTDATA_WEB_UNLOCKER_ZONE这两个环境变量均有对应的单元测试覆盖见 client.test.ts。四、两个核心工具4.1createBrightDataSearchTool()Google 自然搜索结果工具 IDbrightdata-search该工具通过 Bright Data 的 SERP API 发起 Google 搜索并返回解析后的自然结果link / title / description用于让 Agent 先找到相关页面。其输入输出 Schema 由 zod 定义在 search.ts。输入参数参数类型必填说明querystring是搜索关键词countrystring否两位国家代码用于地理定向结果如us、gb需匹配/^[a-z]{2}$/ilanguagestring否语言代码如en、es、fr用于本地化 Google 结果同样要求两位字母startnumber否结果偏移量用于分页例如传10表示取每页 10 条时的第二页输出结构{ query: string; // 原始查询词 results: Array{ // 自然搜索结果缺失 link 或 title 的条目会被过滤 link: string; title: string; description: string; }; currentPage: number; // SERP API 返回的页码上游缺省或非正数时默认为 1 }输出解析层对上游数据做了相当多的防御性处理search.ts当响应体是 JSON 编码的字符串时先JSON.parse再读取organic数组对每个条目做类型守卫并trim字符串字段link或title为空则剔除该条目current_page缺失、非法或非正数时回退为1。4.2createBrightDataFetchTool()Web Unlocker 网页抓取工具 IDbrightdata-fetch该工具通过 Bright Data 的 Web Unlocker 抓取任意网页并返回 Markdown 格式的正文内容用于让 Agent 在定位到相关页面后精读全文。其 Schema 定义见 fetch.ts。输入参数参数类型必填说明urlstring是要抓取的 URL必须是合法的 HTTP/HTTPS 地址zod 的z.string().url()校验输出结构{ url: string; // 原始输入 URL content: string; // 页面内容Markdown }该工具在调用底层scrapeUrl时固定传入dataFormat: markdownfetch.ts因此 Agent 拿到的始终是便于 LLM 阅读的 Markdown而非原始 HTML。4.3 组合入口createBrightDataTools()createBrightDataTools(config?)一次性返回{ webSearch, webFetch }两个工具共享同一份配置对象tools.ts。其行为在 tools.test.ts 中有完整验证返回对象同时包含两个工具、各自的 ID 与描述、以及完整输入输出 Schema。五、源码级原理fetch 直连与入参加固CHANGELOG 中 0.2.1 版本的两条补丁恰好揭示了该集成在实现层面的两个核心决策以下结合源码逐一展开。5.1 为什么改用 fetch 直连Bun 兼容修复0.2.1 的补丁说明写道Fix Bright Data tools under Bun by replacing the SDK runtime client with fetch-based REST callsPR #16630。也就是说早期版本依赖 Bright Data 官方 SDK 的运行时客户端但该客户端在 Bun 运行时下存在兼容问题修复方案是不再依赖 SDK 运行时而是直接用标准fetch调用 Bright Data 的 REST 接口。从 client.ts 可以看到这个请求核心函数requestBrightData的实现请求端点固定为https://api.brightdata.com/request使用POST方法Authorization: Bearer apiKey的鉴权头请求体包含zone目标 zone、method、url、formatraw或json以及可选的country和data_format基于AbortController实现超时控制超时抛出Request timed out after ${timeout}ms响应码映射为语义化错误401/403抛invalid API key or insufficient permissions400抛bad request附带响应体其余非 2xx 抛带状态码的通用错误format: json时自动JSON.parse返回结构化数据raw时原样返回文本。这一实现使集成不再依赖任何非标准运行时 API天然兼容 Node 与 Bun。测试 client.test.ts 还专门验证了 401 响应会被映射为invalid API key or insufficient permissions。5.2 搜索入参的三重加固PR #173410.2.1 的第二条补丁对搜索输入做了系统性加固可以拆成三个层次两位字母代码校验country与language在进入请求前必须匹配/^[a-z]{2}$/i。校验在两层同时生效——工具层由 zod 的.regex(/^[a-z]{2}$/i, ...)在 Schema 处拦截search.ts客户端层在search.google调用前再次校验client.ts后者还会在请求发出前就抛出错误避免无效请求打到上游client.test.ts 验证了fetch不会被调用。语言代码小写归一化getBrightDataClient().search.google()会把传入的language统一toLowerCase()后再拼入 URLclient.ts测试用例验证了EN会被归一化为enclient.test.ts。brd_json1的条件化结构化 JSON 参数brd_json1只有在搜索format为json时才拼入 URLclient.ts。这样当调用方显式要求raw格式时能拿到真正未经结构化处理的原始 SERP 响应——测试 client.test.ts 验证了format: raw时 URL 中不包含brd_json。5.3 一次调用对应的完整链路以brightdata-search为例一次工具调用在内部的完整链路是tool.execute(input) → getBrightDataClient(config) // 解析 apiKey、zone、timeout → client.search.google(query, options) // 校验并归一化 language → buildGoogleSearchUrl(query, options) // 拼出 q / brd_json / hl / gl / start 参数 → requestBrightData(apiKey, body) // fetch POST https://api.brightdata.com/request → 解析 organic 数组、过滤脏数据 → closeClient(client) // finally 中尽力清理不掩盖主错误其中closeClient采用 best-effort 清理策略即便close()抛错也会被吞掉绝不掩盖工具本身的真实错误client.ts测试见 client.test.ts。测试 search.test.ts 还验证了一次成功执行恰好只产生一次上游请求。六、在 Agent 中使用研究型 Agent 实战把两个工具组合进 Agent即可得到一个完整的搜索→抓取→回答研究链路。CHANGELOG 0.2.0 的发布示例与官方文档brightdata.mdx给出的标准写法如下// src/mastra/agents/index.ts import { Agent } from mastra/core/agent; import { createBrightDataTools } from mastra/brightdata; const { webSearch, webFetch } createBrightDataTools(); export const researchAgent 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或通过{ apiKey }显式传入并按需配置BRIGHTDATA_SERP_ZONE/BRIGHTDATA_WEB_UNLOCKER_ZONE。Agent 拿到两个工具后会自行决定何时调用brightdata-search定位候选页面、何时调用brightdata-fetch抓取目标页正文——由于底层由 Bright Data 的 SERP API 与 Web Unlocker 支撑对普通爬虫设置反爬的站点也能正常取数。七、环境变量速查变量说明BRIGHTDATA_API_TOKENBright Data API 令牌未向工厂函数传apiKey时作为默认凭据BRIGHTDATA_SERP_ZONE覆盖 SERP 搜索使用的 zone默认sdk_serpBRIGHTDATA_WEB_UNLOCKER_ZONE覆盖 Web Unlocker 抓取使用的 zone默认sdk_unlocker其中BRIGHTDATA_API_TOKEN缺失时会直接抛出错误Bright Data API token is required. Pass{ apiKey }or setBRIGHTDATA_API_TOKENenv var.见 client.ts。八、工程实践要点凭据管理生产环境优先使用BRIGHTDATA_API_TOKEN环境变量仅在需要多账户隔离或动态注入时用{ apiKey }显式传参。配置优先级为apiKey配置 环境变量 内置默认值。时区与目标定制通过countrygl参数与languagehl参数做地理定向与本地化搜索两者都必须使用两位字母代码且语言代码会自动归一化为小写。分页start偏移量用于翻页如每页 10 条时start: 10取第二页currentPage字段可帮助 Agent 感知当前所处页码。超时控制默认 120 秒的请求超时可通过timeout配置调整超时与鉴权失败都会抛出语义化错误便于 Agent 自行重试或上报。安全治理0.2.4 版本曾因 2026-06-17 的 easy-day-js 供应链事件发布过安全修复版本PR #18056。升级集成包时建议关注此类安全补丁版本并将依赖锁定到已修复的干净版本。包体积自 0.3.1 起CHANGELOG.md不再随包发布PR #22737files仅保留dist目录见 package.json。九、验证与测试证据该集成的行为均有完整单测背书相关测试文件可直接作为行为契约参考client.test.tsapiKey 解析优先级、zone 覆盖、语言校验与小写归一化、brd_json条件化、401 错误映射、closeClient容错search.test.ts工具 ID/Schema、参数映射到请求体与 URL、脏数据过滤、页码回退、错误透传、请求次数fetch.test.tsdata_format: markdown与zone: sdk_unlocker的请求体构造、Markdown 内容回传tools.test.tscreateBrightDataTools返回双工具及其完整 Schema。结合 README.md 与官方集成文档 brightdata.mdx 阅读可以快速上手并深入理解本集成的全部行为细节。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考