Web-Agenten-Annotation

Traces von Web-Browsing-Agenten in Potato durchsehen, mit Filmstreifen-Navigation, SVG-Overlays (Klicks, Bounding-Boxen, Mauspfade) und Annotationsfeldern pro Schritt.

Neu in v2.4.0

Wer KI-Agenten bewertet, die im Web browsen, muss genau sehen, was der Agent gesehen hat, wohin er geklickt hat und ob jeder Schritt sinnvoll war. Potato bringt dafür einen eigenen Web-Agent-Trace-Viewer mit zwei Modi mit: dem Durchsehen bereits aufgezeichneter Traces und dem Erstellen neuer Traces durch Browsen echter Websites.

Überblick

Modus	Wann geeignet
Review-Modus	Es liegen aufgezeichnete Traces aus WebArena, Mind2Web, Anthropic Computer Use oder Potatos eigenem Recorder vor
Erstellungsmodus	Annotatoren sollen Websites besuchen und dabei neue Interaktions-Traces aufzeichnen

Review-Modus

Annotatoren gehen die Screenshots einer Browsing-Sitzung des Agenten Schritt für Schritt durch. SVG-Overlays zeichnen Klickmarken, Bounding-Boxen, Mauspfade und Scroll-Anzeigen über jeden Screenshot.

Konfiguration

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

Datenformat

Jede Instanz braucht ein steps-Array mit den Daten pro Schritt:

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

Unterstützte Aktionstypen

Aktion	Overlay
`click`	Roter Kreis mit Fadenkreuz und Pulsanimation
`type`	Gelbe Hervorhebung des Zielelements
`scroll`	Grüner Richtungspfeil
`hover`	Violetter Kreis
`select`	Blaue Bounding-Box
`navigate`	Kein Overlay
`wait`	Kein Overlay
`done`	Kein Overlay

Tastenkürzel

Taste	Aktion
`←` / `→`	Vorheriger / nächster Schritt
`1`	Klickmarken-Overlays ein- und ausblenden
`2`	Bounding-Box-Overlays ein- und ausblenden
`3`	Mauspfad-Overlays ein- und ausblenden
`4`	Scroll-Anzeigen ein- und ausblenden
`A`	Alle Overlays anzeigen
`N`	Alle Overlays ausblenden

Annotationen pro Schritt

Mit per_step: true in einem beliebigen Annotationsschema entstehen Eingabefelder, die direkt bei jedem Schritt erscheinen:

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"

Annotationen pro Schritt werden als {scheme_name}_step_{index} gespeichert (etwa step_correctness_step_0).

Erstellungsmodus

Annotatoren besuchen eine echte Website innerhalb der Potato-Oberfläche, und ihre Interaktionen werden automatisch als annotationsfertiger Trace aufgezeichnet.

Konfiguration

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

Proxy-Modi

Modus	Beschreibung
`auto` (Standard)	Erkennt, ob die Zielseite eine Einbettung per iframe erlaubt, und wählt automatisch den passenden Modus
`iframe`	Erzwingt den iframe-Proxy, funktioniert bei rund 90 % der Seiten mit weniger als 100 ms Overhead
`playwright`	Erzwingt serverseitiges Playwright, funktioniert bei allen Seiten, setzt das Paket `playwright` voraus

Playwright-Modus aktivieren:

bash

pip install playwright
playwright install chromium

Vorhandene Traces umwandeln

Das CLI-Werkzeug zur Trace-Umwandlung überführt Traces aus anderen Frameworks in Potatos Format:

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

Unterstützte Eingabeformate: WebArena, VisualWebArena, Mind2Web, Anthropic Computer Use und Rohaufzeichnungen aus Potato.

Vollständiges Beispiel

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"

Beispielprojekte ausführen

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-Referenz

Im Erstellungsmodus stehen diese REST-Endpunkte zur Verfügung:

Endpunkt	Methode	Beschreibung
`/api/web_agent/start_session`	POST	Eine Aufzeichnungssitzung beginnen
`/api/web_agent/save_step`	POST	Einen aufgezeichneten Interaktionsschritt speichern
`/api/web_agent/save_screenshot`	POST	Einen Screenshot für einen Schritt hochladen
`/api/web_agent/end_session`	POST	Sitzung beenden und den Trace sichern
`/api/web_agent/proxy/{url}`	GET	Eine externe URL über den Server proxen
`/api/web_agent/check_frameable`	GET	Prüfen, ob eine URL die Einbettung per iframe erlaubt

Weiterführende Informationen

Live-Evaluation von Agenten — Agenten bewerten, während sie laufen
Agentische Annotation — Überblick über Trace-Konverter und Anzeigetypen
Active Learning — die aussagekräftigsten Traces zuerst annotieren

Implementierungsdetails stehen in der Quelldokumentation.