Por que a Anotação de Agentes de Programação Importa

Agentes de programação como Claude Code, Aider e SWE-Agent ficaram bons rápido, e agora as pessoas de fato precisam avaliar o trabalho deles. Uma única execução é uma trajetória bagunçada: edições de código, comandos de terminal, leituras de arquivo e passos de raciocínio amarrados uns aos outros. Para treinar um agente melhor, você precisa de feedback humano sobre essas execuções, e as ferramentas de anotação que a maioria das equipes tinha nunca foram feitas para esse tipo de dado.

Uma interface de anotação de texto simples não consegue renderizar um diff unificado, formatar a saída de terminal ou lidar com a estrutura aninhada de um trace de agente. Então os laboratórios acabam escrevendo suas próprias UIs de avaliação, refazendo o mesmo trabalho e terminando com conjuntos de dados que não conversam entre si.

O Potato agora lida com a anotação de agentes de programação diretamente, com componentes de renderização feitos para traces, schemas de anotação para esse tipo de avaliação e exportações que alimentam o treinamento diretamente. Para a referência completa do recurso, consulte a documentação de anotação de agentes de programação e o guia mais amplo de avaliação de agentes.

CodingTraceDisplay: Um Visualizador de Traces

A maior parte da experiência de anotação acontece pelo componente CodingTraceDisplay. Ele renderiza cada passo da trajetória de um agente usando qualquer visualização que se encaixe naquele tipo de passo.

Veja como fica a interface de anotação de agentes de programação no Potato:

Exibição de trace de agente de programação mostrando renderização de diff e árvore de arquivos O CodingTraceDisplay renderiza diffs de código, saída de terminal e leituras de arquivo com a formatação adequada

Visualização de Diff Unificado

As edições de código são renderizadas como diffs unificados com realce vermelho/verde para linhas removidas e adicionadas. A visualização de diff inclui números de linha, cabeçalhos com o caminho do arquivo e linhas de contexto ao redor das mudanças. Isso espelha a experiência familiar de pull request do GitHub que a maioria dos desenvolvedores já entende.

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

Blocos de Terminal Escuros

Os comandos Bash e suas saídas são renderizados em blocos de terminal escuros com fonte monoespaçada, suporte adequado a cores ANSI e saída rolável para resultados longos. Os blocos de terminal mostram o comando que foi executado, o diretório de trabalho e o código de saída.

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

Blocos de Código com Números de Linha

As operações de leitura de arquivo são exibidas como blocos de código com realce de sintaxe e números de linha. Quando o agente lê um intervalo específico de linhas, apenas essas linhas são mostradas com seus números de linha originais preservados, facilitando a referência cruzada com o arquivo real.

Barra Lateral com Árvore de Arquivos

Uma barra lateral recolhível mostra todos os arquivos tocados durante a trajetória, organizados em uma estrutura de árvore. Cada arquivo exibe um ícone indicando se ele foi criado, modificado, lido ou deletado. Clicar em um arquivo na árvore rola até a primeira aparição dele no trace.

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"

Saídas Recolhíveis

Saídas longas de qualquer tipo de passo podem ser recolhidas para manter o trace legível. Os anotadores podem expandir passos individuais conforme necessário, ou usar os controles "Expand All" / "Collapse All". Os blocos de pensamento/raciocínio dos agentes vêm recolhidos por padrão, mas ficam disponíveis para revisão.

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"

Schema de Modelo de Recompensa por Processo (PRM)

Modelos de recompensa por processo atribuem crédito no nível do passo, em vez de avaliar apenas o resultado final. O Potato suporta dois modos de anotação PRM projetados para diferentes equilíbrios entre velocidade e precisão.

Modo de Primeiro Erro

No modo de primeiro erro, o anotador rola pela trajetória e clica no primeiro passo em que o agente erra. Todos os passos antes do passo clicado são automaticamente marcados como corretos, e todos os passos depois dele (incluindo o passo clicado) são automaticamente marcados como incorretos. Isso acelera drasticamente a anotação, já que o anotador só precisa identificar um único ponto.

yaml

annotation_schemes:
  - annotation_type: process_reward
    name: prm_first_error
    mode: "first_error"
    labels:
      correct: "Correct"
      incorrect: "Incorrect"
    description: "Click the first step where the agent makes an error"
    allow_all_correct: true       # Button to mark entire trace as correct
    allow_all_incorrect: true     # Button to mark entire trace as wrong from step 1
    highlight_clicked_step: true
    auto_scroll_on_click: true

Modo Passo a Passo

No modo passo a passo, cada passo recebe uma avaliação independente. Isso produz dados de treinamento mais detalhados, mas leva mais tempo por trace. Os anotadores avaliam cada passo como correto, incorreto ou parcialmente correto.

yaml

annotation_schemes:
  - annotation_type: process_reward
    name: prm_per_step
    mode: "per_step"
    labels:
      correct:
        text: "Correct"
        description: "This step is logically sound and makes progress"
        keyboard_shortcut: "1"
      partially_correct:
        text: "Partially Correct"
        description: "Right direction but flawed execution"
        keyboard_shortcut: "2"
      incorrect:
        text: "Incorrect"
        description: "This step is wrong or counterproductive"
        keyboard_shortcut: "3"
    require_all_steps: true       # Cannot submit until all steps rated
    show_progress_bar: true

Schema de Revisão de Código

A interface de revisão de código fornece controles de anotação no estilo de PR do GitHub:

Anotação de revisão de código com comentários inline em diffs Os anotadores podem clicar em linhas do diff para adicionar comentários inline, avaliar arquivos e dar veredictos de aprovar/rejeitar

O schema de revisão de código traz a anotação no estilo de PR do GitHub para traces de agentes. Os anotadores podem deixar comentários inline em linhas específicas dentro dos diffs, avaliar arquivos individuais e fornecer um veredicto geral.

yaml

annotation_schemes:
  - annotation_type: code_review
    name: agent_review
    inline_comments:
      enabled: true
      categories:                 # Optional categorization for comments
        - "Bug"
        - "Style"
        - "Logic Error"
        - "Unnecessary Change"
        - "Missing Error Handling"
    file_ratings:
      enabled: true
      scale: [1, 2, 3, 4, 5]
      labels: ["Poor", "Below Average", "Acceptable", "Good", "Excellent"]
    verdict:
      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"
    require_comment_on_reject: true

Conversores de Trace: Importe de Qualquer Agente

O Potato inclui conversores embutidos para os três formatos de agentes de programação mais populares. Os conversores normalizam cada formato na representação estruturada interna de traces do Potato.

Claude Code (API de Mensagens da Anthropic)

Os traces do Claude Code usam o formato da API de Mensagens da Anthropic com blocos de conteúdo tool_use e tool_result. O conversor extrai edições de arquivo, comandos bash e leituras de arquivo das chamadas de ferramenta e preserva o texto de raciocínio do assistente.

bash

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

Aider (Chat em Markdown com Blocos de Edição)

O Aider produz logs de chat formatados em markdown com blocos de edição SEARCH/REPLACE. O conversor analisa esses blocos para reconstruir as edições de arquivo e extrai comandos de shell de blocos de código cercados.

bash

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

SWE-Agent (Pensamento/Ação/Observação)

O SWE-Agent usa um formato de loop de pensamento/ação/observação. O conversor mapeia as ações para os tipos de passo apropriados (edição, bash, leitura) e preserva o raciocínio em cadeia de pensamento do agente como blocos de pensamento recolhíveis.

bash

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

Detecção Automática

Se você tem traces de múltiplos agentes, o Potato pode detectar automaticamente o formato com base na estrutura de cada arquivo:

bash

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

Exportações para o Pipeline de Treinamento

Traces anotados podem ser exportados em formatos prontos para o treinamento de modelos.

Formato PRM

Rótulos de recompensa no nível do passo para treinar modelos de recompensa por processo:

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 Preferência DPO/RLHF

Quando combinado com anotações de comparação pareada, o Potato gera pares de preferência adequados para Otimização Direta de Preferências (DPO) ou treinamento 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 Compatíveis com SWE-bench

Exporte anotações em um formato compatível com o harness de avaliação do SWE-bench para comparação direta com benchmarks publicados:

bash

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

Início Rápido

Ir do zero a um servidor de anotação em execução leva cerca de cinco minutos.

Instalação

bash

pip install potato-annotation[coding-agents]

Converta Seus Traces

bash

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

Crie Sua Configuração

Aqui está uma configuração completa para um projeto de avaliação de agentes de programação que usa tanto schemas de PRM quanto de revisão 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"
    labels:
      correct: "Correct"
      incorrect: "Incorrect"
    allow_all_correct: true
    description: "Click the first step where the agent makes a mistake"
 
  - annotation_type: code_review
    name: code_quality
    inline_comments:
      enabled: true
      categories: ["Bug", "Logic Error", "Style", "Missing Error Handling"]
    file_ratings:
      enabled: true
      scale: [1, 2, 3, 4, 5]
    verdict:
      enabled: true
      options:
        - value: "approve"
          text: "Approve"
        - value: "request_changes"
          text: "Request Changes"
        - value: "comment"
          text: "Comment"
 
  - annotation_type: text_input
    name: overall_notes
    label: "Additional Notes"
    placeholder: "Any other observations about this trace..."
    required: false
 
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"
    password: "secure_password_1"
  - username: "annotator2"
    password: "secure_password_2"

Inicie o Servidor

bash

potato start config.yaml -p 8000

Abra http://localhost:8000 no seu navegador, faça login e comece a anotar. Você obtém toda a renderização de diff, a saída de terminal e a anotação de recompensa por processo descritas acima.

O Que Vem a Seguir

Este é um primeiro lançamento, e há mais que queremos fazer. Na lista: suporte a mais formatos de agentes, melhor visualização para refatorações de múltiplos arquivos e integração mais próxima com frameworks de treinamento como OpenRLHF e TRL.

Se você escrever um novo conversor de trace, schema ou formato de exportação, adoraríamos uma contribuição. E se a sua equipe está avaliando agentes de programação e esbarra em algo que essa configuração não cobre, abra uma issue no nosso repositório do GitHub.