O que é um agent harness? Como agentes de IA ganham ferramentas, memória e controle

A ideia não é exatamente nova. Desenvolvedores vêm criando wrappers, scaffolds e ambientes de execução ao redor de modelos há anos. O termo ganhou força depois que Mitchell Hashimoto, cofundador da HashiCorp, usou "harness engineering" em um post de fevereiro de 2026 sobre seu fluxo de trabalho em IA. A mensagem era simples: quando um agente comete um erro, mude o ambiente para que esse erro não volte a acontecer. A OpenAI adotou o termo na mesma semana no trabalho com o Codex, e a LangChain seguiu com a mesma abordagem.

Neste artigo, vou explicar o que é um agent harness, por que agentes de IA precisam dele, como ele difere de frameworks e runtimes e quais ferramentas os desenvolvedores usam para construir sistemas com esse perfil.

O que é um agent harness?

Uma definição vem da LangChain: "Se você não é o modelo, você é o harness." Na prática, um agent harness é o software em torno de um modelo de linguagem: ferramentas, memória, estado, execução, guardrails e observabilidade.

Agente = Modelo + Harness

O modelo faz o raciocínio. O harness dá a esse raciocínio um lugar para agir, lembrar, checar resultados e seguir regras.

Modelo dentro do seu agent harness de trabalho. Imagem do autor.

A fórmula é útil, mas é um modelo mental, não um padrão da indústria. Alguns fornecedores ainda usam "harness", "framework" e "scaffold" com sentidos parecidos.

Por que agentes de IA precisam de um harness

Um modelo de linguagem puro tem limites quando você pede que ele trabalhe em muitas etapas. Ele não mantém estado durável sozinho, não executa ferramentas por conta própria, não gerencia um contexto crescente nem se recupera de falhas em chamadas de ferramentas sem ajuda. 

Imagine um agente encarregado de corrigir um teste com falha em um projeto Python. Sem um harness, o modelo pode escrever algo que parece uma correção, mas não consegue ler o arquivo de teste real, rodar o pytest, ver o erro de verdade, editar a função que falhou ou confirmar que a correção passou. Com um harness, todo esse ciclo vira alguns minutos de trabalho que o agente faz sozinho, com cada etapa registrada em algum lugar onde um humano pode inspecionar.

Ainda vale o conselho da Anthropic: comece pelo caminho mais simples possível e só adicione partes móveis quando a tarefa exigir.

Do que é feito um agent harness

As peças variam, mas a maioria compartilha alguns blocos de construção. Pense neles como um checklist, não uma especificação rígida. Um agente pequeno pode precisar de poucas dessas partes, enquanto um agente de produção vai precisar de mais.

Prompts de sistema e regras de comportamento

O harness geralmente controla as instruções-base do modelo. Isso inclui o system prompt, mas também pode incluir regras do projeto, padrões de código, restrições de papel e diretrizes de segurança. Nos Deep Agents da LangChain, por exemplo, um arquivo AGENTS.md pode definir as regras do jogo antes da tarefa começar.

Alguns harnesses em 2026 também usam divulgação progressiva de instruções. Em vez de carregar a descrição de todas as ferramentas no contexto logo no início, o harness adiciona só um resumo do que está disponível. As instruções completas de uma ferramenta só são carregadas quando o modelo precisa dela.

Ferramentas: como os agentes interagem com o mundo

Ferramentas permitem que o agente faça mais do que gerar texto. Exemplos comuns incluem busca na web, leitura e escrita de arquivos, consultas a banco de dados, chamadas de API, ações de navegador, execução de código e comandos de terminal. O harness controla quais ferramentas estão disponíveis, quando o modelo pode chamá-las e como os resultados são formatados e devolvidos ao contexto do agente.

Model Context Protocol (MCP) tornou-se uma interface padrão para isso em 2026. Muitos harnesses, incluindo o Anthropic Agent SDK, os LangChain Deep Agents e o OpenAI Agents SDK, usam MCP para conectar servidores de ferramentas externos sem precisar escrever integração personalizada para cada um.

Memória e estado

Agentes precisam saber o que aconteceu antes na tarefa. Um harness pode manter estado de curto prazo na conversa ativa e estado de longo prazo em arquivos, logs, resumos ou preferências salvas. Alguns harnesses também compactam históricos longos em resumos menores para que o modelo não carregue cada detalhe no contexto.

Ambiente de execução: onde o agente roda e atua

Muitos agentes úteis precisam de um lugar para, de fato, trabalhar. Pode ser um sistema de arquivos, um container, um terminal em sandbox, uma instância de navegador ou um runtime em nuvem. Sem um ambiente de execução gerenciado pelo harness, as chamadas de ferramentas não têm onde acontecer.

Hoje, muitos harnesses usam containers isolados em sandbox: ambientes de vida curta, escopados para uma única sessão e limpos ao final da tarefa, para que escritas em arquivo, pacotes instalados e chamadas de rede de uma tarefa não vazem para outra.

Orquestração e planejamento

Algumas tarefas não cabem em uma linha reta de passos. O harness pode oferecer uma ferramenta de planejamento que divide um objetivo em subtarefas e acompanha seu status. Ele também pode criar subagentes que cuidam de uma parte do trabalho e retornam apenas um resumo ao agente principal.

Os Deep Agents da LangChain, por exemplo, rastreiam as etapas do plano em um arquivo no sistema de arquivos, atualizando cada etapa de pendente para concluída conforme a tarefa avança.

Guardrails e permissões

É no harness que você coloca as regras: aprovação humana, bloqueio de chamadas de ferramentas, permissões por função e checagens de saída. OpenAI Agents SDK, LangChain Deep Agents e Microsoft Agent Framework oferecem esse tipo de controle. O padrão mais seguro é verificar entrada, saída e permissões de ferramentas separadamente.

Observabilidade e tracing

Quando uma tarefa de 50 etapas falha na etapa 37, um trace mostra o que aconteceu. O tracing registra chamadas de modelo, chamadas de ferramentas, handoffs, erros, latência e custo ao longo de toda a execução. O OpenAI Agents SDK ativa tracing por padrão. O LangSmith adiciona painéis de depuração e avaliação por cima. O OpenTelemetry virou o padrão para exportar traces em um formato neutro, para você não ficar preso a uma única ferramenta de observabilidade.

Agent harness vs. framework vs. runtime: qual é a diferença?

Essa dúvida aparece muito, e a resposta é mais bagunçada do que muitos guias sugerem. A taxonomia é útil, mas não é fixa.

Três camadas, aumentando a abstração de baixo para cima. Imagem do autor.

Vou começar pelo framework, já que muitos desenvolvedores já usaram um.

O que é um agent framework?

Um agent framework dá aos desenvolvedores blocos de construção para criar agentes. Ele cobre chamadas de modelo, definições de ferramentas, padrões de memória e a estrutura do loop do agente. Exemplos incluem a LangChain em sua fase inicial, CrewAI e Google ADK. Um framework indica como estruturar um agente, mas nem sempre como executá-lo de forma confiável em produção.

O que é um agent runtime?

Um agent runtime é a camada que ajuda um agente a rodar de forma confiável ao longo do tempo. Ele cuida de execução durável, persistência de estado, novas tentativas, passos com humano no loop e streaming. LangGraph, Temporal e Inngest são exemplos. Harrison Chase ofereceu este paralelo: se Node.js é o runtime e Express é o framework, um harness é como o Next.js.

O que torna um harness diferente?

Um harness é um nível acima de um framework. Enquanto um framework entrega componentes, um harness geralmente chega com mais decisões já tomadas: ferramentas, planejamento, acesso ao sistema de arquivos e gestão de contexto.

Casos de uso de agent harness: código, pesquisa, dados e enterprise

Os mesmos blocos aparecem em trabalhos bem diferentes, mas o que muda é a mistura. Um agente de código e um agente de workflow corporativo precisam de um harness, mas exigem partes diferentes dele. Essas categorias não são padrões formais. São formas práticas de enxergar como a mesma ideia se adapta ao trabalho à frente.

Harnesses para agentes de código

Agentes de código são um bom exemplo atual porque o harness fica visível. Para fazer trabalho útil de programação, um agente precisa de acesso a arquivos, contexto do git, execução em terminal, rodar testes, instalar dependências e seguir regras do projeto. Claude Code e Codex são exemplos desse padrão: ambos rodam sobre muito código de harness, não apenas uma API de modelo crua.

A diferença entre um bom e um harness mediano para código costuma aparecer nos detalhes: como ele se recupera de um teste que quebrou, se consegue reverter uma edição ruim, quão limpo é o jeito de expor o histórico do git ao modelo. É nesses detalhes que a maior parte do esforço de engenharia entra.

Harnesses para agentes de pesquisa

Agentes de pesquisa precisam de outro conjunto de ferramentas: busca na web, rastreamento de fontes, anotações, gestão de citações e sumarização. O harness gerencia como os resultados de busca são armazenados, como as fontes são atribuídas e como documentos longos são segmentados e descarregados para não consumir toda a janela de contexto de uma vez.

Harnesses para agentes de análise de dados

Agentes de dados precisam de acesso a datasets, bancos SQL, ambientes de execução Python e contexto de esquema para saber que tabelas e colunas existem antes de começar a escrever queries. O harness também impõe limites de permissão, essenciais quando o agente pode tocar dados de produção.

Harnesses para workflows enterprise

Implantações corporativas adicionam outra camada de requisitos: autenticação, trilhas de auditoria, fluxos de aprovação, controle de acesso por função e integrações com sistemas internos. AWS AgentCore é um exemplo gerenciado nessa categoria, com identidade, rede VPC e observabilidade incluídas. O Microsoft Agent Framework cobre terreno parecido para times em ambientes Azure ou .NET.

Ferramentas para construir agent harnesses em 2026

Uma mão cheia de produtos aparece com mais frequência em meados de 2026. Eles ficam em pontos diferentes no espectro framework-runtime-harness, e as fronteiras ainda estão mudando.

LangChain Deep Agents

LangChain Deep Agents é o harness open source da LangChain, construído sobre o LangGraph como runtime. Ele vem com ferramenta de planejamento, sistema de arquivos virtual, criação de subagentes, compactação automática de contexto e middleware para aprovação humana e detecção de PII. É agnóstico a modelos, suporta endpoints compatíveis com OpenAI e conecta a provedores de sandbox como Modal, Runloop e Daytona para execução de código.

Anthropic Agent SDK

O Anthropic Agent SDK (nome do pacote: claude-agent-sdk) foi extraído do Claude Code e lançado como opção independente. Inclui um loop de agente embutido, ferramentas para execução em bash, leitura e escrita de arquivos, busca na web, integração MCP e compactação de contexto. Funciona apenas com modelos Claude, via API da Anthropic, Amazon Bedrock, Vertex AI e Azure.

OpenAI Agents SDK

Como mencionei antes, o OpenAI Agents SDK cruzou do território de framework para harness à medida que o conjunto de recursos cresceu. A versão de abril de 2026 adicionou execução em sandbox nativa, compactação de memória e ferramentas de sistema de arquivos. Disponível em Python e TypeScript, o SDK oferece uso de ferramentas, handoffs entre agentes e guardrails.

Google Agent Development Kit

Google ADK suporta orquestração multiagente com classes nativas para estruturas sequenciais, paralelas e baseadas em loops. Inclui ferramentas de avaliação, funciona com o Vertex AI para deploy gerenciado e suporta MCP para conexão de ferramentas. Disponível em Python, Java, TypeScript e Go, é ajustado para modelos Gemini, mas descrito como agnóstico a modelos.

Microsoft Agent Framework

Microsoft Agent Framework é o caminho atual de migração da Microsoft para projetos AutoGen. Suporta Python e .NET, funciona com serviços de IA do Azure e inclui suporte a MCP para conexão de ferramentas.

CrewAI

CrewAI adota uma abordagem baseada em papéis para sistemas multiagente. Você define agentes com funções específicas, atribui tarefas, organiza equipes e configura memória e guardrails de forma declarativa. Encaixa bem em problemas que mapeiam naturalmente para um time de especialistas.

Temporal e Inngest

Sozinhas, elas não são agent harnesses. São plataformas de execução durável que lidam com o que acontece quando uma tarefa de agente precisa rodar por horas ou dias sem perder estado. Em caso de falha, o engine reproduz a partir do último checkpoint bem-sucedido em vez de recomeçar do zero.

Desafios e trade-offs de um agent harness

Adicionar um harness amplia o que o sistema consegue fazer, mas cada nova ferramenta, permissão e agente também cria novas formas de algo quebrar. À medida que as tarefas ficam mais longas, guardrails, tracing e estado durável deixam de ser opcionais e viram o que mantém uma execução longa recuperável.

Há também um risco de acoplamento que pega times de surpresa. A LangChain reportou um salto de 10 a 20 pontos em um subconjunto do tau2-bench após adicionar perfis de harness específicos por modelo. A Artificial Analysis fez ponto parecido no Coding Agent Index: resultados de agentes de código dependem do modelo e do harness juntos, com custo, uso de tokens e tempo por tarefa variando bastante entre combinações. O modelo não mudou. Os prompts, as ferramentas e o middleware ao redor mudaram. Esse perfil, em si, é trabalho de harness.

Você realmente precisa de um agent harness?

Aqui vai um jeito direto de pensar se você precisa de um.

É provável que você precise de um harness se o seu sistema atende a uma ou mais destas condições:

• Precisa usar ferramentas externas
• Precisa lembrar o progresso entre sessões
• Precisa rodar código em um ambiente real
• Coordena mais de um agente
• Precisa se recuperar de falhas parciais sem perder trabalho
• Exige aprovação humana

Provavelmente você não precisa de um harness se a tarefa é um workflow previsível em que cada passo já está determinado.

Um teste útil: se a tarefa pode ser resolvida com uma única chamada de modelo, ou com um script determinístico pequeno com alguns condicionais, um harness provavelmente é exagero. No momento em que a tarefa exige que o agente tome decisões, use ferramentas e reaja aos resultados ao longo do tempo, o harness passa a fazer trabalho de verdade.

Um padrão que vejo bastante é times recorrerem a um harness cedo demais, construindo tracing e sandbox para o que, na prática, é uma tarefa de geração de texto pontual. O erro inverso é o que dói: colocar o modelo no ar diretamente e perceber, no segundo teste que falha, na terceira chamada de ferramenta ou no quinto restart, que não há infraestrutura para segurar a bronca.

Considerações finais

Como já mencionei, os fornecedores não usam todos as mesmas palavras para as mesmas coisas, e a fronteira entre framework, runtime e agent harness ainda está mudando.

Para geração one-shot, o wrapper é exagero. Para agentes que precisam agir, lembrar e se recuperar ao longo de sessões longas, o agent harness vira uma parte grande do sistema. Escolher o certo está cada vez mais separado de escolher o modelo certo. Estou curioso para ver quanto dessa camada a próxima geração de modelos vai absorver por conta própria, já que alguns movimentos de OpenAI e Anthropic sugerem que a fronteira vai continuar mudando. A ideia básica continua valendo: um agente é um modelo mais um agent harness.

Se você quer aprender mais sobre como construir sistemas com agentes, nosso curso Building Scalable Agentic Systems aborda os padrões por trás do uso de ferramentas, orquestração e workflows de agentes de longa duração.