关于 browser
browser 技能帮助 Agent 通过 Bright Data 云浏览器运行现有的 Playwright、Puppeteer 或 Selenium 自动化,也可用 `bdata browser` 逐步控制浏览器。它保留原有自动化逻辑,重点说明连接配置、区域选择和故障排查。
主要功能
- 01连接现有浏览器自动化
- 02支持 Playwright、Puppeteer 和 Selenium
- 03使用 `bdata browser` 逐步控制
- 04按类型查找浏览器区域
- 05浏览器连接故障指引
适用场景
- 01在云浏览器中运行现有自动化
- 02从终端逐步操控浏览器
- 03排查浏览器连接失败
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ brightdata/ skills --skill browser安装后在 Claude Code 中输入/browser确认已加载。
附带文件references/connect.mdreferences/errors.md
详细介绍
Bright Data - 浏览器
用户已经编写了自动化脚本。此技能只需更改启动行,让脚本改用 Bright Data 的云端浏览器,而不是本地浏览器,配置该启动行所需的凭据,然后运行一次以验证连接。自动化逻辑本身不需要改动。
唯一需要问的问题
由谁来点击——你的代码、你的 AI 模型,还是我们?
| 谁来点击 | 该怎么做 |
|---|---|
| 用户的代码:Playwright、Puppeteer 或 Selenium | 继续留在这里。将其指向我们的云端浏览器,无需重写。 |
| 用户的计算机使用模型,也就是会自行点击的 AI | 继续留在这里。改法相同,端点也相同。 |
| Agent 自己从终端一步步操作 | 继续留在这里,并通过 bdata browser 操作:open、snapshot、click <ref>、type <ref>、close,每个操作对应一条命令,无需编写代码。所有子命令都列在 bdata browser --help 中,brightdata-cli 技能的 references/commands.md 中包含会话选项。 |
| 我们 | 使用 scrape。Scraper Studio 负责点击,用户拿到的是字段结果,而不是需要维护的驱动程序。 |
如果请求提到了框架、技术或 Agent,却没有说明由谁控制浏览器,就询问这个问题。只问一次,然后采取行动。用户手里已有可运行的 Playwright 代码,只是本地浏览器受阻时,完全不必提及 Scraper Studio。
更改内容
将本地启动调用改为通过 websocket 远程连接:
wss://brd-customer-<CUSTOMER_ID>-zone-<ZONE>:<PASSWORD>@brd.superproxy.io:9222
Selenium 是唯一的例外。它使用 WebDriver,而不是 CDP,因此要在端口 9515 上使用 https://,凭据相同。选择器、等待、导航、屏幕截图和页面逻辑都保持原样。
Agent 会自行填写这三项内容,使用免费的 API 读取和用户已有的密钥(BRIGHTDATA_API_KEY,否则使用 CLI 中存储的登录凭据),绝不会让用户填写占位符。如果完全没有密钥,说明用户尚未完成设置:转交给 agent-onboarding,绝不要在聊天中索要密钥。references/connect.md 介绍了如何查找,以及配置连接的两种方法。
Zone
在写入字符串之前,按类型而不是按名称查找 Browser API zone:
bdata zones --json
找到 "type" 为 "browser_api" 的条目,并使用其 name,填入连接字符串中的 <ZONE>。执行 bdata login 后,名称为 cli_browser;通过 Agent 注册创建的账户中,名称为 agent_browser_api;由 MCP 服务配置的账户中,名称为 mcp_browser;手动创建的账户中,名称可以是任意值:读取类型,然后使用该条目的名称。这是一次免费的读取,不会启动会话。如果系统无法识别 bdata,说明 CLI 尚未安装,或 npm 的全局目录不在 PATH 中;这两种情况的解决方法都在 agent-onboarding 技能的 Install 部分。
如果完全没有该类型的条目,问题不是连接字符串需要修正,但也还不是账户问题。用户同意后(这会更改其账户),可通过一次免费的调用创建:POST https://api.brightdata.com/zone,请求体为 {"zone":{"name":"cli_browser","type":"browser_api"},"plan":{"type":"browser_api"}}。bdata browser open 也会按需创建 zone,但这会启动计费会话,而且除非提供 --zone <name> 或 BRIGHTDATA_BROWSER_ZONE,否则使用名称 cli_browser。因此,如果账户中的 browser zone 使用其他名称,请传入该名称,否则会创建第二个 zone(使用 Agent 注册密钥时无法创建 zone,命令会失败;请传入 --zone agent_browser_api)。如果机器已登录,不要运行 bdata login:这会替换已存储的密钥。如果创建操作因 kyc_required 或 business_account_required 被拒绝,或因权限不足而被拒绝(使用 Agent 注册密钥,或不具备 Admin 或 Ops 角色的用户,都无法创建 zone),请转交给 agent-onboarding:随后由用户在 Control Panel 中创建 zone。
适用范围
构建抓取器属于 scrape,用户只想要数据、不在意浏览器由什么驱动时提出的请求也属于 scrape。将单个页面转换为 Markdown、HTML 或截图属于 fetch。任何从搜索查询开始的请求都属于 search。此技能适用于已有驱动程序的情况。
登录网站
默认情况下,禁止通过 Browser API 输入密码。此操作需要 KYC 和合规例外批准。在获得批准之前,切勿承诺提供登录流程,也不要反复尝试触发拦截。详细说明请参阅相邻的技能:打开 agent-onboarding,并阅读其中的 references/auth.md 文件,了解哪些情况需要 KYC、哪些不需要,以及审批流程。
接下来阅读
- 编写连接行之前,先阅读 references/connect.md——其中说明了确切字符串、密钥和三项参数各自的来源、两种设计(将端点放在密钥中,或在运行时查找)及各自的适用情形,以及 Playwright 的端到端修改方法。
- 连接尝试失败时,立即阅读 references/errors.md——其中说明了 407
client_100xx错误代码及其含义、Browser API 身份验证错误代码,以及重试规则。
危险信号——发现以下情况时请停止
- 向已经有可用驱动程序代码的用户推荐 Scraper Studio
- 重写用户的自动化代码,而不是修改端点行
- 将 Selenium 指向端口 9222,或将 Playwright 指向端口 9515
- 输出、记录日志或提交拼接后的端点(其中包含密码),或输出未做脱敏处理的连接错误
- 在终端中运行
bdata zones info <zone>:该命令会输出区域密码 - 明明 Agent 可以自行读取已存储的密钥,却仍留给用户一个需要填写的变量,或向用户索要密钥
- 未查看 407 附带的错误代码就重试
- 尚未发生连接被错误拒绝的情况,就让用户进行 KYC
- 不按类型查找
browser_api区域,而是硬编码或猜测区域名称 - 未先征求用户同意就创建区域