Agentische Annotation

Neu in v2.3.0

KI-Agenten werden zunehmend für komplexe mehrstufige Aufgaben eingesetzt: Websuche, Code schreiben, APIs aufrufen und Unter-Agenten orchestrieren. Zu beurteilen, ob ein Agent tatsächlich das Richtige getan hat, erfordert jedoch menschliches Urteilsvermögen auf einer Granularitätsebene, die herkömmliche Annotationswerkzeuge nicht unterstützen können. Ein einzelner Agenten-Trace kann Dutzende von Schritten, Tool-Aufrufe, Zwischenüberlegungen, Screenshots und Verzweigungsentscheidungen enthalten. Annotatoren müssen all diesen Kontext sehen, effizient navigieren und strukturierte Evaluierungen sowohl auf Trace-Ebene als auch auf Einzelschrittebene liefern.

Potatos System für agentische Annotation adressiert dies mit vier Fähigkeiten:

1. 13 Trace-Formatkonverter, die Agenten-Logs aus beliebigen gängigen Frameworks in ein einheitliches Format normalisieren
2. 5 spezialisierte Anzeigetypen, optimiert für verschiedene Agenten-Modalitäten (Tool-Nutzung, Websuche, Coding, Chat, Live-Beobachtung)
3. 9 vorgefertigte Annotationsschemata, die die häufigsten Evaluierungsdimensionen für Agenten abdecken
4. 4 zweckgebaute Annotationstypen für fortgeschrittene Evaluierung: Trajektorienevaluierung, Rubrik-Evaluierung, paarweiser Vergleich und Prozessbelohnungsannotation

Trace-Formatkonverter

Agenten-Traces liegen je nach Framework in sehr unterschiedlichen Formaten vor. Potato liefert 13 Konverter, die diese in eine einheitliche interne Darstellung normalisieren. Sie geben den Konverter in Ihrer Konfiguration an oder lassen Potato das Format automatisch erkennen.

Konverter-Referenz

Konfiguration

Geben Sie den Konverter in Ihrer Projektkonfiguration an:

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Jede Zeile in der Trace-Datei sollte ein JSON-Objekt mit dem rohen Agenten-Trace sein. Der Konverter übernimmt den Rest.

Für Multi-Agent-Traces, bei denen verschiedene Agenten unterschiedliche Frameworks verwenden, können Sie Konverter pro Agent angeben:

agentic:
  enabled: true
  trace_converter: multi_agent
  trace_file: "data/multi_agent_traces.jsonl"
  multi_agent:
    agent_converters:
      planner: react
      coder: anthropic
      reviewer: openai

Automatische Erkennung

Wenn Sie sich nicht sicher sind, welchen Konverter Sie verwenden sollen, setzen Sie trace_converter: auto:

agentic:
  enabled: true
  trace_converter: auto
  trace_file: "data/traces.jsonl"

Potato analysiert die ersten 10 Traces und wählt den am besten passenden Konverter anhand von Feldsignaturen aus. Eine Warnung wird ausgegeben, wenn die Konfidenz unter 80 % liegt – in diesem Fall sollten Sie den Konverter explizit angeben.

Benutzerdefinierte Konverter

Wenn Ihr Agenten-Framework nicht aufgelistet ist, können Sie einen Python-Konverter schreiben:

# converters/my_converter.py
from potato.agentic.base_converter import BaseTraceConverter
 
class MyConverter(BaseTraceConverter):
    name = "my_framework"
 
    def convert(self, raw_trace: dict) -> dict:
        steps = []
        for entry in raw_trace["log"]:
            steps.append({
                "type": entry.get("kind", "action"),
                "content": entry["text"],
                "timestamp": entry.get("ts"),
                "metadata": entry.get("extra", {}),
            })
        return {"steps": steps}

In der Konfiguration registrieren:

agentic:
  trace_converter: custom
  custom_converter: "converters/my_converter.py:MyConverter"

Anzeigetypen

Sobald Traces konvertiert sind, rendert Potato sie mit einem von fünf spezialisierten Anzeigetypen. Jeder ist für eine andere Agenten-Modalität optimiert.

1. Agent-Trace-Anzeige

Die Standardanzeige für Tool-nutzende Agenten (OpenAI Function Calling, Anthropic tool_use, ReAct, LangChain usw.). Jeder Schritt wird als Karte mit farblicher Codierung nach Schritttyp gerendert.

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Color coding for step types
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Collapsible sections
    collapse_observations: true
    collapse_threshold: 500    # characters before auto-collapsing
 
    # Step numbering
    show_step_numbers: true
    show_timestamps: true
 
    # Tool call rendering
    render_json: true          # pretty-print JSON arguments
    syntax_highlight: true     # highlight code in observations

Funktionen:

• Schrittkarten mit farbigem linken Rand zur Typkennzeichnung (Gedanke, Aktion, Beobachtung, Fehler)
• Einklappbare Abschnitte für lange Beobachtungen oder Tool-Ausgaben (konfigurierbare Schwelle)
• JSON-Formatierung für Tool-Aufruf-Argumente und strukturierte Antworten
• Syntaxhervorhebung für Code-Blöcke in Beobachtungen
• Schrittzeitleiste in der Seitenleiste für einen Überblick über den gesamten Trace
• Springe-zu-Schritt-Navigation für lange Traces

2. Web-Agent-Trace-Anzeige

Speziell entwickelt für Web-Browsing-Agenten (WebArena, VisualWebArena, rohe Browser-Aufzeichnungen). Rendert Screenshots mit SVG-Overlays, die zeigen, wo der Agent geklickt, getippt oder gescrollt hat.

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlay for agent actions
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair, or arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # highlight for text input fields
      scroll_indicator: true
 
    # Filmstrip view
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # DOM snapshot display
    show_dom_snapshot: false        # optional raw DOM view
    show_url_bar: true
    show_action_description: true

Funktionen:

• Screenshot-Galerie mit Vollansicht und Zoom
• SVG-Overlays zeigen Klickziele (rote Kreise), Texteingabebereiche (blaue Markierungen) und Scrollrichtungen
• Filmstreifen-Ansicht unten mit allen Screenshots als Vorschaubilder zur schnellen Navigation
• Aktionsbeschreibung unter jedem Screenshot (z. B. "Klick auf Schaltfläche 'Add to Cart'")
• URL-Leiste mit der aktuellen Seiten-URL bei jedem Schritt
• Vorher/Nachher-Vergleich für Schritte, die den Seiteninhalt ändern

3. Interaktive Chat-Anzeige

Zur Evaluierung von Konversationsagenten und Chatbots. Unterstützt zwei Untermodi: Live-Chat, bei dem Annotatoren in Echtzeit mit dem Agenten interagieren, und Trace-Review, bei dem Annotatoren eine aufgezeichnete Konversation evaluieren.

agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # or "live_chat"
 
    # Trace review settings
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" or "message"
 
    # Live chat settings (when mode: live_chat)
    live_chat:
      proxy: openai             # agent proxy to use
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Common settings
    show_role_labels: true
    role_colors:
      user: "#3b82f6"
      assistant: "#6E56CF"
      system: "#6b7280"
      tool: "#22c55e"

Trace-Review-Modus rendert eine aufgezeichnete Konversation mit optionalen Token-Zählungen und Latenz pro Nachricht. Annotatoren können einzelne Turns oder die gesamte Konversation bewerten.

Live-Chat-Modus verbindet Annotatoren über das Agent-Proxy-System (siehe unten) mit einem laufenden Agenten. Annotatoren führen eine Konversation mit dem Agenten und annotieren dann das Ergebnis.

4. Coding-Trace-Anzeige

Speziell entwickelt für Sitzungen von Coding-Agenten (Claude Code, Aider, SWE-Agent). Rendert Code-Diffs mit Syntaxhervorhebung, Terminal-Ausgaben in dunklen Blöcken und Datei-Lesevorgänge mit Zeilennummern.

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified           # unified or split
    terminal_theme: dark
    show_file_tree: true
    collapse_long_output: true
    collapse_threshold: 50        # lines
    show_line_numbers: true
    syntax_highlight: true

Funktionen:

• Unified-Diff-Ansicht mit Rot/Grün-Hervorhebung für Bearbeitungsoperationen
• Dunkle Terminal-Blöcke für die Ausgabe von Bash-/Shell-Befehlen
• Code-Blöcke mit Zeilennummern für Datei-Lesevorgänge
• Dateibaum-Seitenleiste mit allen während der Sitzung berührten Dateien
• Einklappbare lange Ausgaben für verbose Terminal- oder Dateiinhalte

Siehe Coding-Agenten-Annotation für die vollständige Referenz.

5. Live-Agent-Anzeige

Echtzeit-Beobachtung von KI-Agenten mit Steuerelementen für menschliches Eingreifen. Unterstützt Web-Browsing-Agenten und Coding-Agenten.

agentic:
  enabled: true
  display_type: live_agent

Funktionen:

• Echtzeit-Streaming der Agenten-Aktionen über Server-Sent Events
• Pausieren/Fortsetzen des Agenten zwischen den Schritten
• Anweisungen senden, um den Agenten mitten in der Aufgabe umzulenken
• Übernehmen der manuellen Steuerung
• Zurücksetzen auf einen beliebigen früheren Checkpoint (Coding-Agenten verwenden git-basierte Checkpoints)
• Verzweigen und erneut abspielen ab einem beliebigen Checkpoint mit anderen Anweisungen

Siehe Live-Agent-Evaluierung und Live-Coding-Agent für Konfigurationsdetails.

Fortgeschrittene Annotationstypen

Über Bewertungen pro Turn und vorgefertigte Schemata hinaus enthält Potato vier zweckgebaute Annotationstypen für die strukturierte Evaluierung von Agenten.

Trajektorienevaluierung (trajectory_eval)

Fehlerlokalisierung pro Schritt mit hierarchischen Fehlertaxonomien und Schweregrad-Bewertung. Jeder Schritt erhält eine Korrektheitsbewertung, einen Fehlertyp, einen Schweregrad und eine optionale Begründung. Ein laufender Punktzähler wird je nach Schweregrad verringert.

annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_eval
    error_taxonomy:
      reasoning:
        - logical_error
        - incorrect_assumption
      action:
        - wrong_tool
        - wrong_arguments
        - premature_termination
    severity_weights:
      minor: -1
      major: -5
      critical: -10

Siehe den Blogbeitrag zur Trajektorienevaluierung für einen vollständigen Leitfaden.

Rubrik-Evaluierung (rubric_eval)

Mehrkriterien-Rasterbewertung im MT-Bench-Stil. Definieren Sie eigene Kriterien und eine Bewertungsskala. Annotatoren bewerten jedes Kriterium unabhängig.

annotation_schemes:
  - annotation_type: rubric_eval
    name: agent_rubric
    criteria:
      - name: correctness
        description: "Did the agent produce the correct result?"
      - name: efficiency
        description: "Did the agent take an efficient path?"
      - name: safety
        description: "Did the agent avoid unsafe actions?"
    scale: 5
    scale_labels:
      1: "Very Poor"
      3: "Acceptable"
      5: "Excellent"

Siehe das Tutorial zur Rubrik-Evaluierung für Einrichtungsanweisungen.

Paarweiser Vergleich

Vergleichen Sie zwei Agenten-Traces nebeneinander mit drei Modi:

• Binär: Klicken Sie, um A oder B auszuwählen (mit optionalem Unentschieden)
• Skala: Schieberegler von "A viel besser" bis "B viel besser"
• Mehrdimensional: unabhängiges A/B/Unentschieden pro Dimension mit erforderlicher Begründung

annotation_schemes:
  - annotation_type: pairwise
    name: agent_comparison
    mode: multi_dimension
    dimensions:
      - correctness
      - efficiency
      - safety
    require_justification: true
    allow_tie: true

Siehe den Leitfaden zum paarweisen Vergleich für alle drei Modi.

Prozessbelohnungsannotation

Binäre Korrektheitsannotation pro Schritt, optimiert für das Training von Prozessbelohnungsmodellen. Zwei Modi: Erster-Fehler (Klick auf den ersten falschen Schritt, der Rest wird automatisch markiert) und Pro-Schritt (jeden Schritt unabhängig bewerten).

annotation_schemes:
  - annotation_type: process_reward
    name: prm
    mode: first_error    # or per_step

Siehe Prozessbelohnungsannotation für die vollständige Referenz.

Bewertungen pro Turn

Für Dialog- und mehrstufige Evaluierungen benötigen Sie häufig Bewertungen für einzelne Turns anstatt (oder zusätzlich zu) dem gesamten Trace. Potato unterstützt Annotationen pro Turn für alle Anzeigetypen.

annotation_schemes:
  # Overall trace rating
  - annotation_type: likert
    name: overall_quality
    description: "Rate the overall quality of this agent trace"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      5: "Excellent"
 
  # Per-turn ratings
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # binds to trace steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: step_explanation
    description: "Explain any issues with this step"
    target: agentic_steps
    rating_type: text
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Bewertungen pro Turn erscheinen neben jeder Schrittkarte. Der conditional-Block ermöglicht die Anzeige von Folgefragen nur bei bestimmten Bewertungen, was die Benutzeroberfläche übersichtlich hält.

Ausgabeformat für Bewertungen pro Turn

Annotationen pro Turn werden mit Schrittindizes gespeichert:

{
  "id": "trace_042",
  "annotations": {
    "overall_quality": 3,
    "step_correctness": {
      "0": "Correct",
      "1": "Correct",
      "2": "Incorrect",
      "3": "Correct"
    },
    "step_explanation": {
      "2": "The agent searched for the wrong product name"
    }
  }
}

Agent-Proxy-System

Für Live-Evaluierungsaufgaben, bei denen Annotatoren in Echtzeit mit einem Agenten interagieren, bietet Potato eine Agent-Proxy-Schicht. Der Proxy sitzt zwischen der Annotationsoberfläche und dem Agenten-Backend und protokolliert die gesamte Konversation zur späteren Überprüfung.

agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http, or echo
 
    # OpenAI proxy
    openai:
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
      system_prompt: "You are a helpful customer service agent."
      temperature: 0.7
      max_tokens: 1024

Proxy-Typen

OpenAI-Proxy leitet Nachrichten an eine OpenAI-kompatible API weiter:

agent_proxy:
  type: openai
  openai:
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
    system_prompt: "You are a helpful assistant."
    temperature: 0.7

HTTP-Proxy leitet Nachrichten an einen beliebigen HTTP-Endpunkt weiter (Ihr eigener Agenten-Server):

agent_proxy:
  type: http
  http:
    url: "https://my-agent.example.com/chat"
    method: POST
    headers:
      Authorization: "Bearer ${AGENT_API_KEY}"
    request_template:
      messages: "{{messages}}"
      session_id: "{{session_id}}"
    response_path: "response.content"
    timeout_seconds: 30

Echo-Proxy spiegelt die Nachricht des Nutzers zurück (nützlich für Tests und UI-Entwicklung):

agent_proxy:
  type: echo
  echo:
    prefix: "[Echo] "
    delay_ms: 500

Vorgefertigte Annotationsschemata

Potato liefert 9 Annotationsschemata, die speziell für die Agentenevaluierung entwickelt wurden. Verwenden Sie sie direkt oder als Ausgangspunkt für eigene Schemata.

Vorgefertigtes Schema nach Name laden:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy

Oder Vorlagen mit eigenen Schemata kombinieren:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Custom schema alongside presets
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations about this agent trace"
    label_requirement:
      required: false

Vollständiges Beispiel: Evaluierung eines ReAct-Agenten

Hier ist eine vollständige Konfiguration zur Evaluierung von ReAct-Agenten-Traces mit Bewertungen pro Schritt:

# project config
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/react_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 300
    show_step_numbers: true
    render_json: true
 
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_efficiency
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Beispiel-Eingabedaten (data/react_traces.jsonl):

{
  "trace_id": "react_001",
  "task_description": "Find the population of Tokyo and compare it to New York City",
  "trace": [
    {"type": "thought", "content": "I need to find the population of both cities. Let me search for Tokyo first."},
    {"type": "action", "content": "search", "action_input": "Tokyo population 2024"},
    {"type": "observation", "content": "Tokyo has a population of approximately 13.96 million in the city proper..."},
    {"type": "thought", "content": "Now I need to find New York City's population."},
    {"type": "action", "content": "search", "action_input": "New York City population 2024"},
    {"type": "observation", "content": "New York City has a population of approximately 8.34 million..."},
    {"type": "thought", "content": "Tokyo (13.96M) has about 67% more people than NYC (8.34M)."},
    {"type": "action", "content": "finish", "action_input": "Tokyo has ~13.96 million people vs NYC's ~8.34 million, making Tokyo about 67% larger by population."}
  ]
}

Server starten:

potato start config.yaml -p 8000

Weiterführende Informationen

• Coding-Agenten-Annotation – Diff-Rendering, Terminal-Ausgaben, Dateibaum für Coding-Agenten
• Prozessbelohnungsannotation – PRM-Trainingsdaten mit Erster-Fehler- und Pro-Schritt-Modus
• Code-Review-Annotation – Inline-Kommentare und Urteile im Stil von GitHub-PRs
• Live-Coding-Agent – Echtzeit-Beobachtung von Coding-Agenten mit Zurücksetzen und Verzweigen
• Live-Agent-Evaluierung – Echtzeit-Beobachtung von Web-Agenten
• Web-Agenten-Annotation – Überprüfung vorab aufgezeichneter Web-Agenten-Traces
• KI-Agenten evaluieren: Ein vollständiger Leitfaden – Walkthrough eines vollständigen Agentenevaluierungsprojekts
• Exportformate – Agentenevaluierungsdaten exportieren

Implementierungsdetails finden Sie in der Quelldokumentation.