# Observabilidade dentro das ferramentas de IA com OpenTelemetry

Este é o nono e último artigo da série sobre arquitetura AI friendly. Ao longo dos textos, falamos sobre contexto, documentação, observabilidade do sistema, skills, agentes, tools, MCP, segurança e o fluxo completo de uma demanda.

Para fechar a série, quero olhar para dentro da própria ferramenta de IA.

Quando um agente participa de uma tarefa, normalmente observamos apenas o resultado final. O pull request foi criado? Os testes passaram? A feature foi entregue?

Essas perguntas são importantes, mas não explicam o caminho percorrido.

Quanto tempo levou para o agente encontrar o contexto certo? Quantas vezes ele repetiu a mesma investigação? Quais ferramentas usou? Em que momento precisou de uma aprovação? O problema estava no modelo, na documentação, na integração ou no próprio fluxo de trabalho?

Sem esses sinais, qualquer avaliação fica baseada em impressão.

## O trabalho do agente também precisa ser observável

Em sistemas tradicionais, já entendemos que logs, métricas e traces ajudam a explicar o comportamento de uma aplicação. Não esperamos que uma API seja confiável apenas porque respondeu uma vez. Observamos latência, erros, dependências, volume e impacto.

Com agentes, muitas equipes ainda fazem o contrário. Avaliam a ferramenta por algumas interações isoladas e concluem que ela é rápida, lenta, boa ou ruim.

Uma sessão de agente também é um fluxo distribuído. Ela envolve um modelo, contexto, ferramentas, permissões, sistemas externos, arquivos, testes e decisões humanas. O resultado final é apenas o último evento dessa cadeia.

Se queremos melhorar esse fluxo, precisamos enxergar o que acontece antes dele.

![](https://cdn.hashnode.com/uploads/covers/67081fa628a6c4cdb75a7fc9/e98ed5d6-ff82-4af9-abd1-c47cbabb2f20.png align="center")

## O que vale a pena medir

Observar não significa registrar tudo. O objetivo não é construir um mecanismo de vigilância sobre desenvolvedores, nem transformar quantidade de tokens em uma falsa medida de produtividade.

O objetivo é criar evidências para decisões de engenharia.

Alguns sinais ajudam bastante:

*   quantidade e duração das sessões;
    
*   tempo gasto em chamadas de modelo e ferramentas;
    
*   tokens consumidos e custo estimado;
    
*   erros, retries e interrupções;
    
*   quantidade de aprovações solicitadas;
    
*   testes executados e seus resultados;
    
*   arquivos ou linhas alteradas;
    
*   resultado da tarefa, como pull request criado, mudança interrompida ou entrega concluída.
    

O valor aparece quando combinamos esses sinais com perguntas reais.

Uma nova documentação reduziu o tempo até a primeira hipótese? Uma skill de investigação diminuiu a quantidade de chamadas de ferramenta? Um MCP externo está adicionando latência sem melhorar o resultado? Um agente está pedindo aprovação cedo demais ou tarde demais? Uma mudança no contexto aumentou o custo porque trouxe informação relevante ou porque adicionou ruído?

Essas são perguntas que não podem ser respondidas olhando apenas para a resposta final do agente.

Uma métrica boa não é necessariamente a mais fácil de contar. É a que ajuda a entender uma decisão ou identificar uma oportunidade de melhoria.

## OpenTelemetry como uma camada comum

O exemplo desta etapa usa OpenTelemetry porque ele é um padrão aberto e um projeto open source. Podemos começar sem contratar uma plataforma proprietária de observabilidade.

Uma arquitetura possível usa um OpenTelemetry Collector para receber e encaminhar os sinais, Prometheus para armazenar métricas e Grafana para consultá-las. São componentes gratuitos e open source, embora o modelo utilizado pela ferramenta ou uma plataforma gerenciada possam ter custos próprios.

O ponto mais importante não é a escolha do dashboard. É a separação entre a ferramenta que produz os eventos e o sistema que os observa.

O OpenCode é apenas o exemplo usado neste artigo. Ele pode ser instrumentado por um plugin que exporta sinais via OTLP. A mesma arquitetura pode ser aplicada ao Codex, Claude Code, Cursor ou outra ferramenta quando existir um exportador nativo, um plugin, um hook ou um adaptador capaz de produzir telemetria.

Cada ferramenta pode ter uma forma diferente de emitir eventos. O backend não precisa conhecer todos esses detalhes. Ele pode trabalhar com conceitos mais estáveis, como sessão, chamada de modelo, tool, aprovação, erro e resultado.

Essa separação permite trocar a ferramenta sem reconstruir toda a infraestrutura de observabilidade. Também permite comparar fluxos diferentes usando uma linguagem comum.

## De atividade para resultado

Uma armadilha comum é observar apenas atividade.

Mais mensagens não significam necessariamente mais progresso. Mais tokens podem representar um contexto melhor, mas também podem indicar que o agente está perdido. Mais chamadas de ferramentas podem mostrar uma investigação cuidadosa ou uma ausência de documentação.

Por isso, sinais de atividade precisam ser relacionados a sinais de resultado.

| Atividade | Resultado que vale investigar |
| --- | --- |
| Tokens usados | A tarefa foi concluída com menos retrabalho? |
| Chamadas de tools | O agente encontrou evidências melhores? |
| Duração da sessão | O tempo trouxe qualidade ou apenas espera? |
| Aprovações solicitadas | O limite de autonomia estava adequado? |
| Linhas alteradas | Os testes e critérios de sucesso foram atendidos? |

Esse cuidado evita transformar observabilidade em um placar. O agente não está sendo avaliado por produzir o maior volume possível. Estamos tentando entender se o sistema de trabalho ajuda a equipe a chegar a decisões melhores com segurança.

## O contexto também aparece nas métricas

Os sinais de uma sessão podem mostrar problemas que não estão no modelo.

Se o agente passa muito tempo procurando arquivos, talvez a arquitetura de contexto esteja difícil de descobrir. Se ele repete consultas, talvez falte uma skill mais especializada. Se as chamadas externas são lentas, talvez a integração esteja mal desenhada. Se ele pede aprovação em quase todas as etapas, talvez as permissões estejam granulares demais ou o fluxo não tenha sido bem definido.

Esse é um ponto importante da arquitetura AI friendly: contexto não é apenas algo que entregamos ao agente. É também algo que podemos avaliar a partir do comportamento observado.

A telemetria fecha o ciclo entre contexto, execução e aprendizado.

## Observabilidade também é segurança

Telemetria de agentes pode conter mais informação do que parece.

Um prompt pode carregar uma regra interna. Um argumento de tool pode conter um token. Um resultado pode incluir dados de cliente. Um trace pode registrar um trecho de código. Um caminho de arquivo pode revelar a estrutura de um sistema.

Por isso, não devemos confiar no próprio agente para decidir o que pode ser enviado para o backend. A proteção precisa estar em componentes determinísticos, como o Collector, o gateway de telemetria e as políticas de acesso.

Alguns princípios são importantes:

*   prompts completos não devem entrar em métricas;
    
*   argumentos e resultados de tools precisam ser sanitizados antes do envio;
    
*   caminhos de arquivos e conteúdo de código não devem virar labels;
    
*   credenciais devem ficar fora da configuração versionada;
    
*   tokens de destinos gerenciados devem ter o menor privilégio possível;
    
*   retenção e acesso devem ser definidos antes da coleta;
    
*   identificadores de alta cardinalidade precisam ser tratados com cuidado.
    

Esse cuidado se conecta ao artigo sobre [segurança, guardrails e fitness functions](https://luizschons.com/seguran-a-guardrails-e-fitness-functions-para-agentes). Guardrails determinísticos não devem proteger apenas as ações do agente. Eles também precisam proteger os dados gerados durante o trabalho do agente.

## O caso do session\_id

Durante uma investigação, pode ser útil abrir uma sessão específica e entender o que aconteceu nela. Uma implementação local pode permitir selecionar um `session_id` no Grafana para esse tipo de análise.

Isso é conveniente em um ambiente local, mas cada sessão nova pode criar uma nova série de métricas. Em uma operação com muitos usuários e muitas execuções, esse crescimento de cardinalidade pode ser caro e difícil de sustentar.

Por isso, existe uma diferença entre observabilidade para desenvolvimento e observabilidade para produção.

Em um ambiente de desenvolvimento, manter o identificador pode facilitar a aprendizagem. Em produção, talvez seja melhor usar métricas agregadas e encaminhar traces ou logs sanitizados para um backend apropriado para investigação individual.

O dashboard é uma ferramenta de investigação. Ele não deve ser tratado como autorização para coletar qualquer dado.

## Um laboratório para tornar a ideia concreta

Para não deixar a discussão apenas no campo conceitual, criei o repositório [agent-observability-with-opentelemetry](https://github.com/sschonss/agent-observability-with-opentelemetry).

Ele contém uma infraestrutura local com OpenTelemetry Collector, Prometheus e Grafana, além de um dashboard inicial para sessões de agentes. O OpenCode aparece como exemplo de instrumentação, mas o desenho foi feito para que a camada de backend possa receber sinais de outras ferramentas.

O repositório também documenta os limites do experimento. Logs e traces ficam desabilitados no primeiro momento porque podem carregar prompts, código e argumentos sensíveis. A ideia é começar com métricas pequenas, entender o que realmente precisamos observar e só depois ampliar a coleta.

Esse caminho é mais saudável do que ligar todos os sinais disponíveis e descobrir tarde demais que criamos um novo problema de segurança.

## Conclusão

Uma arquitetura AI friendly não deve apenas fornecer contexto para o agente. Ela também deve tornar o trabalho do agente observável.

Quando medimos sessões, duração, tokens, tools, erros, aprovações e resultados, conseguimos discutir a evolução do fluxo com evidências. Podemos descobrir que o problema não está no modelo, mas na documentação. Podemos perceber que uma skill reduziu exploração. Podemos encontrar uma integração lenta ou uma etapa que exige revisão humana cedo demais.

OpenTelemetry oferece um caminho aberto para começar. OpenCode foi apenas o exemplo usado neste artigo. A mesma separação entre ferramenta, instrumentação, Collector e backend pode acompanhar outras ferramentas e outros modelos.

Esse é o encerramento da série. A ideia central continua simples: agentes melhores dependem menos de adivinhação e mais de contexto, limites, evidências e feedback. A observabilidade é o mecanismo que nos mostra se estamos realmente evoluindo.