Hassann

Posted on May 15 • Originally published at apidog.com

How to Debug Agent-to-Agent (A2A) Protocol with Apidog's A2A Debugger

If you build AI agents that talk to other AI agents, you need a reliable way to inspect the traffic between them. Console logs are incomplete, browser network tabs often hide the structured fields you care about, and one-off test scripts get stale quickly. Apidog’s A2A Debugger gives you a practical workflow for testing Agent2Agent (A2A) endpoints: paste an Agent Card URL, connect, send a message, and inspect the reply in Preview, Content, and Raw Data views.

Try Apidog today

This guide shows how to connect your first A2A agent, send a test message, inspect the request/response payloads, configure authentication, and decide when to use Apidog’s A2A Debugger versus its existing MCP server testing tools. If you want the protocol background first, read Apidog’s MCP vs A2A breakdown.

What A2A is

A2A, short for Agent2Agent, is an open protocol for communication between AI agents. It defines:

How an agent advertises its capabilities through an Agent Card
How another agent discovers and connects to it
How messages and file attachments are exchanged
How task status and artifacts are returned

Think of A2A as a vendor-neutral transport contract for agent-to-agent traffic. For example, a LangGraph agent in a data pipeline can call a CrewAI agent owned by another team without either side needing to know the other’s internal implementation.

A2A is different from MCP, the Model Context Protocol. MCP gives one agent access to tools and resources. A2A lets agents communicate with other agents. For a deeper comparison, see the MCP vs A2A guide.

What the A2A Debugger gives you

The A2A Debugger is available inside Apidog. It is a visual workbench for testing A2A endpoints before you connect them to a production workflow.

Key capabilities:

Agent Card connection: Paste an Agent Card URL, connect, and inspect the agent’s name, description, capabilities, skills, and protocol version.
Message sending: Send plain text, attach supported files, and include custom metadata.
Three response views:
- Preview for structured rendering
- Content for readable output
- Raw Data for the full JSON payload
Authentication: Configure Bearer Token, Basic Auth, or API Key headers from the UI.
Custom headers: Add gateway auth, tenant IDs, request IDs, or other middleware parameters.
Session history: Review previous messages in the current debugging session.

You do not need to write curl commands manually. Apidog handles the JSON-RPC envelope, SSE streaming when supported by the agent, and response parsing.

Step 1: Connect to your first A2A agent

Before opening the debugger, make sure you have:

The latest Apidog client

Older versions may not include the A2A Debugger. If needed, download Apidog.

An Agent Card URL

For local development, this often looks like:

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

For hosted agents, your platform or infrastructure team should provide the path.

Credentials if required

This could be a bearer token, API key, or basic auth username/password.

Then:

Open Apidog.
Go to the A2A Debugger.
Paste the Agent Card URL.
Configure auth if the discovery endpoint requires it.
Click Connect.

If the agent returns a valid Agent Card, Apidog shows a Connected status and displays metadata such as:

Agent name
Description
Capabilities
Declared skills
Protocol version

If the connection fails, check these first:

The URL is incorrect or the agent is not running.
The Agent Card is missing required fields.
The discovery endpoint requires authentication.
The response is not valid JSON.
The implementation does not match the A2A protocol spec on GitHub.

Step 2: Send a test message

After connecting, open the Messages tab and send a small prompt first.

Example:

Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.

Start with plain text before adding files or metadata. This helps isolate transport issues from input-handling issues.

Optional additions:

Add a file attachment

Use the paperclip button to attach a file.

The debugger checks the agent’s declared input types and rejects unsupported files before sending the request. This helps avoid wasted requests that fail because of unsupported media types.

Add custom metadata

Use metadata for values that the agent’s task handler should read.

Examples:

priority: high
tenant: acme-corp
locale: en-US

When you click Send, Apidog wraps your prompt in the A2A message structure, sends it to the agent, and waits for the response.

Step 3: Inspect the response

A2A responses can contain plain text, structured JSON, file references, task status, artifacts, or a combination of these.

Apidog gives you three views of the same response.

Preview

Use Preview when you want a structured rendering of nested fields such as:

Task ID
Status
Artifacts
Message history
File parts

Content

Use Content when you want the human-readable body.

If the agent returns text, this is the output you would typically show to a user. If the response includes a structured artifact with a text/plain part, this view shows the extracted text.

Raw Data

Use Raw Data when you need the exact payload.

This is the view to use when:

Comparing the response against the A2A spec
Checking exact field names
Debugging escaping issues
Copying payloads into bug reports
Verifying error objects

For example, if Preview looks correct but Content is empty, the agent may be returning a typed artifact that renders structurally but does not flatten cleanly into text.

If Raw Data includes an error object, start with:

{
  "error": {
    "message": "..."
  }
}

The error.message value is usually the fastest path to the root cause.

Session history appears in the left panel. Every message you send is stored as a turn in the current session. Use Clear when starting a new test so previous context does not affect the next run.

Authentication: three common patterns

Most production A2A endpoints require authentication. Apidog supports the common patterns directly in the debugger.

Bearer Token

Use this for hosted agents that expect an OAuth-style or platform-issued token.

In Apidog:

Open the auth panel.
Select Bearer Token.
Paste the token.

Apidog sends:

Authorization: Bearer sk-agent-7f3e9a...

Basic Auth

Use Basic Auth for internal or legacy systems protected by username and password.

In Apidog:

Select Basic Auth.
Enter the username.
Enter the password.

Apidog builds the base64-encoded header for you:

Authorization: Basic ...

API Key via custom header

Use custom headers when the agent expects a non-standard header.

Example:

X-Agent-Key: your-api-key

You can use the same approach for gateway-specific headers such as:

X-Tenant-Id: acme-corp
X-Request-Id: req-123
X-Feature-Flag: a2a-debug

For agent credential practices, read the Apidog AI agent credentials guide.

Custom headers vs metadata

A2A requests can carry extra data in two places: HTTP headers and A2A metadata. They are not interchangeable.

Channel	Where it lives	Use it for
Custom Headers	HTTP request headers	Gateway auth, observability, request IDs, feature flags
Metadata	A2A message payload	Per-message context the agent reads, such as priority, tenant, or locale

Rule of thumb:

If your reverse proxy, API gateway, or middleware needs it, use headers.
If the agent’s task handler needs it, use metadata.

A common bug is putting agent instructions in headers and then wondering why the agent ignored them. Unless your agent explicitly reads those headers, it will never see that context.

A2A Debugger vs MCP server testing in Apidog

Apidog includes both an A2A Debugger and an MCP testing flow. Use them for different layers of an agent system.

Tool	Protocol	Tests	Use when
A2A Debugger	Agent2Agent	Connectivity, message exchange, task status	You are building multi-agent systems where agents call other agents
MCP server testing	Model Context Protocol	Tool calls, resource access, prompt templates	You are building an MCP server that exposes tools or resources to an agent

Short version:

MCP is what an agent uses to access external tools and resources.
A2A is what an agent uses to talk to another agent.

If you are unsure which one you need, start with the MCP vs A2A guide.

For the MCP side, the MCP server testing playbook covers manual and automated testing in Apidog.

In real systems, you may need both:

A user-facing agent receives a task.
It calls another specialized agent over A2A.
That specialized agent uses MCP to access tools or resources.
The result returns through the A2A conversation.

Debugging pattern: round-trip a task

When an agent does not respond as expected, use this loop:

Open the A2A Debugger.
Connect to the agent.
Confirm the Agent Card lists the skill you expect.
Send the smallest possible message that should trigger that skill.
Use plain text first.
Add files only after the text path works.
Add metadata only after the basic request works.
Inspect Raw Data before relying on Preview.
Check whether the response is well-formed.
If the response is missing fields, debug the agent implementation.
If the response is valid but semantically wrong, debug the prompt, model behavior, or task logic.

This is the same isolation-first approach described in How to test AI agents that call your APIs: verify the wire format first, then debug the agent’s reasoning or business logic.

Where this fits in your AI workflow

Multi-agent systems are becoming a common architecture for production AI applications. The AI agents are the new API consumers post explains why agent traffic should be treated as first-class API traffic. The Designing APIs for AI agents follow-up explains how API contracts change when the consumer is an LLM-driven agent instead of a human developer.

The A2A Debugger sits at the same layer as Apidog’s MCP Client visual debugger. Both tools expose traffic that is otherwise hidden inside SDKs and agent frameworks.

The workflow is straightforward:

Wire up the agent.
Send a controlled request.
Inspect the exact response.
Fix protocol, payload, auth, or agent logic issues before production.

Apidog is free to download, and the A2A Debugger ships with the standard client.

Common questions

Is the A2A Debugger free?

Yes. It is bundled with the standard Apidog client. Download Apidog, update to a recent version, and the A2A Debugger appears in the side panel.

Does it work with agents written in any framework?

It works with any agent that exposes a valid A2A Agent Card. The protocol is framework-agnostic, so LangGraph, CrewAI, AutoGen, and custom Python or Go agents can work as long as they implement the A2A spec.

Can I save sessions for later replay?

Sessions persist while the debugger is open. For long-term storage, copy the Raw Data output and save it with your test artifacts.

How does it handle streaming responses?

When the agent supports SSE streaming according to the A2A spec, the debugger reads chunks as they arrive and updates Preview and Content in real time. Raw Data shows the assembled response when the stream closes.

What is the difference between metadata and headers?

Headers live at the HTTP layer. Metadata lives inside the A2A message payload.

Use headers for gateways, proxies, auth, and observability. Use metadata for context the agent’s task handler should consume.

Does Apidog log the agent’s responses to its servers?

No. Apidog operates as a local client. Traffic between your machine and the agent does not pass through Apidog infrastructure.

Can I test a hosted agent on a different network?

Yes, as long as your machine can reach it. The debugger makes outbound HTTPS requests like any HTTP client. If the agent is behind a VPN, connect to the VPN first.

Where do I report bugs or request features?

Use the Apidog feedback channel for product feedback. For protocol-level issues, use the A2A protocol GitHub repo.

Try it now

Pick the simplest A2A agent you can access. If you do not have one yet, the A2A reference implementations include a sample server you can run locally.