agent-onboarding

Bright Data — エージェントのオンボーディング

Bright Data を使うと、エージェントはオープンウェブに確実にアクセスできます。実際のブラウザーで取得したような SERP の結果、あらゆる URL から取得したクリーンな Markdown（CAPTCHA と JS に対応）、数千種類の事前構築済みスクレイパー（Amazon、LinkedIn、Instagram、TikTok、YouTube、Reddit、Crunchbase、…）による構造化データ、そして実際の操作が必要なページ向けの Browser API を利用できます。

このスキルは最初の入り口です。一度読み、進む経路を選んだら、その経路を担当する、より具体的なスキルに引き継いでください。

インストール

1 つのコマンドで CLI とエージェントスキルをインストールし、ブラウザーでの 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 つのコマンドで、次の処理が行われます。

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 がゼロ以外で終了した場合は、続行する前に Path C（認証）へ進んでください。
• どちらかがゼロで終了しても、出力に認証またはゾーンのエラー文字列（例：unauthorized、invalid api key、not logged in、no such zone、zone not found）が含まれている場合は、失敗として扱い、Path C へ進んでください。
• 両方のコマンドがゼロで終了し、認証済みのアカウントと cli_unlocker / cli_browser ゾーンが表示された場合にのみ、以下のいずれかの経路へ進んでください。

エージェントスキルをインストールする（任意、推奨）

CLI には、Bright Data のスキルをコーディングエージェントのスキルディレクトリに直接配置するインストーラーが付属しています。

# 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、…）。

経路を選択する

すべての経路で、上記と同じインストールと認証を行います。次に何をするかが異なります。

状況	経路
今のセッション中にウェブデータが必要	Path A — ライブ CLI ツール
アプリのコードに Bright Data を追加する必要がある	Path B — SDK / REST 統合
LLM エージェント向けのすぐに使えるツールレイヤーが必要	Path M — MCP サーバー
まず API キーが必要	Path C — 認証のみ
何もインストールしたくない	Path D — REST API を直接使用

複数の経路にまたがるタスクの場合は、順番に進めてください。認証 → ライブツールでの調査 → 全体像が明らかになってからアプリに統合。

---

Path A — ライブウェブツール（CLI）

エージェントが今すぐウェブデータを必要とする場合に使用します。URL の発見、クリーンなコンテンツの取得、既知のプラットフォームからの構造化レコードの取得、競合状況の簡易調査などが該当します。

インストールとログインが完了したら、用途を絞った次のスキルに引き継ぎます。

• brightdata-cli — コマンド全体の概要（scrape、search、 pipelines、zones、budget、config）
• search — bdata search による検索（Google／Bing／Yandex の SERP、構造化 JSON）
• scrape — 既知の URL からクリーンなコンテンツを取得する bdata scrape （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 を対象に、「どこが最安で、在庫があるか」を 1 つのランキング表にまとめます
• brand-listening — Reddit、X、TikTok、ニュース、レビューを横断して、ブランドについて人々が何を話しているかをまとめたソーシャルリスニング／センチメントのダイジェスト
• live-research — 複数のクエリで Discover を実行 → 重複を除去 → 出典を明記した調査ブリーフを作成
• seo-audit — サイトマップの分類に基づくライブ SEO 監査

ライブウェブ作業のデフォルトの流れ：

1. 発見が必要な場合は、まず検索します bdata search "query" --json
2. 対象サイトに対応するビルド済みスクレーパーがある場合は、次にパイプラインを使います — パースなしで構造化 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 があり、該当するプラットフォームパイプラインがない場合は、スクレイプします bdata scrape "https://example.com" -f markdown
4. ページでクリック、フォーム、ログインが本当に必要な場合に限り、Browser API を使います（bdata browser については brightdata-cli スキルを、browser-api のリファレンスについては bright-data-best-practices を参照してください）

タスクが「今すぐデータを取得する」から「アプリに組み込む」に変わったら、Path B に切り替えます。

---

Path B — Bright Data をアプリに統合する

コードから Bright Data を呼び出すアプリケーション、エージェント、ワークフローを構築し、.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
Playwright／Puppeteer を使う JS の多いページ／インタラクティブなページ	Browser API	bright-data-best-practices → browser-api.md
任意のサイト向けにカスタムスクレーパーを構築する	サイトの特性に応じて 4 つすべてから選択	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 を直接呼び出すか（エンドポイントは以下の Path D を参照）、CLI をライブラリとして npx @brightdata/cli 経由で使用します。

• プロキシへの直接アクセス（HTTP 通信を Bright Data の IP 経由でルーティング） → ネットワーク／プールの選択、brd-customer- のユーザー名形式、SSL CA のセットアップ、フレームワークとの統合については、proxy に引き継ぎます。

• LLM 向けのウェブ情報に基づく検索／RAG → rag-pipeline に引き継ぎます（Discover を検索／取り込みレイヤーとして使用）。

• LLM ツールレイヤー（Claude、ChatGPT など） → MCP サーバーを使用します（Path M）。

認証情報を設定する

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

まだキーをお持ちでない場合は、先に Path C を実行してください。

実際のコードを書く前にスモークテストを実行する

統合を本格的に進める前に、必ず Bright Data への実際のリクエストを 1 回実行してください。認証、ゾーン、クォータの問題がアプリのエラー処理に隠れる前に検出できます。

# 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 が出力されれば、接続できています。そうでない場合は、ゾーン名とキーを確認してください。

---

Path M — MCP サーバー（LLM ツールレイヤー）

Bright Data をツールとして呼び出す LLM エージェント（例：Claude Code、ChatGPT desktop、カスタムエージェントのループ）を利用する場合に使用します。MCP サーバーは、検索、スクレイピング、1,200 以上の組み込みスクレイパーによる構造化データの取得、ブラウザー自動化など、30 以上のツールを単一の URL 経由で提供します。

以下を使用して接続します。

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

すべてのツールはデフォルトで有効です。&groups=（scrapers、browser、advanced_scraping、geo）または &tools= を追加すると、使用するツールを絞り込めます。

ツールの選択とワークフローのパターンについては、bright-data-mcp スキルに引き継ぎます。このスキルでは、WebFetch／WebSearch を Bright Data MCP の同等機能に明示的に置き換えます。

MCP リクエストは Unlocker API 上で実行され、Path C で説明した同じ月間無料クレジットプールを使用します。MCP 専用の割り当てはありません。

---

Path 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 件につき 1 クレジット（Scraper Studio はページ読み込み 1 回につき 1 クレジット）です。
• Bright Data MCP サーバーのリクエストも同じプールを使用します。MCP は Unlocker API 上で実行されます。
• 入金がない状態でクレジットがなくなると、利用が停止されます。予期しない請求は発生しません。
• クレジットは毎月1 日にリセットされ、翌月に繰り越されません。
• **月間クレジットの対象外：**プロキシ製品と Browser API。これらには、支払い方法の追加後に別途、**1 回限りの 2 ドルのトライアル（7 日間）と5 ドルのボーナス（30 日間）**が適用されます。
• **対象外：**カスタム PAYG プランおよび事前コミットプラン。

最も簡単な方法：CLI の OAuth フローを使用する

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

これにより、サインアップまたはサインイン、キーの生成、ゾーンの作成、ローカル設定を 1 つの手順で行えます。手動の手順よりこちらを優先してください。

手動で行う方法：ダッシュボード

ウェブ UI を使う場合：

1. https://brightdata.com/cp にアクセスします（必要に応じてサインアップしてください）
2. Web Unlocker zone を作成します（「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 を使わずにリクエストを 1、2 回だけ実行したい場合に使います。ライブエージェントでの作業にも、アプリへの統合にも対応しています。

API キーとゾーンは引き続き必要です。取得方法は 2 つあります。

• 人間が貼り付ける — すでにキーがある場合は、環境に 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
• LLM 向けドキュメントのインデックス：https://docs.brightdata.com/llms.txt
• ダッシュボード（ゾーン、キー、請求）：https://brightdata.com/cp

---

オンボーディング後 — 次に進む先

エージェントのセットアップが完了したら、作業内容に合う最も専門的なスキルに振り分けます。簡単な対応表：

ユーザーの依頼…	スキル
「この 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- username」	proxy
「Bright Data を LLM エージェントに接続して」	bright-data-mcp
「CLI を使って」／「ターミナルから実行して」	brightdata-cli
「Browser API / Scraping Browser セッションをデバッグして」	brd-browser-debug

判断に迷った場合は、より具体的なスキルを選んでください。対応プラットフォームには scrape より data-feeds、複数ページの抽出には scrape より scraper-builder、利用者がターミナルの人間ではなく LLM エージェントの場合は brightdata-cli より bright-data-mcp を優先します。

混同しやすい組み合わせが 2 つあります。

• 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 は、消費者向けの購入調査（「この商品が最安値で在庫もあるのはどこか」）です。