📚 suwa-sh / zenn-contents
🌐 技術調査 - agent-browser
目次

🌐 技術調査 - agent-browser

2026-02-25

概要

Vercel Labsが開発を主導するagent-browserは、AIエージェントのブラウザ操作自動化を目的とした専用CLIツールです。
対象のWebページを解析し、インタラクティブな要素に一意の参照ID（例：@e1）を付与したアクセシビリティツリーを生成します。
AIエージェントはこの参照IDを利用して、クリック、テキスト入力、情報取得などのアクションを直感的に実行します。

特徴

Playwright MCPを利用する従来の手法と比較して、LLMのコンテキストウィンドウの消費量を最大93%削減します。
CSSセレクタやXPathを排除し、参照IDによる確定的かつ安定した要素操作を実現します。
Rustによるネイティブコンパイルを採用し、コマンド解析とバックグラウンドプロセスとの通信を50ミリ秒未満の速度で完了します。
ネイティブバイナリの実行が困難な環境向けに、Node.js実装への自動フォールバック機能を備えます。

構造

システムコンテキスト図

User System External
要素名 説明
User ブラウザ操作の命令を発行するAIエージェントまたは開発者
System コマンドを受け取りブラウザの自動化を実行する対象ソフトウェア群
External 構築やテストの対象となる外部のWebアプリケーション

コンテナ図

Client Daemon Browser
要素名 説明
Client ユーザーからの入力を受け付け、プロセス間通信を用いて命令を転送するフロントエンド層
Daemon バックグラウンドで常駐し、各種セッション状態とブラウザのライフサイクルを維持するプロセス
Browser WebページのレンダリングとDOMへの実際の操作を担当するエンジン部分

コンポーネント図

Rust CLI Node js Fallback Node js Daemon Playwright Chromium
要素名 説明
Rust CLI コマンドライン引数をパースし、高速なIPC通信を実現するネイティブ実行ファイル
Node js Fallback ネイティブバイナリ非互換環境で動作を担保する代替実行モジュール
Node js Daemon バックグラウンドで持続的に動作し、Playwrightインスタンスの管理を担当する常駐プログラム
Playwright デーモンからの命令をブラウザエンジンに対する操作プロトコルへ変換するライブラリ
Chromium 実際の描画処理およびアクセシビリティツリーの構築を行うデフォルトのブラウザコア

情報

概念モデル

ClientEnvironment PageContext ExternalEngine SessionState TreeSnapshot InteractiveElement
要素名 説明
ClientEnvironment ツール内部で管理する状態データ全体を包含する領域
SessionState 認証情報やCookieなどの接続コンテキストを保持する論理的なセッション情報
PageContext 特定時点での画面構造やDOMツリーに関する情報を集約する領域
TreeSnapshot 取得したアクセシビリティツリーの全体構造を表すデータ
InteractiveElement スナップショット内に含まれる、操作可能な個々のUI部品を表すデータ
ExternalEngine ツールの外部に存在する、実際の描画やプロトコル通信を担うシステム

情報モデル

SessionState sessionName: String encryptionKey: String expireDays: Int TreeSnapshot success: Boolean snapshotFormat: String InteractiveElement referenceId: String ariaRole: String accessibleName: String 1 many 1 many
要素名 説明
SessionState 並行実行を分離するためのセッション名、保存状態の暗号化キー、有効期限日数を保持するクラス
TreeSnapshot 実行結果の成否ステータスと、抽出されたツリーデータを文字列またはJSON形式で保持するクラス
InteractiveElement AIが要素を指定するための参照ID、役割、およびアクセシブルネームを保持するクラス

構築方法

agent-browserの導入には、パッケージマネージャーを利用したインストールと、ソースコードからのビルドの2つの方法があります。

前提環境の構築

いずれの導入方法でも、以下の環境が必要です。

  • Node.jsバージョン22以降の準備
  • npmまたはpnpmの利用設定
  • Chromiumなどのブラウザエンジンが正常に起動するOS環境の構築

導入方法1: パッケージのインストール

npmを利用してグローバルにインストールします。依存するブラウザバイナリを同時に導入する場合は--with-depsオプションを付与します。

npm install -g @vercel/agent-browser
# またはブラウザバイナリも同時にインストールする場合
npm install -g @vercel/agent-browser --with-deps

インストール完了後、ヘルプコマンドを実行してパスの疎通とバージョン情報を確認します。

agent-browser --help

導入方法2: ソースコードからのビルド

GitHubリポジトリからソースコードをクローンし、ビルドスクリプトを実行してRust CLI層およびNode.jsフォールバック層の実行可能ファイルを生成します。

git clone https://github.com/vercel-labs/agent-browser.git
cd agent-browser
pnpm install
pnpm build

AIアシスタント環境への統合

利用するAIエージェントの仕様に合わせて、Agent Skills または MCP のいずれかの方法で統合します。

方法A: Agent Skillsとしての統合（Claude Code / OpenCodeなど）

AIエージェントがスキルディレクトリをサポートしている場合、公式リポジトリからスキル定義ファイル（SKILL.md）をダウンロードして配置します。

# 例: Claude Codeのスキルディレクトリに配置する場合
mkdir -p .claude/skills/agent-browser
curl -sL https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md -o .claude/skills/agent-browser/SKILL.md

方法B: MCPサーバーとしての統合（Cursor / Clineなど）

MCPをサポートするクライアントを利用する場合は、設定ファイル（mcp.jsonやcline_mcp_settings.jsonなど）に以下のように追記してサーバーとして登録します。

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "@vercel/agent-browser", "mcp"]
    }
  }
}

利用方法

agent-browserは、コマンドラインから直感的にブラウザを操作できます。

ウェブページのナビゲーション

  • 対象URLを指定したopenコマンド実行によるページ読み込み
  • 別ドメインでの検証を並行して進める場合のtab newコマンドによる新規タブ遷移
  • 認証トークンを利用したバックドアアクセスを行う場合の--headersオプション指定

アクセシビリティツリーの取得

  • 画面状態を把握するためのsnapshot -iコマンドによるインタラクティブ要素抽出
  • 構造解析のみを目的とする場合の-cオプション追加による空要素除外
  • マウスホバーなどに反応する要素を含める場合の-Cオプション付与による探索範囲拡張

要素に対する操作

  • ツリーデータ内の参照IDを用いたclick @e1コマンドによるクリックアクション実行
  • フォーム入力を行う場合のfill @e2 "入力値"コマンドによるテキストボックス値設定
  • 画面上のテキストデータを抽出する場合のget text @e1コマンドによる文字列取得

JavaScriptの評価と実行

  • evalコマンドへのJavaScriptコード文字列渡しによるブラウザコンテキスト内直接実行
  • 複雑なスクリプトを安全に渡すためのヒアドキュメント形式と--stdinオプションの組み合わせ
  • シェルのエスケープ問題を回避する目的でのBase64エンコードスクリプトと-bオプション指定

スクリーンショットの撮影と視覚的検証

  • screenshotコマンド実行による現在の画面表示の画像ファイル出力
  • 画像を解析に用いるAIエージェント向けの--annotateオプションによる参照IDオーバーレイ表示
  • 記録を目的として動画を残す場合のrecord startコマンドによるWebM形式キャプチャ開始

運用

agent-browserを安定して運用するためのセッション管理やトラブルシューティング機能が提供されています。

セッションの永続化と分離

  • 複数タスク並列処理時の競合を避けるための--session <名前>オプションによる独立ブラウザインスタンス起動
  • 認証完了後のログイン状態を維持するためのstate save <パス>コマンドによるCookieやローカルストレージ内容の暗号化保存
  • 後続の自動化フローを開始する前のstate load <パス>コマンドによる保存済み状態復元

環境変数を利用した機密情報管理

  • AGENT_BROWSER_SESSION_NAME環境変数設定によるセッション保存時のデフォルト識別名定義
  • AGENT_BROWSER_ENCRYPTION_KEYへの64文字16進数文字列登録によるAES-256-GCM暗号化適用
  • AGENT_BROWSER_STATE_EXPIRE_DAYSへの数値指定による古いセッション状態ファイルの自動破棄日数管理

トラブルシューティングと解析機能

  • エラー原因調査を行う目的でのconsoleコマンド実行によるブラウザ内記録ログ出力
  • キャッチされなかったJavaScript例外を確認するためのerrorsコマンドによる詳細スタックトレース取得
  • DOM構造と実際の表示位置を比較するためのhighlight @e1コマンドによる指定要素強調表示

外部ブラウザとの連携接続

既存のユーザープロファイル情報を利用する場合、Chromeブラウザをリモートデバッグモードで手動起動し、agent-browserからアタッチします。

  1. Chromeをリモートデバッグモードで起動します（ポート9222の例）。
# macOSの例
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
  1. --cdpオプションで対象ポート番号を指定し、起動済みブラウザにアタッチして操作を続行します。Windows環境におけるIPv6とIPv4のバインディング問題を回避するため、接続先ホスト指定には明示的に127.0.0.1を利用します。
agent-browser open https://example.com --cdp http://127.0.0.1:9222

■まとめ

agent-browserは、AIエージェント向けに特化したブラウザ自動化CLIツールであり、Markdown形式でのDOMアクセスや状態管理機能を備え、コンテキストウィンドウを大幅に節約できます。
ローカルテストや大規模言語モデルとの連携など、複雑なブラウザタスクを効率的に実行するための強力な選択肢となります。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク