「agent-browser を入れてみたけど動かない」「ドキュメント通りに書いたのにエラーになる」
そんな経験をしたことはないでしょうか。Vercel Labs が公開したブラウザ自動化CLIツール agent-browser は、GitHub Stars 14,000超の注目プロジェクトだが、ドキュメントと実際の動作にはかなりの乖離がある。
この記事では、agent-browser v0.5.0 の全コマンドを1つずつ実機で検証した結果を報告する。動いたもの、動かなかったもの、そしてドキュメントとの差異13個を重要度ラベル付きで整理した。
agent-browser とは — AIエージェント専用のブラウザ操作CLI
agent-browser は、AIエージェント（Claude Code、Cursor等）がbashコマンドとしてブラウザを操作するためのCLIツールだ。
MCP → CLI の流れ
2025年まで、AIエージェントにブラウザ操作をさせるならPlaywright MCPサーバーが定番だった。MCPサーバーを起動し、ツールとしてエージェントに渡す構成だ。
2026年に入り、この構図が変わりつつある。Playwright CLI の登場により、MCP比で約4分の1のトークン消費で同等のタスクをこなせることが報告されている。agent-browser もこのCLIベースのアプローチを採用している。
MCPプロトコルを介さず、CLIで直接ブラウザと対話する。エージェント側から見れば、bashコマンドを叩くだけなのでシンプルだ。
スナップショット方式の仕組み
agent-browser の核となるのが「スナップショット」だ。
open <url>でページを開くsnapshotでアクセシビリティツリーを取得- 各要素に
e1,e2… のRef番号が振られる click e1やfill e3 "テキスト"でRef番号を指定して操作
DOMのXPathやCSSセレクタを意識する必要がなく、テキストベースで操作が完結する。AIエージェントとの親和性が高い設計だ。
インストールとセットアップ
基本インストール
npm install -g agent-browser
Chromiumの自動インストール
初回実行時にChromiumが自動ダウンロードされる。企業環境でプロキシ配下にある場合は、環境変数 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST を設定する必要がある場合がある。
検証環境
今回の検証は以下の環境で実施した。
| 項目 | バージョン |
|---|---|
| OS | macOS Darwin 25.3.0（Apple Silicon） |
| agent-browser | v0.5.0（npm package 0.16.3） |
| Node.js | v25.7.0 |
| Playwright-core | 1.57.0 |
| 検証日 | 2026年3月7日 |
基本ワークフロー: Navigate → Snapshot → Interact
agent-browser の操作は3ステップのサイクルで回る。
# Step 1: ページを開く
agent-browser open "https://example.com"
# Step 2: スナップショットを取得
agent-browser snapshot -i # インタラクティブ要素のみ
# Step 3: Ref番号で操作
agent-browser click e1 # e1要素をクリック
agent-browser fill e3 "検索キーワード" # e3にテキスト入力
Wikipediaをテストした際、258個のインタラクティブ要素を約3,500トークンで表現できた。ページ全体のHTMLを渡すよりもはるかにトークン効率が良い。
全コマンド検証結果 — カテゴリ別テーブル
ナビゲーション — 全て正常動作
| コマンド | 結果 | 備考 |
|---|---|---|
open <url> | 正常 | |
back | 正常 | |
forward | 正常 | |
reload | 正常 | |
close | 正常 |
スナップショット — ほぼ正常
| コマンド | 結果 | 備考 |
|---|---|---|
snapshot | 正常 | 全アクセシビリティツリー |
snapshot -i | 正常 | インタラクティブ要素のみ。実用上はこれを多用 |
snapshot -c | 正常 | コンパクト出力 |
snapshot -d <n> | 正常 | 深さ制限 |
snapshot -s <selector> | 要注意 | 特定条件でタイムアウトが発生 |
要素操作 — 全て正常動作
| コマンド | 結果 |
|---|---|
click <ref> | 正常 |
fill <ref> <text> | 正常 |
check <ref> | 正常 |
hover <ref> | 正常 |
press <key> | 正常 |
scroll <dir> [px] | 正常 |
scrollintoview <ref> | 正常 |
情報取得 — 一部に問題
| コマンド | 結果 | 備考 |
|---|---|---|
get title | 正常 | |
get url | 正常 | |
get text <ref> | 正常 | Refで動作 |
get attr <ref> <attr> | 正常 | CSSセレクタで動作 |
get box <ref> | 要注意 | Refで動作せず。CSSセレクタのみ |
get count <ref> | 正常 | |
get html <ref> | 要注意 | Refで動作せず。CSSセレクタのみ |
get value <ref> | 動作せず | Refでタイムアウト |
状態チェック — 全て正常動作
| コマンド | 結果 |
|---|---|
is visible <ref> | 正常 |
is enabled <ref> | 正常 |
is checked <ref> | 正常 |
セマンティックロケータ — 一部問題
| コマンド | 結果 | 備考 |
|---|---|---|
find role button click --name "Submit" | 正常 | |
find text "テキスト" click | 要注意 | strict modeで複数マッチエラー |
find first "テキスト" click | 動作せず | Expected string, received null |
待機コマンド — 全て正常動作
| コマンド | 結果 |
|---|---|
wait 1000 | 正常 |
wait --text "Example" | 正常 |
wait --url "..." | 正常 |
wait --load networkidle | 正常 |
スクリーンショット・PDF — 全て正常動作
| コマンド | 結果 | 備考 |
|---|---|---|
screenshot [path] | 正常 | PNG、1280×720 |
screenshot --full | 正常 | フルページ |
screenshot --annotate | 正常 | アノテーション付き |
pdf <path> | 正常 | PDF 1.4形式 |
JavaScript実行 — 一部問題
| コマンド | 結果 | 備考 |
|---|---|---|
eval "document.title" | 正常 | |
eval -b <base64> | 動作せず | Base64デコードされない |
ブラウザ設定 — 一部問題
| コマンド | 結果 | 備考 |
|---|---|---|
set viewport 1920 1080 | 正常 | |
set device "iPhone 14" | 正常 | |
set media dark | 動作せず | Validation error |
set geo 35.6762 139.6503 | 正常 | |
set offline on/off | 正常 | |
set headers <json> | 正常 | |
set credentials <user> <pass> | 正常 |
Cookie・ストレージ — 全て正常動作
ネットワーク制御 — 一部注意
| コマンド | 結果 | 備考 |
|---|---|---|
network route <url> --body <json> | 正常 | |
network unroute | 要注意 | 引数なしでエラー（URLが必須） |
network requests | 要注意 | –filterが必須 |
network requests --filter <pattern> | 正常 |
タブ管理 — 一部注意
| コマンド | 結果 | 備考 |
|---|---|---|
tab | 正常 | タブ一覧 |
tab new <url> | 要注意 | URLが反映されずabout:blank |
tab <n> | 要注意 | 0ベースインデックス |
tab close <n> | 正常 |
セッション・デバッグ — 全て正常動作
session, session list, trace, console, errors, highlight — いずれも正常。
未実装コマンド（ドキュメントに記載あり）
| コマンド | 状態 |
|---|---|
diff snapshot/screenshot/url | Unknown command: diff |
keyboard type/inserttext | Unknown command: keyboard |
ドキュメントとの差異13個 — 重要度ラベル付き
致命的（ワークフローが壊れる）— 2件
差異1: Ref表記が @e1 ではなく e1
ドキュメントでは click @e1 のように @ 付きのRef表記が使われている。しかし実際に @e1 を渡すと一部のコマンドでエラーになる。正しくは click e1 と @ を外して記述する。
これはコア機能に直結する差異だ。初めてagent-browserを使う人がドキュメントを参考にすると、最初のコマンドから躓く可能性がある。
差異2: diff コマンドが未実装
ドキュメントには diff snapshot, diff screenshot, diff url が記載されているが、いずれも Unknown command: diff となる。ページの変化を検出するA/Bテストや回帰テストの基盤となるコマンドだが、v0.5.0時点では実装されていない。
要注意（回避策あり）— 7件
| # | 差異 | 影響 | 回避策 |
|---|---|---|---|
| 3 | keyboard コマンド未実装 | 中 | press や fill で代替 |
| 4 | get value がRefで動作しない | 中 | eval "document.querySelector('...').value" |
| 5 | get html / get box がRefで動作しない | 中 | CSSセレクタを直接指定 |
| 6 | タブインデックスが0ベース | 中 | ドキュメントの例は1ベース的に見えるが0始まり |
| 7 | tab new <url> でURLが反映されない | 中 | tab new → open <url> の2ステップ |
| 8 | find first が動作しない | 中 | find role 等で代替 |
| 9 | Auth Vault が未記載 | 中 | auth save / auth login がヘルプにない |
軽微（ドキュメント修正待ち）— 4件
| # | 差異 | 影響 | 備考 |
|---|---|---|---|
| 10 | eval -b（Base64実行）動作せず | 低 | 通常のevalで代替可能 |
| 11 | set media dark 動作せず | 低 | ダークモードテストは限定ユースケース |
| 12 | --version フラグ不在 | 低 | npm list -g agent-browser で確認可能 |
| 13 | network requests / network unroute に引数必須 | 低 | ドキュメントの例が不正確 |
トラブルシューティング
「@e1 でエラーになる」
@ を外して e1 を使う。これが最も頻出のハマりポイント。
# NG
agent-browser click @e1
# OK
agent-browser click e1
「get value がタイムアウトする」
eval コマンドで直接JavaScriptを実行して取得する。
# NG
agent-browser get value e3
# OK
agent-browser eval "document.querySelector('input[name=search]').value"
「tab new でURLが開かない」
2ステップに分ける。
# NG
agent-browser tab new "https://example.com"
# OK
agent-browser tab new
agent-browser open "https://example.com"
「diff コマンドが使えない」
v0.5.0時点では未実装。screenshotを2枚保存し、外部の画像比較ツールで差分を確認するか、snapshotの出力をテキストとして比較する。
「Rust CLI と書いてあるのにNode.jsが動いている」
正常な動作だ。デフォルトのインストールではNode.js + Playwright-coreベースのCLIが動作する。Rustバイナリはオプションビルドとして提供されている。実用上の影響はないが、起動速度の期待値には注意。
ドキュメントにない隠し機能
検証中に発見した、ドキュメント未記載の機能も紹介する。
--debugフラグ: デバッグモードで詳細なログを出力--cdp <port>: Chrome DevTools Protocolで直接接続AGENT_BROWSER_STREAM_PORT環境変数: WebSocketストリーミング--extension <path>: ブラウザ拡張の読み込みscreencast_start/stop: 画面録画input_mouse/keyboard/touch: 低レベル入力コマンド
これらは --help やソースコードから発見したものだ。公式ドキュメントの更新が追いついていない可能性がある。
まとめ — コア機能は実用的。ドキュメントに注意
使えるか: コア機能（Navigate → Snapshot → Interact）は安定して動作する。AIエージェントにブラウザ操作をさせる手段として実用的だ。
注意点: ドキュメントの約25%に不正確な記述がある。特にRef表記（@e1 → e1）と diff コマンド未実装は致命的。ドキュメントより --help を信頼すること。
正直な所感: まだagent-browserの全貌は掴めていない。今回はコマンド単体の検証にとどまっている。実ワークフローでの耐久性や、他ツールとの比較は今後の課題だ。
次回予告: 連載第2回では、同じブラウザ操作タスクを agent-browser と Playwright MCP の両方で実行し、トークン消費量・実行時間・成功率を実測比較する予定。
関連リンク
- agent-browser GitHub リポジトリ — 公式ソースコード・イシュー管理
- agent-browser npm パッケージ — インストール・バージョン情報
- Playwright MCP GitHub — 比較対象ツール
コメント