Se você tentou colocar um agente de IA em produção nos últimos seis meses e travou na primeira semana, o problema provavelmente não foi o modelo. Foi a confusão entre agent framework e agent harness — dois termos que o mercado passou a usar como sinônimos em 2026, mas que descrevem camadas completamente diferentes da pilha. Um é o código que você escreve. O outro é o que põe esse código para rodar com segurança, contexto e aprovação humana. Confundir os dois é o motivo pelo qual muita PME brasileira desiste de automação com IA antes do segundo sprint.
Resposta curta: framework é a biblioteca que define a estrutura do agente — como ele declara tools, mantém memória, encadeia prompts e delega para sub-agentes. harness é a infraestrutura de runtime — sandbox, sistema de arquivos, permissões de shell, gestão de contexto em sessões longas, human-in-the-loop, persistência. Você quase sempre usa os dois juntos; a escolha errada é tratar um pelo outro.
A distinção, sem jargão
Pense em construir um e-commerce em 2026. Você usa um framework (Next.js, Django, Rails) para estruturar o código. Roda em cima de um runtime/servidor (Node, Gunicorn, Puma) que cuida de processo, porta, ambiente, logs e hot-reload. O framework descreve. O runtime executa. Com agentes de IA, a lógica é idêntica.
O time da LangChain define harness como "framework opinativo, batteries-included, com tools e capacidades embutidas que tornam mais fácil construir agentes sofisticados e de longa duração". O blog oficial da Microsoft no BUILD 2026 — onde o termo ganhou tração institucional — descreve o harness como "a camada onde o raciocínio do modelo encontra a execução real: shell, filesystem, fluxos de aprovação human-in-the-loop e gestão de contexto em sessões longas". A documentação de Frameworks, runtimes e harnesses consolida a taxonomia em três camadas: frameworks entregam blocos de construção, runtimes executam workflows determinísticos, harnesses impõem controle sobre agentes de longa duração.
A confusão comercial é proposital. Vários vendors empacotam o framework como se fosse a solução completa. Sem harness, seu agente é um script que roda uma vez e morre. Sem framework, seu harness é um executor oco sem lógica de negócio.
Tabela comparativa
| Aspecto | Agent framework | Agent harness |
|---|---|---|
| O que é | Biblioteca/SDK que define a estrutura do agente em código | Runtime que executa o agente com segurança e contexto |
| Papel principal | Declarar tools, memória, fluxo, prompts, encadeamento | Shell, filesystem, sandbox, permissões, aprovação, sessão |
| Quem usa direto | Engenheiro escrevendo o agente | Engenheiro implantando o agente; usuários finais |
| Exemplo concreto | Microsoft Agent Framework, LangGraph, LangChain (create_agent) | Microsoft Agent Harness, LangChain Deep Agents, Claude Agent SDK |
| Camada | Lógica / código de aplicação | Infraestrutura / execução |
| Trocar de framework dá trabalho? | Sim — refactor pesado | Não — harness costuma ser agnóstico |
| Trocar de harness dá trabalho? | Não — se o framework expõe hooks padrão | Sim — exige reimplantar permissões, sandbox e integrações |
| Quem decide | Time de engenharia que mantém o código | Time de plataforma / SRE / segurança |
| Maturidade em junho/2026 | Consolidado (Microsoft Agent Framework chegou ao GA 1.0 em 2 de abril de 2026) | Em formação — Microsoft oficializou o conceito em BUILD 2026 |
Os três harnesses que importam em 2026
A escolha prática no Brasil hoje se resume a três opções, cada uma com trade-offs diferentes.
Microsoft Agent Harness — Anunciado em junho de 2026 no BUILD, roda em cima do Microsoft Agent Framework (MAF), que unificou AutoGen e Semantic Kernel no release 1.0 GA de abril. Vem com hosted agents, suporte a CodeAct (gera e executa código em sandbox), aprovação humana obrigatória para ações de alto impacto e observabilidade nativa. Melhor encaixe para empresas que já usam Azure, Dynamics ou Power Platform. Pior encaixe para quem está fora do ecossistema Microsoft e não quer pagar pelo lock-in.
LangChain Deep Agents — Lançado em abril de 2026 como SDK standalone construído sobre LangGraph. É a implementação mais opinativa do conceito: vem com planning automático (todo list interno), virtual filesystem para gerenciar contexto, subagent spawning para paralelizar trabalho e human-in-the-loop com interrupts. Comparado ao Claude Agent SDK, tem 4 categorias de capacidades embutidas: execution environment, context management, delegation e steering. Melhor encaixe para quem já programa em Python e quer ir do protótipo à produção em duas semanas.
Claude Agent SDK — O harness da Anthropic, pensado originalmente para o Claude Code (terminal coding agent). É o que tem a melhor engenharia de sessão longa e de ferramentas de filesystem, e qualquer modelo compatível com a API da Anthropic roda em cima. Pior encaixe para quem precisa orquestrar dezenas de modelos diferentes — é mais fechado que o LangChain.
A escolha entre os três depende menos da tecnologia e mais do seu contexto: ecossistema Microsoft, flexibilidade open-source, ou lock-in com Claude.
Quando usar cada um (e quando usar os dois)
A resposta honesta: você quase sempre usa os dois. A pergunta real é qual framework combina com qual harness e quem opera cada parte dentro da sua empresa.
Use um framework quando:
- Você está definindo a lógica do agente — qual modelo, quais tools, como decide, como lembra, como delega. É trabalho de engenharia de aplicação.
- Você tem requisitos específicos que o framework precisa cobrir (multi-agente, typed state, tool calling estrito, integração com sistema interno).
- A equipe consegue manter código de framework — atualizar dependências, ler changelogs, lidar com breaking changes.
Use um harness quando:
- O agente precisa rodar por horas ou dias, com aprovação humana em pontos críticos.
- O agente precisa de acesso a shell, filesystem ou APIs externas com permissões bem definidas.
- O agente precisa sobreviver a sessões longas sem perder contexto ou explodir a janela de tokens.
- Você tem requisitos de auditoria, sandboxing ou compliance (LGPD, SOC 2, política interna de TI).
Use os dois juntos quando:
- O agente vai para produção real, atendendo cliente, processando pedido ou mexendo em banco de dados.
- O custo de uma execução errada é alto (R$ 5.000 em devolução indevida, dado vazado, ação fora de política).
- Você precisa de observabilidade, retry, fallback e replay — coisas que framework puro não entrega.
Prós e contras
| Abordagem | Prós | Contras |
|---|---|---|
| Só framework (sem harness) | Rápido para protótipo; controle total do loop; sem dependência externa | Sem sandbox, sem gestão de contexto, sem aprovação; quebra em produção |
| Só harness (sem framework) | Batteries-included; menos código de orquestração; time-to-production curto | Opiniativo demais para casos fora do padrão; vendor lock-in |
| Framework + harness separados | Flexibilidade máxima; troca de harness sem reescrever lógica | Mais peças para integrar; dois times para coordenar; custo maior |
| Framework + harness do mesmo vendor (ex: MAF + Microsoft Harness) | Integração testada; menos fricção; suporte único | Lock-in forte; preço amarrado ao ecossistema |
| Deep Agents (harness opinativo sobre LangGraph) | Setup mais rápido que MAF; comunidade Python ativa; open-source | Dependência de LangChain; curva de aprendizado de LangGraph |
| Claude Agent SDK | Melhor engenharia de sessão longa; seguro por padrão | Fechado à família Claude; licenciamento comercial Anthropic |
Veredicto
Se você é uma PME brasileira começando agora: comece com LangChain Deep Agents para protótipos rápidos em Python e migre para Microsoft Agent Harness quando precisar de governança Azure e integração com sistemas Microsoft legados. Use Claude Agent SDK apenas se sua equipe já é fluente em Claude e o caso de uso exige sessões multi-dia com excelência em filesystem.
Em todos os cenários, não confunda framework com harness na hora de comprar. Quem vende framework como solução completa está vendendo o esqueleto. Quem vende harness como produto standalone está vendendo a infraestrutura sem lógica. O que resolve o problema de produção é a pilha inteira, com as duas camadas bem definidas e operadas por times diferentes.
CTA Agendai
Quer ver agent harness e agent framework rodando em um caso real do seu varejo? A Agendai implanta o agente em até duas semanas, com a primeira semana gratuita e sem fidelidade. Atendemos mercados, farmácias, pet shops, restaurantes e varejistas de moda que precisam colocar IA para operar de verdade — não só rodar demo.
Perguntas frequentes
O que é um agent harness? É o runtime que executa um agente de IA com segurança: gerencia shell, filesystem, sandbox, permissões, aprovação humana e contexto de sessão longa. O termo foi oficializado pela Microsoft no BUILD 2026 e pelo time da LangChain em abril de 2026, na página do Deep Agents.
Como agent harness funciona na prática? O harness recebe uma instrução do agente, executa em ambiente controlado (sandbox), expõe tools ao modelo, captura resultados, gerencia tokens da janela de contexto, e pausa para aprovação humana em ações de alto impacto. O Deep Agents tem quatro categorias de capacidades: execution environment, context management, delegation e steering.
Quanto custa implementar agent harness? Custos variam de zero (Deep Agents é open-source em Python) a centavos por execução (Microsoft Agent Harness em Azure cobrando por uso de hosted agents). Para uma PME brasileira com 1.000 a 10.000 execuções por mês, a conta típica fica entre R$ 200 e R$ 2.000 mensais, dependendo do modelo usado. O custo de implementação, se feito por consultoria, gira em R$ 15 mil a R$ 60 mil.
Deep Agents substitui LangGraph? Não. Deep Agents é construído sobre LangGraph. Se você precisa de orquestração determinística e controle fino do estado, use LangGraph puro. Se você quer baterias incluídas (planning, filesystem, subagents), use Deep Agents. A documentação oficial recomenda Deep Agents para a maioria dos casos e LangGraph apenas para necessidades avançadas.
Quando NÃO usar um harness? Quando o agente é descartável (roda uma vez, responde uma pergunta) e não toca em sistema externo. Para chatbot FAQ ou classificador de texto, framework puro resolve. Harness só compensa quando há execução real, sessão longa ou ação com efeito colateral.