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 (CAPTCHA and JS handled), structured datasets for 40+ platforms (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, Crunchbase, etc.), and a Browser API for pages needing real interaction.

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

intent

onboard a coding agent to Bright Data when it first encounters the platform, whether for live web work (search, scrape, structured data), app integration, MCP setup, auth-only flows, or direct REST calls. use this skill to understand what Bright Data does, install the CLI and agent skills in one command, authenticate via OAuth, and route to the right downstream skill based on the job. one command installs everything and handles browser-based login for interactive setups; headless and non-interactive alternatives exist for CI/CD and remote environments.

inputs

• Node.js >= 20 (required for CLI and agent skills)
• npm or similar package manager (for npm install -g path, optional if using curl | bash)
• Bright Data account (free tier available; need to sign up if not existing)
• Internet access and a browser (for OAuth flow; device-code alternative exists for headless)
• Environment one of: macOS / Linux / Windows, interactive terminal / headless SSH / CI/CD
• Optional: existing Bright Data API key (if bypassing signup, set BRIGHTDATA_API_KEY env var)
• Optional: existing OAuth token (if using the MCP server path, Path M, instead of CLI)

external connections:

• Bright Data OAuth server at https://cli.brightdata.com (for login / signup)
• Bright Data CLI installation endpoint at https://cli.brightdata.com/install.sh (curl | bash flow)
• npm registry (for npm install -g flow)
• Bright Data API at https://api.brightdata.com (for smoke tests and REST calls)
• Bright Data dashboard at https://brightdata.com/cp (manual key / zone creation, billing, account management)

procedure

step 1: install the CLI and agent skills

choose one of three install methods based on environment:

input: Node.js >= 20, npm available, internet access.

method A: macOS / Linux with curl (fastest).

curl -fsSL https://cli.brightdata.com/install.sh | bash

this downloads and runs a shell script that installs the CLI, registers the brightdata and bdata commands, and optionally prompts to add the CLI to PATH.

method B: npm (cross-platform, explicit).

npm install -g @brightdata/cli

installs the package globally; brightdata and bdata commands available after install.

method C: one-off, no install.

npx --yes --package @brightdata/cli brightdata <command>
npx --yes --package @brightdata/cli bdata <command>

runs the CLI directly without installing; adds ~5 seconds to first execution. suitable for CI/CD, containers, or testing before committing to a global install.

output: bdata command available in PATH; bdata --version returns a version string.

step 2: authenticate via OAuth (or device-code for headless)

input: bdata command available, internet access, Bright Data account (create one if needed at https://brightdata.com).

for interactive terminal (human at keyboard):

bdata login

this opens a browser window for OAuth (signup if no account), prompts to authorize, then returns to the terminal and saves the API key locally. skips any need to paste tokens by hand.

for headless / SSH / CI/CD (no browser):

bdata login --device

displays a device code and URL (e.g., https://brightdata.com/device?code=ABC123). human opens this URL in any browser, enters the code, authorizes, and the CLI receives the token. suitable for remote servers and automation.

for non-interactive environment with key already known:

bdata login --api-key <key>

or set the env var and skip login entirely:

export BRIGHTDATA_API_KEY=<your-key>

output after successful login:

• local config file created (usually ~/.brightdata/config.json or ~/.config/brightdata/config.json on Linux)
• BRIGHTDATA_API_KEY env var optionally set (human can add to .bashrc / .zshrc / .env if desired)
• two proxy zones auto-created: cli_unlocker and cli_browser

step 3: verify installation and auth before proceeding

input: bdata command available, login completed.

run three smoke tests:

bdata version

prints CLI version; confirms bdata is in PATH and executable.

bdata config

prints current config, authenticated account email, and active zones. if this fails, auth is broken; skip to decision point 1.

bdata zones

lists all zones on the account. must include cli_unlocker and cli_browser (created by bdata login). if missing, login did not complete; skip to decision point 1.

bdata budget

displays account balance and subscription status. any successful response means the API key works and the account is active. no response or 401 error means key is invalid or account is inactive; skip to decision point 1.

output: all four commands succeed with no errors. agent can proceed to path selection (step 4).

step 4: select a path based on the use case

input: installation and auth verified (step 3 passed).

read the table below and identify the closest match to the work ahead:

situation	path	next steps
agent needs web data right now (discover URLs, fetch clean content, pull structured records)	Path A: live CLI tools	hand off to brightdata-cli, search, scrape, data-feeds, competitive-intel, or seo-audit
building an app or workflow that calls Bright Data from code	Path B: SDK / REST integration	choose stack (Python SDK, Node REST, etc.); hand off to stack-specific skill (python-sdk-best-practices, bright-data-best-practices, etc.)
LLM agent (Claude, ChatGPT, custom loop) should call Bright Data as tools	Path M: MCP server	hand off to bright-data-mcp; connect to the MCP URL with your API token
human still needs to sign up, generate a key, or verify auth	Path C: auth only	follow the manual or CLI flows in section "path C" below
environment cannot run npm / curl, or only one or two REST calls needed	Path D: REST API directly	use curl, Python requests, or any HTTP client with the endpoints in section "path D" below

output: one path selected; proceeding to that section next.

step 5 (optional): install agent skills

input: bdata command available, path selected (step 4).

if using Path A (live CLI tools), install the agent-facing skills to your coding agent's skill directory:

bdata skill add

interactive picker; choose which skills to install and where to install them (detects common agent frameworks like Anthropic, LangChain, etc.).

or install a specific skill:

bdata skill add scrape
bdata skill add data-feeds
bdata skill add search
bdata skill add scraper-builder
bdata skill add competitive-intel
bdata skill add seo-audit

list all available skills:

bdata skill list

output: skill files (SKILL.md) copied to the agent's skill directory (e.g., ~/.agents/skills/, or the agent framework's default location). agent can now call these skills as instructions.

---

decision points

decision point 1: smoke tests fail (version, config, zones, or budget command fails or returns 401 / 403).

if bdata config fails or shows "no authenticated account", auth did not persist. this can happen if:

• OAuth was interrupted or the browser closed during login
• the API key is invalid or revoked
• the account has been deleted or suspended

branch A: retry interactive login.

bdata login

if this succeeds, re-run step 3 smoke tests. if it fails, move to branch B.

branch B: use non-interactive login with a known key. if the human has an existing Bright Data API key (from the dashboard at https://brightdata.com/cp), skip the browser flow:

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

re-run smoke tests. if still failing, the key is wrong; ask the human to verify the key in the dashboard or create a new one.

branch C: route to Path C (auth only). if both branches fail, the human is not ready to use Bright Data yet. skip ahead to section "path C" below and follow the manual dashboard flow or troubleshoot the account status.

---

decision point 2: user needs web data now vs. building an app.

this determines whether to use Path A (live CLI, immediate results) or Path B (app integration, code-based, slower setup but durable).

if agent is exploring or discovering data (one-off requests, ad-hoc searches, testing): use Path A. the CLI is fastest; results come back in seconds; no coding required.

if agent is building a product, workflow, or service that will call Bright Data many times: use Path B. set up the SDK or REST client once; reuse it across many requests.

if both apply (explore first, then integrate): do Path A first, confirm the data shape and quality, then move to Path B once the integration is clear.

---

decision point 3: environment cannot run Node.js / npm.

if npm is not available or Node.js is too old, the CLI installation fails.

branch A: use Path D (REST API). call the REST endpoints directly with curl, Python, or any HTTP client. does not require npm or Node.js. requires an API key and zone (from Path C if needed).

branch B: use a container or CI/CD image with Node.js. if the agent runs in Docker or CI/CD, layer Node.js into the image before running the install. example Dockerfile:

FROM node:20-alpine
RUN npm install -g @brightdata/cli
RUN bdata login --api-key $BRIGHTDATA_API_KEY
ENTRYPOINT ["bdata"]

branch C: contact Bright Data support for alternative SDKs. if neither is feasible, Bright Data may offer SDKs or pre-built binaries in other languages; check https://docs.brightdata.com.

---

decision point 4: LLM agent (Claude, ChatGPT, custom loop) is the consumer.

if the downstream consumer of Bright Data is an LLM (not a human or CLI script), use the MCP server (Path M) instead of the CLI or REST directly.

why: MCP exposes 60+ Bright Data tools as a standard tool layer, compatible with Claude Code, ChatGPT, and custom agent loops. the LLM can call tools like brightdata_search, brightdata_scrape, and brightdata_get_social_data without invoking the CLI manually.

branch A: use the MCP server. connect the LLM agent to https://mcp.brightdata.com/mcp?token=YOUR_BRIGHTDATA_API_TOKEN. hand off to bright-data-mcp skill for tool selection and workflow patterns.

branch B: fall back to REST or CLI if MCP is not supported. if the LLM framework does not support MCP, use Path B (SDK) or Path D (REST) and expose Bright Data calls as custom functions or tool definitions in the LLM's native tool format.

---

decision point 5: account has no active subscription or zero balance.

if bdata budget returns zero balance or "inactive subscription", the account cannot make requests.

branch A: purchase a subscription. visit https://brightdata.com/cp, choose a plan, and add payment. free tier is available with limits; paid tiers unlock higher volumes and more features.

branch B: request a trial or contact sales. for large deployments or special cases, contact Bright Data sales at https://brightdata.com/contact. they may offer a trial or custom arrangement.

branch C: use the browser API or MCP in read-only mode (if supported). some features may allow limited queries without active balance; check the feature-specific docs at https://docs.brightdata.com.

---

output contract

success: agent is onboarded and ready to use Bright Data. the following conditions are true:

1. CLI installed and available: bdata --version returns a semantic version (e.g., 2.1.3).
2. Authentication stored locally: bdata config prints an authenticated account email and no errors.
3. Proxy zones created: bdata zones lists at least cli_unlocker and cli_browser.
4. API key valid: bdata budget returns account balance and subscription status (non-zero balance and active subscription preferred).
5. path selected: the use case has been matched to one of Path A, B, M, C, or D. the human or agent has a clear next step.
6. optional: agent skills installed: if using Path A, bdata skill list shows one or more installed skills and no errors.

format of the output: plain text console output from bdata commands; no file is created by this skill. config is stored in the user's home directory (e.g., ~/.brightdata/config.json).

file locations:

• CLI config: ~/.brightdata/config.json (Unix/Mac) or %APPDATA%\brightdata\config.json (Windows)
• Agent skills (if installed): framework-dependent, e.g., ~/.agents/skills/ for Anthropic, ./skills/ for custom agents
• Environment variables (optional): .env, .bashrc, .zshrc, or CI/CD secret store

data format: JSON for config and budget queries; plain text for version and zones. MCP server (Path M) returns JSON-RPC 2.0 over WebSocket.

---

outcome signal

the human or agent knows the skill worked when:

1. all smoke tests pass with no errors:

   • bdata version prints a version number
   • bdata config shows an email address (authenticated) and exits cleanly
   • bdata zones lists cli_unlocker and cli_browser
   • bdata budget shows account balance and subscription status

2. the next downstream skill is clear: the human has read the path descriptions (Path A-D) and knows which section to hand off to. they can state: "we're doing Path A (live CLI)" or "Path B (SDK integration)" with confidence.

3. optional but confirming: a test request succeeds. if the human runs one of the examples from Path A, B, or D (e.g., bdata search "web scraping" --json or a REST curl call), the response comes back with data and no auth errors.

4. no further CLI debugging is needed. if any of the smoke tests fail, the decision point section above tells the human exactly which branch to take (retry login, use --api-key, check account status, etc.). the human does not have to guess.

5. credentials are safe and do not appear in logs or terminal history. the bdata login flow saves the API key to a local config file, not to the terminal or environment by default. if the human explicitly exports BRIGHTDATA_API_KEY, they understand they are doing so and manage it accordingly.

---

after onboarding, where to go next

once the agent is set up, route the work to the narrowest skill that fits:

user says	hand off to
"scrape this URL" / "get this page as markdown"	scrape
"search Google for…" / "find URLs about…"	search
"get Amazon / LinkedIn / Instagram / TikTok / YouTube / Reddit / Crunchbase data"	data-feeds
"build a scraper for " (multi-page, custom logic)	scraper-builder
"analyze my competitor" / "compare pricing" / "review analysis"	competitive-intel
"audit SEO" / "rank check" / "schema check" / "backlink audit"	seo-audit
"write Bright Data code in Python"	python-sdk-best-practices
"write Bright Data code in Node / TypeScript"	bright-data-best-practices
"plug Bright Data into my LLM agent (Claude, ChatGPT, etc.)"	bright-data-mcp
"use the CLI" / "run Bright Data from terminal" / "orchestrate via shell"	brightdata-cli
"debug a Browser API session" / "troubleshoot Playwright / Puppeteer"	brd-browser-debug

prefer the specific skill over the general one: data-feeds over scrape for supported platforms, scraper-builder over scrape for multi-page extraction, bright-data-mcp over brightdata-cli when the consumer is an LLM agent.

---

reference: Path A (live CLI tools)

use this when the agent itself needs web data right now. after install and login, hand off to:

• 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