browser

browser-harness

CDP によるブラウザーの直接操作。タスク固有の編集には agent-workspace/agent_helpers.py を使用してください。セットアップ、インストール、接続に関する問題については、install.md をお読みください。

ドメインスキル（agent-workspace/domain-skills/ 配下にある、コミュニティ提供のサイト別プレイブック）は、デフォルトでは無効です。有効にするには BH_DOMAIN_SKILLS=1 を設定してください。詳細は末尾のセクションを参照してください。

BH_DOMAIN_SKILLS=1 が設定されていて、タスクが特定のサイトに関するものなら、方法を考案する前に、対応する agent-workspace/domain-skills/<site>/ ディレクトリ内のファイルをすべて読んでください。

使用方法

browser-harness <<'PY'
new_tab("https://docs.browser-use.com")
wait_for_load()
print(page_info())
PY

• browser-harness として呼び出します。$PATH に含まれています。cd も uv run も不要です。
• 複数行のコマンドには、必ずヒアドキュメント形式を使用してください。Python の文字列や JavaScript のスニペット内で、シェルによって引用符が崩れるのを防げます。
• 最初のページ移動には goto_url(url) ではなく new_tab(url) を使用してください。goto はユーザーがアクティブにしているタブで実行され、作業内容を上書きします。

ツール呼び出しの形式

browser-harness <<'PY'
# any python. helpers pre-imported. daemon auto-starts.
PY

run.py は exec の前に ensure_daemon() を呼び出します。手動で起動または停止する必要はありません。

リモートブラウザー

並列サブエージェントを実行する場合（各エージェントは異なる BU_NAME を使って、独立したブラウザーを取得します）、またはヘッドレスサーバーで実行する場合は、リモートを使用してください。BROWSER_USE_API_KEY を設定する必要があります。start_remote_daemon、list_cloud_profiles、list_local_profiles、sync_local_profile は事前にインポートされています。

browser-harness <<'PY'
start_remote_daemon("work")                               # default — clean browser, no profile
# start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
# start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
# start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
# start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
PY

BU_NAME=work browser-harness <<'PY'
new_tab("https://example.com")
print(page_info())
PY

start_remote_daemon は liveUrl を出力し、（GUI が検出された場合は）ローカルブラウザーで自動的に開くため、ユーザーは操作を確認できます。ヘッドレスサーバーでは URL のみが出力されます。URL をユーザーと共有してください。デーモンはシャットダウン時にクラウドブラウザーへ PATCH を送信して停止させ、これによってプロファイルの状態が保持されます。リモートデーモンはタイムアウトまで課金されます。

プロファイル（Cookie のみのログイン状態）は interaction-skills/profile-sync.md に記載されています。list_cloud_profiles()、チャットで「どのプロファイルか」を確認するパターン、ローカルの Chrome プロファイルをアップロードする sync_local_profile() について説明しています。

操作スキル

ページの操作中に特定の仕組みで行き詰まった場合は、interaction-skills/ にあるヘルパーを確認してください。ダイアログ、タブ、ドロップダウン、iframe、アップロードなど、再利用可能な UI 操作を扱っています。利用可能な操作スキルは次のとおりです。

• connection.md
• cookies.md
• cross-origin-iframes.md
• dialogs.md
• downloads.md
• drag-and-drop.md
• dropdowns.md
• iframes.md
• network-requests.md
• print-as-pdf.md
• profile-sync.md
• screenshots.md
• scrolling.md
• shadow-dom.md
• tabs.md
• uploads.md
• viewport.md

実際に機能する方法

• まずスクリーンショットを撮ります。capture_screenshot() を使って現在のページをすばやく把握し、表示されている対象を見つけ、クリック、セレクター、または追加のページ移動が必要か判断してください。
• クリックするには、capture_screenshot() → 画像上のピクセル位置を読み取る → click_at_xy(x, y) → capture_screenshot() の順に実行して確認します。「まず要素を探してからクリックする」という Playwright の習慣は抑えてください。getBoundingClientRect もセレクター探しも不要です。対象の表示位置が分からない場合（非表示の入力欄や 0×0 のノード）に限り、DOM を使用します。ヒットテストは Chrome のブラウザープロセス内で行われるため、追加の作業なしで iframe／shadow DOM／クロスオリジンを経由してクリックできます。
• 大量の HTTP リクエスト：http_get(url) と ThreadPoolExecutor を組み合わせます。静的なページにブラウザーは不要です（Netflix のページ 249 件を 2.8 秒で処理できます）。
• goto の後は wait_for_load() を呼び出します。
• タブが違う、または古い場合：ensure_real_tab() を使用します。現在のタブが古い、または内部的なタブの場合に使ってください。デーモンも次回の呼び出し時に古いセッションから自動復旧します。
• 確認：print(page_info()) が、ページが動作しているかを確認する最も簡単な方法です。ただし、表示されている操作が実際に機能したかどうかは、通常、スクリーンショットで確認します。
• DOM の読み取り：スクリーンショットを見て座標操作が適切でない場合は、js(...) を使って調査や情報の抽出を行います。
• iframe を使うサイト（Azure blades、Salesforce）：click_at_xy(x, y) はそのまま通過します。座標クリックが適切でない場合に限り、iframe の DOM を操作してください。
• 認証画面：ログイン画面にリダイレクトされた場合は、そこで停止してユーザーに確認してください。スクリーンショットから認証情報を入力しないでください。
• ヘルパーで対応できない操作には、生の CDP を使用します：cdp("Domain.method", params)。

設計上の制約

• クリックは座標指定をデフォルトにします。Input.dispatchMouseEvent はコンポジター層で iframe／シャドウ DOM／クロスオリジンを通過します。
• ユーザーが実行中の Chrome に接続します。独自のブラウザーは起動しません。
• cdp-use は CDPClient.send_raw にのみ使用します。型付きラッパーより、生の CDP 文字列を優先します。
• run.py は小さく保ちます。argparse、サブコマンド、追加の制御レイヤーは使用しません。
• コアヘルパーは短く保ちます。タスク固有のヘルパーは agent-workspace/agent_helpers.py に追加します。デーモン／ブートストラップとリモートセッションの管理はコアパッケージに配置します。
• 管理レイヤーは追加しません。リトライ用フレームワーク、セッションマネージャー、デーモンスーパーバイザー、設定システム、ロギングフレームワークは追加しません。

注意点（実地検証済み）

• オムニボックスのポップアップは偽のページターゲットです。実際のタブが必要な場合は、chrome://omnibox-popup... やその他の内部ページを除外します。
• CDP のターゲット順は、Chrome で表示されるタブストリップの順序とは異なります。ユーザーが「表示されている最初／2 番目のタブ」を指している場合は、UI オートメーションを使用します。Target.activateTarget で表示できるのは、既知のターゲットのみです。
• デフォルトのデーモンセッションは古くなることがあります。ensure_real_tab() は実際のページに再接続します。
• Browser Use API では、ワイヤー上のキーはキャメルケースです。cdpUrl、proxyCountryCode などです。
• リモートの cdpUrl は HTTPS であり、ws ではありません。/json/version 経由で WebSocket URL を解決します。
• クラウドブラウザーを停止するには、PATCH /browsers/{id} と {"action":"stop"} を使用します。
• 重要なアクションのたびに、成功したと決めつける前にスクリーンショットを撮り直します。画像を使って、状態の変化、開いたメニュー、ページ遷移、表示されたエラー、ページが想定した状態になっているかを確認します。
• スクリーンショットを使って操作方法を探ります。次にクリックする対象を見つけ、隠れた障害に気づき、セレクターを書く価値があるか判断するうえで、多くの場合これが最も速い方法です。
• フレームワーク固有のハックより、コンポジター層の操作を優先します。DOM 固有の回避策を追加する前に、スクリーンショット、座標クリック、生のキー入力を試します。
• フレームワーク固有の DOM 技巧が必要な場合は、まず interaction-skills/ を確認します。ドロップダウン、ダイアログ、iframe、シャドウ DOM、フォームに関するガイダンスは、ここに記載します。

ドメインスキル（オプトイン）

BH_DOMAIN_SKILLS=1 の場合にのみ適用されます。それ以外の場合は無視してください。agent-workspace/domain-skills/ は休止状態で、goto_url にスキルファイルは表示されません。

有効にした場合、アプローチを考案する前に agent-workspace/domain-skills/<host>/ を検索します。goto_url は、遷移先ホストのスキルファイル名を最大 10 件返します。

非自明な情報（プライベート API、安定したセレクター、フレームワークの癖、URL パターン、隠れた待機条件、サイト固有の落とし穴など）を見つけた場合は、agent-workspace/domain-skills/<site>/ に PR を作成します。サイトの永続的な構造（記録ではなく地図）をまとめます。ピクセル座標（レイアウト変更で壊れます）、タスクのナレーション、秘密情報は記載しないでください。このディレクトリは公開されています。