O Agente Mentiu Para Mim: A Verdade Revelada com o Debugger AI da Apidog

Uma tarde de terça-feira. Doze viraram uma sessão de depuração, e o agente me dizia com confiança que nosso endpoint /users estava respondendo em quarenta e sete segundos. O número real era quarenta e sete milissegundos.

Eu estava perseguindo esse bug por dois dias. Toda vez que eu adicionava uma declaração de impressão ao servidor MCP, a resposta do agente mudava o suficiente para me fazer pensar que eu estava chegando a algum lugar. Toda vez que eu reescrevia o prompt do sistema, a resposta soava mais plausível. Nada disso estava certo.

O que eu não tinha feito, até aquela tarde, era abrir o rastreamento de execução real e olhar o que estava sendo passado entre o modelo e a ferramenta. É para isso que serve o Apidog’s AI Agent Debugger. Eu o havia instalado três semanas antes e esquecido. Levei doze minutos para encontrar o bug.

Isso foi o que me surpreendeu.

O bug que eu estava perseguindo

A configuração era simples. Um agente construído no GPT-5.5. Um servidor MCP que eu tinha escrito em um fim de semana, expondo uma ferramenta get_response_time(endpoint) que consultava nosso pipeline de métricas. Um prompt de sistema de talvez quarenta palavras. O prompt do usuário: "Quão rápido é o endpoint /users?"

O agente respondia rápido. Respondia com confiança. Respondia errado, toda vez, de diferentes maneiras. Às vezes "o endpoint está respondendo em 47 segundos". Às vezes "cerca de 0,05 segundos". Uma vez, memoravelmente, "o desempenho é aceitável".

Eu estava fazendo as coisas que se fazem. Adicionando log ao servidor MCP. Lendo a resposta do modelo token por token. Diferenciando prompts de sistema. Xingando. Eu tinha três janelas de terminal abertas e uma página do Notion de hipóteses falhas na manhã de terça-feira.

A questão sobre depurar agentes é que o bug raramente está onde você olha primeiro. Ele pode estar no prompt do sistema, na escolha do modelo, na definição da ferramenta, nos parâmetros que o modelo passou para a ferramenta, nos dados que a ferramenta retornou ou em como o modelo interpretou esses dados. Seis lugares. Um console log mostra um.

O que o painel de rastreamentos realmente mostra

O depurador Apidog abre em três colunas. Sessões à esquerda. Turnos no meio. Rastreamentos à direita. Clique em qualquer sessão e a coluna do meio mostrará o diálogo: mensagem do usuário, resposta do modelo, chamada da ferramenta, retorno da ferramenta, próxima resposta do modelo. Clique em qualquer turno e a coluna da direita se expandirá na árvore de execução completa abaixo dele.

A árvore de execução era a parte que eu estava perdendo. Cada passo, em ordem:

• Prompt do sistema como o modelo o recebeu
• Prompt do usuário como o modelo o recebeu
• Nome e parâmetros da chamada da ferramenta, como JSON, exatamente como o modelo os emitiu
• Payload do resultado da ferramenta, como JSON, exatamente como a ferramenta o retornou
• Resposta do modelo, com tempo e tokens para o turno

Abri a sessão com falha. A chamada da ferramenta parecia boa: get_response_time(endpoint="/users"). O modelo havia escolhido a ferramenta certa com o argumento certo.

Então, expandi o resultado da ferramenta.

{"value": 47, "p95": 89, "samples": 1240}

Lá estava. O pipeline de métricas retornou o valor em milissegundos. O modelo assumiu segundos. 47 tornou-se "47 segundos" através de uma alucinação confiante que não se preocupou em questionar a unidade. A ferramenta estava correta. O modelo estava errado. Meu prompt de sistema não tinha instrução sobre unidades, e a resposta da ferramenta não tinha anotação de unidade.

Doze minutos desde a abertura do depurador. Dois dias eu estava culpando o prompt do sistema.

A correção levou seis linhas

Mudei duas coisas. No servidor MCP, atualizei o formato da resposta:

{
  "value": { "amount": 47, "unit": "ms" },
  "p95": { "amount": 89, "unit": "ms" },
  "samples": 1240
}

Então adicionei uma frase ao prompt do sistema: "Os resultados das ferramentas retornam unidades explicitamente. Leia-os com atenção."

Executei o mesmo prompt /users mais três vezes. Três sessões diferentes no painel esquerdo. Todas as três retornaram corretamente "o endpoint está respondendo em torno de 47 ms" com uma detalhamento milissegundo por percentil no raciocínio do modelo. O custo do token foi de dezoito por cento menor do que minhas execuções com falha, provavelmente porque o modelo não estava gerando prosa de recuperação em torno de suas próprias suposições ruins.

Executei o mesmo prompt no Claude Opus 4.7 em uma segunda sessão, lado a lado. Mesmo resultado, o dobro do custo, ligeiramente mais verboso. Eu sabia qual modelo iria para produção.

Esta é a parte da ferramenta que ganhou meu respeito. Não a descoberta de bugs, que qualquer depurador decente deveria fazer. A comparação de modelos, executada em configurações idênticas com métricas resumidas no painel esquerdo: contagem de turnos, contagem de etapas, tempo, tokens, dólares. Eu estava fazendo essa comparação em uma Planilha Google por seis meses. Agora eram três cliques.

O que eu estava fazendo de errado

A percepção superficial é que o AI Agent Debugger é uma ferramenta de log. Não é. Ferramentas de log mostram o que aconteceu. O depurador mostra o que o modelo e a ferramenta realmente trocaram, o que é uma camada diferente.

Se você escreve agentes e tem feito o que eu estava fazendo, que é ler a saída do modelo e adivinhar a causa das falhas, aqui está o que eu contestaria. Você não está depurando o agente. Você está depurando sua hipótese sobre o agente. São coisas diferentes, e apenas uma delas leva a uma correção.

A coisa que eu me recusava a internalizar por seis meses era que o agente é um sistema fechado entre o modelo, o prompt, as ferramentas e as respostas das ferramentas. O bug sempre vive em um desses quatro. Se você pode ver todos os quatro ao mesmo tempo, você pode encontrar o bug em doze minutos. Se não, você pode persegui-lo por uma semana.

A outra coisa que o depurador revelou, o que eu não esperava, foi o não determinismo em meu próprio agente. Executei o mesmo prompt cinco vezes após a correção, apenas para confirmar. Três execuções chamaram get_response_time uma vez. Duas execuções chamaram duas vezes, a segunda vez com o caminho do endpoint em caixa diferente. Meu esquema de ferramenta era sensível a maiúsculas e minúsculas. Eu não tinha percebido porque meus casos de teste com falha aconteciam de usar minúsculas. Esse foi um segundo bug que eu teria lançado sem ver.

A análise de múltiplas execuções é o recurso que mais usarei daqui para frente. Clique em Executar cinco vezes. Olhe o painel de sessões. Qualquer coisa que varie entre as execuções é um ponto onde seu agente é frágil.

Experimente você mesmo: um passo a passo completo da configuração

Se você quiser a mesma configuração que eu tinha aberta durante a caçada ao bug, aqui está o caminho de uma instalação nova para uma sessão de depuração em execução. Cinco telas, em ordem.

Passo 1: Criar uma nova sessão de depuração de agente

Abra o Apidog e clique em AI Agent Debugger na barra de abas superior. A seção superior da página configura o modelo e o status da execução.

• Escolha o provedor do modelo à esquerda (OpenAI, Anthropic e outros)
• Escolha o modelo específico no meio, por exemplo gpt-5.5
• A URL Base é preenchida automaticamente após a seleção do provedor, sem necessidade de entrada manual
• Clique em Executar para iniciar uma sessão

Passo 2: Configurar os prompts

A aba Prompts possui duas áreas de entrada.

• Prompt do Sistema: define o papel, objetivos, restrições e regras de uso de ferramentas do agente
• Prompt do Usuário: a entrada de teste para esta sessão, por exemplo "O que é Apidog?"

Clique em Executar no canto superior direito quando ambos estiverem configurados. Se você quiser que a caixa de entrada seja limpa automaticamente após cada execução, marque Limpar após Enviar.

Passo 3: Configurar as ferramentas

A aba Ferramentas lista tudo o que o agente pode chamar em tempo de execução. O número na aba é a contagem atual de ferramentas disponíveis ou configuradas.

Ferramentas Integradas vêm com o depurador. Ative-as ou desative-as conforme necessário.

Ferramentas MCP adicionam sistemas externos ou recursos personalizados através de Servidores MCP. Três métodos de conexão:

• STDIO: inicia um processo de Servidor MCP local
• HTTP: conecta-se a um Servidor MCP que suporta HTTP Streamable
• SSE: conecta-se a um Servidor MCP baseado em Server-Sent Events

Servidores MCP que exigem autenticação aceitam cabeçalhos de requisição ou fluxos OAuth 2.0. Assim que a conexão for bem-sucedida, escolha quais ferramentas o servidor expõe ao agente.

Passo 4: Configurar habilidades, autenticação e parâmetros do modelo

Três abas menores completam a configuração.

• Habilidades: fluxos de trabalho reutilizáveis para o agente. Útil para fluxos de trabalho de projeto fixos, especificações de operações de tarefas comuns e redução de texto longo repetitivo em prompts de sistema. As habilidades são carregadas conforme necessário em tempo de execução.

• Autenticação: credenciais exigidas por serviços de modelo ou serviços MCP.
• Configurações: parâmetros de tempo de execução do modelo, como Temperatura, Máximo de Tokens e Top P. Os parâmetros suportados variam por provedor, então verifique o que seu modelo realmente aceita.

Passo 5: Ler os três painéis

Após clicar em Executar, a sessão que você acabou de criar aparece no painel esquerdo. Cada sessão mostra um resumo de uma linha:

Sessão 3
1 turno · 1 etapa · 10s · 3.1k tokens · $0.02
gpt-5.5

• Painel de Sessões (esquerda): histórico de cada execução com métricas de resumo
• Painel de Turnos (meio): cada rodada de diálogo usuário/modelo. Clique em uma rodada para carregar seus detalhes de execução à direita.
• Painel de Rastreamentos (direita): a cadeia de execução completa do agente em ordem, incluindo prompts de sistema e usuário, cada chamada de modelo, o processo de pensamento do modelo (se o modelo o expuser), chamadas de ferramenta MCP e execuções de Habilidades personalizadas, parâmetros de entrada da ferramenta, resultados, tempo consumido, mensagens de erro e a saída final.

Quando uma chamada de ferramenta falha ou o modelo retorna uma exceção, a etapa com falha está ali mesmo no painel de Rastreamentos com suas entradas e saídas visíveis. Sem necessidade de mergulhar em logs.

Passo 6: Comparar o desempenho do modelo

Mesmo prompt, mesma configuração de ferramenta, modelo diferente. Cada execução cria uma nova sessão, e o painel esquerdo permite compará-los lado a lado.

Métricas úteis para comparar:

• Número de etapas de execução para a mesma tarefa
• Qual modelo escolhe as ferramentas com mais precisão
• Qual modelo tem menor tempo de resposta
• Qual modelo mantém o consumo de tokens e o custo mais previsíveis

A conclusão

Dois dias de depuração se resumiram a uma tarde, e eu não aprendi a lição sobre o bug. Eu a aprendi sobre as ferramentas. A razão pela qual eu estava perseguindo a correção errada era que as ferramentas que eu estava usando não me mostravam o que eu precisava ver. Eu tinha uma saída do modelo e uma saída da ferramenta, e nenhum quadro compartilhado para olhá-las juntas. O quadro compartilhado é o ponto principal.

Se você escreveu mais de um agente e ainda não abriu o AI Agent Debugger do Apidog, o próximo agente que você lançar terá um bug que reside entre o modelo e a ferramenta. Você passará uma semana nele. Você escreverá uma página no Notion com hipóteses falhas. O bug estará exatamente onde o depurador teria mostrado a você no primeiro dia.

Baixe o Apidog e abra-o no próximo agente que lhe der uma resposta errada com uma voz confiante. Doze minutos. Quarenta e sete milissegundos, não quarenta e sete segundos.

A referência completa dos recursos, incluindo a configuração de transporte MCP e a disponibilidade do plano, está em Apidog AI Agent Debugger: disponibilidade, cobertura e configuração.