Observabilidade de agentes de IA: depurar em produção

Observabilidade de agentes de IA é a diferença entre consertar um agente que falhou e só torcer para ele não falhar de novo. E a matemática explica a urgência: um agente com 95% de acerto por passo parece sólido — até você encadear 10 passos e a taxa de sucesso cair para cerca de 60%, e para 36% em 20 passos. A conta de erro composto foi detalhada por Flavius Dinu em análise publicada no Medium (k8slens), e é a razão pela qual demos que impressionam viram operações que travam.

O detalhe cruel é que esse tipo de falha quase nunca aparece no log comum. O agente chama uma ferramenta, recebe uma resposta que parece válida, interpreta errado e segue em frente sem lançar nenhum erro. Quando o resultado final sai torto, o log te mostra o sintoma no passo 9 — não a causa, que estava no passo 3. Este guia mostra como tornar essa cadeia visível antes que ela custe caro.

Por que um agente de IA quebra sem dar erro

Um sistema tradicional falha com stack trace: exceção, código de erro, linha exata. Um agente de IA falha em silêncio, porque cada passo é uma decisão probabilística, não uma instrução determinística. A plataforma Latitude mapeou cinco modos de falha recorrentes em agentes em produção — e nenhum deles dispara um erro clássico:

• Corrupção de estado: algo decidido no início da sessão contamina uma decisão lá na frente, invisível se você olhar cada turno isolado.
• Falha silenciosa de ferramenta: a tool devolve uma resposta válida no formato, mas errada no conteúdo, e o agente confia nela.
• Divergência não determinística: a mesma entrada gera caminhos diferentes, então o bug não se reproduz de forma confiável.
• Propagação de erro: um deslize pequeno no passo 3 se acumula pelos passos seguintes e explode como falha grande no passo 9.
• Desalinhamento de avaliação: o agente vai bem nas métricas automáticas e mesmo assim não entrega o que o usuário pediu.

Não é pessimismo de blog: o Gartner projeta que mais de 40% dos projetos de IA agêntica serão cancelados até o fim de 2027, citando custo alto e valor pouco claro. E benchmarks de sistemas multiagente mostram taxas de falha em produção que vão de 41% a 87%, segundo levantamento da própria Latitude. O que derruba a maioria não é o modelo — é a falta de visibilidade sobre o que o agente fez e por quê.

O que é observabilidade de agentes de IA

Observabilidade é conseguir responder por que o sistema se comportou daquele jeito olhando só para o que ele emitiu — sem precisar reproduzir o problema. Para um agente, isso significa registrar cada etapa do raciocínio: qual prompt entrou, qual modelo respondeu, quantos tokens foram gastos, qual ferramenta foi chamada, com quais argumentos, o que ela devolveu e quanto tempo levou. Não é o mesmo que monitorar um servidor — CPU e memória não dizem nada sobre por que o agente escolheu a ferramenta errada.

Trace e span: o caminho completo da decisão

A unidade básica é o trace: a jornada inteira de uma requisição, do pedido do usuário à resposta final. Dentro dele, cada operação vira um span — uma chamada ao LLM, uma consulta ao banco, uma execução de ferramenta. Aninhados, os spans formam a árvore da decisão. É essa árvore que transforma "o agente errou" em "no span 4, a busca no estoque retornou vazio e o agente inventou um número em vez de avisar". Sem ela, depurar agente é adivinhação.

OpenTelemetry GenAI: o padrão que evita lock-in

Instrumentar tudo à mão em cada ferramenta é retrabalho garantido. Por isso o mercado convergiu para o OpenTelemetry, o mesmo padrão aberto de telemetria que já domina backend, agora com um grupo dedicado a IA: as GenAI Semantic Conventions, ativas desde abril de 2024. Elas padronizam como registrar uma operação de IA — atributos como gen_ai.request.model (o modelo usado), gen_ai.usage.input_tokens e gen_ai.usage.output_tokens (contagem de tokens) e gen_ai.response.finish_reasons (por que o modelo parou).

A vantagem é concreta: se você emite spans no padrão OTel, troca de ferramenta de análise sem reinstrumentar o código. Datadog, New Relic e Honeycomb já leem essas convenções nativamente, e frameworks como LangChain, CrewAI e AutoGen emitem spans compatíveis por instrumentação pronta. Padronizar hoje é não ficar refém de um fornecedor amanhã — a mesma lógica de uma boa integração via API entre sistemas.

Langfuse, LangSmith ou Helicone: qual usar

As três ferramentas mais citadas representam apostas de arquitetura diferentes. Escolher errado custa em preço ou em cegueira de dados:

• Helicone: funciona como proxy, registrando cada requisição no nível da chamada. Simples de plugar e honesto para chains diretas e volume de gasto mais baixo.
• Langfuse: plataforma de tracing por spans com suporte de primeira classe às convenções OTel GenAI. É a escolha padrão para agentes multi-passo e para quem precisa de avaliação e datasets no mesmo lugar.
• LangSmith: nativa do ecossistema LangChain e LangGraph, com replay de trajetória e depurador passo a passo — imbatível se você já vive nesse stack.

Para começar sem custo, o Langfuse tem um plano gratuito de 50 mil observações por mês, sem cartão, e o núcleo é open source sob licença MIT: você pode rodar tudo self-hosted de graça, útil quando há exigência de residência de dados (LGPD). O projeto foi adquirido pela ClickHouse em janeiro de 2026, com as capacidades atuais mantidas. Além de depurar, a mesma trilha de spans expõe custo por token e por passo — insumo direto para o ROI da automação com IA parar de ser chute.

Como instrumentar seu agente: passo a passo

Dá para sair do zero à visibilidade útil em uma tarde. O caminho que costuma funcionar:

• Escolha uma ferramenta que fale OpenTelemetry GenAI, para não amarrar o código a um fornecedor único desde o primeiro dia.
• Instrumente o trace de ponta a ponta: um trace por interação do usuário, com um span para cada chamada de LLM e cada execução de ferramenta aninhados dentro dele.
• Registre entrada, saída, tokens e latência de cada span. É o que separa "deu ruim" de "deu ruim aqui, por isto".
• Marque as chamadas de ferramenta com seus argumentos e retornos — a maioria das falhas silenciosas mora exatamente aí.
• Adicione avaliação: rode checagens automáticas (ou um LLM avaliador) sobre uma amostra das respostas de produção para pegar desalinhamento antes do cliente pegar.
• Feche o loop: junte os traces de falha num dataset, corrija o prompt ou o fluxo, e reteste contra esse mesmo dataset para provar que melhorou.

Esse último passo é o que vira observabilidade em qualidade de verdade. Traços de produção viram casos de teste; casos de teste viram guardrails; guardrails evitam a próxima falha silenciosa. É assim que uma automação inteligente com IA ou um atendimento com IA deixam de ser uma caixa-preta e passam a ser um sistema que você melhora com dado, não com achismo.

Um agente sem observabilidade não é autônomo — é apenas um erro que você ainda não conseguiu ver. A diferença entre os dois é a árvore de spans.

Se você já tem um agente ou automação rodando e não consegue explicar por que ele erra às vezes, a VELTRIX faz um diagnóstico gratuito: instrumentamos os primeiros traces, mostramos onde a cadeia de decisão está quebrando e apontamos o custo por passo antes de qualquer proposta. É o jeito de trocar o achismo por dado — e parar de rezar para o agente funcionar.