Meu Agente Chamou a Mesma API com Falha 5 Vezes—O Bug Não Estava no Código

O bug chegou em produção. Meu agente estava repetindo a mesma chamada de API cinco vezes. Por hábito, abri o código primeiro. A lógica de retry estava certa. O fluxo das funções era normal. Nem um único erro nos logs.

O código não tinha respostas. Só quando abri o trace que a causa ficou visível.

O código do agente é um recipiente vazio

Abra o código-fonte de qualquer agente e você vai encontrar uma especificação de modelo, uma lista de ferramentas e um system prompt. É basicamente isso. Qual ferramenta chamar e quando, qual sequência de raciocínio seguir—nada disso vive no código.

Times que trabalham com agentes baseados em LangGraph repetem isso sem parar: “Você não consegue julgar a qualidade de um agente por revisão de código.”

• Mesmo código, mesma entrada, padrões de chamada de ferramentas diferentes toda vez
• Diferente de uma função como handleSubmit(), a lógica de ramificação simplesmente não existe no código
• Testar o GPT-5.2 com a mesma query 10 vezes gera em torno de 40% de consistência na ordem das chamadas de ferramentas
• Quando erros acontecem, não há bug no código, tornando a reprodução impossível

Essa é a mudança fundamental. No software tradicional, o código é o comportamento. Nos agentes, o código é só o scaffolding. O comportamento real emerge em tempo de execução, moldado pelo raciocínio do modelo sobre o contexto que ele recebe.

Traces são o novo código-fonte

Um trace registra cada passo que o agente deu. O que ele raciocinou em cada etapa, qual ferramenta chamou e por quê—tudo capturado. A depuração, os testes e a análise de desempenho que fazíamos pelo código agora precisam acontecer pelos traces.

Quando um agente vê uma mensagem de erro e repete a mesma chamada assim mesmo, não é um bug no código. É uma falha de raciocínio. E você só consegue ver isso no trace.

• Comparar traces antes e depois de uma mudança no prompt revela diferenças de qualidade de raciocínio na hora
• No LangSmith, carregar um trace de um ponto específico no playground funciona como definir um breakpoint
• Um único trace pode mostrar o momento exato em que o raciocínio do agente desviou—algo que nenhuma quantidade de logs consegue replicar

Pense assim: depurar software tradicional é ler a receita para achar o erro. Depurar agentes é assistir ao vídeo da cozinha para ver onde o chef errou. A receita pode ser perfeita. A execução é onde as coisas quebram.

Os testes mudam fundamentalmente

No software tradicional, você testa antes do deploy e pronto. Agentes são não-determinísticos, então você precisa continuar avaliando em produção.

Sem um pipeline que coleta traces, constrói datasets de avaliação e detecta degradação de qualidade ou drift, você simplesmente não consegue operar agentes em escala.

Times que adotaram avaliação baseada em traces viram melhorias mensuráveis nas taxas de sucesso das tarefas. O padrão é consistente: traces revelam modos de falha que nenhum conjunto de testes pré-deploy conseguiria prever.

• Construa um pipeline de avaliação automatizado que amostra traces de produção semanalmente
• Testes pré-deploy sozinhos não conseguem garantir qualidade para sistemas não-determinísticos
• Monitorar sem traces é como só verificar se o servidor está rodando
• Um agente pode estar “funcionando normalmente” enquanto executa tarefas completamente erradas—só os traces pegam isso

Colaboração e analytics de produto também acontecem nos traces

Code review acontece no GitHub. Onde acontece a revisão do julgamento do agente?

Plataformas de observabilidade estão assumindo esse papel. Times comentam em traces, compartilham pontos de decisão específicos e revisam o raciocínio do agente da mesma forma que antes revisavam pull requests. O próprio modelo de colaboração está mudando.

Analytics de produto segue o mesmo padrão. Quando uma métrica diz “30% dos usuários estão insatisfeitos”, você não consegue encontrar a causa sem abrir os traces. O agente pode estar completando tarefas com sucesso pela sua própria métrica enquanto erra completamente o que o usuário realmente queria.

• Ferramentas de analytics como Mixpanel e ferramentas de depuração estão convergindo para os traces como substrato comum
• Analisar padrões de chamadas de ferramentas do agente pode fazer engenharia reversa para descobrir quais funcionalidades os usuários realmente precisam

O ponto final

Na era dos agentes, o código é a planta do edifício e os traces são a filmagem das câmeras de segurança. Quando algo vai errado no prédio, você não desdobra a planta primeiro—você rebobina a filmagem.

Os times que estão acertando na qualidade dos agentes são os que deslocaram seu centro de gravidade do código para os traces. Não porque o código não importa, mas porque as falhas interessantes—as que custam usuários e dinheiro—vivem no comportamento em tempo de execução que só os traces capturam.