OpenTelemetry para agentes de IA: traces que ajudam a depurar
Como modelar a execução de um agente de IA em spans de modelo, ferramenta e decisão com OpenTelemetry, e o que mascarar antes de enviar ao coletor.
Quer aplicar isso na sua empresa?
Agendar conversa com o Juan →OpenTelemetry para agentes de IA: traces que ajudam a depurar
Para usar OpenTelemetry em agentes de IA, trate cada execução como um trace e cada chamada ao modelo, uso de ferramenta e decisão relevante como um span com atributos padronizados. Antes de enviar qualquer coisa ao coletor, mascare dados pessoais, segredos e o conteúdo bruto das mensagens, guardando só o que permite explicar o comportamento. Assim, quando o agente errar, você enxerga o caminho percorrido sem criar um novo ponto de vazamento.
Principais pontos
- Uma execução do agente vira um trace. Cada chamada ao modelo, cada ferramenta e cada decisão de rota vira um span filho, com início, fim e resultado.
- Siga as convenções semânticas de IA generativa do OpenTelemetry para nomes de atributos, e use atributos próprios com prefixo da sua empresa para o que for específico do seu negócio.
- Registre metadados por padrão (modelo, ferramenta, duração, contagem de tokens, status) e o conteúdo das mensagens apenas por exceção, com mascaramento.
- Aplique a máscara o mais perto possível da origem e use o coletor como segunda camada de proteção, não como a única.
- Comece por um fluxo real, com uma pergunta de depuração definida, e só depois amplie a instrumentação.
Por que logs soltos não bastam para depurar um agente
Um software tradicional segue um caminho previsível: a mesma entrada leva ao mesmo fluxo. Um agente de IA decide durante a execução. Ele escolhe qual ferramenta chamar, com quais argumentos, quantas vezes tentar e quando responder. O erro raramente está em uma linha de código. Está na sequência: uma consulta que voltou vazia, um modelo que ignorou o vazio e uma resposta confiante no fim.
Logs soltos mostram eventos, mas perdem a relação entre eles. Você acha a mensagem de erro da ferramenta, mas não sabe qual chamada ao modelo a provocou, nem o que o agente fez depois. Um trace guarda essa relação de causa e tempo. A documentação do OpenTelemetry sobre conceitos de observabilidade descreve o trace como o caminho de uma requisição por um sistema, composto de spans. Essa descrição serve bem para um agente, em que o caminho é justamente a parte difícil de reconstruir.
Há ainda a questão de repetir o problema. Um agente raramente erra do mesmo jeito duas vezes. Se você só tem o resultado final, não consegue reproduzir. Com o trace, a execução que falhou fica registrada como aconteceu, inclusive as escolhas intermediárias.
Como modelar uma execução de agente em spans
O desenho mais útil costuma ser em árvore, com poucos níveis. Quanto mais simples, mais fácil de ler às pressas, quando alguém está investigando uma reclamação.
- Span raiz da execução: representa a tarefa inteira, da mensagem recebida até a resposta ou a transferência para uma pessoa. Leva o identificador da conversa (já pseudonimizado), o canal e o resultado final.
- Span de passo do agente: cada volta do ciclo de raciocínio e ação. É o que permite contar quantos passos a execução usou.
- Span de chamada ao modelo: uma por requisição ao provedor, com modelo, parâmetros relevantes, contagem de tokens e motivo de término.
- Span de ferramenta: uma por chamada a uma função, API ou servidor MCP, com nome da ferramenta, duração e status.
- Span de decisão: um registro curto de uma escolha que muda o rumo, como escalar para humano, recusar uma ação ou pedir confirmação.
As convenções semânticas do OpenTelemetry para IA generativa definem nomes de atributos para operações como chamada ao modelo, execução de ferramenta e invocação de agente. Elas ainda estão em evolução, então confirme na documentação os nomes atuais antes de fixá-los em dashboards e alertas. Na prática, isso significa isolar os nomes em um único módulo da sua instrumentação, para atualizar em um lugar só.
Um detalhe que ajuda: dê nomes de span legíveis para quem não escreveu o código. Algo como consultar_agenda diz mais ao responsável pela operação do que um nome genérico de função.
O que registrar em cada span
A regra de partida é registrar o que explica o comportamento, não tudo o que passou pela execução.
No span de modelo, os atributos que mais pagam o custo são: nome do modelo solicitado e do efetivamente usado, contagem de tokens de entrada e de saída, motivo de término e erro, se houve. Para quem se preocupa com custo, a leitura de o que são tokens em IA ajuda a entender por que essa contagem merece estar em cada trace.
No span de ferramenta, registre o nome, a duração, o status e um resumo do resultado em forma de metadado: quantos itens voltaram, se veio vazio, se houve tempo esgotado. Esse resumo costuma bastar para encontrar a causa, sem guardar o conteúdo devolvido.
No span de passo, registre o número do passo dentro da execução e o motivo da transição, por exemplo, ferramenta solicitada, resposta final ou limite atingido. Isso conversa diretamente com a prática de limites de passos, tempo e gasto em agentes: se o limite é uma regra do sistema, o trace deve mostrar quando ele foi acionado.
Por fim, versione o que muda o comportamento: versão das instruções do agente, versão do conjunto de ferramentas e identificador da configuração. Sem isso, você compara execuções de antes e depois de uma mudança sem saber que houve mudança.
Spans de decisão: o que torna o trace útil
As convenções cobrem bem modelo e ferramenta. A decisão é onde o trace deixa de ser telemetria genérica e vira ferramenta de depuração do seu processo. Aqui você define atributos próprios, com um prefixo que indique que são seus.
Um span de decisão pode registrar: qual regra foi avaliada, qual foi o resultado (permitiu, bloqueou, pediu confirmação, transferiu), e o motivo em uma categoria fechada, não em texto livre. Categorias fechadas permitem contar e filtrar. Texto livre convida a vazar dado pessoal e dificulta consulta.
Exemplos de decisões que merecem span: resposta emitida sem confirmação de uma ferramenta, ação com efeito externo (enviar mensagem, alterar cadastro) que passou por aprovação, entrada sinalizada por uma verificação de segurança, transferência para atendimento humano. As verificações de entrada, saída e ação descritas em guardrails para agentes de IA são candidatas naturais: cada guardrail pode emitir um span com seu veredito.
Essa camada também serve à conformidade. Se a empresa precisa mostrar como uma decisão automatizada foi tomada e como ela pode ser revisada, o registro estruturado das decisões é um insumo concreto. O tema é detalhado em decisões automatizadas na LGPD. Vale validar com o jurídico o que precisa ser guardado e por quanto tempo.
O que mascarar antes de enviar ao coletor
O trace é um novo banco de dados com cópia do que o agente viu. Se você despejar prompts e respostas nele, cria uma base de conversas de clientes com controle de acesso diferente da original. Por isso, o mascaramento faz parte do projeto, não é um ajuste posterior.
O que normalmente deve ser mascarado ou removido:
- Identificadores diretos: nome, CPF, e-mail, telefone (inclusive o número do WhatsApp), endereço e dados de pagamento.
- Conteúdo bruto de mensagens do cliente e respostas do agente, que podem conter qualquer dado pessoal digitado livremente.
- Argumentos e resultados de ferramentas que carregam registros de clientes, como retornos de CRM ou ERP.
- Segredos: tokens de API, chaves, cabeçalhos de autorização e strings de conexão que apareçam em argumentos ou erros.
- Trechos de documentos recuperados por busca, quando o documento é interno ou sensível.
- Mensagens de erro de terceiros que ecoam a entrada original.
A alternativa ao mascaramento total é a pseudonimização: trocar o identificador por um valor derivado, com segredo guardado fora da telemetria, para correlacionar execuções da mesma conversa sem expor quem é a pessoa. Decida isso com quem responde pela privacidade na empresa.
Sobre o conteúdo das mensagens, as convenções de IA generativa tratam a captura de entradas e saídas como algo opcional e sensível. Mantenha desligado por padrão, e ligue de forma temporária, por amostra e em ambiente controlado, quando uma investigação exigir. Se a plataforma de observabilidade estiver fora do Brasil, lembre que enviar o trace é uma transferência de dados; o artigo sobre transferência internacional de dados com IA e LGPD mostra o que checar. A ANPD é a referência oficial para orientações.
Pense também em segurança do próprio conteúdo. O OWASP Top 10 para aplicações com LLMs lista riscos como divulgação de informações sensíveis e manipulação por instruções maliciosas. Um trace com texto bruto pode carregar uma instrução maliciosa para quem o lê com ajuda de outra IA. Trate o conteúdo de trace como dado não confiável.
Em termos técnicos, aplique a máscara em duas camadas. A primeira fica na própria aplicação, antes da exportação, usando um processador de spans ou uma função que só permite atributos de uma lista aprovada. A segunda fica no coletor, com processadores que removem, trocam ou fazem hash de atributos conhecidos. A lista de permissão é mais segura que a lista de bloqueio: o que não foi aprovado simplesmente não sai.
Plano em etapas e um cenário ilustrativo
Um caminho enxuto para sair do zero:
- Escolha um fluxo real e uma pergunta de depuração, como por que o agente respondeu sem confirmar a agenda.
- Liste os atributos necessários para responder essa pergunta e descarte o resto.
- Defina a lista de atributos permitidos e as regras de mascaramento, com aprovação de quem cuida de privacidade.
- Instrumente a raiz, os passos, o modelo, as ferramentas e as decisões.
- Configure o coletor com a segunda camada de proteção e defina retenção e acesso.
- Teste com conversas sintéticas contendo dados falsos e confirme que nada sensível aparece no destino.
- Revise depois de um período de uso: o que ninguém consultou sai, o que faltou entra.
Cenário ilustrativo: uma loja usa um agente no WhatsApp para marcar visitas. Um cliente reclama que o agente confirmou um horário que não existia. No trace da execução, o span raiz mostra o canal e o resultado final. O span da ferramenta consultar_agenda mostra status de sucesso, mas com resultado vazio. O span de passo seguinte mostra que o modelo gerou a resposta mesmo assim, e o span de decisão registra que a resposta foi emitida sem confirmação da ferramenta. A causa fica clara em poucos minutos: o filtro de data estava errado e a instrução do agente não proibia confirmar com resultado vazio. A correção é uma regra de decisão, e o mesmo trace serve de teste de regressão. Nada disso exigiu guardar o texto da conversa.
Como o método se aplica a esse trabalho
O método segue a ordem mapear, limitar, pilotar e transferir. Mapear é entender o processo atual e escolher o que precisa ser explicável. Limitar é definir os dados e as ações que o agente toca, o que também define o que o trace pode conter. Pilotar é instrumentar um fluxo real, com uma métrica de sucesso combinada; para isso, o guia sobre como medir um piloto de automação com IA ajuda a definir critérios. Transferir é entregar à equipe os painéis, as regras de mascaramento e o procedimento de investigação, para que a decisão de expandir, ajustar ou parar seja informada por evidência.
Perguntas frequentes
Preciso registrar o prompt completo para depurar um agente? Na maioria dos casos, não. Metadados como modelo, tokens, ferramenta chamada, status e categoria de decisão costumam bastar para achar a causa. Quando o texto for indispensável, capture de forma temporária, por amostra e já mascarado.
OpenTelemetry funciona com qualquer modelo e framework de agentes? O OpenTelemetry é independente de fornecedor, e você pode instrumentar manualmente qualquer fluxo, inclusive com modelos locais. Alguns frameworks e bibliotecas já trazem instrumentação pronta, mas confira o que ela envia por padrão, porque pode incluir conteúdo de mensagens.
O trace conta como dado pessoal na LGPD? Se contiver informação que identifique uma pessoa, direta ou indiretamente, sim, e passa a exigir base legal, retenção definida e controle de acesso. Por isso o ideal é projetar o trace para não conter esses dados e validar a decisão com o responsável pela privacidade.
Onde começar se a empresa nunca usou tracing? Comece por um fluxo único, com poucos tipos de span e uma lista curta de atributos permitidos. Faça o trace responder uma pergunta de depuração real e só depois acrescente detalhes. Observabilidade que ninguém consulta vira custo e risco sem retorno.