Webブラウジングエージェントのアノテーション：WebArenaトレースから人間評価まで

Webブラウジングエージェントは、テキストベースのエージェントとは根本的に異なるモダリティで動作します。実際のWebページをナビゲートし、ボタンをクリックし、フォームに入力し、コンテンツをスクロールします。これらを評価するには、エージェントが見たもの（ページの状態）とエージェントが行ったこと（実行されたアクション）を確認する必要があり、理想的にはエージェントがクリックした正確な場所を示すビジュアルオーバーレイが必要です。

PotatoのWeb Agent Trace Displayはこのタスク用に特別に構築されています。フルページスクリーンショットにSVGアクションオーバーレイを描画し、クイックナビゲーション用のフィルムストリップビューを提供し、アクション正確性のステップごとのアノテーションをサポートします。

このガイドではWebArenaトレースの評価を説明しますが、VisualWebArena、生のブラウザ記録、その他のWebエージェント形式にも同じアプローチが適用できます。

前提条件

bash

pip install potato-annotation

WebArenaトレースファイルが必要です。通常、スクリーンショットとJSONアクションログが含まれます。VisualWebArenaを使用している場合、形式は類似していますが、追加のビジュアルグラウンディング情報が含まれる場合があります。

ステップ1：WebArenaトレース形式の理解

WebArenaトレースは、タスク説明、アクションシーケンス、スクリーンショットパスを含むエピソードごとのJSONファイルで構成されます。以下は簡略化された例です。

data/web_traces.jsonlを作成してください：

json

{
  "trace_id": "wa_001",
  "task": "Find the cheapest laptop on the electronics store and add it to the cart",
  "website": "shopping",
  "steps": [
    {
      "step": 0,
      "url": "http://shop.example.com/",
      "action_type": "click",
      "action_target": "Electronics category link",
      "element_id": "nav-electronics",
      "coordinates": [245, 82],
      "screenshot": "screenshots/wa_001_step_00.png",
      "dom_snapshot": "dom/wa_001_step_00.html"
    },
    {
      "step": 1,
      "url": "http://shop.example.com/electronics",
      "action_type": "click",
      "action_target": "Laptops subcategory",
      "element_id": "cat-laptops",
      "coordinates": [180, 310],
      "screenshot": "screenshots/wa_001_step_01.png"
    },
    {
      "step": 2,
      "url": "http://shop.example.com/electronics/laptops",
      "action_type": "click",
      "action_target": "Sort by: Price Low to High",
      "element_id": "sort-price-asc",
      "coordinates": [720, 155],
      "screenshot": "screenshots/wa_001_step_02.png"
    },
    {
      "step": 3,
      "url": "http://shop.example.com/electronics/laptops?sort=price_asc",
      "action_type": "click",
      "action_target": "First laptop: 'Budget Pro 14' - $349",
      "element_id": "product-101",
      "coordinates": [400, 380],
      "screenshot": "screenshots/wa_001_step_03.png"
    },
    {
      "step": 4,
      "url": "http://shop.example.com/product/101",
      "action_type": "click",
      "action_target": "Add to Cart button",
      "element_id": "add-to-cart-btn",
      "coordinates": [650, 520],
      "screenshot": "screenshots/wa_001_step_04.png"
    }
  ],
  "success": true,
  "final_screenshot": "screenshots/wa_001_final.png"
}

各ステップにはスクリーンショット、実行されたアクション、ターゲット要素、クリック座標が含まれます。Potatoはこの情報を使用してビジュアルオーバーレイを描画します。

ステップ2：プロジェクトの設定

config.yamlを作成してください：

yaml

task_name: "WebArena Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/web_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
# --- Agentic annotation with web display ---
agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlays
    overlay:
      enabled: true
      click_marker: "circle"
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"
      scroll_indicator: true
 
    # Filmstrip navigation
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # Additional display options
    show_url_bar: true
    show_action_description: true
    show_dom_snapshot: false
 
# --- Annotation Schemas ---
annotation_schemes:
  # Overall task evaluation
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task successfully?"
    labels:
      - "Success"
      - "Partial Success"
      - "Failure"
    label_requirement:
      required: true
 
  - annotation_type: radio
    name: task_efficiency
    description: "Was the agent's navigation path efficient?"
    labels:
      - "Optimal path"
      - "Reasonable but not optimal"
      - "Inefficient (unnecessary steps)"
      - "Completely wrong direction"
    label_requirement:
      required: true
 
  # Per-step evaluation
  - annotation_type: per_turn_rating
    name: action_correctness
    target: agentic_steps
    description: "Was this action correct?"
    rating_type: radio
    labels:
      - "Correct"
      - "Acceptable (not optimal but progresses toward goal)"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: action_error_type
    target: agentic_steps
    description: "What went wrong?"
    rating_type: multiselect
    labels:
      - "Wrong element clicked"
      - "Wrong page navigated to"
      - "Missed a closer/better option"
      - "Incorrect form input"
      - "Premature task completion"
      - "Unnecessary navigation"
      - "Failed to scroll to target"
      - "Interaction with wrong page section"
      - "Other"
    conditional:
      show_when:
        action_correctness: ["Incorrect", "Unnecessary"]
 
  - annotation_type: per_turn_rating
    name: action_notes
    target: agentic_steps
    description: "Notes on this step"
    rating_type: text
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
parquet_export:
  enabled: true
  output_dir: "output/parquet/"

ステップ3：Web Agent Displayの理解

トレースを開くと、Web Agent Displayには以下が表示されます：

メインスクリーンショットビュー

現在のステップのスクリーンショットがフル幅（最大900px）で表示されます。その上にSVGオーバーレイが描画されます：

赤い円がクリック座標に表示され、エージェントがクリックした正確な場所を示す
青いハイライトがエージェントが入力したテキスト入力フィールドの周りに表示
矢印インジケーターがスクロールアクションの方向と大きさを示す

スクリーンショットの下には以下が表示されます：

URLバーがこのステップでのページURLを表示
アクション説明（例：「座標[245, 82]で'Electronics category link'をクリック」）

フィルムストリップ

表示の下部に、すべてのスクリーンショットのサムネイルを表示する水平フィルムストリップがあります。各サムネイルにはアクションタイプ（click、type、scroll）を示す小さなラベルが付いています。任意のサムネイルをクリックしてそのステップにジャンプできます。

フィルムストリップは長いトレース（10ステップ以上）で特に有用で、メインビューをスクロールするのが面倒な場合に役立ちます。

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

各スクリーンショットの隣に、ステップごとのアノテーションコントロールが表示されます。アクションを評価し、不正確な場合はエラータイプを選択します。

ステップ4：アノテーションワークフロー

Webエージェントトレースを評価する典型的なワークフロー：

タスク説明を読む。 エージェントが何を達成すべきだったかを理解する。
概要にフィルムストリップを使用する。 個々のステップを評価する前に、すべてのスクリーンショットをすばやくスキャンしてエージェントの軌跡を把握する。
各ステップを確認する：
- スクリーンショットを見てページの状態を理解する
- SVGオーバーレイを確認してエージェントがクリックした場所を確認する
- アクション説明を読む
- アクションをCorrect、Acceptable、Incorrect、Unnecessaryのいずれかで評価する
- 不正確な場合、エラータイプを選択する
トレース全体を評価する。 すべてのステップを確認した後、タスクの成功と効率を評価する。
送信して次のトレースに進む。

注意すべきポイント

正しいアクションは、合理的な方法でエージェントをゴールに近づけます。エージェントは正しい要素をクリックし、正しいページに移動し、正しい情報を入力しました。

許容可能なアクションは最適な選択ではありませんが、それでも前進しています。例えば、エージェントが検索バーを使用する代わりにカテゴリページをブラウズする -- 遅いですが、依然として有効です。

不正確なアクションはミスです：間違った要素をクリックする、無関係なページに移動する、フォームに間違った情報を入力するなど。

不要なアクションはゴールに貢献しません：何かをクリックしてすぐに戻る、ターゲットを通り過ぎてスクロールする、関連のないページに移動するなど。

ステップ5：エラー分類

Potatoには、Webエージェントアクション用に特別に構築されたエラー分類が含まれています。各カテゴリの適用方法は以下の通りです：

エラータイプ	説明	例
間違った要素のクリック	エージェントが不正確なUI要素をクリックした	「Laptops」ではなく「Tablets」をクリック
間違ったページへの移動	エージェントが無関係なページに移動した	商品リストではなく「About Us」に移動
より良いオプションの見逃し	より良いアクションが利用可能だった	検索バーの代わりにカテゴリブラウジングを使用
フォーム入力の誤り	エージェントがフォームに間違ったテキストを入力した	「laptop」ではなく「labtop」で検索
タスクの早期完了	エージェントが早すぎる段階で成功を宣言した	間違った商品をカートに追加して停止
不要なナビゲーション	ステップがゴールに貢献しない	カテゴリページ間でホームページにアクセス
ターゲットへのスクロール失敗	ターゲットがビューポートの下にあった	要素が見えない；エージェントはスクロールすべきだった
間違ったページセクションとのインタラクション	正しいページだが間違った領域	メインコンテンツではなくヘッダーをクリック

ステップ6：複雑なトレースの処理

長いトレース（15ステップ以上）

長いトレースの場合、まずフィルムストリップを使用して疑わしいステップを特定します。以下を探してください：

URLが予期せず変わるステップ（間違ったナビゲーション）
エージェントが後退しているように見えるステップ
類似のスクリーンショットが繰り返されるステップ（エージェントがループに陥っている）

その後、それらのステップに対する詳細なアノテーションに集中します。

失敗したトレース

エージェントが失敗したトレースでは、最初の不正確なステップを特定してください -- これはエージェントの改善にとって最も価値のあるアノテーションです。明確にマークし、エージェントが代わりに何をすべきだったかを説明してください。

曖昧なアクション

一部のアクションは、完全なページコンテンツを知らないと判断が難しい場合があります。DOMスナップショットが利用可能な場合は、有効にしてください：

yaml

web_agent_display:
  show_dom_snapshot: true

これにより、生のHTMLを表示する折りたたみ可能なパネルが追加されます。スクリーンショットだけでは曖昧な場合（例：エージェントが複数の重なり合った要素がある領域をクリックした場合）に役立ちます。

ステップ7：VisualWebArenaの設定

VisualWebArenaトレースには追加のビジュアルグラウンディング情報が含まれます。設定は類似していますが、ビジュアルグラウンディングオーバーレイを使用します：

yaml

agentic:
  enabled: true
  trace_converter: webarena         # same converter handles both
  display_type: web_agent
 
  web_agent_display:
    screenshot_max_width: 1000
    overlay:
      enabled: true
      click_marker: "crosshair"     # crosshair is better for precise grounding
      click_color: "#ef4444"
      click_radius: 15
      bounding_box: true            # show element bounding box if available
      bounding_box_color: "#f59e0b"
    filmstrip:
      enabled: true
      thumbnail_width: 180

ステップ8：結果の分析

ステップ位置別のアクション正確性

Webエージェントのエラーはトレース内の特定のポイントに集中することが多いです。エラーが発生する場所を分析してください：

python

import pandas as pd
import json
 
annotations = []
with open("output/annotations.jsonl") as f:
    for line in f:
        annotations.append(json.loads(line))
 
# Collect per-step correctness by position
step_errors = {}
for ann in annotations:
    correctness = ann["annotations"].get("action_correctness", {})
    for step_idx, label in correctness.items():
        pos = int(step_idx)
        if pos not in step_errors:
            step_errors[pos] = {"Correct": 0, "Acceptable": 0, "Incorrect": 0, "Unnecessary": 0}
        step_errors[pos][label] += 1
 
# Print error rate by step position
print("Error rate by step position:")
for pos in sorted(step_errors.keys()):
    counts = step_errors[pos]
    total = sum(counts.values())
    error_rate = (counts["Incorrect"] + counts["Unnecessary"]) / total
    print(f"  Step {pos}: {error_rate:.1%} error rate ({total} observations)")

エラータイプの分布

python

error_counts = {}
for ann in annotations:
    errors = ann["annotations"].get("action_error_type", {})
    for step_idx, error_list in errors.items():
        for error in error_list:
            error_counts[error] = error_counts.get(error, 0) + 1
 
print("\nError Type Distribution:")
for error, count in sorted(error_counts.items(), key=lambda x: -x[1]):
    print(f"  {error}: {count}")

Webサイト別の成功率

python

# If traces span multiple websites
website_success = {}
for ann in annotations:
    # Assuming website info is in the original trace data
    success = ann["annotations"]["task_success"]
    website = ann.get("metadata", {}).get("website", "unknown")
    if website not in website_success:
        website_success[website] = {"Success": 0, "Partial Success": 0, "Failure": 0}
    website_success[website][success] += 1
 
for website, counts in website_success.items():
    total = sum(counts.values())
    rate = counts["Success"] / total
    print(f"{website}: {rate:.1%} success rate")

ステップ9：評価のスケーリング

一致度を伴う複数アノテーター

研究論文の場合、トレースごとに複数のアノテーターを割り当ててください：

yaml

annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

タスク成功ラベルのアノテーター間一致度を計算：

python

from sklearn.metrics import cohen_kappa_score
import pandas as pd
 
df = pd.read_parquet("output/parquet/annotations.parquet")
success = df[df["schema_name"] == "task_success"]
pivot = success.pivot(index="instance_id", columns="annotator", values="value")
 
# Pairwise kappa
annotators = pivot.columns.tolist()
for i in range(len(annotators)):
    for j in range(i + 1, len(annotators)):
        mask = pivot[[annotators[i], annotators[j]]].dropna()
        kappa = cohen_kappa_score(mask[annotators[i]], mask[annotators[j]])
        print(f"Kappa ({annotators[i]} vs {annotators[j]}): {kappa:.3f}")

Solo Modeとの組み合わせ

大規模評価（500以上のトレース）の場合、Solo Modeを使用してLLMに簡単なトレースを処理させてください：

yaml

solo_mode:
  enabled: true
  llm:
    endpoint_type: openai
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
  accuracy_threshold: 0.90
 
agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent

人間が難しいトレースを評価し、LLMが明らかな成功と明白な失敗を処理します。

まとめ

Webブラウジングエージェントの評価には、エージェントが見たものと行ったことを正確に確認する必要があります。PotatoのWeb Agent Displayは以下を提供します：

クリックターゲット、入力フィールド、スクロールアクションをマークするSVGオーバーレイ付きフルスクリーンショット
クイック概要とステップへのランダムアクセスのためのフィルムストリップナビゲーション
エージェントのナビゲーションパスを追跡するURLバー
Web固有のエラー分類を伴うステップごとのアノテーション
WebArena、VisualWebArena、生のブラウザ記録に対応する柔軟な設定

効果的なWebエージェント評価の鍵はビジュアルオーバーレイです：エージェントがクリックした正確な場所を確認できなければ、評価者はアクションの正確性を確実に判断できません。

参考資料

エージェント型アノテーションのドキュメント -- 完全な設定リファレンス
AIエージェントの評価 -- 一般的なエージェント評価ガイド
Solo Mode -- 人間-LLM協調で評価をスケールアップ
Parquetエクスポート -- 分析のための結果エクスポート