agent-onboarding

Bright Data — Agent 入门

Bright Data 为 Agent 提供可靠的开放网络访问能力：呈现效果如同真实浏览器的 SERP 结果、来自任意 URL 的干净 Markdown（可处理 CAPTCHA 和 JS）、来自数千个预构建抓取器的结构化数据（Amazon、LinkedIn、Instagram、TikTok、YouTube、Reddit、Crunchbase，……），以及适用于需要真实交互的页面的 Browser API。

本技能是入门入口。阅读一次，选择一条路径，然后转交给负责该路径的专用技能。

安装

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

# macOS / Linux — fastest install
curl -fsSL https://cli.brightdata.com/install.sh | bash

# Cross-platform (or if you don't want the install script)
npm install -g @brightdata/cli

# One-off, no install
npx --yes --package @brightdata/cli brightdata <command>

需要 Node.js >= 20。安装后，即可使用 brightdata 和 bdata（简写）。

然后只需进行一次身份验证：

bdata login

这条命令会：

1. 打开浏览器进行 OAuth（或在无头 / SSH 机器上使用 bdata login --device）
2. 在本地保存 API 密钥——之后无需再粘贴令牌
3. 自动创建所需的代理区域（cli_unlocker、cli_browser）
4. 设置合理的默认配置

对于非交互式设置，可以直接传入密钥：

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

开始实际工作前，请验证安装：

bdata version
bdata config            # confirms auth + zones
bdata zones             # should list cli_unlocker, cli_browser
bdata budget            # confirms account + balance

根据结果进行确定性分流——不要凭直觉判断：

• 如果 bdata config 或 bdata budget 以非零状态码退出，请先转到路径 C（身份验证），再继续。
• 如果任一命令以零状态码退出，但其输出包含身份验证或区域错误字符串（例如 unauthorized、invalid api key、not logged in、no such zone、zone not found），则视为失败并转到路径 C。
• 只有当两个命令都以零状态码退出，且显示已验证身份的账户及 cli_unlocker / cli_browser 区域时，才能继续选择下方的路径。

安装 Agent 技能（可选，建议）

CLI 附带一个安装程序，可将 Bright Data 技能直接放入编码 Agent 的技能目录：

# Interactive picker — choose skills + target agent
bdata skill add

# Install a specific skill
bdata skill add scrape
bdata skill add data-feeds
bdata skill add competitive-intel

# See everything available
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、zones、budget、config）
• search — 通过 bdata search 发现内容（Google / Bing / Yandex SERP，结构化 JSON）
• scrape — 通过 bdata scrape 从已知 URL 获取干净内容 （markdown / HTML / JSON / 截图）
• data-feeds — 通过数千个预构建抓取器获取结构化记录，使用 bdata pipelines search / info / run（Amazon、 LinkedIn、Instagram、TikTok、YouTube、Reddit、Crunchbase、Google Maps，……）
• discover-api — 通过 bdata discover 进行按意图排序的语义网页搜索（相关性评分结果 + 可选的页面内容）
• scraper-studio — 通过纯英文描述生成并运行 AI 构建的抓取器，使用 bdata scraper create / bdata scraper run
• competitive-intel — 基于 CLI 的竞品 / 定价 / 评论 / 招聘 / SEO 分析套件
• price-comparison — 在 Amazon、Walmart、eBay、Best Buy、Google Shopping 中查找“哪里最便宜且有货？”，并汇总为一张排序表
• brand-listening — 汇总 Reddit、X、TikTok、新闻和评论中人们对某个品牌的评价与情绪
• live-research — 多查询 Discover → 去重 → 生成附有引用的研究简报
• seo-audit — 按站点地图分层进行实时 SEO 审核

实时网页任务的默认流程：

1. 需要发现内容时，先搜索 bdata search "query" --json
2. 如果预构建抓取器支持该网站，接着使用 Pipelines — 可直接获取结构化 JSON，无需解析。先查询，切勿猜测 dataset_id 或字段： bdata pipelines search "<site or data type>"，然后 bdata pipelines info <dataset_id> <method>，接着 bdata pipelines run <dataset_id> <method> "<url>"
3. 已有 URL 且没有适用的平台 Pipeline 时，使用 Scrape bdata scrape "https://example.com" -f markdown
4. 仅当页面确实需要点击、填写表单或登录时，才使用 Browser API（bdata browser 请参阅 brightdata-cli 技能，以及 bright-data-best-practices 中的 browser-api 参考文档）

当任务从“立即获取数据”转为“将其接入应用”时，切换到路径 B。

---

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

当你正在构建一个应用、Agent 或工作流，需要通过代码调用 Bright Data，并且需要在 .env 或运行时配置中设置 BRIGHTDATA_API_KEY（和一个 zone）时使用。

此路径需要回答的问题是：

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
使用 Playwright/Puppeteer 处理 JS 密集型 / 交互式页面	Browser API	bright-data-best-practices → browser-api.md
为任意网站构建自定义抓取器	根据网站结构选择上述四种 API	scraper-builder

选择技术栈

• Python → 使用官方 SDK

  pip install brightdata-sdk
  

  将客户端设置（异步/同步）、平台抓取器、SERP、数据集、Browser API 和错误处理交由 python-sdk-best-practices 处理。

• Node / TypeScript → 使用官方 JS/TS SDK

  npm install @brightdata/sdk
  

  将客户端设置（bdclient）、平台抓取器、SERP、Discover、数据集、Browser API、Scraper Studio 和错误处理交由 js-sdk-best-practices 处理。

• Shell / 其他语言 → 直接调用 REST API（下方路径 D 中列有端点），或通过 npx @brightdata/cli 将 CLI 用作库。

• 原始代理访问（通过 Bright Data IP 路由 HTTP） → 将网络/代理池选择、brd-customer- 用户名格式、SSL CA 设置和框架集成交由 proxy 处理。

• 基于 Web 信息的检索 / 大模型的 RAG → 将此任务交由 rag-pipeline 处理（Discover 作为检索/摄取层）。

• 大模型工具层（Claude、ChatGPT 等） → 使用 MCP 服务（路径 M）。

设置凭据

BRIGHTDATA_API_KEY=...
BRIGHTDATA_UNLOCKER_ZONE=cli_unlocker   # created automatically by `bdata login`
BRIGHTDATA_SERP_ZONE=cli_unlocker       # or a dedicated SERP zone

如果你还没有密钥，请先执行路径 C。

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

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

# Web Unlocker via REST
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 服务（大模型工具层）

当使用方是需要将 Bright Data 作为工具调用的大模型 Agent 时，请使用此方式（例如 Claude Code、ChatGPT 桌面版、自定义 Agent 循环）。MCP 服务通过单个 URL 提供 30 多种工具——搜索、抓取、来自 1,200 多个预构建抓取器的结构化数据，以及浏览器自动化。

连接方式：

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

默认启用所有工具。添加 &groups=（scrapers、browser、advanced_scraping、geo）或 &tools= 可限制工具范围。

将工具选择和工作流模式交由 bright-data-mcp 技能处理。该技能会明确使用 Bright Data MCP 对应项替代 WebFetch / WebSearch。

MCP 请求通过 Unlocker API 运行，并从路径 C 中所述的同一月度免费额度池扣除额度——MCP 没有单独的额度。

---

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

当用户仍需要注册、登录或生成密钥时，请使用此路径。如果 bdata config 已显示已通过身份验证的账号，或环境中已设置 BRIGHTDATA_API_KEY，则跳过此路径。

免费套餐——无需信用卡即可开始。 每个新账号每月可从一个共享额度池中获得 5,000 个免费额度（约 $7.50），因此你可以先构建和测试，无需预先存入任何资金。以下数字以文档为准： https://docs.brightdata.com/general/account/billing-and-pricing/free-tier

• Unlocker API、SERP API、Web Scraper API 和 Scraper Studio 共用一个额度池——每次请求/每条记录扣 1 个额度（Scraper Studio：每次页面加载扣 1 个额度）。
• Bright Data MCP 服务的请求也从同一额度池扣除——MCP 通过 Unlocker API 运行。
• 如果没有存入资金，额度用尽时会立即停止——绝不会产生意外账单。
• 额度在每月 1 日重置，且不会结转。
• 不包含在月度额度中：代理产品和 Browser API。这些产品使用单独的一次性$2 试用（7 天），添加付款方式后还可获得 $5 奖励（30 天）。
• **不适用的计划：**自定义 PAYG 和预承诺计划。

最简单：使用 CLI 的 OAuth 流程

bdata login            # browser-based OAuth
bdata login --device   # headless / SSH (device-code flow)

此流程一步即可完成注册或登录、生成密钥、创建区域和本地配置。优先使用此方式，而非手动流程。

手动操作：控制面板

如果用户更倾向于使用 Web 界面：

1. 前往 https://brightdata.com/cp（如有需要，请先注册）
2. 创建一个 Web Unlocker 区域（“Add” → “Unlocker zone”）
3. 从控制面板复制 API 密钥
4. 将其保存在应用读取机密信息的位置：

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

验证

bdata budget    # any successful response means the key works

如果验证失败，说明密钥错误、区域错误，或账户没有有效订阅 — 应向用户反馈错误，而不是猜测。

---

路径 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

核心端点

# Web Unlocker — clean content from any URL
POST /request
{
  "url": "https://target.com",
  "zone": "<unlocker-zone>",
  "format": "raw",
  "data_format": "markdown"   // or "html", "screenshot", "parsed_light"
}

# SERP API — structured search results
# Use the same /request endpoint with a SERP zone and a search URL,
# adding `brd_json=1` to receive parsed JSON instead of raw HTML.
POST /request
{
  "url": "https://www.google.com/search?q=web+scraping&brd_json=1",
  "zone": "<serp-zone>",
  "format": "raw"
}

# Web Scraper API — structured data from pre-built scrapers (async)
POST /datasets/v3/trigger?dataset_id=<id>
[ { "url": "https://amazon.com/dp/B09V3KXJPB" } ]

# then poll
GET  /datasets/v3/snapshot/<snapshot_id>?format=json

完整的参数范围（如 x-unblock-expect 等特殊标头、异步响应 ID、数据集进度状态、Browser API CDP 命令），请查阅 bright-data-best-practices 技能 — 其中的参考资料是 REST 层级操作的权威来源。

文档

• 产品文档：https://docs.brightdata.com
• 适用于大模型的文档索引：https://docs.brightdata.com/llms.txt
• 控制面板（区域、密钥、账单）：https://brightdata.com/cp

---

完成引导后 — 接下来做什么

设置好 Agent 后，将工作分配给最适用的专门技能。快速参考：

用户说……	技能
“抓取此 URL” / “获取此页面”	scrape
“在 Google 上搜索……” / “查找与……相关的 URL”	search
“查找与 相关且符合 的页面” / “语义 / 意图搜索”	discover-api
“获取 Amazon / LinkedIn / Instagram / TikTok / YouTube / Reddit 数据”	data-feeds
“为 构建爬虫”（我想要可运行且归我所有的代码）	scraper-builder
“根据描述生成爬虫” / “bdata scraper run”（AI 构建，无需编写代码）	scraper-studio
“分析我的竞争对手” / “竞争对手的定价策略” / “市场格局”	competitive-intel
“比较价格” / “购买 X 最便宜的地方” / “查询价格”（购物）	price-comparison
“大家在怎么评价我们” / “监控提及” / “品牌情绪”	brand-listening
“深入研究 ” / “撰写附有引用的简报”	live-research
“构建 RAG 管道” / “为我的 LLM 添加网页搜索” / “为我的模型提供依据”	rag-pipeline
“审计 SEO” / “排名检查” / “架构检查”	seo-audit
“让我的应用看起来像 ” / “复刻此设计”	design-mirror
“用 Python 编写 Bright Data 代码”	python-sdk-best-practices
“用 JS / TypeScript 编写 Bright Data 代码”	js-sdk-best-practices
“通过 Bright Data 代理路由请求” / “brd-customer- 用户名”	proxy
“将 Bright Data 接入我的 LLM Agent”	bright-data-mcp
“使用 CLI” / “从终端运行”	brightdata-cli
“调试 Browser API / Scraping Browser 会话”	brd-browser-debug

不确定时，优先选择更具体的技能：对于受支持的平台，选择 data-feeds 而非 scrape；对于多页面提取，选择 scraper-builder 而非 scrape；如果使用者是 LLM Agent 而不是终端前的用户，选择 bright-data-mcp 而非 brightdata-cli。

有两组技能容易混淆：

• scraper-builder 与 scraper-studio — scraper-builder 会编写归你所有、由你自行运行的爬虫（真实代码 + 选择器 + 分页）。scraper-studio 会根据 URL 和通俗的文字描述，生成由 AI 构建的 Bright Data 采集器；你可通过 bdata scraper create / bdata scraper run 运行 — 无需维护代码。
• competitive-intel 与 price-comparison — competitive-intel 用于分析竞争对手的定价策略和市场定位；price-comparison 用于消费者购物研究（“这款产品哪里最便宜且有货”）。