O Que é um Depurador Agente2Agente (A2A) e Por Que Você Precisa de Um

Você construiu um agente A2A. Ele conecta, responde e, às vezes, retorna a coisa errada. O próximo passo não deve ser adivinhar pelo console: você precisa ver o Agent Card, a mensagem enviada, o envelope JSON-RPC e a resposta completa. É exatamente para isso que serve um Depurador Agent2Agent (A2A).

Experimente o Apidog hoje

Este artigo mostra como usar um depurador A2A para testar agentes, isolar erros de transporte e inspecionar respostas sem escrever um cliente do zero. Se você precisa revisar o protocolo antes, comece por o que é Agent2Agent A2A.

O que é um depurador A2A?

Um depurador A2A é uma ferramenta para conectar-se a um agente Agent2Agent, enviar mensagens de teste e inspecionar a requisição e a resposta completas sem escrever código cliente.

Na prática, ele funciona como um cliente manual para agentes:

1. Você informa a URL do Agent Card.
2. O depurador carrega e valida os metadados do agente.
3. Você envia uma mensagem de teste.
4. A ferramenta monta o envelope A2A/JSON-RPC.
5. Você inspeciona a resposta em formato legível e bruto.

A2A é um protocolo aberto para comunicação entre agentes de IA. Ele define o Agent Card, o ciclo de vida da tarefa e o formato das mensagens e artefatos trocados entre agentes.

Um depurador A2A não constrói seu agente nem executa seu workflow de produção. Ele responde a uma pergunta específica:

Dado este Agent Card, o que o agente realmente faz quando recebe esta mensagem?

Por que depurar A2A sem uma ferramenta é difícil

O tráfego entre agentes costuma ficar escondido em camadas que ferramentas genéricas não mostram bem.

1. Logs do console omitem campos importantes

Um SDK registra apenas o que seus autores decidiram expor. Campos como ID da tarefa, partes de artefatos, metadados e payloads estruturados podem nunca aparecer no stdout.

Você vê algo como:

task completed

Mas não vê o payload real que causou o problema.

2. A aba Network mostra JSON demais e contexto de menos

O painel de rede do navegador mostra o corpo HTTP bruto. Só que payloads A2A costumam vir dentro de envelopes JSON-RPC aninhados.

Um exemplo simplificado:

{
  "jsonrpc": "2.0",
  "id": "task-123",
  "result": {
    "artifacts": [
      {
        "parts": [
          {
            "type": "text",
            "text": "Resposta do agente"
          }
        ]
      }
    ]
  }
}

Sem uma visualização específica, você precisa rolar uma parede de JSON para descobrir se o agente retornou text, file, metadados ou um artefato inesperado.

3. Scripts temporários quebram rápido

A alternativa comum é criar um curl, script Python ou cliente descartável. Isso funciona até o Agent Card mudar, a autenticação ser alterada ou o payload evoluir.

Exemplo de teste manual frágil:

curl -X POST http://localhost:3000/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{...}}'

O problema: você passa a depurar o script e o agente ao mesmo tempo.

4. Erros de transporte e erros de lógica parecem iguais

Quando a resposta está errada, a causa pode ser:

• requisição malformada;
• falha de autenticação;
• conexão interrompida;
• Agent Card incorreto;
• bug no código do agente;
• prompt ou raciocínio ruim do modelo.

Sem ver a requisição e a resposta reais, tudo parece “o agente está quebrado”.

Um depurador A2A reduz essa ambiguidade: primeiro confirme o tráfego, depois investigue a lógica.

O que um bom depurador A2A deve fazer

Um depurador A2A útil precisa cobrir quatro áreas: descoberta, envio de mensagens, inspeção de resposta e autenticação.

1. Conexão e descoberta

O primeiro passo é carregar o Agent Card.

Normalmente, em desenvolvimento local, a URL pode ser algo como:

http://localhost:3000/.well-known/agent.json

Ao conectar, o depurador deve mostrar:

• nome do agente;
• descrição;
• versão do protocolo;
• capacidades declaradas;
• habilidades disponíveis;
• tipos de entrada suportados;
• requisitos de autenticação, quando existirem.

Se o Agent Card estiver inválido, a ferramenta deve indicar o campo problemático. Isso evita perder tempo investigando o agente quando o erro está no manifesto.

2. Teste de mensagens

Depois de conectar, você deve conseguir enviar mensagens sem montar manualmente o envelope JSON-RPC.

Um fluxo prático:

1. Comece com uma mensagem de texto simples.
2. Verifique se a habilidade esperada foi acionada.
3. Só depois adicione arquivos.
4. Em seguida, adicione metadados por mensagem.
5. Compare a resposta bruta com a visualização renderizada.

Exemplo de mensagem de teste inicial:

Resuma o conteúdo deste documento em três tópicos.

Depois, adicione metadados apenas se forem relevantes para o handler do agente:

{
  "language": "pt-BR",
  "tenantId": "dev-team"
}

A regra prática: teste o menor payload possível antes de adicionar contexto.

3. Inspeção de resposta

A inspeção da resposta é o ponto central.

Respostas A2A podem incluir:

• texto simples;
• artefatos estruturados;
• referências a arquivos;
• múltiplas partes de mensagem;
• metadados;
• eventos de streaming.

Um bom depurador deve mostrar o mesmo payload por mais de uma lente. O Depurador A2A do Apidog, por exemplo, oferece três visualizações:

• Preview: renderiza campos estruturados como uma árvore legível.
• Content: mostra o conteúdo como o usuário final veria.
• Raw Data: exibe o JSON-RPC completo para inspeção campo a campo.

Isso acelera diagnósticos comuns.

Por exemplo:

• Preview correto, Content vazio: o agente pode ter retornado um artefato tipado que o renderizador não achatou.
• Raw Data sem o campo esperado: o problema provavelmente está no código do agente.
• Raw Data bem formado, mas conteúdo incorreto: o transporte está ok; investigue prompt, modelo ou lógica.

4. Autenticação e cabeçalhos

Agentes de produção normalmente ficam atrás de autenticação.

Um depurador A2A deve permitir configurar, pela UI:

• Bearer Token;
• Autenticação Básica;
• chave de API via cabeçalho customizado;
• cabeçalhos arbitrários para gateways, proxies, tenants ou assinaturas.

Exemplo de cabeçalhos comuns:

Authorization: Bearer <token>
X-Tenant-ID: dev-team
X-Request-ID: debug-001

Também é importante separar dois conceitos:

• Cabeçalhos HTTP: chegam ao gateway, proxy ou camada HTTP.
• Metadados A2A: chegam ao handler de tarefas do agente.

Um erro comum é colocar uma instrução por mensagem em um cabeçalho HTTP quando o agente só lê metadados A2A. Ver os dois canais lado a lado torna esse tipo de bug muito mais fácil de identificar.

O Depurador A2A do Apidog

Apidog inclui um Depurador A2A no cliente padrão.

O fluxo básico é:

1. Abra a página do Depurador A2A.
2. Cole a URL do Agent Card.
3. Clique em Conectar.
4. Confirme se o status mudou para conectado.
5. Verifique os metadados carregados do agente.
6. Abra a aba de mensagens.
7. Envie um prompt de teste.
8. Leia a resposta em Preview, Content e Raw Data.

Para desenvolvimento local, a URL do Agent Card costuma ser parecida com:

http://localhost:3000/.well-known/agent.json

O Apidog lida com:

• envelope JSON-RPC;
• análise da resposta;
• eventos enviados pelo servidor quando o agente suporta streaming;
• histórico de mensagens da sessão;
• configuração de autenticação e cabeçalhos.

O histórico é útil porque você geralmente envia a mesma mensagem várias vezes enquanto ajusta o agente. Em vez de reescrever payloads, você compara execuções.

O depurador funciona como um cliente local: o tráfego vai diretamente entre sua máquina e o agente, não passando pelos servidores do Apidog.

Para um passo a passo completo, veja o guia do Depurador A2A do Apidog. O Apidog também tem um depurador de agente de IA para fluxos de teste mais amplos.

Checklist para escolher um depurador A2A

Ao comparar ferramentas, verifique se elas oferecem:

• Validação do Agent Card: a ferramenta deve explicar por que o card falhou.
• Múltiplas visualizações de resposta: JSON bruto e visualização legível devem existir juntos.
• Autenticação completa: Bearer, Básica, chave de API e cabeçalhos customizados.
• Suporte a arquivos: agentes reais recebem anexos, não apenas texto.
• Suporte a metadados: contexto por mensagem precisa ser fácil de enviar.
• Suporte a streaming: chunks devem aparecer conforme chegam.
• Histórico de sessão: essencial para repetir testes.
• Tráfego local-first: o depurador deve se comunicar diretamente com seu agente.

Essa abordagem transforma a depuração A2A em uma rotina objetiva: confirme primeiro o que está trafegando na rede. É a mesma disciplina aplicada em como testar agentes de IA que chamam suas APIs.

Se você também usa servidores MCP, o guia MCP Server vs A2A explica por que normalmente você precisa de um depurador específico para cada protocolo.

Um loop prático de depuração A2A

Quando um agente A2A se comportar de forma inesperada, use este loop:

1. Conecte-se ao Agent Card

   • Confirme se a ferramenta carregou o card.
   • Verifique se a habilidade esperada aparece.

2. Envie a menor mensagem possível

   • Comece com texto simples.
   • Não adicione arquivos nem metadados ainda.

3. Leia Raw Data primeiro

   • Veja exatamente o que o agente retornou.
   • Não dependa apenas da visualização renderizada.

4. Valide a estrutura

   • A resposta tem o campo esperado?
   • O artefato veio no tipo correto?
   • O ID da tarefa está presente?

5. Adicione complexidade aos poucos

   • Primeiro metadados.
   • Depois arquivos.
   • Depois autenticação mais restritiva ou headers adicionais.

6. Classifique o erro

   • Campo ausente: provável bug no agente.
   • Resposta malformada: provável erro de implementação A2A.
   • Falha HTTP/autenticação: problema de transporte ou configuração.
   • Resposta bem formada, mas incorreta: investigue prompt, modelo ou lógica.

Esse processo separa transporte de lógica e evita depuração por tentativa e erro.

Perguntas comuns

O que é um depurador A2A em uma frase?

É uma ferramenta que se conecta a um agente Agent2Agent, envia mensagens de teste e mostra a requisição e a resposta completas para você depurar integrações sem escrever código cliente.

Como um depurador A2A é diferente de um cliente de API?

Um cliente de API testa endpoints HTTP. Um depurador A2A entende a camada Agent2Agent: Agent Cards, ciclo de vida da tarefa, partes de mensagem e artefatos.

Ele não mostra apenas um corpo bruto; ele interpreta estruturas A2A.

Preciso de um depurador A2A se já tenho logs?

Sim, na maioria dos casos. Logs mostram o que o agente decidiu registrar. Um depurador mostra o tráfego real, incluindo campos que podem não aparecer nos logs.

Para revisar o protocolo, veja o que é Agent2Agent A2A.

O Depurador A2A do Apidog é gratuito?

Sim. Ele está incluído no cliente padrão do Apidog. Baixe o Apidog e acesse o Depurador A2A no painel lateral em uma versão recente.

Um depurador A2A pode testar agentes em qualquer framework?

Sim, desde que o agente exponha um Agent Card A2A válido. O protocolo é agnóstico a frameworks, então agentes em LangGraph, CrewAI, AutoGen ou implementações customizadas podem ser testados.

Um depurador A2A lida com respostas em streaming?

Um bom depurador lida. Quando o agente suporta eventos enviados pelo servidor, ele lê os chunks conforme chegam, atualiza as visualizações em tempo real e mostra o payload montado quando o stream termina.