Observabilidade de agentes de IA: logs, traces e auditoria

Observabilidade de agentes de IA em produção é a capacidade de reconstruir, depois do fato, o que um agente decidiu, com base em quê, usando quais ferramentas e com que resultado — a partir de logs, traces e métricas coletados a cada passo. Para o decisor, a pergunta prática é simples: se um agente executar uma ação errada amanhã às 3h da manhã, alguém consegue explicar o que aconteceu em minutos, e não em semanas? Este artigo é para quem já tem (ou vai ter) agentes operando processos reais e precisa definir o que registrar, por quanto tempo, com que proteção e quem lê.

Por que monitorar um agente não é monitorar um sistema comum

Um agente é não determinista e encadeia decisões: o mesmo pedido pode gerar caminhos diferentes, e o erro costuma estar no meio da cadeia, não no resultado final. Um serviço tradicional falha de forma visível — erro HTTP, exceção, timeout. Um agente pode "funcionar" tecnicamente e ainda assim consultar o documento errado, chamar a ferramenta errada ou agir com uma premissa inventada. Nada disso dispara alerta de infraestrutura.

Três características pedem uma camada própria de observabilidade:

• Raciocínio em vários passos: o resultado depende de uma sequência de chamadas ao modelo, recuperações de contexto e execuções de ferramentas. Sem o encadeamento, o log de cada peça isolada não explica nada.
• Autonomia sobre sistemas reais: o agente escreve em CRM, abre chamado, envia e-mail. A pergunta de auditoria deixa de ser "o que o modelo respondeu" e passa a ser "o que o agente fez".
• Custo variável: cada passo consome tokens. Um laço mal desenhado vira fatura antes de virar incidente (veja FinOps para IA).

Observabilidade, portanto, não é um recurso de engenharia opcional: é a base de governança de agentes de IA autônomos. Sem ela, kill switch, human-in-the-loop e plano de resposta a incidentes ficam cegos — você sabe que precisa parar o agente, mas não sabe quando nem por quê.

Os três sinais: traces, logs e métricas

Traces contam a história de uma execução; logs registram eventos pontuais; métricas mostram tendência agregada. Os três se complementam.

Sinal	O que responde	Exemplo em um agente
Trace	"O que aconteceu nesta execução, passo a passo?"	Pedido do usuário → recuperação de documentos → chamada ao modelo → ferramenta criar_pedido → resposta
Log	"Que evento específico ocorreu, quando e com qual dado?"	Ferramenta chamada com parâmetros X, retorno Y, aprovação humana concedida por Z
Métrica	"O comportamento está mudando ao longo do tempo?"	Tokens por tarefa, taxa de erro de ferramenta, latência, taxa de escalonamento para humano

Em um trace de agente, cada etapa vira um span (um trecho com início, fim e atributos), aninhado sob a execução principal. É isso que permite abrir uma execução problemática e ver a árvore completa de decisões.

O padrão emergente: OpenTelemetry para IA generativa

O projeto OpenTelemetry mantém convenções semânticas para IA generativa que definem operações como create_agent, invoke_agent e execute_tool e atributos padronizados (modelo, tokens consumidos, nome da ferramenta). Duas ressalvas honestas: a documentação oficial classifica essas convenções como em desenvolvimento/experimentais, e o mercado ainda convive com esquemas concorrentes de fornecedores. Adotar o padrão aberto reduz o risco de ficar preso a uma única ferramenta de observabilidade, mas planeje para mudanças de nomenclatura.

O que registrar: checklist por execução

O registro mínimo útil de um agente responde a cinco perguntas: quem, o quê, com base em quê, com qual autoridade e com que resultado.

1. Quem: identificador do agente e da versão (modelo, prompt de sistema, configuração) e a identidade sob a qual ele agiu — ver gestão de identidade para agentes de IA.
2. O quê: cada ferramenta acionada, com parâmetros e retorno, e cada sistema afetado.
3. Com base em quê: quais fontes ou documentos entraram no contexto (referências, não necessariamente o texto completo) e qual instrução do usuário disparou a execução.
4. Com qual autoridade: política aplicada, permissão utilizada e, quando houve, quem aprovou a ação e quando.
5. Com que resultado: saída final, erros, tentativas repetidas, tempo e custo.

Dois campos costumam ser esquecidos e fazem falta no pós-incidente: a versão do prompt e do modelo (sem ela, não dá para saber se o comportamento mudou por uma atualização) e a decisão de não agir (quando o agente escalou para um humano ou recusou algo, isso também é evidência de que o controle funcionou).

Dados pessoais e conteúdo sensível nos registros

Registrar demais cria um segundo problema de governança: o log passa a ser um repositório de dados pessoais e de segredos de negócio. Prompts e respostas podem conter CPF, dados de saúde, contratos, credenciais coladas por engano.

Boas práticas que as próprias convenções do OpenTelemetry apontam para IA generativa: a captura do conteúdo de entradas e saídas deve ser opcional (opt-in), e o padrão recomendado em produção é guardar o conteúdo fora do trace e registrar apenas referências. Traduzindo para a rotina da empresa:

• Minimização: registre metadados e referências por padrão; conteúdo completo apenas onde há justificativa (por exemplo, fluxos de alto risco).
• Mascaramento de identificadores e segredos antes da gravação.
• Retenção definida por tipo de registro: telemetria de engenharia pode expirar em semanas; trilha de auditoria segue o prazo que o jurídico definir.
• Acesso por perfil: quem depura não é necessariamente quem audita, e nenhum dos dois precisa ver todo conteúdo.

A LGPD pesa nos dois sentidos: o art. 37 obriga controlador e operador a manter registro das operações de tratamento de dados pessoais (argumento a favor de registrar), enquanto os princípios de necessidade e minimização limitam o que se guarda (argumento para registrar com critério). O ponto de equilíbrio deve estar escrito na política — veja LGPD e IA generativa e o guia de governança de dados para IA.

Telemetria de engenharia não é trilha de auditoria

Telemetria serve para depurar e otimizar; trilha de auditoria serve para provar. As exigências são diferentes e não devem ser tratadas como o mesmo sistema.

Critério	Telemetria de engenharia	Trilha de auditoria
Objetivo	Depurar, medir desempenho e custo	Demonstrar o que ocorreu, a terceiros
Integridade	Pode ser amostrada e descartada	Deve ser completa e protegida contra alteração
Retenção	Curta	Definida por política e obrigação legal
Leitor	Engenharia e produto	Auditoria, jurídico, compliance, reguladores

O regulamento europeu de IA dá uma referência de exigência para sistemas de alto risco: o art. 12 do AI Act determina que esses sistemas permitam tecnicamente o registro automático de eventos ao longo da vida útil, para garantir rastreabilidade. Empresas brasileiras que atendem o mercado europeu precisam observar isso (ver AI Act europeu e empresas brasileiras); as demais podem usá-lo como régua de maturidade. Para o desenho de uma auditoria de IA que consuma esses registros, parta das perguntas do auditor, não das telas do fornecedor.

Do registro ao controle: alertas que acionam ação

Observabilidade só gera governança quando um sinal leva a uma decisão. Defina de antemão quais padrões disparam o quê:

• Laço de ferramentas: mesma ferramenta chamada N vezes na mesma execução → circuit breaker interrompe a sessão.
• Ação fora do perfil: agente aciona sistema ou volume de registros incomum para seu escopo → bloqueio e revisão humana.
• Custo anômalo: tokens por tarefa acima do limite → alerta ao dono do agente.
• Queda de qualidade: aumento de escalonamentos, correções por humanos ou reclamações → revisão de prompt e dos testes (ver evals e gestão de risco de modelo).
• Incidente confirmado: sinal grave aciona o kill switch e, se necessário, o rollback.

Cada alerta precisa de um dono nomeado e de um tempo de resposta esperado. Alerta sem dono vira ruído em uma semana.

Três níveis de maturidade

Comece pelo nível 1 em todos os agentes e suba o nível conforme o risco da ação que o agente executa. A divisão abaixo é uma proposta prática, não um padrão de mercado.

1. Registro básico: toda execução gera um ID, com agente, versão, usuário, horário, ferramentas acionadas e resultado. Serve para responder "o que aconteceu?".
2. Rastreamento completo: traces com todos os passos, métricas de custo e qualidade, alertas com dono. Serve para depurar e melhorar.
3. Trilha de auditoria: registros protegidos contra alteração, retenção definida, ligação com aprovações humanas e inventário de agentes. Serve para prestar contas a conselho, auditoria e reguladores — conecte com o inventário de sistemas de IA.

Agentes que leem informações e sugerem ações podem ficar no nível 1 ou 2. Agentes que alteram dinheiro, dados de clientes ou contratos pedem o nível 3 desde o primeiro dia. Em ambientes com vários agentes cooperando, o desafio cresce: veja governança de sistemas multiagente.

Quem é dono da observabilidade

A observabilidade tem três donos, e a ausência de qualquer um quebra o ciclo.

• Tecnologia instrumenta, coleta e mantém a plataforma.
• A área dona do processo define o que é "comportamento normal" e responde aos alertas do seu agente.
• Governança/risco/compliance define retenção, acesso e critérios de auditoria — o papel descrito no pilar de governança de IA.

No método Flight Plan da Jetpacks, essa responsabilidade se materializa no estágio de Mission Control — acompanhamento, cujo output são as métricas de adoção: o time deixa de ser apenas capacitado e passa a ser medido no uso real. Para agentes, isso inclui os indicadores acima. Quem constrói agentes precisa saber instrumentá-los — um dos temas do programa Builders (capacitação técnica em agentes, automações e workflows). Veja como funciona em /#metodo.

Limitações e cuidados

• Padrões ainda em evolução: as convenções de IA generativa do OpenTelemetry são experimentais; versionar a instrumentação evita retrabalho.
• Observar não é entender: um trace mostra o que o agente fez; o porquê do modelo continua parcialmente opaco. Para isso, combine com testes e IA explicável.
• Custo do próprio monitoramento: registrar tudo, para sempre, é caro e arriscado. Defina o mínimo por nível de risco.
• Falsa sensação de controle: um painel bonito sem dono de alerta e sem poder de interromper o agente é decoração.

Para definir o que é qualidade aceitável antes de observar, veja evals corporativos.

Leia também: a definição de prazos de guarda dos registros de uso de IA está detalhada em retenção de logs de IA generativa.

FAQ

O que é observabilidade de agentes de IA?

É a prática de capturar cada passo que um agente executa — chamadas ao modelo, consultas a dados, ferramentas acionadas — em traces, logs e métricas, para reconstruir e explicar seu comportamento em produção. Vai além do monitoramento tradicional porque agentes são não deterministas e agem em sistemas reais.

Qual a diferença entre monitoramento e observabilidade em IA?

Monitoramento responde a perguntas que você já previu (o serviço está no ar? qual a latência?). Observabilidade permite investigar perguntas novas depois do fato (por que o agente escolheu esta ferramenta nesta execução?), porque guarda o encadeamento de decisões e não apenas indicadores agregados.

O que registrar nos logs de um agente de IA?

No mínimo: identificador e versão do agente, identidade usada, ferramentas acionadas com parâmetros e retorno, fontes consultadas, aprovações humanas, resultado, erros, tempo e custo. Conteúdo integral de prompts e respostas deve ser opcional e protegido, por conter dados pessoais.

Registrar prompts e respostas viola a LGPD?

Não por si só, mas cria obrigações. A LGPD exige manter registro das operações de tratamento (art. 37) e, ao mesmo tempo, que se trate apenas o necessário. Defina finalidade, minimização, mascaramento, retenção e controle de acesso na política de uso de IA e valide com o jurídico e o encarregado de dados.

Quais ferramentas usar para observabilidade de agentes?

Existem plataformas especializadas e soluções baseadas em OpenTelemetry. O critério de escolha deve ser: suporte ao padrão aberto, controle sobre onde os dados ficam, mascaramento de conteúdo, retenção configurável e integração com os alertas e o plano de incidentes da empresa. A ferramenta importa menos que a definição de donos e limites.

Observabilidade substitui auditoria de IA?

Não. A observabilidade produz a evidência; a auditoria a avalia contra critérios de política, risco e regulação. Uma boa trilha reduz o custo e o tempo de auditoria, mas alguém independente ainda precisa fazer o julgamento.

Próximo passo

Antes de aumentar a autonomia dos agentes, confirme se hoje você consegue responder, para cada um deles, quem é o dono, o que ele pode fazer, o que registra e quem recebe o alerta. Se alguma resposta for "não sei", esse é o ponto de partida. No diagnóstico gratuito — uma conversa de 30 a 45 minutos —, mapeamos onde sua empresa está nessa escada e quais áreas precisam de governança antes de escalar.