agent-browser によるブラウザ自動化
CLIはChrome/ChromiumをCDP経由で直接使用します。インストールは npm i -g agent-browser、brew install agent-browser、または cargo install agent-browser で行います。agent-browser install を実行してChromeをダウンロードしてください。
基本ワークフロー
ブラウザ自動化は以下のパターンに従います。
- ナビゲート:
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 を1回で実行
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)。出力をパースする必要がある場合はコマンドを個別に実行します(例: snapshotで参照を取得し、その参照を使って操作)。
認証の扱い
ログインが必要なサイトを自動化する場合、適切な方法を選択してください。
オプション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: セッション名(クッキー + 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
オプション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 snapshot -i # インタラクティブ要素と参照(推奨)
agent-browser snapshot -i -C # カーソルインタラクティブ要素を含める(onclickを持つdiv、cursor:pointer)
agent-browser snapshot -s "#selector" # CSSセレクターでスコープ指定
# 操作(snapshotで取得した@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 set viewport 1920 1080 # ビューポートサイズ設定(デフォルト: 1280x720)
agent-browser set viewport 1920 1080 2 # 2xレチナ(同一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 clipboard read # クリップボードからテキストを読み込み
agent-browser clipboard write "Hello, World!" # クリップボードにテキストを書き込み
agent-browser clipboard copy # 現在の選択範囲をコピー
agent-browser clipboard paste # クリップボードから貼り付け
# 差分比較(ページ状態の比較)
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" # 要素でスコープ
よくあるパターン
フォーム送信
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で暗号化)
# 推奨: パスワードはシェル履歴に残らないよう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
ビューポートとレスポンシブテスト
# カスタムビューポートサイズを設定(デフォルトは1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# モバイル幅のレイアウトをテスト
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# レチナ/HiDPI: 同一CSSレイアウトを2倍のピクセル密度でレンダリング
# スクリーンショットは論理ビューポートサイズのまま、コンテンツは高DPIで描画
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# デバイスエミュレーション(ビューポート + ユーザーエージェントを一度に設定)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
scaleパラメータ(3番目の引数)は window.devicePixelRatio を設定しますが、CSSレイアウトは変更しません。レチナレンダリングのテストや高解像度スクリーンショットの取得に使用します。
ビジュアルブラウザ(デバッグ)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # 要素をハイライト
agent-browser inspect # アクティブページでChrome DevToolsを開く
agent-browser record start demo.webm # セッションを録画
agent-browser profiler start # Chrome DevToolsプロファイリング開始
agent-browser profiler stop trace.json # 停止してプロファイル保存(パスはオプション)
環境変数 AGENT_BROWSER_HEADED=1 でヘッドモードを有効にできます。ブラウザ拡張機能はヘッドモードとヘッドレスの両方で動作します。
ローカルファイル(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シミュレーター(モバイルSafari)
# 利用可能なiOSシミュレーターを一覧表示
agent-browser device list
# 特定のデバイスでSafariを起動
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# デスクトップと同様のワークフロー: snapshot、操作、再snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # タップ(Clickの別名)
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 + Xcode、Appium(npm install -g appium && appium driver install xcuitest)
実機: 事前設定済みの物理iOSデバイスでも動作します。--device "<UDID>" を使用します。UDIDは xcrun xctrace list devices で取得できます。
セキュリティ
すべてのセキュリティ機能はオプトインです。デフォルトでは、agent-browserはナビゲーション、アクション、出力に制限を設けません。
コンテンツ境界(AIエージェント推奨)
--content-boundaries を有効にすると、ページから取得した出力にマーカーをラップし、LLMがツール出力と信頼できないページコンテンツを区別しやすくなります。
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# 出力:
# --- 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_ALLOWLIST_DOMAINS="*.example.com,*.auth.com,cdn.example.com"
agent-browser open https://example.com # 許可
agent-browser open https://evil.com # ブロック
読み取り専用モード
export AGENT_BROWSER_READONLY=1
agent-browser open https://example.com
agent-browser snapshot -i # 可能
agent-browser click @e1 # ブロック