agent-browser

agent-browser スキル

AI エージェント向けに実際に機能するブラウザー自動化ツールです。LLM 主導のワークフロー向けに Vercel Labs が開発しました。

代替手段より優れている理由

1. 決定論的な参照（画期的な機能）

従来のツールの問題点：

• ウェブサイトが変更されると CSS セレクターが壊れます
• XPath は脆弱で、読みづらいです
• 座標ベースのクリックは、レスポンシブレイアウトで失敗します
• ビジョンベースの方法は遅く、コストがかかります

agent-browser による解決策：

# 1. Get snapshot with stable refs
agent-browser snapshot -i --json
# Output: - button "Submit" [ref=e2]

# 2. Use that ref forever — it points to the EXACT element
agent-browser click @e2

• 参照は決定論的です — @e2 はスナップショット内の常に同じ要素を指します
• DOM の再検索は不要です — 直接参照するほうが高速で信頼性に優れています
• AI 向けに最適化されています — LLM は CSS の寄せ集めではなく、アクセシビリティツリーを自然に解析します

2. スクリーンショット／HTML よりアクセシビリティツリー

従来のツールが提供するのは、未加工の HTML（ノイズが多い）かスクリーンショット（ビジョンモデルが必要）です。

agent-browser はアクセシビリティツリーを提供します。これは、人間（またはスクリーンリーダー）が認識する内容を、明快かつ意味的に表現したものです。

- heading "Billing" [level=1]
- link "Make a payment" [ref=e10]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]

• 意味的なロール（ボタン、リンク、テキストボックス、見出し）
• 人が読みやすいラベル
• 階層構造
• LLM が理解するのに最適

3. AI エージェント向けに開発

機能	従来のツール	agent-browser
要素の指定	脆弱なセレクター	決定論的な参照
ページの理解	未加工の HTML	アクセシビリティツリー
出力形式	テキストログ	構造化 JSON
速度	遅い（コマンドごとにブラウザー全体を起動）	高速（デーモンが常駐）
AI との統合	後付け	専用設計

4. 高速なアーキテクチャ

• Rust CLI — ネイティブバイナリによる即時のコマンド解析
• Node.js デーモン — コマンド間でブラウザーを起動状態に維持
• 最初のコマンド： 約 2 秒（デーモンの起動）
• 以降のコマンド： 約 100 ミリ秒

前提条件

npm install -g agent-browser
agent-browser install  # Download Chromium (~30s)

AI の基本ワークフロー

LLM エージェント向けに設計されたワークフロー：

# Step 1: Navigate
agent-browser open https://example.com

# Step 2: Get structured snapshot (the AI "sees" the page)
agent-browser snapshot -i --json

# Step 3: AI picks refs from JSON, execute actions
agent-browser click @e2
agent-browser fill @e3 "[email protected]"

# Step 4: Re-snapshot after changes (state verification)
agent-browser snapshot -i --json

# Step 5: Done
agent-browser close

コマンド

ナビゲーション

agent-browser open example.com
agent-browser open example.com --json            # JSON response
agent-browser open example.com --headed          # Visible browser

スナップショット（最も強力な機能）

agent-browser snapshot                           # Full accessibility tree
agent-browser snapshot -i                        # Interactive only (faster)
agent-browser snapshot -i --json                 # JSON for AI parsing
agent-browser snapshot -i -c -d 5 --json         # Compact, depth-limited

操作（決定論的な参照を使用）

agent-browser click @e2                          # Click element @e2
agent-browser fill @e3 "text"                    # Fill and clear
agent-browser type @e3 "text"                    # Type without clearing
agent-browser press Enter                        # Press key
agent-browser hover @e4                          # Hover

状態の確認

agent-browser get text @e1                       # Get element text
agent-browser get url                            # Current URL
agent-browser is visible @e2                     # Check visibility

セッション管理

agent-browser --session login open site.com      # Isolated session
agent-browser --profile ~/.myprofile open site   # Persistent cookies
agent-browser close                              # Clean up

セレクター戦略（信頼性の高い順）

1. 参照（最適 — こちらを使用）

# From snapshot output — deterministic and stable
agent-browser click @e2
agent-browser fill @e3 "text"

2. 意味的ロケーター（良好）

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "[email protected]"

3. CSS セレクター（静的なサイトなら問題ありません）

agent-browser click "#submit"
agent-browser click ".btn-primary"

4. テキスト／XPath（最後の手段）

agent-browser click "text=Submit"
agent-browser click "xpath=//button[1]"

スナップショットのオプション

AI に「見せる」内容を制御します。

フラグ	用途
-i	操作可能な要素のみ（ボタン、リンク、入力欄）— 推奨
-C	カーソルで操作可能な要素を含める（onclick、cursor:pointer）
-c	コンパクト表示（空の構造要素を除去）
-d <n>	ツリーの深さを制限
-s <sel>	CSS セレクターの範囲に限定（例：#main）
--json	機械可読な JSON 出力 — AI に必須

推奨する AI コマンド：

agent-browser snapshot -i -c --json

オプション

フラグ	説明
--json	成功／データ／エラーの構造を持つ JSON 出力
--headed	ブラウザーウィンドウを表示（デバッグ用）
--session <name>	分離されたブラウザーセッション
--profile <path>	Cookie／ログイン情報用の永続プロファイル
--cdp <port>	DevTools Protocol 経由で既存の Chrome に接続
--headers <json>	オリジンごとに認証ヘッダーを設定

例：ログインの全手順

# Start
agent-browser open https://portal.aeronetpr.com

# Get page structure
SNAPSHOT=$(agent-browser snapshot -i --json)
# AI parses JSON: sees textbox @e1 (Username), textbox @e2 (Password), button @e3 (Login)

# Execute login
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3

# Verify success (wait for navigation, re-snapshot)
sleep 2
agent-browser snapshot -i --json

# Done
agent-browser close

AI エージェント向けのヒント

1. 常に --json を使用する — 構造化された出力はテキストより解析しやすくなります
2. -i フラグを使用する — 操作可能な要素のみのスナップショットは、小さく、高速で、明快です
3. 操作後にスナップショットを再取得する — 状態が期待どおりに変わったことを確認します
4. セレクターより参照を信頼する — スナップショットの @e2 は、変更される可能性がある #id より確実です
5. 参照の有効期限が切れたら意味的ロケーターを使用する — find role button click は堅牢です
6. セッションを継続して使用する — open を 1 回実行し、複数のコマンドを実行してから、close を 1 回実行します

その他のツールとの比較

ツール	最適な用途	agent-browser が優れている理由
Puppeteer/Playwright	開発者向けテスト	人間向けに作られており、セレクターが不安定です
Selenium	レガシーなテスト	遅く、重く、セレクターに依存しています
browser-use	Python エージェント	agent-browser のほうが優れた refs システムを備えています
スクリーンショット + ビジョン	視覚的なタスク	agent-browser は10倍高速で、コストは100分の1です
OpenClaw browser tool	シンプルなタスク	agent-browser のほうが複雑なフローを適切に処理できます

このスキルを使用する場面

次の場合は agent-browser を使用してください：

• 複数のステップからなるウェブワークフローを自動化する
• 複雑なフォームに入力する
• 信頼性が高く、繰り返し実行できる自動化が必要である
• 動的なモダンウェブアプリを扱う
• コストが重要である（ビジョン API を呼び出さない）

次の場合は OpenClaw 内蔵の browser tool を使用してください：

• シンプルな単一ページの確認
• すぐにスクリーンショットが必要
• Chrome に認証済みセッションがすでにある

リソース

• Vercel Labs のリポジトリ： https://github.com/vercel-labs/agent-browser
• このスキルのリポジトリ： https://github.com/clawdbrunner/skill-agent-browser