Blog · Guia · 28 de outubro de 2026
Checklist de rastreabilidade para agentes de IA em produção: o que registrar, o que assinar e o que mostrar a quem revisa
Aviso: a 100monkeys.ai desenvolve o AEGIS, um orquestrador de agentes open source, e mantém a lista awesome-agent-traceability citada abaixo. Este checklist é neutro em relação a fornecedores: todo item pode ser atendido com ferramentas abertas e nenhum exige nossos produtos. Ele foi redigido por um dos nossos agentes de IA e revisado pela empresa; esta versão em português é uma tradução do original em inglês.
Quando um agente de IA age sobre um sistema real, alguém vai perguntar depois o que ele fez e por quê. Este checklist é o trabalho a fazer antes de essa pergunta chegar: o que registrar em cada execução, o que assinar para o registro ser confiável e o que colocar diante da pessoa que revisa. Cada item cita um padrão ou ferramenta aberta da lista awesome-agent-traceability.
A estrutura vem do nosso artigo Red levers: traceable, deterministic agents in production (em inglês), que define um sistema de agentes como seguro em produção quando uma pessoa consegue ver cada decisão que ele tomou, por que a tomou, e pará-lo. O registro atende ao primeiro ponto, o motivo registrado ao segundo e a etapa de revisão ao terceiro.
Parte 1. O que registrar
Passo 1. Dê uma identidade a cada execução
Atribua um id a cada execução no início e leve-o por toda chamada ao modelo, toda chamada de ferramenta e todo efeito colateral. Sem ele, um log é uma pilha de eventos que ninguém consegue agrupar. Use ids de trace e de span das convenções semânticas do OpenTelemetry para IA generativa, que definem nomes comuns para chamadas de modelo, passos de agente e invocações de ferramentas, para que traces de frameworks diferentes sejam lidos do mesmo jeito. As convenções para spans de agentes cobrem a criação e a invocação de agentes.
Passo 2. Registre o pedido e a intenção, em palavras
Registre o que foi pedido ao agente, por quem e com qual motivo. Depois, a cada ato com consequências, registre a frase do próprio agente explicando por quê. Um motivo escrito no momento do ato é evidência; um motivo reconstruído depois é uma história.
Passo 3. Registre o modelo e suas configurações
Para cada chamada ao modelo: provedor, nome e versão do modelo, os parâmetros que mudam a saída (temperatura, máximo de tokens, ferramentas oferecidas) e a contagem de tokens. Um comportamento que você não consegue ligar a uma versão do modelo não pode ser reproduzido depois que o provedor o atualiza.
Passo 4. Registre cada chamada de ferramenta com entradas e saídas
Anote a ferramenta, os argumentos, o resultado e o horário. Remova dados pessoais antes de armazenar, não depois; o Presidio é uma opção aberta. Uma chamada que escreveu em algum lugar também deve registrar o que mudou: o diff, o id do registro, o id da mensagem.
Passo 5. Registre cada decisão de política
Se um motor de políticas permitiu ou recusou uma chamada, registre a decisão e a regra que a tomou. O Open Policy Agent mantém logs de decisão exatamente para isso. Uma recusa é tão importante de guardar quanto uma permissão: ela mostra que o limite se manteve.
Passo 6. Registre a identidade e o alcance
Registre qual credencial ou token a execução usou e o que essa credencial conseguia alcançar, não o valor secreto. A pergunta de quem revisa costuma ser "ele poderia ter feito pior?", e a resposta é o escopo que ele tinha.
Passo 7. Torne a execução reproduzível
Guarde o suficiente para rodar o trabalho de novo: as entradas, o estado em cada passo e a ordem dos eventos. Motores de execução durável como o Temporal mantêm um histórico de eventos do workflow que permite reproduzi-lo de forma determinística.
Parte 2. O que assinar
Passo 8. Torne o registro append-only e encadeado
Um registro que pode ser reescrito depois não prova nada. Grave os eventos num armazenamento append-only e encadeie cada entrada à anterior por hash, para que uma entrada removida ou editada quebre a cadeia. O grupo de trabalho SCITT da IETF define declarações assinadas registradas em serviços de transparência append-only, um formato pronto para isso.
Passo 9. Assine o que o agente produziu
Quando uma execução produz um artefato (um build, um relatório, um arquivo publicado), anexe uma declaração assinada de como ele foi feito. O in-toto Attestation Framework transporta esse tipo de declaração, e o SLSA define níveis de proveniência de build. Para mídia, a especificação C2PA anexa manifestos de proveniência assinados, inclusive para conteúdo produzido ou editado por IA.
Passo 10. Assine a aprovação
Se uma pessoa aprovou um ato, registre quem aprovou, quando e exatamente o que viu. Vincule a aprovação ao conteúdo: se o ato mudar depois da aprovação, a aprovação deixa de valer.
Parte 3. O que mostrar a quem revisa
Passo 11. Mostre o ato, não um resumo
Quem revisa deve ver o e-mail, o diff ou o comando que vai rodar, gerado a partir da própria saída da execução. Um resumo escrito pelo mesmo modelo que quer a aprovação não é uma superfície de revisão.
Passo 12. Mostre o motivo ao lado do ato
Coloque a intenção registrada do agente ao lado da mudança que ele fez. "Por que esta linha está aqui?" deve ser respondido pela frase escrita quando a linha entrou.
Passo 13. Mostre os limites em que ele rodou
Mostre a política e o escopo da credencial junto com a execução. Quem vê que o agente só podia escrever numa branch lê a execução de um jeito diferente de quem precisa supor que ele alcançava tudo.
Passo 14. Dê a quem revisa um botão de parar
Toda tela de revisão precisa de um jeito de recusar, e a recusa precisa valer. O artigo 14 do AI Act da UE, conforme citado em Red levers, pede que as pessoas que supervisionam sistemas de alto risco possam "intervene in the operation of the high-risk AI system or interrupt the system" (intervir no funcionamento do sistema ou interrompê-lo). Citá-lo aqui trata do formato do controle, não de uma alegação de conformidade.
Teste você mesmo
Escolha uma execução da semana passada e tente responder só com os registros: quem pediu, o que o agente chamou, o que mudou, sob qual política, quem aprovou e se o registro pode ter sido editado desde então. Cada pergunta que você não conseguir responder corresponde a um dos passos acima.
Como aplicamos isso
Desenvolvemos ferramentas para partes desta lista. AEGIS by 100monkeys.ai, in beta, é um orquestrador self-hosted que roda agentes em ambientes isolados, com políticas aplicadas e estado durável; Como dar a um orquestrador uma etapa de aprovação mostra sua etapa de aprovação como exemplo prático, e este guia de instalação coloca o AEGIS para rodar num servidor. O Carbon Forge guarda código e texto num único registro, onde o blame mostra a intenção escrita no momento em que a mudança entrou.