Skip to content

Webエージェントアノテーション

Potatoでwebブラウジングエージェントのトレースをレビューします。フィルムストリップによる移動、SVGオーバーレイ（クリック、バウンディングボックス、マウス軌跡）、ステップごとのアノテーション操作に対応しています。

v2.4.0の新機能

webブラウジングを行うAIエージェントを評価するには、エージェントが何を見て、どこをクリックし、各ステップが妥当だったかを確認する必要があります。Potatoには専用のWebエージェントトレースビューアがあり、録画済みトレースをレビューするモードと、実際のwebサイトを閲覧して新しいトレースを作成するモードの2つを備えています。

概要

モード使う場面
レビューモードWebArena、Mind2Web、Anthropic Computer Use、あるいはPotato自身のレコーダーで録画済みのトレースがある場合
作成モードアノテーターにwebサイトを閲覧してもらい、新しい操作トレースを記録したい場合

レビューモード

アノテーターは、エージェントのブラウジングセッションのスクリーンショットを1ステップずつ辿ります。各スクリーンショットの上には、クリックマーカー、バウンディングボックス、マウス軌跡、スクロール表示がSVGオーバーレイとして描画されます。

設定

yaml
instance_display:
  fields:
    - key: steps
      type: web_agent_trace
      label: "Agent Browsing Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_observation: true
        show_element_info: true
        screenshot_max_width: 800
        screenshot_max_height: 600
        filmstrip_size: 80

データ形式

各インスタンスには、ステップごとのデータが入ったsteps配列が必要です。

json
{
  "id": "trace_001",
  "task_description": "Find and add a blue wool sweater to cart",
  "site": "amazon.com",
  "steps": [
    {
      "step_index": 0,
      "screenshot_url": "screenshots/step_000.png",
      "action_type": "click",
      "element": {
        "tag": "input",
        "text": "Search",
        "bbox": [340, 45, 680, 75]
      },
      "coordinates": {"x": 510, "y": 60},
      "mouse_path": [[200, 300], [350, 200], [510, 60]],
      "thought": "I need to search for blue wool sweaters",
      "observation": "Search box is focused",
      "timestamp": 1.2,
      "viewport": {"width": 1280, "height": 720}
    }
  ]
}

対応しているアクション種別

アクションオーバーレイ
click十字線付きの赤い円とパルスアニメーション
type対象要素の黄色いハイライト
scroll緑色の方向矢印
hover紫色の円
select青いバウンディングボックス
navigateオーバーレイなし
waitオーバーレイなし
doneオーバーレイなし

キーボードショートカット

キー動作
← / →前 / 次のステップ
1クリックマーカーのオーバーレイ切り替え
2バウンディングボックスのオーバーレイ切り替え
3マウス軌跡のオーバーレイ切り替え
4スクロール表示の切り替え
Aすべてのオーバーレイを表示
Nすべてのオーバーレイを非表示

ステップごとのアノテーション

任意のアノテーションスキーマにper_step: trueを追加すると、各ステップの中にインラインで表示されるアノテーション操作が作られます。

yaml
annotation_schemes:
  - annotation_type: radio
    name: step_correctness
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: step_notes
    per_step: true
    label: "Notes on this step"

ステップごとのアノテーションは{scheme_name}_step_{index}という形で保存されます（例：step_correctness_step_0）。

作成モード

アノテーターはPotatoのインターフェース内で実際のwebサイトを閲覧し、その操作がアノテーション可能なトレースとして自動的に記録されます。

設定

yaml
instance_display:
  fields:
    - key: browsing_session
      type: web_agent_recorder
      display_options:
        start_url: "https://www.google.com"
        proxy_mode: auto
        record_mouse_path: true
        record_viewport: true
        screenshot_method: server
        max_steps: 50

プロキシモード

モード説明
auto（デフォルト）対象サイトがiframe埋め込みを許可しているかを判定し、最適なモードを自動的に選びます
iframeiframeプロキシを強制します。約90%のサイトで動作し、オーバーヘッドは100ミリ秒未満です
playwrightサーバー側のPlaywrightを強制します。すべてのサイトで動作しますが、playwrightパッケージが必要です

Playwrightモードを有効にするには次を実行します。

bash
pip install playwright
playwright install chromium

既存トレースの変換

他のフレームワークのトレースをPotatoの形式に正規化するには、トレースコンバーターのCLIを使います。

bash
# Convert from a specific format
python -m potato.trace_converter -i traces.json -f web_agent -o output.jsonl
 
# Auto-detect format
python -m potato.trace_converter -i traces.json --auto-detect -o output.jsonl

対応している入力形式：WebArena、VisualWebArena、Mind2Web、Anthropic Computer Use、そしてPotatoの録画データそのもの。

完全な例

yaml
task_name: "Web Agent Evaluation"
task_dir: "."
 
data_files:
  - "traces.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: steps
      type: web_agent_trace
      label: "Agent Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task successfully?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: radio
    name: step_correctness
    question: "Was this step correct?"
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: error_description
    question: "Describe any errors in the agent's behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

サンプルプロジェクトの実行

bash
# Review Mode
python potato/flask_server.py start examples/agent-traces/web-agent-review/config.yaml -p 8000
 
# Creation Mode
python potato/flask_server.py start examples/agent-traces/web-agent-creation/config.yaml -p 8000

APIリファレンス

作成モードを使う場合、次のRESTエンドポイントが利用できます。

エンドポイントメソッド説明
/api/web_agent/start_sessionPOST録画セッションを開始します
/api/web_agent/save_stepPOST記録した操作ステップを保存します
/api/web_agent/save_screenshotPOSTステップのスクリーンショットをアップロードします
/api/web_agent/end_sessionPOSTセッションを終了し、トレースを保存します
/api/web_agent/proxy/{url}GET外部URLをサーバー経由でプロキシします
/api/web_agent/check_frameableGETURLがiframe埋め込みを許可しているかを調べます

参考資料

実装の詳細については、ソースドキュメントを参照してください。