Observabilidade e Rastreamento de Agentes (OpenTelemetry)

1. Visão geral do conceito e problema sistêmico

Um agente autônomo em produção é uma caixa-preta de alta incerteza:

• O usuário reclama: "O agente levou 45 segundos para responder e retornou um absurdo".
• Sem observabilidade, o desenvolvedor não sabe: o modelo travou no raciocínio? A ferramenta de busca respondeu com 40 segundos de latência? Ou o agente fez 12 requisições redundantes devido a alucinação?
• No final do mês, a empresa recebe uma fatura de $15.000 em vez de $1.500 por causa de um worker invisível preso em loop.

Agent Observability transforma o caos da execução não determinística em uma estrutura hierárquica transparente de eventos e spans (Spans & Traces).

2. Taxonomia arquitetural e modelo mental

Trace ID: 7f8a91-bc42 (Total: 4.8s, Cost: $0.024)
┌─────────────────────────────────────────────────────────────┐
│ ROOT SPAN: User Task: "Analyze sales and generate summary"  │
│ ├── SPAN 1: LLM Reasoning (Claude 3.7) [1.2s, 1.4k tokens]  │
│ │   └── Output: Tool Call `query_database`                  │
│ ├── SPAN 2: Tool Execution: PostgreSQL [0.3s, 42 rows]     │
│ ├── SPAN 3: LLM Reasoning (Reflect on data) [0.9s]          │
│ │   └── Output: Tool Call `generate_chart`                  │
│ ├── SPAN 4: Tool Execution: Python Sandbox [1.8s]           │
│ └── SPAN 5: Final Response Synthesis [0.6s, 450 tokens]     │
└─────────────────────────────────────────────────────────────┘

Pilares fundamentais da observabilidade:

1. Traces & Spans: Árvore completa de chamadas: cada invocação de modelo ou ferramenta possui horário de início, duração, argumentos de entrada e resultados de saída.
2. Token & Cost Attribution: Contabilidade precisa dos custos de tokens (Input, Output, Cache Read, Cache Write) com detalhamento por feature específica do produto.
3. Session Replay: Capacidade de reproduzir passo a passo o estado da memória do agente no momento de qualquer falha.

3. Cenários práticos de engenharia em produção

01. Detecção de vazamentos anômalos de tokens

Alertas no Slack são disparados se uma sessão do agente exceder o limite de 100.000 tokens ou durar mais de 3 minutos. O engenheiro revisa o trace no Langfuse e percebe que o modelo ficou preso corrigindo o mesmo conflito sintático repetidamente.

02. Monitoramento de cache de prompts (Prompt Caching Hit-Rate)

O dashboard rastreia a porcentagem de requisições que atingem o cache estático da Anthropic/OpenAI. Se a taxa de cache cair abaixo de 80%, isso sinaliza que um commit recente quebrou a estrutura do prefixo do prompt.

4. Armadilhas comuns, erros típicos e segurança

• Overhead de armazenamento (Storage Bloat): Registrar prompts completos de cada usuário sob carga de 100.000 requisições/dia pode gerar gigabytes de logs diariamente. Utilize amostragem (Sampling Rate = 10% para requisições bem-sucedidas, 100% para erros) e bancos de dados analíticos rápidos (ClickHouse).
• Vazamento de segredos nos traces: Se o agente ler um arquivo .env, o conteúdo das chaves pode acabar na interface de monitoramento. Ative regexes de sanitização no nível do SDK cliente.

5. Conclusão estratégica para o engenheiro de 2026

A observabilidade é pré-requisito obrigatório para levar agentes do laboratório ao negócio real. O que não pode ser medido e rastreado através de spans é impossível de otimizar com segurança ou escalar para centenas de milhares de usuários.