Annotation d'agent de coding

Annotez des traces d'agents de coding avec rendu des diffs, sortie du terminal et navigation dans l'arborescence de fichiers. Importez depuis Claude Code, Aider, SWE-Agent et d'autres assistants de coding.

Nouveau dans la v2.4.0

Les agents de coding -- Claude Code, Aider, SWE-Agent, OpenHands et les autres -- produisent des traces qui diffèrent de celles des agents généralistes. On y trouve des diffs de code, des sorties de terminal, des lectures de fichiers, des parcours de répertoires et des résultats de tests. Relire ces traces demande un rendu spécialisé, qui comprenne la structure des modifications de code et les présente dans un format familier aux développeurs.

Le CodingTraceDisplay de Potato est un type d'affichage dédié aux sessions d'agents de coding. Il affiche les diffs unifiés avec des lignes rouges/vertes colorées syntaxiquement, la sortie du terminal en blocs sombres, les lectures de fichiers avec numéros de ligne, et propose une barre latérale d'arborescence qui montre chaque fichier touché par l'agent. Les annotateurs peuvent naviguer entre les fichiers, déplier ou replier les longues sorties, et noter les opérations une à une ou la trace dans son ensemble.

Configuration

Activez l'affichage de traces de coding dans la configuration de votre projet :

yaml

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    # Diff rendering
    diff_style: unified          # "unified" or "side_by_side"
    diff_context_lines: 3        # lines of context around changes
    syntax_highlight: true       # language-aware highlighting
    show_line_numbers: true
 
    # Terminal output
    terminal_theme: dark         # "dark" or "light"
    terminal_max_lines: 80       # auto-collapse after this many lines
    show_exit_codes: true
 
    # File reads
    file_read_max_lines: 100     # auto-collapse file reads longer than this
    show_file_path: true
    show_line_range: true        # display "lines 42-87" when partial reads
 
    # File tree sidebar
    file_tree:
      enabled: true
      position: left             # "left" or "right"
      show_operation_icons: true # icons for read/edit/create/delete
      group_by_directory: true
      click_to_navigate: true    # click a file to jump to its operations
 
    # Collapsible sections
    auto_collapse_threshold: 500 # characters before auto-collapsing
    collapse_file_reads: true
    collapse_terminal_output: true

Fonctions d'affichage

Vue de diff unifié

Les opérations d'édition sont affichées en diffs unifiés avec surlignage rouge/vert. Les lignes supprimées ont un fond rouge et un préfixe - ; les lignes ajoutées ont un fond vert et un préfixe +. Les lignes de contexte apparaissent en gris neutre. Le chemin du fichier et la plage de lignes s'affichent dans une barre d'en-tête au-dessus de chaque bloc de diff.

Avec diff_style: side_by_side, l'ancienne et la nouvelle version apparaissent dans deux colonnes voisines, ce qui aide à voir ce qui a changé dans les modifications complexes.

Blocs de terminal sombres

Les commandes bash et shell sont affichées en blocs de terminal sombres, en police à chasse fixe. La commande elle-même apparaît avec un préfixe d'invite $, et la sortie s'affiche en dessous. Les codes de retour sont indiqués dans un petit badge (vert pour 0, rouge sinon). Les sorties longues sont repliées automatiquement, avec un bouton « Show N more lines » pour les déplier.

Lectures de fichiers numérotées

Quand l'agent lit un fichier, le contenu est affiché avec les numéros de ligne dans un bloc de code clair. Les lectures partielles indiquent la plage de lignes (par exemple « lines 42-87 of 312 »). La coloration syntaxique est appliquée selon l'extension du fichier.

Barre latérale d'arborescence

L'arborescence latérale montre chaque fichier touché par l'agent au cours de la trace. Les fichiers sont regroupés par répertoire et triés par ordre alphabétique. Chaque fichier porte une icône indiquant les opérations effectuées :

Crayon pour les fichiers modifiés
Œil pour les fichiers lus seulement
Plus pour les fichiers créés
Corbeille pour les fichiers supprimés
Terminal pour les scripts exécutés

Cliquer sur un fichier dans l'arborescence fait défiler le panneau principal jusqu'à la première opération concernant ce fichier.

Repliement des longues sorties

Tout bloc de sortie qui dépasse auto_collapse_threshold est replié automatiquement. Une ligne de résumé montre les premières et les dernières lignes, avec un bouton « Show all N lines ». La trace reste ainsi navigable même quand une opération produit des centaines de lignes de sortie.

Convertisseurs de traces

Potato livre quatre convertisseurs propres aux agents de coding, qui normalisent les formats de traces vers la représentation unifiée des traces de coding.

Convertisseur	Source	Format
`claude_code`	Claude Code / API Anthropic	API Messages avec blocs `tool_use` (outils Read, Edit, Bash, Write)
`aider`	Aider	Journaux de chat en Markdown avec blocs d'édition SEARCH/REPLACE et ORIGINAL/UPDATED
`swe_agent_trajectory`	SWE-Agent	Fichiers JSON de trajectoire avec triplets pensée/action/observation
`auto`	Détection automatique	Inspecte la structure de la trace et choisit le meilleur convertisseur

Indiquez le convertisseur dans votre configuration :

yaml

agentic:
  trace_converter: claude_code    # or aider, swe_agent_trajectory, auto

Convertisseur Claude Code

Le convertisseur claude_code traite les traces de l'API Messages d'Anthropic, où l'usage d'outils est représenté par des blocs de contenu tool_use et tool_result. Il reconnaît les outils standard de Claude Code :

Les appels à Read deviennent des affichages de lecture de fichier
Les appels à Edit deviennent des diffs unifiés
Les appels à Write deviennent des affichages de création de fichier
Les appels à Bash deviennent des blocs de terminal
Les appels à Glob/Grep deviennent des affichages de résultats de recherche

Convertisseur Aider

Le convertisseur aider analyse le format de chat en Markdown d'Aider. Il extrait les blocs SEARCH/REPLACE (ainsi que l'ancien format ORIGINAL/UPDATED) et les convertit en diffs unifiés. Les commandes shell et leur sortie sont extraites des blocs de code délimités marqués bash ou shell.

Convertisseur de trajectoires SWE-Agent

Le convertisseur swe_agent_trajectory lit les fichiers JSON de trajectoire de SWE-Agent. Chaque entrée de trajectoire contient une pensée (le raisonnement de l'agent), une action (la commande exécutée) et une observation (la sortie de la commande). Le convertisseur classe les actions en modifications de fichiers, lectures de fichiers, commandes shell et opérations de navigation.

Utilisation en ligne de commande

Convertissez les traces brutes avant de démarrer le serveur d'annotation :

bash

# Convert Claude Code traces
python -m potato.trace_converter \
  -i traces.json \
  -f claude_code \
  -o data/converted.jsonl
 
# Convert Aider chat logs
python -m potato.trace_converter \
  -i aider_chat_history/ \
  -f aider \
  -o data/aider_converted.jsonl
 
# Convert SWE-Agent trajectories
python -m potato.trace_converter \
  -i trajectories/ \
  -f swe_agent_trajectory \
  -o data/swe_converted.jsonl
 
# Auto-detect format
python -m potato.trace_converter \
  -i mixed_traces/ \
  -f auto \
  -o data/auto_converted.jsonl

L'option -i accepte un fichier unique ou un répertoire. Quand un répertoire est indiqué, tous les fichiers .json et .jsonl sont traités. Le convertisseur écrit un objet JSON par ligne dans le fichier de sortie.

Autres options :

bash

# Filter by file extension
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --include "*.json"
 
# Add metadata fields from a CSV
python -m potato.trace_converter \
  -i traces/ -f claude_code -o data/out.jsonl \
  --metadata metadata.csv --join-key trace_id
 
# Validate output without writing
python -m potato.trace_converter \
  -i traces.json -f claude_code --validate

Format des données

Après conversion, chaque ligne du fichier JSONL de sortie suit cette structure :

json

{
  "id": "trace_001",
  "task_description": "Fix the failing test in test_parser.py",
  "repository": "myproject",
  "structured_turns": [
    {
      "type": "file_read",
      "tool": "Read",
      "file_path": "src/parser.py",
      "content": "def parse(input_str):\n    tokens = tokenize(input_str)\n    ...",
      "line_start": 1,
      "line_end": 45
    },
    {
      "type": "edit",
      "tool": "Edit",
      "file_path": "src/parser.py",
      "old_content": "    if len(tokens) == 0:\n        return None",
      "new_content": "    if len(tokens) == 0:\n        raise ParseError('Empty input')",
      "line_start": 12,
      "line_end": 13
    },
    {
      "type": "terminal",
      "tool": "Bash",
      "command": "python -m pytest test_parser.py -v",
      "output": "test_parser.py::test_empty_input PASSED\ntest_parser.py::test_valid_input PASSED\n\n2 passed in 0.34s",
      "exit_code": 0
    },
    {
      "type": "file_write",
      "tool": "Write",
      "file_path": "src/parser.py",
      "content": "...",
      "is_new_file": false
    }
  ],
  "metadata": {
    "agent": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "total_tokens": 15234,
    "duration_seconds": 42
  }
}

Le tableau structured_turns conserve l'ordre exact des opérations. Chaque tour a un champ type (file_read, edit, terminal, file_write, search, thought) et des champs propres à ce type.

Référence de configuration

Voici une configuration complète qui associe l'affichage de traces de coding à des schémas d'annotation pour évaluer la sortie d'un agent de coding :

yaml

task_name: "Coding Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/coding_traces.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    terminal_max_lines: 80
    show_exit_codes: true
    file_read_max_lines: 100
    file_tree:
      enabled: true
      position: left
      show_operation_icons: true
      group_by_directory: true
      click_to_navigate: true
    auto_collapse_threshold: 500
 
annotation_schemes:
  # Did the agent complete the task?
  - annotation_type: radio
    name: task_completion
    description: "Did the agent successfully complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
      - "Made Things Worse"
 
  # Per-step correctness
  - annotation_type: per_turn_rating
    name: step_quality
    description: "Rate this step"
    target: agentic_steps
    rating_type: radio
    labels:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Code quality rating
  - annotation_type: likert
    name: code_quality
    description: "Rate the quality of the code changes"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      2: "Poor"
      3: "Acceptable"
      4: "Good"
      5: "Excellent"
 
  # Free-text notes
  - annotation_type: text
    name: notes
    description: "Any additional observations about the coding trace"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Lancer les projets d'exemple

Potato fournit des projets d'exemple pour l'annotation d'agents de coding :

bash

# Clone the repository
git clone https://github.com/davidjurgens/potato.git
cd potato
 
# Run the Claude Code trace evaluation example
potato start example/coding_agent_eval/config.yaml -p 8000
 
# Run the SWE-bench evaluation example
potato start example/swe_bench_eval/config.yaml -p 8000
 
# Run the multi-agent comparison example
potato start example/coding_agent_comparison/config.yaml -p 8000

Chaque exemple contient des traces d'échantillon, un fichier de configuration complet et un README décrivant la tâche d'annotation.

Voir aussi

Annotation de récompense de processus -- recueillir des signaux de récompense par étape pour l'entraînement de PRM
Annotation de revue de code -- revue en ligne de style PR GitHub pour les modifications de code
Observation d'un agent de coding en direct -- regarder des agents de coding travailler et interagir avec eux en temps réel
Annotation agentique -- annotation généraliste de traces d'agents
Formats d'exportation -- exporter les données d'annotation pour l'entraînement de modèles

Pour les détails d'implémentation, consultez la documentation source.