agent-browser によるブラウザ自動化
CLI は CDP 経由で直接 Chrome/Chromium を使用します。インストールは npm i -g agent-browser、brew install agent-browser、または cargo install agent-browser で行います。agent-browser install を実行すると Chrome がダウンロードされます。agent-browser upgrade で最新バージョンにアップデートできます。
基本ワークフロー
ブラウザ自動化は次のパターンに従います:
- ナビゲート:
agent-browser open <url> - スナップショット:
agent-browser snapshot -i（@e1、@e2などの要素参照を取得） - 操作: 参照を使用してクリック、入力、選択
- 再スナップショット: ナビゲーション後または DOM 変更後に、新しい参照を取得
agent-browser open https://example.com/form
agent-browser snapshot -i
# 出力: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # 結果を確認
コマンドチェーン
コマンドは単一のシェル呼び出し内で && を使ってチェーンできます。ブラウザはバックグラウンドデーモンを介してコマンド間で永続化されるため、チェーンは個別の呼び出しよりも安全で効率的です。
# 1回の呼び出しで open + wait + snapshot をチェーン
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# 複数の操作をチェーン
agent-browser fill @e1 "[email protected]" && 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）に && を使用します。最初に出力を解析する必要がある場合（例: スナップショットで参照を発見し、その参照を使って操作する）は、コマンドを個別に実行します。
認証の処理
ログインが必要なサイトを自動化する場合は、適切なアプローチを選択してください:
オプション 1: ユーザーのブラウザから認証をインポート（1回限りのタスクに最速）
# ユーザーの実行中の Chrome に接続（ユーザーは既にログイン済み）
agent-browser --auto-connect state save ./auth.json
# その認証状態を使用
agent-browser --state ./auth.json open https://app.example.com/dashboard
状態ファイルにはセッショントークンが平文で含まれています。.gitignore に追加し、不要になったら削除してください。保存時に暗号化するには AGENT_BROWSER_ENCRYPTION_KEY を設定します。
オプション 2: 永続プロファイル（繰り返しタスクに最も簡単）
# 初回実行: 手動または自動化でログイン
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 認証情報を入力、送信 ...
# 以降の実行: 認証済み
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
オプション 3: セッション名（Cookie + localStorage の自動保存/復元）
agent-browser --session-name myapp open https://app.example.com/login
# ... ログインフロー ...
agent-browser close # 状態が自動保存される
# 次回: 状態が自動復元される
agent-browser --session-name myapp open https://app.example.com/dashboard
オプション 4: 認証ボールト（資格情報を暗号化して保存、名前でログイン）
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login は load でナビゲートした後、ログインフォームのセレクタが表示されるのを待ってから入力/クリックを行うため、遅延のある SPA ログイン画面でより信頼性が高くなります。
オプション 5: 状態ファイル（手動保存/読み込み）
# ログイン後:
agent-browser state save ./auth.json
# 将来のセッションで:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
OAuth、2FA、Cookieベース認証、トークン更新パターンについては references/authentication.md を参照してください。
基本コマンド
# ナビゲーション
agent-browser open <url> # ナビゲート（エイリアス: goto, navigate）
agent-browser close # ブラウザを閉じる
agent-browser close --all # 全てのアクティブセッションを閉じる
# スナップショット
agent-browser snapshot -i # 参照付きの操作可能要素（推奨）
agent-browser snapshot -s "#selector" # CSSセレクタで範囲指定
# 操作（スナップショットの @ref を使用）
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 get cdp-url # CDP WebSocket URL を取得
# 待機
agent-browser wait @e1 # 要素を待機
agent-browser wait --load networkidle # ネットワークアイドルを待機
agent-browser wait --url "**/page" # URLパターンを待機
agent-browser wait 2000 # ミリ秒待機
agent-browser wait --text "Welcome" # テキストが表示されるのを待機（部分一致）
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # テキストが消えるのを待機
agent-browser wait "#spinner" --state hidden # 要素が消えるのを待機
# ダウンロード
agent-browser download @e1 ./file.pdf # 要素をクリックしてダウンロードをトリガー
agent-browser wait --download ./output.zip # ダウンロード完了を待機
agent-browser --download-path ./downloads open <url> # デフォルトダウンロードディレクトリを設定
# ネットワーク
agent-browser network requests # 追跡されたリクエストを表示
agent-browser network requests --type xhr,fetch # リソースタイプでフィルタ
agent-browser network requests --method POST # HTTPメソッドでフィルタ
agent-browser network requests --status 2xx # ステータスコードでフィルタ（200、2xx、400-499）
agent-browser network request <requestId> # リクエスト/レスポンスの詳細を表示
agent-browser network route "**/api/*" --abort # 一致するリクエストをブロック
agent-browser network har start # HAR録音を開始
agent-browser network har stop ./capture.har # 停止してHARファイルを保存
# ビューポートとデバイスエミュレーション
agent-browser set viewport 1920 1080 # ビューポートサイズを設定（デフォルト: 1280x720）
agent-browser set viewport 1920 1080 2 # 2倍Retina（CSSサイズは同じ、高解像度スクリーンショット）
agent-browser set device "iPhone 14" # デバイスをエミュレート（ビューポート＋ユーザーエージェント）
# キャプチャ
agent-browser screenshot # 一時ディレクトリにスクリーンショット
agent-browser screenshot --full # ページ全体のスクリーンショット
agent-browser screenshot --annotate # 番号付き要素ラベル付きの注釈スクリーンショット
agent-browser screenshot --screenshot-dir ./shots # カスタムディレクトリに保存
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # PDFとして保存
# ライブプレビュー / ストリーミング
agent-browser stream enable # 自動選択ポートでWebSocketストリーミングを開始
agent-browser stream enable --port 9223 # 特定のローカルホストポートにバインド
agent-browser stream status # 有効状態、ポート、接続、スクリーンキャスト状態を表示
agent-browser stream disable # ストリーミングを停止し、.stream メタデータファイルを削除
# クリップボード
agent-browser clipboard read # クリップボードからテキストを読み取る
agent-browser clipboard write "Hello, World!" # クリップボードにテキストを書き込む
agent-browser clipboard copy # 現在の選択範囲をコピー
agent-browser clipboard paste # クリップボードから貼り付け
# ダイアログ（alert、confirm、prompt、beforeunload）
# デフォルトでは、alert と beforeunload ダイアログは自動的に承認されるため、エージェントをブロックしません。
# confirm と prompt ダイアログは明示的な処理が必要です。
# --no-auto-dialog を使用すると自動処理を無効にできます。
agent-browser dialog accept # ダイアログを承認
agent-browser dialog accept "my input" # プロンプトダイアログにテキストを入力して承認
agent-browser dialog dismiss # ダイアログを閉じる/キャンセル
agent-browser dialog status # ダイアログが現在開いているか確認
# 差分（ページ状態の比較）
agent-browser diff snapshot # 現在のスナップショットと最後のスナップショットを比較
agent-browser diff snapshot --baseline before.txt # 現在のスナップショットと保存ファイルを比較
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" # 要素に範囲を限定
ストリーミング
すべてのセッションは、OSが割り当てたポートで自動的にWebSocketストリームサーバーを起動します。agent-browser stream status を使用して、バインドされたポートと接続状態を確認できます。stream disable で終了し、stream enable --port <port> で特定のポートで再び有効にできます。
バッチ実行
JSON配列の文字列配列を batch にパイプすることで、単一の呼び出しで複数のコマンドを実行できます。これにより、複数ステップのワークフロー実行時のコマンドごとのプロセス起動オーバーヘッドを回避できます。
echo '[
["open", "https://example.com"],
["snapshot", "-i"],
["click", "@e1"],
["screenshot", "result.png"]
]' | agent-browser batch --json
# 最初のエラーで停止
agent-browser batch --bail < commands.json
既知のコマンドシーケンスで、中間出力に依存しない場合は batch を使用します。ステップ間で出力を解析する必要がある場合（例: スナップショットで参照を発見してから操作する）は、個別のコマンドまたは && チェーンを使用します。
一般的なパターン
フォーム送信
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
認証ボールトによる認証（推奨）
# 資格情報を一度保存（AGENT_BROWSER_ENCRYPTION_KEY で暗号化）
# 推奨: シェル履歴への露出を避けるため、パスワードは標準入力からパイプする
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
auth login は、操作前にユーザー名/パスワード/送信セレクタが表示されるのを待ち、デフォルトのアクションタイムアウトに連動したタイムアウトがあります。
状態永続化による認証
# 一度ログインして状態を保存
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
セッション永続化
# ブラウザ再起動時にCookieと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
iframe の操作
iframe のコンテンツはスナップショットに自動的にインライン化されます。iframe 内の参照にはフレームコンテキストが含まれるため、直接操作できます。
agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
# @e3 [input] "Card number"
# @e4 [input] "Expiry"
# @e5 [button] "Pay"
# 直接操作 — フレーム切り替えは不要
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5
# スナップショットを1つのiframeに限定するには:
agent-browser frame @e2
agent-browser snapshot -i # iframeのコンテンツのみ
agent-browser frame main # メインフレームに戻る
データ抽出
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
Auto-connect は DevToolsActivePort、一般的なデバッグポート（9222、9229）を介してChromeを検出し、HTTPベースのCDP検出が失敗した場合は、直接WebSocket接続にフォールバックします。
カラースキーム
--color-scheme フラグを使用して、ページのカラースキームを制御できます:
agent-browser --color-scheme dark open https://example.com
agent-browser --color-scheme light open https://example.com
グローバルフラグ
agent-browser --help # ヘルプを表示
agent-browser --version # バージョンを表示
agent-browser --verbose # 詳細なログ出力を有効化
agent-browser --timeout 30000 # デフォルトのタイムアウトをミリ秒単位で設定（デフォルト: 30000）
agent-browser --action-timeout 5000 # 操作タイムアウトをミリ秒単位で設定（fill、clickなど）（デフォルト: 5000）
agent-browser --color-scheme dark # カラースキームを設定（light、dark、system）
agent-browser --download-path ./dl # ダウンロードディレクトリを設定
環境変数
export AGENT_BROWSER_ENCRYPTION_KEY=... # 認証ボールトとセッション状態の保存時の暗号化キー
export AGENT_BROWSER_DATA_DIR=... # データディレクトリのカスタムパス（デフォルト: ~/.agent-browser）
export AGENT_BROWSER_CHROME_PATH=... # Chrome/Chromiumバイナリへのカスタムパス
export AGENT_BROWSER_CDP_URL=... # 接続用のCDP WebSocket URL（--auto-connectと同じ）
export AGENT_BROWSER_DEBUG=... # デバッグログを有効化
export AGENT_BROWSER_DOWNLOAD_PATH=... # デフォルトのダウンロードディレクトリ
export AGENT_BROWSER_TIMEOUT=... # デフォルトのタイムアウト（ミリ秒）
export AGENT_BROWSER_ACTION_TIMEOUT=... # アクションタイムアウト（ミリ秒）
export AGENT_BROWSER_SESSION_FILE=... # セッション状態のファイルパス
export HOME=... # （セッション状態がデフォルトで保存される場所）
export AGENT_BROWSER_LOG_LEVEL=... # ログレベル: error、warn、info、debug、trace（デフォルト: info）
既知の制限
- ヘッドフルモード: デフォルトでは、agent-browser はヘッドレスモードで Chrome を起動します。GUI を表示するには、
AGENT_BROWSER_HEADLESS=falseを設定するか、--headless falseフラグを使用します。 - 複数のブラウザインスタンス: 各セッションは独自のブラウザインスタンスを管理します。
agent-browser session listでアクティブなセッションを確認できます。 - ファイルサイズの制限: 大きなページや大量のネットワークリクエストがあるページでは、スナップショットの生成が遅くなったり、大量の出力が発生したりする可能性があります。スナップショットのスコープを特定の要素に限定するには、
-sフラグを使用します。 - WebSocketの安定性: 不安定なネットワーク環境では、WebSocket ストリームが切断される可能性があります。
agent-browser stream statusで接続状態を確認し、必要に応じてstream enableで再接続してください。