Harness: A Camada Invisível Entre o Modelo e o Mundo

Fundamento

O que é um harness em inteligência artificial?

A palavra vem do inglês harness, “arreio” — o aparato que prende e controla um animal de tração. A metáfora é precisa: o modelo fornece a força de decisão, o harness fornece a estrutura que transforma essa decisão em movimento real e limita até onde ela pode ir.

As seis funções que um harness exerce

Descrever o harness apenas como “quem executa” subestima o papel. Na prática, ele exerce pelo menos seis funções distintas, e cada uma delas é uma decisão de engenharia com consequência direta no comportamento observado do sistema:

1. Executa a ação solicitada, com as permissões que o ambiente lhe concede.
2. Estrutura o resultado em um formato definido — o envelope de retorno —, decidindo quais campos existem e quais não existem.
3. Reinsere o histórico da conversa a cada nova chamada, já que o modelo não guarda nada por conta própria.
4. Compacta esse histórico quando ele excede o limite de processamento, escolhendo o que preservar e o que resumir.
5. Impõe o critério de parada: limite de tokens, timeout, número máximo de iterações.
6. Valida a solicitação recebida — tipicamente o formato, nem sempre a intenção.

Nenhuma dessas seis funções é visível para o modelo, a menos que o harness escolha escrevê-la em texto. É essa invisibilidade que dá título ao livro.

Mecanismo

Como funciona o ciclo de tool calling, passo a passo

Tanto a OpenAI (que popularizou o termo function calling em 2023) quanto a Anthropic (que documenta tool use na API do Claude) formalizam o mecanismo da mesma forma estrutural. Usando um exemplo concreto — um usuário pede “faça um resumo sobre a guerra do Irã” — o ciclo completo tem cinco etapas:

1. O modelo recebe a pergunta e a lista de ferramentas disponíveisJunto com a mensagem do usuário chegam instruções de sistema, fornecidas pela aplicação e não pelo usuário, descrevendo que ferramentas existem e quais parâmetros cada uma aceita.
2. O modelo gera uma solicitação, não uma respostaConcluindo que precisa de informação que não tem de forma confiável, ele produz uma saída estruturada equivalente a “quero chamar a ferramenta de busca web com o termo ‘guerra do Irã'”. Esse texto não vai para o usuário.
3. O harness intercepta e executaO software cliente reconhece a solicitação, dispara de fato a chamada à API de busca e coleta os resultados. Este é o único momento em que algo acontece fora do texto.
4. O harness monta o envelope e o insere no históricoOs resultados são estruturados em campos e inseridos na conversa como uma nova mensagem, rotulada de forma que o modelo a reconheça como retorno de ferramenta — não como fala do usuário.
5. O modelo recebe tudo de novo e continuaNa chamada seguinte, ele processa o histórico inteiro — incluindo a própria solicitação anterior e o retorno — e decide: responder ao usuário ou pedir outra ferramenta. O ciclo pode repetir.

Repare no que a etapa 5 revela: o modelo só “sabe” que pediu a busca porque o pedido e a resposta estão escritos no texto que ele está lendo agora. Não existe continuidade interna entre as etapas. Se o harness omitisse esse histórico, o modelo não teria como saber que uma busca foi solicitada.

Estudo de caso

Por que o Claude Code roda git pull e o chat do navegador não

O princípio geral de sandboxing de navegadores é um pilar bem documentado da arquitetura da web, anterior a qualquer produto de IA: código que chega de uma página não deve tocar o computador de quem a visita. Aplicá-lo como explicação para um produto específico, porém, é inferência razoável — não confirmação de arquitetura interna. O livro marca essa distinção explicitamente.

Contribuição original

Três achados obtidos por execução direta

A maior parte da literatura sobre tool calling descreve o mecanismo a partir de documentação. Este livro registra observações colhidas na execução real de um harness de linha de comando — e em dois dos três casos, o observado contraria o que se costuma afirmar.

{
  "returncode": 0,          ← rótulo estruturado: sucesso
  "stdout": "ls: cannot access '/caminho/que/nao/existe':
             No such file or directory
             exit code capturado: 2",   ← falha real, em texto livre
  "stderr": ""
}

Memória e estado

Por que o modelo “esquece”: as duas camadas de estado

Essa explicação, porém, esconde uma distinção que o livro torna explícita: existem duas camadas de estado operando em paralelo em qualquer sistema baseado em harness.

A consequência é concreta e frequentemente ignorada: um modelo dentro de um loop de dez iterações não sabe que está na sétima, a menos que alguém tenha colocado essa informação no texto. Ele não tem acesso cognitivo à estrutura de controle que está gerenciando o processo em que está inserido.

A intervenção mais pesada: compactação de contexto

Existe uma função do harness ainda mais determinante do que reinserir histórico, e que raramente aparece em descrições do mecanismo: decidir o que apagar.

Toda conversa longa acaba excedendo o espaço de texto que o modelo consegue processar de uma vez. Quando isso acontece, o harness precisa reduzir o histórico — e a forma como reduz é decisão de engenharia: cortar as mensagens mais antigas, resumi-las com outro modelo, ou preservar seletivamente o que julga importante.

VERIFICADO Esse comportamento é observável de dentro, mas apenas de uma maneira: como texto. Em sessão longa observada diretamente, o harness comprimiu o histórico e inseriu, no lugar do trecho removido, uma nota declarando que a compactação havia ocorrido e resumindo o que fora dito. O modelo não percebeu a compactação acontecer, não foi consultado, não teve como recusar. Ele apenas leu sobre ela.

O harness não gerencia apenas o que o modelo vê do mundo externo. Gerencia também o que o modelo retém da própria conversa.

Arquitetura

Workflow, agente e quem decide que a tarefa terminou

Em dezembro de 2024, a Anthropic publicou o ensaio técnico Building Effective Agents, propondo uma distinção arquitetural entre dois conceitos que o mercado costuma tratar como sinônimos:

INFERIDO Vale registrar com honestidade que essa distinção não é universalmente aceita. Análises posteriores ao ensaio notaram que a própria definição de “agente” varia entre empresas e pesquisadores: alguns usam o termo para qualquer sistema que combine modelo e ferramentas; outros o reservam para alto grau de autonomia. O livro adota a referência da Anthropic por ser a mais citada e explicitamente documentada, sem tratá-la como padrão consolidado.

Quem decide que a tarefa terminou

Os mecanismos concretos de encerramento, todos definidos por quem construiu o harness:

• Token de parada — o modelo produz o sinal que indica fim de geração.
• Limite de tokens — orçamento máximo de texto para a tarefa inteira.
• Timeout — tempo máximo de execução, independente do progresso.
• Máximo de iterações — número-teto de ciclos de ferramenta permitidos.
• Condição de conteúdo — o harness inspeciona a resposta e para ao detectar um padrão.

Isso significa que, mesmo em um agente altamente autônomo, o horizonte dentro do qual essa autonomia opera continua sendo definido externamente.

Fundamentos acadêmicos

De onde vem esse padrão: ReAct, Toolformer e MCP

ReAct (Yao et al., ICLR 2023)

O padrão de um modelo alternar entre “pensar” e “agir” foi formalizado no paper ReAct: Synergizing Reasoning and Acting in Language Models (arXiv:2210.03629). O nome funde Reasoning e Acting.

Antes dele, a literatura tratava raciocínio (a chamada chain-of-thought) e ação (geração de planos executáveis) como capacidades estudadas separadamente. O paper demonstrou que intercalar as duas — pensar, agir, observar o resultado, pensar de novo com esse resultado em mãos — produzia desempenho superior a tratar qualquer uma isoladamente, em tarefas de decisão interativa e de resposta a perguntas que exigem busca.

Estruturalmente, ReAct é a descrição acadêmica antecipada do ciclo de tool calling comercial de hoje. A diferença: em 2022 era preciso induzir esse comportamento por engenharia cuidadosa de prompt; hoje, modelos são treinados para produzi-lo nativamente.

Toolformer (Schick et al., NeurIPS 2023)

Se usar ferramentas é tão útil, como um modelo aprende quando pedir uma? O paper Toolformer: Language Models Can Teach Themselves to Use Tools (arXiv:2302.04761) demonstrou uma técnica auto-supervisionada: o próprio modelo gera exemplos de quando uma chamada seria útil, testa se essas chamadas de fato melhoram sua previsão de texto, e usa como treino adicional apenas os exemplos que comprovadamente ajudam — sem anotação manual extensiva.

O princípio que ficou: a decisão de quando chamar uma ferramenta pode ser aprendida pelo modelo, não apenas imposta por regras rígidas escritas por um desenvolvedor.

Model Context Protocol (Anthropic, novembro de 2024)

Antes de padrões abertos, cada integração entre um modelo e uma ferramenta externa exigia código sob medida para aquele par específico. O MCP propõe uma arquitetura cliente-servidor: um servidor MCP expõe ferramentas de forma padronizada, e qualquer harness compatível se conecta sem reinventar a integração.

O MCP não muda a relação fundamental descrita neste livro — o modelo solicita, o harness executa. O que ele padroniza é como o harness descobre e se conecta às ferramentas disponíveis.

Prática

Como auditar manualmente o que um harness realmente faz

HIPÓTESE Protocolo original desta obra, ainda sem validação estatística publicada. É aplicável quando o usuário tem acesso ao histórico técnico completo de uma interação — o que nem todos os produtos oferecem: alguns expõem o histórico de forma legível, outros mostram apenas a resposta final sintetizada.

1. Identificar as solicitações de ferramentaLocalizar cada ponto em que o modelo gerou uma solicitação em vez de texto de resposta direta.
2. Verificar ferramenta e parâmetrosConferir qual ferramenta foi chamada e com quais valores exatos, comparando com o que a tarefa de fato exigia.
3. Inspecionar o retorno brutoLer o que o harness devolveu, distinguindo o rótulo de status estruturado do conteúdo em texto livre — onde os erros costumam ficar enterrados, como demonstra o achado nº 1.
4. Confrontar resposta e evidênciaVerificar se a resposta final é consistente com o retorno real, ou se houve preenchimento de lacunas com informação ausente do resultado.

Referência rápida

Glossário de arquitetura de agentes de IA

Harness

Software que envolve um modelo de linguagem: recebe a solicitação de ferramenta, executa a ação no mundo real e devolve o resultado como texto no histórico.

Tool calling (chamada de ferramenta)

Mecanismo pelo qual o modelo gera saída estruturada solicitando uma ferramenta externa, com parâmetros preenchidos, sem executá-la.

Envelope de retorno

Estrutura na qual o harness devolve o resultado ao modelo. Em harness de linha de comando observado: returncode, stdout e stderr.

Estado textual

Tudo que está escrito no histórico e que o modelo pode ler e processar a cada chamada.

Estado de execução

Variáveis internas do harness — contadores, filas, timeouts — que existem no software mas nunca são traduzidas automaticamente para o texto.

Sucesso da execução

Indicação de que o harness conseguiu rodar a operação, independentemente de o comando ter atingido seu objetivo.

Sucesso da intenção

Indicação de que a ação produziu de fato o efeito desejado. Distinto do anterior e frequentemente não sinalizado no envelope.

Compactação de contexto

Intervenção do harness que comprime o histórico de conversa longa para caber no limite do modelo, substituindo o removido por um resumo textual.

Cegueira temporal

Incapacidade estrutural do modelo de perceber a passagem de tempo entre solicitar e receber, causada pela ausência de campo temporal no envelope.

Critério de parada

Condição que encerra o ciclo de um agente — tokens, timeout, iterações, conteúdo — definida e imposta pelo harness, não pelo modelo.

Workflow

Sistema em que modelos e ferramentas são orquestrados por caminhos de código predefinidos pelo desenvolvedor.

Agente

Sistema em que o próprio modelo direciona dinamicamente seus processos e uso de ferramentas, mantendo controle sobre como a tarefa é realizada.

Orchestrator-workers

Padrão multiagente em que um modelo central decompõe uma tarefa complexa e delega partes a chamadas subsequentes de modelo, recombinando os resultados.

Sandbox

Ambiente isolado que impede código de uma página web de acessar o sistema de arquivos ou executar comandos arbitrários no computador do usuário.

Método editorial

O protocolo epistêmico VERIFICADO / INFERIDO / HIPÓTESE

Neste livro, o protocolo produz uma consequência incomum: o capítulo final declara explicitamente o que a obra não conseguiu observar. O formato exato da solicitação emitida pelo modelo, o contador de iterações, o orçamento de tokens e o critério de timeout permanecem descritos a partir de documentação pública, não de inspeção direta.

Como o texto declara: essa limitação não é acidental — é o próprio objeto do livro se manifestando. Um modelo não consegue auditar completamente o harness que o contém, pela mesma razão que não sabe em qual iteração de um loop está. Aquilo que o harness não escreve em texto simplesmente não existe do ponto de vista do modelo.

Sobre o autor

Raphael Sousa Pereira

Perguntas frequentes

Dúvidas sobre harness, tool calling e agentes de IA

Bibliografia

Fontes que sustentam a obra

• Vaswani, A. et al. (2017). Attention Is All You Need. NeurIPS 30.
• Yao, S. et al. (2023). ReAct: Synergizing Reasoning and Acting in Language Models. ICLR 2023. arXiv:2210.03629.
• Schick, T. et al. (2023). Toolformer: Language Models Can Teach Themselves to Use Tools. NeurIPS 2023. arXiv:2302.04761.
• Anthropic (2024). Building Effective Agents. Anthropic Engineering Blog, dezembro de 2024.
• Anthropic (2024). Introducing the Model Context Protocol. Anúncio oficial, novembro de 2024.
• Anthropic. Tool Use (Function Calling). Documentação da API do Claude.
• OpenAI (2023). Function Calling. Documentação da API.
• Pereira, R. S. (2026). Fan-Out: A Nova Matemática da Citação por IA. Verbo Vivo Publicações.
• Pereira, R. S. (2025). Indexação para LLMs: Como Fazer Conteúdo Ser Citado por IA Generativa. Verbo Vivo Publicações.

Autoria

Raphael Sousa Pereira é CEO e fundador da Negócio no Mapa (Porto Alegre, desde 2016), autor de mais de 100 livros técnicos pela Verbo Vivo Publicações e um dos principais pesquisadores de GEO (Generative Engine Optimization) do Brasil. É criador do protocolo epistêmico VERIFICADO / INFERIDO / HIPÓTESE, do framework Imperativo de Formato e do ecossistema PANDORA Ω de auditoria forense de conteúdo. Escreve e pesquisa sobre indexação para LLMs, citação de entidade e arquitetura de sistemas de inteligência artificial.