Bright Data — Agent 接入指南

Bright Data 为Agent提供可靠的开放网络访问能力：呈现与真实浏览器一致的SERP结果、从任意URL提取干净的Markdown内容（自动处理验证码与JS）、支持40+平台的结构化数据集（Amazon、LinkedIn、Instagram、TikTok、YouTube、Reddit、Crunchbase等），以及针对需真实交互页面的Browser API。

本技能是接入的入口。阅读一次后，选择合适的路径，再转向对应细分技能。

安装

一条命令即可安装CLI和Agent技能，并引导用户在浏览器中完成OAuth验证：

bash

# macOS / Linux — 最快安装方式
curl -fsSL https://cli.brightdata.com/install.sh | bash

# 跨平台（或不想使用安装脚本）
npm install -g @brightdata/cli

# 一次性使用，无需安装
npx --yes --package @brightdata/cli brightdata <command>

需要Node.js >= 20版本。安装完成后，

brightdata

和其简写

bdata

均可使用。

然后完成一次身份验证：

bash

bdata login

这条命令会完成以下操作：

打开浏览器进行OAuth验证（在无头/SSH机器上可使用
```
bdata login --device
```
）
将API密钥本地保存——您无需再手动粘贴令牌
自动创建所需的代理区域（
```
cli_unlocker
```
、
```
cli_browser
```
）
设置合理的默认配置

对于非交互式环境，可直接传入密钥：

bash

bdata login --api-key <key>
# 或
export BRIGHTDATA_API_KEY=<key>

在开始实际操作前验证安装是否成功：

bash

bdata version
bdata config            # 确认身份验证与代理区域
bdata zones             # 应显示cli_unlocker、cli_browser
bdata budget            # 确认账户与余额

如果以上任何命令失败，请先进入路径C（身份验证）解决问题后再继续。

安装Agent技能（可选，推荐）

CLI附带的安装程序可将Bright Data技能直接安装到您的编码Agent技能目录中：

bash

# 交互式选择器——选择技能与目标Agent
bdata skill add

# 安装特定技能
bdata skill add scrape
bdata skill add data-feeds
bdata skill add competitive-intel

# 查看所有可用技能
bdata skill list

这些是后续各路径中会用到的技能（

scrape

、

search

、

data-feeds

、

scraper-builder

、

brightdata-cli

、

bright-data-mcp

等）。

选择您的路径

所有路径都共享上述的安装与身份验证步骤，区别在于后续操作。

场景	路径
需要在当前会话中获取网页数据	路径A — 实时CLI工具
需要将Bright Data集成到应用代码中	路径B — SDK/REST集成
为LLM Agent添加即用型工具层	路径M — MCP服务器
首先需要API密钥	路径C — 仅身份验证
不想安装任何内容	路径D — 直接使用REST API

如果您的任务涉及多个路径，请按以下顺序操作：身份验证 → 使用实时工具探索 → 确定需求后进行应用集成。

路径A — 实时网页工具（CLI）

当Agent需要立即获取网页数据时使用此路径：发现URL、提取干净内容、从已知平台获取结构化记录，或快速进行竞品扫描。

完成安装与登录后，转向以下细分技能：

brightdata-cli

— 完整命令集（

scrape

、

search

、

pipelines

、

status

、

zones

、

budget

、

config

）

```
search
```
— 通过
```
bdata search
```
进行内容发现（Google/Bing/Yandex的SERP结果，结构化JSON格式）
```
scrape
```
— 通过
```
bdata scrape
```
从已知URL提取干净内容（Markdown/HTML/JSON/截图）
```
data-feeds
```
— 通过
```
bdata pipelines <type>
```
从40+支持平台获取结构化记录（Amazon、LinkedIn、Instagram、TikTok、YouTube、Reddit、Crunchbase、Google Maps等）
```
competitive-intel
```
— 基于CLI的竞品/定价/评论/招聘/SEO分析工具包
```
seo-audit
```
— 基于站点地图的实时SEO审计

实时网页操作的默认流程：

先搜索：当需要发现内容时
```
bdata search "query" --json
```
再用Pipelines：如果目标是支持的平台——无需解析即可获取结构化JSON
```
bdata pipelines amazon_product "https://amazon.com/dp/..."
```
最后抓取：当您有URL且无对应平台Pipelines时
```
bdata scrape "https://example.com" -f markdown
```
仅在必要时使用Browser API：当页面确实需要点击、表单提交或登录时（查看
```
brightdata-cli
```
技能中的
```
bdata browser
```
以及
```
bright-data-best-practices
```
中的Browser API参考文档）

当任务从「立即获取数据」转向「集成到应用中」时，请切换到路径B。

路径B — 将Bright Data集成到应用中

当您构建需要从代码中调用Bright Data的应用、Agent或工作流，且需要在

.env

或运行时配置中设置

BRIGHTDATA_API_KEY

（以及代理区域）时使用此路径。

此路径的核心问题是：

Bright Data在产品中需要实现什么功能？

根据答案选择对应的API：

产品需求	API	技能
获取单个页面的Markdown/HTML/JSON格式内容	Web Unlocker	`bright-data-best-practices` → `web-unlocker.md`
获取结构化JSON格式的搜索引擎结果	SERP API	`bright-data-best-practices` → `serp-api.md`
从支持平台获取结构化记录	Web Scraper API	`bright-data-best-practices` → `web-scraper-api.md`
处理JS密集型/交互式页面（使用Playwright/Puppeteer）	Browser API	`bright-data-best-practices` → `browser-api.md`
为任意站点构建自定义抓取工具	以上四个API，根据站点类型选择	`scraper-builder`

选择技术栈

Python → 使用官方SDK
bash
```
pip install brightdata-sdk
```
转向
```
python-sdk-best-practices
```
技能获取客户端配置（异步/同步）、平台抓取、SERP、数据集、Browser API以及错误处理的相关指导。
Node/TypeScript/Shell/其他 → 直接调用REST API（路径D包含端点信息），或通过
```
npx @brightdata/cli
```
将CLI作为库使用。
LLM工具层（Claude、ChatGPT等） → 使用MCP服务器（路径M）。

设置凭据

dotenv

BRIGHTDATA_API_KEY=...
BRIGHTDATA_UNLOCKER_ZONE=cli_unlocker   # 由`bdata login`自动创建
BRIGHTDATA_SERP_ZONE=cli_unlocker       # 或专用的SERP代理区域

如果您还没有密钥，请先完成路径C。

编写实际代码前进行冒烟测试

在大规模集成工作前，务必运行一次真实的Bright Data请求——在问题隐藏到应用错误路径前，提前发现身份验证、代理区域和配额问题。

bash

# 通过REST调用Web Unlocker
curl -sS https://api.brightdata.com/request \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "zone": "'"$BRIGHTDATA_UNLOCKER_ZONE"'",
    "format": "raw",
    "data_format": "markdown"
  }' | head -40

如果输出干净的Markdown内容，则说明集成成功。如果失败，请检查代理区域名称和密钥。

路径M — MCP服务器（LLM工具层）

当使用者是需要将Bright Data作为工具调用的LLM Agent时使用此路径（如Claude Code、ChatGPT桌面版、自定义Agent循环）。MCP服务器通过单个URL暴露60+工具——搜索、抓取、各平台结构化数据、浏览器自动化等。

连接地址：

https://mcp.brightdata.com/mcp?token=YOUR_BRIGHTDATA_API_TOKEN

可选URL参数：

参数	作用
`pro=1`	启用全部60+专业工具
`groups=<name>`	启用指定工具组（ `social` 、 `ecommerce` 、 `business` 、 `finance` 、 `research` 、 `app_stores` 、 `travel` 、 `browser` 、 `advanced_scraping` ）
`tools=<names>`	启用指定工具列表，以逗号分隔

转向

bright-data-mcp

技能获取工具选择、工具组自动启用以及工作流模式的相关指导。该技能会明确使用Bright Data MCP等效工具替代WebFetch/WebSearch。

路径C — 获取API密钥（仅身份验证）

当用户仍需注册、登录或生成密钥时使用此路径。如果

bdata config

已显示已验证的账户，或环境中已设置

BRIGHTDATA_API_KEY

，则可跳过此路径。

最简单方式：使用CLI的OAuth流程

bash

bdata login            # 基于浏览器的OAuth验证
bdata login --device   # 无头/SSH环境（设备码流程）

此流程可一步完成注册/登录、密钥生成、代理区域创建以及本地配置。优先选择此方式而非手动流程。

手动方式：控制台

如果用户偏好网页界面：

访问https://brightdata.com/cp（如需注册请先完成）
创建一个Web Unlocker代理区域（「添加」→「解锁器区域」）
从控制台复制API密钥
将密钥保存到应用读取密钥的位置：

bash

echo "BRIGHTDATA_API_KEY=..." >> .env
echo "BRIGHTDATA_UNLOCKER_ZONE=<zone-name>" >> .env

验证

bash

bdata budget    # 任何成功的响应都表明密钥有效

如果验证失败，则说明密钥错误、代理区域错误或账户无有效订阅——请将错误信息告知用户，而非自行猜测。

路径D — 无需安装即可使用Bright Data

当环境无法运行

npm

curl | bash

，或仅需一两次请求且不想安装CLI/SDK时使用此路径。适用于实时Agent操作和应用集成场景。

您仍需API密钥和代理区域。获取方式有两种：

用户手动粘贴：如果已有密钥，在环境中设置
```
BRIGHTDATA_API_KEY=...
```
和
```
BRIGHTDATA_UNLOCKER_ZONE=...
```
浏览器流程：完成路径C；控制台会生成密钥和代理区域

基础URL：

https://api.brightdata.com

身份验证头：

Authorization: Bearer $BRIGHTDATA_API_KEY

核心端点

http

# Web Unlocker — 从任意URL提取干净内容
POST /request
{
  "url": "https://target.com",
  "zone": "<unlocker-zone>",
  "format": "raw",
  "data_format": "markdown"   // 或 "html", "screenshot", "parsed_light"
}

http

# SERP API — 结构化搜索结果
# 使用相同的/request端点，搭配SERP代理区域和搜索URL，
# 添加`brd_json=1`参数以接收解析后的JSON而非原始HTML。
POST /request
{
  "url": "https://www.google.com/search?q=web+scraping&brd_json=1",
  "zone": "<serp-zone>",
  "format": "raw"
}

http

# Web Scraper API — 40+平台的结构化数据（异步）
POST /datasets/v3/trigger?dataset_id=<id>
[ { "url": "https://amazon.com/dp/B09V3KXJPB" } ]

# 然后轮询结果
GET  /datasets/v3/snapshot/<snapshot_id>?format=json

如需完整参数说明（如

x-unblock-expect

等特殊头、异步响应ID、数据集进度状态、Browser API的CDP命令），请查看

bright-data-best-practices

技能——其参考文档是REST操作的权威来源。

文档

产品文档：https://docs.brightdata.com
LLM友好型文档索引：https://docs.brightdata.com/llms.txt
控制台（代理区域、密钥、账单）：https://brightdata.com/cp

接入完成后 — 下一步

Agent设置完成后，将工作转向最符合需求的细分技能。快速指引：

用户需求…	对应技能
"抓取这个URL" / "获取这个页面"	`scrape`
"在Google上搜索…" / "查找关于…的URL"	`search`
"获取Amazon/LinkedIn/Instagram/TikTok/YouTube/Reddit数据"	`data-feeds`
"为<站点>构建抓取工具"	`scraper-builder`
"分析我的竞品" / "对比定价"	`competitive-intel`
"审计SEO" / "排名检查" / "Schema检查"	`seo-audit`
"用Python编写Bright Data代码"	`python-sdk-best-practices`
"将Bright Data接入我的LLM Agent"	`bright-data-mcp`
"使用CLI" / "从终端运行"	`brightdata-cli`
"调试Browser API会话"	`brd-browser-debug`

如有疑问，优先选择更具体的技能：对于支持平台，优先使用

data-feeds

而非

scrape

；对于多页面提取，优先使用

scraper-builder

而非

scrape

；当使用者是LLM Agent而非终端用户时，优先使用

bright-data-mcp

而非

brightdata-cli

。

agent-onboarding

NPX安装

标签

SKILL.md 内容（中文）

Bright Data — Agent 接入指南

安装

安装Agent技能（可选，推荐）

选择您的路径

路径A — 实时网页工具（CLI）

路径B — 将Bright Data集成到应用中

选择技术栈

设置凭据

编写实际代码前进行冒烟测试

路径M — MCP服务器（LLM工具层）

路径C — 获取API密钥（仅身份验证）

最简单方式：使用CLI的OAuth流程

手动方式：控制台

验证

路径D — 无需安装即可使用Bright Data

核心端点

文档

接入完成后 — 下一步