O que é um agent harness e por que ele importa tanto?

Agent harness é todo o software que fica entre o modelo e o mundo em um agente de IA: o que entra na janela de contexto, quais ferramentas existem e como são descritas, o que precisa de confirmação, onde o comando roda e quando parar de gastar. O modelo escolhe a ação. O harness decide o que ele pode ver, o que pode fazer e quanto custa.

Importa porque duas ferramentas rodando o mesmo modelo, no mesmo dia, com o mesmo pedido, entregam resultados diferentes o bastante para parecerem modelos diferentes. Quase toda a discussão pública é sobre qual modelo usar. Boa parte da diferença está nas camadas que ficam em volta dele.

Isso torna o diagnóstico difícil. Quando um agente falha, o primeiro instinto é trocar de modelo, e o culpado costuma estar do lado de fora. Este artigo trata do que essa camada externa faz, e não de adotar uma biblioteca ou escrever o loop você mesmo, que é uma decisão vizinha e separada.

O que acontece entre um turno e o seguinte

O modelo faz uma coisa só: recebe uma sequência de tokens e devolve outra. Tudo que parece iniciativa do agente acontece do lado de fora.

Uma iteração completa, na ordem em que roda:

1. O harness monta a requisição: instruções de sistema, histórico da conversa, resultados das ferramentas anteriores, catálogo de ferramentas disponíveis, configuração do projeto.
2. O modelo responde com texto e, possivelmente, um pedido de ferramenta.
3. O harness interpreta o pedido e valida os argumentos contra o schema.
4. Verifica se aquela ação específica precisa de confirmação humana.
5. Executa, dentro de algum limite de sistema de arquivos, rede e tempo.
6. Recebe a saída, que pode ter 200 bytes ou 40 MB, e decide quanto disso volta.
7. Reinjeta o resultado no contexto, em algum formato e em alguma posição.
8. Atualiza o estado persistido da sessão.
9. Confere o orçamento de tokens e de passos.
10. Decide se chama o modelo de novo.

O modelo participa do passo 2. Os outros nove são código de alguém, com escolhas que ninguém documentou porque parecem detalhe de implementação.

Nenhum desses passos é neutro. O passo 6 sozinho carrega uma decisão que muda a tarefa inteira: quando uma busca devolve 3.000 linhas, o harness pode cortar nas primeiras 50, cortar nas últimas 50, resumir com uma segunda chamada de modelo, ou gravar em arquivo e devolver só o caminho. As quatro opções são defensáveis. Elas produzem trajetórias que não se parecem.

O harness também decide o que o modelo nunca vê. Um comando que sai com código de erro pode voltar como a mensagem de erro completa, como um resumo de uma linha, ou como nada além de “falhou”. Na terceira variante o agente tenta de novo às cegas, porque a informação que resolveria o problema foi descartada antes de chegar nele. Ninguém escreve essa decisão na documentação, e ela é a origem de uma classe inteira de repetição inútil.

Por que a discussão pública é quase toda sobre o modelo

Modelo tem nome, versão, data de corte, placar de benchmark e página de lançamento. Harness tem número de release e um changelog que ninguém lê.

O efeito é que a única variável visível na conversa é a que menos varia entre duas ferramentas concorrentes. Em julho de 2026, boa parte das ferramentas de agente de código roda os mesmos três ou quatro modelos de fronteira, muitas vezes o mesmo modelo por padrão. A diferença de experiência entre elas continua grande. Ela não pode estar no modelo, porque o modelo é o mesmo.

Há um segundo motivo, menos confortável: harness é difícil de medir publicamente. Um placar de benchmark reporta modelo e pontuação, e o scaffold usado vira uma nota de rodapé, quando aparece. Duas submissões com o mesmo modelo e pontuações distantes são lidas como ruído experimental, não como o resultado principal.

O que já foi medido com o modelo fixo

Três resultados publicados isolam uma decisão de harness e mostram o tamanho do efeito sem trocar de modelo.

O formato da ação. Um trabalho de 2024 comparou três formas de o agente pedir uma ação: JSON, texto em formato fixo e código Python executável. Testaram 17 modelos no API-Bank e num benchmark próprio. A versão em código chegou a 20% a mais de taxa de sucesso¹. Nada no modelo mudou. Mudou como o harness representa a ação e o que ele aceita de volta.

A interface entre o agente e a máquina. Outro trabalho de 2024 partiu de uma observação simples: o terminal e o editor foram desenhados para humanos, com rolagem, cores e paginação que não ajudam quem lê tudo de uma vez. Os autores construíram uma interface específica para o agente — navegação de arquivo, edição com verificação e execução de teste — e reportaram 12,5% de pass@1 no SWE-bench, o estado da arte no momento em que o trabalho saiu². O número envelheceu: em julho de 2026 ele serve como marco histórico, não como referência. O que não envelheceu é o achado, que era o objetivo declarado do paper: o desenho da interface muda o comportamento do agente.

A posição da informação no contexto. Um estudo de 2023 mediu o que acontece quando a informação relevante muda de lugar dentro de um contexto longo. O desempenho é mais alto quando ela está no começo ou no fim, e cai no meio³. O experimento usou modelos daquela época, e a magnitude mudou desde então. A parte que continua valendo é mais fraca e mais útil: a posição não é neutra, e quem escolhe a posição de cada resultado de ferramenta é o harness, não você.

Nenhum desses três é um resultado sobre inteligência. São resultados sobre encanamento, e é encanamento que a maioria dos times não instrumenta.

As seis áreas onde as decisões ficam

As sete camadas da figura anterior se agrupam em seis áreas de decisão. O sandbox é consequência da política de permissão, e subagente é uma forma de gestão de contexto: cada um recebe uma janela limpa e devolve só o resumo.

Contexto. Que fração do histórico sobrevive, o que é resumido, o que é descartado, o que volta a ser lido do disco quando faz falta. É a camada com mais efeito e a menos visível, porque a perda acontece em silêncio: o agente não avisa que esqueceu, ele só age como se nunca tivesse visto.

Ferramentas. Quais existem, como são descritas, quantas ficam carregadas ao mesmo tempo e como o harness apresenta 80 delas sem gastar contexto com 78 que não serão usadas. Descrição de ferramenta é prompt, com todos os efeitos de prompt, e quase nunca é tratada como tal.

Extensão. Como você acrescenta capacidade sem tocar no código do harness: servidores MCP, scripts, hooks, procedimentos guardados. Define o teto do que dá para fazer sem trocar de ferramenta.

Permissão. O que roda direto, o que para e pergunta, o que é proibido sempre. Errar para o lado permissivo produz incidente; errar para o restritivo produz um agente que interrompe tanto que sai mais barato fazer à mão.

Sessão. O que sobrevive ao fim da execução e o que acontece quando a janela enche no meio de uma tarefa. Retomar de onde parou é uma capacidade do harness, não do modelo, que não tem memória entre chamadas.

Custo. Limite de passos, limite de tokens, o que dispara aviso, o que interrompe. Sem essa camada você descobre o teto pela fatura.

As seis se contaminam, e é isso que torna o diagnóstico traiçoeiro. Um catálogo grande de ferramentas gasta contexto, o que antecipa a compactação, o que faz o agente esquecer uma decisão de duas iterações atrás e refazer trabalho, o que gasta orçamento. O sintoma aparece no custo. A causa está na camada de ferramentas. Trocar de modelo não move nenhuma das duas.

O mesmo modelo, dois harness

Considere a tarefa “descubra por que o cálculo de frete está ignorando o cupom”. O modelo é o mesmo nos dois lados.

O harness A oferece uma ferramenta de leitura que devolve o arquivo inteiro. O agente abre 40 arquivos, a janela enche na iteração 12, a compactação resume o histórico e o resumo perde a linha exata que continha a pista. Ele recomeça a busca com menos informação do que tinha antes, e essa é a parte cara: o segundo ciclo custa mais tokens e chega a menos.

O harness B oferece busca por padrão, leitura por intervalo de linhas e um lugar para gravar achados fora do contexto. O agente lê três trechos, anota o número da linha, e o que ele anotou continua lá depois da compactação.

A diferença não está em raciocínio. Está em quais ferramentas existem e no que acontece com a saída delas.

Onde o harness não ajuda

Mais harness não é melhor, e essa é a correção mais importante deste artigo.

Scaffold complexo perde para pipeline fixo com frequência. Um trabalho de 2024 montou um processo de três fases — localizar, corrigir, validar — sem deixar o modelo escolher o próximo passo, e chegou a 32,00% no SWE-bench Lite, a US$ 0,70 por problema, à frente de todos os agentes open-source da época⁴. A leitura razoável é que parte do que se chama de harness é complexidade substituindo uma capacidade que o modelo já tem, e que atrapalha ao competir com ela.

Harness não conserta inconsistência. O mesmo agente, na mesma tarefa, oito vezes seguidas, não dá oito vezes o mesmo resultado. Um benchmark de 2024 mediu isso com uma métrica de sucesso em todas as k tentativas e reportou pass^8 abaixo de 25% no domínio de varejo, com o gpt-4o resolvendo menos de 50% das tarefas em uma tentativa⁵. Nenhuma camada de permissão ou de contexto transforma isso em confiabilidade; elas só reduzem o custo de cada falha.

O harness gruda no modelo para o qual foi ajustado. Descrição de ferramenta, formato de saída esperado e instruções de sistema são afinados contra uma família de modelos. Trocar de família costuma derrubar o resultado, o que faz o harness parecer melhor do que é no modelo de casa e pior do que é fora dele.

Cada camada custa. Verificação de permissão adiciona uma ida ao usuário. Sandbox adiciona latência de inicialização. Catálogo de ferramentas adiciona tokens em toda chamada. Uma camada que evita uma falha rara e custa 3% em toda execução pode não se pagar.

A atribuição fica embaralhada na prática. Quando uma ferramenta melhora de um mês para o outro, costuma ter trocado o modelo padrão e mexido em três camadas do harness na mesma janela. Do lado de fora não dá para separar. É por isso que a comparação útil é a que você roda em casa, com o modelo travado, e não a leitura de uma nota de release.

O custo do harness, em ordem de grandeza

A parte mensurável é o catálogo de ferramentas, porque ele é reenviado a cada iteração. Um schema de ferramenta com cinco parâmetros e descrições curtas costuma ficar entre 150 e 400 tokens, dependendo do tokenizador. Quarenta ferramentas carregadas colocam de 6.000 a 16.000 tokens em toda chamada, antes de qualquer histórico. Numa tarefa de 30 iterações isso vira de 180 mil a 480 mil tokens só de catálogo.

Prompt caching corta a maior parte disso enquanto o prefixo não muda, o que transforma “quais ferramentas ficam carregadas” numa decisão de custo com efeito composto. Trate os números acima como ordem de grandeza: conte os seus, é uma linha de código e vale mais que qualquer estimativa deste artigo.

Como medir o harness que você já usa

1. Registre a trajetória completa. Não a resposta final: cada requisição enviada e cada resultado de ferramenta como o modelo os recebeu. Sem isso toda análise de falha vira palpite.
2. Conte os tokens por parte da requisição antes de discutir modelo. Instruções de sistema, catálogo de ferramentas, histórico e resultados. Um dos quatro costuma estar consumindo mais do que você imagina.
3. Leia a saída de ferramenta como o modelo a recebeu. O terminal mostra cores e paginação; o modelo recebe texto truncado em algum ponto que alguém escolheu.
4. Fixe o modelo e troque uma camada por vez. Duas variáveis ao mesmo tempo não produzem conclusão.
5. Rode a mesma tarefa real em dois harness com o mesmo modelo. Vinte tarefas do seu próprio repositório dizem mais sobre a sua escolha do que qualquer placar público.

Os cinco passos carregam um viés declarado: todos supõem que a resposta está no que o modelo recebeu, e não no modelo. É o lugar mais barato de olhar primeiro, e os três resultados medidos mais acima são a razão para começar por ele.

Footnotes

1. Wang et al. (2024) compararam JSON, texto em formato fixo e código Python executável como espaço de ação, em 17 modelos, e mediram até 20% a mais de taxa de sucesso com a versão em código. ↩

2. Yang et al. (2024) construíram uma interface desenhada para o agente em vez de reaproveitar a do humano, e o objetivo declarado do trabalho era medir quanto o desenho dessa interface afeta o desempenho. ↩

3. Liu et al. (2023) mediram queda de desempenho quando a informação relevante fica no meio de um contexto longo, em perguntas sobre múltiplos documentos e em recuperação de chave-valor. ↩

4. Xia et al. (2024) mostraram que um processo fixo de três fases, sem decisão autônoma de próximo passo, superou os agentes open-source da época no SWE-bench Lite com custo por instância menor. ↩

5. Yao et al. (2024) propuseram a métrica pass^k, que exige sucesso em todas as k tentativas, e mediram queda acentuada de confiabilidade entre uma tentativa e oito. ↩