run-agent-browser

run-agent-browser

agent-browserをライブターミナルREPLとして操作します。コマンドを1つ実行し、結果を読み取ってから、次の操作を決めます。ユーザーから再利用可能なハーネスを求められていない限り、場当たり的なブラウザー操作をスクリプトや&&で連結しないでください。

次の手段に進み、行き詰まらないようにします。 あるティアで失敗したら、原因を一度診断してから次のティアに進みます。すべての自動化ティアで失敗した場合は、そこで「できません」と止めず、認証情報／CDP URL／デプロイの判断をユーザーに求めてください。

権限

agent-browser skills get core
agent-browser COMMAND --help
agent-browser --version

構文については、インストール済みCLIのヘルプを優先します。このスキルでは、このホストでの実行時の選択と失敗時のエスカレーションを扱います。

優先順位（必ずティア1から開始）

ティア	場合	方法
1. ローカル環境	新しいタスクでは常にデフォルト	プロバイダーの環境変数を解除し、ステルス用引数でローカルのChromeを起動
2. Steel CDP	ティア1が失敗した場合（Chromeがない、ディスプレイやサンドボックスの問題がある場合、またはユーザーがマネージドCDPを求めた場合）	Steel環境変数を読み込み、--cdpで接続。詳細はreferences/cdp-and-steel.mdを参照
3. クラウドプロバイダー	ティア2が失敗した場合、または利用できない場合	Browser Use → Kernel → Browserless → Browserbase（またはユーザー指定のプロバイダー）。Browser UseでCDP WebSocket connect failed: HTTP error: 400 Bad Requestが返された場合は、再試行せずにスキップして次に進みます（下記のティア3を参照）。詳細はreferences/providers.mdを参照
4. ユーザーに確認	すべてのティアで失敗した場合、または認証情報がない場合	CDP URL、プロバイダーキー、またはインストール／デプロイの承認を求め、その後設定して再試行

特別なケース（明確に必要な場合に限り、優先順位をスキップします）：

必要なもの	方法
公開URLのテキストのみ	agent-browser read URL（ブラウザー不要）
Google AI Overview／AI Mode／Geminiのキャプチャ	PatchrightスクレイプAPI — references/managed-cdp-pool.md（CDPではありません）
既存の認証情報がある、ユーザーが起動したChrome	--auto-connectまたはconnect <port|url> — references/cdp-and-steel.md
Electron／Slack／AgentCoreサンドボックス	agent-browser skills get <name>の専用スキル

ステルスをデフォルトにする（すべてのティア）

常に自動化対策のデフォルトを優先します。公式のagent-browser-plugin-stealth npmパッケージは存在しません（404）。組み込み機能とプロバイダーのステルスフラグを使用してください。

# Local / Steel launch args (tier 1; also apply when launching unmanaged Chrome)
STEALTH_ARGS='--disable-blink-features=AutomationControlled'

# Browserless: stealth ON by default (BROWSERLESS_STEALTH=true)
# Kernel: stealth OFF by default — always set KERNEL_STEALTH=true for this skill
# Proxy (optional, all tiers): --proxy "$AGENT_BROWSER_PROXY" when configured

プロキシのパスワード、APIキー、Cookieの値をコマンド出力、コミット、チャットに記載しないでください。

ティア1 — ローカル環境（ここから開始）

新しいzshシェル（この環境のデフォルト）では、rcファイルからプロバイダー環境変数が自動的に読み込まれることはありません。一方、.bashrcはagent-browser-kernel.envを自動的に読み込みます（AGENT_BROWSER_PROVIDER=kernel）。ティア3の作業中にプロバイダーのファイルを手動でsourceすると、その変数はシェルを使い続ける間、エクスポートされたままになります。どのシェルを使っているか、直前にどのコマンドを実行したかにかかわらず、ティア1では必ずこの変数を解除してください。 解除しないと、気づかないうちにローカルのChromeではなくクラウドプロバイダーを使ってしまいます。

SESSION="local-$(agent-browser session id --scope cwd --prefix task)"

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" \
  --args "--disable-blink-features=AutomationControlled" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" get title
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" close

次の症状が見られた場合は、ティア1での失敗とみなしてエスカレーションしてください。Chrome／Chromiumが見つからない、ディスプレイ／Xvfbのエラー、サンドボックス／--no-sandboxのクラッシュ、CDPのバインド失敗、DOMのない空白ページが繰り返し表示される、またはユーザーのマシンにローカルブラウザーがない（CI、リモート専用のノートPCなど）。

エラーがCannot use --cdp and -p/--provider togetherの場合、ティアを混在させています。CDPを使う場合は-p／AGENT_BROWSER_PROVIDERを外すか、プロバイダーを使う場合は--cdpを外してください。

ティア2 — Steel CDP（このフリート上でセルフホスト）

エンドポイントの変更や接続失敗の診断を行う前に、**references/cdp-and-steel.md**を読んでください。簡単な手順は次のとおりです。

source "$HOME/.config/steel-browser-cdp.env"   # no-op if missing — then ask user / deploy
# If STEEL_AGENT_BROWSER_CDP is empty: ask user for a CDP websocket URL, or offer to deploy Steel
# (deploy path: Coolify compose in crawler-service/deploy/steel-browser/ — use deploy-coolify-cloud skill)

SESSION="steel-$(agent-browser session id --scope cwd --prefix task)"

# Optional clean slate (Steel is single-session / shared page — see reference)
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" close
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true   # full reset; close only detaches

重要なSteelの仕様（必ず確認してください）： Chromiumを共有しており、実質的に使えるページは1つです。Steelのタスクは直列に実行してください。--sessionで分離されるのはデーモンの状態のみです。closeは接続を切り離し、POST …/v1/sessions/releaseはリセットします。完全な仕様、ポート、tailnet URL、トラブルシューティングについては、references/cdp-and-steel.mdを参照してください。

次の場合はティア3にエスカレーションしてください。環境変数ファイルがなく、ユーザーもCDP URLを持っていない場合、health／/json/versionが失敗する場合、復旧を1回試した後も接続が拒否される場合、またはSteelの直列化によって必要な並列タスクを実行できない場合。

ユーザーが生のCDPリンク（ホストは問いません）のみを持っている場合は、そのURLを使ってティア2の方法で接続してください。

env -u AGENT_BROWSER_PROVIDER agent-browser --session cdp-user --cdp "$USER_SUPPLIED_CDP_WS" open https://example.com

Tier 3 — クラウドプロバイダー（確認、設定、再試行）

環境ファイル、ステルスのデフォルト設定、インストールについては references/providers.md を読んでください。ユーザーがプロバイダーを指定していない場合の優先順位は次のとおりです。

1. Browser Use（-p browseruse）— このホストにキーがすでに設定されていることが多いですが、利用する前に下記の既知の問題に関する注記を確認してください
2. Kernel（-p kernel）— KERNEL_STEALTH=true を設定してください。このホストで動作確認済みです
3. Browserless（-p browserless）— デフォルトでステルスが有効です。このホストで動作確認済みです
4. Browserbase（-p browserbase）— キーが設定されている場合、またはユーザーから提供された場合のみ

既知の問題（このホスト、agent-browser 0.33.2、2026-08-03 に確認）： -p browseruse は、セッション名を変更しても、-v／--debug の有無を変えても、新しいシェルを使っても、ドキュメントに記載された構文をそのまま使っても、毎回 ✗ CDP WebSocket connect failed: HTTP error: 400 Bad Request で確実に失敗します。キーの問題ではありません。認証済み API プローブは 200 を返し、生の API を使ったセッション作成も成功します。また、返された webSocketDebuggerUrl は生の WebSocket アップグレードを直接受け付けます。そのため、問題はアカウントやネットワークではなく、agent-browser 内部の Browser Use 接続処理にあります。-p browseruse での 400 Bad Request が一度でも発生したら、既知の失敗シグナルであり、一時的な障害ではありません。再試行せず、すぐに Kernel に切り替えてください。

# Example: Browser Use (do NOT print the key)
source "$HOME/.config/agent-browser-browseruse.env"   # if present
# If BROWSER_USE_API_KEY empty → ask user for the key; write to that env file (chmod 600); source; retry
# If it returns "CDP WebSocket connect failed: HTTP error: 400 Bad Request" → known-broken on this host, skip to Kernel

SESSION="prov-$(agent-browser session id --scope cwd --prefix task)"
env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" -p browseruse \
  open https://example.com

コマンドでは常に -p <name> を明示してください（セッション全体でグローバルな AGENT_BROWSER_PROVIDER の設定が維持されることに頼らないでください。後で Steel／CDP が動作しなくなります）。-p と --cdp は併用しないでください。

プロバイダーのキーがない場合： 使用するプロバイダーと API キー（またはダッシュボードへの招待）をユーザーに尋ねてください。次の対応を提案してください。

• ~/.config/agent-browser-<provider>.env（chmod 600）と、保護された ~/.zshrc の source 行を書き込む
• references/providers.md にあるプロバイダーのダッシュボード URL を開く
• 設定後、失敗した手順を再実行する

キーを捏造しないでください。キーの値をチャット、コミット、ログに貼り付けないでください。「キーが設定されているか／長さのみ」で確認してください。

Tier 4 — それでもブロックされる場合

次のいずれか1つをユーザーに求めてから、該当する Tier の設定を行って再試行してください。

1. CDP WebSocket URL（ws://／wss://）または既存の Chrome の host:port
2. プロバイダー名と API キー（Browser Use／Kernel／Browserless／Browserbase）
3. ローカルの Chrome／agent-browser のインストール許可（npm i -g agent-browser、agent-browser install）
4. セルフホスト可能な Steel のデプロイ許可（このフリートでは、deploy/steel-browser/ 配下の Coolify compose を使用）

コアとなる操作ループ（全 Tier 共通）

フロー内のすべてのコマンドで同じランタイムプレフィックスを使用してください。

# PREFIX is tier-1 env -u … --session … --args …   OR tier-2 … --cdp …   OR tier-3 … -p <name>
$PREFIX open https://example.com
$PREFIX snapshot -i          # refs like @e3 — never @ref=e3
$PREFIX click @e3
$PREFIX wait --url "**/expected"
$PREFIX snapshot -i          # refs stale after navigation — always re-snapshot
$PREFIX get url
$PREFIX get title
$PREFIX errors
$PREFIX close

操作の成功とは別に、結果を確認してください。視覚的な証拠が重要な場合はスクリーンショットを撮ってください。

ヘルパー

パス	用途
scripts/check-agent-browser-version.sh	読み取り専用の CLI、Steel、プールの健全性確認
scripts/inspect-page.sh	Steel のページ取得ハーネス
assets/templates/*.sh	再利用可能なワークフロー（ユーザーがハーネスを求めた場合のみ）
references/cdp-and-steel.md	Steel のエンドポイント、単一セッションのセマンティクス、リリース、テールネット、CDP 接続
references/providers.md	Browser Use／Browserbase／Browserless／Kernel の設定、ステルス、認証情報
references/managed-cdp-pool.md	Patchright の Google AI／Gemini スクレイピング API
references/commands.md	日常的なコマンドのルーティング
references/sessions-and-refs.md	Refs、タブ、復元、認証情報ボールト
references/safety.md	復旧手順、共有ランタイムの安全性
references/trust-boundaries.md	シークレット、インジェクション、外部への操作
references/advanced.md	プロキシ、記録、エンジン、React

出力要件

最終 URL／タイトルとユーザーに見える結果を報告してください。実行した Tier（およびエスカレーションがあればその内容）、セッション名、決定論的なチェック、実施したクリーンアップ（使用した場合は Steel の sessions/release を含む）、アーティファクトとその機密性、要求した認証情報または書き込んだファイル（名前のみ。値は記載しない）、およびユーザーに委ねたインストール／デプロイの推奨事項を報告してください。