Skip to content

Annotation d'agents web

Examinez des traces d'agents de navigation web dans Potato avec la pellicule de navigation, les surcouches SVG (clics, boîtes englobantes, trajets de souris) et des contrôles d'annotation par étape.

Nouveau dans la v2.4.0

Évaluer des agents IA qui naviguent sur le web suppose de voir exactement ce que l'agent a vu, où il a cliqué, et si chaque étape avait du sens. Potato fournit une visionneuse de traces d'agents web dédiée, avec deux modes : l'examen de traces préenregistrées et la création de nouvelles traces en naviguant sur des sites en direct.

Vue d'ensemble

ModeQuand l'utiliser
Mode examenVous disposez de traces préenregistrées venant de WebArena, Mind2Web, Anthropic Computer Use, ou de l'enregistreur de Potato
Mode créationVous voulez que les annotateurs naviguent sur des sites et enregistrent de nouvelles traces d'interaction

Mode examen

Les annotateurs parcourent pas à pas les captures d'écran d'une session de navigation de l'agent. Des surcouches SVG dessinent les marqueurs de clic, les boîtes englobantes, les trajets de souris et les indicateurs de défilement par-dessus chaque capture.

Configuration

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

Format des données

Chaque instance a besoin d'un tableau steps contenant les données de chaque étape :

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}
    }
  ]
}

Types d'action pris en charge

ActionSurcouche
clickCercle rouge avec réticule et animation de pulsation
typeSurlignage jaune sur l'élément ciblé
scrollFlèche directionnelle verte
hoverCercle violet
selectBoîte englobante bleue
navigateAucune surcouche
waitAucune surcouche
doneAucune surcouche

Raccourcis clavier

ToucheAction
← / →Étape précédente / suivante
1Afficher ou masquer les marqueurs de clic
2Afficher ou masquer les boîtes englobantes
3Afficher ou masquer les trajets de souris
4Afficher ou masquer les indicateurs de défilement
AAfficher toutes les surcouches
NMasquer toutes les surcouches

Annotations par étape

Ajoutez per_step: true à n'importe quel schéma d'annotation pour créer des contrôles d'annotation qui apparaissent en ligne avec chaque étape :

yaml
annotation_schemes:
  - annotation_type: radio
    name: step_correctness
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: step_notes

Les annotations par étape sont stockées sous la forme {scheme_name}_step_{index} (par exemple step_correctness_step_0).

Mode création

Les annotateurs naviguent sur un site en direct depuis l'interface de Potato, et leurs interactions sont enregistrées automatiquement sous forme de trace prête à annoter.

Configuration

yaml
instance_display:
  fields:
    - key: browsing_session
      type: web_agent_trace
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_observation: true
        show_thought: true

Modes de proxy

ModeDescription
auto (par défaut)Détecte si le site cible autorise l'intégration en iframe et choisit le meilleur mode automatiquement
iframeForce le proxy iframe : fonctionne pour environ 90 % des sites, avec moins de 100 ms de surcoût
playwrightForce Playwright côté serveur : fonctionne pour 100 % des sites, nécessite le paquet playwright

Pour activer le mode Playwright :

bash
pip install playwright
playwright install chromium

Conversion de traces existantes

Utilisez le convertisseur de traces en ligne de commande pour normaliser au format de Potato des traces issues d'autres cadres logiciels :

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

Formats d'entrée pris en charge : WebArena, VisualWebArena, Mind2Web, Anthropic Computer Use, et les enregistrements bruts de Potato.

Exemple complet

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
    description: "Did the agent complete the task successfully?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: radio
    name: step_correctness
    description: "Was this step correct?"
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: error_description
    description: "Describe any errors in the agent's behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Lancer les projets d'exemple

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

Référence de l'API

Ces points de terminaison REST sont disponibles en mode création :

Point de terminaisonMéthodeDescription
/api/web_agent/start_sessionPOSTDémarre une session d'enregistrement
/api/web_agent/save_stepPOSTEnregistre une étape d'interaction
/api/web_agent/save_screenshotPOSTEnvoie une capture d'écran pour une étape
/api/web_agent/end_sessionPOSTTermine la session et sauvegarde la trace
/api/web_agent/proxy/{url}GETFait passer une URL externe par le serveur
/api/web_agent/check_frameableGETTeste si une URL autorise l'intégration en iframe

Pour aller plus loin

Pour les détails d'implémentation, consultez la documentation source.