Observabilidade em aplicações de IA: como descobrir o que seu agente aprontou

Um bug tradicional costuma deixar rastro: uma exceção, uma linha de log, um stack trace apontando o culpado. Um agente que “decidiu” fazer algo estranho não tem esse tipo de rastro por padrão, porque a decisão aconteceu dentro de um modelo, e sem instrumentação nenhuma, tudo o que sobra depois é a resposta final, sem explicação de como se chegou até ali.

O que vale a pena capturar, no mínimo

Para reconstruir o que um agente fez, quatro coisas costumam ser indispensáveis: qual prompt foi enviado e com qual contexto, quais tools foram chamadas e com quais argumentos, quantos tokens cada chamada consumiu, e qual foi a resposta final recebida do modelo. Sem esses quatro pontos, investigar um comportamento inesperado depois vira reconstrução por hipótese, em vez de leitura direta do que realmente aconteceu.

OpenTelemetry como base comum, ainda em formação

OpenTelemetry vem definindo convenções semânticas específicas para IA generativa, sob o prefixo gen_ai.*: atributos padronizados para nome do modelo, contagem de tokens de entrada e saída, motivo de finalização da geração, além de spans dedicados para chamada de modelo e execução de tool. A vantagem de seguir essa convenção, em vez de inventar um esquema de atributo próprio, é permitir que qualquer ferramenta de observabilidade compatível com OpenTelemetry consiga interpretar esses dados sem tradução manual.

Vale registrar que essas convenções específicas de IA generativa ainda estão em desenvolvimento, sem status estável fechado, então nomes de atributo podem mudar entre versões. Isso não invalida usá-las hoje, só pede atenção a qual versão da convenção está sendo seguida ao configurar a instrumentação.

Instrumentando sem reescrever a aplicação inteira

Para quem já usa Microsoft.Extensions.AI, boa parte dessa instrumentação já vem pronta como middleware, sem precisar instrumentar manualmente cada chamada:

builder.Services.AddChatClient(services =>
    baseClient
        .AsBuilder()
        .UseOpenTelemetry(sourceName: "MinhaAplicacao.IA")
        .UseFunctionInvocation()
        .Build(services));

UseOpenTelemetry envolve as chamadas ao IChatClient numa Activity do System.Diagnostics, populando os atributos gen_ai.* relevantes automaticamente, o que inclui a chamada de tool quando UseFunctionInvocation está na mesma pipeline.

Contagem de token não é detalhe de faturamento, é sinal de comportamento

Acompanhar o número de tokens consumidos por chamada não serve só para prever custo. Um salto inesperado de consumo de token numa interação específica costuma ser sinal de outra coisa acontecendo: um contexto crescendo mais do que deveria, um ciclo de correção entre etapas que não está convergindo, ou uma ferramenta devolvendo uma resposta muito maior do que o esperado. Sem essa métrica visível por chamada, esse tipo de anomalia só aparece na fatura no fim do mês, tarde demais para investigar a causa raiz.

Rastrear a chamada de tool com o mesmo cuidado que se rastreia uma chamada de API

Toda vez que um agente decide invocar uma ferramenta, isso deveria ser registrado com o mesmo nível de detalhe que qualquer chamada de API externa: nome da tool, argumentos recebidos, resultado devolvido, tempo de execução. Sem isso, entender por que um agente tomou determinada ação específica exige inferir a partir da resposta final, sem visibilidade sobre o caminho que ele realmente percorreu para chegar lá.

Ferramentas prontas em vez de reinventar o painel

Construir um painel próprio a partir de dados brutos de trace é possível, mas ferramentas especializadas em observabilidade de LLM, como LangSmith ou Arize Phoenix, já vêm com visualização pensada para esse tipo de dado: linha do tempo de chamadas encadeadas, custo agregado por sessão, comparação entre execuções. Para quem já opera dentro do ecossistema AWS, exportar essas métricas para o CloudWatch, com um relatório customizado sobre latência, contagem de token e taxa de erro por tool, também é um caminho razoável, aproveitando infraestrutura de monitoramento que já existe em vez de introduzir mais uma ferramenta nova na stack.

Sem instrumentação, “funcionou” é uma opinião, não um fato

Sem visibilidade sobre prompt, tool, token e resposta, qualquer afirmação de que um agente “está funcionando bem” é, na melhor das hipóteses, uma impressão baseada em algumas interações observadas manualmente. Com instrumentação decente, essa mesma afirmação vira algo que pode ser checado, comparado ao longo do tempo, e principalmente investigado quando alguma coisa sai visivelmente errada.