Trilha de auditoria de agentes de IA: como registrar cada ação do chatbot

Em 9 de julho, a OpenAI adicionou chamadas de ferramentas programáticas e orquestração multiagente em beta ao GPT-5.6. Esse lançamento segue um movimento mais amplo, de respostas curtas para agentes que trabalham em várias ferramentas por muito mais tempo: a OpenAI relatou que 70,2% dos usuários do Codex amostrados haviam solicitado pelo menos uma tarefa estimada em mais de uma hora de trabalho humano até maio de 2026. Mais ações por tarefa criam mais pontos onde intenção, execução e resultado podem se distanciar.

As falhas costumam ser comuns, não hostis. Depois de analisar um milhão de tarefas de agentes de codificação, o Google DeepMind descobriu que a maioria dos eventos sinalizados vinha de interpretação incorreta ou de excesso de iniciativa. Uma trilha de auditoria de agentes de IA útil, portanto, precisa reconstruir cada ação de maior impacto do chatbot, incluindo as tentativas repetidas de aparência inofensiva que criam reembolsos, tickets, reservas ou e-mails duplicados.

Comece com este registro de evento mínimo. Armazene um evento para cada mudança de estado, acrescente novos eventos em vez de sobrescrever os antigos e vincule cada evento ao mesmo trace.

Campo	Registra	Por que importa
`trace_id`	Um ID para toda a solicitação do usuário	Reconstrói uma execução de várias etapas
`action_id`	Um ID para a ação de negócio pretendida	Agrupa tentativas e retentativas
`attempt_id`	Um ID único para cada chamada de ferramenta	Expõe execuções duplicadas
`idempotency_key`	Chave estável enviada ao destino	Evita efeitos colaterais repetidos
`actor`	Usuário, chatbot, subagente, aprovador ou serviço	Estabelece responsabilidade
`tool` e `operation`	Conector mais a operação exata	Mostra qual capacidade foi executada
`input_summary` e `input_hash`	Resumo com dados sensíveis removidos mais hash da entrada canônica	Permite revisão sem copiar segredos
`decision`	Permitir, negar, exigir aprovação ou escalar	Captura o resultado da política
`result`	Sucesso, falha, timeout, desconhecido ou compensado	Separa o status de transporte do resultado de negócio
`external_reference`	ID de reembolso, ticket, reserva ou mensagem	Conecta o trace ao sistema de registro
`occurred_at`	Timestamp do servidor em UTC	Ordena eventos entre serviços

Separe intenção, tentativa e efeito

Uma transcrição de chat geralmente captura a intenção: "Reembolse meu último pedido." Um log HTTP captura uma tentativa: POST /refunds. Um processador de pagamento captura o efeito: o reembolso rf_8421 alterou o saldo da conta. Nenhum desses registros comprova os outros dois.

Trate-os como três fatos relacionados:

Intenção registra a solicitação do usuário, a interpretação do agente, a ferramenta selecionada e os parâmetros propostos.
Tentativa registra a operação exata enviada, a decisão da política, o destino, o timeout e a classe de resposta.
Efeito registra o resultado externo durável, como um ID de reembolso e valor, um status de reserva ou uma transição de ticket.

Essa separação importa sempre que uma solicitação expira. Um timeout significa que quem chamou não recebeu resposta. O destino ainda pode ter concluído a ação. Se o registro de auditoria reduzir "sem resposta" a "falhou", o chatbot pode repetir uma operação que já teve sucesso.

O mesmo limite aprimora as permissões. O checklist de permissões de ferramentas do chatbot ajuda a decidir se um bot pode chamar uma capacidade. A trilha de auditoria fornece evidências sobre o que aconteceu depois dessa decisão.

Dê quatro IDs a cada ação

Um único ID de conversa não é suficiente para uma investigação em produção. Uma conversa de suporte pode disparar várias ações, e cada ação pode ter várias tentativas.

Use quatro identificadores com ciclos de vida diferentes:

ID de conversa. Agrupa as mensagens visíveis ao usuário. Mantenha-o estável durante toda a sessão de chat.

ID de trace. Agrupa o trabalho necessário para cumprir uma solicitação. Uma nova solicitação na mesma conversa deve receber um novo trace.

ID de ação. Identifica a operação de negócio que o agente pretende concluir, como "reembolsar o pedido 10492 em $48." As retentativas mantêm o mesmo ID de ação.

ID de tentativa. Identifica uma chamada de rede. Cada retentativa recebe um novo ID de tentativa para que os operadores possam ver quantas vezes o sistema tentou.

Passe os IDs de trace e de ação por webhooks, filas, serviços de conectores e telas de aprovação. Se uma API de terceiros aceitar metadados, inclua-os ali também. Um investigador deve conseguir partir de uma mensagem do cliente, de uma falha de job ou de uma transação externa e chegar ao mesmo trace.

Incidente na prática: o reembolso que rodou duas vezes

Suponha que um cliente escreva: "Por favor, reembolse a cobrança duplicada de $48 no pedido 10492." O chatbot encontra dois pagamentos capturados, propõe reembolsar a cobrança mais recente e recebe aprovação humana. A API de pagamento processa o reembolso, mas sua resposta ultrapassa um timeout de 10 segundos. Um worker repete a solicitação sem uma chave de idempotência, criando um segundo reembolso.

A primeira tentativa deve produzir um evento append-only como este:

{
  "event_type": "tool.attempt.finished",
  "trace_id": "tr_7f2c",
  "action_id": "act_refund_10492_48usd",
  "attempt_id": "att_01",
  "conversation_id": "conv_5198",
  "actor": {
    "type": "chatbot",
    "id": "billing-support"
  },
  "tool": "payments",
  "operation": "create_refund",
  "decision": "approved",
  "approval_event_id": "apr_6630",
  "input_summary": "Refund $48.00 to payment ending 8812",
  "input_hash": "sha256:4cb3...91e0",
  "idempotency_key": null,
  "result": "timeout_unknown",
  "external_reference": null,
  "occurred_at": "2026-07-15T09:42:18.511Z"
}

O resultado timeout_unknown é a pista crucial. O worker precisa consultar o processador usando os identificadores estáveis da ação antes de tentar novamente. Se encontrar o reembolso rf_8421, ele anexa um evento effect.confirmed e encerra a ação. Se não conseguir consultar, a ação vai para revisão em vez de ser executada novamente de forma cega.

Agora imagine que a duplicidade já aconteceu. Um trace completo mostra o mesmo ID de ação, dois IDs de tentativa, nenhuma chave de idempotência e dois IDs de reembolso externos. A correção pode registrar uma ação compensatória separadamente. Os operadores podem responder ao cliente, os engenheiros podem corrigir o comportamento de retentativa e o financeiro pode reconciliar o livro-razão a partir da mesma evidência.

É também por isso que os registros de aprovação precisam conter mais do que um clique. O guia de fluxos de aprovação de chatbot explica como mostrar a consequência e os parâmetros antes da execução. Sua trilha de auditoria deve vincular esse payload aprovado ao payload executado com um hash canônico.

Torne as retentativas rotineiras

Retentativas são normais em sistemas distribuídos. Redes travam, filas reentregam jobs, workers reiniciam e provedores retornam erros ambíguos. O design seguro assume que cada ação pode ser tentada mais de uma vez.

Gere a chave de idempotência a partir da ação de negócio estável, não da tentativa. Para o reembolso acima, a chave poderia derivar do ID do tenant, do ID do pagamento, do valor do reembolso, do motivo e do ID da ação. Toda retentativa envia a mesma chave. Um valor ou destino alterado se torna uma nova ação que exige uma nova decisão.

Depois, defina regras de retentativa por resultado:

Falha definitiva antes da aceitação: repita automaticamente com a mesma ação e a mesma chave de idempotência.
Timeout ou perda de conexão após o envio: consulte o status primeiro; repita somente quando o destino comprovar que nenhum efeito existe.
Falha de validação ou permissão: pare e mostre a correção específica necessária.
Limite de taxa ou falha temporária do provedor: respeite o sinal de backoff do provedor e preserve a mesma identidade de ação.
Resultado desconhecido sem suporte a consulta: exija revisão para ações de maior impacto.

Registre o motivo do agendador para cada retentativa. "Tentativa 2 iniciada" é uma evidência fraca. "Tentativa 2 iniciada após a consulta de status não retornar reembolso correspondente" é uma evidência revisável.

Vincule aprovações ao payload executado

Uma aprovação só é válida para a ação que a pessoa viu. Se um chatbot pede para reembolsar $48 e depois executa $96, a presença de um evento de aprovação oferece um falso conforto.

Canonize o payload proposto, remova campos voláteis como timestamps e calcule o hash do resultado. Armazene esse hash junto com a aprovação. Imediatamente antes da execução, calcule o hash novamente. Uma divergência deve invalidar a aprovação e devolver a proposta alterada ao aprovador.

Registre estes detalhes com o evento de aprovação:

identidade e função do aprovador;
política ou regra que exigiu aprovação;
consequência legível mostrada ao humano;
hash canônico do payload;
expiração da aprovação;
decisão e motivo opcional;
IDs de trace e de ação.

Mantenha também os eventos de negação e expiração. Uma sequência append-only mostra se um agente respeitou a decisão ou tentou um caminho diferente depois de ser bloqueado.

Oculte dados sensíveis sem destruir evidências

Payloads brutos de ferramentas podem conter tokens de acesso, dados de pagamento, informações de saúde, mensagens privadas e identificadores pessoais. Copiar tudo isso em um log pesquisável cria um segundo banco de dados sensível.

Use um registro em camadas. Coloque um resumo com dados sensíveis removidos no evento operacional. Armazene um hash da entrada canônica para detectar mudanças. Se a retenção do payload completo for genuinamente necessária, criptografe-o em um repositório de evidências restrito, com um período de retenção mais curto e controles de acesso separados.

Defina o mascaramento campo a campo, não apenas por expressão regular. Um bearer token nunca deve entrar no pipeline de eventos. Endereços de e-mail podem ser mascarados em visões operacionais amplas, permanecendo disponíveis para um pequeno grupo de suporte. Entradas de texto livre precisam de limites de tamanho e detecção de segredos, porque os usuários colam credenciais nas janelas de chat.

A privacidade também afeta fornecedores de observabilidade. Antes de exportar traces, decida quais campos saem do seu ambiente, em qual região eles são armazenados e se as solicitações de exclusão se propagam. O guia de segurança administrativa do chatbot cobre mudanças de configuração privilegiadas; aplique a mesma segregação de funções ao acesso e à retenção do log de auditoria.

Transforme traces em perguntas operacionais

Os painéis devem responder a perguntas concretas em vez de celebrar volume de eventos. Comece com consultas que revelem dano ao cliente:

Quais efeitos de negócio bem-sucedidos seguiram uma resposta de timeout?
Quais IDs de ação produziram mais de uma referência externa?
Quais hashes de payload aprovados diferem dos hashes de payload executados?
Quais ferramentas têm a maior taxa de resultado desconhecido?
Quais usuários ou tenants disparam mais retentativas?
Quais ações foram concluídas depois que uma aprovação expirou?
Quais ações negadas foram seguidas por uma ação semelhante por meio de outra ferramenta?

Revise uma amostra de traces normais ao lado de cada incidente. Exemplos normais mostram se o schema é compreensível antes que a pressão chegue. Eles também revelam transferências ausentes, rótulos de resultado enganosos e campos que as equipes presumiram que outro serviço registrava.

Para ações de baixo risco, uma revisão adiada pode ser suficiente. O roteiro de controle do Google DeepMind, de forma semelhante, distingue o monitoramento retrospectivo para comportamento reversível do bloqueio em tempo real para ações graves. Atribua a cada ferramenta um modo de revisão baseado na consequência: amostragem assíncrona, alerta por anomalia, aprovação antes da execução ou aplicação de política síncrona.

Teste a trilha de auditoria como uma superfície de produto

Uma trilha de auditoria pode falhar enquanto o chatbot parece saudável. Adicione testes de release que criem deliberadamente estados incômodos:

Force um timeout depois que o destino aceitar uma ação.
Entregue a mesma mensagem de fila duas vezes.
Altere um parâmetro aprovado antes da execução.
Rotacione uma credencial de conector durante uma tarefa de várias etapas.
Retorne um status HTTP de sucesso com um resultado de negócio rejeitado.
Execute dois subagentes contra a mesma solicitação do cliente.
Exclua ou mascare dados do cliente e verifique as regras de retenção nas exportações.

Para cada teste, comece a partir de três pontos: a conversa, o job interno e a transação externa. Todos os três devem levar a um único trace coerente. Alguém que não construiu a integração deve conseguir explicar o que o usuário pediu, o que o agente decidiu, o que o sistema tentou e o que de fato mudou.

A descrição da Anthropic sobre agentes confiáveis enfatiza a transparência à medida que os agentes planejam, agem, observam e repetem o ciclo entre ferramentas. O padrão prático é um trace que sobrevive a esse ciclo, incluindo transferências entre subagentes e intervenções humanas.

Um recibo faz parte da ação

A resposta visível ao cliente, "Seu reembolso está concluído", deve ser gerada a partir de um efeito confirmado, não da intenção do chatbot ou de um disparo de ferramenta bem-sucedido. A mesma referência externa mostrada ao suporte deve aparecer no recibo do usuário quando aplicável.

À medida que as tarefas do chatbot se estendem por mais ferramentas, modelos, workers e aprovações, uma trilha de auditoria de agentes de IA se torna parte do contrato da ação. Ela dá aos clientes um recibo defensável e dá aos operadores um caminho de um resultado surpreendente de volta até a decisão e a tentativa exatas que o produziram.

No Agentkit, os logs de conversas fornecem a camada de revisão legível por humanos, e as ações de API personalizadas conectam chatbots a sistemas de negócio; mantenha os recibos do sistema de registro vinculados junto a essas conversas.

Crie seu chatbot gratuitamente →

Não é necessário cartão de crédito.