Snapshot
Agent がウェブページを構造化スナップショットとして読む仕組みと、@N 参照の挙動。
Snapshot は、エージェントがウェブページを読むための仕組みです。現在のページを簡潔な構造化テキストにまとめ、ボタン、入力欄、リンクといった操作可能な要素に @1、@2 のような一時的な番号を割り当てます。エージェントは、生の HTML を読んだり画面座標を推測したりするのではなく、このスナップショットを見て次に何をするかを決めます。
何を解決するか
人にとってウェブページは見るための画面ですが、エージェントにとっては数万トークン分の HTML、スクリプト、スタイル、そして動的状態の塊です。それをそのまま LLM に渡すと、よくある 2 つのコストが発生します:
- トークンコストが高い。一般的な管理画面はそれだけで 30k トークン規模になり、しかも操作のたびに読み直す必要があります。
- ノイズが多い。DOM 全体のうちの大半（スタイル、スクリプト、隠しノード）は判断に関係せず、かえって邪魔になります。
Snapshot はブラウザの accessibility tree（無障害ツリー。ブラウザがスクリーンリーダーのために維持しているセマンティックなビュー）を元に、ページを数百トークン程度に圧縮します:
- ページタイトルと現在の URL。
- 見えているテキストと主な構造。
- クリック、入力、選択ができる要素と、その役割と名前。
- 各インタラクティブ要素に対応する一時的な
@N。
これだけあれば、エージェントはどのボタンを押すか、どの入力欄に入れるかを判断できます。生の HTML も画面座標も不要です。
@N 参照の使い方
スナップショット内の各インタラクティブ要素には一時的な番号が振られます:
@1 [input] "検索"
@2 [button] "送信"
@3 [link] "次のページ"
エージェントはこの番号で操作します。例えば await click('@2') のように。
@N は今回のスナップショット限定で有効です。ページが変化したあと（遷移、リロード、ダイアログ、フォーム送信、タブ切り替え、動的な再レンダリング）、古い番号は別の場所を指しているかもしれません。安全な習慣は、ページが変わったら @N を抱え込まず、もう一度スナップショットを取り直すことです。
ある要素を複数のステップにまたがって安定的に指したい場合は、スナップショット出力に含まれる loc=... を安定セレクタとして使うか、CSS セレクタを直接書きます。詳しくは ego-browser を参照してください。
あなたが Snapshot に気づく場面
普段はスナップショットを意識する必要はありません。エージェントが裏で読みます。次のような場面で表に出てきます:
- エージェントが「スナップショットを取り直す」「ページスナップショット」と言うとき。ページの変化を検知して、現在の状態を読み直しているサインです。
- タスクの結果に、根拠としてスナップショットの抜粋が添えられているとき。
エージェントへのタスク指示の書き方
スナップショットがあればエージェントはページをはっきり見られますが、タスクの境界はあなたが定義する仕事です。良い指示には次の要素が入ります:
- 対象のページまたはサイト。
- 何を読み、入力し、クリックし、ダウンロードするか。
- やってはいけないこと（削除、公開、決済、メール送信など）。
- CAPTCHA、決済、認可の場面で止まるかどうか。
- 期待する返却形式（表、要約、スクリーンショット、ローカルファイルパス）。
例:
GitHub Notifications を開き、レビューが必要な PR をリポジトリ名・タイトル・リンクで一覧化してください。
アーカイブも既読化もしないこと。
管理画面の注文一覧を開き、昨日分を絞り込んで CSV をダウンロードしてください。
ログイン確認やエクスポート確認が出たら止まって私に渡し、ファイルの保存場所も教えてください。
エージェントの結果を確認する
タスクが終わったら、次の手がかりで判断します:
- 訪れたページと主な操作を明示しているか。
- 返却結果に、確認できる情報（タイトル、ID、リンク、金額、時刻）が含まれているか。
- ダウンロード系のタスクなら、ローカルファイルパスが提示されているか。
- 変更や送信を伴うタスクなら、最終確認の手前で止まっているか。
- 関連ページが Space に残っていて、後から見直せるか。
結果が変だと感じたら、前の回答を頼りに推測を続けさせず、現在のページのスナップショットを取り直させましょう。
よくある質問
なぜ「ref が無効」と言われるのか
前回のスナップショット以降にページが変わっています。新しいスナップショットを取らせてください。
スナップショットはすべての内容を読めますか
そうとも限りません。画面外のコンテンツ、画像内の文字、複雑な canvas、制約のある cross-origin iframe などは、スナップショットに完全には現れないことがあります。そういう場面では、スクリーンショット、テキスト抽出、人の確認を組み合わせる必要があるかもしれません。
スナップショットでデータが変わることはありますか
ありません。スナップショットはページ構造を読むだけです。実際に状態を変えるのは、その後のクリック、入力、送信、アップロード、削除といった操作です。
@1、@2 を覚えておく必要はありますか
ありません。「今のページにある一時的な要素番号」と思っておけば十分です。番号を使うのはエージェント、目的と境界を伝えるのがあなたの仕事です。