TRAJEVAL: Decomposing Code Agent Trajectories for Fine-Grained Diagnosis

O artigo apresenta o TRAJEVAL, um framework de diagnóstico que decompõe as trajetórias de agentes de código em etapas de busca, leitura e edição para identificar falhas específicas, permitindo melhorias significativas no desempenho e na redução de custos através de feedback em tempo real.

O essencial

Imagine que você tem um estagiário muito inteligente, mas um pouco desajeitado, chamado "Agente de Código". A função dele é entrar em uma biblioteca gigante de livros (o repositório de código do GitHub), encontrar um erro específico em um dos livros e consertá-lo sozinho.

Às vezes, ele acerta. Às vezes, ele erra.

O problema é que, até hoje, como os chefes avaliavam esse estagiário? Apenas perguntando: "O livro foi consertado? Sim ou Não?".

• Se sim: Parabéns, nota 10!
• Se não: Nota 0, tente de novo.

Isso é como o sistema atual de avaliação (chamado Pass@k). Ele diz se o trabalho foi feito, mas não diz por que o estagiário falhou. Ele não diz se o estagiário perdeu tempo procurando o livro errado, se achou o livro certo mas não entendeu o que estava escrito, ou se entendeu tudo mas escreveu a correção no lugar errado.

É aqui que entra o TRAJEVAL (o tema deste artigo).

O Que é o TRAJEVAL?

O TRAJEVAL é como um detetive que assiste a todo o filme da jornada do estagiário, em vez de apenas olhar o resultado final. Ele divide o trabalho do agente em três etapas simples, como se fosse uma receita de bolo:

1. Procurar (Search): O agente encontrou o livro certo na prateleira?
   • Analogia: Se você precisa achar "Harry Potter", você vai direto à seção de fantasia ou fica vasculhando a seção de culinária por 2 horas?
2. Ler (Read): O agente leu as páginas certas dentro do livro?
   • Analogia: Você pegou o livro, mas só olhou a capa e o índice, ou leu o capítulo onde está o erro?
3. Editar (Edit): O agente fez a correção no lugar certo?
   • Analogia: Você riscou o erro na página 50, ou riscou a página 51 por engano?

O Que Eles Descobriram?

Ao analisar mais de 16.000 tentativas de diferentes "estagiários" (modelos de IA), eles descobriram coisas fascinantes:

• Todos são muito "gastos": Os agentes leem e exploram 22 vezes mais do que o necessário! É como se, para achar um único livro, eles lessem a biblioteca inteira. Isso é ineficiente e caro.
• O segredo do sucesso não é ser rápido, é ser completo: O que realmente faz o agente acertar não é ser eficiente (ler pouco), mas sim garantir que ele leu tudo o que precisava (alta "Recall"). Se ele ler tudo e errar a edição, ainda é melhor do que ler pouco e não achar o problema.
• Cada modelo tem um "defeito de fábrica" diferente:
  • O GPT-5 é ótimo em achar o livro e ler as páginas, mas às vezes faz a correção no lugar errado (como quem sabe a receita, mas coloca sal no bolo em vez de açúcar).
  • O Qwen-32B (um modelo menor) muitas vezes nem consegue achar o livro na biblioteca (falha na busca).

A Mágica: Usando o Diagnóstico para Ajudar

A parte mais legal do TRAJEVAL é que ele não serve só para criticar depois. Ele pode ajudar em tempo real.

Imagine que, enquanto o agente está procurando, o sistema TRAJEVAL sussurra no ouvido dele:

"Ei, você está olhando para o arquivo certo! Continue focado ali!"

Ou:

"Cuidado, você está editando o arquivo errado!"

Quando os pesquisadores testaram isso, os agentes ficaram melhores e mais baratos. Eles acertaram mais tarefas e gastaram menos "dinheiro" (tokens de processamento) porque não perderam tempo procurando coisas que não eram relevantes.

Resumo em uma Frase

O TRAJEVAL transformou a avaliação de robôs programadores de um simples "aprovado/reprovado" em um check-up de saúde detalhado, mostrando exatamente onde eles estão doentes e como curá-los enquanto trabalham, tornando-os mais inteligentes e eficientes.

Resumo técnico

Resumo Técnico: TRAJEVAL

1. O Problema

Os agentes de código baseados em Grandes Modelos de Linguagem (LLMs) demonstraram capacidade de resolver problemas no GitHub de forma autônoma. No entanto, as métricas de avaliação atuais (como Pass@k) são baseadas apenas no resultado final (sucesso ou falha binária).

• Limitação Principal: Quando um agente falha, métricas como Pass@1 não oferecem visibilidade sobre onde ou por que o agente errou. Elas colapsam toda a execução em um único número, impossibilitando a distinção entre um agente que encontrou o arquivo certo mas editou a função errada, e um agente que nem sequer localizou o arquivo.
• Necessidade: Há uma lacuna crítica na necessidade de diagnósticos em nível de estágio (fine-grained) para entender os mecanismos de falha e sucesso, permitindo otimizações direcionadas.

2. Metodologia: O Framework TRAJEVAL

Os autores introduzem o TRAJEVAL, um framework de diagnóstico que decompõe a trajetória de execução de um agente em três estágios interpretáveis, comparando-a com um "patch de referência" (ground truth).

Decomposição em Três Estágios

Para cada tarefa, o framework calcula Precisão (eficiência) e Recall (efetividade) em três níveis:

1. Search (Busca - Nível de Arquivo):
   • Avalia a capacidade do agente de localizar os arquivos corretos no repositório.
   • Métrica: Recall de busca indica se os arquivos necessários foram encontrados; Precisão indica se houve navegação redundante.
2. Read (Leitura - Nível de Função):
   • Avalia a compreensão do código dentro dos arquivos encontrados. O agente abriu o arquivo, mas examinou as funções relevantes?
   • Métrica: Recall de leitura mede se as funções críticas foram compreendidas.
3. Edit (Edição - Nível de Função):
   • Avalia a precisão da localização das modificações. O agente alterou as funções corretas?
   • Métrica: Recall de edição mede se as modificações foram aplicadas nas regiões de código necessárias.

Definição do "Golden Context"

O framework utiliza o patch de referência para definir o contexto ideal:

• Tier 0 (Core): Arquivos e funções explicitamente modificados no patch de referência (o mínimo necessário).
• Tier 1 (Extended): O Tier 0 mais dependências estruturais de um salto (imports, classes pai, arquivos de teste).
• Uso: O Recall é calculado contra o Tier 0 (rigoroso), enquanto a Precisão considera o Tier 1 para distinguir entre exploração razoável e navegação inútil.

Extração de Recursos e Predição

• O framework extrai vetores de características (6 métricas: P e R para Search, Read, Edit) de 16.758 trajetórias.
• Um modelo de Regressão Logística leve é treinado para prever o Pass@1 (sucesso da tarefa) com base nessas características, sem precisar acessar o patch de referência durante a inferência.

3. Principais Contribuições

1. Framework de Diagnóstico: Introdução do TRAJEVAL, que transforma logs de execução não estruturados em sinais quantitativos de precisão e recall por estágio.
2. Análise de Comportamento Universal e Específico: Identificação de ineficiências universais (todos os agentes examinam ~22x mais funções do que o necessário) e modos de falha distintos entre modelos.
3. Predição de Sucesso: Demonstração de que características de trajetória podem prever o Pass@1 com alta precisão (erro médio absoluto de 0,87% a 2,1%) e manter forte correlação de ranking (ρ ≥ 0,886) mesmo sob mudanças de distribuição (repositórios e linguagens não vistos).
4. Intervenção Acionável: Validação de que feedback em tempo real baseado nesses sinais melhora o desempenho.

4. Resultados Chave

Ineficiência Universal vs. Eficácia

• Precisão Baixa: Todos os agentes exibem baixa precisão (4–5% no estágio de leitura), indicando uma exploração excessiva (over-exploration). Eles leem muito mais código do que o necessário.
• Recall como Fator de Sucesso: A Recall (especialmente no estágio de Edit) é o preditor mais forte de sucesso. Um agente que explora muito mas acerta o alvo final tem sucesso; um agente eficiente que erra o alvo falha.

Modos de Falha Distintos (Diagnóstico por Modelo)

O framework revela falhas específicas que métricas agregadas ocultam:

• GPT-5: Localiza arquivos e lê funções corretamente (alto Recall de Search/Read), mas falha em direcionar as edições corretamente (baixo Recall de Edit). Falha na transição de compreensão para modificação.
• Qwen-32B: Falha completamente na descoberta de arquivos (baixo Recall de Search), nunca encontrando os arquivos relevantes, independentemente da capacidade de edição.

Validação de Predição

• O modelo prediz o Pass@1 com MAE de 1,20% no SWE-bench.
• Mantém correlação de ranking perfeita (ρ = 1,00) em cenários de "repositório não visto" e "linguagem não vista", demonstrando robustez.

Estudo de Intervenção (Feedback em Tempo Real)

Os autores implementaram um mecanismo onde o agente recebe um sinal de confirmação quando interage com o "golden context" (ex: "✓ Você está examinando código relevante").

• Resultado: Melhora o Pass@1 em 2,2 a 4,6 pontos percentuais em modelos de ponta (GPT-5 e Qwen3-Coder-480B).
• Eficiência: Reduz o uso de tokens em até 29% e os custos em até 31%, pois os agentes convergem mais rápido para a solução correta.

5. Significado e Impacto

O TRAJEVAL representa uma mudança de paradigma na avaliação de agentes de código:

• De "Caixa-Preta" para "Diagnóstico Mecanístico": Em vez de apenas medir se o agente passou ou não, o framework explica o porquê, permitindo otimizações direcionadas (ex: melhorar prompts de descoberta de arquivos para Qwen, ou melhorar o planejamento de edição para GPT-5).
• Otimização de Custos e Desempenho: Ao identificar gargalos específicos (como a ineficiência universal na precisão), o framework permite intervenções que aumentam a acurácia e reduzem custos simultaneamente.
• Generalização: A capacidade de prever desempenho em repositórios e linguagens não vistos sugere que os padrões de comportamento de agentes (busca, leitura, edição) são transferíveis e fundamentais para o desenvolvimento de agentes mais robustos.

Em suma, o TRAJEVAL transforma a avaliação de agentes de uma métrica de resultado binário para uma ferramenta de diagnóstico detalhada, essencial para o avanço de sistemas de engenharia de software autônomos.