Um agente pode impressionar numa demo e falhar na primeira tarefa longa. Ele perde o estado, recebe contexto velho, chama a ferramenta errada ou declara sucesso sem ter produzido o resultado esperado. Um agent harness cria a camada de execução que organiza memória, contexto, ferramentas, permissões e verificações. Para entender a base, vale também revisar este guia prático sobre agentes com function calling.
Agent harness: arquitetura em camadas com Estado, Contexto, Evals e Ferramentas para agentes de IA em produção
Principais conclusões
Estado persistente permite retomar tarefas interrompidas sem começar do zero.
Contexto bom é selecionado, versionado e auditável, não apenas maior.
Evals precisam verificar resultados observáveis, chamadas de ferramentas e políticas.
Permissões, limites e logs fazem parte da arquitetura, não de um remendo posterior.
Bit pode organizar componentes reutilizáveis, mas não é obrigatório.
O que é um agent harness e por que ele importa em produção?
Um agent harness é a camada de software que envolve o modelo e coordena sua execução. Ele decide que contexto entra, quais ferramentas podem ser chamadas, como o estado é salvo e qual evidência prova que a tarefa terminou. Em produção, essa camada transforma uma conversa probabilística em uma execução controlada e observável.
Agent harness coordena três estados críticos: interrompido (retomada), persistente (memória) e retomado (verificação) para garantir execução confiável de agentes de IA em produção
O modelo raciocina e gera próximos passos. O harness fornece um ambiente para agir, lembrar, receber feedback e parar. Essa definição é próxima da apresentada pelo DataCamp, que reúne ferramentas, memória, estado, execução, guardrails e observabilidade no software ao redor do modelo.
Um trabalho publicado no arXiv formaliza essa ideia como um sistema modelo-harness-ambiente. O artigo lista 11 responsabilidades, incluindo especificação da tarefa, seleção de contexto, acesso a ferramentas, memória do projeto, estado, observabilidade, permissões, verificação e registro de intervenções, segundo os autores. Isso ajuda a tirar o conceito do campo da metáfora.
Framework, runtime e harness se sobrepõem, mas cumprem papéis diferentes. Um framework oferece blocos para construir o agente. Um runtime cuida da execução durável, dos retries e dos checkpoints. O harness combina essas capacidades com decisões concretas sobre contexto, ferramentas, regras e critérios de sucesso.
Um prompt sozinho não controla timeout, concorrência ou efeitos colaterais. Também não impede um loop infinito. Se uma API responde parcialmente, o modelo pode interpretar a resposta de forma errada. Se a sessão cai depois de uma ação externa, uma nova tentativa pode duplicar o efeito. Quem coordena esses casos é a infraestrutura.
Uma tarefa de 50 etapas pode falhar na etapa 37. Sem tracing, você vê apenas uma resposta final ruim. Com um harness, consegue recuperar chamadas de modelo, ferramentas, handoffs, erros, latência e custo, como descreve o DataCamp na discussão sobre tracing. O diagnóstico deixa de ser um palpite.
O ponto central é simples: agentes de IA em produção precisam de mais do que um bom modelo. Eles precisam de um ambiente que limite ações, preserve evidências e saiba quando continuar, pausar ou pedir ajuda.
Como o estado torna um agente capaz de continuar seu trabalho?
O estado permite que o agente retome uma execução com conhecimento do progresso, das pendências e dos erros anteriores. Ele deve registrar fatos operacionais da tarefa, não apenas copiar toda a conversa. Persistência, versionamento, idempotência e recuperação após falhas determinam se o agente realmente consegue trabalhar por várias sessões.
Agent harness: arquitetura em camadas com estado persistente, contexto, execução de ferramentas e verificação para agentes de IA em produção
No tutorial de referência, o componente state separa três listas: done, inProgress e next. A estrutura é pequena, mas resolve uma falha comum: iniciar cada sessão sem saber o que já foi concluído. O exemplo usa um arquivo JSON local para carregar e salvar esse registro, como mostra o artigo da DEV Community.
export type HarnessState = {
done: string[];
inProgress: string[];
next: string[];
};
Em produção, o estado costuma precisar de mais campos. Inclua um identificador de execução, versão do schema, objetivo original, entradas normalizadas, resultados intermediários, timestamps, tentativas, erros e referências para artefatos. Para agentes de dados, isso pode incluir a query aprovada e o ambiente usado. Para agentes de código, branch, commit, testes e arquivos modificados.
Segundo o relatório da Arize sobre harnesses, a persistência de sessão deve usar estado append-only quando a recuperação exata após uma falha importa. O mesmo relatório apresenta nove partes da arquitetura, incluindo persistência de sessão, hooks de ciclo de vida e permissões. O dado reforça que estado é uma peça estrutural.
Histórico de mensagens e estado não são sinônimos. O histórico registra a conversa. O estado registra a situação operacional. Memória de longo prazo armazena informações que podem ser reutilizadas entre tarefas, como preferências ou fatos estáveis. Misturar as três camadas cria contexto caro, confuso e difícil de auditar.
A persistência também precisa lidar com concorrência. Duas instâncias podem tentar atualizar a mesma execução. Use controle otimista de versão, locks ou uma fila, conforme o caso. Cada transição deve ser idempotente: repetir a operação não pode criar um pedido duplicado, cobrar duas vezes ou publicar o mesmo arquivo.
Uma forma prática de modelar a transição é guardar eventos, em vez de apenas o último snapshot:
{
"run_id": "run_123",
"schema_version": 2,
"events": [
{"type": "task_started", "at": "2026-08-25T10:00:00Z"},
{"type": "tool_called", "name": "query_database"},
{"type": "tool_succeeded", "name": "query_database"}
]
}
Com eventos, fica mais fácil reproduzir a execução, investigar uma falha e migrar o formato. O snapshot ainda pode ser gerado para leitura rápida. O importante é definir o contrato antes de conectar o agente a sistemas externos.
Como fornecer contexto relevante sem sobrecarregar o agente?
Contexto relevante é o conjunto mínimo de informações necessárias para o próximo passo correto. O harness deve selecionar, ordenar, compactar e identificar as fontes antes de enviar tudo ao modelo. Mais tokens não garantem melhor decisão. Contexto excessivo aumenta custo, latência e a chance de instruções conflitantes.
Agent harness filtra contexto bruto em informações relevantes para que o agente de IA execute tarefas com estado persistente e verificações estruturadas
O componente context do tutorial consulta metadados do workspace e monta um mapa de dependências antes da primeira ação. A ideia pode ser ampliada para documentos, esquema de banco, resultados de ferramentas, regras de negócio e estado atual. O agente começa com uma visão estruturada, em vez de redescobrir relações a cada sessão.
O DataCamp descreve o harness como responsável por oferecer um ambiente de execução e administrar o que chega ao modelo. Já a Salesforce trata o harness como a infraestrutura que conecta raciocínio, ferramentas, memória, regras e execução. As fontes convergem num ponto: contexto precisa ser gerenciado.
Comece pela hierarquia. Instruções de sistema e políticas devem ter prioridade sobre dados recuperados. O estado da tarefa vem depois. Documentos e resultados externos entram com origem, data e escopo. Essa organização não elimina conflitos, mas torna a resolução mais previsível.
Registre as fontes usadas. Um item de contexto pode carregar source_id, timestamp, permissões e versão. Se o agente responder com base num documento desatualizado, você consegue descobrir por quê. Sem esse registro, uma resposta errada parece apenas uma alucinação genérica.
A compactação também precisa preservar decisões, pendências e restrições. Resumir todo o histórico em um parágrafo pode apagar uma autorização negada ou uma condição de negócio. Prefira resumos estruturados, com fatos confirmados, hipóteses abertas e ações realizadas.
E se duas fontes discordarem? Não deixe o modelo resolver silenciosamente. Defina uma política: priorizar o sistema de registro, marcar a inconsistência, pedir confirmação ou bloquear a ação. Dados sensíveis exigem ainda filtragem por identidade e finalidade. Contexto útil para um usuário pode ser proibido para outro.
Uma estratégia simples para cada ciclo é:
Carregar o estado da execução.
Recuperar apenas as fontes ligadas ao próximo objetivo.
Aplicar permissões e limites de tamanho.
Ordenar instruções, estado, evidências e ferramentas.
Registrar o pacote de contexto enviado.
Esse pacote pode ser salvo junto do trace. Assim, uma avaliação futura reproduz não só o prompt, mas também os dados que estavam disponíveis naquele momento.
O que são evals e como verificar se o agente concluiu a tarefa?
Evals são avaliações sistemáticas da qualidade e do comportamento de um agente. Elas verificam se a tarefa produziu o resultado esperado, se as ferramentas foram usadas corretamente, se as políticas foram respeitadas e se a execução permaneceu dentro dos limites. Ler apenas a resposta final não basta para avaliar um sistema que age.
Agent harness em produção: execução controlada de agentes de IA com estado persistente, contexto relevante, ferramentas seguras, políticas respeitadas e limites operacionais
O verificador do tutorial original começa com uma regra simples: procurar sinais de sucesso ou falha na saída. Ele retorna quatro vereditos, NO, YES, MAYBE e IFF, conforme a implementação publicada na DEV Community. É um bom ponto de partida, mas palavras-chave não provam que uma ação ocorreu.
O artigo acadêmico sobre harness engineering propõe transformar cada execução em um pacote auditável de episódio, com logs, atribuição de falhas e verificações estruturadas, segundo o resumo do trabalho. A proposta é importante porque desloca a avaliação da frase final para as evidências da trajetória.
Há pelo menos quatro tipos de avaliação. A determinística compara um resultado com uma regra exata, como schema válido ou arquivo existente. A avaliação por critérios verifica uma rubrica. A avaliação por modelo usa outro modelo como juiz. A validação observável confere efeitos reais, como status de pedido, teste executado ou registro atualizado.
Use cada tipo onde ele funciona melhor. Um JSON pode ser validado por schema. Uma explicação pode exigir critérios semânticos. Uma transferência bancária precisa de confirmação no sistema de origem, não de uma frase convincente do agente.
As métricas devem cobrir a execução completa. Acompanhe taxa de sucesso, falhas por ferramenta, custo, latência, número de tentativas, necessidade de intervenção humana e regressões entre versões. Não invente uma meta universal. O limite aceitável depende do risco e do valor da tarefa.
Um conjunto inicial de casos deve conter entradas normais, ambíguas, incompletas e adversariais. Inclua timeout, resposta inválida da API, ferramenta indisponível, documento contraditório e retomada após queda. Para cada caso, defina o resultado esperado e o que deve acontecer quando o agente não puder concluir.
Um fluxo de avaliação pode ser descrito assim:
const result = await evaluate({
finalState,
toolTrace,
artifacts,
policyEvents,
});
if (!result.success) {
await pauseForReview(result.reasons);
}
A avaliação deve rodar antes e depois de mudanças no modelo, prompt, ferramenta ou componente. Se o agente ficou mais barato, mas passou a chamar uma API destrutiva com mais frequência, houve regressão. Evals tornam esse trade-off visível.
Um harness confiável precisa controlar ferramentas, permissões e falhas
Estado, contexto e evals formam o núcleo, mas não bastam quando o agente pode agir fora da conversa. Ferramentas precisam de contratos, permissões, limites e validação. Falhas devem produzir estados recuperáveis. Ações de alto impacto precisam de aprovação humana ou de uma política explícita de bloqueio.
Agent harness: controle de permissões, bloqueios e aprovações necessárias para agentes de IA em produção
A Salesforce destaca permissões, guardrails e governança como partes do ambiente de agentes. O relatório da Arize lista modos como somente leitura, escrita no workspace e acesso completo, além de aprovação interativa. Esses controles definem o que pode acontecer, não apenas o que o modelo deveria fazer.
Comece pelo contrato de cada ferramenta. Defina argumentos tipados, valores permitidos, timeout, custo estimado, efeitos colaterais e resposta esperada. Valide os argumentos antes da chamada. Nunca confie apenas na descrição textual fornecida ao modelo.
Retries exigem cuidado. Repetir uma consulta de leitura costuma ser seguro. Repetir uma chamada de pagamento pode ser desastroso. Use idempotency keys, reconciliação com o sistema externo e políticas diferentes para operações reversíveis e irreversíveis.
Circuit breakers interrompem uma sequência quando há falhas repetidas, custo acima do orçamento ou comportamento fora do padrão. Limites de iteração evitam loops. Timeouts por ferramenta impedem que uma dependência lenta bloqueie toda a execução.
Logs estruturados devem registrar quem iniciou a execução, qual modelo foi usado, qual versão do prompt estava ativa, que contexto entrou, qual ferramenta foi chamada e qual decisão veio depois. Evite guardar segredos e dados pessoais sem necessidade. Observabilidade útil também respeita privacidade.
Aprovação humana não deve ser um botão genérico no final. Ela precisa aparecer antes de ações com impacto financeiro, jurídico, reputacional ou sobre dados sensíveis. O pedido de aprovação deve mostrar intenção, argumentos, evidências e consequência provável. Caso contrário, a pessoa apenas carimba uma caixa.
Respostas incompletas pedem estados explícitos. Use blocked, needs_review, retryable_error e completed, por exemplo. Evite tratar qualquer saída textual como sucesso. O sistema precisa saber diferenciar uma conclusão, uma dúvida e uma falha parcial.
Como organizar componentes reutilizáveis com Bit?
Bit pode organizar o harness como componentes independentes, versionados e compartilháveis. Um desenho inicial separa armazenamento de estado, carregamento de contexto, execução de ferramentas e verificação. Cada componente publica um contrato claro. Essa organização reduz cópia de scripts entre projetos, mas não substitui decisões de arquitetura ou operação.
Arquitetura de agent harness com componentes versionados: estado persistente, contexto gerenciado, ferramentas seguras, verificação e observabilidade integrados para agentes de IA em produção
A documentação oficial define o Bit Component como um contêiner para peças de software composáveis. A página lista recursos como versionamento automático, dependências simplificadas, nomes expressivos e uso em diferentes projetos. Para um harness, isso combina com a necessidade de distribuir módulos pequenos sem empacotar uma aplicação inteira.
O tutorial usa três componentes: harness/state, harness/context e harness/verifier. O primeiro lê e salva o estado. O segundo monta um mapa de dependências. O terceiro verifica a saída antes de o loop continuar. Essa divisão cria fronteiras úteis para testes e evolução.
Uma estrutura possível seria:
harness/
state/
state.ts
state.spec.ts
context/
context.ts
context.spec.ts
tools/
executor.ts
executor.spec.ts
verifier/
verifier.ts
verifier.spec.ts
O contrato entre os componentes deve ser mais estável que a implementação. loadState() pode trocar JSON local por banco sem alterar o loop do agente. buildContext() pode começar consultando um workspace e depois usar um índice de documentos. O restante do sistema deve depender da interface, não do detalhe.
Depois de testar, o fluxo do Bit permite versionar e exportar componentes para um escopo remoto. A documentação mostra o comando bit export e explica que o escopo armazena versões exportadas, segundo a referência oficial. O consumo pode ocorrer em outros workspaces, conforme a estratégia do time.
Bit não é obrigatório. Um monorepo, pacotes npm, uma biblioteca interna ou um repositório separado também resolvem o problema. A escolha depende de governança, familiaridade, CI e necessidade de compartilhar componentes entre equipes.
O ganho aparece quando a reutilização é real. Se cada projeto precisa de regras diferentes, forçar um componente comum pode aumentar o acoplamento. Comece com contratos pequenos, testes de compatibilidade e versionamento semântico. Compartilhe depois que o comportamento estiver claro.
Como avaliar se um agent harness está pronto para produção?
Um agent harness está pronto quando seu comportamento pode ser controlado, medido e recuperado sob condições normais e adversas. A demo precisa sobreviver a interrupções, dados incompletos, ferramentas lentas, mudanças de modelo e ações repetidas. Prontidão não é uma nota do modelo; é uma propriedade do sistema inteiro.
Agent harness: arquitetura de produção para agentes de IA com estado persistente, contexto versionado, evals observáveis, ferramentas controladas e governança pronto para produção
O trabalho do arXiv propõe níveis de maturidade de H0 a H3, aumentando o suporte exposto ao agente e a qualidade das evidências produzidas, de acordo com o resumo do artigo. A ideia sugere uma progressão útil: sair de uma resposta final e chegar a episódios reproduzíveis, com falhas atribuídas e verificações estruturadas.
Use esta checklist antes de ampliar o escopo:
Uma execução interrompida retoma do último checkpoint correto?
O formato do estado tem versão e migração?
O contexto enviado pode ser auditado depois?
Cada ferramenta valida argumentos e identidade?
Chamadas com efeitos colaterais usam idempotência?
Existem limites de tempo, iterações, tokens e custo?
Falhas distinguem retry, bloqueio e intervenção humana?
Cada tarefa possui um critério de sucesso observável?
O trace registra modelo, prompt, contexto, ferramentas e resultados?
Mudanças passam por evals antes de chegar ao tráfego real?
Há um caminho para revogar permissões rapidamente?
Faça testes de recuperação. Mate o processo antes e depois de uma chamada externa. Simule resposta inválida. Force duas instâncias a atualizar o mesmo estado. O objetivo é descobrir se a arquitetura retoma com segurança ou apenas parece funcionar em sequência perfeita.
Teste também a governança. Um agente deve recusar uma ferramenta fora do escopo. Deve pedir aprovação quando a política exigir. Deve registrar a intervenção. Deve continuar sem expor segredos no contexto ou nos logs.
Monitore o que acontece depois do lançamento. Distribuição de latência, custo por tarefa, falhas por ferramenta e frequência de intervenção mostram mudanças de comportamento. Uma alteração aparentemente pequena no schema de uma API pode mudar o planejamento do agente.
A pergunta útil não é “o agente responde bem?”. É “o sistema consegue provar o que fez, desfazer o que precisa e parar quando não sabe continuar?”. Essa pergunta separa um protótipo convincente de uma operação confiável.
Perguntas frequentes
Agent harness coordena estado persistente, contexto relevante, evals, ferramentas seguras e observabilidade para preparar agentes de IA para produção
O que é um agent harness?
É a camada de software ao redor do modelo que coordena contexto, estado, ferramentas, permissões, execução e verificação. O DataCamp explica que o harness fornece ao raciocínio um lugar para agir, lembrar, checar resultados e seguir regras. Em sistemas longos, ele também registra traces e recupera falhas.
Qual é a diferença entre agent harness e framework de agentes?
Um framework oferece blocos para construir agentes, como chamadas de modelo, ferramentas e loops. O harness combina blocos com decisões operacionais, contexto, permissões, critérios de sucesso e observabilidade. A distinção não é universal. O guia do DataCamp sobre framework, runtime e harness trata essa taxonomia como uma separação útil, mas móvel.
O que deve ser armazenado no estado de um agente?
Armazene progresso, pendências, entradas normalizadas, resultados intermediários, erros, tentativas, versão do schema e metadados da execução. Não confunda estado com histórico completo de mensagens. O relatório da Arize destaca persistência de sessão e retomada após crashes como responsabilidades do harness.
O que são evals em agentes de IA?
Evals são testes sistemáticos que verificam qualidade, segurança e comportamento. Eles podem comparar resultados exatos, aplicar rubricas, usar um modelo avaliador ou conferir efeitos observáveis em sistemas externos. O artigo sobre guardrails para agentes de IA ajuda a conectar avaliações com validação, monitoramento e políticas.
Bit é obrigatório para criar um agent harness?
Não. Bit é uma opção para criar, versionar e exportar componentes reutilizáveis. Você também pode usar pacotes npm, monorepos ou bibliotecas internas. A documentação do Bit Component mostra os benefícios do modelo, mas a confiabilidade vem dos contratos, testes, permissões, estado e evals, independentemente da ferramenta escolhida.
Da demonstração ao sistema confiável
Um agente experimental costuma ter um prompt, algumas ferramentas e uma resposta final. Um agente de produção precisa de estado para continuar, contexto para decidir e evals para provar que concluiu. Ao redor desses pilares entram permissões, limites, retries, logs, intervenção humana e componentes versionados.
Agent harness em produção: estado persistente, contexto relevante, evals, ferramentas seguras, observabilidade e conectividade garantem execução controlada e confiável de agentes de IA.
A sequência prática é começar pequeno. Defina um contrato de estado. Registre o contexto usado. Crie um verificador para o resultado observável. Depois adicione limites de ferramenta, tracing e recuperação. Só então amplie o número de ferramentas, agentes ou tipos de tarefa.
O harness também precisa evoluir junto com modelos e regras de negócio. Uma nova versão pode alterar custo, latência, chamadas de ferramenta ou necessidade de intervenção. Por isso, cada mudança deve ser comparada com evals e traces anteriores.
Para continuar, vale estudar observabilidade em agentes com LlamaIndex e revisar os frameworks de agentes de IA. O objetivo não é escolher a stack mais famosa. É construir um sistema que saiba agir, lembrar, verificar e parar.
Quer acompanhar discussões práticas sobre dados, IA e engenharia? Inscreva-se na newsletter do Data Hackers para receber os próximos conteúdos.