Anotación de Agentes de Coding

Anota trazas de agentes de coding con renderizado de diffs, salida de terminal y navegación por el árbol de archivos. Importa desde Claude Code, Aider, SWE-Agent y otros asistentes de programación.

Novedad en la v2.4.0

Los agentes de coding -- Claude Code, Aider, SWE-Agent, OpenHands y otros -- producen trazas distintas a las de los agentes de propósito general. Contienen diffs de código, salida de terminal, lecturas de archivos, recorridos de directorios y resultados de pruebas. Revisar estas trazas requiere un renderizado especializado que entienda la estructura de los cambios de código y los presente en un formato familiar para quien programa.

El CodingTraceDisplay de Potato es un tipo de visualización dedicado a las sesiones de agentes de coding. Renderiza diffs unificados con líneas resaltadas en rojo y verde y coloreado de sintaxis, salida de terminal en bloques oscuros, lecturas de archivos con números de línea, y ofrece una barra lateral con el árbol de archivos que muestra cada archivo que ha tocado el agente. Los anotadores pueden navegar entre archivos, plegar o desplegar salidas largas y valorar operaciones individuales o la traza en conjunto.

Configuración

Activa la visualización de trazas de coding en la configuración de tu proyecto:

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

Funciones de Visualización

Vista de Diff Unificado

Las operaciones de edición se renderizan como diffs unificados con resaltado en rojo y verde. Las líneas eliminadas aparecen con fondo rojo y el prefijo -; las líneas añadidas aparecen con fondo verde y el prefijo +. Las líneas de contexto se muestran en gris neutro. La ruta del archivo y el rango de líneas aparecen en una barra de cabecera sobre cada bloque de diff.

Con diff_style: side_by_side, las versiones antigua y nueva aparecen en columnas contiguas, lo que facilita ver qué ha cambiado en ediciones complicadas.

Bloques Oscuros de Terminal

Los comandos de bash y de shell se renderizan en bloques oscuros de terminal con tipografía monoespaciada. El comando aparece con el prefijo de prompt $ y la salida debajo. Los códigos de salida se muestran en una insignia pequeña (verde para 0, rojo para valores distintos de 0). Las salidas largas se pliegan automáticamente con un desplegable «Show N more lines».

Lecturas de Archivo con Números de Línea

Cuando el agente lee un archivo, el contenido se muestra con números de línea en un bloque de código claro. Las lecturas parciales indican el rango de líneas (por ejemplo, «lines 42-87 of 312»). El resaltado de sintaxis se aplica según la extensión del archivo.

Barra Lateral con el Árbol de Archivos

La barra lateral del árbol de archivos muestra cada archivo que el agente ha tocado durante la traza. Los archivos se agrupan por directorio y se ordenan alfabéticamente. Cada archivo lleva un icono que indica las operaciones realizadas:

Icono de lápiz para archivos editados
Icono de ojo para archivos solo leídos
Icono de más para archivos recién creados
Icono de papelera para archivos eliminados
Icono de terminal para scripts ejecutados

Al pulsar un archivo del árbol, el panel principal se desplaza hasta la primera operación que lo involucra.

Salidas Largas Plegables

Cualquier bloque de salida que supere auto_collapse_threshold se pliega automáticamente. Una línea de resumen muestra las primeras y las últimas líneas con un botón «Show all N lines». Así la traza sigue siendo navegable aunque alguna operación produzca cientos de líneas de salida.

Conversores de Trazas

Potato incluye cuatro conversores específicos para agentes de coding que normalizan los formatos de traza a la representación unificada de traza de coding.

Conversor	Origen	Formato
`claude_code`	Claude Code / API de Anthropic	Messages API con bloques `tool_use` (herramientas Read, Edit, Bash, Write)
`aider`	Aider	Registros de chat en Markdown con bloques de edición SEARCH/REPLACE y ORIGINAL/UPDATED
`swe_agent_trajectory`	SWE-Agent	Archivos JSON de trayectoria con tríos de pensamiento/acción/observación
`auto`	Detección automática	Inspecciona la estructura de la traza y elige el mejor conversor automáticamente

Indica el conversor en tu configuración:

yaml

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

Conversor de Claude Code

El conversor claude_code procesa trazas de la Messages API de Anthropic, donde el uso de herramientas se representa con bloques de contenido tool_use y tool_result. Reconoce las herramientas estándar de Claude Code:

Las llamadas a Read se convierten en visualizaciones de lectura de archivo
Las llamadas a Edit se convierten en diffs unificados
Las llamadas a Write se convierten en visualizaciones de creación de archivo
Las llamadas a Bash se convierten en bloques de terminal
Las llamadas a Glob/Grep se convierten en visualizaciones de resultados de búsqueda

Conversor de Aider

El conversor aider analiza el formato de chat basado en markdown de Aider. Extrae los bloques SEARCH/REPLACE (y el formato antiguo ORIGINAL/UPDATED) y los convierte en diffs unificados. Los comandos de shell y su salida se extraen de los bloques de código delimitados marcados como bash o shell.

Conversor de Trayectorias de SWE-Agent

El conversor swe_agent_trajectory lee los archivos JSON de trayectoria de SWE-Agent. Cada entrada de la trayectoria contiene un pensamiento (el razonamiento del agente), una acción (el comando ejecutado) y una observación (la salida del comando). El conversor clasifica las acciones en ediciones de archivo, lecturas de archivo, comandos de shell y operaciones de navegación.

Uso desde la Línea de Comandos

Convierte las trazas en bruto antes de arrancar el servidor de anotación:

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

La opción -i acepta un único archivo o un directorio. Si le pasas un directorio, se procesan todos los archivos .json y .jsonl. El conversor escribe un objeto JSON por línea en el archivo de salida.

Opciones adicionales:

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

Formato de Datos

Tras la conversión, cada línea del archivo JSONL de salida sigue esta estructura:

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

El array structured_turns conserva el orden exacto de las operaciones. Cada turno tiene un campo type (file_read, edit, terminal, file_write, search, thought) y campos específicos de ese tipo.

Referencia de Configuración

Esta es una configuración completa que combina la visualización de trazas de coding con esquemas de anotación para evaluar la salida de un agente 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"

Ejecutar los Proyectos de Ejemplo

Potato incluye proyectos de ejemplo para la anotación de agentes 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

Cada ejemplo incluye trazas de muestra, un archivo de configuración completo y un README que describe la tarea de anotación.

Véase También

Anotación de Recompensa de Proceso -- recoger señales de recompensa por paso para entrenar PRM
Anotación de Revisión de Código -- revisión en línea al estilo de PR de GitHub para cambios de código
Observación de Agentes de Coding en Vivo -- ver a los agentes de coding e interactuar con ellos en tiempo real
Anotación Agéntica -- anotación de trazas de agente de propósito general
Formatos de Exportación -- exportar datos de anotación para entrenar modelos

Para detalles de implementación, consulta la documentación fuente.