Apidog AI Agent Debugger: Disponibilidade, Cobertura e Configuração

O Depurador de Agente de IA do Apidog está disponível na versão mais recente do cliente Apidog em todos os planos, incluindo o Gratuito. Com ele, você pode executar agentes de IA usando modelos OpenAI e Anthropic, conectar servidores MCP, inspecionar cada chamada de modelo e invocação de ferramenta no painel de Rastros e acompanhar o custo estimado por execução.

Experimente o Apidog hoje

Este guia mostra como usar o Depurador de Agente de IA na prática: quais provedores são suportados, como conectar servidores MCP, como iniciar uma execução e quais limitações considerar antes de integrá-lo ao seu fluxo de desenvolvimento.

O que está disponível

O Depurador de Agente de IA vem no cliente Apidog padrão. Não há licença separada, plano adicional ou taxa por usuário.

Disponibilidade:

• Planos Gratuito, Básico, Profissional e Empresarial incluem o Depurador de Agente de IA.
• O recurso é habilitado por padrão.
• Você precisa estar na versão mais recente do cliente Apidog.
• Clientes antigos podem não exibir a aba Depurador de Agente de IA.

Provedores de modelo suportados

Provedor	Status	Modelos
OpenAI	Suportado	GPT-5.5, GPT-5.5 Instant, série o e qualquer modelo disponível na conta OpenAI
Anthropic	Suportado	Claude 4.7 Sonnet, Claude 4.7 Opus, Claude 4.7 Haiku
Endpoints personalizados compatíveis com OpenAI	Suportado via substituição de URL Base	Qualquer provedor que exponha uma API compatível com OpenAI
Outros provedores, como Google, Mistral e xAI	No roteiro	Atualmente não são de primeira classe

Como configurar um provedor de modelo

No Depurador de Agente de IA:

1. Abra a aba Depurador de Agente de IA no Apidog.
2. Selecione o provedor, como OpenAI ou Anthropic.
3. Escolha o modelo.
4. Confirme a URL Base preenchida automaticamente.
5. Se estiver usando um endpoint compatível com OpenAI, substitua a URL Base pelo endpoint do seu provedor.
6. Cole sua chave de API.
7. Execute um thread vazio para validar a conexão.

Exemplo conceitual de configuração para um endpoint compatível com OpenAI:

Provedor: OpenAI-compatible
URL Base: https://api.seu-provedor.com/v1
API Key: sk-...
Modelo: nome-do-modelo

Use essa opção quando o provedor expõe uma API compatível com OpenAI, mas não aparece como provedor nativo no Apidog.

Métodos de conexão com servidor MCP

O depurador se comunica nativamente com o Protocolo de Contexto de Modelo, ou MCP. Três transportes são suportados:

• STDIO: executa um subprocesso local. É útil para servidores MCP em desenvolvimento ativo.
• HTTP Streamable: conecta servidores MCP hospedados acessíveis via HTTP.
• SSE: usa Eventos Enviados pelo Servidor. Ainda é suportado para compatibilidade retroativa.

A autenticação para servidores MCP cobre dois padrões:

• Cabeçalhos padrão, como chave de API.
• OAuth 2.0 com troca completa de token.

Exemplo de fluxo para depurar um agente

Um fluxo básico de depuração fica assim:

1. Configure o provedor de modelo.
2. Adicione um servidor MCP, se o agente precisar de ferramentas externas.
3. Defina o prompt ou cenário de execução.
4. Clique em Executar.
5. Abra o painel de Rastros.
6. Inspecione:
   • chamadas de modelo;
   • parâmetros enviados;
   • respostas recebidas;
   • ferramentas invocadas;
   • dados retornados pelas ferramentas;
   • tokens usados;
   • custo estimado.

Esse fluxo ajuda a responder perguntas como:

• O modelo recebeu o contexto correto?
• A ferramenta certa foi chamada?
• Os parâmetros foram montados corretamente?
• O servidor MCP retornou o dado esperado?
• O custo da execução está dentro do esperado?

O que o depurador captura

O depurador captura a cadeia completa de execução de um agente:

• Chamadas de modelo com payloads completos de solicitação e resposta.
• Rastros de pensamento do modelo quando o modelo os expõe, como série o da OpenAI e pensamento estendido da Anthropic.
• Invocações de ferramentas com valores de parâmetros e dados de retorno.
• Tráfego do servidor MCP, listado no painel de Rastros como qualquer outra chamada de ferramenta.
• Ferramentas integradas:
  • bash
  • web_fetch
  • read
  • edit
  • write
  • grep
  • glob
  • kill_shell
• Métricas por execução:
  • tempo de resposta;
  • tokens de entrada;
  • tokens de saída;
  • custo estimado.
• Habilidades, ou seja, pacotes salvos com prompt do sistema, lista de ferramentas e parâmetros para reexecutar um cenário.

Como usar Rastros para diagnosticar problemas

Durante uma execução, use o painel de Rastros como uma linha do tempo técnica da execução do agente.

Verifique cada etapa:

1. Entrada do modelo
   
   Confirme se o prompt, o contexto e as instruções do sistema estão corretos.

2. Resposta do modelo
   
   Veja se o modelo decidiu chamar uma ferramenta ou responder diretamente.

3. Invocação de ferramenta
   
   Analise os parâmetros enviados. Erros comuns aparecem aqui, como IDs incorretos, filtros inválidos ou campos ausentes.

4. Resposta da ferramenta
   
   Confirme se o servidor MCP ou ferramenta integrada retornou o dado esperado.

5. Resposta final
   
   Compare a saída final com o objetivo da execução.

Esse processo é útil para iterar rapidamente em prompts, ferramentas e servidores MCP sem precisar adicionar logs manuais em cada etapa.

O que o depurador não cobre

O Depurador de Agente de IA não substitui ferramentas específicas para outros cenários:

• Observabilidade em produção
  
  Para registro de tráfego de longo prazo, use uma ferramenta dedicada de observabilidade.

• Teste de regressão automatizado
  
  Para grades de prompts contra fixtures, use uma estrutura como Promptfoo.

• Tráfego Agente-para-Agente, ou A2A
  
  Para A2A, use o Depurador A2A separado do Apidog.

• Validação isolada de servidor MCP
  
  Para testar ferramentas e recursos de um único servidor MCP sem loop de agente, use o fluxo de teste de servidor MCP do Apidog.

Como habilitar o Depurador de Agente de IA

Não há configuração em nível de projeto. O depurador roda em seu próprio espaço de trabalho.

Para começar:

1. Atualize o Apidog para a versão mais recente.
2. Abra o Apidog.
3. Clique em Depurador de Agente de IA na barra de abas superior.
4. Selecione um provedor de modelo.
5. Selecione um modelo.
6. Confirme a URL Base ou substitua por um endpoint personalizado.
7. Cole sua chave de API.
8. Clique em Executar em um thread vazio para confirmar a conexão.

Depois disso, você pode adicionar prompts, ferramentas e servidores MCP conforme o cenário que deseja depurar.

O que permanece igual nos projetos existentes

O uso do Depurador de Agente de IA não altera seus projetos Apidog existentes.

Permanece igual:

• Projetos Apidog existentes.
• Definições de API.
• Suítes de teste.
• Fluxo de teste de servidor MCP.
• Depurador A2A.
• Depuração de endpoints de API.
• Servidores mock.
• Edição OpenAPI.
• Faturamento e níveis de plano.

O Depurador de Agente de IA não consome novos créditos do Apidog.

Você paga pelas chamadas de API do modelo subjacente de acordo com o faturamento da sua conta OpenAI ou Anthropic. O Apidog não cobra sobretaxa pelo uso.

Para administradores de Equipes e Empresas

Em ambientes de equipe, considere estes pontos antes de liberar o uso:

• O Depurador de Agente de IA é habilitado por usuário.
• Cada membro usa sua própria chave de API do provedor.
• As chaves de API inseridas no depurador são armazenadas localmente no cliente de cada usuário.
• As chaves não são transmitidas para os servidores Apidog.
• Proprietários de espaços de trabalho podem gerenciar endpoints compartilhados de servidor MCP usando variáveis de ambiente padrão do Apidog.
• Controles de auditoria e acesso para servidores MCP seguem o modelo de autenticação do próprio servidor MCP, como cabeçalhos ou OAuth 2.0.

Limitações conhecidas

Antes de adotar o depurador no fluxo diário, considere as limitações atuais:

• A expansão de provedores além de OpenAI e Anthropic está no roteiro.
• Enquanto isso, use substituição de URL Base para provedores compatíveis com OpenAI.
• O compartilhamento de rastros é apenas local.
• Para compartilhar um rastro, copie o JSON da visualização Raw ou tire uma captura de tela do painel.
• A estimativa de custo é uma aproximação local baseada nos preços publicados do modelo.
• Para faturamento real, consulte o painel de uso do seu provedor.

Checklist rápido

Use este checklist para validar sua primeira execução:

• [ ] Apidog atualizado para a versão mais recente.
• [ ] Aba Depurador de Agente de IA disponível.
• [ ] Provedor de modelo selecionado.
• [ ] Modelo selecionado.
• [ ] URL Base confirmada ou substituída.
• [ ] Chave de API inserida.
• [ ] Servidor MCP conectado, se necessário.
• [ ] Execução iniciada.
• [ ] Rastros revisados.
• [ ] Custo estimado conferido.