Logs para replay de agentes de IA: campos para reproduzir uma falha
Quais campos o harness precisa registrar para reproduzir, passo a passo, uma execução ruim de agente de IA em ambiente de teste, com checklist prático.

Para reproduzir a execução de um agente de IA, o harness precisa registrar, em cada passo, o contexto que o modelo de fato recebeu, o modelo e as configurações usadas, cada chamada de ferramenta com seus argumentos e resultados retornados, e as versões de prompts, ferramentas e permissões em vigor naquele momento. Um ambiente de teste pode então alimentar essas entradas gravadas nos mesmos passos, com as ações que alteram sistemas substituídas por simulações, e mostrar onde a execução se afastou do esperado. Se os logs guardam apenas a resposta final, a execução ruim pode ser descrita, mas não reproduzida.
Principais pontos
- Um replay precisa do contexto que cada passo realmente viu, e não do contexto que você pretendia enviar.
- Registre a identidade do modelo, suas configurações e as versões de prompts, skills, esquemas de ferramentas e permissões em cada passo.
- Guarde os argumentos das ferramentas e os resultados completos devolvidos, com regras de mascaramento acordadas antes da primeira execução.
- Armazene um identificador de execução, um número de sequência e um vínculo com o passo anterior, para ordenar os passos e rastrear ramificações.
- Reproduza no sandbox com as escritas reais simuladas e compare o novo comportamento com o registro original.
Por que uma execução ruim não pode ser reproduzida a partir da resposta final
Uma execução de agente é uma cadeia de decisões. Cada chamada ao modelo depende de tudo o que veio antes no contexto: as instruções, os documentos recuperados, os resultados de ferramentas anteriores e a própria saída anterior do modelo. Uma ferramenta também pode alterar estados, de modo que o mesmo pedido retorne algo diferente em uma segunda tentativa. Uma mensagem final dizendo que o pedido saiu errado informa o desfecho, mas não qual passo introduziu o erro.
Replay não significa pedir ao modelo que produza as mesmas palavras de novo. Modelos não garantem saídas idênticas, e o fornecedor pode ter mudado o comportamento desde a execução original. O que você precisa é poder executar novamente o harness com as entradas registradas em cada passo, para ver se a decisão que falhou foi causada pelo contexto, pela ferramenta, pela configuração de permissões ou pelo modelo. Quando o modelo é executado novamente em um único passo, essa reexecução é um teste, e o resultado deve ser guardado como registro próprio.
Os campos que cada registro de passo precisa ter
Pense no log como uma sequência de registros de passo sob um mesmo identificador de execução. Cada registro deve conter, no mínimo, os campos abaixo.
- Identificador da execução, identificador do passo, identificador do passo pai e número de sequência, para ordenar os passos e rastrear ramificações.
- Carimbos de início e fim em UTC para cada chamada ao modelo e para cada chamada de ferramenta.
- Versão do harness, versão do prompt e os identificadores de cada arquivo de habilidade e de cada esquema de ferramenta carregado naquele passo.
- Nome do modelo, string de versão do fornecedor e configurações de amostragem, como temperatura e tamanho máximo da saída.
- O contexto completo enviado ao modelo, ou uma cópia armazenada de cada bloco de contexto com um hash de conteúdo que comprove que não foi alterado.
- A saída bruta do modelo, incluindo o motivo de parada e qualquer pedido de chamada de ferramenta exatamente como foi emitido.
- Para cada chamada de ferramenta: o nome da ferramenta, os argumentos validados, a decisão de permissão e o identificador de quem aprovou, caso houve uma etapa humana.
- Para cada resultado de ferramenta: a resposta como foi recebida, a versão passada ao modelo após qualquer truncamento e um marcador do que foi removido.
- Status, classe do erro, número de tentativas e a regra que escolheu o próximo passo.
- Contagem de tokens e custo do passo, para que um estouro de orçamento possa ser explicado além de interrompido.
Mantenha o resultado bruto e o resultado truncado em dois campos separados. Equipes costumam truncar para proteger a janela de contexto e só depois descobrem que o campo que explicava a falha foi justamente o cortado. Guardar os dois permite reproduzir o que o modelo viu e auditar o que o harness reteve.
Parte desses dados é pessoal ou confidencial. Registre referências a segredos, nunca os segredos em si, mascare identificadores de clientes na captura quando o fluxo permitir, defina os prazos de retenção antes da primeira execução e limite quem pode ler blocos de contexto completos. Pela LGPD e pelas regras europeias de proteção de dados, um log que contenha pessoas identificáveis continua sendo dado pessoal, então a retenção dele deve entrar na mesma revisão do restante do tratamento de dados.
Um plano de replay que você pode seguir
Quando uma execução dá errado, percorra o registro nesta ordem. O objetivo é reproduzir a decisão de forma isolada antes de mudar qualquer coisa em produção.
- Congele a execução com problema copiando seus registros para um armazenamento somente leitura e anotando quem pediu a investigação.
- Restaure as versões do harness, do prompt, da habilidade e do esquema de ferramenta indicadas no primeiro registro de passo, e não as versões atualmente implantadas.
- Carregue as permissões registradas e substitua cada ferramenta que escreve em um sistema real por uma simulação que devolve a resposta gravada.
- Alimente cada resultado de ferramenta registrado na sequência e compare os argumentos gerados pelo modelo com os originais.
- Pare na primeira divergência e registre o que mudou: a saída do modelo, os argumentos, o contexto recuperado ou a decisão do harness.
- Execute o modelo novamente apenas naquele passo, várias vezes, para descobrir se a falha é estável ou intermitente.
- Escreva a causa como uma mudança específica em um prompt, na descrição de uma ferramenta, em uma permissão, em um orçamento ou em uma condição de parada, e então repita a mesma execução com essa mudança antes de qualquer liberação.
O ambiente de teste deve ser separado da produção e não ter nenhum caminho para credenciais reais. O texto Ambiente sandbox para agentes de IA: teste mudanças antes de irem ao ar detalha essa separação.
Um cenário ilustrativo: o pedido duplicado
Cenário ilustrativo: uma pequena equipe de operações usa um agente que atualiza pedidos de fornecedores a partir de confirmações por e-mail. Em uma tarde, o sistema de pedidos responde devagar, uma chamada de ferramenta expira e o agente envia o pedido novamente. A equipe tem apenas uma mensagem final informando dois pedidos, sem nenhuma explicação de como o segundo surgiu.
Os registros de passo contam uma história mais útil. A primeira chamada de ferramenta retornou timeout, mas o harness guardou apenas o código de status, não a classe do erro. A regra de truncamento manteve as primeiras linhas da resposta, que não continham nenhum campo de erro. A lógica de nova tentativa tratou então a chamada como falha, sem saber que ela havia sido parcialmente bem-sucedida, e emitiu uma nova escrita sem chave de idempotência. Ao reproduzir a execução com a ferramenta simulada, a divergência apareceu no passo de nova tentativa, e não na chamada ao modelo.
As correções foram específicas. A regra de truncamento agora sempre preserva o bloco de erro, toda escrita guarda sua chave de idempotência, e qualquer criação de pedido que venha depois de um timeout passa por uma aprovação humana. Cada mudança foi testada reproduzindo a mesma execução antes de chegar ao sistema real. Para a regra de truncamento, o texto Truncamento de resultados em agentes de IA: mantenha os campos que decidem explica quais campos proteger.
Como a Be Human trata o replay em operações gerenciadas
A Be Human trata o esquema de logs como parte do primeiro trabalho, e não como um detalhe posterior. Quando um papel útil é definido, a memória que ele lê, as ferramentas que chama, os limites de aprovação e o critério de sucesso determinam quais campos precisam ser registrados, para que os logs descrevam as decisões que o agente de fato toma. Em operações gerenciadas, esses mesmos registros sustentam o monitoramento, a resposta a incidentes e as avaliações recorrentes. As regras de retenção são aplicadas, as mudanças de permissão são revisadas contra o histórico registrado, e falhas passadas são reproduzidas antes que qualquer melhoria controlada chegue ao harness em produção. Uma revisão de incidente, então, começa com evidências registradas, e não com a lembrança de o que se pediu ao agente.
Erros que tornam uma execução ruim impossível de reproduzir
A maioria das falhas de replay vem de um pequeno conjunto de hábitos. O mais comum é registrar a resposta final sem registrar os passos. Outro é guardar o template do prompt sem o prompt renderizado, porque o template não mostra os documentos recuperados que o modelo leu. Deixar as versões fora do registro dificulta saber se uma mudança de comportamento veio de um prompt novo, de uma nova descrição de ferramenta ou de uma atualização do modelo. Algumas equipes também reproduzem contra sistemas reais, o que transforma uma investigação em um segundo incidente. Um harness que muda sem histórico de liberações não consegue dizer qual configuração uma execução usou, um problema tratado em Versionamento de harness de IA: uma nota de release para cada mudança.
Por onde começar com o registro para replay
Comece pelo fluxo em que uma execução ruim seria mais difícil de explicar. Adicione os campos de passo a esse fluxo primeiro, execute-o em ambiente de teste até que um replay reproduza uma falha real, e só então amplie o esquema para outros fluxos. Se você não tem certeza de qual fluxo merece essa atenção primeiro, faça o diagnóstico gratuito de IA da Be Human para encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
Um replay consegue reproduzir exatamente a saída que o modelo deu na primeira vez? Não de forma confiável. A saída do modelo pode variar entre chamadas, e os fornecedores atualizam seus modelos, então um replay deve reproduzir as entradas e os resultados de ferramentas registrados, e não prometer as mesmas palavras. Executar o modelo novamente no passo que falhou mostra se o comportamento é estável, e essa reexecução deve ser guardada como registro próprio.
É seguro armazenar prompts e resultados de ferramentas completos? Somente com controles em vigor. Mascare valores pessoais e confidenciais quando o fluxo permitir, mantenha os segredos fora dos logs por completo, limite quem pode ler blocos de contexto completos e defina os prazos de retenção antes da primeira execução. Trate o armazenamento de logs como dado sensível, porque ele muitas vezes contém mais detalhes do que o sistema original.
Por quanto tempo os logs de agentes devem ser guardados? O prazo adequado depende das suas obrigações legais, do seu setor e do seu ciclo interno de revisão, então ele deve ser decidido com as pessoas responsáveis por proteção de dados e compliance. Escreva o prazo na política de logs, aplique-o automaticamente e documente as exclusões. Retenções mais curtas reduzem a exposição, mas problemas costumam aparecer depois, então defina o prazo levando esse atraso em conta.
Preciso de ferramentas de replay antes de o primeiro agente entrar em operação? Você precisa do esquema de logs antes da primeira execução, porque os registros não podem ser recriados depois. As ferramentas de replay podem começar mais simples, por exemplo com um script que alimenta resultados gravados em um ambiente simulado. Construa ferramentas mais completas conforme cresce o número de fluxos e fica mais claro o custo de um incidente.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


