🤖 AI

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

Este artigo apresenta o Harness Handbook, uma representação centrada no comportamento e um método de Revelação Progressiva Guiada pelo Comportamento (BGPD) que mapeia automaticamente requisitos comportamentais de alto nível para locais específicos de código-fonte, superando assim o gargalo de localização e melhorando a eficiência e a qualidade da evolução de harnesses de agentes de IA complexos.

Autores originais: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

Publicado 2026-07-16

📖 4 min de leitura☕ Leitura rápida

CC BY 4.0

Autores originais: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine que você acabou de construir um assistente robô superinteligente. Você deu a ele um cérebro (um modelo de IA massivo) e disse: "Vá consertar meu computador!". Mas o cérebro sozinho não é suficiente. O robô precisa de um corpo, um sistema nervoso e um conjunto de instruções sobre como mover seus dedos, segurar uma chave de fenda e saber quando terminou. No mundo da IA, esse "corpo e sistema nervoso" é chamado de harness (harness/estribo). É a camada de software que diz à IA quando falar, quando usar uma ferramenta e como se lembrar do que acabou de fazer.

Agora, imagine que você queira atualizar esse robô. Talvez você queira que ele seja mais cuidadoso antes de deletar um arquivo, ou talvez queira que ele verifique seu trabalho três vezes em vez de apenas uma. Nos velhos tempos, um programador humano teria que vasculhar milhares de linhas de código, tentando descobrir exatamente onde na estrutura do sistema nervoso do robô essa regra de "verifique seu trabalho" está escondida. É como tentar encontrar um nervo específico em uma enorme bola de barbante emaranhada. O código geralmente está espalhado por muitos arquivos diferentes, misturado com outras lógicas, e é difícil de rastrear. Se você perder até mesmo um pequeno ponto, seu robô ainda poderá deletar arquivos por acidente. Este artigo aborda o frustrante problema de encontrar esses pontos ocultos para que possamos atualizar nossos ajudantes de IA de forma segura.

Os pesquisadores por trás deste estudo, liderados por Ruhan Wang e colegas, perceberam que o maior gargalo não é ensinar a IA como fazer mudanças, mas sim ajudar humanos (ou outros agentes de IA) a descobrir onde fazê-las. Eles chamam esse problema de localização de comportamento (behavior localization). Para resolvê-lo, eles inventaram algo chamado Harness Handbook (Manual do Harness).

Pense no Harness Handbook não como uma lista de arquivos, mas como um manual de instruções para o comportamento do robô. Em vez de organizar as informações por "Arquivo A, Arquivo B, Arquivo C" (que é como o código é geralmente armazenado), o Handbook organiza as informações por "O que o robô realmente faz". É como ter um guia que diz: "Se você quiser alterar a forma como o robô lida com um sinal de 'Tarefa Concluída', aqui estão os três lugares específicos no cérebro dele onde esse sinal é processado, e aqui está exatamente como eles conversam entre si".

A equipe construiu um sistema que cria automaticamente este Handbook lendo o código do robô e usando uma IA inteligente para mapear as conexões. Eles chamam o método de usar este mapa de Revelação Progressiva Guiada pelo Comportamento (Behavior-Guided Progressive Disclosure). Imagine que você está tentando consertar um relógio complexo. Em vez de encarar uma pilha de 500 engrenagens e molas, você abre um manual que primeiro mostra a seção "Indicação de Tempo", depois dá zoom na engrenagem do "Ponteiro das Horas" e, finalmente, destaca o parafuso exato que você precisa girar. O Handbook faz isso com o código da IA: ele começa com uma visão geral de alto nível do que o sistema faz e, em seguida, guia o usuário até as linhas específicas de código que precisam ser editadas.

Os pesquisadores testaram essa ideia em dois sistemas de IA do mundo real (chamados Terminus-2 e Codex). Eles pediram a agentes de codificação que fizessem alterações baseadas em solicitações simples como: "Faça o robô pedir confirmação três vezes antes de avaliar uma tarefa". Eles compararam dois grupos: um grupo teve que encontrar o código da maneira antiga (pesquisando através de arquivos) e o outro usou o Harness Handbook.

Os resultados foram claros. O grupo que usou o Handbook foi muito melhor em encontrar os pontos certos para editar. Eles cometeram menos erros, não alteraram acidentalmente coisas que não deveriam e fizeram tudo isso usando menos poder computacional (menos "tokens", que é como a moeda que a IA gasta para pensar). O Handbook foi especialmente útil quando o código estava bagunçado, espalhado por muitos arquivos ou escondido em partes do sistema que raramente são executadas. De fato, os agentes que usaram o Handbook foram tão bons em encontrar o código certo que um modelo de IA "mais fraco" conseguiu performar quase tão bem quanto um modelo "mais forte" apenas por ter o mapa.

O artigo sugere que, à medida que os sistemas de IA se tornam mais complexos, não podemos apenas confiar em cérebros mais inteligentes; precisamos de melhores mapas. O Harness Handbook prova que, se organizarmos o código em torno do que o sistema faz em vez de onde os arquivos estão, podemos tornar a evolução desses agentes poderosos muito mais segura, rápida e confiável. Ele transforma a tarefa caótica de desenredar uma grande bola de barbante em uma jornada simples e guiada através de uma biblioteca bem iluminada.

Resumo Técnico: Harness Handbook

Declaração do Problema

A evolução dos sistemas modernos de agentes de IA é cada vez mais limitada pela dificuldade de localização de comportamento em harnesses de escala de produção. Um harness é a camada de software que constró_ui os prompts, gerencia o estado, invoca ferramentas e coordena a execução, efetivamente traduzindo as capacidades do modelo de fundação em comportamento de sistema. À medida que os requisitos mudam, desenvolvedores ou agentes de codificação devem modificar esses harnesses. No entanto, identificar todos os locais de código que implementam um pedido comportamental específico é notoriamente difícil porque:

Complexidade Estrutural: Os comportamentos são frequentemente distribuídos por arquivos não adjacentes, funções, estágios de execução e transições de estado compartilhadas.
Descompasso de Representação: Os pedidos de modificação descrevem o que o sistema deve fazer (comportamento), enquanto os repositórios são organizados pelo como o código é estruturado (arquivos, módulos, funções).
Limitações das Ferramentas Existentes: As abordagens atuais (busca de código, indexação de repositório, processamento de contexto longo) organizam a informação em torno de artefatos de implementação. Elas ajudam a localizar trechos individuais de código, mas falham em mapear explicitamente como partes dispersas trabalham juntas para produzir um comportamento específico, deixando o agente ou o desenvolvedor para inferir essas conexões manualmente.

Essa lacuna força os desenvolvedores a construir modelos mentais do sistema e os agentes a explorar repositórios de forma iterativa, muitas vezes perdendo caminhos de código dispersos ou raramente executados.

Metodologia

O artigo introduz o Harness Handbook, uma representação centrada no comportamento sintetizada automaticamente de um código-fonte de harness, e o Behavior-Guided Progressive Disclosure (BGPD), um fluxo de trabalho para utilizar esta representação.

1. Representação Harness Handbook

O Handbook reorganiza o conhecimento de implementação em torno do comportamento em tempo de execução, em vez da estrutura de arquivos. Ele consiste em duas visões complementares:

Árvore de Documentos ( $D$ ): Uma hierarquia de três níveis (L1–L3) que progride de visões gerais de alto nível do sistema para unidades detalhadas fundamentadas no código-fonte.
- L1 (Visão Geral do Sistema): Arquitetura, modelo de execução, principais estágios e fluxo de dados global.
- L2 (Visão Geral do Componente): Responsabilidades, entradas/saídas, dependências e estado local para estágios de execução específicos.
- L3 (Aprofundamento de Unidade): Entradas de implementação fundamentadas no código (funções ou arquivos) vinculadas a locais de código específicos.
Visão de Registro de Estado ( $Z$ ): Uma visão trans-estágio que rastreia relações de estado que abrangem fronteiras de estágio, garantindo que comportamentos dependentes de estado compartilhado sejam capturados mesmo que estruturalmente distantes.

A representação adere a duas regras:

Revelação Progressiva (Progressive Disclosure): Os leitores movem-se de L1 para L3 apenas quando uma tarefa exige mais detalhes.
Alinhamento Comportamento–Implementação: Todo localizador L1 ativo deve resolver-se para o repositório de origem atual. Se um localizador não puder ser revalidado, ele é congelado para evitar alucinação.

2. Pipeline de Construção

O Handbook é construído automaticamente a partir de um repositório ( $R$ ) através de três fases:

Fase I: Extração de Fatos Estáticos: O parsing determinístico extrai funções, grafos de chamada e acessos a estado. Chamadas não resolvidas são registradas em vez de presumidas.
Fase II: Organização Comportamental: As unidades de origem são mapeadas para um esqueleto de estágio de execução ( $S$ $S$ ). O pipeline suporta dois modos de folha:
- Função-como-folha: Começa de um esqueleto semente e atribui funções (ou regiões contíguas) aos estágios.
- Arquivo-como-folha: Infere o esqueleto de estágio a partir de resumos de arquivos e organiza os arquivos de acordo.
Fase III: Síntese Hierárquica: Converte a organização na árvore de documentos L1–L3 e na visão de registro de estado, validando todos os localizadores contra o código-fonte.

3. Fluxo de Trabalho de Modificação (BGPD)

O fluxo de trabalho para modificar um harness usando o Handbook envolve quatro etapas:

Localização: O agente utiliza o BGPD para navegar no Handbook de granularidade grosseira (L1/L2) para fina (L3). Ele identifica estágios relevantes e registros de estado, expande o conjunto de candidatos via grafos de chamada e, em seguida, verifica esses candidatos contra o repositório de origem atual para produzir evidência verificada ($bEq$).
Planejamento: Um planejador converte $bEq$ em um plano de edição ( $P$ ) e declarações de ação ( $\Gamma$ ).
Execução: Um executor aplica o plano ao repositório.
Resincronização: Qualquer diff não vazio dispara uma resincronização automática do Handbook. O sistema atualiza apenas as partes afetadas (usando fingerprints ou hashes de conteúdo) em vez de reconstruir todo o Handbook, garantindo que a representação permaneça consistente com o código-fonte em evolução.

Principais Contribuições

Definição de Localização de Comportamento: O artigo define formalmente a localização de comportamento como a etapa prévia de encontrar todos os locais de código que implementam um pedido comportamental antes que uma edição possa ser planejada.
Harness Handbook: Uma representação inovadora, gerada automaticamente, que vincula descrições comportamentais diretamente a implementações de código distribuídas, organizada pelo "o que o harness faz" em vez da estrutura de arquivos.
Fluxo de Trabalho BGPD: Um método para guiar agentes de codificação de descrições de comportamento de alto nível para detalhes de implementação relevantes em estágios, verificando candidatos contra a fonte viva.
Validação Empírica: Avaliação em dois harnesses de código aberto (Terminus-2 e Codex) demonstrando que o planejamento assistido pelo Handbook melhora a precisão da localização e a qualidade do plano de edição, reduzindo simultaneamente o uso de tokens.

Resultados Experimentais

Os autores avaliaram a abordagem em 60 pedidos de modificação (30 por harness) em três tipos: Consulta (Query - modificando comportamento existente), Trans-arquivo (Cross-file - adicionando capacidades que abrangem módulos) e Busca Hostil (Search-Hostile - escondendo implementações em caminhos difíceis de encontrar).

Qualidade do Plano e Custo: O planejamento assistido pelo Handbook alcançou taxas de vitória significativamente maiores em qualidade de plano (ex: +18,9% no Terminus-2) em comparação com um baseline que explora o repositório diretamente. Crucialmente, essa melhoria foi alcançada com menos tokens de planejador (reduções de 12,7% e 8,6% no Codex e Terminus-2, respectivamente), indicando eficiência em vez de apenas aumento de orçamento.
Precisão de Localização: Um planejador mais fraco (DeepSeek-V4-Pro) assistido pelo Handbook igualou a localização de sítios de implementação de modelos substancialmente mais fortes (Opus 4.8, GPT-5.5). Os escores F1 para localização de nível de arquivo e de símbolo melhoraram de 5,0 a 18,8 pontos em todas as comparações. A métrica "Errado" (Wrong - zero sobreposição com a referência) diminuiu significativamente, indicando menos falhas completas.
Robustez: Os ganhos persistiram em todos os tipos de pedidos (Consulta, Trans-arquivo, Busca Hostil) e níveis de dificuldade (Fácil, Médio, Difícil). As melhorias mais significativas foram observadas em mudanças envolvendo sítios de implementação dispersos e interações entre módulos.

Significância e Alegações

O artigo alega que a evolução de sistemas agênticos complexos depende não apenas de gerar edições, mas de determinar onde essas edições devem ser feitas. Ao tornar explícita a conexão entre comportamento e implementação, o Harness Handbook aborda o gargalo central da localização de comportamento.

Os autores posicionam este trabalho como um passo em direção à autoevolução de harness. Eles sugerem que uma representação de repositório centrada no comportamento, que se mantém sincronizada com o código, pode suportar usos mais amplos, como auditoria de comportamento e análise de impacto de regressão. O objetivo final é permitir que agentes fechem autonomamente o ciclo de localização, planejamento, execução e resincronização, movendo os harnesses de agentes em direção à auto-melhoria sem exigir orçamentos maiores de tokens de planejamento.