Annoter les agents de navigation web : des traces WebArena à l'évaluation humaine

Les agents de navigation web opèrent dans une modalité fondamentalement différente des agents textuels. Ils naviguent sur de vraies pages web, cliquent sur des boutons, remplissent des formulaires et font défiler le contenu. Les évaluer nécessite de voir ce que l'agent a vu (l'état de la page) et ce que l'agent a fait (l'action effectuée), idéalement avec des superpositions visuelles montrant exactement où l'agent a cliqué.

L'affichage de traces d'agents web de Potato est conçu spécifiquement pour cette tâche. Il rend des captures d'écran pleine page avec des superpositions SVG d'actions, fournit une vue en pellicule pour une navigation rapide et supporte l'annotation par étape de la correction des actions.

Ce guide vous accompagne dans l'évaluation de traces WebArena, mais la même approche fonctionne pour VisualWebArena, les enregistrements bruts de navigateur et tout autre format d'agent web.

Prérequis

bash

pip install potato-annotation

Vous aurez besoin de fichiers de traces WebArena, qui incluent généralement des captures d'écran et un journal d'actions JSON. Si vous travaillez avec VisualWebArena, le format est similaire mais peut inclure des informations supplémentaires d'ancrage visuel.

Étape 1 : Comprendre le format de traces WebArena

Une trace WebArena consiste en un fichier JSON par épisode contenant la description de la tâche, la séquence d'actions et les chemins des captures d'écran. Voici un exemple simplifié.

Créez 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"
}

Chaque étape a une capture d'écran, l'action effectuée, l'élément cible et les coordonnées du clic. Potato utilise ces informations pour rendre les superpositions visuelles.

Étape 2 : Configurer le projet

Créez 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/"

Étape 3 : Comprendre l'affichage d'agent web

Quand vous ouvrez une trace, l'affichage d'agent web montre :

La vue principale de capture d'écran

La capture d'écran de l'étape courante est affichée en pleine largeur (jusqu'à 900px). Une superposition SVG est dessinée par-dessus :

Cercle rouge aux coordonnées du clic, montrant exactement où l'agent a cliqué
Surbrillance bleue autour des champs de saisie de texte où l'agent a tapé
Indicateur fléché pour les actions de défilement montrant la direction et l'amplitude

Sous la capture d'écran, vous voyez :

Barre d'URL montrant l'URL de la page à cette étape
Description de l'action (par ex. « Clic sur 'Lien catégorie Electronics' aux coordonnées [245, 82] »)

La pellicule

En bas de l'affichage, une pellicule horizontale montre les miniatures de toutes les captures d'écran. Chaque miniature a une petite étiquette indiquant le type d'action (clic, saisie, défilement). Cliquez sur n'importe quelle miniature pour accéder à cette étape.

La pellicule est particulièrement utile pour les longues traces (10+ étapes) où faire défiler la vue principale serait fastidieux.

Annotation par étape

À côté de chaque capture d'écran, les contrôles d'annotation par étape apparaissent. Notez l'action, et si elle est incorrecte, sélectionnez le type d'erreur.

Étape 4 : Le flux d'annotation

Un flux de travail typique pour évaluer une trace d'agent web :

Lisez la description de la tâche. Comprenez ce que l'agent devait accomplir.
Utilisez la pellicule pour un aperçu. Parcourez rapidement toutes les captures d'écran pour avoir une idée de la trajectoire de l'agent avant de noter les étapes individuelles.
Parcourez chaque étape :
- Regardez la capture d'écran pour comprendre l'état de la page
- Vérifiez la superposition SVG pour voir ce que l'agent a cliqué
- Lisez la description de l'action
- Notez l'action comme Correcte, Acceptable, Incorrecte ou Inutile
- Si incorrecte, sélectionnez le(s) type(s) d'erreur
Notez la trace globale. Après avoir examiné toutes les étapes, notez la réussite de la tâche et l'efficacité.
Soumettez et passez à la trace suivante.

Quoi chercher

Les actions correctes rapprochent l'agent de l'objectif de manière raisonnable. L'agent a cliqué sur le bon élément, navigué vers la bonne page ou saisi les bonnes informations.

Les actions acceptables ne sont pas le choix optimal mais font quand même progresser. Par exemple, l'agent parcourt une page de catégorie au lieu d'utiliser la barre de recherche -- plus lent, mais toujours viable.

Les actions incorrectes sont des erreurs : cliquer sur le mauvais élément, naviguer vers une page sans rapport ou saisir de mauvaises informations dans un formulaire.

Les actions inutiles ne contribuent pas à l'objectif : cliquer sur quelque chose puis revenir immédiatement en arrière, défiler au-delà de la cible ou naviguer vers des pages non pertinentes.

Étape 5 : Taxonomie des erreurs

Potato inclut une taxonomie d'erreurs spécialement conçue pour les actions d'agents web. Voici comment appliquer chaque catégorie :

Type d'erreur	Description	Exemple
Mauvais élément cliqué	L'agent a cliqué sur un élément UI incorrect	A cliqué sur « Tablettes » au lieu de « Laptops »
Mauvaise page naviguée	L'agent a abouti sur une page sans rapport	A navigué vers « À propos » au lieu de la liste de produits
Option meilleure/plus proche manquée	Une meilleure action était disponible	A utilisé la navigation par catégorie au lieu de la barre de recherche
Saisie de formulaire incorrecte	L'agent a saisi du mauvais texte dans un formulaire	A cherché « labtop » au lieu de « laptop »
Complétion prématurée de tâche	L'agent a déclaré le succès trop tôt	A ajouté le mauvais article au panier et s'est arrêté
Navigation inutile	L'étape ne contribue pas à l'objectif	A visité la page d'accueil entre les pages de catégories
Échec de défilement vers la cible	La cible était en dessous du viewport	L'élément n'était pas visible ; l'agent aurait dû défiler
Interaction avec la mauvaise section de page	Bonne page mais mauvaise zone	A cliqué sur l'en-tête au lieu du contenu principal

Étape 6 : Gérer les traces complexes

Longues traces (15+ étapes)

Pour les longues traces, utilisez la pellicule pour identifier d'abord les étapes suspectes. Cherchez :

Des étapes où l'URL change de manière inattendue (mauvaise navigation)
Des étapes où l'agent semble revenir en arrière
Des captures d'écran similaires répétées (agent bloqué dans une boucle)

Puis concentrez votre annotation détaillée sur ces étapes.

Traces échouées

Pour les traces où l'agent échoue, identifiez la première étape incorrecte -- c'est l'annotation la plus précieuse pour améliorer l'agent. Marquez-la clairement et décrivez ce que l'agent aurait dû faire à la place.

Actions ambiguës

Certaines actions sont difficiles à juger sans connaître le contenu complet de la page. Si le snapshot DOM est disponible, activez-le :

yaml

web_agent_display:
  show_dom_snapshot: true

Cela ajoute un panneau réductible montrant le HTML brut, ce qui aide quand la capture d'écran seule est ambiguë (par ex. l'agent a cliqué dans une zone avec plusieurs éléments superposés).

Étape 7 : Configuration pour VisualWebArena

Les traces VisualWebArena incluent des informations supplémentaires d'ancrage visuel. La configuration est similaire mais utilise la superposition d'ancrage visuel :

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

Étape 8 : Analyser les résultats

Exactitude des actions par position d'étape

Les erreurs d'agents web se regroupent souvent à des points spécifiques de la trace. Analysez où les erreurs se produisent :

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)")

Distribution des types d'erreurs

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}")

Taux de réussite par site 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")

Étape 9 : Passer à l'échelle

Annotateurs multiples avec accord

Pour les articles de recherche, assignez plusieurs annotateurs par trace :

yaml

annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

Calculez l'accord inter-annotateurs sur l'étiquette de réussite de la tâche :

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}")

Combiner avec le Solo Mode

Pour les évaluations à grande échelle (500+ traces), utilisez le Solo Mode pour laisser un LLM gérer les traces faciles :

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

L'humain évalue les traces difficiles ; le LLM gère les réussites évidentes et les échecs manifestes.

Résumé

Évaluer les agents de navigation web nécessite de voir exactement ce que l'agent a vu et fait. L'affichage d'agent web de Potato fournit :

Des captures d'écran complètes avec des superpositions SVG marquant les cibles de clic, les champs de saisie et les actions de défilement
La navigation par pellicule pour un aperçu rapide et un accès aléatoire aux étapes
La barre d'URL suivant le chemin de navigation de l'agent
L'annotation par étape avec une taxonomie d'erreurs spécifique au web
Une configuration flexible pour WebArena, VisualWebArena et les enregistrements bruts de navigateur

La clé d'une évaluation efficace des agents web est la superposition visuelle : sans voir exactement où l'agent a cliqué, les évaluateurs ne peuvent pas juger de manière fiable l'exactitude des actions.

Pour aller plus loin

Documentation de l'annotation agentique -- référence de configuration complète
Évaluer les agents IA -- guide général d'évaluation d'agents
Solo Mode -- passer à l'échelle avec la collaboration humain-LLM
Export Parquet -- exporter les résultats pour l'analyse