CODESTRUCT: Code Agents over Structured Action Spaces

1. O Problema

Os agentes de código baseados em Grandes Modelos de Linguagem (LLMs) atuais interagem com repositórios de software tratando o código como texto não estruturado. Essa abordagem gera uma "mismatch de abstração" fundamental:

• Fragilidade na Leitura: Os agentes precisam ler arquivos inteiros ou faixas de linhas arbitrárias, o que introduz contexto irrelevante e degrada o raciocínio, ou corre o risco de truncar funções no meio de uma declaração.
• Fragilidade na Escrita: As edições são realizadas via correspondência de strings ou números de linha. Isso é ineficiente (exige regeneração de grandes blocos de código inalterados) e propenso a erros. Pequenas variações de formatação ou padrões repetidos causam falhas como "nenhuma ocorrência encontrada" ou "múltiplas ocorrências".
• Ciclo de Tentativa e Erro: Essas falhas sistemáticas forçam os agentes a ciclos caros de tentativa e erro, aumentando o consumo de tokens e o custo de inferência sem garantir a correção do patch.

2. Metodologia: CODESTRUCT

O CODESTRUCT propõe reestruturar a interação do agente com o repositório, transformando-o em um espaço de ação estruturado baseado na Árvore de Sintaxe Abstrata (AST). Em vez de manipular spans de texto, os agentes operam sobre entidades de programa nomeadas (classes, funções, métodos).

O framework introduz dois primitivos principais (ferramentas) que operam diretamente nos nós da AST:

A. readCode (Recuperação Estruturada)

Substitui a leitura de arquivos por faixas de linhas ou arquivos inteiros.

• Funcionamento: O agente solicita a recuperação de uma entidade específica usando um seletor (ex: file.py::ClassName::method).
• Benefício: Retorna unidades sintáticas completas (ex: o corpo inteiro de uma função) sem truncamento ou contexto excessivo.
• Modos de Operação:
  1. Navegação de diretório (lista de arquivos).
  2. Sumarização de arquivo (seleciona apenas assinaturas de classes/funções para arquivos grandes).
  3. Recuperação de entidade (retorna a implementação completa da entidade selecionada).

B. editCode (Modificação Estruturada)

Substitui a substituição de strings ou edição por linha.

• Funcionamento: O agente especifica uma operação (inserção, substituição ou remoção) e um seletor para o nó alvo na AST.
• Garantias: A ferramenta aplica a transformação no nível da AST, preservando automaticamente a indentação e a validade sintática. Se uma edição resultar em erro de sintaxe, ela é rejeitada antes de ser aplicada.
• Vantagem: Elimina a necessidade de regenerar código inalterado e remove a dependência de correspondência de strings frágil.

3. Principais Contribuições

1. Interface de Espaço de Ação Estruturado: Uma ponte entre representações baseadas em AST e agentes LLM, expondo entidades semânticas nomeadas como unidades primárias de interação.
2. Primitivas Sensíveis à Estrutura: Implementação de readCode e editCode com seletores legíveis por humanos, resolução automática de escopo e validação de sintaxe para recuperação robusta do agente.
3. Evidência Empírica Abrangente: Avaliação em dois benchmarks (SWE-Bench Verified e CodeAssistBench) com seis modelos de linguagem diferentes, demonstrando ganhos tanto em eficácia quanto em eficiência.

4. Resultados Experimentais

Os resultados foram avaliados no SWE-Bench Verified (correção de bugs em repositórios Python) e no CodeAssistBench (assistência de código interativa).

Desempenho no SWE-Bench Verified:

• Precisão (Pass@1): O CODESTRUCT melhorou a precisão em 1,2% a 5,0% para modelos de ponta (ex: GPT-5, Qwen3-Coder).
• Ganhos em Modelos Menores: O modelo GPT-5-nano apresentou um salto dramático de 20,8 pontos percentuais (de 19,6% para 40,4%). Isso ocorreu porque a interface estruturada reduziu as falhas de "patch vazio" (onde o agente falha em gerar qualquer correção) de 46,6% para 7,2%, permitindo que o modelo explorasse mais profundamente em vez de desistir cedo.
• Eficiência e Custo:
  • Redução no consumo de tokens de entrada em 12% a 38% para a maioria dos modelos.
  • Redução no custo de inferência de até 33% (ex: GPT-5-mini reduziu o custo em 32,6%).
  • Menor número de chamadas de API, indicando convergência mais rápida para soluções corretas.

Desempenho no CodeAssistBench:

• Ganhos consistentes de precisão (+0,8% a +4,4%) em todos os modelos avaliados.
• Reduções significativas de custo (até 33%) e tokens, demonstrando que a abordagem se generaliza para fluxos de trabalho interativos e exploratórios.

Análise de Erros:

• A abordagem estruturada reduziu erros de edição em 76-88% para modelos de alta capacidade, substituindo a correspondência de strings falha por operações AST confiáveis.
• Para modelos menores, a redução de erros de interface permitiu que o agente tentasse mais edições corretas, compensando limitações de raciocínio.

5. Significado e Conclusão

O artigo demonstra que tratar o código como texto plano é um gargalo fundamental para agentes de IA. Ao ancorar as interações na estrutura sintática (AST) do código, o CODESTRUCT oferece uma base mais confiável e eficiente.

• Mudança de Paradigma: Move a responsabilidade da "correspondência de texto" para o agente (que precisa entender a lógica) para a ferramenta (que garante a sintaxe), alinhando o espaço de ação do agente com a forma como desenvolvedores humanos raciocinam sobre o código (por entidades nomeadas, não por linhas).
• Impacto Prático: Permite que modelos menores (como o GPT-5-nano) realizem tarefas complexas de engenharia de software com muito mais sucesso, e reduz drasticamente os custos operacionais para modelos maiores ao eliminar leituras e edições redundantes.
• Futuro: A abordagem sugere que interfaces de agente sensíveis à estrutura são essenciais para escalar a automação de tarefas de engenharia de software, superando as limitações atuais de fragilidade e ineficiência.