agent-browser CLI ガイド

agent-browser はAIエージェント向けの高速ブラウザ自動化CLIツール。Bashツールから直接呼び出して使う。

基本ワークフロー

1. ページを開く → スナップショット → 操作 のループ

# ページを開く
agent-browser open "https://example.com"

# アクセシビリティツリーを取得（AI向け。@ref付きで要素を特定できる）
agent-browser snapshot -i  # -i: インタラクティブ要素のみ

# @ref を使って要素を操作
agent-browser click @e2
agent-browser fill @e3 "入力テキスト"

# 操作後に再度スナップショットで状態確認
agent-browser snapshot -i

重要: 操作のたびに snapshot -i で現在の状態を確認すること。 ページの状態は操作ごとに変わるため、古い@refは無効になる可能性がある。

2. スナップショットのオプション

agent-browser snapshot              # フルツリー
agent-browser snapshot -i           # インタラクティブ要素のみ（推奨）
agent-browser snapshot -c           # コンパクト（空の構造要素を除去）
agent-browser snapshot -d 3         # 深さ制限
agent-browser snapshot -s "#main"   # CSSセレクタでスコープ限定

コマンドリファレンス

ナビゲーション

agent-browser open <url>       # URLに移動
agent-browser back             # 戻る
agent-browser forward          # 進む
agent-browser reload           # リロード

クリック・入力

agent-browser click <sel>      # クリック（@ref またはCSSセレクタ）
agent-browser dblclick <sel>   # ダブルクリック
agent-browser type <sel> <text>  # テキスト入力（既存テキストに追加）
agent-browser fill <sel> <text>  # クリア後に入力（フォーム向け）
agent-browser press <key>      # キー押下（Enter, Tab, Control+a など）
agent-browser hover <sel>      # ホバー
agent-browser check <sel>      # チェックボックスON
agent-browser uncheck <sel>    # チェックボックスOFF
agent-browser select <sel> <val>  # ドロップダウン選択

情報取得

agent-browser get text <sel>   # テキスト取得
agent-browser get html <sel>   # HTML取得
agent-browser get value <sel>  # input値取得
agent-browser get attr <name> <sel>  # 属性取得
agent-browser get title        # ページタイトル
agent-browser get url          # 現在のURL
agent-browser get count <sel>  # 要素数
agent-browser get box <sel>    # 要素の位置・サイズ

要素の状態確認

agent-browser is visible <sel>   # 表示されているか
agent-browser is enabled <sel>   # 有効か
agent-browser is checked <sel>   # チェックされているか

要素検索（find）

セマンティックなロケーターで要素を探してアクションを実行：

agent-browser find role button click --name "送信"
agent-browser find text "ログイン" click
agent-browser find label "メールアドレス" fill "test@example.com"
agent-browser find placeholder "検索..." fill "キーワード"
agent-browser find testid "submit-btn" click

スクリーンショット・PDF

agent-browser screenshot              # 画面キャプチャ（デフォルトパス）
agent-browser screenshot ./shot.png   # パス指定
agent-browser screenshot --full       # フルページ
agent-browser pdf ./page.pdf          # PDF保存

スクリーンショットを撮った後は Read ツールでファイルを読み取って画像を確認できる。

スクロール

agent-browser scroll down        # 下にスクロール
agent-browser scroll up          # 上にスクロール
agent-browser scroll down 500    # 500pxスクロール
agent-browser scrollintoview <sel>  # 要素が見えるまでスクロール

待機

agent-browser wait <sel>    # 要素が表示されるまで待機
agent-browser wait 2000     # 2秒待機

JavaScript実行

agent-browser eval "document.title"
agent-browser eval "document.querySelectorAll('a').length"

タブ管理

agent-browser tab list     # タブ一覧
agent-browser tab new      # 新しいタブ
agent-browser tab 2        # 2番目のタブに切替
agent-browser tab close    # 現在のタブを閉じる

ネットワーク

agent-browser network requests                    # リクエスト一覧
agent-browser network requests --filter "api"     # フィルタ
agent-browser network route "*/api/*" --abort      # リクエストブロック
agent-browser network unroute                      # ルート解除

デバッグ

agent-browser console          # コンソールログ表示
agent-browser errors           # エラー表示
agent-browser highlight <sel>  # 要素ハイライト
agent-browser trace start      # トレース開始
agent-browser trace stop       # トレース停止

ブラウザ設定

agent-browser set viewport 1280 720       # ビューポート設定
agent-browser set device "iPhone 15"      # デバイスエミュレーション
agent-browser set media dark              # ダークモード
agent-browser set offline on              # オフラインモード
agent-browser set headers '{"Authorization":"Bearer xxx"}'  # ヘッダー設定

セッション管理

agent-browser --session mywork open "https://example.com"  # 名前付きセッション
agent-browser session list   # セッション一覧

セッションを指定すると、同じブラウザコンテキスト（Cookie等）を維持できる。

よく使うパターン

Webページの内容を読み取る

agent-browser open "https://example.com"
agent-browser snapshot -c  # コンパクトなツリーで内容確認

フォームに入力して送信

agent-browser open "https://example.com/form"
agent-browser snapshot -i
# スナップショットの@refを使って操作
agent-browser fill @e1 "名前"
agent-browser fill @e2 "email@example.com"
agent-browser click @e3  # 送信ボタン
agent-browser wait 2000
agent-browser snapshot -i  # 結果確認

ログインが必要なサイト

agent-browser --session auth open "https://example.com/login"
agent-browser --session auth snapshot -i
agent-browser --session auth fill @e1 "username"
agent-browser --session auth fill @e2 "password"
agent-browser --session auth click @e3
# 以降も同じセッションを使い続ける
agent-browser --session auth open "https://example.com/dashboard"

スクリーンショットで視覚的に確認

agent-browser open "https://example.com"
agent-browser screenshot ./tmp_screenshot.png
# Readツールで画像を確認

オプション

オプション	説明
--session <name>	セッション名（Cookie等を維持）
--headed	ブラウザウィンドウを表示（デバッグ用）
--json	JSON形式で出力
--full, -f	フルページスクリーンショット
--cdp <port>	Chrome DevTools Protocolで接続
--headers <json>	HTTPヘッダーを設定
--debug	デバッグ出力

注意事項

• セレクタ: @ref（スナップショットから取得）が最も確実。CSSセレクタも使える
• セッション: 同じセッション名を使えばCookieやログイン状態を維持できる
• ヘッドレス: デフォルトはヘッドレスモード。--headed で画面表示
• 初回実行: ブラウザ未インストールなら agent-browser install を先に実行