Harness de agente
Por que isso importa
O mesmo modelo pode ter desempenhos muito diferentes dependendo do harness. Em benchmarks de programação como SWE-bench Verified e Terminal-Bench, mudar apenas o harness pode mover as pontuações em muitos pontos, e é por isso que os rankings listam o modelo e o sistema de agente juntos. Quando um produto de agente parece mais inteligente do que uma chamada direta à API do mesmo modelo, o motivo é o harness.
Para quem constrói, o harness é onde vai a maior parte da engenharia. Em geral você não pode mudar o modelo, mas pode mudar o que ele vê, quais ferramentas ele tem e o que acontece quando algo dá errado.
Em profundidade
Um modelo de linguagem sozinho apenas mapeia texto para texto. Ele não consegue ler um arquivo, executar um comando ou lembrar o que fez uma hora atrás. O harness é o programa em volta do modelo que torna essas coisas possíveis. Ele envia um prompt ao modelo, executa as chamadas de ferramentas que o modelo pede, devolve os resultados e repete até a tarefa terminar.
Um atalho útil: agente = modelo + harness. O Claude Code, o Codex CLI da OpenAI, o modo agente do Cursor e projetos open source como OpenHands e SWE-agent são todos harnesses. Também são os frameworks que as pessoas usam para construir o seu, como o Claude Agent SDK, o OpenAI Agents SDK e o LangGraph. Pesquisadores costumam chamar a mesma coisa de scaffolding (andaime).
O que um harness faz
- O loop: chamar o modelo, executar as chamadas de ferramentas, devolver os resultados, repetir e decidir quando parar.
- Ferramentas: defini-las, validar os argumentos, executá-las e formatar os resultados para que sejam curtos e úteis. O artigo do SWE-agent chamou isso de agent-computer interface e mostrou que o design das ferramentas importa tanto quanto os prompts.
- Gerenciamento de contexto: montar o prompt de sistema, carregar as instruções do projeto, resumir o histórico antigo (compactação) quando a janela de contexto enche e manter o cache de prompt intacto.
- Permissões e sandboxing: decidir quais ações rodam automaticamente, quais precisam de aprovação humana e no que o agente pode mexer.
- Memória e estado: anotações, listas de tarefas e arquivos que sobrevivem além de uma janela de contexto, além de checkpoints para desfazer.
- Orquestração: disparar subagentes, rodar ferramentas em paralelo, tentar de novo após erros e impor limites de passos e de tokens.
Um harness mínimo
O loop central é pequeno:
messages = [{"role": "user", "content": task}]
while True:
reply = model(messages, tools=tools)
messages.append(reply)
if not reply.tool_calls:
break
for call in reply.tool_calls:
messages.append(run_tool(call))
Todo o resto em um harness de produção existe para lidar com o que esse loop ignora: tarefas longas, falhas, segurança e custo.
Cada vez mais fino
Os primeiros sistemas de agentes precisavam de muito andaime: planos rígidos, parsers de saída, recuperação construída à mão e muitos prompts especializados. À medida que os modelos melhoraram no uso de ferramentas e no planejamento, boa parte disso se tornou desnecessária ou até prejudicial, porque impedia o modelo de usar o próprio julgamento. É a lição amarga aplicada aos agentes. Muitos dos harnesses mais fortes de hoje são deliberadamente simples: um bom loop, algumas ferramentas gerais como um shell e um editor de arquivos, e um gerenciamento cuidadoso do contexto.
Disso decorre um hábito prático: quando sair um modelo novo, experimente remover partes do seu harness e veja se os resultados melhoram.
Harness e avaliação
Como o harness muda os resultados, os números de benchmark só são comparáveis quando o harness é o mesmo. Nas avaliações de segurança, um harness fraco é um risco real, porque pode fazer um modelo parecer menos capaz do que é. Por isso os avaliadores investem em elicitação: dar ao modelo boas ferramentas e orçamento suficiente para mostrar o que ele realmente consegue fazer.
Escolher ou construir um
Comece com um harness ou SDK existente, a menos que você tenha necessidades incomuns. Invista primeiro em ferramentas com descrições claras e saídas compactas, depois no gerenciamento de contexto e depois nas permissões. Registre em log cada passo do loop. Quando algo falhar, leia a transcrição: a maioria das falhas de agentes vem do que foi mostrado ao modelo, não da capacidade do modelo.