Observabilidade de agentes de código: o que medir além de tokens e custo

O painel dizia que o uso estava alto. O sistema continuava difícil de manter

Uma equipe habilita um agente de código para centenas de desenvolvedores. O dashboard mostra quantidade de sessões, tokens consumidos e sugestões aceitas. Depois de algumas semanas, a liderança quer saber se a iniciativa está funcionando.

A resposta não está nesses números.

Aceitar uma sugestão não significa que ela chegou à produção. Uma chamada de ferramenta bem-sucedida não significa que o resultado foi útil. Um agente pode consumir pouco, responder rápido e ainda introduzir duplicação, dependências frágeis, testes que apenas exercitam imports ou alterações que ninguém consegue revisar com segurança.

O problema não é a falta de telemetria. É medir apenas a parte mais fácil da operação.

O que a instrumentação precisa revelar

Uma implementação útil começa tratando cada execução do agente como uma operação observável, não como uma caixa-preta associada a um usuário.

O OpenTelemetry oferece uma base adequada para isso porque permite reunir traces, métricas e logs em um pipeline comum. O ponto importante, porém, não é apenas exportar spans. É definir atributos que representem as decisões e os efeitos reais do agente.

1. Quais habilidades estão sendo usadas

Se a organização mantém skills próprias — para consultar padrões internos, criar componentes, revisar contratos ou operar ferramentas — cada invocação precisa carregar um identificador estável, como skill_name.

Esse dado responde a perguntas que o custo não responde:

• Quais skills aparecem nas tarefas reais?
• Quais são usadas por apenas um time?
• Quais foram construídas, documentadas e nunca chamadas?
• Uma skill é reutilizada ou cada equipe mantém uma variação parecida?

Sem essa dimensão, o inventário de skills vira uma lista de intenções. Com ela, passa a existir uma trilha de uso que pode ser comparada com o código produzido e com os resultados das tarefas.

2. Quais ferramentas são críticas e quais estão falhando

Servidores MCP e outras ferramentas externas precisam ser observáveis como dependências de produção. Nomear a ferramenta com mcp_tool_name, registrar latência e classificar erros permite distinguir problemas diferentes:

• uma ferramenta lenta, mas confiável;
• uma ferramenta rápida que falha em casos específicos;
• um servidor usado por muitos fluxos e sem alternativa;
• uma integração que responde com erro, mas cujo erro é engolido pelo agente;
• uma ferramenta que recebe chamadas, mas não produz alterações aproveitáveis.

A classificação do erro importa tanto quanto a contagem. Timeout, autenticação, limite de uso, resposta inválida e falha de validação exigem ações diferentes. Uma métrica agregada de “tool error” costuma esconder justamente a decisão operacional necessária.

3. Como o trabalho se espalha entre subagentes

A execução de um agente raramente é linear. Um agente principal pode delegar pesquisa, análise, edição e validação a outros agentes. Se o contexto de trace não é propagado, o observador enxerga apenas a chamada inicial e perde a árvore que explica o comportamento.

Quando cada subagente aparece como um span filho, torna-se possível reconstruir:

• quem iniciou a cadeia;
• quais subagentes foram chamados;
• em que ordem;
• quanto tempo cada etapa consumiu;
• onde ocorreu a falha;
• quais ferramentas foram usadas em cada ramo.

Isso muda a investigação. Em vez de perguntar por que uma sessão demorou, o time pode localizar o ramo responsável pela demora e verificar se ele é necessário, redundante ou mal configurado.

4. O que sobrevive no código

A métrica mais enganosa da operação de assistentes de código é a aceitação da sugestão. Ela mede um clique, não o valor entregue.

Uma alternativa é acompanhar a sobrevivência da edição. A pergunta passa a ser: quanto do código aceito continua presente depois de novas alterações, revisões, testes e releases?

Essa medida também precisa ser interpretada com cuidado. Uma edição removida pode ter sido substituída por uma solução melhor. Uma edição que sobrevive pode continuar errada. Ainda assim, observar a permanência oferece mais contexto do que uma taxa de aceitação isolada.

Para isso, é necessário relacionar a execução do agente com o diff produzido e com a evolução posterior do repositório. O vínculo pode ser feito por trace, commit, pull request ou outro identificador adotado pelo fluxo da equipe. O importante é não fingir precisão onde o sistema não consegue estabelecer a relação.

Um desenho técnico mínimo

A instrumentação não precisa começar com um programa paralelo de observabilidade. Ela pode entrar no mesmo fluxo usado para operar os agentes.

No ponto de execução

Cada execução deve criar um span principal com atributos como:

• identificador da organização, time ou projeto;
• ambiente e cliente de execução;
• modelo ou versão do agente, quando aplicável;
• skill acionada;
• resultado da execução;
• duração;
• referência para a alteração gerada, quando existir.

Os valores devem evitar conteúdo sensível. O objetivo é observar o comportamento do sistema, não exportar prompts, arquivos inteiros ou segredos para o backend de telemetria.

No ponto de ferramenta

Cada chamada de ferramenta deve ser um span filho. Além do nome, registre início, fim, status, tipo de erro e informações suficientes para identificar o servidor ou o recurso sem expor credenciais.

A política de cardinalidade merece atenção. Nomes de ferramentas, repositórios e equipes podem ser úteis como dimensões; texto livre de erro, caminhos completos e entradas arbitrárias podem criar custo e risco desnecessários. O esquema precisa ser definido antes de liberar a exportação para toda a organização.

No ponto de delegação

A propagação do contexto deve atravessar a chamada para subagentes. Sem isso, a organização pode ter milhares de spans tecnicamente corretos, mas sem relação causal.

A árvore precisa permanecer consultável no backend escolhido, com correlação entre execução principal, subagentes, ferramentas e resultado final. O formato deve ser o mesmo nos diferentes clientes de desenvolvimento. Caso contrário, o time acaba mantendo dois sistemas de observabilidade para o mesmo processo.

Telemetria não substitui evidência de engenharia

O trace mostra como o agente trabalhou. Ele não prova sozinho que a arquitetura melhorou.

Para avaliar o efeito no repositório, combine a telemetria com sinais de engenharia: hotspots de mudança, complexidade, duplicação, cobertura e qualidade dos testes, dependências, tratamento de erros e evolução dos componentes. Uma alteração que sobrevive no arquivo, por exemplo, ainda precisa ser examinada à luz da saúde do módulo em que foi aplicada.

Também é necessário separar três tipos de informação:

• fato: a chamada ocorreu, a ferramenta retornou erro, o commit alterou determinado arquivo;
• estimativa: parte da edição permaneceu após um intervalo definido;
• interpretação: a alteração melhorou ou piorou a manutenibilidade.

Misturar essas camadas produz dashboards convincentes e decisões frágeis. Quando não houver correlação confiável entre a sessão e o código, o resultado correto é declarar a análise inconclusiva.

Como transformar sinais em uma solução operável

Uma sequência prática evita começar pelo dashboard:

1. Defina as decisões que a organização precisa tomar: remover uma skill, corrigir um servidor MCP, revisar uma política ou priorizar uma área do código.
2. Escolha os eventos que sustentam essas decisões e estabeleça um esquema estável de atributos.
3. Instrumente primeiro o caminho principal, as ferramentas e a delegação de subagentes.
4. Crie controles de privacidade, retenção, acesso e cardinalidade antes de exportar em escala.
5. Relacione a telemetria com commits, pull requests e análises do repositório.
6. Valide os indicadores com exemplos reais, incluindo sessões que falharam e alterações que foram revertidas.
7. Publique apenas métricas que tenham uma ação associada.

O resultado não precisa ser um placar único de produtividade. Em muitos casos, uma tabela de investigação é mais útil: ferramenta, volume de chamadas, latência, classes de erro, equipes afetadas, alterações relacionadas e evolução do componente.

Onde o ArchGenerator pode entrar

Uma plataforma de diagnóstico pode ajudar a fechar o intervalo entre o evento observado e a decisão sobre o código. O ArchGenerator, por exemplo, conecta evidências do repositório a laudos de arquitetura, saúde, integração, evolvabilidade e risco de código assistido por IA. Isso permite analisar sinais como dependências frágeis, clones, erros engolidos, hotspots e lacunas de teste junto da trajetória das alterações.

A vantagem não está em prometer que a telemetria identifica automaticamente uma boa decisão. Está em manter cada conclusão vinculada ao que foi medido, ao arquivo e à linha que sustentam o achado. Quando a correlação entre uso do agente e efeito no código não puder ser comprovada, ela deve permanecer marcada como inconclusiva.

A partir desse diagnóstico, o time pode gerar um kit executável de especificações, contratos, guardrails e sensores de progresso. Assim, a observabilidade deixa de ser apenas retrospectiva: passa a orientar as próximas mudanças e a verificar se os riscos realmente diminuíram.

O próximo passo é medir o efeito, não a atividade

Agentes de código já produzem atividade suficiente para preencher qualquer painel. O trabalho difícil é identificar quais chamadas, integrações e alterações melhoram — ou degradam — a capacidade de evoluir o sistema.

OpenTelemetry fornece o encanamento para observar essa operação. Convenções de GenAI, contexto propagado e correlação com o repositório fornecem a estrutura. A engenharia continua responsável por interpretar os sinais, declarar incertezas e escolher o que fazer depois.

Uma organização madura não pergunta apenas quantos tokens gastou ou quantas sugestões aceitou. Pergunta quais ferramentas sustentam o trabalho, onde os agentes falham, que alterações permanecem e qual evidência mostra que o sistema ficou melhor.