agent-browser 導入ガイド

agent-browser は AI エージェント向けのブラウザ自動化 CLI。Rust 製のネイティブバイナリで、Playwright や Node.js ランタイム不要で Chrome を操作できる。Claude Code から bash 経由で直接呼び出して使う。

• リポジトリ: https://github.com/vercel-labs/agent-browser
• ドキュメント: https://agent-browser.dev

セットアップ手順

1. インストール

pnpm add -g agent-browser
agent-browser install   # Chrome for Testing をダウンロード（初回のみ）

pnpm approve-builds -g のプロンプトが出た場合は、ビルドスクリプトの許可は不要（バイナリは同梱済み）。

agent-browser install で Chrome for Testing がダウンロードされる（既存の Chrome とは別管理）:

Installing Chrome...
  Downloading Chrome 147.0.7727.50 for win64
  180/180 MB (100%)
✓ Chrome 147.0.7727.50 installed successfully
  Location: C:\Users\numbe\.agent-browser\browsers\chrome-147.0.7727.50

2. Claude Code スキルの追加（グローバル）

npx skills add vercel-labs/agent-browser

対話型インストーラーが起動する。以下の順に選択:

1. Select skills to install: agent-browser をスペースで選���
2. Which agents do you want to install to?: 使用するエージェントを選択（Claude Code 等）
3. Installation scope: Global を選択（ホームディレクトリにインストール、全���ロジェクトで利用���能）
4. Installation method: Symlink (Recommended) を選択
5. Proceed with installation?: Yes

インストール結果:

Installation Summary
  ~\.agents\skills\agent-browser
    universal: Amp, Antigravity, Cline, Codex, Cursor +7 more
    symlink → Claude Code

スキルは ~\.agents\skills\agent-browser に配置され、Claude Code の .claude/skills/ にシンボリックリンクが張られる。

Note: Snyk が "High Risk" と表示するが、これは agent-browser がブラウザプロセスを起動・操作するネイティブバイナリであるため。Vercel公式パッケージなので問題ない。

3. グロー��ル CLAUDE.md への追記（任意）

以下のセクションをグローバルの CLAUDE.md に追記する。

▼ ここから CLAUDE.md に追記する内容 ▼

## Browser Automation (agent-browser)

ブラウザの操作・テスト・デバッグには `agent-browser` を使う。
Chrome DevTools を直接操作するのではなく、agent-browser CLI 経由で行うこと。

### 基本ワークフロー

1. `agent-browser open <url>` — ページを開く
2. `agent-browser snapshot -i` — インタラクティブ要素のアクセシビリティツリーを取得（ref付き）
3. `agent-browser click @e1` / `agent-browser fill @e2 "text"` — ref を使って操作
4. ページ遷移・変更後は再度 `snapshot -i` を取得して状態を確認

### Chrome 拡張機能の読み込み

ローカルの unpacked extension を読み込む場合：

```bash
agent-browser --extension "C:\path\to\extension\directory" open https://example.com

デバッグ用コマンド

agent-browser snapshot                    # アクセシビリティツリー全体
agent-browser snapshot -i                 # インタラクティブ要素のみ（推奨）
agent-browser snapshot -i -c              # コンパクト表示
agent-browser snapshot -i --json          # JSON出力（構造化データとして処理する場合）
agent-browser screenshot                  # スクリーンショット取得
agent-browser screenshot --annotate       # 要素に番号ラベル付きスクリーンショット
agent-browser console                     # コンソールメッセージ確認
agent-browser errors                      # JSエラー確認
agent-browser eval "document.title"       # JavaScript 実行
agent-browser get text @e1                # 要素のテキスト取得
agent-browser get html @e1                # 要素のHTML取得
agent-browser get url                     # 現在のURL取得
agent-browser network requests            # ネットワークリクエスト一覧
agent-browser network requests --filter api  # APIリクエストのみフィルタ

操作コマンド

agent-browser click @e1                   # クリック
agent-browser fill @e2 "value"            # フィールドに入力（クリア→入力）
agent-browser type @e2 "value"            # 追記入力
agent-browser select @e3 "option"         # ドロップダウン選択
agent-browser check @e4                   # チェックボックスON
agent-browser press Enter                 # キー入力
agent-browser scroll down 500             # スクロール
agent-browser wait --text "完了"           # テキスト出現を待機
agent-browser wait --load networkidle     # ネットワーク待機

セッション管理

複数サイトを並行操作する場合はセッション分離する：

agent-browser --session site-a open https://example-a.com
agent-browser --session site-b open https://example-b.com

認証状態の保存と再利用：

# 認証状態を保存
agent-browser state save ./auth-state.json

# 次回以降、認証状態を復元して起動
agent-browser --state ./auth-state.json open https://example.com

# または session-name で自動永続化
agent-browser --session-name my-session open https://example.com

headed モード（画面表示）

デバッグ時にブラウザ画面を表示したい場合：

agent-browser open https://example.com --headed

バッチ実行

複数コマンドを一括実行してオーバーヘッドを減らす：

echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

注意事項

• snapshot -i の結果をパースして ref（@e1, @e2 ...）を特定してから操作すること
• ページ遷移やDOM変更後は必ず再度 snapshot を取ること（ref は snapshot 取得時に生成される）
• --json フラグで機械可読な出力が得られる
• デフォルトタイムアウトは 25 秒。遅いページには AGENT_BROWSER_DEFAULT_TIMEOUT=45000 を設定
• 拡張機能は --extension で unpacked ディレクトリのパスを指定する
• Windows 環境ではパス区切りに \ を使用する

## ▲ ここまで CLAUDE.md に追記する内容 ▲

---

## 用途別ユースケース

### Chrome 拡張機能の開発・デバッグ

```bash
# 拡張を読み込んだ状態でサイトを開く
agent-browser --extension "C:\Users\numbe\Git_repo\chrome-extension-x" --headed open https://example.com

# 拡張が注入したDOMの変化を確認
agent-browser snapshot -i

# コンソールログで拡張の動作確認
agent-browser console

# ネットワークリクエストの確認
agent-browser network requests --filter api

クラウド会計への自動操作（仕訳登録等）

# 認証付きで起動
agent-browser --session-name accounting open https://accounting-app.example.com

# 仕訳入力画面に遷移
agent-browser snapshot -i
agent-browser click @e5   # メニューリンク等

# フォーム入力
agent-browser fill @e10 "2025-04-01"   # 日付
agent-browser select @e11 "売上高"      # 勘定科目
agent-browser fill @e12 "100000"        # 金額
agent-browser click @e20                # 登録ボタン

# 結果確認
agent-browser wait --text "登録しました"
agent-browser screenshot result.png

ローカル開発サーバーのテスト

# ローカル開発サーバーに接続
agent-browser open http://localhost:3000

# ページの構造確認
agent-browser snapshot -i -c

# フォームのE2Eテスト
agent-browser fill @e3 "[email protected]"
agent-browser click @e5
agent-browser wait --text "送信完了"
agent-browser screenshot test-result.png

# レスポンシブ確認
agent-browser set viewport 375 812    # iPhone サイズ
agent-browser screenshot mobile.png
agent-browser set viewport 1280 720   # デスクトップ
agent-browser screenshot desktop.png

動作検証結果（2026-04-06）

Windows 11環境で実際に動作検証を行った結果をまとめる。

基本機能（全て動作OK）

制限事項

1. セッションが毎回リセットされる

--profile Default はChromeプロファイルのcookieをコピーして使う。close --all で閉じると次回起動時にリセットされる。ログインが必要なSaaSサイトでは毎回ログインが必要になる。

state save / state load でcookieを保存・復元できる可能性はあるが、セッショントークンには有効期限があるため永続的な解決にはならない。

2. chrome.storage.local が引き継がれない

--profile Default でChromeプロファイルのcookieはコピーされるが、拡張機能の chrome.storage.local は空の状態で起動する。拡張機能がローカルストレージに設定データを保持している場合、初期状態に戻ってしまう。

対策として、拡張ディレクトリ内の defaults.json からフォールバック読み込みする仕組みを実装できるが、ログイン問題が先に立ちはだかるため効果は限定的。

3. プロファイルアイコンのクリックでブラウザが消える

agent-browserが起動したChromeでプロファイルアイコンをクリックすると、プロファイル切替画面に遷移してブラウザが閉じる。プロファイルアイコンは操作しないこと。

4. デーモンの再起動が必要な場合がある

--extension, --profile, --headed はデーモン起動時のみ有効。既にデーモンが動いている場合は close --all してから再起動する必要がある。

Chrome DevTools MCP との使い分け

結論

• ログイン必須のSaaS操作: Chrome DevTools MCP が適切（ログイン・拡張ストレージがそのまま使える）
• agent-browser の適用場面: 未ログインサイトの自動操作、E2Eテスト、スクレイピング、CI環境
• ログイン必須サイトをagent-browserで操作したい場合は、ログイン自動化 + storage フォールバックの組み合わせが必要

Windows 環境での注意事項

• pnpm add -g でインストールした場合、pnpm bin -g の出力パスにPATHが通っているか確認
• agent-browser install がダウンロードする Chrome for Testing は既存の Chrome とは別管理（プロファイルやデータは共有しない）
• Git Bash から実行する場合、パスの \ が / に変換されることがある。--extension のパスはダブルクォートで囲むこと
• Chrome DevTools MCP（ポート9222/9223）と agent-browser は同時に使えない場合がある。ポート競合に注意

トラブルシューティング