Agent2Agent (A2A) is moving from spec to production quickly. As soon as you run more than one agent, you need a way to inspect Agent Cards, outgoing messages, headers, files, metadata, streaming events, and raw JSON-RPC payloads. This guide compares the A2A debugging tools available today and shows when to use each one.
If A2A is new to you, start with what Agent2Agent (A2A) is and what an A2A debugger is. They cover the Agent Card, task lifecycle, and why agent-to-agent traffic is harder to debug than a normal REST call.
How to evaluate an A2A debugger
Use this checklist before choosing a tool:
- Agent Card discovery: Can it fetch and validate the Agent Card URL?
- Capability visibility: Does it show the agent name, description, protocol version, capabilities, and skills?
- Message testing: Can you send text, files, and metadata without manually writing JSON-RPC?
- Response inspection: Can you view both a readable response and the raw payload?
- Auth support: Can you configure Bearer Token, Basic Auth, API keys, and custom headers?
- Streaming: Can it handle server-sent events when the agent supports streaming?
- History: Can you keep a record of messages in a debugging session?
- Local execution: Does traffic go directly from your machine to the agent?
1. Apidog A2A Debugger
Apidog includes a dedicated A2A Debugger in its standard client. For most teams, this is the most practical starting point because it provides a visual workflow without requiring custom scripts.
A typical debugging loop looks like this:
- Open the A2A Debugger.
- Paste the agent’s Agent Card URL.
- Click Connect.
- Review the validated card: name, description, capabilities, skills, and protocol version.
- Open the Messages tab.
- Send a plain-text test message.
- Attach files if the Agent Card declares supported input types.
- Add metadata as key-value pairs when needed.
- Inspect the response in:
- Preview for a readable tree
- Content for the human-readable message body
- Raw Data for the full JSON-RPC payload
Authentication is configured in the UI. Apidog supports:
- No auth
- Bearer Token
- Basic Auth
- API key through a custom header
- Additional custom headers for gateways, tenants, or routing
It also keeps session history, supports server-sent-event streaming when the agent supports it, and runs as a local client, so your traffic goes directly between your machine and the target agent.
Strengths: broad A2A feature coverage, no scripting required, three response views, file and metadata testing, auth handling, streaming support, and the same workspace you can use for REST, GraphQL, and MCP.
Trade-off: it is part of the full Apidog client rather than a tiny single-purpose CLI.
Best for: teams building or consuming A2A agents who want a visual, no-code debugging workflow.
Start with the Apidog A2A Debugger guide, then download Apidog to follow the workflow.
2. A2A Inspector
The A2A project maintains an open-source A2A Inspector. It is a web-based tool for connecting to an agent, viewing its Agent Card, and sending messages. It is published alongside the spec at the A2A GitHub organization.
Because it comes from the project that owns the protocol, it is useful as a reference for what a compliant Agent Card and message exchange should look like.
Use it when you want to:
- Run a spec-aligned tool locally.
- Validate an Agent Card.
- Send a basic message.
- Compare your agent behavior against the protocol reference.
Strengths: spec-accurate, open source, free, and useful for conformance checks.
Trade-off: it is usually a self-run developer tool. Its UX, auth handling, and file attachment flow are less complete than a dedicated product.
Best for: developers who want a protocol reference and are comfortable running tools locally.
3. A2A CLI and SDK tooling
The official A2A SDKs, including Python and JavaScript/TypeScript tooling, include command-line helpers and sample clients. These can fetch an Agent Card, send a message, and print the response.
This approach is best when you need something scriptable.
A CLI-based flow usually looks like this:
# Pseudocode example: exact commands depend on the SDK you use
a2a card fetch https://agent.example.com/.well-known/agent-card.json
a2a message send \
--agent https://agent.example.com \
--text "Ping from CI"
Use SDK or CLI tooling for:
- CI smoke tests
- Automated conformance checks
- Regression tests
- Repeatable pass/fail validation
Strengths: scriptable, automatable, and convenient if your project already depends on the SDK.
Trade-off: you usually inspect raw JSON in the terminal. There are no rich response views, visual history, or exploratory debugging features.
Best for: CI pipelines and automated checks, not interactive debugging.
4. A2A sample agents and demo UI
The A2A project publishes sample agents and a multi-agent demo UI in its samples repository, reachable from the A2A protocol site. The demo UI shows multiple agents coordinating and lets you inspect the messages between them.
Use the demo UI to understand a healthy A2A exchange before debugging your own implementation.
A useful learning flow is:
- Run the demo UI.
- Observe how agents discover each other.
- Inspect the message sequence.
- Compare that known-good flow with your own agent.
- Move to a debugger when testing your own Agent Card and messages.
Strengths: good for learning, shows real multi-agent flows, free and open source.
Trade-off: it is a demo, not a general-purpose debugging product. You do not use it to drive arbitrary agents the same way you would with Apidog or the Inspector.
Best for: learning the protocol and getting a known-good reference exchange.
5. General API clients: curl and custom scripts
You can debug A2A with raw HTTP because an A2A request is JSON-RPC over HTTP. For a one-off check, curl or a small script can work.
For example:
curl -X POST "https://agent.example.com/a2a" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": "debug-1",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "Hello from curl"
}
]
}
}
}'
This is useful for confirming that an endpoint responds, but it becomes painful quickly. You have to manually maintain the JSON-RPC envelope, headers, auth, files, metadata, and response parsing.
Strengths: already available and fine for a single sanity check.
Trade-off: no Agent Card validation, no visual response rendering, no session history, no guided file handling, and no streaming support.
Best for: one-time checks only.
Quick comparison
| Tool | Type | Visual response views | Auth in UI | Streaming | Best for |
|---|---|---|---|---|---|
| Apidog A2A Debugger | Visual client | Three views | Yes | Yes | Day-to-day A2A debugging |
| A2A Inspector | Web tool (self-run) | Basic | Limited | Partial | Spec reference |
| A2A CLI / SDK | Command line | None (raw JSON) | Via flags | Limited | CI and automation |
| A2A demo UI | Sample app | Built-in | N/A | Yes | Learning the protocol |
| curl / scripts | Raw HTTP | None | Manual | No | One-off checks |
Which one should you use?
For interactive debugging, start with the Apidog A2A Debugger. It validates Agent Cards, sends messages with files and metadata, renders responses in three ways, and handles auth without custom scripts. It also sits next to REST, GraphQL, and MCP tooling, which helps when your agent system uses more than one protocol. The MCP server vs A2A guide explains why this matters as agent systems grow.
For automated conformance in CI, pair a visual debugger with the A2A SDK CLI. Use the visual debugger to reproduce and isolate bugs, then convert the fixed behavior into a scripted check. The same wire-level testing discipline from how to test AI agents that call your APIs applies here.
For learning the protocol, run the A2A demo UI first. It gives you a known-good multi-agent exchange before you debug your own agents.
Once your agents need credentials, review the secure AI agent API credentials guide so you know what to rotate, scope, and avoid exposing.
The practical setup for most teams is:
- Use Apidog A2A Debugger for day-to-day investigation.
- Use A2A Inspector as a protocol reference.
- Use SDK CLI tooling in CI.
- Use curl only for quick sanity checks.
Common questions
What is the best A2A debugger right now?
For interactive debugging, the Apidog A2A Debugger is the most complete option: Agent Card validation, message testing with files and metadata, three response views, auth configuration, and streaming support without scripting.
Are there free A2A debuggers?
Yes. The Apidog A2A Debugger ships free with the standard client, and the official A2A Inspector, SDK CLI, and demo UI are open source and free.
Can I debug A2A agents with Postman?
Postman has no native A2A support. You can send the raw JSON-RPC HTTP request manually, but you lose Agent Card validation, response rendering, and streaming support. A dedicated A2A debugger handles the protocol layer for you.
Do A2A debuggers work with any agent framework?
Yes, as long as the agent publishes a valid A2A Agent Card. A2A is framework-agnostic, so LangGraph, CrewAI, AutoGen, and custom agents can work with A2A tooling. See what Agent2Agent (A2A) is for the protocol basics.
Should I use a CLI or a visual A2A debugger?
Use both. A visual debugger like Apidog is faster for reproducing, inspecting, and isolating issues. A CLI is better for automated conformance checks in CI. A common workflow is to debug visually first, then script the fixed behavior.
How do I get started debugging an A2A agent?
Download Apidog, open the A2A Debugger, paste your agent’s Agent Card URL, click Connect, and send a plain-text test message. The Apidog A2A Debugger guide walks through the full loop.
Top comments (0)