agent-browser
作成者 vercel-labsagent-browser は、AI エージェントやシェルスクリプトから利用できる Chrome/Chromium 自動化用の CLI です。ページを開く、遷移する、クリックする、フォーム入力、スナップショット取得、スクリーンショット撮影、動画録画、パフォーマンス計測、セッション管理、認証処理など、ブラウザーを使ったエンドツーエンドのワークフローを自動化できます。
Overview
What is agent-browser?
agent-browser は、AI エージェントやシェルベースのワークフロー向けに設計されたコマンドラインのブラウザー自動化ツールです。Chrome DevTools Protocol (CDP) 経由で Chrome / Chromium に直接接続し、ターミナルやエージェントの実行環境から、本物のブラウザー操作をスクリプトとして実行できます。
agent-browser を使うと、次のような操作を自動化できます:
- Web ページを開く・遷移する（
agent-browser open <url>） - 構造化されたスナップショットを通じて、インタラクティブな要素を発見
- ボタンをクリック、リンクをたどる、フォームと対話
- 入力欄を埋める、文字を入力する、キー入力を送信
- ページ構造や利用可能なアクションを理解するためのスナップショット取得
- セッションを管理し、ログイン済み状態を保持
- 認証フローの実行（OAuth や、人の手を交えた 2FA などを含む）
- プロキシを使った地域別テストや社内ネットワークでの利用
- プロファイリング用のパフォーマンストレース取得
- デバッグやドキュメント向けにブラウザーセッションの動画を録画
Who is agent-browser for?
agent-browser は、次のようなケースに適したツールです:
- 実ブラウザーを制御する必要のある AI エージェントや自動化フレームワークを運用している
- CLI を起点に Chrome/Chromium のワークフローを自動化したい
- コンパクトな
@refsを使った、LLM にフレンドリーな堅牢な要素指定が必要 - ログインフロー、フォーム送信、複数ステップの Web アプリ操作を自動化したい
- テストやデモ、デバッグセッションを、再現性のある動画やトレースとして記録したい
とくに有用なのは、次のようなシナリオです:
- ブラウザー自動化: ナビゲーション、クリック、フォーム入力のスクリプト化
- ワークフロー自動化: 「ログイン → 遷移 → レポート出力」といったエンドツーエンドのシーケンス
- テスト自動化: Web アプリのスモークテスト、リグレッションチェック、パフォーマンス計測
When agent-browser is and is not a good fit
次のような場合に agent-browser の利用が適しています:
- ローカルで CLI を実行でき、Chrome または Chromium にアクセスできる
- AI エージェントから制御しやすい、決定的でスクリプト可能なブラウザー挙動が欲しい
- セッション、Cookie、認証を細かくコントロールする必要がある
逆に、次のようなケースでは適さない場合があります:
- ホスト環境に Chrome/Chromium をインストール・実行できない
- 必要なのは生の HTML やシンプルな HTTP リクエストのみ（純粋な HTTP クライアントやスクレイパーのほうが簡単）
- 特定の言語やランタイムで、他のブラウザー自動化ライブラリと密に統合されたヘッドレスブラウザー制御が必要
How to Use
Installation options
agent-browser には複数のインストール方法があります。環境に合ったものを選んでください:
-
npm (Node.js)
npm i -g agent-browser -
Homebrew (macOS/Linux)
brew install agent-browser -
Rust / Cargo
cargo install agent-browser
CLI をインストールしたら、組み込みの Chrome セットアップを実行します:
agent-browser install
これにより、互換性のある Chrome/Chromium ビルドがダウンロードされ、agent-browser から操作できるように設定されます。新しいバージョンが利用可能になったら、次でアップデートします:
agent-browser upgrade
agent-browser をエージェントプラットフォームの skill として使う場合は、次のように追加することもできます:
npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser
最新の skill 向け接続方法については、リポジトリ内の SKILL.md を確認してください。
Core browser automation workflow
agent-browser を使ったワークフローは、基本的に open → snapshot → interact → re-snapshot というシンプルなループで構成されます。
-
ページへ移動する
agent-browser open https://example.com/form -
スナップショットを取得して要素を見つける
インタラクティブスナップショットモードを使うと、@refs付きのクリック・入力可能な要素一覧をコンパクトに取得できます:agent-browser snapshot -i出力例（簡略化）:
@e1 [input type="email"] @e2 [input type="password"] @e3 [button] "Submit" -
refs を使って操作する
agent-browser fill @e1 "user@example.com" agent-browser fill @e2 "password123" agent-browser click @e3 -
待機して再度スナップショットを取得する
agent-browser wait --load networkidle agent-browser snapshot -i
このパターンにより、AI エージェントは DOM 全体ではなくコンパクトな構造ビューを扱えるため、コンテキスト消費を大きく抑えられます。
Command reference basics
agent-browser には多くのコマンドが用意されています（references/commands.md を参照）。代表的なものは次のとおりです:
-
Navigation
agent-browser open <url> agent-browser back agent-browser forward agent-browser reload agent-browser close -
Snapshot and refs
agent-browser snapshot # full tree agent-browser snapshot -i # interactive elements only (recommended) agent-browser snapshot -c # compact output agent-browser snapshot -d 3 # limit depth agent-browser snapshot -s "#main" # scoped to CSS selector -
Interactions
agent-browser click @e1 agent-browser dblclick @e1 agent-browser hover @e1 agent-browser focus @e1 agent-browser fill @e2 "text" agent-browser type @e2 "text" agent-browser press Enter
@refs の生成方法や有効期間など、より詳しいガイドは references/snapshot-refs.md を参照してください。
Working with sessions and authentication
agent-browser は、認証済みブラウジングや複数セッションの管理機能を備えています。ログインフロー、複数アカウントのテスト、ロールごとのユーザー分離などに便利です。
-
名前付きセッション（
references/session-management.mdを参照）:# Session "auth": login flow agent-browser --session auth open https://app.example.com/login # Session "public": separate browsing agent-browser --session public open https://example.com各セッションは Cookie、ストレージ、キャッシュ、履歴がそれぞれ分離されています。
-
セッション状態の永続化:
# Save cookies and storage agent-browser state save ./auth-state.json # Restore later agent-browser state load ./auth-state.json agent-browser open https://app.example.com/dashboard -
認証パターン（
references/authentication.mdを参照）:- すでにログイン済みの Chrome（デバッグ有効）から Cookie をインポート
- スナップショットと
fill/clickを使って標準的なログインフォームを順番に処理 - Cookie ベース認証、HTTP Basic 認証、トークンリフレッシュの扱い
複雑な OAuth や 2FA フローでは、初回セットアップに人の介入が必要な場合がありますが、一度認証状態を保存してしまえば、その後は agent-browser がその状態を再利用できます。
Proxy support and network configuration
トラフィックをプロキシ経由で流したい場合（地域別テスト、レート制限対策、社内ネットワークなど）、references/proxy-support.md に記載されているオプションを利用します:
-
CLI フラグによる HTTP/HTTPS プロキシ指定
agent-browser --proxy "http://proxy.example.com:8080" open https://example.com -
環境変数による設定
export HTTP_PROXY="http://proxy.example.com:8080" export HTTPS_PROXY="https://proxy.example.com:8080" agent-browser open https://example.com -
SOCKS プロキシ
export ALL_PROXY="socks5://proxy.example.com:1080" agent-browser open https://example.com
Profiling and performance tracing
テスト自動化やパフォーマンス調査のために、agent-browser は Chrome のパフォーマンストレースを取得できます（references/profiling.md を参照）。
# Start profiling
agent-browser profiler start
# Run your scenario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000
# Stop and save trace
agent-browser profiler stop ./trace.json
生成された trace.json は Chrome DevTools（Performance タブ）や対応ビューアーで開き、JavaScript 実行、レンダリング、ユーザータイミングイベントなどを分析できます。
Video recording for debugging and documentation
agent-browser はブラウザーセッションを動画として録画できます。失敗している自動化のデバッグや、手順書用のハウツー動画作成に役立ちます（references/video-recording.md を参照）。
# Start recording
agent-browser record start ./demo.webm
# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
# Stop recording
agent-browser record stop
こうして生成した .webm ファイルは、ドキュメントへの埋め込み、チームメンバーとの共有、バグ報告への添付などに利用できます。
Using templates for common workflows
リポジトリの templates/ ディレクトリには、再利用しやすいワークフロー用のシェルスクリプトテンプレートが含まれています:
templates/form-automation.sh– フォーム入力と送信を行う構造化パターンtemplates/authenticated-session.sh– ログインとセッション状態の永続化の例templates/capture-workflow.sh– 複数ステップのフローをスナップショットや録画で記録するパターン
これらのスクリプトをコピーして自分の環境や CI ジョブ、エージェントパイプライン向けにカスタマイズできます。
FAQ
What problems does agent-browser solve compared to simple HTTP clients?
agent-browser は CDP 経由で実際の Chrome/Chromium インスタンスを制御します。そのため、次のようなケースに対応できます:
- クライアントサイドレンダリングや複雑な JavaScript
- ブラウザー API に依存するシングルページアプリケーション
- クリック・入力・キー操作などの実ユーザーに近いインタラクション
- 描画タイミングやレンダリング挙動、パフォーマンストレースの取得
単に基本的なエンドポイントから HTML や JSON を取得したいだけなら、HTTP クライアントで十分です。ブラウザー上でのユーザー操作を再現する必要がある場合には、agent-browser のほうが適した選択肢になります。
How do I install Chrome or Chromium for agent-browser?
npm、Homebrew、Cargo のいずれかで CLI をインストールしたら、次を実行します:
agent-browser install
これにより、agent-browser が CDP 経由で制御可能な互換 Chrome/Chromium がダウンロード・設定されます。新バージョンがリリースされたときは、次でアップデートします:
agent-browser upgrade
Can agent-browser reuse my existing logged-in browser session?
はい。references/authentication.md では、--remote-debugging-port を指定して Chrome を起動し、すでにログイン済みのセッションから Cookie をインポートする方法を説明しています。一度 Cookie を取り込んだら、agent-browser state save で認証状態を保存し、後から復元することで、ログインフローを繰り返す必要がなくなります。
Is agent-browser suitable for CI and automated testing?
はい。agent-browser は CLI ツールなので、Chrome/Chromium が利用可能であれば自動化環境や CI でも問題なく動作します。次のような用途に使えます:
- テストスイートの一部としてエンドツーエンドフローを実行
- ビルド中のパフォーマンストレース取得
- 失敗シナリオの動画録画
CI 環境では、ビルドイメージに合ったインストール方法（npm / Homebrew / Cargo）を選び、シェルスクリプトやエージェントフレームワークを通じてフローをスクリプト化してください。
How does agent-browser help AI agents work with complex pages?
agent-browser は DOM 全体をそのまま出力する代わりに、重要な要素（リンク、ボタン、入力欄など）に対して安定した @refs 付きのコンパクトなスナップショットを提供します。これによりトークン消費を大幅に削減しつつ、AI エージェントが次のような処理を行いやすくなります:
- ページ構造の理解
- ref を使った適切な要素の選択
click、fill、pressといった精度の高いコマンド発行
references/snapshot-refs.md では、refs の生成方法、再取得が必要になるタイミング、堅牢な自動化のベストプラクティスを解説しています。
Does agent-browser support proxies and corporate networks?
はい。CLI フラグ（--proxy）や環境変数（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY）を使って、HTTP / HTTPS / SOCKS プロキシを設定できます。references/proxy-support.md では、基本設定に加え、認証付きプロキシ、バイパスルール、トラブルシューティングのヒントなどを扱っています。
Where should I start in the repository to learn more?
agent-browser を深く理解するためのおすすめの読み進め方は次のとおりです:
- まずは
SKILL.mdで全体像とクイックスタートを把握 references/commands.mdでコマンド一覧とオプションを確認references/authentication.md、references/session-management.md、references/snapshot-refs.md、references/profiling.md、references/video-recording.mdで各トピックを掘り下げtemplates/ディレクトリにあるワークフロースクリプトを見て、自分のユースケースに合わせてカスタマイズ