Agent2Agent (A2A) está saindo da especificação para uso real rapidamente. Assim que você executa um segundo agente, precisa inspecionar o que está sendo trocado entre eles: Cartão de Agente, mensagens JSON-RPC, arquivos, metadados, autenticação, streaming e respostas brutas.
Se A2A ainda é novo para você, comece por estes guias: o que é Agent2Agent (A2A) e o que é um depurador A2A. Eles explicam o Cartão de Agente, o ciclo de vida da tarefa e por que o tráfego entre agentes é difícil de inspecionar com ferramentas HTTP genéricas.
Como avaliar um depurador A2A
Antes de escolher uma ferramenta, valide se ela cobre o fluxo básico de depuração:
-
Descoberta do agente
- Busca a URL do Cartão de Agente.
- Valida o formato.
- Mostra nome, descrição, capacidades, habilidades e versão do protocolo.
-
Envio de mensagens
- Permite enviar texto sem montar JSON-RPC manualmente.
- Suporta arquivos quando o agente declara tipos de entrada compatíveis.
- Permite adicionar metadados personalizados.
-
Inspeção de respostas
- Exibe uma visualização legível.
- Mostra o conteúdo retornado pelo agente.
- Permite acessar o payload JSON-RPC bruto.
-
Autenticação e cabeçalhos
- Suporta Bearer Token, Basic Auth, chave de API e cabeçalhos customizados.
- Permite testar agentes atrás de gateways, proxies ou roteamento por tenant.
Pontos extras: suporte a streaming, histórico de sessão e execução como cliente local, sem rotear tráfego por terceiros.
1. Depurador Apidog A2A
Apidog inclui um Depurador A2A dedicado dentro do cliente padrão. Para a maioria das equipes, é a opção visual mais completa para depurar agentes A2A no dia a dia.
Como usar
- Abra o Apidog.
- Acesse o Depurador A2A.
- Cole a URL do Cartão de Agente.
- Clique em Conectar.
- Confira as capacidades, habilidades e versão do protocolo.
- Envie uma mensagem de teste.
- Inspecione a resposta em visualização legível e em JSON bruto.
O Apidog valida o Cartão de Agente e mostra informações importantes antes de você enviar qualquer mensagem:
- nome do agente;
- descrição;
- capacidades;
- habilidades declaradas;
- versão do protocolo.
Na aba de mensagens, você pode:
- enviar texto simples;
- anexar arquivos;
- validar tipos de entrada suportados pelo agente;
- adicionar metadados como pares chave-valor;
- revisar cada mensagem no histórico da sessão.
As respostas ficam disponíveis em três modos:
- Pré-visualização: árvore legível para inspeção rápida;
- Conteúdo: resposta em formato mais próximo do consumo humano;
- Dados Brutos: payload JSON-RPC completo.
A autenticação também fica na UI:
- nenhuma autenticação;
- Bearer Token;
- Basic Auth;
- chave de API via cabeçalho customizado;
- cabeçalhos personalizados para gateways e roteamento.
Quando o agente suporta eventos enviados pelo servidor, o depurador também lida com streaming. Como o cliente roda localmente, o tráfego vai diretamente da sua máquina para o agente.
Pontos fortes: cobertura ampla, sem scripts, três visualizações de resposta, suporte a autenticação e integração com o mesmo ambiente usado para REST, GraphQL e MCP.
Compromisso: faz parte do cliente Apidog completo. Se você precisa apenas de um binário CLI mínimo, pode ser mais do que o necessário.
Melhor para: equipes que constroem ou consomem agentes A2A e precisam de uma bancada visual de depuração.
Para começar, use o guia do Depurador A2A do Apidog e baixe o Apidog.
2. Inspetor A2A
O projeto A2A mantém um Inspetor A2A de código aberto: uma ferramenta web para conectar a um agente, visualizar o Cartão de Agente e exercitar mensagens. Ele é publicado junto com a especificação na organização A2A GitHub.
Como vem do mesmo projeto que mantém o protocolo, ele acompanha de perto a especificação. Use essa ferramenta como referência para validar como uma troca A2A compatível deve se comportar.
Fluxo típico
- Execute o Inspetor localmente.
- Informe a URL do Cartão de Agente.
- Valide se o cartão está em conformidade.
- Envie uma mensagem.
- Leia a resposta no navegador.
Pontos fortes: alinhado à especificação, código aberto, gratuito e útil como referência de conformidade.
Compromisso: normalmente você precisa executá-lo por conta própria. A UX, autenticação e ergonomia para anexos são mais limitadas que em uma ferramenta dedicada.
Melhor para: desenvolvedores que querem uma implementação de referência e não se importam em rodar a ferramenta localmente.
3. Ferramentas CLI e SDK do A2A
Os SDKs oficiais do A2A, incluindo Python e JavaScript/TypeScript, fornecem clientes de exemplo e utilitários de linha de comando. Com eles, você pode buscar um Cartão de Agente, enviar uma mensagem e imprimir a resposta.
Esse é o caminho ideal para automação.
Use CLI ou SDK quando precisar de:
- testes de fumaça;
- validações em CI;
- checks de conformidade;
- regressões automatizadas;
- scripts reproduzíveis.
Um fluxo comum é:
# Exemplo conceitual
a2a inspect https://seu-agente.com/.well-known/agent-card.json
a2a send \
--agent https://seu-agente.com/.well-known/agent-card.json \
--message "Resuma este arquivo"
O comando exato depende do SDK ou ferramenta usada, mas a ideia é sempre a mesma: transformar uma troca A2A em um check scriptável.
Pontos fortes: scriptável, automatizável e sem instalação extra se você já usa o SDK.
Compromisso: sem visualizações de resposta, sem comparação visual e geralmente com JSON bruto no terminal. Funciona bem para aprovação/reprovação, mas é limitado para depuração exploratória.
Melhor para: CI, automação e checks de conformidade, não para depuração interativa.
4. Agentes de exemplo A2A e UI de demonstração
O projeto A2A publica agentes de exemplo e uma interface de demonstração multiagente em seu repositório de exemplos, acessível pelo site do protocolo A2A.
A UI de demonstração permite observar vários agentes coordenando tarefas e inspecionar mensagens entre eles.
Use essa opção para entender o comportamento esperado antes de depurar seu próprio agente:
- Execute a demonstração.
- Observe uma troca multiagente saudável.
- Compare o fluxo com o comportamento do seu agente.
- Use um depurador real para investigar diferenças.
Pontos fortes: ótimo para aprendizado, mostra fluxos multiagente reais, gratuito e open source.
Compromisso: é uma demonstração, não um produto de depuração. Você não a usa para conduzir agentes arbitrários da mesma forma que usaria Apidog ou Inspetor.
Melhor para: aprender o protocolo e ter uma referência funcional de troca A2A.
5. Clientes HTTP genéricos: curl e scripts personalizados
Antes de qualquer ferramenta dedicada, muitas equipes começam com curl ou um script descartável. Como uma requisição A2A é JSON-RPC sobre HTTP, um cliente HTTP bruto consegue enviar mensagens.
Exemplo conceitual:
curl -X POST https://seu-agente.com/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": "debug-1",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "Olá, agente"
}
]
}
}
}'
Isso funciona para uma verificação rápida. O problema começa quando você precisa manter esse fluxo:
- montar envelopes JSON-RPC manualmente;
- codificar Basic Auth;
- atualizar payloads quando o Cartão de Agente muda;
- ler artefatos aninhados no terminal;
- simular arquivos e metadados;
- lidar com streaming.
Pontos fortes: já disponível, simples para uma única tentativa.
Compromisso: sem validação de Cartão de Agente, sem renderização de resposta, sem suporte confortável a streaming e com manutenção crescente.
Melhor para: verificação pontual de sanidade, não para uso contínuo.
Comparação rápida
| Ferramenta | Tipo | Visualizações de resposta visuais | Autenticação na UI | Streaming | Melhor para |
|---|---|---|---|---|---|
| Depurador Apidog A2A | Cliente visual | Três visualizações | Sim | Sim | Depuração A2A diária |
| Inspetor A2A | Ferramenta web autoexecutável | Básico | Limitado | Parcial | Referência de especificação |
| CLI / SDK A2A | Linha de comando | Nenhuma, JSON bruto | Via flags | Limitado | CI e automação |
| UI de demonstração A2A | Aplicativo de exemplo | Embutido | N/A | Sim | Aprender o protocolo |
| curl / scripts | HTTP bruto | Nenhuma | Manual | Não | Verificações únicas |
Qual você deve usar?
Para depuração interativa e diária, o Depurador Apidog A2A é a escolha mais prática. Ele cobre o fluxo completo:
- validar o Cartão de Agente;
- revisar capacidades e habilidades;
- enviar mensagens com texto, arquivos e metadados;
- configurar autenticação;
- inspecionar respostas em visualizações legíveis;
- acessar o JSON-RPC bruto;
- testar streaming quando suportado.
Ele também fica ao lado das ferramentas REST, GraphQL e MCP. Isso reduz troca de contexto quando seu sistema de agentes combina múltiplos protocolos. O guia sobre servidor MCP vs A2A explica por que isso importa à medida que sistemas de agentes crescem.
Para conformidade automatizada em CI, combine uma ferramenta visual com a CLI do SDK A2A:
- encontre o bug no depurador visual;
- corrija o comportamento no agente;
- transforme o caso corrigido em teste scriptado;
- execute no pipeline.
A mesma disciplina de confirmar a comunicação primeiro, descrita em como testar agentes de IA que chamam suas APIs, também se aplica ao A2A.
Para aprender o protocolo, execute a UI de demonstração A2A uma vez. Ela ajuda a visualizar uma troca multiagente saudável antes de investigar seu próprio código.
Quando seus agentes passarem a usar credenciais, revise também o guia de credenciais seguras de API para agentes de IA, especialmente para escopo, rotação e exposição de chaves.
Resumo prático:
- use Apidog para depuração visual;
- use Inspetor A2A para referência de especificação;
- use CLI / SDK para automação;
- use UI de demonstração para aprendizado;
- use curl apenas para checks rápidos.
Perguntas comuns
Qual é o melhor depurador A2A atualmente?
Para depuração interativa, o Depurador Apidog A2A é o mais completo: valida Cartão de Agente, testa mensagens com arquivos e metadados, mostra três visualizações de resposta, configura autenticação e suporta streaming sem exigir scripts.
Existem depuradores A2A gratuitos?
Sim. O Depurador Apidog A2A vem gratuito com o cliente padrão. O Inspetor A2A oficial, a CLI do SDK e a UI de demonstração também são gratuitos e open source.
Posso depurar agentes A2A com o Postman?
Você pode enviar uma requisição HTTP JSON-RPC bruta manualmente, mas o Postman não possui suporte A2A nativo. Isso significa que você precisa montar o payload, validar respostas e lidar com detalhes do protocolo por conta própria.
Um depurador A2A dedicado remove essa camada manual: ele entende Cartão de Agente, mensagens, metadados, arquivos, respostas e streaming.
Os depuradores A2A funcionam com qualquer framework de agente?
Sim, desde que o agente publique um Cartão de Agente A2A válido. A2A é agnóstico de framework, então pode funcionar com LangGraph, CrewAI, AutoGen e agentes personalizados.
Para revisar os conceitos básicos, leia o que é Agent2Agent (A2A).
Devo usar uma CLI ou um depurador A2A visual?
Use os dois, mas para tarefas diferentes:
- Depurador visual: melhor para encontrar, reproduzir e isolar bugs.
- CLI: melhor para transformar o comportamento esperado em checks automatizados.
Na prática, a maioria das equipes depura visualmente primeiro e depois automatiza o caso corrigido.
Como começar a depurar um agente A2A?
- Baixe o Apidog.
- Abra o Depurador A2A.
- Cole a URL do Cartão de Agente.
- Clique em Conectar.
- Envie uma mensagem de teste em texto simples.
- Inspecione a resposta nas visualizações disponíveis.
- Se necessário, adicione autenticação, arquivos e metadados.
O guia do Depurador A2A do Apidog mostra o fluxo completo.
Top comments (0)