O que Deve Ser Registrado em uma Trilha de Auditoria de Agentes de IA?

Registre as evidências necessárias para distinguir quem solicitou uma ação, que autoridade o executor usou, qual decisão se aplicava a qual proposta e que resultado foi realmente observado. Uma trilha de auditoria de agentes de IA conecta esses registros às suas fontes e limitações. Um histórico de conversa ou identificador de sessão, isoladamente, não estabelece essa conexão.

A governança de agentes de IA define a autoridade e as responsabilidades envolvidas. A trilha de auditoria permite examinar essa autoridade depois de uma decisão ou ação. Especifique as informações necessárias ao longo da trilha, sem exigir todos os campos em cada evento nem presumir que toda integração pode fornecê-los. A observabilidade de agentes descreve a telemetria disponível para entender o fluxo; uma trilha de auditoria organiza evidências para uma pergunta de revisão.

Comece pela pergunta que a investigação precisa responder

Considere o exemplo hipotético do guia de arquitetura: um funcionário solicita acesso de visualização para um contratado de plantão em um workspace de resposta a incidentes. O fluxo proposto exige uma aprovação aplicável do responsável pelo workspace. Suponha que uma solicitação seja enviada, mas sua resposta se perca, e que uma consulta posterior mostre o contratado como membro. Essas são condições ilustrativas, não telemetria coletada ou uma integração da KonaSense.

A consulta posterior estabelece um estado observado de associação ao workspace. Ela não identifica qual tentativa produziu esse estado, se o perfil aprovado foi o enviado ou se outro ator alterou a associação. Essas perguntas exigem registros com uma relação causal com a operação, não apenas timestamps próximos.

Os grupos de campos a seguir descrevem uma especificação de evidências para responder a essas perguntas. Eles não são um schema de exportação de produto.

Identifique os atores e o trabalho ao qual estão vinculados

Ator / usuário: registre a referência da pessoa ou do sistema solicitante e como essa identidade foi estabelecida. A fonte pode ser o contexto autenticado da solicitação ou um sistema aprovado de gestão de tarefas. Distinga um solicitante verificado de um nome informado em um prompt. No exemplo, o funcionário que pede acesso e o contratado que o recebe têm papéis diferentes.

Identidade do agente: identifique o agente ou a instância do runtime envolvida, com uma referência de implementação ou configuração quando pertinente. Obtenha essa informação do ambiente de execução, não apenas da descrição que o agente faz de si mesmo. Identifique separadamente a conta ou identidade de serviço usada para executar a operação, incluindo o escopo de permissões relevante sem copiar a credencial. O nome atribuído ao agente não é necessariamente a identidade que o destino autoriza.

ID da sessão: use a referência de sessão do runtime para agrupar trabalhos relacionados, preservando sua origem ou namespace. Associe-a aos registros de tarefa, proposta, decisão e tentativa conforme necessário. Uma sessão pode conter várias ações, novas tentativas ou operações concorrentes; seu identificador não distingue todas elas. Trabalhos retomados também precisam permitir a identificação da configuração e das condições de autorização que se aplicavam.

Preserve a proposta e o contexto realmente avaliados

Modelo: quando um modelo participa, registre o identificador e a versão ou referência de implantação disponíveis na chamada ou na configuração do runtime. Preserve a distinção entre um alias informado e uma revisão efetivamente identificada. Se a versão exata não estiver disponível, registre essa limitação. O campo de modelo ajuda a investigar a origem da proposta; ele não estabelece a autoridade do executor nem permite reproduzir o resultado por si só.

Referência do prompt ou da entrada: identifique a entrada da tarefa e a versão usada na etapa relevante, preferencialmente por uma referência com acesso controlado quando o conteúdo integral for desnecessário. O sistema solicitante ou o runtime deve estabelecer essa associação. Defina para qual conteúdo a referência aponta, quem pode acessá-lo e o que acontece quando ele expira. Um ID cujo conteúdo não esteja disponível ou não seja confiável não explica o que o agente recebeu.

Contexto: preserve os fatos relevantes para a decisão e suas origens. No exemplo do workspace, isso inclui a conta identificada do contratado, sua designação para o incidente, o workspace, o perfil proposto e a aprovação aplicável. Associe os fatos à versão ou ao momento da observação usado na avaliação. Uma consulta posterior ao diretório pode mostrar o estado atual, em vez dos fatos em que o avaliador se apoiou.

Ferramenta selecionada: registre a identidade da ferramenta fornecida pelo runtime e o servidor ou a implementação à qual ela corresponde. Inclua uma referência de versão ou configuração quando um nome de ferramenta puder corresponder a comportamentos diferentes. A investigação precisa distinguir a interface proposta pelo agente do componente que realmente executou uma operação.

Parâmetros da ferramenta, quando apropriado: preserve os argumentos relevantes da operação proposta e, quando observáveis, os argumentos efetivamente enviados. Use campos selecionados ou referências protegidas quando os parâmetros contiverem dados sensíveis. Uma mudança de viewer para administrator é relevante para a autorização no exemplo; um registro genérico de “ferramenta de associação chamada” não revela essa diferença. Registre transformações sem substituir silenciosamente a proposta anterior.

Registre a decisão de política e a aprovação aplicável

Política avaliada: identifique a política, o conjunto de regras e a versão realmente usados pelo avaliador, junto à referência do contexto. Obtenha essas informações do fluxo de avaliação quando estiverem disponíveis. Uma cópia da política configurada posteriormente não comprova qual versão produziu uma decisão anterior. Se a versão não foi capturada, preserve essa lacuna em vez de preenchê-la com a política atual.

Decisão: retenha o resultado do avaliador e sua relação com a proposta avaliada. Mantenha separadas a resposta construída para o executor e a observação de que ele a aplicou. Solicitações negadas ou pendentes podem ter registros de decisão sem nenhuma tentativa de ação. Uma decisão Allow autoriza uma tentativa dentro de suas condições; ela não relata sucesso no destino.

Estado da aprovação: registre se a aprovação era exigida, estava pendente, foi rejeitada, concedida, expirou ou não se aplicava, conforme o mecanismo usado. Quando houver aprovação, associe sua origem, o revisor autorizado, o escopo e a versão da proposta à qual ela se aplica. Uma afirmação em texto gerado pelo agente não é o registro de aprovação. Se o workspace, o perfil, a conta ou o executor mudar, a trilha deve permitir que um revisor avalie se a aprovação anterior continuava aplicável.

Sinais de risco: retenha as observações ou avaliações que influenciaram uma decisão, com sua origem e interpretação. Distinga uma condição observada, como uma conta ainda não identificada, da avaliação de um classificador ou de uma afirmação do agente. Se uma pontuação for usada, documente seu significado e a versão relevante. Um rótulo de severidade não prova intenção maliciosa, e um sinal posterior não deve ser apresentado como se tivesse embasado uma decisão anterior.

O pilar de governança de IA em runtime explica como a validade de uma decisão muda com o contexto. A especificação de auditoria deve preservar contexto suficiente para revisar essa validade, sem afirmar que o próprio registro a fez cumprir.

Distinga uma tentativa de ação de um resultado observado

Ação tentada: identifique a tentativa específica de envio ou execução, seu destino real, a identidade executora e a relação com a proposta autorizada. A fonte deve ser um componente em posição de observar essa tentativa. Use referências distintas para novas tentativas, preservando sua relação com a operação ou tarefa comum. Não crie um evento de tentativa de ação apenas porque o avaliador retornou Allow.

Resultado da ação: preserve o que a ferramenta, o executor ou o destino realmente informou, identificando a fonte e a etapa. A aceitação de uma solicitação, a conclusão do processamento e uma observação posterior de estado são evidências diferentes. Mantenha os estados de falha, sucesso parcial e resultado desconhecido quando se aplicarem. Um erro ao receber uma resposta pode deixar o resultado no destino desconhecido, em vez de comprovar que a ação falhou.

Na mudança hipotética de associação ao workspace, um registro de auditoria no destino que vincule de forma confiável a mudança à solicitação específica enviada poderia sustentar a atribuição àquela tentativa. Sua utilidade depende de como essa associação foi produzida e verificada. Um ID de sessão repetido, um perfil correspondente ou uma consulta posterior de associação não basta por si só. Se essa associação não estiver disponível, a investigação pode relatar o estado observado e manter a causa como não esclarecida.

A nota controlada sobre a ação do agente compara condições deliberadas de replay local em que a confirmação indisponível para o componente chamador acompanha estados diferentes de arquivo observados, com referências aos registros coletados e seus limites.

Separe o horário do evento do horário da coleta

Timestamp: registre quando a fonte informa que o evento ocorreu e, quando disponível, quando o sistema de coleta o observou ou recebeu. Identifique a origem do relógio, a incerteza relevante e qualquer conversão. Um atraso na coleta pode fazer um evento antigo aparecer depois no sistema receptor; relógios diferentes podem divergir mesmo quando a entrega é imediata.

O Logs Data Model do OpenTelemetry separa explicitamente Timestamp, medido na origem, de ObservedTimestamp, medido quando o sistema de coleta observa o evento. Ele também oferece os campos opcionais TraceId e SpanId para correlacionar solicitações. Essas são semânticas gerais de telemetria, não um modelo completo de auditoria de agentes de IA nem prova de que uma integração produz esses campos. OpenTelemetry Logs Data Model.

Preserve as relações causais por meio da identificação de solicitações, decisões, envios e observações no destino. Ordenar eventos de componentes diferentes por timestamp não recupera uma relação ausente. Se um timestamp foi gerado durante a ingestão porque o horário na origem era desconhecido, não o apresente como horário de execução.

Descreva a proteção de integridade realmente aplicada

Metadados de integridade da evidência: identifique a origem do evento, as versões do coletor e das transformações, as proteções de acesso relevantes e qualquer mecanismo de integridade efetivamente usado. Registre o que foi verificado, por qual verificador e contra qual referência confiável. O sistema de evidências deve distinguir uma afirmação de proteção recebida de uma verificação bem-sucedida.

Um hash criptográfico pode ajudar a detectar uma mudança nos bytes que abrange quando comparado a um digest confiável. O Secure Hash Standard do NIST descreve essa finalidade de detecção de mudanças. Para um registro de auditoria, especifique o algoritmo, a representação abrangida e como o valor de comparação é protegido. Um digest armazenado junto de conteúdo editável não oferece, por si só, uma garantia independente do histórico desse conteúdo. NIST FIPS 180-4.

Uma assinatura digital responde a outra pergunta: o Digital Signature Standard do NIST descreve a detecção de alterações não autorizadas e a autenticação do signatário. Registre qual identidade de assinatura foi verificada e quais dados a assinatura abrange. Mesmo uma assinatura válida não comprova que o signatário observou a ação corretamente ou emitiu todos os eventos necessários. NIST FIPS 186-5.

Se o armazenamento for descrito como imutável, documente a configuração de retenção e acesso que sustenta essa afirmação e a evidência de que ela foi aplicada. Proteção de armazenamento, assinatura verificada e digest correspondente estabelecem propriedades diferentes. Nenhum deles recupera um evento que nunca foi produzido. Esses são requisitos a avaliar, não afirmações sobre capacidades de armazenamento ou assinatura da KonaSense.

Minimize o conteúdo sensível ao longo da trilha

Defina a finalidade da investigação antes de decidir qual conteúdo reter. O exemplo do workspace exige a conta, o perfil, a tarefa e a relação com a aprovação pertinentes; ele não exige automaticamente todas as conversas ou atributos do diretório sem relação com o caso. Quando um registro delimitado responder à pergunta, evite criar outra cópia integral da entrada sensível.

A orientação de logging da OWASP recomenda excluir valores sensíveis, como tokens e senhas, e tratar identificadores e outros dados de contexto conforme sua sensibilidade. Ela também recomenda controles de acesso e verificação do mecanismo de logging. Use esses princípios ao especificar a trilha e os sistemas que permitem acessar o conteúdo de suas referências. OWASP Logging Cheat Sheet.

Uma referência não é automaticamente inofensiva. Ela pode identificar uma pessoa, revelar um recurso interno ou permitir acesso a conteúdo sensível. Aplique autorização ao acessar o conteúdo referenciado e separe o acesso operacional rotineiro daquele necessário a uma investigação específica. Remover o conteúdo do log visível não protege um repositório associado com acesso irrestrito.

Defina a retenção por finalidade para os registros e o conteúdo referenciado, incluindo extratos criados durante investigações. Mantenha a expiração coerente: um registro retido deve indicar quando o conteúdo que o sustenta já não está disponível, em vez de passar a apontar silenciosamente para outra versão. Nenhum prazo universal de retenção atende a toda investigação ou organização, e conservar todos os prompts indefinidamente não substitui um requisito de evidência definido.

Torne as lacunas do pipeline visíveis para a investigação

Especifique como a trilha representa um evento que não foi emitido, não foi coletado, foi perdido, duplicado, atrasado, transformado ou está inacessível ao revisor. Esses estados não são intercambiáveis. A ausência de um evento de envio coletado pode indicar que não houve envio, mas também pode indicar uma lacuna na coleta. Use observações sobre o produtor e o caminho de coleta para reduzir essa incerteza.

Preserve a identidade do evento de origem ao longo do encaminhamento e das transformações quando ela estiver disponível. Uma entrega duplicada não deve se tornar silenciosamente uma segunda ação, e um “sucesso” normalizado não deve substituir um significado mais limitado na origem, como aceitação da solicitação. Se um mapeamento remover informação necessária à investigação, registre essa perda e, quando houver justificativa, mantenha um caminho com controle de acesso adequado até a evidência de origem.

Um registro inacessível também é uma condição operacional. Identifique quem pode autorizar o acesso ou confirmar a expiração, sem enfraquecer os controles do repositório de evidências. A investigação deve conseguir explicar por que uma conclusão permanece incompleta, em vez de interpretar todo campo ausente como “não se aplica”.

Valide a especificação com perguntas e registros sintéticos

Use um ambiente controlado e identidades sintéticas para testar se as relações especificadas respondem às perguntas da investigação. Para o exemplo do workspace, planeje uma proposta de acesso de visualização com aprovação aplicável, uma proposta alterada, uma nova tentativa após a perda da resposta e uma consulta posterior de estado sem registro causal. Inclua também uma entrega duplicada e uma referência de entrada expirada. Esses são casos de validação propostos, não testes executados para este guia.

Peça a um revisor que distinga o que cada caso estabelece e o que permanece desconhecido. Ele consegue identificar a proposta exata aprovada, separar tentativas concorrentes, distinguir o horário da coleta do horário do evento e reconhecer um resultado cuja causa não foi esclarecida? Registre qualquer campo ou relação ausente que tenha impedido a resposta e revise a especificação para atender a essa finalidade. Não preencha a lacuna com um valor presumido.

O guia de implantação da governança de agentes de código explica como atribuir responsáveis, conduzir um piloto delimitado e encaminhar evidências às equipes operacionais. Use este modelo de auditoria para definir os registros que essas equipes precisam conseguir interpretar.

Avalie os registros da KonaSense pela origem e pelo significado

No fluxo PreToolUse do adaptador Claude Code analisado para o Kona for Agents, o adaptador pode enviar um reporte contendo a resposta do hook que construiu. Quando disponível, esse reporte é evidência sobre a resposta do adaptador. Ele não confirma que o host aplicou a resposta nem que o destino concluiu uma ação.

Avalie cada registro disponível considerando sua origem, transformação e caminho de coleta antes de usá-lo em uma conclusão de auditoria. Nem um reporte do adaptador nem a atividade recebida por OTLP, isoladamente, estabelece uma trilha completa ou imutável. Confirme os campos e as relações presentes na integração instalada e deixe explícita a indisponibilidade de evidências sobre decisão, execução e resultado.