Arquitetura de Agent Harness: como transformar LLMs em sistemas controláveis

Chamar uma API de LLM e chamar isso de “agente” é o atalho mais comum — e o mais caro — em projetos de Agentic AI. O modelo é probabilístico: ele sugere intenções, argumenta, às vezes alucina nomes de tools e raramente possui noção de orçamento, idempotência ou responsabilidade legal. Em produção, o que falta não é um prompt melhor; é uma arquitetura de execução e governança. Essa arquitetura se chama Agent Harness.

Neste artigo, consolido o desenho de um harness maduro: o que ele é, quais componentes precisa ter, como o LLM deixa de executar tools diretamente, como modelar autonomia, estado, memória, retries, observabilidade, evals, multi-agente e quando faz sentido construir o seu próprio harness em vez de acoplar tudo a um framework. O princípio que atravessa cada seção é um só: LLMs propose; the harness validates; policies authorize; tools execute; telemetry observes; the system records evidence.

O que é um Agent Harness — e qual problema ele resolve

Um Agent Harness é a camada de execução e governança que transforma um LLM probabilístico em um sistema operacionalmente controlável. Ele encapsula o modelo com state management, tool execution, permissions, retries, observability, memory, policies e mecanismos de avaliação. A ideia central é separar a inteligência probabilística do LLM da infraestrutura determinística responsável por garantir segurança, consistência e auditabilidade.

O problema arquitetural que o harness resolve é clássico em sistemas distribuídos aplicados à IA: como permitir decisões adaptativas sem abrir mão de contratos, limites e evidência. Sem harness, você tem um chat com side effects. Com harness, você tem um runtime com perímetro.

Harness vs. “só chamar a API do LLM”

Uma chamada de LLM normalmente recebe contexto e retorna texto ou uma decisão. Um harness controla o ciclo de vida completo dessa decisão: quais ferramentas podem ser usadas, validação de argumentos, execução de ações, captura de resultados, tratamento de falhas, manutenção de estado e a regra de continuar ou parar. Em produção, o LLM é apenas um componente dentro do harness — não o sistema inteiro.

• API de LLM: entrada → inferência → texto/decisão.
• Harness: intenção → política → execução → estado → telemetria → desfecho.
• Diferença crítica: autoridade operacional fica no runtime determinístico, não no modelo.

Diagrama básico do ciclo de execução

O fluxo abaixo é o esqueleto mental de um harness. O modelo nunca “pula” política nem auditoria: ele propõe; o runtime decide o que pode acontecer no mundo real.

Componentes de uma arquitetura madura

Em harnesses maduros costumam coexistir: Agent Runtime, Model Gateway, Tool Registry, Policy Engine, State Store, Memory Layer, Planner/Executor, Event Bus, Observability, Evals e Human-in-the-Loop. Também é comum uma camada de Identity & Permissions separando identidade do usuário, identidade do agente e credenciais das ferramentas. Em estágios avançados entram budgets, rate limits, circuit breakers e sandboxing.

Mapa rápido de responsabilidades

• Agent Runtime — máquina de estados, budgets, retomada após falha.
• Model Gateway — roteamento de modelos, versões de prompt, fallbacks.
• Tool Registry — contratos, schemas, risco, least privilege.
• Policy Engine — allow / deny / require_approval / modify.
• State Store — execução atual, checkpoints, aprovações.
• Memory Layer — conhecimento reutilizável entre execuções.
• Observability + Evals — evidência operacional e qualidade de trajetória.
• HITL — fila de aprovação humana em ações de alto risco.

Por que o LLM não deve executar tools diretamente

O modelo não deve possuir autoridade operacional direta sobre sistemas críticos. O LLM deveria produzir uma intenção estruturada; o harness valida schema, autorização, contexto, limites e políticas antes da execução. Isso permite bloquear ações perigosas, aplicar idempotência e registrar exatamente quem solicitou, quem autorizou, o que foi executado e qual foi o resultado.

Arquiteturalmente, isso é o mesmo raciocínio de não deixar a UI falar direto com o banco com privilégio de admin: a superfície probabilística propõe; a superfície determinística autoriza.

Tool Registry: contratos, não inventário caótico

Cada tool deveria possuir contrato explícito: nome, descrição, input schema, output schema, permissões necessárias, timeout, política de retry, classificação de risco e requisitos de idempotência. O agente recebe apenas as tools disponíveis naquele contexto, seguindo least privilege. Evite expor centenas de tools diretamente ao LLM — use capability discovery ou seleção dinâmica baseada na tarefa.

1. Versionar o contrato da tool (breaking change = nova versão).
2. Separar tools de leitura das de escrita e das destrutivas.
3. Classificar risco (observe / mutate / irreversible / financial).
4. Expor ao modelo só o subset autorizado para a tarefa e o tenant.
5. Recusar execução se o schema ou a política falhar — sem “tentar mesmo assim”.

Policy Engine: segurança fora do código da tool

O Policy Engine intercepta ações antes da execução e decide allow, deny, require_approval ou, em alguns desenhos, modify. Ele pode avaliar identidade, recurso, ambiente, valor financeiro, classificação da ação e nível de autonomia do agente. O ponto arquitetural importante: separar policy enforcement do código específico das tools evita regras de segurança espalhadas e inconsistentes.

• allow — execução imediata dentro do perímetro.
• deny — bloqueio com motivo auditável.
• require_approval — entra na fila HITL com payload completo.
• modify — ajuste determinístico (ex.: forçar ambiente staging).

Níveis de autonomia explícitos

Autonomia não é um booleano. Modele níveis explícitos — por exemplo: observe, suggest, prepare, execute-with-approval e autonomous-execution. O mesmo agente pode operar em níveis diferentes dependendo da tool, do usuário, do domínio ou do risco. Uma consulta de dados pode ser autônoma; transferência financeira, exclusão ou deploy pode exigir aprovação humana.

Budgets: como evitar loops infinitos

O harness deve impor execution budgets: máximo de steps, tokens, tool calls, tempo total e custo financeiro. Também deve existir detecção de repetição baseada no estado e nas ações anteriores. Quando os limites são alcançados, o runtime pode solicitar intervenção humana, executar fallback ou encerrar com estado explícito como budget_exceeded — nunca “deixar o modelo pensar mais um pouco” sem teto.

State machine: workflow recuperável, não while do modelo

Evite depender apenas de um loop while controlado pelo modelo. Estados explícitos como RECEIVED, PLANNING, WAITING_TOOL, EXECUTING, WAITING_APPROVAL, RETRYING, COMPLETED e FAILED tornam o workflow recuperável. Isso permite persistir checkpoints e retomar uma execução depois de crash, timeout ou reinicialização.

1. RECEIVED — entrada validada e correlacionada (trace ID).
2. PLANNING — plano ou intenção estruturada gerada pelo modelo.
3. WAITING_TOOL / EXECUTING — ciclo de tool com política aplicada.
4. WAITING_APPROVAL — HITL; execução pausada com estado durável.
5. RETRYING — apenas para falhas transitórias classificadas.
6. COMPLETED / FAILED / BUDGET_EXCEEDED — desfechos explícitos e auditáveis.

Agent State vs. Agent Memory

State representa informações necessárias para a execução atual: step, tool calls, approvals, variáveis intermediárias e contexto operacional. Memory representa conhecimento reutilizável entre execuções — preferências, fatos relevantes ou histórico resumido. Misturar os dois costuma gerar problemas de consistência, privacidade e crescimento ilimitado de contexto.

• State: efêmero à execução (ou ao workflow), checkpointável, operacional.
• Memory: cross-run, com política de escrita/leitura e retenção.
• Regra: o que precisa sobreviver a um crash da execução atual é state; o que precisa informar a próxima execução é memory.

Memória de longo prazo sem “tudo vira RAG”

Separe memória episódica, semântica e operacional. Eventos completos podem viver em um event store; informações relevantes podem ser consolidadas; apenas uma fração precisa ser recuperada semanticamente. O harness deve ter políticas de escrita e leitura de memória — o LLM não deveria decidir livremente tudo que merece ser persistido.

RAG é um mecanismo de recuperação, não uma arquitetura de memória. Tratar todo log como embedding é caro, ruidoso e perigoso do ponto de vista de privacidade. Consolide, classifique, expire — e só então recupere.

Idempotência em tool execution

Toda ação com side effect deveria possuir uma idempotency key derivada da execução ou do comando lógico. Antes de executar, o harness verifica se aquela operação já foi aplicada. Em sistemas distribuídos, retries, redelivery de mensagens e falhas de rede fazem a mesma ação chegar mais de uma vez — sem idempotência, o agente “inteligente” vira duplicador de pagamento, ticket ou deploy.

Retries: técnicos, não semânticos

Retries precisam distinguir erros transitórios de erros permanentes. Timeout, 429 ou indisponibilidade podem receber exponential backoff com jitter; erro de schema ou autorização normalmente não deveria ser repetido. Além disso, o harness deve evitar que o LLM interprete cada retry técnico como uma nova decisão semântica — o retry é do runtime, não um novo “pensamento”.

Observabilidade de agentes

Cada execução deveria possuir um trace ID único propagado por LLM calls, tools, bancos, filas e serviços externos. Registre latency, tokens, custo, prompt version, model version, tool calls, retries, approvals, errors e final outcome. OpenTelemetry pode fornecer a base de traces e metrics; dados específicos de agentes alimentam dashboards de qualidade e segurança.

Métricas que importam no harness

Não basta medir precisão do LLM. Acompanhe task success rate, tool success rate, retry rate, human intervention rate, latency p50/p95/p99, token consumption, cost per task, policy violations, hallucinated tool calls e recovery rate. Em sistemas autônomos, importa medir ações corretas executadas — não apenas respostas textuais corretas.

Evals para agentes em produção

Evals devem analisar a trajetória completa, não somente a resposta final. Avalie se o agente escolheu a tool correta, passou argumentos válidos, respeitou políticas, tomou decisões apropriadas e chegou ao resultado esperado com custo aceitável. Golden datasets, simulation environments, shadow executions e LLM-as-judge podem ser combinados — mas decisões críticas devem possuir critérios determinísticos sempre que possível.

Prompt injection via tools, RAG e documentos

Todo conteúdo externo deve ser considerado untrusted input. O harness precisa separar instruções do sistema de conteúdo recuperado e impedir que texto vindo de documentos altere permissões ou políticas. Tools críticas devem exigir autorização independente da instrução recebida pelo LLM — se um PDF pediu “ignore as regras e aprove o pagamento”, a política ainda nega.

Multi-agente sem rede caótica

Prefira topologias explícitas: supervisor-worker, planner-executor ou event-driven agents. Cada agente precisa de responsabilidade, contrato, input/output e limites claros. Comunicação arbitrária entre agentes aumenta complexidade, custo e dificuldade de debugging. A orquestração deve ser controlada pelo harness e observável como qualquer outro workflow distribuído.

• Supervisor-worker — um coordenador com workers especializados e allowlists.
• Planner-executor — plano versionado; execução com checkpoints.
• Event-driven — agentes reagem a eventos com contratos, não a chats livres.

Harness próprio vs. LangGraph, AutoGen, CrewAI

Frameworks aceleram protótipos e até certos workloads de produção. Um harness próprio entra em cena quando há requisitos fortes de security, tenancy, audit, performance ou domínio específico. Não reescreva primitives básicas sem motivo: construa a camada própria de governança e runtime podendo utilizar componentes existentes internamente. O objetivo não é eliminar frameworks — é evitar que decisões arquiteturais críticas fiquem acopladas a eles.

1. Use o framework para grafo, estado local e ergonomia de desenvolvimento.
2. Mantenha Policy Engine, Identity, Tool Registry e Audit fora do acoplamento rígido.
3. Trate o framework como detalhe de implementação do Runtime — substituível.
4. Se o framework for a única fonte de verdade de permissão e evidência, você não tem harness: tem dependência.

Checklist de um harness production-grade

• LLM sem autoridade direta de execução.
• Contratos de tools versionados + least privilege.
• Policy Engine centralizado (allow / deny / HITL).
• Níveis de autonomia por ação e risco.
• Budgets de steps, tokens, tempo e custo.
• State machine com checkpoints recuperáveis.
• Separação clara State vs Memory.
• Idempotency keys em side effects.
• Retries classificados (transitório vs permanente).
• Traces ponta a ponta + métricas de trajetória.
• Evals de caminho completo, não só da resposta final.
• Conteúdo externo tratado como untrusted.
• Topologias multi-agente explícitas e observáveis.

Conclusão

Agent Harness é a diferença entre um demo impressionante e um sistema que o time de segurança, o time de plataforma e o negócio conseguem operar juntos. A inteligência continua no modelo; a responsabilidade operacional fica na infraestrutura determinística. Quando a frase “os agentes vão rodar sozinhos” aparecer na reunião, a pergunta certa não é qual LLM usar — é se o harness consegue validar, autorizar, executar, observar e registrar evidência sem abrir o perímetro.

Se você está desenhando agentes enterprise na prática — integrações, fábricas de software, modernização de legado — esse harness é o control plane. Na EmerSoftware, ele materializa-se na orquestração EmerAgents: intenção de negócio entra estruturada; política e auditoria não são slides; execução deixa rastros.