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

agent-browser を使う場面: CLI 優先のヘッドレス CDP 自動化 — ブラウザ拡張機能やピクセル単位のスクリーンショットは不要です。スクリプト化された Web ワークフロー、CI に適したブラウザテスト、GUI インタラクションではなくシェルコマンドを使用したセッションベースのスクレイピングに最適です。

クイックスタート

agent-browser open <url>        # ページへ移動
agent-browser snapshot -i       # インタラクティブ要素と参照を取得
agent-browser click @e1         # 参照でクリック
agent-browser fill @e2 "text"   # 参照で入力を入力
agent-browser close             # ブラウザを閉じる

コアワークフロー

移動: agent-browser open <url>
スナップショット: agent-browser snapshot -i (@e1、@e2 などの参照を返します)
スナップショットの参照を使用してインタラクト
移動または DOM の大きな変更後に再スナップショット

コマンド

移動

agent-browser open <url>      # URL に移動 (エイリアス: goto, navigate)
                              # サポート: https://, http://, file://, about:, data://
                              # プロトコル指定がない場合は自動的に https:// を追加
agent-browser back            # 戻る
agent-browser forward         # 進む
agent-browser reload          # ページを再読込
agent-browser close           # ブラウザを閉じる (エイリアス: quit, exit)
agent-browser connect 9222    # CDP ポート経由でブラウザに接続

スナップショット (ページ分析)

agent-browser snapshot            # フルアクセシビリティツリー
agent-browser snapshot -i         # インタラクティブ要素のみ (推奨)
agent-browser snapshot -c         # コンパクト出力
agent-browser snapshot -d 3       # 深さを 3 に制限
agent-browser snapshot -s "#main" # CSS セレクタにスコープ

インタラクション (スナップショットの @refs を使用)

agent-browser click @e1           # クリック
agent-browser dblclick @e1        # ダブルクリック
agent-browser focus @e1           # 要素にフォーカス
agent-browser fill @e2 "text"     # クリアして入力
agent-browser type @e2 "text"     # クリアせずに入力
agent-browser press Enter         # キーを押す (エイリアス: key)
agent-browser press Control+a     # キーの組み合わせ
agent-browser keydown Shift       # キーを押さえつける
agent-browser keyup Shift         # キーを離す
agent-browser hover @e1           # ホバー
agent-browser check @e1           # チェックボックスをチェック
agent-browser uncheck @e1         # チェックボックスをアンチェック
agent-browser select @e1 "value"  # ドロップダウンオプションを選択
agent-browser select @e1 "a" "b"  # 複数オプションを選択
agent-browser scroll down 500     # ページをスクロール (デフォルト: 下 300px)
agent-browser scrollintoview @e1  # 要素をビューにスクロール (エイリアス: scrollinto)
agent-browser drag @e1 @e2        # ドラッグアンドドロップ
agent-browser upload @e1 file.pdf # ファイルをアップロード

情報を取得

agent-browser get text @e1        # 要素テキストを取得
agent-browser get html @e1        # innerHTML を取得
agent-browser get value @e1       # 入力値を取得
agent-browser get attr @e1 href   # 属性を取得
agent-browser get title           # ページタイトルを取得
agent-browser get url             # 現在の URL を取得
agent-browser get count ".item"   # マッチング要素数をカウント
agent-browser get box @e1         # バウンディングボックスを取得
agent-browser get styles @e1      # 計算済みスタイル (フォント、色、背景など) を取得

状態を確認

agent-browser is visible @e1      # 表示されているか確認
agent-browser is enabled @e1      # 有効になっているか確認
agent-browser is checked @e1      # チェック状態か確認

スクリーンショット & PDF

agent-browser screenshot "body" path.png  # ビューポートスクリーンショットをファイルに保存
agent-browser screenshot --full "body" path.png  # フルページをファイルに保存
agent-browser screenshot "body"           # ビューポートスクリーンショット (tmp に自動保存)
agent-browser screenshot ".modal" modal.png  # 特定要素のスクリーンショット
agent-browser pdf output.pdf              # PDF として保存

v0.9.1 の注意事項: screenshot には最初のポジショナル引数として CSS セレクタが必要です。フルビューポートキャプチャには "body" を使用します。セレクタを省略すると Validation error: selector: Expected string, received null が発生します。

動画記録

agent-browser record start ./demo.webm    # 記録を開始 (現在の URL と状態を使用)
agent-browser click @e1                   # アクションを実行
agent-browser record stop                 # 記録を停止して保存
agent-browser record restart ./take2.webm # 現在の記録を停止して新しい記録を開始

記録は新しいコンテキストを作成しますが、セッションのクッキーとストレージを保持します。URL が提供されない場合、自動的に現在のページに戻ります。スムーズなデモのために、まず探索してから記録を開始します。

待機

agent-browser wait @e1                     # 要素を待機
agent-browser wait 2000                    # ミリ秒数分待機
agent-browser wait --text "Success"        # テキストを待機 (または -t)
agent-browser wait --url "**/dashboard"    # URL パターンを待機 (または -u)
agent-browser wait --load networkidle      # ネットワーク待機時間を待機 (または -l)
agent-browser wait --fn "window.ready"     # JS 条件を待機 (または -f)

マウス制御

agent-browser mouse move 100 200      # マウスを移動
agent-browser mouse down left         # ボタンを押す
agent-browser mouse up left           # ボタンを離す
agent-browser mouse wheel 100         # マウスホイールをスクロール

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

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find text "Sign In" click --exact      # 完全一致のみ
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "query"
agent-browser find alt "Logo" click
agent-browser find title "Close" click
agent-browser find testid "submit-btn" click
agent-browser find first ".item" click
agent-browser find last ".item" click
agent-browser find nth 2 "a" hover

ブラウザ設定

agent-browser set viewport 1920 1080          # ビューポートサイズを設定
agent-browser set device "iPhone 14"          # デバイスをエミュレート
agent-browser set geo 37.7749 -122.4194       # 地理情報を設定 (エイリアス: geolocation)
agent-browser set offline on                  # オフラインモードを切り替え
agent-browser set headers '{"X-Key":"v"}'     # 追加 HTTP ヘッダー
agent-browser set credentials user pass       # HTTP ベース認証 (エイリアス: auth)
agent-browser set media dark                  # カラースキームをエミュレート
agent-browser set media light reduced-motion  # ライトモード + 動作削減

クッキーとストレージ

agent-browser cookies                     # すべてのクッキーを取得
agent-browser cookies set name value      # クッキーを設定
agent-browser cookies clear               # クッキーをクリア
agent-browser storage local               # すべての localStorage を取得
agent-browser storage local key           # 特定のキーを取得
agent-browser storage local set k v       # 値を設定
agent-browser storage local clear         # すべてをクリア

ネットワーク

agent-browser network route <url>              # リクエストをインターセプト
agent-browser network route <url> --abort      # リクエストをブロック
agent-browser network route <url> --body '{}'  # レスポンスをモック
agent-browser network unroute [url]            # ルートを削除
agent-browser network requests                 # トラッキングされたリクエストを表示
agent-browser network requests --filter api    # リクエストをフィルター

タブとウィンドウ

agent-browser tab                 # タブをリスト
agent-browser tab new [url]       # 新しいタブ
agent-browser tab 2               # インデックスでタブに切り替え
agent-browser tab close           # 現在のタブを閉じる
agent-browser tab close 2         # インデックスでタブを閉じる
agent-browser window new          # 新しいウィンドウ

フレーム

agent-browser frame "#iframe"     # iframe に切り替え
agent-browser frame main          # メインフレームに戻す

ダイアログ

agent-browser dialog accept [text]  # ダイアログを受け入れ
agent-browser dialog dismiss        # ダイアログを閉じる

JavaScript

agent-browser eval "document.title"   # JavaScript を実行

グローバルオプション

agent-browser --session <name> ...    # 分離されたブラウザセッション
agent-browser --json ...              # 解析用 JSON 出力
agent-browser --headed ...            # ブラウザウィンドウを表示 (ヘッドレスではない)
agent-browser --full ...              # フルページスクリーンショット (-f)
agent-browser --cdp <port> ...        # Chrome DevTools Protocol で接続
agent-browser -p <provider> ...       # クラウドブラウザプロバイダー (--provider)
agent-browser --proxy <url> ...       # プロキシサーバーを使用
agent-browser --headers <json> ...    # URL のオリジンをスコープとした HTTP ヘッダー
agent-browser --executable-path <p>   # カスタムブラウザ実行可能ファイル
agent-browser --extension <path> ...  # ブラウザ拡張機能をロード (繰り返し可)
agent-browser --help                  # ヘルプを表示 (-h)
agent-browser --version               # バージョンを表示 (-V)
agent-browser <command> --help        # コマンドの詳細ヘルプを表示

プロキシサポート

agent-browser --proxy http://proxy.com:8080 open example.com
agent-browser --proxy http://user:pass@proxy.com:8080 open example.com
agent-browser --proxy socks5://proxy.com:1080 open example.com

環境変数

AGENT_BROWSER_SESSION="mysession"            # デフォルトセッション名
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # カスタムブラウザパス
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # カンマ区切り拡張機能パス
AGENT_BROWSER_PROVIDER="browserbase"         # クラウドブラウザプロバイダー
AGENT_BROWSER_STREAM_PORT="9223"             # WebSocket ストリーミングポート
AGENT_BROWSER_HOME="/path/to/agent-browser"  # カスタムインストール場所 (daemon.js 用)

例: フォーム送信

agent-browser open https://example.com/form
agent-browser snapshot -i
# 出力: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]

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  # 結果を確認

例: 保存された状態による認証

# 1 回ログイン
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

セッション (並列ブラウザ)

agent-browser --session test1 open site-a.com
agent-browser --session test2 open site-b.com
agent-browser session list

JSON 出力 (解析用)

--json を追加して機械可読出力を得ます:

agent-browser snapshot -i --json
agent-browser get text @e1 --json

デバッグ

agent-browser --headed open example.com   # ブラウザウィンドウを表示
agent-browser --cdp 9222 snapshot         # CDP ポート経由で接続
agent-browser connect 9222                # 代替: connect コマンド
agent-browser console                     # コンソールメッセージを表示
agent-browser console --clear             # コンソールをクリア
agent-browser errors                      # ページエラーを表示
agent-browser errors --clear              # エラーをクリア
agent-browser highlight @e1               # 要素をハイライト
agent-browser trace start                 # トレース記録を開始
agent-browser trace stop trace.zip        # トレースを停止して保存
agent-browser record start ./debug.webm   # 現在のページから動画を記録
agent-browser record stop                 # 記録を保存

詳細ドキュメント

詳細なパターンとベストプラクティスについては、以下を参照してください:

リファレンス	説明
references/snapshot-refs.md	参照のライフサイクル、無効化ルール、トラブルシューティング
references/session-management.md	並列セッション、状態永続化、並行スクレイピング
references/authentication.md	ログインフロー、OAuth、2FA 処理、状態の再利用
references/video-recording.md	デバッグとドキュメント化のための記録ワークフロー
references/proxy-support.md	プロキシ設定、ジオテスト、プロキシローテーション

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

一般的なパターンの実行可能なワークフロースクリプト:

テンプレート	説明
templates/form-automation.sh	検証付きフォーム入力
templates/authenticated-session.sh	1 回ログイン、状態を再利用
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

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

agent-browser

SKILL.md 本文