AI Agent Debugger é uma ferramenta visual de depuração para desenvolvedores de AI Agent.Diferentemente das abordagens de depuração que se concentram apenas na entrada e na saída do modelo, o AI Agent Debugger amplia o escopo da depuração para o processo completo de execução do Agent. Ele exibe claramente cada rodada de diálogo, cada chamada de modelo, chamada de ferramenta MCP, execução de Skill personalizada e saída final, ajudando os desenvolvedores a observar a cadeia operacional do Agent e localizar rapidamente problemas em prompts, configurações de modelo, chamadas de ferramenta ou lógica de negócios.O AI Agent Debugger é aplicável aos seguintes cenários:Depurar cadeias de chamadas de ferramentas de grandes modelos de IA, solucionando problemas de parâmetros de ferramentas, resultados de execução ou causas de exceções
Comparar o desempenho de diferentes modelos executando a mesma tarefa, avaliando métricas-chave como tempo de resposta, consumo de Token e custo
Verificar se a integração do MCP Server com grandes modelos de IA atende às expectativas
Otimizar iterativamente prompts de sistema e observar o impacto de diferentes configurações nos resultados de execução
Recomenda-se usar o cliente Apidog mais recente para experimentar toda a funcionalidade do AI Agent Debugger.
Criar nova sessão de depuração de Agent#
Navegue até AI Agent Debugger pela barra de abas superior no Apidog.A seção superior da página é usada para configurar o modelo e o status de execução:Selecione o provedor do modelo à esquerda, como OpenAI ou Anthropic.
Selecione o modelo no meio, como gpt-5.5
Após selecionar o provedor e o modelo, a Base URL correspondente será correspondida automaticamente, como https://api.openai.com/v1, sem necessidade de entrada manual
Clique em Run para iniciar a depuração
Configurar prompts#
Configure o conteúdo de entrada do Agent na aba Prompts.A página é dividida em duas áreas de entrada:System Prompt: usado para definir a função, os objetivos, as restrições e as regras de uso de ferramentas do Agent, pertencendo à configuração do Agent
User Prompt: usado para preencher a entrada de teste desta sessão, como "What's Apidog?"
Configurar ferramentas#
Na aba Tools, você pode selecionar as ferramentas disponíveis para o Agent chamar durante o runtime. O número na aba indica a quantidade atual de ferramentas disponíveis ou configuradas.As ferramentas são divididas em duas categorias:Ferramentas integradas#
O AI Agent Debugger fornece ferramentas integradas comumente usadas para que grandes modelos de IA leiam arquivos, pesquisem conteúdo, executem comandos ou busquem conteúdo da web.| Ferramenta | Descrição |
|---|
bash | Executar comandos em uma sessão Shell persistente |
web_fetch | Buscar conteúdo da web e convertê-lo em Markdown, texto ou HTML |
read | Ler arquivos de texto, imagem ou PDF |
edit | Realizar substituição precisa de strings em arquivos |
write | Criar ou sobrescrever arquivos |
grep | Pesquisar conteúdo de arquivos usando expressões regulares |
glob | Encontrar arquivos usando padrões glob |
kill_shell | Redefinir a sessão Shell atual |
Você pode habilitar ou desabilitar ferramentas individuais conforme necessário. Quando desabilitada, o Agent não poderá chamar essa ferramenta durante o runtime.Ferramentas MCP#
Se você precisar que o Agent chame sistemas externos ou recursos personalizados, poderá adicionar MCP Servers na aba Tools.O AI Agent Debugger oferece suporte aos seguintes métodos de conexão MCP:STDIO: iniciar um processo local do MCP Server
HTTP: conectar-se a um MCP Server que oferece suporte a Streamable HTTP
SSE: conectar-se a um MCP Server baseado em Server-Sent Events
Configurar Skills#
Na aba Skills, você pode configurar Skills reutilizáveis para o Agent. O número na aba indica a quantidade atual de skills carregadas.Skills são aplicáveis aos seguintes cenários:Fornecer fluxos de trabalho fixos dentro de um projeto para o Agent
Reutilizar especificações de operação para tarefas comuns
Reduzir descrições longas e repetitivas em prompts de sistema
Configurar autenticação e parâmetros do modelo#
Configure as informações de autenticação exigidas por serviços de modelo ou serviços MCP na aba Authentication.Na aba Settings, você pode configurar parâmetros de runtime do modelo, como Temperature, Max Tokens, Top P etc. Diferentes provedores de modelo podem oferecer suporte a parâmetros diferentes; consulte os parâmetros realmente compatíveis com o seu provedor de modelo.Visualizar lista de sessões#
Cada vez que você clicar em Run, um novo registro de sessão será gerado à esquerda.A lista de sessões exibe informações resumidas dessa execução, como:Número de rodadas de diálogo
Número de etapas de execução
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
Visualizar rodadas#
O painel Turns no meio é usado para exibir diálogos de múltiplas rodadas na sessão atual.Quando uma sessão contém várias entradas de usuário, cada rodada será exibida como uma rodada de diálogo independente. Depois de clicar em uma rodada de diálogo, você pode visualizar o processo de chamada correspondente à direita.Visualizar traces#
O painel Traces à direita é usado para exibir o processo completo de execução do Agent.Os traces de chamada são exibidos em ordem de execução, mostrando:Prompts de usuário e prompts de sistema
Processo de raciocínio do modelo (se compatível com o modelo)
Chamadas de ferramentas MCP e execuções de Skill personalizadas
Parâmetros de entrada da ferramenta, resultados de execução, tempo consumido e mensagens de erro
Saída final do grande modelo de IA
Comparar desempenho de modelos#
Você pode usar o mesmo prompt e a mesma configuração de ferramentas para selecionar diferentes modelos para executar tarefas e comparar o desempenho dos modelos por meio da lista de sessões.Os resumos de sessão exibem métricas-chave como tempo de resposta, consumo de Token e custo estimado, ajudando você a avaliar os trade-offs entre diferentes modelos em termos de eficácia, desempenho e custo.Por exemplo, você pode comparar:Se o número de etapas de execução difere para a mesma tarefa em modelos diferentes
Qual modelo consegue selecionar ferramentas com mais precisão
Qual modelo tem menor tempo de resposta
Qual modelo tem consumo de Token e custo mais controláveis
Perguntas frequentes#
O Agent não chamou a ferramenta esperada; como solucionar o problema?#
Verifique as seguintes configurações:1.
Se a ferramenta foi habilitada na aba Tools.
2.
Se o prompt de sistema descreve claramente os cenários de uso da ferramenta.
3.
Se o MCP Server está conectado com sucesso e se a ferramenta de destino não está desabilitada.
4.
Se há processos de raciocínio do modelo ou registros de chamada de ferramenta nos traces de chamada.
5.
Se o grande modelo de IA atualmente usado oferece suporte a chamadas de ferramentas.
O que fazer quando chamadas de ferramentas MCP falham?#
Você pode visualizar chamadas de ferramenta com falha nos traces de chamada, concentrando-se em verificar parâmetros de entrada, resultados de saída e mensagens de erro. Causas comuns incluem:MCP Server não conectado ou conexão desconectada
Formato de parâmetro não atende aos requisitos da ferramenta
Configuração de autenticação OAuth, API Key ou Header incorreta
Comando de inicialização do serviço STDIO local indisponível
O que pode ser avaliado ao executar a mesma tarefa várias vezes?#
Agents são sistemas não determinísticos. O mesmo prompt pode produzir caminhos de execução diferentes em modelos diferentes, parâmetros diferentes ou configurações de ferramentas diferentes. Recomenda-se observar etapas de execução, resultados de chamadas, tempo consumido, consumo de Token e saída final por meio de várias execuções e comparações de sessões, avaliando assim configurações mais adequadas. 