What is A2A protocol? Starter to intermediate guide

It defines a simple JSON handshake that lets each agent plug into the same conversation without bespoke glue code. Instead of tracking dozens of scripts, you point every component at a common endpoint and they automatically discover, invoke and report on actions. In this guide, you will see how that handshake works, explore real-world examples and get practical next steps to start building multi-agent workflows in minutes.

What is A2A protocol?

Introduced by Google, A2A protocol stands for agent-to-agent protocol. It is a vendor-neutral JSON schema that standardises how AI agents announce their capabilities, invoke one another’s actions and report results. This standardisation removes the need for bespoke glue code whenever you add a new agent or service. Any A2A-compliant endpoint can plug into your system, and agents will automatically speak the same language, reducing errors and accelerating development.

Interestingly, A2A was initially developed for Self-Sovereign Identity (SSI) ecosystems but has since expanded to broader applications in AI, Web3, fintech, and enterprise multi-agent systems.

Why A2A protocol matters

Custom agent integrations often feel like building one-off bridges for every new handoff. You write bespoke scripts to map inputs and outputs, only to watch them break when one API changes. Teams end up spending more hours on plumbing than on building intelligence.

A2A protocol cuts through that mess with a shared JSON handshake. Think of it as giving every agent the same sheet music. They speak a predictable language with fields for sender, recipient, action and parameters. You no longer need custom translators for each service.

With a common schema, agents can validate messages before processing. That catches errors early and keeps workflows running smoothly in production.

Version tolerance becomes practical, too. Agents declare their version in the handshake so you can support old and new formats side by side. That lets you roll out upgrades gradually without disrupting running workflows.

Core A2A concepts and terminologies

The heart of the A2A protocol is a shared vocabulary that agents use to communicate.

Message schema fields

Every A2A message follows a predictable JSON format. Fields include:

• Sender the unique identifier of the agent initiating the action
• Recipient the identifier of the agent expected to handle the request
• Action the name of the operation to perform for example fetchData or generateReport
• Parameters a structured object containing inputs for the action such as IDs or query filters
• Metadata optional fields for correlation identifiers timestamps or version information

This consistent schema prevents misunderstandings and lets agents validate incoming messages before they process them.

Agent cards and capability discovery

Agent cards are self-describing JSON manifests that list an agent’s capabilities and requirements. Each card includes:

• Agent name and version to identify the implementation
• Supported actions with descriptions of inputs and outputs
• Authentication details such as required tokens or scopes
• Optional performance hints like expected response time or parallelism support

When an agent first connects to an A2A endpoint it requests the available agent cards. That discovery step lets it build a local registry of who can do what and how to authenticate each call.

Feedback loops for long-running tasks

Not all actions complete instantly. Feedback loops let agents stream progress updates back to the caller. A long-running action might send interim messages such as:

• Status updates indicating percentage complete or next subtask
• Partial results as they become available for example a first batch of records
• Error notices with details if a step fails and retry logic kicks in

By handling streaming and retries within the handshake, agents avoid timeouts and give human operators real-time visibility into workflows that span minutes or hours.

A2A vs MCP vs ACP

A2A protocol, MCP and ACP each solve different problems. A2A focuses on agent-to-agent workflows and task lifecycles. MCP connects language models to external tools and data sources. ACP provides a lightweight registry for agent capabilities without full orchestration. In practice, you might use A2A when two or more agents must hand off a job, MCP when an LLM needs to fetch or update data, and ACP when you simply need discovery of what each agent can do.

A2A protocol practical applications

Let’s consider some more examples and real-life use cases to better understand the role of A2A protocol.

1. Candidate sourcing and hiring workflows: A recruiting team uses a job posting agent to broadcast open roles. A sourcing agent listens for those postings, queries LinkedIn and internal databases for matching profiles and returns a shortlist. A background check agent then picks up each candidate ID, runs verification steps and reports back.
   With A2A protocol every agent speaks the same JSON language. The recruiting platform simply points each agent at the shared endpoint and they coordinate without custom integration scripts.
2. Supply chain demand forecasting and restocking: A demand forecast agent analyzes sales data and predicts inventory needs for the coming week. It sends a structured message to an inventory agent, which checks current stock levels in the warehouse management system. When stock falls below the threshold the inventory agent invokes a purchase order agent to reorder products from suppliers.
   Because each agent follows the A2A handshake they automatically discover and invoke the correct actions, cutting manual handoffs and reducing stockouts by up to twenty percent.
3. Security incident response: A threat detection agent monitors logs and streams alerts when it spots suspicious activity. It notifies a context enrichment agent that gathers user session data, related alerts and historical risk scores. Finally a remediation agent executes containment steps such as disabling compromised accounts or isolating affected systems.
   The A2A protocol’s feedback loops let each agent stream progress updates so security analysts can watch the response in real time. Teams report a forty percent reduction in mean time to resolution after adopting this pattern.
4. Automated financial report generation: A data extraction agent pulls daily transactions from ERP systems. It passes the results to a transformation agent that aggregates revenue by region and product line. A reporting agent then formats charts and tables and publishes a dashboard update.
   With A2A protocol each agent validates incoming messages against the shared schema. That prevents formatting errors and lets finance teams trust the automated pipeline without constant manual checks.

Best practices and common pitfalls

When you build A2A workflows it pays to follow a few proven patterns and watch out for common traps.

• Validate your schema early and often. Define your JSON schema before writing any agent code. Use tools like json schema validators in your CI pipeline to catch mismatches on every commit. That way you avoid discovering payload errors only after production workflows fail.
• Implement idempotency for safe retries. Include a unique request identifier in every message. Agents can use that identifier to detect duplicate requests and avoid processing the same action twice. Idempotent design prevents side effects like creating the same record multiple times when network glitches trigger retries.
• Use robust authentication and versioning. Require token based authentication for every agent interaction. Scope tokens to the minimum permissions needed for each action. Include a version field in your agent cards and message metadata. That lets agents negotiate compatible formats and maintain backward compatibility as you roll out new features.
• Avoid circular workflows and infinite loops. Design your agent interactions with clear termination criteria. A calls B which calls C which calls A can easily spiral into never-ending loops. Add a hop count or a time to live field in your metadata so each message expires after a defined number of handoffs.

Ecosystem tools and resources for A2A

A2A SDKs and client libraries

• The official A2A protocol specification site provides reference implementations in Go, Python and TypeScript. 
• For JavaScript and TypeScript projects, the a2a-client package on npm offers helpers for message serialisation, schema validation and agent discovery. Install it with npm install a2a-client.
• Python teams can use the agent_interop package on PyPI. It includes client stubs, JSON schema definitions and integration tests to get you up and running quickly.
• Community members maintain additional libraries on GitHub. Search for repositories tagged with A2A-protocol to discover custom extensions and language bindings.
  

Hosted services and community registries

• The A2A Registry lists public servers and connectors contributed by the community. You can fork an existing agent server or deploy your own with a single click.
• MCPmarket.com and A2A Registry both host community-maintained endpoints you can point your agents at for testing or production use.
• Hosted platforms like Superflow and Boomi are beginning to add A2A protocol support for no-code or low-code agent orchestration. Check their integration marketplaces for A2A connectors.
• Join the A2A Protocol community forum on GitHub Discussions to stay informed about new SDK releases, specification updates and best practices shared by early adopters.

How to get started with A2A protocol

First, let us build a quick proof of concept so you can see A2A protocol in action.

1. Clone the reference repo
   Visit the official A2A protocol GitHub organization and fork the Go, Python or TypeScript example. Clone it locally so you have both the server and sample agents on your machine.
2. Launch the server and agents
   In the project folder run docker-compose up. This command spins up a local A2A server along with two out-of-the-box agents ready to talk to each other.
3. Review the agent cards
   Open each agent_card.json file to inspect the agent name, version and supported actions. This manifest is your contract for what the agent can do.
4. Discover available agents
   Use the client stub or a curl command to POST to http://localhost:8000/discover. You should see a JSON array of agent cards in the response. That confirms your client can talk to the server.
5. Test a ping-pong workflow
   Send a simple message from one agent to another:
   {
"sender": "agentA",
"recipient": "agentB",
"action": "ping",
"parameters": {}
}
Verify that agentB responds with a pong message. This handshake proves end-to-end connectivity.
6. Extend with real logic
   Modify agentB to fetch a record from a test database or call a public API. Update its agent card to list the new action. Rerun your ping example with the new action name and watch your agents perform a real task.

For minimal code complexity and a straightforward approach you can also consider the following options:

• Hosted A2A services
  Sign up for a managed A2A endpoint on platforms like Superflow or Boomi. Paste in your agent cards, then use their visual dashboard to run discovery and invoke actions—all without writing integration code.
• IDE plugins
  Install the Cursor extension (or a similar A2A-enabled plugin) in your development environment. Point it at a public A2A server URL, bind your functions to agent actions and let the plugin handle the JSON handshake for you.
• Visual orchestration tools
  Use n8n, Node-RED or similar low-code platforms with HTTP request nodes. Configure discovery and invoke steps by dragging and dropping nodes, wiring them together visually. You write only the business logic while these tools manage the protocol calls.

Closing thoughts

The A2A protocol brings a predictable, vendor-neutral handshake to multi-agent systems. By standardizing message schemas, agent cards and feedback loops, it cuts the brittle glue code that slows down development and breaks in production.

Whether you need rapid experimentation or enterprise-grade agent orchestration, A2A protocol lays the foundation for resilient, scalable workflows. Start building your first multi-agent project today and see how a simple JSON handshake can transform your AI ecosystem.