Anotação de Agentes de Programação

Anote traces de agentes de programação com renderização de diffs, saída de terminal e navegação por árvore de arquivos. Importe do Claude Code, Aider, SWE-Agent e outros assistentes de programação.

Novidade na v2.4.0

Agentes de programação -- Claude Code, Aider, SWE-Agent, OpenHands e outros -- produzem traces que são fundamentalmente diferentes dos traces de agentes de uso geral. Eles contêm diffs de código, saída de terminal, leituras de arquivos, percursos de diretórios e resultados de testes. Revisar esses traces exige uma renderização especializada que compreenda a estrutura das mudanças de código e as apresente em um formato familiar aos engenheiros de software.

O CodingTraceDisplay do Potato é um tipo de exibição feito sob medida para sessões de agentes de programação. Ele renderiza diffs unificados com linhas destacadas em vermelho/verde por sintaxe, saída de terminal em blocos escuros, leituras de arquivos com números de linha, e fornece uma barra lateral com a árvore de arquivos mostrando cada arquivo que o agente tocou. Os anotadores podem navegar entre arquivos, expandir ou recolher saídas longas e avaliar operações individuais ou o trace como um todo.

Configuração

Habilite a exibição de trace de programação na configuração do seu projeto:

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

Recursos de Exibição

Visualização de Diff Unificado

As operações de edição são renderizadas como diffs unificados com destaque em vermelho/verde. As linhas removidas aparecem com fundo vermelho e prefixo -; as linhas adicionadas aparecem com fundo verde e prefixo +. As linhas de contexto são exibidas em cinza neutro. O caminho do arquivo e o intervalo de linhas aparecem em uma barra de cabeçalho acima de cada bloco de diff.

Quando diff_style: side_by_side é definido, as versões antiga e nova aparecem em colunas adjacentes, facilitando ver o que mudou em edições complexas.

Blocos de Terminal Escuros

Comandos Bash e de shell são renderizados em blocos de terminal escuros com fonte monoespaçada. O próprio comando aparece com um prefixo de prompt $, e a saída aparece abaixo. Os códigos de saída são exibidos em um pequeno selo (verde para 0, vermelho para diferente de zero). Saídas longas são recolhidas automaticamente com um expansor "Mostrar mais N linhas".

Leituras de Arquivo com Números de Linha

Quando o agente lê um arquivo, o conteúdo é exibido com números de linha em um bloco de código claro. Leituras parciais mostram o intervalo de linhas (por exemplo, "linhas 42-87 de 312"). O destaque de sintaxe é aplicado com base na extensão do arquivo.

Barra Lateral com Árvore de Arquivos

A barra lateral com a árvore de arquivos mostra cada arquivo que o agente tocou durante o trace. Os arquivos são agrupados por diretório e ordenados alfabeticamente. Cada arquivo tem um ícone indicando as operações realizadas:

Ícone de lápis para arquivos editados
Ícone de olho para arquivos somente leitura
Ícone de mais para arquivos recém-criados
Ícone de lixeira para arquivos excluídos
Ícone de terminal para scripts executados

Clicar em um arquivo na árvore rola o painel principal até a primeira operação envolvendo aquele arquivo.

Saídas Longas Recolhíveis

Qualquer bloco de saída que exceda o auto_collapse_threshold é recolhido automaticamente. Uma linha de resumo mostra as primeiras e últimas linhas com um botão "Mostrar todas as N linhas". Isso mantém o trace navegável mesmo quando operações individuais produzem centenas de linhas de saída.

Conversores de Trace

O Potato vem com quatro conversores específicos para agentes de programação que normalizam formatos de trace na representação unificada de trace de programação.

Conversor	Origem	Formato
`claude_code`	Claude Code / API da Anthropic	API de Messages com blocos `tool_use` (ferramentas Read, Edit, Bash, Write)
`aider`	Aider	Logs de chat em Markdown com blocos de edição SEARCH/REPLACE e ORIGINAL/UPDATED
`swe_agent_trajectory`	SWE-Agent	Arquivos JSON de trajetória com triplas de pensamento/ação/observação
`auto`	Detecção automática	Inspeciona a estrutura do trace e seleciona o melhor conversor automaticamente

Especifique o conversor na sua configuração:

yaml

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

Conversor do Claude Code

O conversor claude_code processa traces da API de Messages da Anthropic, em que o uso de ferramentas é representado como blocos de conteúdo tool_use e tool_result. Ele reconhece as ferramentas padrão do Claude Code:

Chamadas da ferramenta Read tornam-se exibições de leitura de arquivo
Chamadas da ferramenta Edit tornam-se diffs unificados
Chamadas da ferramenta Write tornam-se exibições de criação de arquivo
Chamadas da ferramenta Bash tornam-se blocos de terminal
Chamadas das ferramentas Glob/Grep tornam-se exibições de resultados de busca

Conversor do Aider

O conversor aider analisa o formato de chat baseado em markdown do Aider. Ele extrai blocos SEARCH/REPLACE (e o formato mais antigo ORIGINAL/UPDATED) e os converte em diffs unificados. Comandos de shell e sua saída são extraídos de blocos de código delimitados marcados com bash ou shell.

Conversor de Trajetória do SWE-Agent

O conversor swe_agent_trajectory lê os arquivos JSON de trajetória do SWE-Agent. Cada entrada de trajetória contém um pensamento (o raciocínio do agente), uma ação (o comando executado) e uma observação (a saída do comando). O conversor classifica as ações em edições de arquivos, leituras de arquivos, comandos de shell e operações de navegação.

Uso da CLI

Converta traces brutos antes de iniciar o servidor de anotação:

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

A flag -i aceita um único arquivo ou um diretório. Quando um diretório é informado, todos os arquivos .json e .jsonl são processados. O conversor grava um objeto JSON por linha no arquivo de saída.

Opções adicionais:

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 Dados

Após a conversão, cada linha no arquivo JSONL de saída segue esta estrutura:

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

O array structured_turns preserva a ordem exata das operações. Cada turno tem um campo type (file_read, edit, terminal, file_write, search, thought) e campos específicos do tipo.

Referência de Configuração

Aqui está uma configuração completa combinando a exibição de trace de programação com esquemas de anotação para avaliar a saída de agentes de programação:

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"

Executando Projetos de Exemplo

O Potato inclui projetos de exemplo para anotação de agentes de programação:

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 exemplo inclui traces de amostra, um arquivo de configuração completo e um README descrevendo a tarefa de anotação.

Veja Também

Anotação de Recompensa por Processo -- colete sinais de recompensa por etapa para treinamento de PRM
Anotação de Revisão de Código -- revisão inline no estilo de PR do GitHub para mudanças de código
Observação ao Vivo de Agentes de Programação -- assista e interaja com agentes de programação em tempo real
Anotação Agêntica -- anotação de traces de agentes de uso geral
Formatos de Exportação -- exporte dados de anotação para treinamento de modelos

Para detalhes de implementação, consulte a documentação de origem.