Annotation von Coding-Agenten: Traces aus Claude Code, Aider und SWE-Agent evaluieren

Warum die Annotation von Coding-Agenten wichtig ist

Coding-Agenten wie Claude Code, Aider und SWE-Agent sind schnell gut geworden, und jetzt muss ihre Arbeit tatsächlich bewertet werden. Ein einzelner Durchlauf ist eine unübersichtliche Trajektorie: Codeänderungen, Terminalkommandos, Dateilesevorgänge und Reasoning-Schritte, aneinandergereiht. Um einen besseren Agenten zu trainieren, braucht man menschliches Feedback zu diesen Durchläufen, und die Annotationswerkzeuge, die den meisten Teams zur Verfügung standen, waren nie für solche Daten gebaut.

Eine reine Textannotationsoberfläche kann kein Unified Diff darstellen, keine Terminalausgabe formatieren und mit der verschachtelten Struktur eines Agent-Trace nichts anfangen. Also schreiben Labore ihre eigenen Evaluationsoberflächen, machen dieselbe Arbeit noch einmal und landen bei Datensätzen, die nicht zueinander passen.

Potato beherrscht die Annotation von Coding-Agenten jetzt direkt, mit Darstellungskomponenten für Traces, Annotationsschemata für diese Art von Evaluation und Exporten, die unmittelbar ins Training fließen. Die vollständige Feature-Referenz steht in der Dokumentation zur Annotation von Coding-Agenten und im weiter gefassten Leitfaden zur Agent-Evaluation.

CodingTraceDisplay: ein Trace-Viewer

Der größte Teil der Annotationserfahrung läuft über die Komponente CodingTraceDisplay. Sie stellt jeden Schritt der Trajektorie eines Agenten mit der Visualisierung dar, die zum jeweiligen Schritttyp passt.

So sieht die Oberfläche für die Annotation von Coding-Agenten in Potato aus:

Die CodingTraceDisplay stellt Code-Diffs, Terminalausgabe und Dateilesevorgänge sauber formatiert dar

Unified-Diff-Ansicht

Codeänderungen werden als Unified Diffs mit roter und grüner Hervorhebung für entfernte und hinzugefügte Zeilen dargestellt. Die Diff-Ansicht enthält Zeilennummern, Kopfzeilen mit Dateipfad und Kontextzeilen rund um die Änderungen. Das entspricht der vertrauten Ansicht eines GitHub-Pull-Requests, die die meisten Entwickler ohnehin kennen.

# The diff rendering is automatic when your trace data includes tool_use
# steps with file edit operations. No special config is needed.
coding_agent:
  display:
    diff_style: "unified"         # "unified" or "split" side-by-side
    context_lines: 3              # Lines of context around changes
    syntax_highlighting: true     # Language-aware highlighting
    collapse_large_diffs: true    # Auto-collapse diffs > 100 lines
    large_diff_threshold: 100

Dunkle Terminalblöcke

Bash-Kommandos und ihre Ausgaben erscheinen in dunklen Terminalblöcken mit Monospace-Schrift, ANSI-Farbunterstützung und scrollbarer Ausgabe bei langen Ergebnissen. Die Terminalblöcke zeigen das ausgeführte Kommando, das Arbeitsverzeichnis und den Exit-Code.

coding_agent:
  display:
    terminal_theme: "dark"        # "dark" or "light"
    max_terminal_height: 400      # pixels, scrollable beyond this
    show_exit_codes: true
    show_working_directory: true
    ansi_colors: true             # Render ANSI escape sequences

Codeblöcke mit Zeilennummern

Dateilesevorgänge werden als syntaxhervorgehobene Codeblöcke mit Zeilennummern dargestellt. Liest der Agent nur einen bestimmten Zeilenbereich, werden auch nur diese Zeilen gezeigt, mit den ursprünglichen Zeilennummern, sodass sich der Abgleich mit der tatsächlichen Datei leicht machen lässt.

Dateibaum in der Seitenleiste

Eine einklappbare Seitenleiste zeigt alle Dateien, die im Lauf der Trajektorie angefasst wurden, als Baumstruktur. Ein Symbol an jeder Datei zeigt an, ob sie angelegt, geändert, gelesen oder gelöscht wurde. Ein Klick auf eine Datei im Baum scrollt zu ihrem ersten Auftreten im Trace.

coding_agent:
  display:
    file_tree:
      enabled: true
      position: "left"            # "left" or "right"
      show_change_icons: true     # Icons for created/modified/deleted
      group_by: "directory"       # "directory" or "chronological"

Einklappbare Ausgaben

Lange Ausgaben lassen sich bei jedem Schritttyp einklappen, damit der Trace lesbar bleibt. Annotatoren können einzelne Schritte nach Bedarf aufklappen oder die Schaltflächen „Expand All" und „Collapse All" verwenden. Die Thinking- und Reasoning-Blöcke der Agenten sind standardmäßig eingeklappt, stehen aber zur Durchsicht bereit.

coding_agent:
  display:
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
      long_output_threshold: 50   # lines
      default_expanded_types:     # These step types start expanded
        - "file_edit"
        - "bash_command"

Das Schema für Process Reward Models (PRM)

Process Reward Models vergeben Kredit auf Schrittebene, statt nur das Endergebnis zu bewerten. Potato unterstützt zwei PRM-Annotationsmodi, die auf unterschiedliche Abwägungen zwischen Tempo und Genauigkeit ausgelegt sind.

First-Error-Modus

Im First-Error-Modus scrollt der Annotator durch die Trajektorie und klickt auf den ersten Schritt, an dem der Agent danebenliegt. Alle Schritte davor werden automatisch als korrekt markiert, alle Schritte danach (einschließlich des angeklickten) automatisch als inkorrekt. Das beschleunigt die Annotation erheblich, weil der Annotator nur einen einzigen Punkt bestimmen muss.

annotation_schemes:
  - annotation_type: process_reward
    name: prm_first_error
    mode: "first_error"
    description: "Click the first step where the agent makes an error"

Modus pro Schritt

Im Modus pro Schritt bekommt jeder Schritt eine eigene Bewertung. Das liefert detailliertere Trainingsdaten, dauert pro Trace aber länger. Annotatoren bewerten jeden Schritt als korrekt, inkorrekt oder teilweise korrekt.

annotation_schemes:
  - annotation_type: process_reward
    name: prm_per_step
    mode: "per_step"

Das Code-Review-Schema

Die Code-Review-Oberfläche bietet Annotationselemente im Stil eines GitHub-Pull-Requests:

Annotatoren können Diff-Zeilen anklicken, um Inline-Kommentare zu hinterlassen, Dateien zu bewerten und ein Urteil zu Annahme oder Ablehnung abzugeben

Das Code-Review-Schema bringt die Annotation im Stil eines GitHub-Pull-Requests zu Agent-Traces. Annotatoren können Inline-Kommentare an bestimmten Zeilen innerhalb von Diffs hinterlassen, einzelne Dateien bewerten und ein Gesamturteil abgeben.

annotation_schemes:
  - annotation_type: code_review
    name: agent_review
    comment_categories:
      enabled: true
      categories:                 # Optional categorization for comments
        - "Bug"
        - "Style"
        - "Logic Error"
        - "Unnecessary Change"
        - "Missing Error Handling"
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
      labels: ["Poor", "Below Average", "Acceptable", "Good", "Excellent"]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
          description: "Changes are correct and complete"
        - value: "request_changes"
          text: "Request Changes"
          description: "Changes need fixes before merging"
        - value: "comment"
          text: "Comment"
          description: "General feedback, no strong opinion"

Trace-Konverter: Import aus jedem Agenten

Potato bringt Konverter für die drei verbreitetsten Formate von Coding-Agenten mit. Die Konverter überführen jedes Format in Potatos interne strukturierte Trace-Darstellung.

Claude Code (Anthropic Messages API)

Traces aus Claude Code nutzen das Format der Anthropic Messages API mit tool_use- und tool_result-Inhaltsblöcken. Der Konverter zieht Dateiänderungen, Bash-Kommandos und Dateilesevorgänge aus den Tool-Aufrufen und erhält den Reasoning-Text des Assistenten.

# Convert Claude Code traces to Potato format
potato convert-traces \
  --format claude_code \
  --input ./claude_traces/ \
  --output ./potato_data/traces.jsonl

Aider (Markdown-Chat mit Edit-Blöcken)

Aider erzeugt Chat-Logs in Markdown mit SEARCH/REPLACE-Blöcken für Änderungen. Der Konverter parst diese Blöcke, um Dateiänderungen zu rekonstruieren, und zieht Shell-Kommandos aus den Codeblöcken.

# Convert Aider chat logs
potato convert-traces \
  --format aider \
  --input ./aider_logs/ \
  --output ./potato_data/traces.jsonl

SWE-Agent (Thought/Action/Observation)

SWE-Agent arbeitet in einer Schleife aus Thought, Action und Observation. Der Konverter bildet Aktionen auf die passenden Schritttypen ab (Edit, Bash, Read) und erhält die Chain-of-Thought-Überlegungen des Agenten als einklappbare Thinking-Blöcke.

# Convert SWE-Agent trajectories
potato convert-traces \
  --format swe_agent \
  --input ./swe_agent_trajectories/ \
  --output ./potato_data/traces.jsonl

Automatische Erkennung

Wer Traces von mehreren Agenten hat, kann Potato das Format anhand der Struktur jeder Datei selbst erkennen lassen:

# Auto-detect format for mixed trace directories
potato convert-traces \
  --format auto \
  --input ./mixed_traces/ \
  --output ./potato_data/traces.jsonl

Exporte für die Trainingspipeline

Annotierte Traces lassen sich in Formaten exportieren, die direkt fürs Modelltraining taugen.

PRM-Format

Reward-Labels auf Schrittebene für das Training von Process Reward Models:

# Exported PRM format (one line per trace)
{
  "trace_id": "trace_001",
  "steps": [
    {"step_idx": 0, "content": "Read file src/main.py", "label": "correct"},
    {"step_idx": 1, "content": "Edit src/main.py: fix import", "label": "correct"},
    {"step_idx": 2, "content": "Run tests", "label": "correct"},
    {"step_idx": 3, "content": "Edit src/utils.py: wrong fix", "label": "incorrect"},
    {"step_idx": 4, "content": "Run tests again", "label": "incorrect"}
  ],
  "first_error_step": 3
}

Präferenzpaare für DPO/RLHF

In Kombination mit paarweisen Vergleichsannotationen erzeugt Potato Präferenzpaare, die sich für Direct Preference Optimization oder RLHF-Training eignen:

# Exported preference pair format
{
  "prompt": "Fix the failing test in src/test_utils.py",
  "chosen": {"trace_id": "trace_001", "steps": [...]},
  "rejected": {"trace_id": "trace_002", "steps": [...]},
  "preference_strength": 0.85
}

SWE-bench-kompatible Ergebnisse

Annotationen lassen sich in einem Format exportieren, das mit dem SWE-bench-Evaluations-Harness kompatibel ist, für den direkten Vergleich mit veröffentlichten Benchmarks:

# Export to SWE-bench format
potato export \
  --format swe_bench \
  --project ./my_project/ \
  --output ./swe_bench_results.json

Schnelleinstieg

Von null bis zum laufenden Annotationsserver sind es etwa fünf Minuten.

Installation

pip install potato-annotation[coding-agents]

Traces konvertieren

# Convert traces from your coding agent
potato convert-traces \
  --format auto \
  --input ./my_agent_traces/ \
  --output ./data/traces.jsonl

Konfiguration anlegen

Hier eine vollständige Konfiguration für ein Evaluationsprojekt zu Coding-Agenten, das sowohl das PRM- als auch das Code-Review-Schema verwendet:

# config.yaml
project_name: "Coding Agent Evaluation"
port: 8000
 
data:
  source: "local"
  input_path: "./data/traces.jsonl"
  data_format: "coding_trace"
 
coding_agent:
  display:
    diff_style: "unified"
    context_lines: 3
    syntax_highlighting: true
    collapse_large_diffs: true
    terminal_theme: "dark"
    max_terminal_height: 400
    show_exit_codes: true
    file_tree:
      enabled: true
      position: "left"
      show_change_icons: true
    collapsible:
      auto_collapse_thinking: true
      auto_collapse_long_output: true
 
annotation_schemes:
  - annotation_type: process_reward
    name: prm_evaluation
    mode: "first_error"
    description: "Click the first step where the agent makes a mistake"
 
  - annotation_type: code_review
    name: code_quality
    comment_categories:
      enabled: true
      categories: ["Bug", "Logic Error", "Style", "Missing Error Handling"]
    file_rating_dimensions:
      enabled: true
      scale: [1, 2, 3, 4, 5]
    verdict_options:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
        - value: "request_changes"
          text: "Request Changes"
        - value: "comment"
          text: "Comment"
 
  - annotation_type: text
    name: overall_notes
    description: "Additional Notes"
    placeholder: "Any other observations about this trace..."
output:
  path: "./output/"
  format: "jsonl"
  export_formats:
    - "prm"
    - "swe_bench"
 
quality_control:
  inter_annotator_agreement: true
  overlap_percentage: 20
  minimum_time_per_instance: 30  # seconds
 
annotators:
  - username: "annotator1"
  - username: "annotator2"

Server starten

potato start config.yaml -p 8000

Dann http://localhost:8000 im Browser öffnen, anmelden und mit dem Annotieren beginnen. Diff-Darstellung, Terminalausgabe und Process-Reward-Annotation stehen dabei wie oben beschrieben zur Verfügung.

Wie es weitergeht

Das ist ein erstes Release, und einiges steht noch aus. Auf der Liste: Unterstützung für weitere Agentenformate, eine bessere Visualisierung für Refactorings über mehrere Dateien und eine engere Anbindung an Trainings-Frameworks wie OpenRLHF und TRL.

Wer einen neuen Trace-Konverter, ein Schema oder ein Exportformat schreibt, dessen Beitrag nehmen wir gern. Und wenn ein Team Coding-Agenten evaluiert und auf etwas stößt, das dieses Setup nicht abdeckt, freuen wir uns über ein Issue in unserem GitHub-Repository.