agent-browser によるブラウザ自動化
このCLIは、CDPを介してChrome/Chromiumを直接操作します。npm i -g agent-browser、brew install agent-browser、またはcargo install agent-browserでインストールしてください。agent-browser installを実行するとChromeがダウンロードされます。既存のChrome、Brave、Playwright、Puppeteerのインストールは自動的に検出されます。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 2000
agent-browser snapshot -i # 結果を確認
コマンドチェーン
コマンドは単一シェル呼び出し内で&&を使ってチェーンできます。ブラウザはバックグラウンドデーモンを介してコマンド間で維持されるため、チェーンは個別の呼び出しよりも安全で効率的です。
# チェーン: open + snapshot(openはページロードを待機)
agent-browser open https://example.com && 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 screenshot
チェーンを使用すべき場合: 中間コマンドの出力を読み取る必要がない場合(例:open + wait + screenshot)は&&を使用します。出力を解析してから次のコマンドを決定する必要がある場合(例:snapshotで参照を発見し、その参照を使って操作する場合)は、コマンドを個別に実行してください。
認証の処理
ログインが必要なサイトを自動化する場合、状況に応じて適切な方法を選択してください:
オプション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: Chromeプロファイルの再利用(設定不要)
# 利用可能なChromeプロファイルを一覧表示
agent-browser profiles
# ユーザーの既存のChromeログイン状態を再利用
agent-browser --profile Default open https://gmail.com
オプション3: 永続プロファイル(繰り返しタスク向け)
# 初回実行: 手動または自動化でログイン
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 認証情報を入力、送信 ...
# 以降の実行: すでに認証済み
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
オプション4: セッション名(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
オプション5: 認証ボールト(暗号化された認証情報、名前でログイン)
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ログイン画面でも信頼性が高まります。
オプション6: 状態ファイル(手動保存/読み込み)
# ログイン後:
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を参照してください。
主要コマンド
# バッチ: 2つ以上の連続コマンドでは常にバッチを使用。コマンドは順番に実行されます。
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# ナビゲーション
agent-browser open <url> # ナビゲート(エイリアス: goto, navigate)
agent-browser close # ブラウザを閉じる
agent-browser close --all # すべてのアクティブセッションを閉じる
# スナップショット
agent-browser snapshot -i # 参照付きのインタラクティブ要素(推奨)
agent-browser snapshot -i --urls # リンクのhref URLを含める
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 2000 # ミリ秒待機
agent-browser wait --url "**/page" # URLパターンを待機
agent-browser wait --text "Welcome" # テキストが表示されるのを待機(部分一致)
agent-browser wait --load networkidle # ネットワークアイドルを待機(注意: 落とし穴を参照)
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 tab list # 開いているタブをすべて一覧表示
agent-browser tab new # 空白の新しいタブを開く
agent-browser tab new https://example.com # 新しいタブでURLを開く
agent-browser tab 2 # タブインデックスで切り替え(0ベース)
agent-browser tab close # 現在のタブを閉じる
agent-browser tab close 2 # インデックスを指定してタブを閉じる
# ネットワーク
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 # 特定のlocalhostポートをバインド
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_NO_AUTO_DIALOG=1)を使用すると、自動処理を無効にできます。
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" # 要素に範囲を限定
# チャット(AIによる自然言語制御)
agent-browser chat "open google.com and search for cats" # 単発指示
agent-browser chat # インタラクティブREPLモード
agent-browser -q chat "summarize this page" # 静か(テキストのみ、ツール呼び出しなし)
agent-browser -v chat "fill in the login form" # 詳細(コマンド出力を表示)
agent-browser --model openai/gpt-4o chat "take a screenshot" # モデルをオーバーライド
ストリーミング
すべてのセッションは、OSが割り当てたポートで自動的にWebSocketストリームサーバーを開始します。agent-browser stream statusを使用して、バインドされたポートと接続状態を確認します。stream disableで停止し、stream enable --port <port>で特定のポートで再有効化します。
バッチ実行
2つ以上のコマンドを連続して実行する場合は、常にbatchを使用してください。バッチはコマンドを順番に実行するため、依存関係のあるコマンド(navigateしてからscreenshotなど)が正しく動作します。各引用符で囲まれた引数は個別のコマンドです。
# ナビゲートしてスナップショットを撮る
agent-browser batch "open https://example.com" "snapshot -i"
# ナビゲート、スナップショット、スクリーンショットを一度に
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# クリック、待機、スクリーンショット
agent-browser batch "click @e1" "wait 1000" "screenshot"
# --bail を使用して最初のエラーで停止
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
次のコマンドを決定する前に出力を読み取る必要がある場合にのみ、単一コマンド(batchではない)を使用します。たとえば、何をクリックするかを決めるために参照を読み取る必要がある場合は、snapshot -iを単一コマンドとして実行する必要があります。スナップショットを読み取った後、残りの手順をバッチ処理します。
stdinモードもプログラムでの使用のためにサポートされています:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
効率化戦略
これらのパターンは、ツール呼び出しとトークン使用量を最小限に抑えます。
再ナビゲーションを避けるために--urlsを使用する。 ページからリンクにアクセスする必要がある場合は、snapshot -i --urlsを使用してすべてのhref URLを事前に取得します。その後、参照をクリックして戻る代わりに、各URLを直接openします。
一度スナップショットを撮り、何度も操作する。 同じページを再スナップショットしないでください。単一のスナップショットから必要な情報(参照、URL、テキスト)をすべて抽出し、残りのアクションをバッチ処理します。
マルチページワークフロー(例:「N個のサイトを訪問し、それぞれスクリーンショットを撮る」):
# 1. 一度の呼び出しですべてのURLを取得
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 出力を読み取ってURLを抽出し、各サイトに直接アクセス:
# 2. ターゲットサイトごとに1つのバッチ
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"
このアプローチでは、14回以上のツール呼び出しではなく4回で済みます。訪問の間に一覧ページに戻らないでください。
一般的なパターン
フォーム送信
# ナビゲートしてフォーム構造を取得
agent-browser batch "open https://example.com/signup" "snapshot -i"
# スナップショット出力を読み取ってフォーム参照を特定し、入力と送信
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
認証ボールトを使用した認証(推奨)
# 認証情報を一度保存(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 batch "open https://example.com" "get text @e1"
# すべてのリンクを取得
agent-browser batch "open https://example.com" "snapshot -i --urls"
# 属性の抽出(get textの代わりにget attributeを使用)
agent-browser batch "open https://example.com" "get attribute @e1 href"
タブ間での作業
# 最初のタブで何かを行い、新しいタブを開き、切り替え、スクリーンショットを撮る
agent-browser batch "open https://example.com/page1" "tab new https://example.com/page2" "tab 2" "screenshot"
# すべてのタブを一覧表示
agent-browser tab list
# タブを閉じる
agent-browser tab close 2
落とし穴と注意事項
wait --load networkidleに注意
ネットワークアイドル待機は、特に以下を含むページでは信頼性が低いか、予想よりも大幅に遅くなる可能性があります:
- 長いポーリング
- サーバー送信イベント(SSE)
- 継続的なWebSocket接続
- アナリティクススクリプト
代わりに、可能な場合は--wait-until domcontentloaded(デフォルト)を使用するか、スペシフィックな要素セレクターやテキストベースの待機条件を使用してください。
自動ダイアログ処理
デフォルトでは、alert(警告)とbeforeunload(アンロード前)ダイアログは自動的に許可され、エージェントをブロックしません。confirm(確認)とprompt(プロンプト)ダイアログは明示的な処理が必要です。--no-auto-dialogフラグ(または環境変数AGENT_BROWSER_NO_AUTO_DIALOG=1)を使用すると、この自動処理を無効にできます。
ダウンロード
ダウンロードは、ファイルがディスクに完全に書き込まれる前にエージェントが続行しようとする可能性があるため、注意が必要です。ダウンロードをトリガーした後は常にwait --downloadを使用して、ファイルが完全に書き込まれるのを確認してから続行してください。
リソース消費
各agent-browserコマンドはコマンド間でブラウザを開いたままにするデーモンを作成します。リソースを節約するために、不要になったらcloseを使用してブラウザを閉じてください。
トラブルシューティング
一般的な問題
agent-browser: command not found:npm install -g agent-browserでグローバルにインストールされていることを確認してください。Could not find Chrome:agent-browser installを実行してChromeをダウンロードするか、使用するパスをAGENT_BROWSER_CHROME_PATH環境変数で指定します。Connection refused: ブラウザがcloseされた後、またはタイムアウト後にコマンドを実行しようとしています。もう一度openして新しいセッションを開始してください。@e1が無効: スナップショットを撮った後、ブラウザがページ間を移動すると参照が無効になります。ページが変更された後は、もう一度snapshot -iを実行して更新された参照を取得してください。
デバッグ
より詳細な出力を得るには、--verbose(または-v)フラグを任意のコマンドに追加します:
agent-browser -v open https://example.com
ダウンロードディレクトリを指定するには、--download-pathフラグを使用します:
agent-browser --download-path ./downloads open https://example.com