agent-browser: AIエージェント向けブラウザー自動化

agent-browser は、AIエージェント向けに設計された Apache-2.0 ライセンスのブラウザー自動化 CLI です。エージェントに Playwright プログラム全体を生成させる代わりに、ナビゲーション、操作、検査、状態、ネットワーク、可観測性の各操作をシェルコマンドとして公開します。永続的なネイティブデーモンが、これらのコマンド間でブラウザーを保持します。

このプロジェクトは、次の 3 つの考え方を組み合わせています。

コンパクトなアクセシビリティスナップショットにより、完全な DOM を送信せずに、モデルへページの構造化されたビューを提供する。
スナップショット参照により、後続のコマンドで要素を識別する。
長時間稼働するデーモンにより、ブラウザーのライフタイムを各 CLI プロセスのライフタイムから分離する。

2026 年 9 月 11 日時点の現行バージョンは 0.37.1 です。プロジェクトは速いペースで変更されるため、この記事でバージョンに依存する挙動を説明する箇所では、0.37.1 のソースリビジョンにリンクしています。

ブラウザー自動化にエージェント指向のインターフェースが必要な理由 #

Playwright などのライブラリは正確なブラウザー API を提供しますが、LLM 駆動のプロセスがそれらを直接利用すると、追加コストが発生します。

生成されたソースコードはコンテキストを消費し、ランタイムも必要とする。
生の DOM にはスクリプト、スタイル、非表示ノード、フレームワークが生成した構造が含まれるが、次のアクションに寄与することはほとんどない。
ある観測結果から生成した CSS セレクターは、再レンダリング後に無効になる可能性がある。
個別のスクリプトでは、ブラウザーとコンテキストのライフサイクルを明示的に管理する必要がある。

agent-browser はブラウザー自体ではなく、インターフェースを変更します。エージェントはコンパクトなツリーを観測し、操作を選択し、1 つのコマンドを実行して、再び観測します。

flowchart LR
    Goal[User Goal] --> Model[Agent]
    Model -->|open or snapshot| CLI[agent-browser CLI]
    CLI --> Daemon[Native Daemon]
    Daemon -->|CDP or WebDriver| Browser[Browser]
    Browser --> Daemon
    Daemon -->|Snapshot and Refs| Model
    Model -->|click @e2| CLI

モデルは引き続き実行内容を決定します。一方、CLI は安定したアクション語彙を提供し、ブラウザー状態を管理します。プロジェクト概要によれば、一般的なテキストスナップショットは約 200–400 トークンであるのに対し、完全な DOM は 3,000–5,000 トークンを使用します。これらは独立したベンチマークではなく、プロジェクトによる推定値です。しかし、その背景にある理由は明確です。アクセシビリティツリーは、エージェントが必要としない実装詳細の多くを省略するためです。

アーキテクチャ #

各呼び出しは小さな CLI クライアントを起動します。クライアントは引数を解析してネイティブ Rust デーモンと通信し、デーモンはブラウザーを所有または接続し、Chrome DevTools Protocol（CDP）経由でコマンドを送信します。

flowchart TB
    subgraph Commands[Short-Lived Processes]
        C1[open]
        C2[snapshot]
        C3[click]
    end

    Socket[Local IPC]
    Daemon[Persistent Rust Daemon]
    CDP[Chrome DevTools Protocol]
    Chrome[Chrome or Chromium]

    C1 --> Socket
    C2 --> Socket
    C3 --> Socket
    Socket --> Daemon
    Daemon --> CDP
    CDP --> Chrome

永続性が重要なのは、ログイン状態、開いているタブ、Cookie jar、インメモリのアプリケーション状態がシェルコマンド間で維持されるためです。デーモンは自動的に起動します。デフォルトでは、設定された復元状態を保存し、ローカルで所有するヘッドレスブラウザーを閉じ、コマンドまたはダッシュボード入力が 1 時間ない場合に終了します。ヘッド付きブラウザー、Safari と iOS の WebDriver セッション、CDP 経由で接続されたブラウザーには、デフォルトのシャットダウン動作は適用されません。タイムアウトは --idle-timeout または AGENT_BROWSER_IDLE_TIMEOUT_MS で設定できます。

現在のリリースはネイティブ Rust 実装を使用します。以前の Node.js および Playwright ベースのデーモンは削除されました。ネイティブパスが CDP と直接通信するため、主な対象は Chrome と Chromium です。プロジェクトは次も提供します。

CDP 互換の Lightpanda エンジン。ただし、ヘッド付きモード、拡張機能、永続プロファイルはありません。
Appium と XCUITest を介した iOS Simulator 上の Safari。
Browser Use、Browserbase、Browserless、Kernel、AWS Bedrock AgentCore 向けのクラウドブラウザープロバイダー。

バックエンドごとに利用可能な機能は同一ではありません。たとえば、注釈付きスクリーンショットは CDP パスでは動作しますが、Safari WebDriver パスでは動作しません。

agent-browser のインストールと実行 #

npm パッケージは、プラットフォーム固有のネイティブバイナリをインストールします。

npm install -g agent-browser
agent-browser install

agent-browser install は互換性のある既存のブラウザーを検出するか、Chrome for Testing をダウンロードします。Linux ホストでは、ブラウザーのシステム依存関係も要求できます。

agent-browser install --with-deps

その他に、npx、プロジェクトローカルの npm 依存関係、macOS の Homebrew、Cargo によるインストールもサポートされています。インストールされたデーモンに Playwright は必要ありません。npm 配布版は、ランチャーがネイティブバイナリを選択するため Node.js 24 を要件として宣言しています。一方、Homebrew でインストールしたバイナリには Node.js デーモンは必要ありません。リポジトリをビルドする場合は pnpm 11 と Rust が必要です。インストールガイドには、ブラウザーの検出、設定、デーモンファイル、プロバイダー接続、スクラッチのヘッドレス起動を確認する agent-browser doctor についても記載されています。

最小限の操作シーケンスは次のとおりです。

agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e2
agent-browser screenshot page.png
agent-browser close

CLI には 50 を超えるコマンドが含まれています。関連するグループには、ナビゲーション、フォーム、キーボードおよびポインター入力、タブ、フレーム、ファイル、Cookie、ストレージ、ネットワークルーティング、HAR キャプチャ、スクリーンショット、PDF 生成、動画録画、プロファイリング、差分比較があります。agent-browser read <url> は Chrome を起動せずにエージェントが読み取り可能なコンテンツを取得できます。また、agent-browser mcp は MCP stdio サーバーを介してコマンドサーフェスを公開します。

スナップショットと要素参照 #

snapshot は中心となる抽象化です。アクセシビリティツリーをシリアライズし、要素に参照を割り当てます。

text

@e1 [heading] "Documentation" [level=1]
@e2 [input type="search"] placeholder="Search"
@e3 [button] "Submit"

エージェントは CSS セレクターを推測せずに操作できます。

agent-browser fill @e2 "session persistence"
agent-browser click @e3

複数のフィルターにより、コンテキスト使用量を削減できます。

オプション	効果
`-i`, `--interactive`	インタラクティブ要素のみを含める
`-c`, `--compact`	空の構造要素を削除する
`-d`, `--depth`	ツリーの深さを制限する
`-s`, `--selector`	ツリーを CSS セレクターに限定する
`-u`, `--urls`	リンク先を含める

参照は、それを生成したページ状態に属します。ナビゲーションや意味のある DOM 変更によって参照は無効になるため、信頼性の高いエージェントは状態遷移のたびに再度スナップショットを取得します。

agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

分析、ストリーミング、ポーリングによってネットワークアクティビティが継続する可能性があるため、すべてのアプリケーションで networkidle を待つことが正しいとは限りません。利用可能であれば、観測可能なアプリケーション条件を優先してください。

agent-browser wait "#account-dashboard"
agent-browser wait --url "**/account"

snapshot のドキュメントでは、1 レベルの iframe 展開についても説明しています。子参照はフレームコンテキストを保持するため、別途フレームを切り替えなくても、アクセシブルな iframe 内の要素を操作できます。アクセシビリティツリーへのアクセスを妨げるクロスオリジンフレームは省略されます。

アクセシビリティは、すべての視覚的事実を表現するわけではありません。Canvas のコンテンツ、ラベルのないアイコン、重なり合う要素、レイアウトの欠陥にはピクセル情報が必要です。注釈付きスクリーンショットは、@e2 に対応する [2] などのラベルを重ねて表示します。

agent-browser screenshot --annotate page.png

したがって、スナップショットはセマンティックな操作を駆動し、セマンティクスだけでは不十分な場合にスクリーンショットが視覚的な証拠を提供します。

セッション、プロファイル、状態 #

名前付きセッションはブラウザーインスタンスを分離します。

agent-browser --session buyer open https://shop.example
agent-browser --session admin open https://admin.example
agent-browser session list

ローカルで管理される各セッションには、Cookie、ストレージ、履歴、認証状態が個別に存在します。同じ既存の Chrome に CDP 経由で接続されたセッションは例外です。この場合、それらは同じ Chrome インスタンスを共有し、異なるタブにバインドされます。--pin-tab を指定すると、バインドされたタブが閉じたときにセッションが別のタブへ暗黙的に移動するのを防ぎます。

3 つの永続化メカニズムは、それぞれ異なる問題を解決します。

メカニズム	目的
名前付きセッション	同時実行されるブラウザーインスタンスを分離する
`--profile`	ブラウザープロファイルをインポートする、または永続プロファイルディレクトリを使用する
`--state` または `--restore`	Cookie と Web Storage を保存して再読み込みする

セッション名だけでは、デーモンのシャットダウン後もデータは永続化されません。--session <name> と --restore を組み合わせると、自動的な状態の読み込みと定期的な保存が ~/.agent-browser/sessions/ 配下で有効になります。

状態ファイルには認証情報が含まれるため、ソース管理に入れてはなりません。64 文字の 16 進数である AGENT_BROWSER_ENCRYPTION_KEY を設定すると、復元状態を AES-256-GCM で暗号化できます。セッションガイドでは、プロファイルのコピー動作、自動保存のタイミング、有効期限、暗号化について説明しています。

設定とデプロイメントのバックエンド #

設定は、優先度の低いものから高いものへ次の順序で解決されます。

~/.agent-browser/config.json;
./agent-browser.json;
AGENT_BROWSER_* 環境変数; and
コマンドラインフラグ。

プロジェクトは公式 JSON Schemaを公開しているため、エディターまたは CI ジョブでプロジェクト設定を検証できます。

ローカル実行では、ヘッドレスまたはヘッド付きの Chrome を起動できます。--executable-path は特定の Chromium 系バイナリを選択します。--cdp は、ローカルポート、ws:// エンドポイント、または wss:// エンドポイントに接続します。

agent-browser --cdp 9222 snapshot
agent-browser --cdp "wss://browser.example/cdp?token=..." snapshot

プロバイダーモードでは、同じ CLI を維持したまま、ブラウザーインフラストラクチャをサポート対象のサービスへ移します。

BROWSERBASE_API_KEY=... \
  agent-browser --provider browserbase open https://example.com

リモート実行は CI やサーバーレス環境で有用ですが、信頼境界が変わります。プロバイダーの認証情報、ブラウザーセッションの保持、リージョンをまたぐ送信、プロバイダー側の起動動作が、デプロイメント上の考慮事項になります。CDP デバッグエンドポイントはブラウザーを広範に制御できるため、信頼されていないネットワークに公開してはなりません。

セキュリティには明示的な設定が必要 #

agent-browser のセキュリティ機能はすべてオプトインです。デフォルトの実行では、ナビゲーション、操作、出力が制限されません。したがって、本番デプロイメントではエージェントハーネスの一部として制御を定義する必要があります。

json

{
  "$schema": "https://agent-browser.dev/schema.json",
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": [
    "app.example.com",
    "*.app.example.com",
    "cdn.example.net"
  ],
  "actionPolicy": "./agent-browser-policy.json"
}

制限的なアクションポリシーでは、観測と通常のナビゲーションを許可しながら、コード実行とファイル転送を拒否できます。

json

{
  "default": "deny",
  "allow": [
    "navigate",
    "snapshot",
    "click",
    "scroll",
    "wait",
    "get"
  ]
}

制御は、それぞれ異なる脅威に対応します。

コンテンツ境界は、ページ由来の出力をランダムな nonce とオリジンメタデータで囲み、オーケストレーターが信頼されていないページテキストとツールのフレーミングを区別できるようにする。
ドメイン許可リストは、許可されていないナビゲーションとサブリソースをブロックし、サポート対象の Chromium セッションでは WebRTC を無効にする。
アクションポリシーは、eval、upload、download、network、state などのカテゴリを許可または拒否する。
確認は、選択したカテゴリをオーケストレーターまたは対話的な承認の対象にする。
出力制限は、ページ由来データによるコンテキストの氾濫を抑制する。
認証情報保管庫は保存された認証情報を暗号化し、通常のデーモン IPC およびエージェントから見える出力にパスワードが現れないようにする。

コンテンツ境界は多層防御であり、モデルがプロンプトインジェクションを無視することを保証するものではありません。ドメインフィルタリングはオペレーティングシステムのファイアウォールではなく、WebSocket または EventSource のインターセプトもベストエフォートです。したがって、強力な分離には、コンテナ制限、ファイルシステム権限、ネットワークの外向き通信ポリシー、狭く限定した認証情報と、agent-browser のポリシーを組み合わせる必要があります。

ドメイン許可リストは、デーモンが封じ込めを確立する前に既存コンテンツを実行する可能性があるため、既存の CDP 接続、プロファイル、復元状態、Safari/iOS バックエンドなど、いくつかの組み合わせを意図的に拒否します。必要な CDN、フォント、API、ID プロバイダーのドメインも許可リストに含める必要があります。含まれていない場合、サイトの読み込みに失敗します。

agent-browser と Playwright の選択 #

agent-browser と Playwright は異なる抽象化レベルで動作します。

要件	より適したインターフェース
AI エージェントがシェルツールを通じて任意のページを検査・操作する必要がある	agent-browser
テストスイートにアサーション、フィクスチャ、再試行、並列ワーカー、レポートが必要である	Playwright
ワークフローにコンパクトな観測結果と要素参照が必要である	agent-browser
コードで Firefox、WebKit、Chromium をカバーする必要がある	Playwright
アプリケーションに、型付きのブラウザーロジックとソース管理されたセレクターが必要である	Playwright
エージェントにコマンドごとの永続的なブラウザー状態が必要である	agent-browser

Playwright はエンドツーエンドテストフレームワークであり、ブラウザー自動化ライブラリです。agent-browser はエージェントループ向けのコマンドインターフェースです。フィクスチャ、アサーション、トレースツール、複数エンジン対応はコードに属するため、決定的なテストプログラムには Playwright の方が適しています。agent-browser は観測からアクションへの変換を最小化するため、オープンエンドなエージェント作業に適しています。

Browser Use は別の層です。agent-browser は --provider browseruse を通じて Browser Use をホスト型ブラウザープロバイダーとして利用できますが、その統合によって両プロジェクトが機能的に同等になるわけではありません。リモートブラウザーをバックエンドとする agent-browser コマンドが必要ならプロバイダー統合を選択し、必要なアプリケーションインターフェースが Browser Use の SDK とエージェント API なら Browser Use を直接使用してください。

運用上の指針 #

信頼性の高いデプロイメントでは、次のルールに従います。

コマンドの挙動とバックエンドのサポートが継続的に変化するため、agent-browser のバージョンを固定する。
要素参照は特定のページ状態を表すため、ナビゲーションまたは DOM の変更後に再度スナップショットを取得する。
固定遅延や普遍的な networkidle を仮定せず、アプリケーションから見える条件を待つ。
タスクと主体ごとにセッションを分離し、分離したタスクを同じ Chrome インスタンスに接続しない。
スクリーンショット、ダウンロード、動画、HAR ファイル、プロファイル、保存状態を、機密性を持つ可能性のあるアーティファクトとして扱う。
コンテンツ境界、出力制限、アクションポリシー、ドメイン制限を明示的に有効にする。
CLI レベルのポリシーはオペレーティングシステムのサンドボックスの代替にならないため、ブラウザープロセスより下位でファイルシステムとネットワークを分離する。

agent-browser はブラウザーエージェントを決定的にはしません。ページは変化し、認証は期限切れになり、アクセシビリティメタデータは不完全な場合があり、モデルの判断は確率的なままです。agent-browser が提供するのは、より狭く、より状態を保持するインターフェースです。つまり、ブラウザーはゼロから生成したスクリプトの集合ではなく、コンパクトな観測結果、明示的な参照、強制可能なアクションカテゴリを備えた永続的なツールになります。