O Depurador de Agentes de IA é uma ferramenta visual de depuração para programadores de Agentes de IA.Ao contrário das abordagens de depuração que se concentram apenas na entrada e na saída do modelo, o Depurador de Agentes de IA alarga o âmbito da depuração ao processo completo de execução do Agente. Apresenta claramente cada ronda de diálogo, cada chamada ao modelo, chamada a ferramentas MCP, execução de Skills personalizadas e saída final, ajudando os programadores a observar a cadeia operacional do Agente e a localizar rapidamente problemas em prompts, configurações do modelo, chamadas a ferramentas ou lógica de negócio.O Depurador de Agentes de IA é aplicável aos seguintes cenários:Depurar cadeias de chamadas a ferramentas de grandes modelos de IA, resolver problemas de parâmetros de ferramentas, resultados de execução ou causas de exceções
Comparar o desempenho de diferentes modelos ao executar a mesma tarefa, avaliando métricas-chave como tempo de resposta, consumo de Tokens e custo
Verificar se a integração de MCP Server com grandes modelos de IA corresponde às expectativas
Otimizar iterativamente prompts de sistema e observar o impacto de diferentes configurações nos resultados de execução
Recomenda-se utilizar o cliente Apidog mais recente para experienciar toda a funcionalidade do Depurador de Agentes de IA.
Criar uma Nova Sessão de Depuração de Agente#
Navegue para Depurador de Agentes de IA a partir da barra de separadores superior no Apidog.A secção superior da página é utilizada para configurar o modelo e o estado de execução:Selecione o fornecedor do modelo à esquerda, como OpenAI ou Anthropic.
Selecione o modelo no centro, como gpt-5.5
Depois de selecionar o fornecedor e o modelo, o Base URL correspondente será automaticamente associado, como https://api.openai.com/v1, sem necessidade de introdução manual
Clique em Executar para iniciar a depuração
Configurar Prompts#
Configure o conteúdo de entrada do Agente no separador Prompts.A página está dividida em duas áreas de entrada:Prompt de Sistema: utilizado para definir o papel, os objetivos, as restrições e as regras de utilização de ferramentas do Agente, pertencendo à configuração do Agente
Prompt do Utilizador: utilizado para preencher a entrada de teste desta sessão, como "O que é o Apidog?"
Configurar Ferramentas#
No separador Tools, pode selecionar as ferramentas disponíveis para o Agente chamar durante a execução. O número no separador indica o número atual de ferramentas disponíveis ou configuradas.As ferramentas estão divididas em duas categorias:Ferramentas Integradas#
O Depurador de Agentes de IA fornece ferramentas integradas comummente utilizadas para grandes modelos de IA lerem ficheiros, pesquisarem conteúdo, executarem comandos ou obterem conteúdo da Web.| Ferramenta | Descrição |
|---|
bash | Executar comandos numa sessão Shell persistente |
web_fetch | Obter conteúdo da Web e convertê-lo para Markdown, texto ou HTML |
read | Ler ficheiros de texto, imagem ou PDF |
edit | Efetuar substituição precisa de cadeias de caracteres em ficheiros |
write | Criar ou substituir ficheiros |
grep | Pesquisar conteúdo de ficheiros utilizando expressões regulares |
glob | Encontrar ficheiros utilizando padrões glob |
kill_shell | Repor a sessão Shell atual |
Pode ativar ou desativar ferramentas individuais conforme necessário. Quando estiver desativada, o Agente não poderá chamar essa ferramenta durante a execução.Ferramentas MCP#
Se precisar que o Agente chame sistemas externos ou capacidades personalizadas, pode adicionar MCP Servers no separador Tools.O Depurador de Agentes de IA suporta os seguintes métodos de ligação MCP:STDIO: iniciar um processo local de MCP Server
HTTP: ligar a um MCP Server que suporte Streamable HTTP
SSE: ligar a um MCP Server baseado em Server-Sent Events
Configurar Skills#
No separador Skills, pode configurar Skills reutilizáveis para o Agente. O número no separador indica o número atual de skills carregadas.As Skills são aplicáveis aos seguintes cenários:Fornecer fluxos de trabalho fixos dentro de um projeto para o Agente
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 pelos serviços de modelo ou serviços MCP no separador Authentication.No separador Settings, pode configurar parâmetros de execução do modelo, como Temperature, Max Tokens, Top P, etc. Diferentes fornecedores de modelos podem suportar parâmetros diferentes; consulte os parâmetros efetivamente suportados pelo seu fornecedor de modelo.Ver Lista de Sessões#
Sempre que clicar em Executar, será gerado um novo registo de sessão à esquerda.A lista de sessões apresenta informações de resumo dessa execução, tais como:Número de rondas de diálogo
Número de passos de execução
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
Ver Rondas#
O painel Rondas, no centro, é utilizado para apresentar diálogos de várias rondas na sessão atual.Quando uma sessão contém várias entradas do utilizador, cada ronda será apresentada como uma ronda de diálogo independente. Depois de clicar numa ronda de diálogo, pode ver o processo de chamada correspondente à direita.Ver Rastreios#
O painel Rastreios, à direita, é utilizado para apresentar o processo completo de execução do Agente.Os rastreios de chamadas são apresentados por ordem de execução, mostrando:Prompts do utilizador e prompts de sistema
Processo de raciocínio do modelo (se suportado pelo modelo)
Chamadas a ferramentas MCP e execuções de Skills personalizadas
Parâmetros de entrada das ferramentas, resultados de execução, tempo consumido e mensagens de erro
Saída final do grande modelo de IA
Comparar o Desempenho de Modelos#
Pode utilizar a mesma configuração de prompt e ferramentas para selecionar diferentes modelos para executar tarefas e comparar o desempenho dos modelos através da lista de sessões.Os resumos de sessão apresentam métricas-chave, como tempo de resposta, consumo de Tokens e custo estimado, ajudando-o a avaliar os compromissos entre diferentes modelos em termos de eficácia, desempenho e custo.Por exemplo, pode comparar:Se o número de passos de execução difere para a mesma tarefa em modelos diferentes
Que modelo consegue selecionar ferramentas com maior precisão
Que modelo tem menor tempo de resposta
Que modelo tem consumo de Tokens e custo mais controláveis
FAQ#
O Agente não chamou a ferramenta esperada; como resolver o problema?#
Verifique as seguintes configurações:1.
Se a ferramenta foi ativada no separador Tools.
2.
Se o prompt de sistema descreve claramente os cenários de utilização da ferramenta.
3.
Se o MCP Server está ligado com sucesso e a ferramenta-alvo não está desativada.
4.
Se existem processos de raciocínio do modelo ou registos de chamadas a ferramentas nos rastreios de chamadas.
5.
Se o grande modelo de IA atualmente utilizado suporta chamadas a ferramentas.
O que fazer quando as chamadas a ferramentas MCP falham?#
Pode ver chamadas a ferramentas falhadas nos rastreios de chamadas, concentrando-se na verificação dos parâmetros de entrada, resultados de saída e mensagens de erro. As causas comuns incluem:MCP Server não ligado ou ligação interrompida
O formato dos parâmetros não cumpre os requisitos da ferramenta
Configuração incorreta de autenticação OAuth, API Key ou cabeçalho
Comando de arranque do serviço STDIO local indisponível
O que pode ser avaliado ao executar a mesma tarefa várias vezes?#
Os Agentes são sistemas não determinísticos. O mesmo prompt pode produzir diferentes caminhos de execução com modelos diferentes, parâmetros diferentes ou configurações de ferramentas diferentes. Recomenda-se observar passos de execução, resultados de chamadas, tempo consumido, consumo de Tokens e saída final através de várias execuções e comparações de sessões, avaliando assim configurações mais adequadas. 