Se você constrói agentes de IA que conversam com outros agentes de IA, você já se deparou com a mesma dificuldade que todos os outros: não há uma maneira clara de inspecionar o que um agente envia para outro. Os logs do console mentem, as abas de rede escondem os campos estruturados e os scripts de teste personalizados apodrecem rapidamente. O A2A Debugger do Apidog corrige isso para o protocolo Agent2Agent (A2A). Cole uma URL de Cartão de Agente, clique em Conectar, envie uma mensagem e leia a resposta em três visualizações.
Este guia descreve o que o A2A Debugger faz, como conectar seu primeiro agente, como a requisição e a resposta se parecem nos bastidores, e onde ele se encaixa ao lado das ferramentas de teste de servidor MCP existentes do Apidog. Se você precisar do contexto do protocolo upstream primeiro, o Apidog tem uma leitura mais aprofundada sobre MCP vs A2A que combina bem com esta publicação.
O que é A2A (em um parágrafo)
A2A, abreviação de Agent2Agent, é um protocolo aberto para comunicação entre agentes. Ele define como um agente anuncia suas capacidades (o Cartão de Agente), como outro agente se conecta a ele, como mensagens e anexos de arquivos são trocados, e como o status da tarefa é relatado. Pense nisso como HTTP para tráfego entre agentes: uma especificação fina e neutra em relação ao fornecedor que permite que um agente LangGraph em seu pipeline de dados envie um ping para um agente CrewAI de outra equipe sem que nenhum dos lados conheça os detalhes internos do outro.
É distinto do MCP (Model Context Protocol), que se trata de dar a um único agente acesso a ferramentas e recursos. O A2A trata de agentes conversando com outros agentes. O detalhamento de MCP vs A2A é a leitura mais clara sobre a diferença.
O que o A2A Debugger oferece a você
O A2A Debugger reside dentro do Apidog. É um ambiente visual para testar endpoints A2A antes de conectá-los a um fluxo de trabalho de produção. Principais recursos:
- Conexão do Cartão de Agente. Cole uma URL, clique em Conectar, veja o nome do agente, descrição, capacidades, habilidades declaradas e versão do protocolo. Se o cartão estiver malformado, a conexão falha ruidosamente para que você possa corrigir o manifesto em vez de perseguir fantasmas.
- Envio de mensagens. Componha texto simples, anexe arquivos (quando os tipos de entrada declarados do agente os suportam) e adicione pares de chave-valor de metadados personalizados.
- Três visualizações de resposta. O Preview renderiza a saída estruturada, o Content mostra o payload legível por humanos e o Raw Data despeja o JSON completo quando você precisa verificar nomes de campos ou caracteres de escape.
- Autenticação. Bearer Token, Basic Auth e API Key via cabeçalhos personalizados, tudo na UI.
- Cabeçalhos personalizados. Adicione autenticação de gateway, parâmetros de negócios ou qualquer middleware que seu endpoint A2A espere.
- Histórico da sessão. Cada mensagem enviada permanece em um log de sessão. Limpe-o quando iniciar um novo teste.
Você não escreve nenhum comando curl. O Apidog lida com o envelope JSON-RPC, o streaming SSE (onde o agente o suporta) e a análise da resposta.
Passo 1: Conecte-se ao seu primeiro agente A2A
Você precisa de três coisas antes de abrir o debugger:
- Apidog instalado e atualizado. A versão mais recente do cliente é necessária; versões mais antigas não vêm com o A2A Debugger. Baixe o Apidog se você ainda não o tem.
- Uma URL de Cartão de Agente. Este é o ponto de entrada canônico para qualquer agente compatível com A2A. Para desenvolvimento local, geralmente se parece com
http://localhost:3000/.well-known/agent.json; para agentes hospedados, seu fornecedor de plataforma fornecerá o caminho. - Credenciais (se o agente as exigir). Token Bearer, chave de API ou autenticação básica.
Abra o Apidog, vá para a página do A2A Debugger e cole a URL do Cartão de Agente na parte superior. Clique em Conectar. Se o agente responder com um Cartão de Agente válido, o status mudará para Conectado e o painel será preenchido com os metadados do agente: nome, descrição, capacidades, habilidades declaradas, versão do protocolo.
Se falhar, as causas mais comuns são:
- A URL está errada ou o agente não está em execução. Acesse a URL em um navegador para confirmar que um payload JSON é retornado.
- O Cartão de Agente está faltando campos obrigatórios. Compare com a especificação do protocolo A2A no GitHub.
- O agente espera autenticação no endpoint de descoberta. Adicione a autenticação no Apidog antes de clicar em Conectar.
Passo 2: Envie uma mensagem de teste
Uma vez conectado, abra a aba Messages (Mensagens). Digite um prompt como faria em qualquer interface de chat. Por exemplo:
Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.
Adições opcionais antes de clicar em Enviar:
- Anexo de arquivo. Clique no clipe de papel e selecione um arquivo. O debugger verifica os tipos de entrada declarados do agente e rejeita tipos de arquivo não suportados antecipadamente, para que você não perca uma rodada em um 415.
- Metadados personalizados. Adicione pares chave-valor como
priority: highoutenant: acme-corp. Estes fluem para o envelope da requisição A2A e são visíveis para o agente se seu manipulador os ler.
Clique em Send (Enviar). O Apidog envolve seu prompt na estrutura da mensagem A2A, a envia para o agente e aguarda a resposta.
Passo 3: Leia a resposta com três visualizações
As respostas A2A podem ser strings simples, JSON estruturado, referências de arquivos ou uma mistura. O debugger oferece três lentes sobre o mesmo payload:
- Preview. O Apidog renderiza campos estruturados como uma árvore. Útil quando o agente retorna objetos aninhados (ID da tarefa, status, artefatos, histórico).
- Content. O corpo legível por humanos. Se o agente retornou texto, é isso que você mostraria a um usuário. Se retornou um artefato estruturado com uma parte
text/plain, este é o texto extraído. - Raw Data. O payload JSON-RPC completo. É isso que você deve copiar em um relatório de bug quando algo está errado, e o que deve comparar com a especificação ao verificar a conformidade.
Alterne entre os três. Se o Preview parece bom, mas o Content está vazio, o agente provavelmente está retornando um artefato tipado que o Apidog pode renderizar, mas não sabe como nivelar. Se o Raw Data mostra um código de erro, o agente rejeitou a requisição e a mensagem em error.message é seu ponto de partida.
O histórico da sessão fica no painel esquerdo. Cada envio se torna uma virada para a qual você pode rolar para trás. Clique em Clear (Limpar) quando iniciar um novo teste e não quiser que o contexto obsoleto confunda o agente.
Autenticação: três padrões comuns
A maioria dos endpoints A2A de produção está por trás de algum tipo de autenticação. O debugger lida com três padrões logo de cara:
Bearer Token
O padrão mais comum para agentes hospedados. No painel de autenticação, selecione Bearer Token e cole o token. O Apidog adiciona Authorization: Bearer <token> a cada requisição.
Authorization: Bearer sk-agent-7f3e9a...
Basic Auth
Para agentes protegidos por nome de usuário e senha (comum em sistemas internos/legados). Selecione Basic Auth, insira ambos os valores, e o Apidog calcula o cabeçalho Authorization: Basic ... codificado em base64.
Chave de API via cabeçalho personalizado
Quando o agente espera um nome de cabeçalho não padrão, como X-Agent-Key, desça até a seção Headers (Cabeçalhos) e adicione-o manualmente. O mesmo fluxo para qualquer cabeçalho específico do gateway (tokens CSRF, IDs de inquilino, assinaturas de requisição).
Para um pensamento de longo prazo sobre a higiene das credenciais do agente, o guia de credenciais de agente de IA do Apidog cobre o que rotacionar, o que delimitar e o que nunca cometer.
Cabeçalhos personalizados e metadados: quando usar cada um
Dois lugares contêm dados "extras" em uma requisição A2A. Eles parecem semelhantes, mas vão para camadas diferentes:
| Canal | Onde reside | Use para |
|---|---|---|
| Custom Headers | Cabeçalhos de requisição HTTP | Autenticação de gateway, observabilidade (X-Request-Id), feature flags |
| Metadata | Payload da mensagem A2A | Contexto por mensagem que o agente lê (prioridade, inquilino, localidade) |
Regra geral: se seu proxy reverso ou API gateway precisa vê-lo, coloque-o nos cabeçalhos. Se o manipulador de tarefas do agente precisa, coloque-o nos metadados. Confundi-los é a principal fonte de bugs do tipo "por que o agente ignorou minha dica".
A2A Debugger vs. Teste de servidor MCP no Apidog
O Apidog oferece tanto um A2A Debugger quanto um fluxo de teste MCP. São ferramentas diferentes para protocolos diferentes:
| Ferramenta | Protocolo | Testes | Use quando |
|---|---|---|---|
| A2A Debugger | Agent2Agent | Conectividade, troca de mensagens, status da tarefa | Construindo sistemas multiagentes onde agentes chamam outros agentes |
| Teste de servidor MCP | Model Context Protocol | Chamadas de ferramentas, acesso a recursos, modelos de prompt | Construindo um servidor MCP que expõe ferramentas/recursos a um agente |
Se você não tem certeza de qual precisa, o guia MCP vs A2A descreve a decisão. A versão curta: MCP é o que um agente usa para acessar sistemas externos. A2A é o que um agente usa para conversar com outro agente.
Para o lado MCP do fluxo de trabalho, o playbook de teste de servidor MCP aborda caminhos manuais e automatizados no Apidog. Muitas equipes acabam usando ambas as interfaces porque os sistemas de agente do mundo real combinam a coordenação A2A com o acesso a ferramentas MCP.
Um padrão de depuração comum: ida e volta de uma tarefa
Quando você estiver preso com "o agente não está respondendo da maneira que eu espero", siga este ciclo:
- Abra o A2A Debugger.
- Conecte-se ao agente. Confirme se o Cartão de Agente mostra a habilidade que você espera.
- Envie a menor mensagem possível que deveria acionar essa habilidade. Use texto simples primeiro; adicione arquivos e metadados somente depois que o caminho de texto funcionar.
- Leia o Raw Data, não o Preview, na primeira vez. Você quer ver exatamente o que o agente emitiu.
- Se a resposta estiver faltando um campo que você espera, isso é um problema no código do agente, não no transporte.
- Se a resposta estiver bem formada, mas errada, isso é um problema de prompt ou modelo, e você já isolou o transporte da lógica.
Este é o mesmo ciclo de isolamento-antes-da-culpa que o post Como testar agentes de IA que chamam suas APIs aplica ao lado da API. Mesmo princípio: confirme a conexão primeiro, depois depure o cérebro.
Onde ele se encaixa em seu fluxo de trabalho de IA
Sistemas multiagentes são como muito trabalho sério de IA é entregue em 2026. A postagem Agentes de IA são os novos consumidores de API apresenta o caso para tratar o tráfego de agentes como de primeira classe. O acompanhamento Projetando APIs para agentes de IA aborda o que muda em seu contrato de API quando o consumidor é um agente movido a LLM em vez de um desenvolvedor humano.
O A2A Debugger se situa na mesma camada do depurador visual do Cliente MCP do Apidog. Ambos visam fornecer uma janela para o tráfego que, de outra forma, estaria oculto dentro dos SDKs dos agentes. Você conecta seu agente, pode ver o que ele faz e corrigir os bugs antes que cheguem à produção.
O Apidog é gratuito para download e o A2A Debugger vem com o cliente padrão; sem licença separada, sem plano separado.
Perguntas comuns
O A2A Debugger é gratuito?
Sim. Ele é incluído no cliente Apidog padrão. Baixe o Apidog e o A2A Debugger aparecerá no painel lateral, desde que você esteja em uma versão recente o suficiente.
Funciona com agentes escritos em qualquer framework?
Funciona com qualquer agente que exponha um Cartão de Agente A2A válido. O protocolo é agnóstico em relação ao framework, então LangGraph, CrewAI, AutoGen e agentes Python ou Go personalizados funcionam, desde que sigam a especificação A2A.
Posso salvar sessões para reprodução posterior?
As sessões persistem enquanto o depurador está aberto. Para armazenamento de longo prazo, copie a saída Raw Data e salve-a em seus artefatos de teste; a exportação de sessão completa está no roadmap.
Como ele lida com respostas de streaming?
Quando o agente suporta streaming SSE (conforme a especificação A2A), o depurador lê os pedaços à medida que chegam e atualiza o Preview e o Content em tempo real. O Raw Data mostra a resposta montada quando o stream é fechado.
Qual é a diferença entre o campo de metadados e a seção de cabeçalhos?
Cabeçalhos são da camada HTTP; metadados são da camada de mensagem A2A. Cabeçalhos alcançam o gateway e o proxy reverso; metadados alcançam o manipulador de tarefas do agente. Consulte a tabela anterior nesta postagem.
O Apidog registra as respostas do agente em seus servidores?
Não. O Apidog opera como um cliente local. O tráfego entre sua máquina e o agente não passa pela infraestrutura do Apidog.
Posso usar o A2A Debugger para testar um agente hospedado em uma rede diferente?
Sim, desde que o caminho da rede esteja aberto. O depurador faz requisições HTTPS de saída como qualquer cliente HTTP faria. Se seu agente estiver atrás de uma VPN, você precisará ter essa VPN ativa.
Onde posso relatar bugs ou solicitar recursos?
O canal de feedback do Apidog é a rota principal; o repositório GitHub do protocolo A2A é onde a especificação upstream evolui, então as requisições de nível de especificação pertencem lá.
Experimente agora
Escolha o agente A2A mais simples que você tiver acesso. Se ainda não tiver um, as implementações de referência A2A incluem um servidor de exemplo que você pode executar localmente em menos de cinco minutos. Cole a URL do Cartão de Agente no A2A Debugger do Apidog, envie uma mensagem "olá" e observe as três visualizações de resposta serem preenchidas. Este é o menor ciclo ponta a ponta, e a partir daí você pode escalar para prompts reais, anexos de arquivos e fluxos de trabalho multiagente.
Combine o depurador com o Apidog para o restante do seu trabalho com APIs e MCP, e você terá uma única interface para os três protocolos em que os sistemas de agente são executados: HTTP, MCP e A2A.