著者注：インストールから snapshot、ref を使った操作、結果の検証まで、5 ステップで agent-browser の「ページを読み、要素をクリックし、再びページを読む」サイクルを習得します。AI Agent で実際のブラウザを安定して操作するための入門ガイドです。
AI Agent に Web ページを操作させる際、よくある課題は、Agent がページを見られず、目的の要素を安定してクリックするのも難しいことです。スクリーンショットと座標クリックを組み合わせる方法は大量のトークンを消費し、クリック位置がずれることもあります。一方、HTML 全体をモデルに渡すと、コンテキストがすぐにいっぱいになってしまいます。この記事では、agent-browser の snapshot-ref 操作サイクルを紹介し、Agent が「一度に 1 コマンドずつ」ブラウザを操作する方法を解説します。
この記事は、ブラウザ自動化フレームワークの概念を紹介するだけの記事ではありません。実際に操作する順序に沿って、agent-browser のインストール、snapshot と ref の組み合わせ方、失敗時のリトライ戦略、Agent ワークフローへの組み込み方を解説します。
この記事で得られること：agent-browser の snapshot-ref サイクルが大規模言語モデルに適している理由を理解し、自分の Agent で 5 つのコマンドを使って最初のブラウザ操作タスクを実行できるようになります。
agent-browser の snapshot-ref ループの要点
agent-browser は、Vercel Labs が Apache-2.0 ライセンスで公開しているブラウザ自動化ツールです。Rust 製のネイティブ CLI で、AI Agent がコマンドを一つずつ実行してブラウザを操作できるように設計されています。Agent がページを開くと、その内容をアクセシビリティツリー（accessibility tree）形式のコンパクトなテキストとして読み取り、shell コマンドで要素を操作します。
| 要点 | 説明 | Agent にとってのメリット |
|---|---|---|
| コンパクトな snapshot テキスト | ページがアクセシビリティツリー形式で出力され、各要素に @e1 のような ref が付く |
スクリーンショットや生の HTML よりコンテキストを節約できる |
| ref による正確な指定 | click @e1 のように、操作コマンドから ref を直接参照する |
モデルが自分で CSS セレクターを組み立てる必要がない |
| ブラウザの常駐 | バックグラウンドのデーモンがブラウザを開いたままにする | 各ステップは短い shell 呼び出しだけで済む |
| 失敗時の明示的なエラー | 要素が覆われている、非表示、無効といった場合、クリックは成功したように見せかけず失敗する | Agent が実際の結果に基づいて次の行動を決められる |
| skills を内蔵 | CLI にバージョンに対応した使い方の説明が組み込まれている | Agent が読む指示とインストール済みバージョンが一致する |
snapshot-ref ループの仕組み
このループは、まず snapshot でページを読み、次に ref を指定して操作し、再びページを読み取って結果を確認する、という流れを繰り返します。公式が示す example.com のスナップショットは、わずか一行です：- link "Learn more" [ref=e1]。モデルはこの一行から、ページに Learn more というリンクがあり、@e1 でクリックできることを把握します。
この設計は、「ページの理解」と「操作の実行」を検証可能な二つのステップに分けており、大規模言語モデルのツール呼び出し方式によく合っています。モデルは複雑な DOM 構造を理解する必要がなく、テキストから目的に合った要素を見つけ、対応する ref を指定するだけで済みます。操作のたびに再びスナップショットを取得することで、Agent は記憶を頼りに推測するのではなく、常に最新のページ状態に基づいて判断できます。
agent-browser の基盤アーキテクチャ
CLI 自体がブラウザを直接保持するわけではありません。最初のコマンド実行時にバックグラウンドのデーモン（daemon）が起動し、Chrome DevTools Protocol を通じてブラウザを制御します。以降の CLI コマンドはすべてこのデーモンに送られます。そのため、コマンドの実行間もブラウザは開いたままで、ログイン状態やページ内の位置が失われません。
各 --session は独立したデーモンとブラウザを持つため、複数のタスクを互いに干渉させず並行実行できます。デフォルトでは、ヘッドレスブラウザはコマンドを受け取らない状態が連続して1時間続くと閉じられ、デーモンも終了します。セッション永続化（session persistence）が設定されている場合は、終了前に状態が保存されます。
このループを動かす「頭脳」は大規模言語モデルです。各回のスナップショットテキストがモデルのコンテキストに入り、モデルが次のコマンドを決めるため、指示に従う能力と単価がタスクの成功率やコストに直接影響します。APIYI は、この記事で扱う Claude、DeepSeek、Kimi などのモデルへの API 呼び出しを提供し、OpenAI と Anthropic の両方のインターフェース形式に対応しています。接続方法のドキュメントは docs.apiyi.com をご覧ください。
agent-browser クイックスタート：5ステップで snapshot-ref サイクルを試す
ステップ1：agent-browser とブラウザをインストールする
最も一般的な方法は、npm でグローバルインストールしてから Chrome for Testing をダウンロードする方法です。npm パッケージはホストのプラットフォームに応じてネイティブバイナリを自動選択します。現在は macOS（ARM64、x64）、Linux（ARM64、x64、glibc と musl）、Windows（x64）に対応しています。
| インストール方法 | コマンド | 適した用途 |
|---|---|---|
| npm でグローバルインストール | まず npm install -g agent-browser、次に agent-browser install |
一般的な開発環境。初回はブラウザのダウンロードが必要 |
| Homebrew | まず brew install agent-browser、次に agent-browser install |
macOS ユーザー |
| Linux で依存関係もインストール | agent-browser install --with-deps |
ブラウザ用のシステムライブラリも必要なサーバーやコンテナ |
| インストール不要 | npx agent-browser open example.com |
一時的な試用や CI での単発タスク |
| メンテナンスコマンド | agent-browser upgrade、agent-browser doctor |
バージョンの更新や環境トラブルの調査 |
ソースからビルドする場合、公式の要件は Node.js 24 以上、pnpm 11 以上、Rust ツールチェーンです。pnpm install、pnpm build:source、pnpm link --global を順に実行し、最後に agent-browser install を実行します。普段使うだけなら、npm でのインストールで十分です。
ステップ 2〜5：最小限の一連の操作
インストールが完了したら、以下のコマンドで snapshot-ref の一連の操作を実行できます。まずはターミナルで手動実行し、各ステップの出力を確認してから、Agent に自動実行を任せるのがおすすめです。
| ステップ | コマンド | 役割 | 期待される結果 |
|---|---|---|---|
| 2. ページを開く | agent-browser open example.com |
デーモンを起動して URL を開く | ブラウザがバックグラウンドで動作する |
| 3. スナップショットを読み取る | agent-browser snapshot -i |
操作可能な要素のみを、それぞれ ref 付きで一覧表示する | link "Learn more" [ref=e1] のように出力される |
| 4. ref を操作する | agent-browser click @e1 |
スナップショット内の要素をクリックする | ページが遷移するか、状態が変化する |
| 5. 結果を確認する | agent-browser get url |
現在の URL を読み取り、操作が反映されたことを確認する | 遷移後のアドレスが返る |
| 終了処理 | agent-browser close |
ブラウザを閉じる | リソースが解放される |
ステップ 3 の -i パラメータは重要です。操作可能な要素だけを出力するため、スナップショットのテキストを大幅に短縮でき、特にトークン予算が限られている場合に役立ちます。ステップ 5 の確認も省略できません。Agent は「クリックすれば成功」と決めつけず、実際のフィードバックをもとに操作が成功したかどうかを判断する必要があります。
🚀 クイックスタート：手動で一連の操作を確認できたら、Agent にこれらのコマンドを任せてみましょう。まず APIYI apiyi.com でテスト用クレジットを取得し、同じタスクを複数のモデルで試して、どのモデルがスナップショットのテキストから正しい ref を選ぶのに優れているか比べてみるのがおすすめです。インターフェースは OpenAI および Anthropic 形式と互換性があるため、既存の Agent フレームワークでは基本的にキーとアドレスを差し替えるだけで利用できます。詳細は docs.apiyi.com のドキュメントを参照してください。
agent-browser の ref の有効期間とスナップショットの再取得
ref は「スナップショット取得時点」のページを表します。ページ遷移や DOM の変更があると、古い ref は無効になったり、誤った要素を指したりする可能性があります。そのため、ページ遷移やページの明らかな変化があった後は、必ず snapshot を再実行してから新しい ref を使いましょう。
このルールは、Agent のシステムプロンプトに直接書いておくのがおすすめです。信頼できるサイクルは「スナップショット、操作、スナップショット」であり、「一度スナップショットを取得して、続けて10回操作する」ことではありません。スナップショットを追加で取得するコストは、要素をクリックし間違えた後の調査やロールバックにかかるコストよりもずっと小さくなります。
agent-browser でクリックに失敗したときの対処法
agent-browser はクリックを「成功したふり」で済ませません。対象の要素が非表示、無効、ビューポート外にある場合や、別の要素（Cookie 同意ポップアップなど）に覆われている場合、click は失敗を返します。エラー情報そのものが次の判断材料になるため、Agent にとって扱いやすい仕組みです。
| 失敗の原因 | 典型的な状況 | 推奨される対処法 |
|---|---|---|
| 覆われている | 同意ポップアップやフローティング要素がボタンを覆っている | 先に覆っている要素を閉じ、スナップショットを再取得してから再試行する |
| ビューポート外 | 要素がページの下方にある | scroll でスクロールし、スナップショットを再取得する |
| 要素が無効 | フォームの未入力によりボタンを押せない | 先に fill で必須項目を入力し、スナップショットで確認する |
| 要素が非表示 | メニューを展開しないと表示されない | 先に展開ボタンをクリックし、wait で待機してからスナップショットを取得する |
| ref の期限切れ | ページが遷移または更新された | snapshot を再実行して新しい ref を取得する |
ref のほかに、agent-browser は CSS セレクター、テキスト、XPath、セマンティックロケーターにも対応しています。例えば、agent-browser find role button click --name "Submit" を使うと、役割と名前から送信ボタンを見つけてクリックできます。ページ構造が安定していて要素の意味が明確な場合は、セマンティックロケーターを ref の補助として活用できます。
agent-browser のよく使うコマンド
agent-browser には幅広いコマンドが用意されています。全コマンドは agent-browser --help で、各コマンドの詳細は agent-browser <command> --help で確認できます。ここでは、Agent にどの機能を開放するか判断しやすいよう、よく使うコマンドを用途別にまとめました。
| 分類 | 主なコマンド | 典型的な用途 |
|---|---|---|
| ナビゲーションと読み取り | open、back、reload、read、snapshot、get、is |
ページを開く、スナップショットを読む、状態を確認する |
| 操作 | click、fill、type、press、select、check、scroll、upload、find |
クリック、フォームへの入力、ファイルのアップロード |
| 待機 | wait |
要素の表示やページの読み込みを待つ |
| データの取得 | screenshot、pdf、record、download、diff |
スクリーンショットの撮影、PDF の出力、画面録画、ページの比較 |
| ページとネットワークの状態 | cookies、storage、network、eval |
Cookie の管理、ネットワーク通信のインターセプト、スクリプトの実行 |
| タブとポップアップ | tab、frame、dialog |
複数タブ、iframe、ダイアログの操作 |
| デバッグとパフォーマンス | console、errors、trace、vitals、a11y |
コンソールエラーやパフォーマンス指標の取得 |
| セッションと認証 | session、state、auth、confirm、deny |
セッションの分離、ログイン状態の管理、慎重な操作の確認 |
| Agent との連携 | skills、mcp、flow、batch、plugin |
スキルの読み込み、MCP サービスの起動 |
ブラウザエンジンには、デフォルトで Chrome for Testing が使われます。--cdp または --auto-connect を使って起動中の Chrome に接続したり、--engine で Lightpanda や Obscura に切り替えたりすることもできます。また、iOS シミュレータで Mobile Safari を操作したり、Browserbase、Browserless、Browser Use、Kernel、AgentCore などのクラウドブラウザサービスに接続したりすることも可能です。
agent-browser を AI Agent に組み込む
組み込みスキルで Agent に使い方を教える
agent-browser の巧みな設計の一つは、使用方法が CLI と一緒に提供されていることです。agent-browser skills get core を実行すると、基本的なループ、ref の使い方、待機戦略、よく使うワークフローが出力されます。--ref commands を付けると、コマンドの完全な一覧など、特定のリファレンスだけを確認できます。--full を付けると、コマンドの完全なリファレンスとテンプレートも表示されます。agent-browser skills list では、electron、slack、dogfood などの専用スキルも一覧できます。
Agent フレームワークでは、npx skills add vercel-labs/agent-browser でスキルをインストールできます。このスキルはシンプルな導入ガイドで、Agent に agent-browser skills get core を読み込ませる仕組みです。そのため、指示は常にインストール済みの CLI バージョンと一致します。スキルをインストールしたくない場合は、AGENTS.md に次の一文を書いておく方法もあります。「ブラウザーの自動化には agent-browser を使い、初回使用前に agent-browser skills get core を実行して、その指示に従ってください。」
MCP 経由で接続する
クライアントが MCP に対応している場合、agent-browser mcp を実行すると、stdio 経由で MCP サーバーが起動します。これにより、Claude のようなデスクトップクライアントや自社開発の Agent は、シェル実行層を自分で用意しなくても、ブラウザー操作を標準のツール呼び出しとして利用できます。
snapshot-ref ループを駆動するモデルを選ぶ
ブラウザータスクはやり取りの回数が多く、各回にスナップショットのテキストが含まれるため、通常は出力よりも入力トークンの割合がはるかに高くなります。そのため、モデルを選ぶ際は、指示に従う能力に加えて、入力単価とキャッシュ価格も重視しましょう。下表の価格はすべて APIYI の料金ページ docs.apiyi.com/models の実データに基づいています。単位と課金方法については、料金ページの記載を確認してください。
| モデル | 入力価格 | 出力価格 | キャッシュ価格 | 適した用途 | 利用可能なプラットフォーム |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | 複雑な複数ステップのタスク、対応が難しいページ | APIYI apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | 日常的に使う主力モデル | APIYI apiyi.com |
| kimi-k3.1-pro | $2 | $10 | $0.2 | 中国語のウェブページ | APIYI apiyi.com |
| deepseek-v4.1-flash | $0.3 | $1.2 | $0.006 | シンプルなフォーム、大量の定期チェック | APIYI apiyi.com |
実用的な組み合わせとしては、構造がシンプルで手順が決まっている大量のタスクを deepseek-v4.1-flash で処理し、claude-sonnet-5-5 を汎用の主力モデルとして使います。複雑な操作が必要なページや失敗が頻発するページでは、claude-opus-5-5 に切り替えるとよいでしょう。スキルのテキストやシステムプロンプトは毎回繰り返し入力されるため、長いループではキャッシュ価格の低いモデルのほうがコスト面で有利です。
なお、文心 ERNIE シリーズは APIYI の料金表では現在確認できず、APIYI ではまだ提供されていません。できるだけ早く提供を開始する予定です。Agent が ERNIE に依存している場合は、まず上表のモデルで代替テストを行えます。
💡 選び方のヒント：すべてのウェブサイトで最適なモデルはありません。実際の業務で使うページを3〜5個選んで小規模なテストを行い、APIYI apiyi.com の統一インターフェースでモデルを切り替えながら、成功率とタスクあたりのコストを比較してから主力モデルを決めることをおすすめします。
agent-browser を安全に使うための推奨事項
Agent に実際のブラウザを操作させる場合は、事前にセキュリティ境界を設計しておく必要があります。agent-browser の公式ドキュメントのセキュリティセクションでは、認証情報を保管する auth vault、ドメインの許可リスト、操作ポリシー、コンテンツ境界といった仕組みが紹介されています。コマンドでは、auth でログイン認証情報を管理し、confirm と deny で機密性の高い操作を承認または拒否できます。
本番環境では、少なくとも次の3点を実施することをおすすめします。
- アクセス可能なドメインを制限する：ドメインの許可リストを使って、Agent のアクセス先を業務に関連するサイトに限定します。ページに誘導されて、見知らぬサイトへ移動するのを防ぎます。
- 認証情報をコンテキストに含めない：アカウント名やパスワードはプロンプトに書かず、auth vault に保管します。これにより、認証情報がモデルのログに残るのを防ぎます。
- 重要な操作は人間が確認する：支払い、削除、注文の確定といった操作には確認を必須に設定し、最終的な判断を人間が行えるようにします。
Webページ自体に、Agent を狙った悪意ある指示が含まれている可能性もあるため、コンテンツ境界の仕組みも有効にしておくとよいでしょう。これは、モデルが「ページ内のテキスト」と「ユーザーからの指示」を明確に区別できるようにし、プロンプトインジェクションのリスクを軽減する仕組みです。
よくある質問 FAQ
Q1：agent-browser の snapshot-ref ループとは何ですか？
agent-browser の基本的な動作方法です。まず `snapshot` でページを ref 付きのコンパクトなテキストとして読み取り、ref を指定して操作します。その後、再びスナップショットを取得して結果を確認し、この手順を繰り返します。ページの理解と操作の実行を検証可能な小さなステップに分けるため、大規模言語モデルによる段階的な推論に適しています。
Q2：agent-browser とスクリーンショット駆動型のブラウザ Agent はどう違いますか？
スクリーンショットを使う方法は視覚的な理解の汎用性が高い一方、トークン消費が大きく、座標を指定したクリックもずれやすいという課題があります。対して agent-browser は、アクセシビリティツリーのテキストと ref を使って要素を特定します。コンテキストがコンパクトで操作も正確なうえ、失敗時には明確なエラーが返されるため、安定した実行が求められる自動化タスクに適しています。
Q3：ページ遷移後に古い ref を使い続けられないのはなぜですか？
ref はスナップショットを取得した時点のページを表すものです。ページ遷移や DOM の変更後は、要素が消えたり置き換わったりしている可能性があり、古い ref は無効になるか、誤った要素を指す場合があります。ページが変化するたびに `snapshot` を再実行し、新しい ref を使いましょう。
Q4：agent-browser はどのような用途に適していますか？
主に次のような用途に適しています。
– **フォームの自動入力**：登録、申し込み、管理画面への入力など、手順が決まった作業。
– **サイトの巡回チェックと回帰テスト**：`errors`、`console`、`vitals` を組み合わせてページのエラーやパフォーマンスを確認。
– **情報収集**：管理画面にログインした後、メニューに沿ってページごとにデータを読み取り。
– **Electron や Slack などに特化した用途**：`skills list` にある専用スキルで機能を拡張。
Q5：agent-browser を動かすモデルにはどう接続すればよいですか？
次の手順で接続できます。
1. APIYI の apiyi.com にアクセスしてアカウントを登録し、APIキーを取得します。
2. Agent フレームワークで OpenAI または Anthropic 互換の形式を選び、docs.apiyi.com のドキュメントに従って接続パラメータを設定します。
3. 本記事の5ステップのループをテストタスクとして使い、モデルごとの性能を比較します。
APIYI では Claude、DeepSeek、Kimi など、さまざまなモデルに統一的な方法で接続できます。モデルを切り替える際は、モデル名を変更するだけです。
Q6：snapshot-ref ループを実行する際のモデル利用コストはどう見積もればよいですか？
ブラウザタスクでは入力トークンが中心となり、各ラウンドでスナップショットのテキストとシステムプロンプトを送る必要があります。見積もる際は入力単価とキャッシュの料金を確認し、`snapshot -i` を使ってスナップショットをできるだけ短くしましょう。各モデルの実際の単価は、古い第三者の料金情報ではなく、APIYI の料金ページ docs.apiyi.com/models で確認してください。
Q7：agent-browser にはどのような既知の制限がありますか？
ref には有効な期間が限られているため、Agent は頻繁にスナップショットを再取得する必要があり、その分ラウンド数が増えます。アクセシビリティ情報が大幅に不足しているページでは、スナップショットが不完全になることもあります。その場合は CSS セレクター、XPath、またはスクリーンショットを補助的に使う必要があります。また、ヘッドレスブラウザは1時間操作がないと自動的に閉じるため、長時間のタスクではセッションの永続化を設定する必要があります。
agent-browser snapshot-ref の要点 Key Takeaways
- 基本：agent-browser は Vercel Labs がオープンソースで公開している Rust 製 CLI です。Agent がコマンドを一つずつ実行してブラウザを操作できます。
- 基本のループ：スナップショットでページを読み取り、ref を使って操作し、再びスナップショットで検証する、という3ステップを繰り返します。
- ref の鉄則：ページ遷移や DOM の変更後は、ref を使う前に必ずスナップショットを取り直します。
- 失敗は対処のサイン：要素が隠れている場合や無効になっている場合、クリックはエラーになります。Agent はまず原因に対処してから再試行します。
- 接続方法：
skills get coreでバージョンに対応した指示を読み込むか、agent-browser mcpで MCP クライアントに接続します。 - セキュリティ優先：本番環境ではドメインの許可リスト、auth vault、重要な操作の確認を有効にします。
- モデルの選択：APIYI apiyi.com の統一インターフェースで動作モデルを比較できます。料金は docs.apiyi.com/models を確認してください。
まとめ
agent-browser の snapshot-ref ループの要点は次のとおりです。
- スクリーンショットの代わりにテキストを使う：アクセシビリティツリーのスナップショットと ref により、モデルは最小限のコンテキストでページを理解できます。
- 操作するたびに検証する：各操作後にページや URL を確認し、Agent が誤った状態のまま処理を続けるのを防ぎます。
- 失敗に対処できる：要素の重なり、ビューポート、無効化、ref の期限切れには、それぞれ明確な対処方法があります。
- 導入コストが低い：npm によるインストール、組み込みの skills、MCP サービスのいずれも、既存の Agent に素早く組み込めます。
まずはターミナルで open、snapshot、click、get、close の5つのコマンドを手動で試し、次にループのルールを Agent のシステムプロンプトに組み込みましょう。最後に、実際の業務ページで動作モデルを選ぶことをおすすめします。
APIYI apiyi.com を使えば、異なるモデルで agent-browser を動かしたときの効果を素早く検証できます。プラットフォームは OpenAI と Anthropic のインターフェース形式に対応しています。接続方法は docs.apiyi.com、モデルの料金は docs.apiyi.com/models を確認してください。
📚 参考資料
- GitHub – agent-browser：公式オープンソースリポジトリ
- リンク：
github.com/vercel-labs/agent-browser -
内容：インストール方法、クイックスタート、コマンドの分類、開発に関する説明
-
agent-browser 公式ドキュメント：完全ガイドとコマンドリファレンス
- リンク：
agent-browser.dev -
内容：スナップショット、セレクター、セッション、CDP モード、セキュリティ機能を網羅
-
agent-browser セキュリティドキュメント：認証とアクセス制御
- リンク：
agent-browser.dev/security -
内容：auth vault、ドメインの許可リスト、操作ポリシー、コンテンツの境界について解説
-
APIYI ドキュメントセンター：モデルの接続方法
- リンク：
docs.apiyi.com -
内容：OpenAI および Anthropic 互換形式での接続方法
-
APIYI モデル価格ページ：各モデルの実際の料金
- リンク：
docs.apiyi.com/models - 内容：本記事のモデル価格はすべてこのページに準拠
著者：APIYI 技術チーム
技術交流：お問い合わせは APIYI のウェブサイト apiyi.com のトップページからどうぞ。接続に関する詳しい資料は、ドキュメントセンター docs.apiyi.com でご覧いただけます。
