agent-browserによるブラウザ自動化

基本的なワークフロー

ブラウザ自動化は常に次のパターンに従います：

1. 移動: agent-browser open <url>
2. スナップショット: agent-browser snapshot -i (要素参照 @e1, @e2 などを取得)
3. 操作: 参照を使ってクリック、入力、選択を実行
4. 再スナップショット: ナビゲーション後またはDOM変更後、新しい参照を取得

agent-browser open https://example.com/form
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Check result

コマンドチェーン

コマンドは1つのシェル呼び出し内で && でチェーンできます。ブラウザはバックグラウンドデーモン経由で複数コマンド間で保持されるため、チェーンは安全で、個別呼び出しより効率的です。

# open + wait + snapshot をチェーン
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 複数の操作をチェーン
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3

# ナビゲーションとキャプチャ
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

チェーンの使用場面: 中間コマンドの出力を先に解析する必要がない場合に && を使用してください（例：open + wait + screenshot）。先に出力を解析する必要がある場合はコマンドを個別に実行してください（例：参照を発見するためのスナップショット、その後その参照を使って操作）。

主要なコマンド

# ナビゲーション
agent-browser open <url>              # ナビゲーション (エイリアス: goto, navigate)
agent-browser close                   # ブラウザを閉じる

# スナップショット
agent-browser snapshot -i             # インタラクティブ要素と参照 (推奨)
agent-browser snapshot -i -C          # カーソルインタラクティブ要素を含める (onclickを持つdiv、cursor:pointer)
agent-browser snapshot -s "#selector" # CSSセレクタにスコープを限定

# インタラクション (スナップショットから @refs を使用)
agent-browser click @e1               # 要素をクリック
agent-browser click @e1 --new-tab     # クリックして新規タブで開く
agent-browser fill @e2 "text"         # テキストをクリアして入力
agent-browser type @e2 "text"         # クリアなしで入力
agent-browser select @e1 "option"     # ドロップダウンオプションを選択
agent-browser check @e1               # チェックボックスをチェック
agent-browser press Enter             # キーを押す
agent-browser keyboard type "text"    # 現在のフォーカスに入力 (セレクタなし)
agent-browser keyboard inserttext "text"  # キーイベントなしで挿入
agent-browser scroll down 500         # ページをスクロール
agent-browser scroll down 500 --selector "div.content"  # 特定コンテナ内をスクロール

# 情報を取得
agent-browser get text @e1            # 要素テキストを取得
agent-browser get url                 # 現在のURLを取得
agent-browser get title               # ページタイトルを取得

# 待機
agent-browser wait @e1                # 要素の表示を待つ
agent-browser wait --load networkidle # ネットワークアイドルを待つ
agent-browser wait --url "**/page"    # URLパターンを待つ
agent-browser wait 2000               # ミリ秒単位で待つ

# ダウンロード
agent-browser download @e1 ./file.pdf          # 要素をクリックしてダウンロードをトリガー
agent-browser wait --download ./output.zip     # ダウンロード完了を待つ
agent-browser --download-path ./downloads open <url>  # デフォルトダウンロードディレクトリを設定

# キャプチャ
agent-browser screenshot              # 一時ディレクトリにスクリーンショット
agent-browser screenshot --full       # フルページスクリーンショット
agent-browser screenshot --annotate   # 番号付き要素ラベルが付いた注釈付きスクリーンショット
agent-browser pdf output.pdf          # PDFとして保存

# 差分 (ページ状態を比較)
agent-browser diff snapshot                          # 現在 vs 最後のスナップショットを比較
agent-browser diff snapshot --baseline before.txt    # 現在 vs 保存ファイルを比較
agent-browser diff screenshot --baseline before.png  # ビジュアルピクセル差分
agent-browser diff url <url1> <url2>                 # 2つのページを比較
agent-browser diff url <url1> <url2> --wait-until networkidle  # カスタム待機戦略
agent-browser diff url <url1> <url2> --selector "#main"  # 要素にスコープを限定

一般的なパターン

フォーム送信

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

Auth Vaultを使った認証 (推奨)

# 認証情報を一度保存 (AGENT_BROWSER_ENCRYPTION_KEY で暗号化)
# 推奨: シェル履歴に保存されないよう、stdin経由でパスワードを指定
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 保存されたプロフィールを使ってログイン (LLMはパスワードを見ません)
agent-browser auth login github

# プロフィールをリスト、表示、削除
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github

ステート永続化による認証

# ログインして状態を保存
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# 今後のセッションで再利用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

セッション永続化

# ブラウザ再起動間でクッキーとlocalStorageを自動保存/復元
agent-browser --session-name myapp open https://app.example.com/login
# ... ログインフロー ...
agent-browser close  # ステートは自動的に ~/.agent-browser/sessions/ に保存

# 次回は状態が自動的に読み込まれます
agent-browser --session-name myapp open https://app.example.com/dashboard

# 休止状態の暗号化
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com

# 保存された状態を管理
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7

データ抽出

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5           # 特定の要素テキストを取得
agent-browser get text body > page.txt  # すべてのページテキストを取得

# 解析用のJSON出力
agent-browser snapshot -i --json
agent-browser get text @e1 --json

並列セッション

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

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

既存のChromeに接続

# リモートデバッグが有効な実行中のChromeを自動発見
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot

# または明示的なCDPポート
agent-browser --cdp 9222 snapshot

カラースキーム (ダークモード)

# フラグ経由の永続的なダークモード (すべてのページと新規タブに適用)
agent-browser --color-scheme dark open https://example.com

# または環境変数経由
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com

# またはセッション中に設定 (その後のコマンドに持続)
agent-browser set media dark

ビジュアルブラウザ (デバッグ)

agent-browser --headed open https://example.com
agent-browser highlight @e1          # 要素をハイライト
agent-browser record start demo.webm # セッションを記録
agent-browser profiler start         # Chrome DevToolsプロファイリングを開始
agent-browser profiler stop trace.json # 停止してプロファイルを保存 (パスはオプション)

ローカルファイル (PDF、HTML)

# file:// URLでローカルファイルを開く
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

iOSシミュレータ (Mobile Safari)

# 利用可能なiOSシミュレータをリスト表示
agent-browser device list

# 特定デバイスでSafariを起動
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# デスクトップと同じワークフロー - snapshot、interact、re-snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # タップ (クリックのエイリアス)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up         # モバイル固有のジェスチャー

# スクリーンショットを撮る
agent-browser -p ios screenshot mobile.png

# セッションを閉じる (シミュレータをシャットダウン)
agent-browser -p ios close

要件: macOS with Xcode、Appium (npm install -g appium && appium driver install xcuitest)

実機: 事前設定済みの物理的iOSデバイスでも動作します。xcrun xctrace list devices から取得したUUIDで --device "<UDID>" を使用してください。

セキュリティ

すべてのセキュリティ機能はオプトインです。デフォルトでは、agent-browserはナビゲーション、アクション、出力に制限を課しません。

コンテンツバウンダリ (AIエージェント向け推奨)

--content-boundaries を有効にして、ページソースの出力をマーカーでラップすることにより、LLMがツール出力を信頼されないページコンテンツと区別するのに役立ちます：

export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Output:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [accessibility tree]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---

ドメイン許可リスト

ナビゲーションを信頼できるドメインに限定します。*.example.com のようなワイルドカードはベアドメイン example.com にも一致します。サブリソースリクエスト、WebSocket、EventSourceの非許可ドメインへの接続もブロックされます。ターゲットページが依存するCDNドメインを含めます：

export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
agent-browser open https://example.com        # OK
agent-browser open https://malicious.com       # ブロック

アクションポリシー

ポリシーファイルを使って破壊的なアクションを制限：

export AGENT_BROWSER_ACTION_POLICY=./policy.json

policy.json の例：

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

Auth Vault操作 (auth login など) はアクションポリシーをバイパスしますが、ドメイン許可リストは依然として適用されます。

出力制限

大きなページからのコンテキストフロッディングを防止：

export AGENT_BROWSER_MAX_OUTPUT=50000

差分 (変更を検証)

アクション実行後に diff snapshot を使用して、意図した効果があったことを検証します。これは現在のアクセシビリティツリーを、セッション内の最後に取得したスナップショットと比較します。

# 典型的なワークフロー: snapshot -> action -> diff
agent-browser snapshot -i          # ベースラインスナップショットを取得
agent-browser click @e2            # アクションを実行
agent-browser diff snapshot        # 何が変わったかを見る (自動的に最後のスナップショットと比較)

ビジュアルリグレッションテストまたは監視の場合：

# ベースラインスクリーンショットを保存して、後で比較
agent-browser screenshot baseline.png
# ... 時間が経過するか変更が加えられます ...
agent-browser diff screenshot --baseline baseline.png

# ステージング vs 本番を比較
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

diff snapshot の出力は + で追加、- で削除を示し、git diffと同様です。diff screenshot は差分画像を生成し、変更されたピクセルを赤でハイライトし、不一致の割合を示します。

タイムアウトと遅いページ

ローカルブラウザのデフォルト Playwright タイムアウトは25秒です。これは AGENT_BROWSER_DEFAULT_TIMEOUT 環境変数でオーバーライドできます (値はミリ秒単位)。遅いWebサイトまたは大きなページの場合、デフォルトタイムアウトに頼るのではなく、明示的な待機を使用してください：

# ネットワークアクティビティが落ち着くまで待つ (遅いページに最適)
agent-browser wait --load networkidle

# 特定の要素が表示されるまで待つ
agent-browser wait "#content"
agent-browser wait @e1

# リダイレクト後に特定のURLパターンを待つ
agent-browser wait --url "**/dashboard"

# JavaScript条件を待つ
agent-browser wait --fn "document.readyState === 'complete'"

# 固定期間 (ミリ秒単位) 待つ (最後の手段)
agent-browser wait 5000

一貫して遅いWebサイトを扱う場合、open 後に wait --load networkidle を使用してページが完全に読み込まれてからスナップショットを取るようにしてください。特定の要素の表示が遅い場合、wait <selector> または wait @ref で直接待機してください。

セッション管理とクリーンアップ

複数のエージェントや自動化を同時に実行する場合は、常に名前付きセッションを使用して競合を回避してください：

# 各エージェントが独立したセッションを取得
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# アクティブなセッションを確認
agent-browser session list

完了したらブラウザセッションを常に閉じてプロセスリークを回避してください：

agent-browser close                    # デフォルトセッションを閉じる
agent-browser --session agent1 close   # 特定セッションを閉じる

前のセッションが適切に閉じられなかった場合、デーモンはまだ実行中かもしれません。新しい作業を始める前に agent-browser close を使用してクリーンアップしてください。

参照ライフサイクル (重要)

参照 (@e1, @e2 など) はページ変更時に無効になります。常に次の後に再スナップショットしてください：

• リンクまたはボタンをクリックしてナビゲート
• フォーム送信
• 動的コンテンツの読み込み (ドロップダウン、モーダル)

agent-browser click @e5              # 新しいページへナビゲート
agent-browser snapshot -i            # 再スナップショット必須
agent-browser click @e1              # 新しい参照を使用

注釈付きスクリーンショット (ビジョンモード)

--annotate を使用してインタラクティブ要素に番号ラベルをオーバーレイしたスクリーンショットを撮ります。各ラベル [N] は参照 @eN にマップされます。また参照がキャッシュされるため、個別のスナップショットなしで要素と直ちにやり取りできます。

agent-browser screenshot --annotate
# 出力には画像パスと凡例が含まれます：
#   [1] @e1 button "Submit"
#   [2] @e2 link "Home"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # 注釈付きスクリーンショットの参照を使ってクリック

次の場合に注釈付きスクリーンショットを使用してください：

• ページがラベルなしのアイコンボタンまたはビジュアルのみの要素を持つ
• ビジュアルレイアウトまたはスタイリングを検証する必要がある
• Canvas またはチャート要素が存在する (テキストスナップショットから見えない)
• 要素位置についての空間推論が必要

セマンティックロケータ (参照の代替)

参照が利用できないまたは信頼できない場合、セマンティックロケータを使用してください：

agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click

JavaScript評価 (eval)

ブラウザコンテキストでJavaScriptを実行するには eval を使用してください。シェルクォーティングは複雑な式を破損させる可能性があります -- --stdin または -b を使用して問題を回避してください。

# シンプルな式は通常のクォーティングで動作
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# 複雑なJS: heredoc付き --stdin を使用 (推奨)
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# 代替：base64エンコーディング (すべてのシェルエスケープの問題を回避)
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

これが重要な理由: シェルがコマンドを処理するとき、内部の二重引用符、! 文字 (履歴展開)、バックティック、$() はすべてJavaScriptを agent-browser に到達する前に破損させる可能性があります。--stdin および -b フラグはシェル解釈を完全にバイパスします。

経験則：

• 1行、ネストされた引用符なし -> eval 'expression' with single quotes は大丈夫
• ネストされた引用符、アロー関数、テンプレートリテラル、またはマルチライン -> eval --stdin <<'EVALEOF' を使用
• プログラム的/生成スクリプト -> base64 付き eval -b を使用

構成ファイル

プロジェクトルートに agent-browser.json を作成して永続的な設定を行います：

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

優先度 (低から高)：~/.agent-browser/config.json < ./agent-browser.json < 環境変数 < CLIフラグ。カスタム構成ファイルに --config <path> または AGENT_BROWSER_CONFIG 環境変数を使用してください (見つからないまたは無効な場合はエラーで終了)。すべてのCLIオプションは camelCase キーにマップされます (例：--executable-path -> "executablePath")。ブール値フラグは true/false 値を受け入れます (例：--headed false は構成をオーバーライド)。ユーザーおよびプロジェクト構成の拡張はマージされ、置換されません。

詳細ドキュメント

リファレンス	使用場面
references/commands.md	すべてのオプション付きの完全なコマンドリファレンス
references/snapshot-refs.md	参照ライフサイクル、無効化ルール、トラブルシューティング
references/session-management.md	並列セッション、ステート永続化、同時スクレイピング
references/authentication.md	ログインフロー、OAuth、2FA処理、ステート再利用
references/video-recording.md	デバッグとドキュメント用のレコーディングワークフロー
references/profiling.md	パフォーマンス分析用のChrome DevToolsプロファイリング
references/proxy-support.md	プロキシ構成、地域テスト、回転プロキシ

実験的：ネイティブモード

agent-browser には Node.js と Playwright をバイパスして Chrome と直接 CDP 経由で通信する実験的なネイティブ Rust デーモンがあります。オプトインであり、本番環境での使用はまだお勧めされません。

# フラグで有効化
agent-browser --native open example.com

# 環境変数で有効化 (毎回 --native を渡さないようにする)
export AGENT_BROWSER_NATIVE=1
agent-browser open example.com

ネイティブデーモンは Chromium と Safari (WebDriver経由) をサポートしています。Firefox と WebKit はまだサポートされていません。すべてのコアコマンド (navigate、snapshot、click、fill、screenshot、cookies、storage、tabs、eval など) はネイティブモードで同じように動作します。同じセッション内でネイティブモードとデフォルトモードを切り替える前に agent-browser close を使用してください。

すぐに使えるテンプレート

テンプレート	説明
templates/form-automation.sh	検証付きのフォーム入力
templates/authenticated-session.sh	ログイン一度、ステート再利用
templates/capture-workflow.sh	スクリーンショット付きコンテンツ抽出

./templates/form-automation.sh https://example.com/form
./templates/authenticated-session.sh https://app.example.com/login
./templates/capture-workflow.sh https://example.com ./output