Observabilidade de Agentes de IA: Como Rastrear (e Debugar) Falhas em Produção

Às três da tarde de uma quarta-feira, um agente de atendimento começa a devolver respostas erradas para um subconjunto de usuários. Não é um erro 500, não é uma exception. O agente responde, com toda a confiança do mundo, com uma informação incorreta sobre o pedido de um cliente. Você abre o log da aplicação e encontra uma linha: INFO: request processed successfully. status=200. Nenhuma pista sobre o que aconteceu entre o input e o output.

Esse cenário separa quem construiu um chatbot de quem construiu um sistema agêntico de verdade. Um agente moderno não faz uma chamada de API e retorna uma resposta — ele decide quais ferramentas chamar, em que ordem, reavalia o plano no meio do caminho, às vezes delega para um sub-agente especializado que chama outras ferramentas. Cada decisão é não-determinística: o mesmo input pode gerar caminhos de execução diferentes em execuções diferentes. Quando algo dá errado, "olhar o log" simplesmente não é uma estratégia de debug viável.

Esse post é sobre o que preenche esse vácuo: como aplicar tracing distribuído ao raciocínio de um agente, quais convenções o ecossistema já convergiu, quais ferramentas usar, e como montar um dashboard mínimo que avisa antes do cliente reclamar. Já falei sobre como monitorar o custo de tokens em produção via LangSmith — este post complementa aquele mostrando o outro lado: não quanto o agente gastou, mas o que ele fez, passo a passo, e onde saiu dos trilhos.

---

Por Que Logs Tradicionais Não Bastam

A instrumentação clássica de observabilidade foi desenhada para sistemas determinísticos: você loga entrada, loga saída, correlaciona por um request_id através de alguns serviços. Funciona bem quando dado o mesmo input, o mesmo código sempre executa o mesmo caminho.

Um agente quebra essa premissa de três formas. Primeiro, a decisão em si é não-determinística — o LLM pode escolher chamar a ferramenta A ou B dado exatamente o mesmo prompt, dependendo de temperatura ou de nondeterminismo interno do provider. Não existe "o caminho esperado" para comparar contra um log de erro.

Segundo, a cadeia de execução é dinâmica e profunda. Um agente de suporte pode consultar o histórico do cliente, chamar uma ferramenta de billing, reavaliar que precisa de mais contexto, chamar uma segunda ferramenta, e só então formular a resposta. Um log de linha única não representa essa árvore de decisões — na melhor das hipóteses você tem quinze linhas espalhadas, sem relação hierárquica entre elas.

Terceiro — e é o que mais pega arquiteturas modernas desprevenidas — sistemas multiagente introduzem uma dimensão extra de indireção. Um orquestrador chama um sub-agente especializado, que tem seu próprio loop de raciocínio e suas próprias ferramentas. Se o sub-agente decide errado, esse erro sobe como resultado aparentemente válido; o pai não viu o raciocínio do filho, só recebeu um output. Sem tracing que atravesse essa fronteira, você não sabe se o problema começou no orquestrador, no sub-agente, ou numa ferramenta lá no fundo. Como venho reforçando desde o post sobre confiabilidade de agentes em produção, o gap entre demo e produção quase sempre aparece nesses pontos de indireção que ninguém testou.

---

Tracing Distribuído Aplicado a Agentes: o Conceito de Trajectory

A resposta da indústria não é nova — é emprestada de sistemas distribuídos tradicionais. Em vez de logs soltos, você constrói um trace: uma árvore de spans, onde cada span representa uma unidade de trabalho com início, fim, atributos e uma relação de pai-filho com outros spans.

No mundo de agentes, essa árvore completa — do input inicial até a resposta final, passando por cada chamada de LLM, tool call e sub-agente invocado — ganhou um nome específico: trajectory. É o registro replay-ável de tudo que o agente decidiu fazer numa execução: não um log de eventos desconexos, mas a árvore de decisão inteira, ordenada no tempo, com cada nó carregando o que foi decidido e por quê.

Pensa numa trajectory como o stack trace de uma exception, só que em vez de "essa função chamou essa outra", você tem "o agente chamou a ferramenta de busca, recebeu esse resultado, decidiu que precisava de mais contexto, invocou o sub-agente de billing, que chamou a ferramenta de fatura errada". Cada span carrega o prompt exato enviado ao modelo, a resposta recebida, tokens consumidos, latência e, quando aplicável, os argumentos passados a uma ferramenta e o resultado devolvido.

O valor prático é que a trajectory vira sua unidade de debug. Em vez de perguntar "o que esse serviço fez às 15h03", você pergunta "o que esse agente fez nessa trajectory que gerou a resposta errada para o cliente X" — abrindo a árvore e vendo onde o raciocínio divergiu do esperado. Vale não confundir trajectory com memória: a trajectory é o registro de execução de uma tarefa, enquanto a arquitetura de memória do agente é o que persiste entre sessões — camadas complementares, problemas diferentes.

---

OpenTelemetry e as Semantic Conventions para GenAI

O ecossistema não ficou reinventando isso de forma fragmentada por muito tempo. O OpenTelemetry — já o padrão de fato para tracing distribuído — publicou semantic conventions específicas para GenAI, definindo um vocabulário comum de atributos que qualquer ferramenta de observabilidade interpreta sem acoplamento proprietário.

Na prática, uma chamada de modelo vira um span com atributos como gen_ai.system (qual provider), gen_ai.request.model, gen_ai.usage.input_tokens e gen_ai.usage.output_tokens. Uma tool call vira seu próprio span filho, com nome da ferramenta, argumentos serializados e resultado retornado. O orquestrador que decide qual ferramenta chamar também tem semântica própria, com spans invoke_agent que encapsulam toda a sub-árvore de decisões daquele agente.

O ganho de padronizar é duplo: você instrumenta uma vez e troca de backend sem reescrever nada, e custo e tokens passam a ser atributo de span, correlacionável com a etapa exata da trajectory que gerou aquele custo. Você responde "qual chamada de ferramenta consumiu 40% do custo total" olhando direto para a árvore de spans, sem cruzar planilhas.

A maioria dos SDKs de agente modernos (LangChain, LangGraph, CrewAI, o SDK de agentes da própria Anthropic) já expõe integrações que emitem spans nesse formato automaticamente. O trabalho manual costuma ser só configurar o exportador e garantir que a propagação de contexto atravesse as chamadas entre agente pai e sub-agente — exatamente o ponto onde a instrumentação costuma falhar silenciosamente.

---

Ferramentas do Mercado: Onde Cada Uma Brilha

Instrumentar com OpenTelemetry resolve a coleta. Mas você ainda precisa de um lugar para visualizar e comparar trajectories. O mercado já tem opções maduras, cada uma com um ângulo diferente.

LangSmith, da LangChain, tem a adoção mais ampla em times que já usam LangChain ou LangGraph, com integração nativa. Mostra a árvore de trajectory completa com drill-down por span, permite comparar duas execuções lado a lado e — como já mencionei no post sobre gestão de custo — expõe custo e cache hit rate por trajectory, unindo debugging de comportamento e FinOps na mesma superfície.

Langfuse é a alternativa open source mais madura da categoria, com tração forte por ser self-hostable — relevante para times com dado sensível que não querem trajectories de produção saindo para um SaaS de terceiros. Tem suporte nativo a OpenTelemetry, prompt management versionado e avaliação por scores manuais ou LLM-as-judge atrelada à trajectory.

Arize Phoenix vem de uma origem em ML observability tradicional (drift de modelo, avaliação offline) trazida para o mundo de LLM. É forte em avaliação sistemática — rodar trajectories de produção contra métricas de qualidade (relevância, alucinação, toxicidade) de forma automatizada. Também é open source, com modo local útil antes de ir para produção.

Datadog LLM Observability é a opção natural para quem já tem Datadog como plataforma central. A vantagem é correlacionar a trajectory do agente com o resto da stack de APM: se o agente chamou uma ferramenta que bateu num microsserviço interno, você vê os dois traces na mesma tela — unificação que vale mais, para organizações grandes, do que features isoladas de um concorrente.

Não existe escolha universalmente certa: LangChain puxa para LangSmith, dado sensível pede Langfuse, foco em avaliação em escala aponta para Phoenix, e quem já vive no ecossistema Datadog ganha ao integrar ali.

---

Como Estruturar um Dashboard Mínimo Viável

Antes de instrumentar tudo que é possível, vale definir o que entra num dashboard que alguém vai olhar todo dia — ou que dispara um alerta às três da manhã. Um MVP de observabilidade de agente precisa de quatro categorias de métrica, não quinze.

Latência por step. Não a latência total da trajectory — isso esconde onde o tempo foi gasto. Você quer p50/p95/p99 de cada tipo de span: LLM, cada ferramenta, cada sub-agente. Isso permite responder "por que essa trajectory demorou 12 segundos" sem abrir o trace manualmente — o dashboard já aponta que 9 desses 12 segundos foram numa chamada específica de API externa.

Taxa de erro por ferramenta. Agregada por nome de ferramenta, não por trajectory. Uma ferramenta de consulta de CEP falhando 15% das chamadas é um sinal diferente de uma taxa de erro geral de 2%. Sem essa quebra, um problema pontual e sério fica diluído numa média que parece saudável.

Custo por trajectory. A métrica que interessa é a distribuição, não só a média. Um agente que custa R$ 0,08 por interação em média mas tem uma cauda custando R$ 4,00 tem um loop ou re-tentativa descontrolada que a média esconde — e isso se conecta direto com o cache hit rate: quando ele cai, o custo por trajectory sobe, e esse dashboard mostra o sintoma antes de você investigar a causa.

Cache hit rate. É o indicador mais barato de "algo mudou estruturalmente no prompt". Uma queda de 80% para 30% geralmente indica conteúdo dinâmico introduzido cedo demais — timestamp, ID de sessão, algo que devia estar no fim do prompt. Esse painel, sozinho, evita boa parte dos incidentes de custo antes que virem problema de FinOps.

Esses quatro painéis, quebrados por agente e por ferramenta, cobrem o essencial. O resto (breakdown de finish_reason, profundidade de árvore, uso por sub-agente) você adiciona conforme identifica necessidade real.

---

Debugando um Caso Real: Falha em Cascata Entre Agentes

Vale fechar com um cenário concreto. Imagine um orquestrador de atendimento que recebe "quero cancelar minha assinatura e saber se tenho reembolso" e delega para um sub-agente de billing, que precisa escolher entre duas ferramentas parecidas: get_refund_policy (política geral) e get_customer_refund_eligibility (elegibilidade específica daquele cliente).

O sub-agente de billing chama a ferramenta errada — get_refund_policy em vez de get_customer_refund_eligibility. O resultado não é um erro; é uma resposta válida, só que genérica: a política padrão de reembolso, sem considerar que aquele cliente está fora da janela de elegibilidade. O orquestrador recebe esse resultado, não tem motivo para desconfiar, e diz ao cliente que ele tem direito a reembolso integral. Está errado, e ninguém levantou uma exception.

Sem tracing estruturado, essa falha é quase impossível de reproduzir depois do fato — você só tem a reclamação do cliente e um log dizendo "200 OK". Com a trajectory completa, o debug vira mecânico: você abre o trace daquela sessão (localizável por session_id ou user_id, propagados em todos os spans), vê o span do orquestrador se expandir no span invoke_agent do sub-agente, e dentro dele os dois candidatos de tool call que o modelo considerou. Você vê o prompt exato enviado naquele ponto, e a causa fica óbvia: a descrição das duas ferramentas no schema é ambígua o suficiente para o modelo confundir uma com a outra.

A correção quase nunca é "trocar o modelo". É reescrever a descrição das ferramentas para serem mutuamente exclusivas, e opcionalmente adicionar uma validação de pós-condição — se a pergunta menciona "meu caso específico", force uma checagem de que a ferramenta de elegibilidade foi chamada antes de aceitar a resposta como final. Esse guarda-rail só fica óbvio quando você vê, span por span, onde a decisão divergiu do esperado — e é o que distingue resolver o incidente em vinte minutos de passar a tarde tentando reproduzir manualmente algo que só acontece em 15% das execuções.

---

Conclusão

Observabilidade de agentes não é uma extensão trivial do APM tradicional — é uma disciplina com vocabulário, ferramentas e padrões próprios, porque o objeto observado (uma cadeia de decisões não-determinísticas, potencialmente recursiva entre agentes) é diferente de uma stack trace de código determinístico. Tracing distribuído aplicado à trajectory, instrumentado com as semantic conventions de GenAI do OpenTelemetry, transforma "o agente errou, mas não sei por quê" em "o agente errou nesse span, com esse prompt, e aqui está o porquê".

Você não precisa adotar tudo de uma vez. Comece instrumentando com OpenTelemetry, suba um dashboard com as quatro métricas que cobri — latência por step, taxa de erro por ferramenta, custo por trajectory, cache hit rate — e escolha uma ferramenta compatível com onde seu time já vive. O ganho não é cosmético: é a diferença entre resolver um incidente em minutos, olhando a trajectory exata que falhou, ou passar a tarde adivinhando o que um modelo não-determinístico decidiu fazer há duas horas.

No fim, observabilidade de agente é aceitar uma premissa desconfortável: você não vai prever todo comportamento de um sistema que raciocina. Mas pode garantir que, quando ele errar, você tenha o rastro necessário para entender por quê — e essa garantia é o que separa um agente de demo de um agente de produção.

---

Fontes:

• OpenTelemetry — Semantic Conventions for Generative AI Systems
• Datadog — Monitor, Trace, and Evaluate LLM Applications with LLM Observability
• Honeycomb — Observability for LLM-Powered Applications
• LangChain — Debugging Agents with LangSmith Tracing