Live-Evaluation von Agenten

KI-Agenten in Echtzeit bei der Arbeit zusehen und ihr Verhalten mitten im Lauf annotieren, mit Pause, Anweisungen und Übernahme. Unterstützt Web- und Coding-Agenten mit Anthropic, Ollama und dem Claude SDK.

Neu in v2.4.0

Die Live-Evaluation von Agenten lässt Annotatoren einem KI-Agenten in Echtzeit beim Surfen zusehen und sein Verhalten während des Laufs annotieren statt im Nachhinein. Der Agent macht Screenshots, schickt sie an ein Vision-LLM, bekommt Aktionen zurück und führt sie in einem Headless-Browser aus. Jeder Schritt wird live auf den Bildschirm des Annotators gestreamt.

Voraussetzungen

bash

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

Konfiguration

yaml

live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  system_prompt: |
    You are a web browsing agent. Complete the given task efficiently.
    At each step, describe your thought, then output an action.
  max_steps: 30
  step_delay: 1.0
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Agent Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true

Konfigurationsreferenz

Option	Typ	Standard	Beschreibung
`endpoint_type`	string	`anthropic_vision`	LLM-Anbieter für den Agenten
`ai_config.model`	string	`claude-sonnet-4-20250514`	zu verwendendes Modell
`ai_config.api_key`	string	Umgebungsvariable	API-Key (Syntax `${VAR}` nutzen)
`ai_config.max_tokens`	int	`4096`	maximale Tokenzahl je LLM-Antwort
`ai_config.temperature`	float	`0.3`	Sampling-Temperatur
`system_prompt`	string	eingebaut	System-Prompt für den Agenten
`max_steps`	int	`30`	maximale Schrittzahl vor dem Abbruch
`step_delay`	float	`1.0`	Sekunden zwischen zwei Schritten
`viewport.width`	int	`1280`	Breite des Browser-Viewports
`viewport.height`	int	`720`	Höhe des Browser-Viewports
`allow_takeover`	bool	`true`	erlaubt Annotatoren die manuelle Steuerung
`allow_instructions`	bool	`true`	erlaubt Annotatoren Anweisungen mitten im Lauf
`history_window`	int	`5`	Anzahl der letzten Schritte im LLM-Kontext

Datenformat

Jede Instanz liefert die Aufgabe und die Start-URL:

json

{
  "id": "task_001",
  "task_description": "Search for climate change on Wikipedia and find the year it was first described",
  "start_url": "https://en.wikipedia.org"
}

Ablauf für Annotatoren

Der Annotator liest die Aufgabenbeschreibung und klickt auf Start Agent
Ein Headless-Chromium startet und verbindet sich mit dem LLM
Screenshots werden live in den Viewer gestreamt, während der Agent navigiert. Jeder Schritt zeigt den Screenshot, den Gedanken des Agenten und die ausgeführte Aktion
Über das Bedienfeld kann der Annotator eingreifen:
- Pause / Fortsetzen — den Agenten zwischen zwei Schritten anhalten
- Anweisungen senden — mitten im Lauf eine Nachricht in den Kontext des Agenten einspeisen
- Übernehmen — auf manuelle Steuerung des Browsers umschalten
- Stopp — die Sitzung vorzeitig beenden
Endet die Sitzung (Erfolg, Fehlschlag oder max_steps erreicht), wird der Trace gespeichert und die Anzeige wechselt in den Prüfmodus
Der Annotator füllt die Annotationsschemata aus, um die Leistung des Agenten zu bewerten

Tastenkürzel

Taste	Aktion
`Space`	Pause / Fortsetzen
`Escape`	Sitzung beenden

Annotationsschemata ergänzen

Die Live-Agent-Anzeige lässt sich mit beliebigen Annotationsschemata von Potato kombinieren:

yaml

annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes, fully"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "How efficiently did the agent work?"
    min_label: "Very inefficient"
    max_label: "Very efficient"
    scale: 5
  - annotation_type: text
    name: errors_observed
    question: "Describe any errors or unnecessary steps"
  - annotation_type: span
    name: error_steps
    question: "Mark any steps where the agent made an error"
    labels:
      - name: hallucination
      - name: wrong_target
      - name: unnecessary_action

Vollständiges Beispiel

yaml

task_name: "Live Agent Evaluation Study"
task_dir: "."
 
live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  max_steps: 25
  step_delay: 1.5
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
  history_window: 5
 
data_files:
  - "tasks.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "Rate the agent's efficiency"
    scale: 5
    min_label: "Very inefficient"
    max_label: "Very efficient"
  - annotation_type: text
    name: notes
    question: "Notes on agent behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Architektur

Der Live-Agent läuft als Hintergrund-Thread in Flask. Screenshots und Zustandsänderungen werden über Server-Sent Events (SSE) an den Browser gestreamt. Die Bedienelemente für den Annotator (Pause, Anweisung, Übernahme, Stopp) rufen REST-Endpunkte auf, die sich mit dem Hintergrund-Thread abstimmen.

text

Annotator (browser)  <── SSE stream ──  Flask Server  ── Playwright ──► Headless Browser
                     ──► REST control ─►              ◄── LLM API ────► Claude Vision

Screenshots werden unter {task_dir}/live_sessions/ gespeichert und für die Filmstreifen-Ansicht über die API ausgeliefert.

Trace-Export

Endet eine Sitzung, exportiert Potato den vollständigen Trace automatisch als JSON im Format web_agent_trace, darin enthalten:

alle Schritte mit Screenshots, Aktionen, Gedanken und Beobachtungen
alle Anweisungen, die der Annotator während des Laufs geschickt hat
Zeitstempel und Metadaten zur Agent-Konfiguration
Ereignisse, bei denen der Annotator übernommen hat

Abgeschlossene Live-Sitzungen lassen sich damit später im gewohnten Viewer für die Annotation von Web-Agenten durchsehen.

Fehlerbehebung

„Playwright is not installed" — pip install playwright && playwright install chromium ausführen.

„Anthropic API key required" — die Umgebungsvariable ANTHROPIC_API_KEY setzen oder in der Konfiguration api_key: ${ANTHROPIC_API_KEY} verwenden.

Der Agent wirkt langsam — jeder Schritt braucht einen LLM-API-Aufruf (typischerweise 3–10 Sekunden). Während das LLM rechnet, erscheint die Denkanzeige. Bei langen Sitzungen history_window verkleinern, um Tempo zu gewinnen.

Screenshots laden nicht — prüfen, ob task_dir beschreibbar ist und der Server genug freien Speicherplatz hat.

Backends für Coding-Agenten

Neben Web-Agenten unterstützt Potato auch die Live-Beobachtung von Coding-Agenten. Dafür stehen drei Backends bereit:

Ollama (lokal, ohne API-Key)

Coding-Agenten mit vollständig lokalen Modellen evaluieren, ohne API-Key.

yaml

live_agent:
  endpoint_type: coding_agent
  backend: ollama
  ai_config:
    model: qwen2.5-coder:7b
    host: "http://localhost:11434"
  max_steps: 50
  project_dir: "./workspace"

Anthropic API

Claude mit Tool-Nutzung für die Evaluation von Coding-Agenten einsetzen.

yaml

live_agent:
  endpoint_type: coding_agent
  backend: anthropic
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 8192
  max_steps: 50
  project_dir: "./workspace"

Claude Agent SDK

Die vollen Claude-Code-Fähigkeiten für anspruchsvollere Sitzungen mit Coding-Agenten.

yaml

live_agent:
  endpoint_type: coding_agent
  backend: claude_agent_sdk
  ai_config:
    max_turns: 50
  project_dir: "./workspace"

Die vollständige Referenz samt Rollback, Verzweigung und Export der Trajektorien steht unter Live-Beobachtung von Coding-Agenten.

Rollback und Checkpoints

Bei Sitzungen mit Coding-Agenten legt Potato nach jeder Dateiänderung einen Git-Commit an. Das ermöglicht:

Rollback per Klick auf jeden früheren Checkpoint
Verzweigen und erneut abspielen — von jedem Checkpoint aus einen anderen Ansatz versuchen
Vollständige Historie jedes Dateizustands für die Prüfung

Die Checkpoints werden automatisch über einen eigenen Git-Branch pro Sitzung verwaltet.

Verzweigte Trajektorien

Setzt ein Annotator zurück und probiert einen anderen Ansatz, entsteht in Potato eine verzweigte Trajektorie. Beide Branches bleiben in der Ausgabe erhalten und liefern Trainingsdaten für:

Process Reward Models — Korrektheitslabels pro Schritt über die Branches hinweg
Präferenzlernen — welcher Branch das bessere Ergebnis geliefert hat
Code-Review-Datensätze — Codequalität über verschiedene Ansätze hinweg vergleichen

Weiterführende Literatur

Live-Beobachtung von Coding-Agenten — Coding-Agenten beobachten mit Ollama, Anthropic und dem Claude SDK
Annotation von Web-Agenten — aufgezeichnete Agent-Traces durchsehen
Agentische Annotation — Überblick über Agent-Trace-Formate und Konverter
Process-Reward-Annotation — Erhebung von PRM-Trainingsdaten
KI-Unterstützung — LLM-Anbindung zur Unterstützung der Annotation

Implementierungsdetails stehen in der Quelldokumentation.