Depuração de Agentes de IA: o Seu Painel Conhece o Custo, mas Não a Causa

A depuração de agentes de IA começa onde o seu painel de observabilidade termina. Quando um agente de codificação de IA quebra algo e a execução já terminou, o painel pode informar quanto a execução custou (tokens, dólares, latência), e fica em silêncio sobre a única pergunta que você realmente tem: por que o agente alterou aquele arquivo? O artefato que responde a isso é um trace registrado que você pode abrir, ler e reproduzir, porque ele devolve a execução a você em vez de descrevê-la de fora.

Isso deixou de ser um evento raro no momento em que os agentes começaram a fazer trabalho de verdade. Um agente percorre um repositório, edita vários arquivos, executa as verificações e reporta sucesso, tudo entre dois comandos que você digitou com minutos de diferença. Se uma dessas edições estiver errada, você descobre depois: depois que o terminal foi fechado, depois que o histórico de rolagem se foi, depois que o processo que poderia ter se explicado já saiu. O que acontece em seguida depende inteiramente do que você guardou. Se a resposta for um painel de custos, você está prestes a fazer arqueologia. Se a resposta for uma gravação, você está prestes a fazer leitura.

A falha que você não consegue reproduzir

É assim que funciona. Você volta ao repositório e um arquivo que você nunca pediu a ninguém para tocar foi reescrito, ou excluído, ou esvaziado da função da qual todo o resto depende. Você pergunta ao agente o que aconteceu; a sessão está encerrada, e mesmo quando uma transcrição sobrevive, o relato do agente sobre a própria execução é uma reconstrução, não uma gravação. Então você faz o que é natural e executa novamente, e obtém uma execução diferente. Chamadas de ferramentas diferentes, edições diferentes, possivelmente nenhuma falha, porque a trajetória original dependia de amostragem, do estado do repositório, do timing. A execução que você precisa inspecionar não existe mais.

É pior do que não reproduzível. É não reproduzível e marcado como sucesso. Uma execução sai com o código 0 quando o agente sai com o código 0, mesmo que uma verificação dentro da execução tenha saído com o código 1: o pipeline pode estar verde enquanto uma etapa de verificação dentro da execução falhou, e o código de saída em que você naturalmente confiaria não está lhe dizendo nada.

Não importa qual modelo o roteador escolheu para a execução (GLM 5.3 Flash ou qualquer outro): quando o processo termina, o raciocínio desaparece junto com ele. A evidência existia apenas enquanto a execução estava ativa: os prompts, as chamadas de ferramentas, as saídas, os diffs. Se nada os registrou, "por que ele mudou aquele arquivo" não tem resposta. Tem apenas teorias.

Este é o modo de falha que separa agentes de codificação de IA de todas as ferramentas que vieram antes deles: o dano e a explicação acontecem no mesmo lugar, e o lugar se fecha.

O que um dashboard mede e o que ele ignora?

O instinto após uma execução ruim é abrir o painel de observabilidade, e o painel será genuinamente bom no seu trabalho. O trabalho dele é tráfego: tokens por dia, custo por modelo, latência, taxas de erro. Para planejamento de capacidade e faturamento, esse é exatamente o instrumento certo, e se você executa agentes em produção, deve mantê-lo aberto.

Mas a sua pergunta não é agregada. Ela é singular e causal: por que esta execução alterou este arquivo? A agregação passa exatamente por cima da granularidade que a responde. Na média entre as execuções, a execução que lhe interessa é ruído; dentro dessa execução, a chamada de ferramenta que lhe interessa é ruído novamente.

Um painel descreve uma execução pelo lado de fora: que ela aconteceu, quanto pesou, quanto custou. Ele não pode entregar a execução a você, e o "porquê" não é uma propriedade da descrição. É uma propriedade da sequência.

• Quanto custou a execução? — O painel de custos responde a isso vs. o trace gravado responde a isso

• Por que o agente alterou esse arquivo? — Painel de custos Sem resposta vs. Rastreamento gravado A edição, em sequência, com seu diff

• Qual verificação falhou dentro de uma execução verde? — Painel de custos Sem resposta vs Rastreamento gravado A verificação, com seu código de saída

• Posso executar a mesma falha novamente? — Painel de custos: Não vs. Rastreamento gravado: Sim, offline, sem custo.

A camada que responde a isso está logo abaixo: logs de requisições gravados, capturados durante a execução, com cada prompt enviado, cada chamada de ferramenta emitida, cada resposta que voltou, em ordem. Não um resumo da execução. A execução em si.

Lendo uma execução como linha do tempo

Com uma gravação, depurar deixa de ser arqueologia e vira leitura. Arqueologia é o que você faz sem uma: git reflog, entradas de stash, histórico do shell, sua própria lembrança do que você pediu mais cedo naquele dia. Leitura é o que você faz com uma: abra a linha do tempo e role.

A linha do tempo apresenta a execução na ordem em que aconteceu: o prompt que a iniciou, cada chamada de ferramenta, cada edição de arquivo com seu diff, cada verificação, cada código de saída. Um snapshot do sistema de arquivos é tirado uma vez por turno, em vez de uma vez por chamada de ferramenta, o que é suficiente para ver o estado do repositório em cada etapa da conversa sem se afogar no ruído de cada chamada. O que torna isso depuração, e não navegação, é a adjacência: a edição e a verificação que a reprovou ficam lado a lado, em ordem, sem nada entre elas sobre o que especular. O "porquê" é, em sua maioria, uma propriedade da adjacência.

Um exemplo concreto, extraído de uma correção registrada: 14 eventos, incluindo a alteração de arquivo impressa como +1 -3 e uma verificação que falhou com o código de saída 1. A edição e, em seguida, a verificação que falhou por causa dela, adjacentes no registro. Essa é toda a diferença entre reconstruir uma execução a partir de fragmentos e ler uma execução. Isso é mais importante para agentes de codificação em terminal, cujo espaço de trabalho é um terminal que fecha no momento em que o trabalho é concluído: a linha do tempo é o histórico de rolagem que sobrevive.

Registrado ou inferido: o que o trace sabe versus o que ele deduziu

Uma linha do tempo mostra o que aconteceu em ordem. O grafo causal mostra o que levou ao quê, e a lacuna entre esses dois é onde a confiança precisa ser conquistada.

O grafo conecta eventos: esta edição, depois esta verificação com falha. Algumas dessas arestas são fatos registrados: a chamada de ferramenta que produziu o diff está ali mesmo no trace. Outras são inferidas: a conclusão do grafo de que a verificação falhou por causa daquele diff. o orca graph rotula cada aresta como registrada ou inferida e nomeia a regra que usou em ambos os casos, para que você sempre saiba se está vendo algo que a execução fez ou algo que a ferramenta deduziu sobre a execução.

Essa distinção é uma imposição, não mera aspiração: arestas inferidas nunca são gravadas de volta no trace. O trace permanece um registro fiel do que aconteceu; a inferência é uma visão por cima dele, que você pode inspecionar, questionar e contestar. Isso é especialmente importante quando há mais de um agente envolvido. Quando um agente de refatoração e um agente de escrita de testes alteram os mesmos arquivos, "qual agente causou isso" é exatamente a pergunta atribuição multiagente existe para responder. Uma aresta que silenciosamente se promove de inferência a fato é como você acaba depurando uma história em vez de uma execução.

Reproduzindo-o quantas vezes quiser, de graça

Ler explica. Repetir comprova. Uma vez que você tem uma hipótese (a verificação falhou porque a edição removeu a chamada de reset), você quer executá-la de novo e ver acontecer. Reexecutar o agente ao vivo gera uma nova trajetória e uma nova conta.

Reproduzir a gravação garante a mesma execução: a reprodução roda com a rede bloqueada, portanto não custa tokens e não tem variação. Os mesmos eventos, todas as vezes, offline. Essa é a propriedade que transforma a depuração de agentes de jogo de azar em engenharia: a falha se tornou determinística, e falhas determinísticas são corrigidas.

A ferramenta também não é uma caixa-preta. OrcaReplay é de código aberto sob a licença Apache-2.0 e o formato de trace é CC BY 4.0; portanto, qualquer pessoa pode reimplementá-lo: suas gravações não são reféns de um formato proprietário, nem as nossas. E ele é exercitado, não apenas demonstrado: 1393 testes no Node 20 e no Node 22. Você pode ler o código-fonte, verificar o formato e executar a suíte você mesmo antes de confiar as execuções da sua equipe a qualquer parte disso.

A conclusão

Um dashboard é uma conta. Um trace registrado é a execução. Se o seu plano para depurar agentes de IA termina em um dashboard de custos, você não tem um plano de depuração: você tem um sistema de cobrança. O dashboard sempre será capaz de dizer quanto uma execução custou, e nunca será capaz de dizer por que o agente excluiu seu arquivo, porque o "porquê" vive na sequência, e a sequência só existe se você a manteve.

O método inteiro tem quatro etapas:

• Registre as execuções.

• Leia a linha do tempo.

• Verifique as arestas do grafo.

• Reproduza os que te assustam, gratuitamente, quantas vezes quiser.

Nota sobre as fontes: todos os números deste artigo são fornecidos pelo fornecedor, a partir do nosso próprio produto e do repositório OrcaReplay e da sua documentação: o comportamento do código de saída de uma execução, a correção registrada com 14 eventos, com seu diff +1 -3 e sua verificação de código de saída 1, a rotulagem de arestas no grafo orca, a cadência de snapshot de uma vez por turno, o replay offline com a rede bloqueada e a suíte de 1393 testes no Node 20 e no Node 22. Nenhuma medição de terceiros é citada em qualquer parte deste artigo. A suíte de 1393 testes é a única afirmação que você pode verificar por conta própria: basta clonar o repositório e executá-la. Todos os itens foram verificados pela última vez em 2026-09-04.