Arriva l'annotazione dei coding agent: valuta le tracce di Claude Code, Aider e SWE-Agent

Perché serve annotare i coding agent

I coding agent come Claude Code, Aider e SWE-Agent sono diventati bravi in fretta, e ora c'è davvero bisogno di dare un voto al loro lavoro. Una singola esecuzione è una traiettoria disordinata: modifiche al codice, comandi da terminale, letture di file e passi di ragionamento infilati uno dietro l'altro. Per addestrare un agente migliore serve il giudizio umano su quelle esecuzioni, e gli strumenti di annotazione che la maggior parte dei team aveva a disposizione non erano stati pensati per dati di questo tipo.

Un'interfaccia di annotazione a solo testo non sa renderizzare un diff unificato, formattare l'output del terminale o gestire la struttura annidata di una traccia di agente. Così i laboratori finiscono per scriversi le proprie interfacce di valutazione, rifacendo ogni volta lo stesso lavoro e ritrovandosi con dataset che non si parlano tra loro.

Potato ora gestisce direttamente l'annotazione dei coding agent, con componenti di rendering pensati per le tracce, schemi di annotazione adatti a questo tipo di valutazione ed esportazioni che entrano subito nell'addestramento. Per il riferimento completo della funzionalità, vedi la documentazione sull'annotazione dei coding agent e la più ampia guida alla valutazione degli agenti.

CodingTraceDisplay: un visualizzatore di tracce

Quasi tutta l'esperienza di annotazione passa dal componente CodingTraceDisplay. Renderizza ogni passo della traiettoria di un agente usando la visualizzazione più adatta a quel tipo di passo.

Ecco come si presenta in Potato l'interfaccia di annotazione dei coding agent:

Il CodingTraceDisplay renderizza diff del codice, output del terminale e letture di file con la formattazione giusta

Vista a diff unificato

Le modifiche al codice vengono renderizzate come diff unificati, con evidenziazione in rosso e verde per le righe rimosse e aggiunte. La vista dei diff comprende numeri di riga, intestazioni con il percorso del file e righe di contesto attorno alle modifiche. È la stessa esperienza delle pull request di GitHub, che la maggior parte degli sviluppatori conosce già.

# 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

Blocchi di terminale scuri

I comandi bash e il loro output vengono renderizzati in blocchi di terminale scuri, con carattere monospaziato, supporto ai colori ANSI e output scorrevole per i risultati lunghi. I blocchi di terminale mostrano il comando eseguito, la directory di lavoro e l'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

Blocchi di codice con numeri di riga

Le letture di file vengono mostrate come blocchi di codice con evidenziazione della sintassi e numeri di riga. Quando l'agente legge un intervallo specifico di righe, vengono mostrate solo quelle, con i numeri di riga originali conservati, così è facile riscontrarle nel file vero.

Sidebar con l'albero dei file

Una sidebar richiudibile mostra tutti i file toccati durante la traiettoria, organizzati in una struttura ad albero. Ogni file ha un'icona che indica se è stato creato, modificato, letto o cancellato. Cliccando un file nell'albero si scorre fino alla sua prima comparsa nella traccia.

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"

Output richiudibili

Gli output lunghi di qualsiasi tipo di passo possono essere richiusi per tenere la traccia leggibile. Gli annotatori possono espandere i singoli passi all'occorrenza, oppure usare i controlli «Expand All» e «Collapse All». I blocchi di ragionamento degli agenti sono richiusi per impostazione predefinita, ma restano consultabili.

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"

Schema per i process reward model (PRM)

I process reward model assegnano il merito a livello di passo, invece di valutare solo l'esito finale. Potato supporta due modalità di annotazione PRM pensate per compromessi diversi tra velocità e accuratezza.

Modalità primo errore

Nella modalità primo errore l'annotatore scorre la traiettoria e clicca sul primo passo in cui l'agente sbaglia. Tutti i passi precedenti a quello cliccato vengono segnati in automatico come corretti, e tutti quelli successivi (compreso il passo cliccato) come sbagliati. L'annotazione ne guadagna molto in velocità, visto che l'annotatore deve individuare un solo punto.

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

Modalità passo per passo

Nella modalità passo per passo ogni passo riceve una valutazione indipendente. Ne escono dati di addestramento più dettagliati, ma serve più tempo per traccia. Gli annotatori valutano ogni passo come corretto, sbagliato o parzialmente corretto.

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

Schema di code review

L'interfaccia di code review offre controlli di annotazione in stile pull request di GitHub:

Gli annotatori possono cliccare sulle righe del diff per aggiungere commenti inline, valutare i file e dare un verdetto di approvazione o rifiuto

Lo schema di code review porta l'annotazione in stile pull request di GitHub sulle tracce degli agenti. Gli annotatori possono lasciare commenti inline su righe specifiche dei diff, valutare i singoli file e dare un verdetto complessivo.

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"

Convertitori di tracce: importa da qualsiasi agente

Potato include convertitori integrati per i tre formati di coding agent più diffusi. I convertitori normalizzano ciascun formato nella rappresentazione strutturata interna delle tracce di Potato.

Claude Code (Anthropic Messages API)

Le tracce di Claude Code usano il formato dell'Anthropic Messages API con blocchi di contenuto tool_use e tool_result. Il convertitore estrae dalle chiamate agli strumenti le modifiche ai file, i comandi bash e le letture di file, e conserva il testo del ragionamento dell'assistente.

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

Aider (chat in markdown con blocchi di modifica)

Aider produce log di chat formattati in markdown con blocchi di modifica SEARCH/REPLACE. Il convertitore analizza quei blocchi per ricostruire le modifiche ai file ed estrae i comandi di shell dai blocchi di codice delimitati.

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

SWE-Agent (pensiero/azione/osservazione)

SWE-Agent usa un formato a ciclo pensiero/azione/osservazione. Il convertitore mappa le azioni sui tipi di passo corrispondenti (modifica, bash, lettura) e conserva la catena di ragionamento dell'agente come blocchi richiudibili.

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

Rilevamento automatico

Se hai tracce provenienti da agenti diversi, Potato può rilevare il formato in automatico dalla struttura di ogni file:

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

Esportazioni per la pipeline di addestramento

Le tracce annotate possono essere esportate in formati pronti per l'addestramento dei modelli.

Formato PRM

Etichette di reward a livello di passo per addestrare i process reward model:

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

Coppie di preferenza DPO/RLHF

Se le combini con annotazioni di confronto a coppie, Potato genera coppie di preferenza adatte all'addestramento con Direct Preference Optimization o RLHF:

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

Risultati compatibili con SWE-bench

Esporta le annotazioni in un formato compatibile con l'harness di valutazione di SWE-bench, per il confronto diretto con i benchmark pubblicati:

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

Quick start

Passare da zero a un server di annotazione funzionante richiede circa cinque minuti.

Installazione

pip install potato-annotation[coding-agents]

Converti le tue tracce

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

Crea la configurazione

Ecco una configurazione completa per un progetto di valutazione di coding agent che usa sia lo schema PRM sia quello di code review:

# 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"

Avvia il server

potato start config.yaml -p 8000

Apri http://localhost:8000 nel browser, accedi e comincia ad annotare. Hai a disposizione il rendering completo dei diff, l'output del terminale e l'annotazione di process reward descritti qui sopra.

Che cosa arriva dopo

Questa è una prima release, e c'è dell'altro che vogliamo fare. In lista: il supporto ad altri formati di agente, una visualizzazione migliore per i refactoring su più file e un'integrazione più stretta con framework di addestramento come OpenRLHF e TRL.

Se scrivi un nuovo convertitore di tracce, uno schema o un formato di esportazione, il contributo è benvenuto. E se il tuo team sta valutando coding agent e incappa in qualcosa che questa configurazione non copre, apri una issue sul nostro repository GitHub.