Como Depurar um Agente de IA em Produção (Um Guia de Campo)

Índice

Atualizado junho de 2026.

TL;DR: Depurar um agente de IA em produção é principalmente sobre isolar qual camada falhou — prompt, chamada de ferramenta, saída do modelo ou orquestração. Registro cada passo com um ID de rastreamento, reproduzo as entradas exatas e biseco a partir daí. Nos meus agentes, cerca de 70% do que parece um “bug de IA” acaba sendo encanamento: um resultado de ferramenta malformado, uma entrada truncada, uma exceção silenciosamente engolida.

Leitura do operador: Opero mais de 100 agentes em produção — fluxos de reserva para a Pickleland, pipelines de conteúdo, triadores de caixa de entrada. Eles quebram do jeito que todo software quebra, mais algumas formas novas. Este é o guia de campo que eu gostaria de ter tido: como encontrar a camada que falha sem ficar encarando uma parede de tokens.

Quando um agente se comporta mal em produção, o instinto é culpar o modelo. “O Claude alucinou.” Às vezes é verdade. Geralmente não. O modelo é uma camada em uma pilha de cinco ou seis, e o bug está muito mais frequentemente na camada que você escreveu do que na que a Anthropic entregou. Este post é a forma sistemática como eu o encontro.

Torne cada execução rastreável antes de depurar qualquer coisa

Você não pode depurar o que não pode ver. A coisa de maior alavancagem que você pode fazer — antes de qualquer bug específico aparecer — é anexar um ID de rastreamento a cada execução do agente e registrar cada passo que ele dá.

Um “passo” é qualquer coisa que cruza uma fronteira: o gatilho de entrada, cada chamada ao modelo (com o array completo de mensagens), cada chamada de ferramenta (com argumentos), cada resultado de ferramenta e a saída final. Registre-os como JSON estruturado indexado pelo ID de rastreamento.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

No Cloudflare Workers eu os envio para uma fila e para uma tabela; localmente vão para o stdout. A regra é absoluta: se um passo não está registrado, ele não aconteceu no que diz respeito à depuração. Isso espelha a instrumentação que descrevo na stack de agentes que uso — o ID de rastreamento é a espinha dorsal da qual tudo o mais depende.

Isole a camada: prompt, ferramenta, modelo ou orquestração

Uma vez que você tem um rastreamento, a depuração vira uma bisseção. Há quatro camadas e o bug vive em exatamente uma delas na maior parte do tempo.

1. A camada de entrada (o culpado mais comum)

Extraia o array messages exato que entrou na chamada ao modelo que falhou. Não uma reconstrução — o payload literal do log. Depois leia-o como um estranho leria. Metade dos meus bugs de “o modelo ignorou as instruções” são na verdade:

• Um resultado de ferramenta que voltou como "[object Object]" porque algo foi convertido errado em string.
• Uma entrada truncada no meio da frase porque estourou a janela de contexto e um corte ingênuo a cortou.
• Uma variável que foi interpolada como undefined e envenenou silenciosamente o prompt.

Se a entrada está errada, o modelo fez seu trabalho perfeitamente sobre lixo. Conserte o encanamento.

2. A camada de ferramentas

Se a entrada parece limpa, verifique se uma ferramenta retornou um erro que o agente tratou como sucesso. Um clássico: uma API retorna 200 com um corpo de { "error": "rate limited" }, seu wrapper de ferramenta não verifica o corpo, e o agente age com confiança sobre uma mensagem de erro. Registre os resultados de ferramenta crus e verifique sua forma.

3. A camada do modelo

Só depois de descartar 1 e 2 é que suspeito do modelo. Mesmo então, “bug do modelo” geralmente significa “meu prompt é ambíguo.” Pegue a entrada exata que falhou, jogue-a num script avulso contra o mesmo modelo e temperatura, e veja se reproduz. Se reproduzir, a correção é trabalho de prompt ou uma eval mais rigorosa, não uma troca frenética de modelo.

4. A camada de orquestração

Se um único passo está bem isoladamente mas a execução de múltiplos passos falha, o bug está no repasse — estado perdido entre passos, uma condição de corrida, um retry que reexecutou uma ação não idempotente. Estes são os mais cruéis e eu cubro os padrões em padrões de orquestração multiagente.

Reproduza o não-determinismo em vez de combatê-lo

O que faz os agentes parecerem impossíveis de depurar é o não-determinismo: a mesma entrada produz saídas diferentes entre execuções. Você pode domá-lo.

Primeiro, fixe o que puder. Defina temperature: 0 durante a depuração. Não vai tornar o Claude totalmente determinístico, mas estreita bastante a variância para que você consiga distinguir um bug real do ruído de amostragem.

Segundo, execute N vezes. Se uma falha reproduz 1 em cada 20 execuções, repita a entrada exata 50 vezes e capture cada saída. Agora você tem uma amostra, não um anedota. Um bug que dispara 5% das vezes é um bug real — você só precisa de volume para vê-lo.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# então conte as falhas
grep -c '"status":"fail"' runs.jsonl

Terceiro, compare as execuções que passam e as que falham. Com a temperatura fixada e a mesma entrada, uma diferença na saída significa uma diferença na entrada que você ainda não notou — um timestamp no prompt, um resultado de ferramenta que varia, um documento recuperado que mudou.

Construa um harness de replay para parar de depurar em produção

Depurar reacionando o agente ao vivo é lento e arriscado — ele envia e-mails reais, reserva quadras reais. Em vez disso, capture o rastreamento e reproduza-o offline.

O harness de replay carrega um rastreamento registrado, reconstrói as entradas exatas de qualquer passo e reexecuta apenas aquele passo contra o modelo. Como você registrou o array completo messages, não precisa do sistema upstream de jeito nenhum. Isso transforma uma ida e volta de 10 minutos em produção num loop local de 2 segundos, e é a maior aceleração no meu fluxo de depuração.

Um bom harness de replay também permite mutar e reexecutar: mude uma linha do prompt de sistema, reproduza os mesmos 50 rastreamentos que falharam e veja quantos passam agora. Essa é a ponte da depuração para a eval — uma vez que você tem um corpus de rastreamentos que falham, você tem o começo de uma suíte de regressão.

Observe as métricas que realmente predizem quebras

Algumas falhas nunca lançam uma exceção. O agente roda, retorna algo plausível e silenciosamente faz a coisa errada. Para pegar essas você observa métricas comportamentais, não apenas taxas de erro:

• Taxa de sucesso de chamadas de ferramenta por ferramenta. Uma queda aqui frequentemente precede uma falha visível.
• Validade do schema de saída — qual % das saídas faz parsing contra a estrutura esperada. Valido cada saída com Zod e alerto quando a validade cai.
• Comprimento do loop — número médio de passos por execução. Um pico repentino geralmente significa que o agente está preso tentando novamente.
• Custo por execução — um loop descontrolado aparece como um pico de custo antes de aparecer como uma reclamação. (Quando o custo importa, vale conhecer a matemática de Haiku vs Sonnet.)

Eu acompanho essas do mesmo jeito que acompanho tudo o mais — veja como eu meço se um agente de IA está realmente funcionando. A métrica que pega uma falha silenciosa vale dez que pegam as barulhentas.

A checklist de triagem de 5 minutos

Quando um agente quebra e estou contra o relógio, eu rodo isto em ordem:

1. Obtenha o ID de rastreamento da execução que falhou.
2. Leia a entrada exata do passo que falhou. Está bem formada? (Resolve ~50% dos casos aqui.)
3. Verifique os resultados de ferramenta naquele rastreamento por erros disfarçados de sucesso.
4. Reproduza o passo offline em temperature: 0. Reproduz?
5. Se reproduz, é um problema de prompt/modelo — conserte e reexecute o corpus de rastreamentos. Se não, é não-determinismo ou um bug de estado/orquestração — repita 50× para caracterizá-lo.

Isolamento disciplinado vence prompting esperto toda vez. O modelo raramente é o problema; o sistema ao redor dele geralmente é.

FAQ

Como eu depuro um agente de IA que falha só às vezes?

Capture a entrada exata de um rastreamento registrado e reproduza-a mais de 50 vezes em temperatura 0. Falhas intermitentes são bugs reais com baixas taxas de disparo — o volume transforma a anedota numa amostra reproduzível que você pode comparar e corrigir.

O bug costuma estar no modelo ou no meu código?

Nos meus agentes de produção, cerca de 70% dos aparentes “bugs de IA” são encanamento: resultados de ferramenta malformados, entradas truncadas, exceções engolidas ou estado perdido entre passos. Descarte as camadas de entrada e de ferramenta antes de suspeitar do modelo.

Qual é o mínimo de logging que eu preciso para depurar agentes?

Um ID de rastreamento em cada execução, mais logs estruturados do gatilho, cada chamada ao modelo (array completo de mensagens), cada chamada de ferramenta e seu resultado cru, e a saída final. Se um passo não está registrado, você não consegue depurá-lo.

Como eu paro de depurar contra a produção ao vivo?

Construa um harness de replay que carregue um rastreamento registrado e reexecute qualquer passo isolado offline usando as entradas capturadas. Ele transforma uma ida e volta lenta e arriscada em produção num loop local rápido e se torna a semente da sua suíte de regressão.