Se você constrói agentes de IA que conversam com outros agentes de IA, o problema aparece rápido: é difícil inspecionar exatamente o que um agente envia para outro. Logs de console omitem contexto, abas de rede nem sempre mostram o payload estruturado com clareza, e scripts de teste personalizados ficam desatualizados. O A2A Debugger do Apidog resolve isso para o protocolo Agent2Agent (A2A): você cola a URL do Cartão de Agente, conecta, envia uma mensagem e analisa a resposta em três visualizações.
Este guia mostra como usar o A2A Debugger na prática: conectar seu primeiro agente, enviar uma mensagem de teste, ler a resposta, configurar autenticação e decidir quando usar cabeçalhos ou metadados. Ele também explica onde essa ferramenta se encaixa ao lado das ferramentas de teste de servidor MCP existentes do Apidog. Se você quiser revisar o contexto dos protocolos antes, leia também o guia do Apidog sobre MCP vs A2A.
O que é A2A
A2A, abreviação de Agent2Agent, é um protocolo aberto para comunicação entre agentes. Ele define como um agente anuncia suas capacidades por meio de um Cartão de Agente, como outro agente se conecta, como mensagens e anexos são trocados e como o status da tarefa é reportado.
Pense no A2A como uma camada de comunicação entre agentes. Um agente LangGraph em um pipeline de dados pode chamar um agente CrewAI mantido por outra equipe sem precisar conhecer sua implementação interna.
Isso é diferente do MCP, o Model Context Protocol. MCP dá a um agente acesso a ferramentas e recursos. A2A permite que agentes conversem com outros agentes. O detalhamento de MCP vs A2A cobre essa diferença em mais detalhes.
O que o A2A Debugger oferece
O A2A Debugger fica dentro do Apidog. Ele fornece uma interface visual para testar endpoints A2A antes de conectá-los a fluxos de produção.
Você pode usar o debugger para:
- Conectar a partir de um Cartão de Agente. Cole a URL, clique em Conectar e veja nome, descrição, capacidades, habilidades declaradas e versão do protocolo.
- Validar o manifesto do agente. Se o Cartão de Agente estiver malformado, a conexão falha de forma explícita.
- Enviar mensagens. Escreva prompts em texto, anexe arquivos quando suportado e inclua metadados por mensagem.
- Inspecionar respostas em três modos. Use Preview, Content e Raw Data para ver a mesma resposta em níveis diferentes.
- Configurar autenticação. Use Bearer Token, Basic Auth ou API Key via cabeçalhos personalizados.
- Adicionar cabeçalhos personalizados. Inclua dados esperados por gateways, proxies ou middleware.
- Consultar histórico da sessão. Cada mensagem enviada fica disponível no log da sessão.
Você não precisa montar comandos curl manualmente. O Apidog lida com o envelope JSON-RPC, com streaming SSE quando suportado pelo agente e com a análise da resposta.
Passo 1: conecte-se ao seu primeiro agente A2A
Antes de abrir o debugger, tenha estes itens:
- Apidog instalado e atualizado. O A2A Debugger está disponível nas versões recentes do cliente. Se necessário, baixe o Apidog.
- URL do Cartão de Agente. Em desenvolvimento local, ela pode ser algo como:
http://localhost:3000/.well-known/agent.json
Para agentes hospedados, use o caminho fornecido pela sua plataforma.
- Credenciais, se exigidas. Por exemplo: Bearer Token, chave de API ou usuário e senha.
Depois disso:
- Abra o Apidog.
- Acesse a página do A2A Debugger.
- Cole a URL do Cartão de Agente no campo superior.
- Configure autenticação, se necessário.
- Clique em Conectar.
Se o agente retornar um Cartão de Agente válido, o status mudará para Conectado e o painel mostrará os metadados do agente.
Se a conexão falhar, verifique:
- A URL está correta?
- O agente está em execução?
- A URL retorna JSON quando aberta no navegador?
- O Cartão de Agente contém os campos obrigatórios?
- O endpoint de descoberta exige autenticação?
Compare o manifesto com a especificação do protocolo A2A no GitHub quando necessário.
Passo 2: envie uma mensagem de teste
Depois de conectar, abra a aba Messages. Envie primeiro uma mensagem pequena e fácil de validar.
Exemplo:
Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.
Antes de clicar em Send, você pode adicionar:
- Arquivo anexado. Use o ícone de clipe. O debugger valida os tipos de entrada declarados pelo agente e rejeita arquivos não suportados antes do envio.
- Metadados personalizados. Adicione pares chave-valor como:
priority: high
tenant: acme-corp
Esses metadados entram no payload da mensagem A2A e ficam disponíveis para o agente, caso o handler leia esses campos.
Depois, clique em Send. O Apidog monta a mensagem no formato esperado pelo A2A, envia para o agente e aguarda a resposta.
Passo 3: leia a resposta em três visualizações
Respostas A2A podem conter texto simples, JSON estruturado, referências a arquivos ou uma combinação desses formatos. O A2A Debugger mostra a resposta em três visualizações.
Preview
Use o Preview para navegar por campos estruturados em formato de árvore. É útil para validar objetos aninhados, como:
- ID da tarefa
- status
- artefatos
- histórico
- partes da resposta
Content
Use Content para ver a saída legível por humanos. Se o agente retornou texto, é aqui que você verá o conteúdo que provavelmente seria exibido ao usuário final.
Raw Data
Use Raw Data para inspecionar o payload JSON-RPC completo. Essa é a melhor visualização para:
- investigar erros;
- comparar a resposta com a especificação;
- copiar payloads para relatórios de bug;
- verificar nomes de campos;
- validar caracteres escapados.
Se o Preview estiver correto, mas o Content estiver vazio, o agente pode estar retornando um artefato estruturado que o Apidog consegue renderizar, mas não consegue converter diretamente em texto.
Se o Raw Data mostrar um erro, comece por error.message.
O histórico da sessão fica no painel esquerdo. Cada envio vira uma entrada que você pode reabrir. Use Clear quando quiser iniciar um novo teste sem contexto antigo interferindo.
Autenticação: três padrões comuns
Endpoints A2A de produção normalmente ficam atrás de algum mecanismo de autenticação. O A2A Debugger suporta os padrões mais comuns.
Bearer Token
Use quando o agente espera um cabeçalho como:
Authorization: Bearer sk-agent-7f3e9a...
No painel de autenticação:
- Selecione Bearer Token.
- Cole o token.
- Envie a requisição.
O Apidog adiciona o cabeçalho em cada chamada.
Basic Auth
Use para agentes protegidos por usuário e senha, comum em sistemas internos ou legados.
No painel de autenticação:
- Selecione Basic Auth.
- Informe usuário e senha.
- O Apidog gera o cabeçalho
Authorization: Basic ...codificado em base64.
Chave de API via cabeçalho personalizado
Use quando o agente espera um cabeçalho não padrão, como:
X-Agent-Key: your-api-key
No Apidog:
- Vá até Headers.
- Adicione o nome do cabeçalho.
- Adicione o valor.
- Envie a mensagem.
O mesmo fluxo vale para cabeçalhos de gateway, tokens CSRF, IDs de tenant e assinaturas de requisição.
Para práticas de longo prazo sobre credenciais, veja o guia de credenciais de agente de IA do Apidog.
Cabeçalhos personalizados vs metadados
Uma requisição A2A pode carregar dados extras em dois lugares: cabeçalhos HTTP ou metadados da mensagem. Eles não têm o mesmo propósito.
| Canal | Onde reside | Use para |
|---|---|---|
| Custom Headers | Cabeçalhos HTTP | Autenticação de gateway, observabilidade, X-Request-Id, feature flags |
| Metadata | Payload da mensagem A2A | Contexto que o agente deve ler, como prioridade, tenant ou localidade |
Regra prática:
- Se o proxy reverso, API gateway ou middleware precisa ler o valor, use Headers.
- Se o handler da tarefa do agente precisa ler o valor, use Metadata.
Esse erro é uma causa comum de bugs como: “por que o agente ignorou meu parâmetro?”.
A2A Debugger vs teste de servidor MCP no Apidog
O Apidog oferece tanto um A2A Debugger quanto um fluxo de teste MCP. Eles resolvem problemas diferentes.
| Ferramenta | Protocolo | Testa | Use quando |
|---|---|---|---|
| A2A Debugger | Agent2Agent | Conectividade, mensagens, status da tarefa | Você está criando sistemas multiagentes em que agentes chamam outros agentes |
| Teste de servidor MCP | Model Context Protocol | Chamadas de ferramentas, acesso a recursos, modelos de prompt | Você está criando um servidor MCP que expõe ferramentas ou recursos para um agente |
Resumo:
- MCP: um agente acessa ferramentas e sistemas externos.
- A2A: um agente conversa com outro agente.
Se ainda estiver em dúvida, leia o guia MCP vs A2A.
Para o lado MCP do fluxo de trabalho, o playbook de teste de servidor MCP cobre caminhos manuais e automatizados no Apidog. Em sistemas reais, é comum usar as duas interfaces: A2A para coordenação entre agentes e MCP para acesso a ferramentas.
Fluxo prático de depuração
Quando o agente não responde como esperado, use este ciclo:
- Abra o A2A Debugger.
- Conecte-se ao agente.
- Confirme se o Cartão de Agente mostra a habilidade esperada.
- Envie a menor mensagem possível que deveria acionar essa habilidade.
- Comece com texto simples.
- Só adicione arquivos e metadados depois que o fluxo básico funcionar.
- Leia primeiro o Raw Data, não o Preview.
- Verifique se a resposta contém os campos esperados.
- Se um campo esperado está ausente, investigue o código do agente.
- Se a resposta está bem formada, mas semanticamente errada, investigue prompt, modelo ou lógica de negócio.
Esse é o mesmo princípio usado em testes de API: isole transporte, contrato e lógica. O post Como testar agentes de IA que chamam suas APIs aplica essa abordagem ao lado das APIs.
Onde o A2A Debugger entra no fluxo de IA
Sistemas multiagentes exigem observabilidade sobre o tráfego entre agentes. O post Agentes de IA são os novos consumidores de API explica por que o tráfego de agentes deve ser tratado como tráfego de primeira classe. O guia Projetando APIs para agentes de IA mostra o que muda quando o consumidor da API é um agente movido a LLM em vez de um desenvolvedor humano.
O A2A Debugger fica na mesma categoria do depurador visual do Cliente MCP do Apidog: ambos expõem tráfego que normalmente fica escondido dentro de SDKs e frameworks.
O resultado é um fluxo mais direto:
- Conecte o agente.
- Envie uma mensagem mínima.
- Leia o payload real.
- Corrija o contrato, a autenticação ou a lógica.
- Só então leve o fluxo para produção.
O Apidog é gratuito para download, e o A2A Debugger vem no cliente padrão, sem licença separada ou plano separado.
Perguntas comuns
O A2A Debugger é gratuito?
Sim. Ele está incluído no cliente Apidog padrão. Baixe o Apidog e verifique se você está usando uma versão recente o suficiente para ver o A2A Debugger no painel lateral.
Funciona com agentes escritos em qualquer framework?
Sim, desde que o agente exponha um Cartão de Agente A2A válido. O protocolo é agnóstico em relação ao framework. Agentes em LangGraph, CrewAI, AutoGen ou implementações personalizadas em Python ou Go podem funcionar se seguirem a especificação A2A.
Posso salvar sessões para reprodução posterior?
As sessões persistem enquanto o debugger está aberto. Para armazenamento de longo prazo, copie a saída em Raw Data e salve-a nos seus artefatos de teste. A exportação completa de sessão está no roadmap.
Como ele lida com respostas de streaming?
Quando o agente suporta streaming SSE conforme a especificação A2A, o debugger lê os pedaços conforme chegam e atualiza Preview e Content em tempo real. O Raw Data mostra a resposta montada quando o stream é encerrado.
Qual é a diferença entre metadados e cabeçalhos?
Cabeçalhos pertencem à camada HTTP. Metadados pertencem à camada da mensagem A2A.
Use cabeçalhos para gateway, proxy e autenticação. Use metadados para contexto que o agente deve processar.
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 testar um agente hospedado em outra rede?
Sim, desde que sua máquina consiga alcançar essa rede. O debugger faz requisições HTTPS de saída como qualquer cliente HTTP. Se o agente estiver atrás de uma VPN, a VPN precisa estar ativa.
Onde posso relatar bugs ou solicitar recursos?
Use o canal de feedback do Apidog para bugs e solicitações da ferramenta. Para mudanças na especificação, use o repositório GitHub do protocolo A2A.
Experimente agora
Escolha o agente A2A mais simples ao qual você tem acesso. Se ainda não tiver um, as implementações de referência A2A incluem um servidor de exemplo que você pode executar localmente.
Depois:
- Abra o A2A Debugger no Apidog.
- Cole a URL do Cartão de Agente.
- Clique em Conectar.
- Envie uma mensagem como
olá. - Compare Preview, Content e Raw Data.
Esse é o menor ciclo ponta a ponta. Depois dele, você pode evoluir para prompts reais, anexos, metadados e fluxos multiagentes.
Combine o debugger com o Apidog para trabalhar com HTTP, MCP e A2A em uma única interface.
Top comments (0)