Manual de Harness: Tornando os Harnesses de Agentes em Evolução Legíveis, Navegáveis e Editáveis

Resumo

A capacidade de um agente de IA moderno depende não apenas de seu modelo base, mas também de seu arcabouço (harness), que constrói prompts, gerencia estado, invoca ferramentas e coordena a execução. À medida que modelos, APIs, ambientes e requisitos evoluem, o arcabouço deve ser continuamente modificado. Antes que tal alteração possa ser feita, um desenvolvedor ou agente de codificação precisa identificar todas as localizações de código que implementam o comportamento alvo. Isso é difícil porque arcabouços de produção são grandes, fortemente acoplados e comportamentalmente distribuídos, enquanto as solicitações de modificação descrevem o que o sistema deve fazer e os repositórios são organizados por arquivos e módulos. Busca de código, indexação de repositório e processamento de contexto longo facilitam a inspeção, mas ainda deixam esse mapeamento comportamento-código a ser recuperado manualmente. A localização de comportamento é, portanto, um gargalo central na evolução de arcabouços. Apresentamos o Manual do Arcabouço (Harness Handbook), uma representação centrada em comportamento sintetizada automaticamente a partir de uma base de código de arcabouço por meio de análise estática e estruturação assistida por LLM, vinculando cada comportamento ao seu código fonte correspondente. Também introduzimos a Divulgação Progressiva Guiada por Comportamento (Behavior-Guided Progressive Disclosure, BGPD), que guia agentes desde comportamentos de alto nível até detalhes de implementação relevantes e verifica localizações candidatas em relação ao código-fonte atual. Em diversas solicitações de modificação de dois arcabouços de código aberto, o planejamento assistido pelo Manual melhora a localização de comportamento e a qualidade dos planos de edição, utilizando menos tokens do planejador, com os maiores ganhos em locais dispersos, caminhos raramente executados e interações entre módulos. Evoluir sistemas agentes complexos depende, portanto, não apenas de gerar edições, mas também de determinar onde essas edições devem ser feitas.

English

The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution. As models, APIs, environments, and requirements evolve, the harness must be continually modified. Before such a change can be made, a developer or coding agent must identify all code locations that implement the target behavior. This is difficult because production harnesses are large, tightly coupled, and behaviorally distributed, while modification requests describe what the system should do and repositories are organized by files and modules. Code search, repository indexing, and long-context processing ease inspection, but still leave this behavior-to-code mapping to be recovered by hand. Behavior localization is therefore a central bottleneck in harness evolution. We introduce the Harness Handbook, a behavior-centric representation synthesized automatically from a harness codebase via static analysis and LLM-assisted structuring, linking each behavior to its corresponding source. We also introduce Behavior-Guided Progressive Disclosure (BGPD), which guides agents from high-level behaviors to relevant implementation details and verifies candidate locations against the current source. On diverse modification requests from two open-source harnesses, Handbook-Assisted planning improves behavior localization and edit-plan quality while using fewer planner tokens, with the largest gains on scattered sites, rarely executed paths, and cross-module interactions. Evolving complex agentic systems thus depends not only on generating edits, but also on determining where those edits should be made.