Name: Potato
Author: Potato

Por qué importa anotar agentes de coding

Los agentes de coding como Claude Code, Aider y SWE-Agent han mejorado rápido, y ahora hace falta poder calificar su trabajo. Una sola ejecución es una trayectoria desordenada: ediciones de código, comandos de terminal, lecturas de archivos y pasos de razonamiento encadenados. Para entrenar un agente mejor necesitas realimentación humana sobre esas ejecuciones, y las herramientas de anotación con las que contaba la mayoría de equipos nunca se pensaron para este tipo de datos.

Una interfaz de anotación de texto plano no puede renderizar un diff unificado, dar formato a la salida de terminal ni manejar la estructura anidada de la traza de un agente. Así que los laboratorios acaban escribiendo sus propias interfaces de evaluación, repitiendo el mismo trabajo y quedándose con conjuntos de datos que no se entienden entre sí.

Potato ahora gestiona la anotación de agentes de coding directamente, con componentes de renderizado pensados para trazas, esquemas de anotación para este tipo de evaluación y exportaciones que alimentan el entrenamiento sin pasos intermedios. Para la referencia completa de la funcionalidad, consulta la documentación de anotación de agentes de coding y la guía general de evaluación de agentes.

CodingTraceDisplay: un visor de trazas

Casi toda la experiencia de anotación pasa por el componente CodingTraceDisplay, que renderiza cada paso de la trayectoria del agente con la visualización que corresponde a ese tipo de paso.

Así se ve la interfaz de anotación de agentes de coding en Potato:

Coding agent trace display showing diff rendering and file tree El CodingTraceDisplay renderiza diffs de código, salida de terminal y lecturas de archivos con el formato adecuado

Vista de diff unificado

Las ediciones de código se renderizan como diffs unificados con resaltado en rojo y verde para las líneas eliminadas y añadidas. La vista de diff incluye números de línea, cabeceras con la ruta del archivo y líneas de contexto alrededor de los cambios. Reproduce la experiencia conocida de los pull requests de GitHub, que casi todos los desarrolladores ya manejan.

yaml

# 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

Bloques oscuros de terminal

Los comandos de bash y su salida se renderizan en bloques oscuros de terminal con tipografía monoespaciada, soporte de colores ANSI y salida desplazable para resultados largos. Los bloques de terminal muestran el comando ejecutado, el directorio de trabajo y el código de salida.

yaml

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

Bloques de código con números de línea

Las lecturas de archivos se muestran como bloques de código con resaltado de sintaxis y números de línea. Cuando el agente lee un rango concreto de líneas, solo se muestran esas líneas conservando su numeración original, lo que facilita cotejarlas con el archivo real.

Barra lateral con árbol de archivos

Una barra lateral plegable muestra todos los archivos tocados durante la trayectoria, organizados en árbol. Cada archivo lleva un icono que indica si se creó, modificó, leyó o borró. Al hacer clic en un archivo del árbol, la vista se desplaza a su primera aparición en la traza.

yaml

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"

Salidas plegables

Las salidas largas de cualquier tipo de paso pueden plegarse para que la traza siga siendo legible. Los anotadores pueden desplegar pasos concretos cuando lo necesiten o usar los controles «Expand All» / «Collapse All». Los bloques de razonamiento del agente vienen plegados por defecto, pero quedan disponibles para revisarlos.

yaml

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"

Esquema de modelo de recompensa de proceso (PRM)

Los modelos de recompensa de proceso asignan crédito a nivel de paso en lugar de evaluar solo el resultado final. Potato admite dos modos de anotación PRM pensados para distintos equilibrios entre velocidad y precisión.

Modo de primer error

En el modo de primer error, el anotador recorre la trayectoria y hace clic en el primer paso en el que el agente se equivoca. Todos los pasos anteriores al clic se marcan automáticamente como correctos, y todos los posteriores (incluido el paso señalado) se marcan como incorrectos. Esto acelera mucho la anotación, porque el anotador solo tiene que identificar un punto.

yaml

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

Modo por paso

En el modo por paso, cada paso recibe una valoración independiente. Produce datos de entrenamiento más detallados, pero lleva más tiempo por traza. Los anotadores califican cada paso como correcto, incorrecto o parcialmente correcto.

yaml

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

Esquema de revisión de código

La interfaz de revisión de código ofrece controles de anotación al estilo de los PR de GitHub:

Code review annotation with inline diff comments Los anotadores pueden hacer clic en las líneas del diff para añadir comentarios en línea, valorar archivos y emitir un veredicto de aprobación o rechazo

El esquema de revisión de código lleva la anotación al estilo de los PR de GitHub a las trazas de agente. Los anotadores pueden dejar comentarios en línea sobre líneas concretas de los diffs, valorar archivos individuales y dar un veredicto global.

yaml

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"

Conversores de trazas: importa desde cualquier agente

Potato incluye conversores para los tres formatos de agente de coding más extendidos. Los conversores normalizan cada formato a la representación interna de trazas estructuradas de Potato.

Claude Code (API de mensajes de Anthropic)

Las trazas de Claude Code usan el formato de la API de mensajes de Anthropic, con bloques de contenido tool_use y tool_result. El conversor extrae de las llamadas a herramientas las ediciones de archivos, los comandos de bash y las lecturas de archivos, y conserva el texto de razonamiento del asistente.

bash

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

Aider (chat en Markdown con bloques de edición)

Aider produce registros de chat en Markdown con bloques de edición SEARCH/REPLACE. El conversor analiza esos bloques para reconstruir las ediciones de archivos y extrae los comandos de shell de los bloques de código delimitados.

bash

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

SWE-Agent (pensamiento/acción/observación)

SWE-Agent usa un formato de bucle pensamiento/acción/observación. El conversor asigna las acciones a los tipos de paso correspondientes (edición, bash, lectura) y conserva el razonamiento en cadena del agente como bloques de pensamiento plegables.

bash

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

Detección automática

Si tienes trazas de varios agentes, Potato puede detectar el formato automáticamente a partir de la estructura de cada archivo:

bash

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

Exportaciones para el pipeline de entrenamiento

Las trazas anotadas pueden exportarse en formatos listos para entrenar modelos.

Formato PRM

Etiquetas de recompensa a nivel de paso para entrenar modelos de recompensa de proceso:

python

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

Pares de preferencia para DPO/RLHF

Combinado con anotaciones de comparación por pares, Potato genera pares de preferencia aptos para entrenamiento con Direct Preference Optimization o RLHF:

python

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

Resultados compatibles con SWE-bench

Exporta las anotaciones en un formato compatible con el harness de evaluación de SWE-bench para compararlas directamente con los resultados publicados:

bash

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

Inicio rápido

Pasar de cero a un servidor de anotación en marcha lleva unos cinco minutos.

Instalación

bash

pip install potato-annotation[coding-agents]

Convierte tus trazas

bash

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

Crea la configuración

Esta es una configuración completa para un proyecto de evaluación de agentes de coding que usa a la vez los esquemas de PRM y de revisión de código:

yaml

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

Arranca el servidor

bash

potato start config.yaml -p 8000

Abre http://localhost:8000 en el navegador, inicia sesión y empieza a anotar. Tendrás el renderizado completo de diffs, la salida de terminal y la anotación de recompensa de proceso descritos arriba.

Qué viene después

Esta es una primera versión y queda trabajo por delante. En la lista: soporte para más formatos de agente, mejor visualización de las refactorizaciones que tocan varios archivos e integración más estrecha con frameworks de entrenamiento como OpenRLHF y TRL.

Si escribes un nuevo conversor de trazas, un esquema o un formato de exportación, nos encantaría recibir tu contribución. Y si tu equipo está evaluando agentes de coding y se topa con algo que esta configuración no cubre, abre un issue en nuestro repositorio de GitHub.