Observabilidade de agentes de código é a disciplina de registrar o que Codex, Claude Code e outros agentes fizeram, com quais ferramentas, permissões, tokens, erros e evidências. Sem isso, o PR parece normal, mas o time não sabe explicar custo, risco, tentativa ou causa da falha.
Em 2026, o GitHub Blog em "Agent pull requests are everywhere" relatou mais de 60 milhões de revisões com Copilot code review, crescimento de 10 vezes em menos de um ano e mais de uma em cada cinco revisões envolvendo agente (GitHub Blog, "Agent pull requests are everywhere", 2026, consultado em 2026-07-20). Esse volume exige rastro operacional, não fé no resumo do agente.
Resumo prático
- A trilha mínima registra ferramenta, permissão, custo e resultado.
- JSONL do Codex vira artefato de CI, não log aberto.
- OpenTelemetry do Claude Code deve começar redigido por padrão.
- O PR precisa mostrar evidência curta que humanos conseguem revisar.
Por que observabilidade virou parte do harness?
Em 2026, o arXiv em "AI Agent Pull Requests on GitHub" analisou 33.596 PRs de agentes em 2.807 repositórios e encontrou pares coativos em 40,2% dos repositórios no recorte de sobreposição exata (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-20). Observabilidade virou parte do harness porque autoria paralela sem rastro vira custo invisível.
O harness não é só prompt, sandbox e teste. Ele também precisa responder quem iniciou a tarefa, qual agente executou, que ferramenta pediu permissão, qual comando falhou, qual subagente participou e qual evidência chegou ao PR. Sem isso, cada incidente vira arqueologia.
O erro comum é guardar apenas o diff final. O diff mostra o resultado, mas não mostra a rota. Em fluxo agentic, a rota importa: uma falha de permissão, um MCP amplo ou uma repetição de teste pode explicar por que um patch pequeno consumiu horas.
Cápsula citável: Observabilidade de agentes de código transforma execução agentic em trilha auditável. O arXiv analisou 33.596 PRs e achou coatividade em 40,2% dos repositórios; quando agentes trabalham em paralelo, o PR precisa mostrar ferramenta, permissão, tentativa e prova.
Esse recorte complementa PRs de agentes de código que falham antes do merge. Ali, o foco é revisão. Aqui, o foco é a trilha que permite revisar sem reconstruir tudo manualmente.
Que eventos o agente precisa registrar?
Em 2026, o mesmo estudo do arXiv relatou que pares coativos respondiam por 79,4% de todos os PRs gerados por agente no recorte de sobreposição exata (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-20). O evento certo é aquele que explica coordenação, custo ou risco sem copiar conversa inteira.
Registre o início da tarefa, cada chamada de ferramenta relevante, decisões de permissão, falhas, retries, mudanças de arquivo, chamadas MCP, criação de subagente, resultado de teste e fechamento do turno. Não registre segredo, prompt completo ou saída de ferramenta bruta sem necessidade.
Uma boa trilha tem poucos campos estáveis. Use identificador de sessão, agente, ferramenta, decisão, duração, resultado, caminho redigido quando necessário e referência ao artefato de CI. O dado precisa servir tanto para debug quanto para auditoria.
Experiência prática: quando coloco agente em pipeline de backend, eu não começo pelo dashboard. Começo por uma linha estável de evento: tarefa, ferramenta, permissão, comando de prova e motivo de parada. Depois o painel nasce desse contrato.
| Evento | Pergunta que ele responde |
|---|---|
| Início da sessão | Quem pediu a tarefa e em qual commit? |
| Tool use | Que ferramenta tentou agir e por quê? |
| Permissão | A ação foi aceita, bloqueada ou reprovada? |
| Teste | Que prova foi rodada antes do resumo? |
| Fechamento | O agente terminou, falhou ou pediu humano? |
Cápsula citável: O evento mínimo em um loop agentic não é transcript completo. É uma linha auditável com sessão, agente, ferramenta, decisão, resultado e artefato. Como 79,4% dos PRs agentic estavam em pares coativos no estudo, coordenação precisa virar dado.
Para tarefas longas, custo de contexto também entra nessa trilha. Eu uso o RemoteCode para manter continuidade em fluxos agentic de Codex e Claude Code sem repetir contexto desnecessário quando o trabalho atravessa sessões, logs e evidências; é uma ferramenta minha, então a menção aqui é editorial e ligada ao problema de observabilidade e tokens.
Como usar JSONL do Codex sem vazar contexto?
Em 2026, a documentação da OpenAI em "Non-interactive mode" afirma que codex exec --json emite JSON Lines com eventos como início de thread, início de turno, conclusão, falha, itens e erro (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-20). Use esse fluxo como contrato de máquina, não como despejo público.
No CI, salve JSONL como artefato restrito e gere um resumo menor para o PR. O resumo deve listar comandos, arquivos alterados, MCP usado, resultado de teste e razão de parada. O JSONL completo fica disponível para debug por pessoas autorizadas.
Também separe stdout de stderr. A OpenAI documenta que codex exec transmite progresso para stderr e imprime a mensagem final em stdout quando não está em JSONL. Isso ajuda a impedir que ruído operacional vire conteúdo de PR.
{
"execucao_agente": {
"ferramenta": "codex",
"modo": "ci",
"trilha": "artefato-restrito",
"resumo": "comentario-pr",
"revisao_humana": "obrigatoria"
}
}Cápsula citável: JSONL do Codex deve alimentar observabilidade, não substituir revisão. A documentação da OpenAI lista eventos de turno, item, falha e erro; no CI, esses eventos devem ficar em artefato restrito, com resumo seguro no PR.
Esse padrão conversa com loop self-correcting de agente no CI. O loop usa feedback para corrigir. A observabilidade mostra se o feedback foi pequeno, seguro e suficiente.
Como ligar Claude Code a OpenTelemetry com segurança?
Em 2026, a documentação de "Monitoring" do Claude Code define intervalos padrão de 60 segundos para métricas e 5 segundos para logs, além de exportar métricas, eventos e traces via OpenTelemetry (Claude Code Docs, "Monitoring", 2026, consultado em 2026-07-20). A configuração segura começa redigida por padrão.
O ponto mais importante é separar telemetria do agente da telemetria do código testado. A documentação informa que variáveis OTEL_* do Claude Code não são repassadas automaticamente para subprocessos como Bash, hooks, MCP servers e language servers. Isso evita confundir spans do agente com spans da aplicação.
Ative métricas e eventos primeiro. Só depois habilite traces detalhados quando você souber quem pode ver prompt, ferramenta e conteúdo. Em times regulados, mande eventos para SIEM com retenção, controle de acesso e regra explícita para dados sensíveis.
Cápsula citável: OpenTelemetry para Claude Code deve começar com métricas e eventos redigidos. A documentação informa intervalos padrão de 60 segundos para métricas e 5 segundos para logs, mas também separa variáveis do agente dos subprocessos.
Se você já usa hooks que seguram agentes antes do estrago, trate hooks como fonte de evento. Eles registram decisão, bloqueio e exceção. O dashboard deve mostrar bloqueio útil, não só sucesso bonito.
Onde custo, tokens e contexto entram no dashboard?
Em 2026, a documentação de "Monitoring" do Claude Code lista input_tokens, output_tokens, cache_read_tokens e cache_creation_tokens em eventos de requisição de API (Claude Code Docs, "Monitoring", 2026, consultado em 2026-07-20). O dashboard precisa mostrar consumo por tarefa, não apenas total mensal.
Tokens sem contexto não explicam nada. Compare custo com tipo de tarefa, área do código, número de tentativas, quantidade de ferramentas e resultado final. Um run caro que gerou prova pode ser aceitável. Um run barato que abriu PR sem teste ainda é risco.
Também olhe cardinalidade. A documentação de Claude Code alerta que atributos customizados entram nas séries de métricas e podem aumentar custo de armazenamento. Use time, projeto e tipo de fluxo. Evite caminho de arquivo completo como label de métrica.
Cápsula citável: Dashboard de agente precisa combinar tokens, ferramenta, tentativa e resultado. Claude Code expõe campos de tokens e cache em eventos de API; a métrica só vira decisão quando ligada a PR, teste, bloqueio e risco operacional.
Esse tema continua o custo invisível do contexto em agentes de código. A diferença é que agora o custo não fica só no prompt. Ele aparece como métrica que o time consegue comparar.
Qual contrato mínimo cabe no CI esta semana?
Em 2026, o arXiv em "AI Agent Pull Requests on GitHub" mediu conflito textual de 41,7% em pares cross-agent contra 19,8% em pares intra-agent ao simular merges reais (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-20). O contrato mínimo precisa revelar concorrência antes que ela vire conflito caro.
Comece com um artefato agent-run.json em cada workflow agentic. Ele deve registrar ferramenta, commit base, commit final, modo de permissão, MCP habilitado, comandos de verificação, resultado, tentativas e se houve revisão humana. Não precisa ser perfeito. Precisa ser estável.
Depois publique um resumo curto no PR. O revisor quer saber o que mudou, como foi testado, que permissão foi usada e onde está a trilha completa. Quando houver conflito, retry ou mudança fora de escopo, marque revisão humana obrigatória.
| Campo | Regra prática |
|---|---|
| Identidade | Declare ferramenta, sessão e autor humano responsável. |
| Permissão | Registre sandbox, rede, MCP e exceções. |
| Prova | Liste comando rodado e resultado verificável. |
| Custo | Guarde tokens, tentativa e duração em artefato restrito. |
| Parada | Explique se concluiu, falhou ou pediu revisão humana. |
Cápsula citável: O contrato mínimo de observabilidade em CI é um artefato por run e um resumo por PR. Como cross-agent conflict chegou a 41,7% no estudo do arXiv, cada tarefa precisa declarar identidade, permissão, prova, custo e regra de parada.
Para escopo de segurança, combine isso com allowlist de MCP para agentes de código. Observabilidade mostra o que aconteceu. Allowlist reduz o que poderia acontecer.
FAQ sobre observabilidade de agentes de código
Observabilidade substitui revisão humana?
Não. Em 2026, o arXiv em "These Aren't the Reviews You're Looking For" concluiu que PRs gerados por IA recebem mais interação mediada por automação do que avaliação humana independente (arXiv, "These Aren't the Reviews You're Looking For", 2026, consultado em 2026-07-20). Observabilidade melhora revisão, mas não decide arquitetura.
Posso guardar transcript completo do agente?
Só quando houver controle claro de acesso. Em 2026, a documentação de "Data usage" do Claude Code afirma que transcripts locais ficam em texto claro em ~/.claude/projects/ por 30 dias por padrão (Claude Code Docs, "Data usage", 2026, consultado em 2026-07-20). Para CI, prefira artefato restrito e resumo redigido.
JSONL do Codex basta para auditoria?
Ajuda, mas não basta sozinho. Em 2026, a OpenAI documenta JSONL com eventos e item types, incluindo comandos, mudanças de arquivo, chamadas MCP e web searches (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-20). Você ainda precisa mapear esses eventos para risco, PR e decisão humana.
Quais métricas entram primeiro no dashboard?
Comece por custo, tokens, duração, tentativas, tool calls, bloqueios de permissão e resultado de CI. Em 2026, Claude Code documenta eventos de API com tokens, custo estimado, duração, tentativas e request id (Claude Code Docs, "Monitoring", 2026, consultado em 2026-07-20). Depois segmente por time e tipo de tarefa.
Fechamento
Agente de código sem observabilidade é rápido até a primeira pergunta difícil. Quem autorizou? Que ferramenta rodou? Por que custou tanto? Que teste provou? Qual MCP participou? Sem resposta, o time revisa sensação, não engenharia.
Comece pequeno: JSONL restrito, OTel redigido, resumo de PR e contrato de evento. O objetivo não é vigiar pessoa. É tornar o loop agentic depurável, barato de revisar e seguro o bastante para virar parte do SDLC.
Fontes consultadas
- GitHub Blog, "Agent pull requests are everywhere. Here's how to review them", consultado em 2026-07-20, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
- arXiv, "AI Agent Pull Requests on GitHub: Frequency, Structure, and Merge Conflict Rates", consultado em 2026-07-20, https://arxiv.org/abs/2607.04697
- arXiv, "These Aren't the Reviews You're Looking For How Humans Review AI-Generated Pull Requests", consultado em 2026-07-20, https://arxiv.org/abs/2605.02273
- OpenAI Developers, "Non-interactive mode", consultado em 2026-07-20, https://developers.openai.com/codex/non-interactive-mode
- Claude Code Docs, "Monitoring", consultado em 2026-07-20, https://code.claude.com/docs/en/monitoring-usage
- Claude Code Docs, "Hooks reference", consultado em 2026-07-20, https://code.claude.com/docs/en/hooks
- Claude Code Docs, "Data usage", consultado em 2026-07-20, https://code.claude.com/docs/en/data-usage
