Annotazione di agenti web

Rivedi in Potato le tracce degli agenti che navigano il web, con filmstrip, overlay SVG (clic, bounding box, percorsi del mouse) e controlli di annotazione passo per passo.

Novità della v2.4.0

Per valutare un agente AI che naviga il web serve vedere esattamente che cosa ha visto l'agente, dove ha cliccato e se ogni passo aveva senso. Potato mette a disposizione un visualizzatore di tracce per agenti web con due modalità: la revisione di tracce già registrate e la creazione di nuove tracce navigando siti dal vivo.

Panoramica

Modalità	Quando usarla
Modalità revisione	Hai tracce già registrate da WebArena, Mind2Web, Anthropic Computer Use o dal registratore di Potato
Modalità creazione	Vuoi che gli annotatori navighino i siti e registrino nuove tracce di interazione

Modalità revisione

Gli annotatori scorrono gli screenshot di una sessione di navigazione dell'agente. Gli overlay SVG disegnano sopra ogni screenshot i marcatori di clic, le bounding box, i percorsi del mouse e gli indicatori di scorrimento.

Configurazione

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

Formato dei dati

Ogni istanza richiede un array steps con i dati di ciascun passo:

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

Tipi di azione supportati

Azione	Overlay
`click`	Cerchio rosso con mirino e animazione a pulsazione
`type`	Evidenziazione gialla sull'elemento di destinazione
`scroll`	Freccia verde direzionale
`hover`	Cerchio viola
`select`	Bounding box blu
`navigate`	Nessun overlay
`wait`	Nessun overlay
`done`	Nessun overlay

Scorciatoie da tastiera

Tasto	Azione
`←` / `→`	Passo precedente / successivo
`1`	Mostra o nasconde i marcatori di clic
`2`	Mostra o nasconde le bounding box
`3`	Mostra o nasconde i percorsi del mouse
`4`	Mostra o nasconde gli indicatori di scorrimento
`A`	Mostra tutti gli overlay
`N`	Nasconde tutti gli overlay

Annotazioni passo per passo

Aggiungi per_step: true a uno schema di annotazione qualsiasi per far comparire i suoi controlli in linea con ogni passo:

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"

Le annotazioni per passo vengono salvate come {scheme_name}_step_{index} (per esempio step_correctness_step_0).

Modalità creazione

Gli annotatori navigano un sito dal vivo dentro l'interfaccia di Potato e le loro interazioni vengono registrate in automatico come traccia pronta per l'annotazione.

Configurazione

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

Modalità proxy

Modalità	Descrizione
`auto` (predefinita)	Rileva se il sito di destinazione permette l'incorporamento in iframe e sceglie da solo la modalità migliore
`iframe`	Forza il proxy via iframe: funziona con circa il 90% dei siti e aggiunge meno di 100 ms di latenza
`playwright`	Forza Playwright lato server: funziona con il 100% dei siti, richiede il pacchetto `playwright`

Per abilitare la modalità Playwright:

bash

pip install playwright
playwright install chromium

Conversione di tracce esistenti

Usa la CLI di conversione per normalizzare nel formato di Potato le tracce prodotte da altri framework:

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

Formati di input supportati: WebArena, VisualWebArena, Mind2Web, Anthropic Computer Use e le registrazioni native di Potato.

Esempio completo

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"

Esecuzione dei progetti di esempio

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

Riferimento API

Questi endpoint REST sono disponibili quando si usa la modalità creazione:

Endpoint	Metodo	Descrizione
`/api/web_agent/start_session`	POST	Avvia una sessione di registrazione
`/api/web_agent/save_step`	POST	Salva un passo di interazione registrato
`/api/web_agent/save_screenshot`	POST	Carica lo screenshot di un passo
`/api/web_agent/end_session`	POST	Chiude la sessione e salva la traccia
`/api/web_agent/proxy/{url}`	GET	Instrada un URL esterno attraverso il server
`/api/web_agent/check_frameable`	GET	Verifica se un URL permette l'incorporamento in iframe

Ulteriori letture

Valutazione dal vivo degli agenti — valuta gli agenti mentre girano in tempo reale
Annotazione Agentiva — panoramica dei convertitori di formato e dei tipi di visualizzazione
Apprendimento Attivo — dai priorità alle tracce più informative da annotare

Per i dettagli implementativi, vedi la documentazione sorgente.