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

Uma tarde de terça-feira. Doze minutos 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.

Experimente o Apidog hoje

Eu estava perseguindo esse bug por dois dias. A cada print adicionado ao servidor MCP, a resposta do agente mudava o suficiente para parecer progresso. A cada ajuste no prompt do sistema, a resposta ficava mais plausível. Mas continuava errada.

O que faltava era abrir o rastreamento real da execução e observar o que estava sendo passado entre o modelo e a ferramenta. É para isso que serve o AI Agent Debugger do Apidog. Eu o havia instalado três semanas antes e esquecido. Levei doze minutos para encontrar o bug.

O bug que eu estava perseguindo

A configuração era simples:

• Um agente construído no GPT-5.5
• Um servidor MCP escrito em um fim de semana
• Uma ferramenta get_response_time(endpoint) que consultava nosso pipeline de métricas
• Um prompt de sistema com cerca de quarenta palavras
• Um prompt de usuário: "Quão rápido é o endpoint /users?"

O agente respondia rápido. Respondia com confiança. E respondia errado.

Exemplos de respostas:

• "O endpoint está respondendo em 47 segundos"
• "Cerca de 0,05 segundos"
• "O desempenho é aceitável"

Eu estava fazendo o fluxo clássico de depuração:

1. Adicionar logs ao servidor MCP
2. Ler a resposta do modelo token por token
3. Alterar o prompt do sistema
4. Comparar hipóteses
5. Repetir

O problema é que, em agentes, o bug raramente está em um único lugar. Ele pode estar em:

• Prompt do sistema
• Escolha do modelo
• Definição da ferramenta
• Parâmetros enviados pelo modelo para a ferramenta
• Dados retornados pela ferramenta
• Interpretação feita pelo modelo

Um console.log mostra uma parte. O rastreamento completo mostra o fluxo inteiro.

O que o painel de rastreamentos mostra

O AI Agent Debugger do Apidog organiza a execução em três colunas:

• Sessões, à esquerda
• Turnos, no centro
• Rastreamentos, à direita

Ao clicar em uma sessão, o painel central mostra o diálogo completo:

• Mensagem do usuário
• Resposta do modelo
• Chamada da ferramenta
• Retorno da ferramenta
• Próxima resposta do modelo

Ao clicar em um turno, o painel direito expande a árvore de execução completa.

A árvore mostra cada passo, em ordem:

• Prompt do sistema como o modelo recebeu
• Prompt do usuário como o modelo recebeu
• Nome e parâmetros da chamada da ferramenta, em JSON
• Payload retornado pela ferramenta, em JSON
• Resposta final do modelo
• Tempo, tokens e demais métricas do turno

Na sessão com falha, a chamada da ferramenta parecia correta:

get_response_time(endpoint="/users")

O modelo havia escolhido a ferramenta certa e enviado o argumento certo.

Então expandi o resultado da ferramenta:

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

O bug estava ali.

O pipeline de métricas retornava o valor em milissegundos. O modelo assumia segundos. 47 virava "47 segundos" porque a unidade não estava explícita.

A ferramenta estava correta. O modelo estava interpretando errado. O prompt de sistema não dizia nada sobre unidades, e a resposta da ferramenta não anotava a unidade.

Doze minutos após abrir o depurador. Dois dias culpando o prompt errado.

A correção levou seis linhas

Corrigi em dois pontos.

Primeiro, atualizei o formato da resposta no servidor MCP:

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

Depois, adicionei uma instrução 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.

As três sessões retornaram corretamente algo como:

O endpoint está respondendo em torno de 47 ms.

Também comparei com Claude Opus 4.7 em uma segunda sessão, usando a mesma configuração. O resultado foi equivalente, com custo maior e resposta um pouco mais verbosa.

Essa comparação foi a parte mais útil: o painel de sessões resume execuções diferentes com métricas como:

• Contagem de turnos
• Contagem de etapas
• Tempo
• Tokens
• Custo estimado

Eu fazia essa comparação manualmente em uma planilha. Agora eram poucos cliques.

O erro no meu processo de depuração

A percepção superficial é achar que o AI Agent Debugger é apenas uma ferramenta de log.

Não é.

Logs mostram o que aconteceu em um ponto específico do sistema. O depurador mostra o que o modelo e as ferramentas trocaram entre si.

Se você depura agentes apenas lendo a saída do modelo e inferindo a causa da falha, você não está depurando o agente. Está depurando sua hipótese sobre o agente.

Um agente é um sistema fechado entre:

1. Modelo
2. Prompt
3. Ferramentas
4. Respostas das ferramentas

O bug quase sempre vive em uma dessas partes ou na fronteira entre elas. Quando você vê as quatro ao mesmo tempo, o problema fica muito mais fácil de isolar.

O depurador também expôs outro problema: não determinismo.

Depois da correção, executei o mesmo prompt cinco vezes:

• Três execuções chamaram get_response_time uma vez
• Duas execuções chamaram a ferramenta duas vezes
• Na segunda chamada, o endpoint vinha com caixa diferente

Meu schema da ferramenta era sensível a maiúsculas e minúsculas. Eu não tinha percebido porque meus testes usavam /users sempre em minúsculas.

Esse era outro bug que provavelmente iria para produção.

Como configurar uma sessão de depuração no Apidog

Se você quiser reproduzir o mesmo fluxo, este é o caminho de uma instalação nova até uma sessão de depuração em execução.

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

Abra o Apidog e clique em AI Agent Debugger na barra superior.

Na seção de configuração:

1. Escolha o provedor do modelo, como OpenAI, Anthropic ou outro
2. Escolha o modelo específico, por exemplo gpt-5.5
3. Verifique a URL Base, preenchida automaticamente após selecionar o provedor
4. Clique em Executar para iniciar a sessão

Passo 2: configurar os prompts

A aba Prompts tem duas áreas principais.

Use Prompt do Sistema para definir:

• Papel do agente
• Objetivo
• Restrições
• Regras de uso das ferramentas
• Regras de interpretação de dados, como unidades, formatos e limites

Use Prompt do Usuário para a entrada de teste da sessão.

Exemplo:

Quão rápido é o endpoint /users?

Depois de configurar ambos, clique em Executar no canto superior direito.

Se quiser limpar a entrada 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 exibido na aba indica quantas ferramentas estão disponíveis ou configuradas.

Ferramentas integradas

As ferramentas integradas vêm com o depurador. Ative apenas o que for necessário para o teste.

Ferramenta	O que ela faz
bash	Executa comandos em uma sessão de shell persistente
web_fetch	Busca conteúdo web e converte para Markdown, texto ou HTML
read	Lê arquivos de texto, imagem ou PDF
edit	Aplica substituições precisas de string em arquivos
write	Cria ou sobrescreve arquivos
grep	Pesquisa conteúdo de arquivos com expressões regulares
glob	Encontra arquivos usando padrões glob
kill_shell	Reinicia a sessão de shell atual

Ferramentas MCP

Ferramentas MCP adicionam sistemas externos ou recursos personalizados por meio de servidores MCP.

Métodos de conexão disponíveis:

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

Servidores MCP que exigem autenticação podem usar cabeçalhos de requisição ou fluxos OAuth 2.0.

Depois que a conexão for bem-sucedida, selecione quais ferramentas o servidor expõe ao agente.

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

Três abas completam a configuração.

Habilidades

Use Habilidades para fluxos de trabalho reutilizáveis do agente.

Elas são úteis para:

• Fluxos fixos do projeto
• Especificações de operações comuns
• Redução de texto repetitivo no prompt do sistema

As habilidades são carregadas conforme necessário em tempo de execução.

Autenticação

Use Autenticação para credenciais exigidas por:

• Serviços de modelo
• Serviços MCP
• APIs externas chamadas pelas ferramentas

Configurações

Use Configurações para parâmetros de execução do modelo, como:

• Temperatura
• Máximo de tokens
• Top P

Os parâmetros suportados variam por provedor. Verifique o que o modelo selecionado realmente aceita.

Passo 5: ler os três painéis

Depois de clicar em Executar, a sessão aparece no painel esquerdo com um resumo.

Exemplo:

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

Use os painéis assim:

• Painel de Sessões, à esquerda: histórico das execuções e métricas resumidas
• Painel de Turnos, no centro: cada rodada de diálogo entre usuário e modelo
• Painel de Rastreamentos, à direita: cadeia completa de execução do agente

O painel de rastreamentos inclui:

• Prompts do sistema e do usuário
• Chamadas ao modelo
• Processo de pensamento, se o modelo expuser
• Chamadas de ferramentas MCP
• Execuções de habilidades personalizadas
• Parâmetros de entrada das ferramentas
• Resultados retornados
• Tempo consumido
• Mensagens de erro
• Saída final

Quando uma chamada de ferramenta falha ou o modelo retorna uma exceção, a etapa com falha aparece diretamente no painel de rastreamentos, com entradas e saídas visíveis.

Passo 6: comparar modelos

Para comparar modelos, mantenha a mesma configuração e altere apenas o modelo.

Execute:

1. Mesmo prompt
2. Mesmas ferramentas
3. Mesmo servidor MCP
4. Modelo diferente

Cada execução cria uma nova sessão no painel esquerdo.

Métricas úteis para comparar:

• Número de etapas para a mesma tarefa
• Precisão na escolha das ferramentas
• Tempo de resposta
• Consumo de tokens
• Custo estimado
• Estabilidade entre execuções repetidas

Esse fluxo ajuda a identificar não só qual modelo responde melhor, mas qual modelo é mais previsível para produção.

Conclusão

Dois dias de depuração se resumiram a uma tarde porque eu finalmente olhei para a fronteira certa: a troca entre modelo e ferramenta.

Eu tinha a saída do modelo. Tinha a saída da ferramenta. Mas não tinha um quadro compartilhado para ver como uma coisa virou a outra.

Esse quadro compartilhado é o ponto principal.

Se você escreveu mais de um agente, é provável que o próximo bug não esteja apenas no prompt ou apenas na ferramenta. Ele estará entre os dois.

Baixe o Apidog e abra o AI Agent Debugger no próximo agente que responder errado com confiança.

Quarenta e sete milissegundos, não quarenta e sete segundos.

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