/agent-onboarding

name: agent-onboarding
description: |
  Onboard an agent to Bright Data. Use when a coding agent first
  encounters Bright Data — for live web work (search, scrape,
  structured data), for wiring Bright Data into product code, for
  installing the agent skill bundle, or for getting an API key. One
  install command sets up the CLI, agent skills, and authentication.
  Routes the reader to the right path: live tools, app integration,
  MCP, auth-only, or direct REST without any install.
license: MIT
metadata:
  author: brightdata
  version: "1.1.0"

Bright Data — Agent Onboarding

Bright Data gives agents reliable access to the open web: SERP results that look like a real browser, clean markdown from any URL (with CAPTCHA + JS handled), structured datasets for 40+ platforms (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, Crunchbase, …), and a Browser API for pages that need real interaction.

This skill is the entry point. Read it once, pick a path, then hand off to the narrower skill that owns that path.

Install

One command installs the CLI **and** the agent skills, and walks the human through OAuth in the browser:

# 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>

Requires Node.js >= 20. After install, both `brightdata` and `bdata` (shorthand) are available.

Then authenticate **once**:

bdata login

This single command:

1. Opens the browser for OAuth (or use `bdata login --device` on headless / SSH machines) 2. Saves the API key locally — you never need to paste a token again 3. Auto-creates the required proxy zones (`cli_unlocker`, `cli_browser`) 4. Sets sensible default configuration

For non-interactive setups you can pass the key directly:

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

Verify the install before doing real work:

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

**Branch deterministically on the result** — don't eyeball it:

• If `bdata config` or `bdata budget` exits **non-zero**, route to Path C

(auth) before continuing.

• If either exits zero but its output contains an auth or zone error

string (e.g. `unauthorized`, `invalid api key`, `not logged in`, `no such zone`, `zone not found`), treat it as a failure and route to Path C.

• Only proceed to a path below when both commands exit zero **and** show

an authenticated account with the `cli_unlocker` / `cli_browser` zones.

Install agent skills (optional, recommended)

The CLI ships an installer that drops Bright Data skills directly into your coding agent's skill directory:

# 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

These are the skills you'll hand off to from the paths below (`scrape`, `search`, `data-feeds`, `scraper-builder`, `brightdata-cli`, `bright-data-mcp`, …).

Choose your path

All paths share the same install + auth above. The difference is what you do next.

| Situation | Path | |---|---| | Need web data **during this session** | **Path A** — live CLI tools | | Need to **add Bright Data to app code** | **Path B** — SDK / REST integration | | Want a **drop-in tool layer for an LLM agent** | **Path M** — MCP server | | Need an **API key first** | **Path C** — auth only | | Don't want to install anything | **Path D** — REST API directly |

If your task spans paths, do them in order: auth → live tools to explore → app integration once the shape is known.

---

Path A — Live web tools (CLI)

Use this when the agent itself needs web data right now: discovering URLs, fetching clean content, pulling structured records from a known platform, or running a quick competitive scan.

After install + login, hand off to the narrower skills:

• `brightdata-cli` — overall command surface (`scrape`, `search`,

`pipelines`, `status`, `zones`, `budget`, `config`)

• `search` — discovery via `bdata search` (Google / Bing / Yandex

SERP, structured JSON)

• `scrape` — clean content from a known URL via `bdata scrape`

(markdown / HTML / JSON / screenshot)

• `data-feeds` — structured records from 40+ supported platforms via

`bdata pipelines <type>` (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, Crunchbase, Google Maps, …)

• `discover-api` — intent-ranked semantic web search via

`bdata discover` (relevance-scored results + optional page content)

• `scraper-studio` — generate and run an AI-built scraper from a

plain-English description via `bdata scraper create` / `bdata scraper run`

• `competitive-intel` — packaged competitor / pricing / review /

hiring / SEO analyses on top of the CLI

• `price-comparison` — "where is this cheapest, in stock?" across

Amazon, Walmart, eBay, Best Buy, Google Shopping, into one ranked table

• `brand-listening` — social-listening / sentiment digest of what

people are saying about a brand across Reddit, X, TikTok, news, reviews

• `live-research` — multi-query Discover → dedup → a cited research brief
• `seo-audit` — sitemap-stratified live SEO audits

Default flow for live web work:

1. **Search first** when you need discovery `bdata search "query" --json` 2. **Pipelines next** if the target is a supported platform — you get structured JSON with no parsing `bdata pipelines amazon_product "https://amazon.com/dp/..."` 3. **Scrape** when you have a URL and no platform pipeline applies `bdata scrape "https://example.com" -f markdown` 4. **Browser API** only when the page truly needs clicks, forms, or login (see the `brightdat