O que é uma harness e por que a distinção com framework importa

Existe uma confusão terminológica que prejudica quem está começando a construir agentes: harness e framework são usados de forma intercambiável, mas representam coisas estruturalmente diferentes.

Um framework como LangChain, LangGraph ou CrewAI te dá abstrações e componentes: grafos de estado, chains, conectores de memória, retrievers. Você monta o agente a partir dessas peças. A premissa é que você, o arquiteto, vai configurar o sistema.

Uma harness é o inverso: ela já é um agente funcionando. Você não monta nada. Você fornece o objetivo, a harness cuida do resto. Claude Code, Codex, Cursor são exemplos. Cada um começou de um problema concreto e construiu uma arquitetura que resolve aquele problema de forma autônoma.

A distinção é importante porque quando você decide construir um agente, você está escolhendo entre duas coisas muito diferentes: montar um sistema com peças de framework, ou construir uma harness do zero para o seu problema específico.

Os nove componentes

Uma harness moderna tem estrutura interna bem definida. Não é mágica, é engenharia. Esses são os componentes que aparecem em praticamente todas as implementações sérias:

While loop: o coração de qualquer harness. O agente lê o contexto, decide qual ferramenta chamar, executa, injeta o resultado no contexto, e repete. Esse loop continua até o agente produzir texto puro sem chamar ferramenta, ou até atingir um limite de iterações. É simples. É o que transforma um modelo de um-turno numa entidade que persiste até o problema estar resolvido.

Context management: a cada turno, o contexto cresce. Mensagens, resultados de ferramentas, histórico. Em algum momento você atinge o limite do modelo. A harness precisa decidir o que manter verbatim, o que sumarizar, e o que descartar. Compactação mal feita destrói informação crítica. Claude Code, por exemplo, mantém as mensagens mais recentes integrais e sumariza as mais antigas quando se aproxima do limite de contexto.

Skills e ferramentas: ferramentas são primitivos (ler arquivo, executar bash, buscar código). Skills são conhecimento de domínio codificado, geralmente em arquivos markdown. A distinção: ferramentas são universais, skills são específicas do time ou do sistema. O registry centraliza o que está disponível, as permissões de cada ferramenta, e como as chamadas são despachadas.

Gestão de subagentes: quando uma tarefa é grande demais ou paralela demais para uma thread única, a harness cria subagentes com contexto isolado, conjunto restrito de ferramentas, e system prompt focado. O padrão é span-restrict-collect: cria o subagente, limita o escopo dele, coleta o output.

Skills built-in: toda harness de código vem com um conjunto básico de ferramentas que não são negociáveis: ler arquivo, editar arquivo, executar bash, navegar no codebase. Sem isso, o agente não consegue agir. Harnesses mais maduras também incluem skills de nível mais alto: como fazer commit, abrir pull request, rodar testes.

Persistência de sessão: se o processo travar, tudo que não foi salvo em disco se perde. Harnesses sérias salvam cada evento em disco de forma append-only (JSON ou markdown) enquanto acontece. Isso permite retomar exatamente de onde parou. O arquivo só cresce, nunca é sobrescrito, então falha num ponto não corrompe o que veio antes.

Montagem do system prompt: o system prompt não é uma string estática na maioria das harnesses maduras. É um pipeline que percorre diretórios em busca de arquivos de instrução (CLAUDE.md, agents.md, arquivos de memória) e os injeta no prompt dinamicamente. Ordem importa aqui: parte estática primeiro, conteúdo dinâmico depois, para não quebrar o cache de prefixo.

Lifecycle hooks: extensibilidade sem tocar na harness. Hooks permitem injetar lógica antes ou depois de qualquer chamada de ferramenta. Um pre-hook pode negar ou modificar a chamada. Um post-hook pode inspecionar o resultado e logar. É assim que empresas adotam harnesses sem precisar forkar o código: elas plugam seus guardrails via hooks.

Permissões e segurança: cada ferramenta declara o nível mínimo de acesso que precisa (leitura, workspace, acesso total). A harness verifica isso antes de despachar a chamada. Para ferramentas genéricas como bash, a classificação é dinâmica: ls é read-only, rm -rf exige acesso total. Além das regras estáticas, o agente pode pausar e pedir aprovação humana antes de ações destrutivas.

O que isso muda na prática

Quando construo agentes como o Athena ou o Nexus ZDT, esses componentes estão presentes mesmo quando não são nomeados explicitamente. O pipeline de ingestão do Nexus ZDT tem um while loop implícito no processamento de filas. O context management do Athena está na decisão de quais blocos de schema incluir em cada chamada. Os lifecycle hooks são os guardrails que sanitizam dados pessoais antes de qualquer LLM ver.

A diferença entre ter esse vocabulário e não ter é que com ele você pode identificar exatamente onde um problema está ocorrendo e qual componente precisar ser corrigido. Sem ele, você está depurando uma caixa preta.

Qual dos nove componentes é o mais difícil de implementar bem no tipo de agente que você está construindo?