Observabilidade de agentes de IA: como entender o que o agente fez e o que registrar

O que é observabilidade de um agente de IA

Observabilidade de agentes de IA é a possibilidade de responder, com base em artefatos — e não na memória ou nas palavras do agente —, a três perguntas: o que ele fez, por que exatamente assim, e o que comprova que o resultado está correto. Se, depois de vinte minutos de trabalho, o agente diz «pronto, mas dois testes falham, talvez por causa de timing», e, quando você pergunta quais caminhos foram afetados, responde «deixe eu olhar o código», não há observabilidade. O agente não é burro: ele simplesmente não tem o que apresentar.

O problema é sistêmico. O mesmo agente, ao longo de uma semana, pode dizer dez vezes, com honestidade, «pronto», e cada vez isso significará uma coisa diferente: em um caso, todos os testes foram rodados; em outro, só um; em outro, nada. Quanto mais tempo o projeto vive, mais cara fica cada nova sessão, porque ela começa com escavação.

Duas camadas: runtime e processo

Observabilidade costuma ser confundida com logs, mas logs são só metade da história.

Só o runtime: vê-se o que caiu, mas não se sabe o que se pretendia. Só o processo: sabe-se o que se queria, mas não se vê por que não deu certo. São necessárias as duas.

Por que o agente não faz isso sozinho

Pedir ao agente «registre melhor o que faz» não funciona, por três motivos.

• Ele não sabe o que não sabe. O agente não registra um sinal cuja importância ele não percebe.
• O formato varia. Em uma sessão ele escreve em detalhe; em outra, em uma linha. Comparar sessões e calcular agregados fica impossível.
• O processo não se fecha com logs. A resposta para «por que assim» está em documentos criados antes do trabalho, e não na saída dos comandos.

Por isso a observabilidade é incorporada ao harness — o ambiente do agente: modelos, hooks, scripts, formato obrigatório do relatório.

O que registrar: o conjunto mínimo

Um bom diário não é uma transcrição de tudo, e sim um conjunto de fatos com os quais é possível reconstruir o andamento do trabalho e calcular estatísticas.

• Identificadores: id da sessão, id da tarefa ou da funcionalidade, modelo do agente.
• Ações com efeitos colaterais: quais comandos foram executados, quais arquivos foram alterados. A leitura de arquivos normalmente não precisa ser registrada.
• Resultados das verificações: qual comando de verificação, código de retorno, quantos testes passaram e quantos falharam.
• Retentativas: quantas tentativas foram necessárias em um passo e em que diferiam.
• Consumo: tokens e tempo, se a ferramenta os informar.
• Desfecho: a tarefa foi aceita, rejeitada ou abandonada, e por quê.

O que não registrar: segredos, tokens de acesso, dados pessoais presentes na saída dos comandos. O diário pode acabar em um acesso compartilhado ou voltar ao contexto do modelo.

Diário de ações com hooks do Claude Code

No Claude Code, é cômodo manter o diário com hooks — comandos disparados pela própria ferramenta, e não pelo modelo, por isso eles sempre são executados. O hook recebe em sua entrada um JSON com a descrição do evento, incluindo o id da sessão, o nome da ferramenta e seus parâmetros. Exemplo de configuração em .claude/settings.json que, depois de cada chamada de Bash, Edit ou Write, acrescenta uma linha ao diário:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — uma linha JSON por ação
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

O formato JSONL (um registro JSON por linha) é prático porque pode ser filtrado com jq e carregado em qualquer sistema de análise. Além disso, o próprio Claude Code guarda o histórico completo das sessões localmente, no diretório ~/.claude/projects/ — dá para abri-lo quando se quer ver o raciocínio e a saída completa, mas, para estatísticas, o próprio diário compacto é mais cômodo.

Rastreamento: um trace por sessão, um span por tarefa

Quando há muitos agentes ou eles trabalham agendados, os diários de texto deixam de bastar: são necessários agregados. Aqui servem as ferramentas comuns de rastreamento distribuído e o padrão OpenTelemetry.

• Trace — uma sessão do agente.
• Span — uma tarefa dentro da sessão.
• Spans aninhados — passos de verificação: build, testes, E2E.

O mínimo de atributos por span: id da funcionalidade e da sessão, modelo, resultado da verificação, tokens, número de retentativas. Esses dados são lidos no Jaeger, no Grafana Tempo, no Honeycomb e respondem a perguntas que não se veem dentro de uma sessão isolada: que tipo de tarefa exige mais retentativas, onde o agente gasta mais tokens, depois de qual mudança no harness caiu a taxa de tarefas aceitas. O Claude Code tem exportação embutida de métricas e eventos via OpenTelemetry — ela é ativada por variáveis de ambiente; os detalhes estão na documentação da ferramenta.

Commits como diário

O diário mais barato e confiável já existe: é o git. Basta torná-lo legível.

1. Um commit — uma tarefa. Assim, o git log coincide com a lista do que foi feito, e reverter uma tarefa é um único git revert.
2. Na mensagem — o que foi feito e como foi verificado. Não «fix», e sim «o que mudou, por quê, com qual comando foi verificado».
3. Commit só depois de uma verificação verde. Assim, cada ponto do histórico é um estado funcional, e o git bisect encontra o culpado.

fix(payments): arredondamento do desconto em centavos

O desconto era calculado em float, e em um valor de 999.99 perdia-se um centavo.
Passei o cálculo para int, em centavos.
Verificado: make test (142 passed), make e2e checkout — ok.
Fora do escopo: arredondamento nos relatórios, registrado no BACKLOG.md.

Relatório do agente: evidências no lugar de impressões

A mensagem final do agente também é um artefato de observabilidade, se tiver um formato fixo. Defina o modelo no AGENTS.md ou no CLAUDE.md:

## Relatório ao final da tarefa
- O que foi feito: lista de alterações (arquivo — o essencial)
- Como foi verificado: comandos exatos e seus resultados
- O que NÃO foi verificado e por quê
- Desvios do acordo sobre a tarefa
- Perguntas em aberto para a pessoa

A regra principal: cada afirmação aponta para uma evidência — arquivo e linha, saída de um teste, registro no diário. «Parece normal» e «acho que está ok» não contam como relatório. O item «o que não foi verificado» é especialmente valioso: ele mostra com honestidade os limites da confiança.

Acordo antes do código e rubrica depois

A camada de processo começa antes do trabalho. Um acordo curto sobre a tarefa (sprint contract) fixa o escopo, os critérios de aceitação, a seção «fora do escopo» e as perguntas em aberto que a pessoa decide. A seção «fora do escopo» evita metade das discussões sobre o resultado.

Depois do trabalho, o resultado é avaliado por uma rubrica, e não por impressão. Caso contrário, dois revisores experientes dariam vereditos diferentes, e a avaliação viraria loteria.

Cada dimensão é avaliada com A/B/C/D, e uma nota sem referência não vale. Uma regra simples de decisão: um D ou duas C — rejeitar, com a lista do que corrigir. Essa mesma rubrica pode ser aplicada por um agente verificador separado.

Como revisar o que o agente fez em uma sessão

Se não há relatório ou se ele não merece confiança, percorra os artefatos nesta ordem.

1. Estado da árvore: git status — o que não foi commitado, se há arquivos de lixo.
2. Histórico: git log --stat desde o início da sessão — quais commits e arquivos.
3. Tamanho das alterações: git diff --stat main...HEAD, depois o diff completo dos arquivos importantes.
4. Diário de ações: quais comandos foram executados e o que as verificações retornaram.
5. Nova verificação: rode você mesmo o build e os testes. Confie na saída de um comando, e não no relato sobre ele.

# quais comandos o agente rodou na última sessão
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# quais arquivos foram editados com mais frequência
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Erros típicos

• Registrar tudo. Gigabytes de transcrição que ninguém lê. Registre as ações com efeitos colaterais e os resultados das verificações.
• Formato livre. Se o próprio agente define o formato do diário, não haverá agregados. O formato quem define é o harness.
• Acreditar no relatório sem a saída dos comandos. «Testes verdes» sem a saída é uma opinião.
• Retentativas cegas. Sem a causa da falha, o agente mexe em lugares aleatórios. Exija primeiro o diagnóstico com link para o log, e só depois a correção.
• «Limpamos depois». Arquivos de depuração e alterações não commitadas confundem a sessão seguinte: ela não distingue o temporário do intencional.

Resumo

A observabilidade de agentes de IA se constrói em duas camadas: runtime (diário de ações por meio de hooks, traces, commits com a descrição das verificações) e processo (acordo sobre a tarefa antes do código, rubrica e relatório com evidências). Assim, «pronto» significa a mesma coisa em cada sessão, e revisar o trabalho do agente leva minutos. O tema é tratado na prática no curso de harness engineering, em um projeto de backend de pagamentos.