Embora cada implementação tenha suas particularidades, os harnesses modernos (como os que sustentam o Claude Code, o Codex e o OpenCode) convergem para um conjunto comum de componentes. Vamos a eles.
1. O Loop de Execução
É o coração do harness. O agente opera em um ciclo no estilo ReAct: recebe a tarefa, raciocina sobre o que fazer, emite uma chamada de ferramenta, observa o resultado e raciocina novamente, repetindo até concluir. O harness é quem roda esse loop, decide quando parar, impõe limites de iterações e de orçamento, e lida com falhas no meio do caminho. Diferentemente de um orquestrador tradicional de pipelines, esse loop é não determinístico: quem programa o próximo passo é o próprio LLM.
2. Gerenciamento de Contexto
A janela de contexto é o recurso mais escasso de um agente. O harness decide o que entra nela a cada turno: instruções do projeto, trechos relevantes do histórico, resultados de ferramentas, resumos de etapas anteriores. Técnicas como compactação de histórico, sumarização automática e isolamento de subtarefas em subagentes existem justamente para evitar que o contexto se polua e degrade o raciocínio do modelo.
3. Ferramentas
O catálogo de ferramentas define o que o agente consegue fazer: ler e escrever arquivos, executar comandos, buscar na web, consultar bancos de dados, chamar APIs externas (inclusive via protocolos como o MCP, o Model Context Protocol). O harness registra essas ferramentas, descreve cada uma para o modelo, executa as chamadas e formata os resultados de volta.
4. Memória e Persistência de Estado
Para compensar a ausência de estado do LLM, o harness mantém memória de curto prazo (a conversa ativa) e de longo prazo (arquivos, logs, resumos, preferências salvas). É isso que permite a um agente retomar uma tarefa interrompida ou acumular conhecimento sobre um projeto ao longo de semanas.
5. Verificação e Sensores
Um bom harness não confia cegamente no modelo. Ele instala verificadores: testes automatizados, linters, validações de schema, checagens estruturais. O ponto-chave é que esses sensores produzem sinais otimizados para consumo pelo próprio LLM, ou seja, mensagens de erro que já incluem instruções de correção, permitindo que o agente se autocorrija dentro do loop.
6. Guardrails e Sandbox
Agentes executam código e comandos, e isso exige limites. O harness controla permissões (quais ferramentas exigem aprovação humana), isola a execução em sandboxes e impõe restrições de rede e de sistema de arquivos. É a diferença entre dar autonomia e dar carta branca.
7. Observabilidade
Por fim, tudo o que o agente faz precisa ser rastreável: quais ferramentas chamou, quantos tokens consumiu, quantos turnos levou, onde falhou. Sem telemetria, é impossível diagnosticar e melhorar o sistema. Métricas como custo por tarefa e número de iterações do loop são indicadores diretos da qualidade do harness.
Uma forma elegante de organizar os mecanismos de um harness, popularizada em artigos publicados no site de Martin Fowler, é dividi-los em duas famílias, emprestadas da teoria de controle:
• Guias (controles feedforward): antecipam o comportamento do agente e o direcionam antes da ação. Exemplos: arquivos de instrução do projeto (AGENTS.md, CLAUDE.md), templates, convenções de código documentadas, especificações. Guias aumentam a probabilidade de o agente acertar na primeira tentativa.
• Sensores (controles de feedback): observam o resultado depois da ação e permitem a autocorreção. Exemplos: testes, linters customizados, validadores estruturais, monitores de consistência. Sensores transformam erros em sinais acionáveis dentro do próprio loop.
Sistemas maduros combinam os dois e adicionam ainda uma terceira camada que alguns times chamam de coleta de lixo: agentes que rodam periodicamente para encontrar inconsistências na documentação ou violações de arquitetura, combatendo a entropia natural de bases de código geradas em alta velocidade.
No próximo post veremos um exemplo de Harness na prática.
David Matos
Referências: