Engenharia de Harness para Agentes

Um agente de codificação é o modelo mais tudo o que é construído ao seu redor. A engenharia de harness trata esse arcabouço como um artefato vivo, ajustando-o sempre que o agente comete um erro.

Simplificando: sempre que um agente falha, você projeta uma solução permanente para que ele nunca mais cometa exatamente aquele erro.

Nos últimos dois anos, a indústria debateu modelos: qual é o mais inteligente, qual escreve o React mais limpo ou qual alucina menos. Embora essa conversa seja importante, ela ignora a outra metade do sistema.

O modelo é apenas uma entrada para um agente em execução. O resto é o harness: os prompts, ferramentas, políticas de contexto, hooks, sandboxes, subagentes, loops de feedback e caminhos de recuperação que envolvem o modelo para que ele possa realmente concluir tarefas.

Um modelo decente com um ótimo harness supera consistentemente um ótimo modelo com um harness ruim. Cada vez mais, o trabalho de engenharia mais interessante não está em selecionar o modelo, mas em projetar o arcabouço ao seu redor.

Essa disciplina agora tem um nome. @Vtrivedy10 cunhou o termo engenharia de harness, fornecendo uma análise clara do que realmente é um harness e por que cada peça existe. Outras vozes da indústria, como @dexhorthy rastreando padrões emergentes, a HumanLayer enquadrando falhas de agentes como "problemas de habilidade" de configuração, a equipe de engenharia da Anthropic publicando guias sobre design de aplicativos de longa duração e Birgitta Böckeler explorando a experiência do lado do usuário, estão todas convergindo para a mesma ideia.

Este post une esses fios.

O que é um Harness, Realmente?

A definição central de Trivedy faz a maior parte do trabalho pesado:

Agente = Modelo + Harness. Se você não é o modelo, você é o harness.

Um harness abrange cada pedaço de código, configuração e lógica de execução que não é o modelo em si. Um modelo bruto não é um agente. Ele só se torna um quando um harness fornece estado, execução de ferramentas, loops de feedback e restrições aplicáveis.

Concretamente, um harness inclui:

• Prompts de sistema, CLAUDE.md, AGENTS.md, arquivos de habilidade e instruções de subagentes.
• Ferramentas, habilidades, servidores MCP e suas descrições técnicas.
• Infraestrutura agregada, como sistema de arquivos, sandboxes e navegadores headless.
• Lógica de orquestração para gerar subagentes, lidar com transferências e rotear modelos.
• Hooks e middleware para execução determinística, como verificações de lint ou compactação de contexto.
• Ferramentas de observabilidade para logs, rastreamentos, custo e medição de latência.

Em sua essência, um agente é um sistema que executa ferramentas em um loop para atingir um objetivo. A verdadeira habilidade está em projetar tanto as ferramentas quanto esse loop.

Embora isso represente uma área de superfície massiva, é a sua área de superfície, não a do provedor do modelo. Claude Code, Cursor, Codex, Aider e Cline são todos harnesses. O modelo subjacente pode ser idêntico entre as plataformas, mas o comportamento que você experimenta é dominado pelo harness.

Vamos reformular o "Problema de Habilidade"

É comum ver engenheiros culpando o modelo quando um agente faz algo sem sentido, muitas vezes arquivando o problema como algo para "esperar a próxima versão" corrigir.

A mentalidade da engenharia de harness rejeita esse padrão. As falhas geralmente são um tanto legíveis. Se o agente ignorou uma convenção, adicione-a ao AGENTS.md. Se ele executou um comando destrutivo, escreva um hook para bloqueá-lo. Se ele se perdeu em uma tarefa de 40 etapas, divida a arquitetura em um planejador e um executor. Se ele termina consistentemente com código quebrado, conecte um sinal de pressão reversa de verificação de tipo no loop.

Como a HumanLayer coloca: "Não é um problema de modelo. É um problema de configuração." Considere os benchmarks de desempenho: um modelo líder rodando dentro de um framework padrão geralmente pontua drasticamente menos do que o exato mesmo modelo rodando em um harness personalizado e altamente ajustado. Mover um modelo para um ambiente com melhores ferramentas de base de código, prompts mais precisos e pressão reversa mais afiada pode desbloquear capacidades que a configuração original deixou para trás.

A lacuna entre o que os modelos de hoje podem teoricamente fazer e o que você realmente os vê fazendo é, em grande parte, uma lacuna de harness.

O Catraca: Cada erro se torna uma regra

O hábito mais vital na engenharia de harness é tratar os erros do agente como sinais permanentes - não como acasos pontuais para repetir e esquecer.

Se um agente envia um PR com um teste comentado que é mesclado por acidente, isso é uma entrada. A próxima iteração do AGENTS.md deve afirmar: "Nunca comente testes; exclua ou corrija-os." O próximo hook de pré-commit deve sinalizar automaticamente .skip( no diff. O subagente revisor deve ser atualizado para bloquear testes comentados.

Restrições devem ser adicionadas apenas quando você observa uma falha real e removidas apenas quando um modelo capaz as torna redundantes. Cada linha em um bom prompt de sistema deve remontar a uma falha histórica específica.

Por causa disso, a engenharia de harness é uma disciplina, em vez de um framework único para todos. O harness certo para uma base de código específica é inteiramente moldado por seu histórico de falhas único.

Trabalhando de trás para frente a partir do comportamento

A maneira mais eficaz de projetar um harness é começar com o comportamento desejado e construir o componente que o entrega: Comportamento que queremos → Design do harness para alcançá-lo.

Cada peça do harness deve ter um trabalho distinto. Se você não consegue nomear o comportamento específico que um componente existe para entregar, ele deve ser removido.

Sistema de Arquivos e Git - estado durável

O sistema de arquivos é fundamental. Os modelos só podem operar com o que cabe em sua janela de contexto. Um sistema de arquivos fornece um espaço de trabalho para ler dados, um lugar para descarregar trabalho intermediário e uma superfície para vários agentes coordenarem.

Adicionar Git fornece versionamento gratuito, permitindo que o agente acompanhe o progresso, faça experimentos em branches e reverta erros.

Bash e Execução de Código: ferramentas de propósito geral

A maioria dos agentes opera em um loop ReAct: raciocinar, agir por meio de uma chamada de ferramenta, observar, repetir. Em vez de pré-construir uma ferramenta para cada ação concebível, dar ao agente acesso ao bash permite que ele construa o que precisa na hora.

Os agentes geralmente se destacam em comandos de shell, tornando o bash e a execução de código a estratégia padrão para resolução autônoma de problemas.

Sandboxes e Ferramentas Padrão

O bash só é útil se for executado com segurança. Sandboxes fornecem aos agentes um ambiente isolado para executar código, inspecionar arquivos e verificar o trabalho sem arriscar a máquina host.

Um bom sandbox vem com padrões sólidos: runtimes de linguagem pré-instalados, CLIs de teste e navegadores headless, permitindo que o agente observe seu próprio trabalho e feche o loop de autoverificação.

Memória e Pesquisa: Aprendizado Contínuo

Os modelos não têm conhecimento além de seus pesos de treinamento e contexto atual. Os harnesses preenchem essa lacuna usando arquivos de memória (como AGENTS.md) que injetam conhecimento em cada sessão.

Para informações em tempo real, como novas versões de bibliotecas ou dados ao vivo, a pesquisa na web e ferramentas MCP são incorporadas diretamente no harness.

Combatendo a Rotação de Contexto

Os modelos degradam seu raciocínio à medida que suas janelas de contexto se enchem. Os harnesses gerenciam essa escassez usando três técnicas principais:

• Compactação: Resumindo e descarregando inteligentemente o contexto mais antigo para evitar erros de API.
• Descarregamento de chamadas de ferramenta: Armazenando saídas massivas de ferramentas (como logs de 2.000 linhas) no sistema de arquivos, mantendo apenas os cabeçalhos e rodapés essenciais no contexto.
• Divulgação progressiva: Revelando instruções e ferramentas apenas quando uma tarefa as exige explicitamente, em vez de carregar tudo na inicialização.

Execução de Longo Horizonte

O trabalho autônomo e de longa duração sofre com parada precoce e má decomposição de problemas. Os harnesses combatem isso por meio do design estrutural:

• Loops: Interceptando a tentativa de saída de um modelo e forçando-o a continuar em direção a uma meta de conclusão em uma nova janela de contexto.
• Planejamento: Forçando o modelo a decompor metas em um arquivo de plano passo a passo, verificando seu trabalho por meio de hooks de autoverificação após cada etapa.
• Divisões: Separando a geração e a avaliação em agentes distintos, prevenindo o viés positivo inerente que os modelos têm ao avaliar seu próprio trabalho.

Hooks são sua Camada de Imposição

Os hooks preenchem a lacuna entre solicitar uma ação e impô-la. Eles são executados em ciclos de vida específicos: antes de uma chamada de ferramenta, após uma edição de arquivo ou antes de um commit. Os hooks bloqueiam comandos destrutivos, impõem formatação automática para economizar tokens e executam suítes de teste.

Idealmente, o sucesso é silencioso e as falhas são detalhadas. Se uma verificação de tipo passa, o agente não ouve nada; se falha, o erro é injetado diretamente de volta no loop para autocorreção.

Aqui está o livro de regras e a escolha de ferramentas

Um arquivo markdown simples na raiz de um repositório ainda é o ponto de configuração de maior alavancagem. No entanto, deve ser tratado como a lista de verificação de um piloto, não como um guia de estilo. Mantenha-o curto e garanta que cada regra seja conquistada por meio de uma falha passada.

A mesma disciplina se aplica às ferramentas. Dez ferramentas altamente focadas sempre superarão cinquenta sobrepostas.

Além disso, como as descrições das ferramentas preenchem o prompt, integrações externas maliciosas ou descuidadas (como servidores MCP não verificados) podem injetar prompts ruins no agente antes mesmo de ele começar a trabalhar.

Como isso se parece na produção

A imagem pública mais clara que já vi de um harness maduro é a análise (estimada) de Fareed Khan da arquitetura do Claude Code.

Quase todos os conceitos da seção anterior aparecem neste diagrama como um componente nomeado. A injeção de contexto é a camada de conhecimento. O estado do loop reside no armazenamento de memória e no isolador de árvore de trabalho. Os hooks de ação destrutiva ficam atrás do gate de permissão. As firewalls de contexto de subagente são toda a camada de múltiplos agentes. O registro de despacho de ferramentas é onde os servidores MCP e o bash se conectam. A trajetória do Claude Code é sobre o harness tanto quanto sobre o modelo subjacente.

Harnesses Não Encolhem, Eles se Movem

À medida que os modelos melhoram, a necessidade de um harness não desaparece - ela muda.

É tentador supor que modelos melhores tornam o arcabouço obsoleto. Por exemplo, atualizações recentes de modelos reduziram drasticamente a necessidade de mitigações de "ansiedade de contexto". Mas, à medida que o piso sobe, o teto também sobe. Tarefas que antes eram inatingíveis agora estão em jogo, trazendo modos de falha inteiramente novos.

Cada componente em um harness codifica uma suposição sobre o que o modelo não pode fazer sozinho. Quando o modelo melhora, o arcabouço desatualizado deve ser removido, e um novo arcabouço deve ser construído para alcançar o próximo horizonte.

E o Loop de Treinamento?

Há um loop de feedback ativo entre o design do harness e o treinamento do modelo.

Os modelos de hoje são frequentemente pós-treinados com harnesses específicos no loop, criando um certo grau de overfitting. O modelo fica excepcionalmente bom nas ações específicas que os designers do harness priorizaram (por exemplo, operações de sistema de arquivos, bash, despacho de subagentes).

Isso torna o harness um sistema vivo, não um arquivo de configuração estático, e prova que o "melhor" harness é aquele otimizado especificamente para suas tarefas e fluxos de trabalho distintos.

Harness-como-Serviço (HaaS)

A indústria está mudando de construir em APIs LLM (que fornecem conclusões) para construir em APIs de Harness (que fornecem um runtime). SDKs agora oferecem o loop, ferramentas, gerenciamento de contexto, hooks e sandboxes prontos para uso.

Em vez de construir orquestração do zero, o padrão moderno é selecionar um framework de harness, configurar seus pilares principais e focar puramente no design de prompts e ferramentas específicos do domínio.

É isso que torna a solução de problemas escalável: você está ajustando uma superfície de configuração bem estruturada, em vez de reinventar toda a arquitetura do agente.

Para Onde Isso Está Indo

Se você olhar para os principais agentes de codificação hoje, eles se parecem mais entre si do que seus modelos subjacentes. Os modelos diferem, mas os padrões de harness estão convergindo. A indústria está rapidamente identificando o arcabouço de suporte necessário para transformar texto generativo em software entregável.

Os problemas em aberto mais empolgantes estão indo além de agentes únicos: orquestrar múltiplos agentes em paralelo, permitir que agentes analisem seus próprios rastros para corrigir falhas em nível de harness e construir ambientes que montam ferramentas dinamicamente no momento exato.

Em última análise, esta é a fase em que os harnesses param de ser arquivos de configuração estáticos e começam a agir muito mais como compiladores.

Se você está procurando um ótimo framework de harness para agentes, @FredKSchott escreveu o Flue. Ele é sólido e foi aparentemente inspirado por uma versão anterior deste post!