wehub-resource-sync
a9cd7750f4
A2A (Agent2Agent) Protocol — Design Notes
A working understanding of the A2A protocol, derived from the official spec (
a2a-protocol.org), thea2aprojectGitHub org, Google's launch material, and the purchasing-concierge codelab. These notes exist to inform how Conductor might interoperate with A2A. Where a statement is an inference rather than spec text, it is marked (inference).Researched: 2026-06-18. A2A is moving fast — re-verify field/method names against the version you target before implementing (see 06-versioning.md).
What A2A is, in one paragraph
A2A is an open, vendor-neutral protocol that lets independent AI agents discover one another and collaborate as peers over standard web transports (HTTP + JSON-RPC 2.0, gRPC, or HTTP+JSON). An agent publishes a machine-readable Agent Card describing its identity, skills, supported transports, and authentication. A client agent finds a remote agent, sends it a Message, and the remote agent either replies inline or opens a stateful Task that progresses through a defined lifecycle, emits Artifacts (outputs), and can stream updates or call back via webhooks for long-running work. Crucially, agents stay opaque to each other — they do not share memory, tools, or internal logic; they cooperate only through the standardized message/task surface. A2A was announced by Google in April 2025 and donated to the Linux Foundation in June 2025; it reached v1.0 with an 8-company technical steering committee.
The one thing to remember: A2A vs MCP
They are complementary, not competing:
- MCP connects an agent down to its tools — APIs, databases, functions (agent → tooling).
- A2A connects an agent across to other agents — as collaborating peers (agent → agent).
"A2A is about agents partnering on tasks, while MCP is more about agents using capabilities." — official docs
A typical agent uses MCP internally to drive its own tools and A2A externally to collaborate with other agents. See 02-a2a-vs-mcp.md.
Heads-up: two live spec generations
This is the biggest practical gotcha, so it is called out everywhere in these notes.
| v0.2.x / v0.3.x (de-facto standard today) | v1.0 (/latest/ on the site) |
|
|---|---|---|
| Model | JSON-RPC-first | Protobuf-first (a2a.proto, ProtoJSON) |
| Enums | lowercase strings ("input-required") |
SCREAMING_SNAKE_CASE (TASK_STATE_INPUT_REQUIRED) |
| Roles | "user" / "agent" |
ROLE_USER / ROLE_AGENT |
| Polymorphism | kind discriminator field |
JSON member / wrapper based (no kind) |
| Well-known path | /.well-known/agent.json |
/.well-known/agent-card.json |
| Transport on card | preferredTransport + additionalInterfaces[] |
supportedInterfaces[] |
Most of these notes lead with the v0.3.x JSON-RPC model (what the broad SDK ecosystem still implements) and flag v1.0 deltas. Pin your target version explicitly. Full breakdown in 06-versioning.md.
Reading order
| # | Doc | What's in it |
|---|---|---|
| 1 | 01-overview-and-motivation.md | The problem, the vision, the 5 design principles, governance & timeline, core actors |
| 2 | 02-a2a-vs-mcp.md | The complementary relationship, the auto-repair-shop analogy, opaque agents |
| 3 | 03-data-model.md | Agent Card, Task & lifecycle, Message, Part, Artifact, events, push config |
| 4 | 04-protocol-mechanics.md | Transports, RPC methods, streaming (SSE), push notifications, error codes, "life of a task" |
| 5 | 05-security.md | Secure-by-default, security schemes, header-based identity, extended card, webhook security |
| 6 | 06-versioning.md | v0.2.5 → v0.3.0 → v1.0, what changed, which to target |
| 7 | 07-ecosystem-and-samples.md | Linux Foundation governance, canonical proto spec, official SDKs, samples, use cases |
| 8 | 08-conductor-implications.md | Analysis: how A2A maps onto Conductor (workflows-as-agents, A2A client task, lifecycle mapping) |
| 9 | 09-durable-a2a.md | Durability: what "durable A2A" must mean for the claim to hold — durability properties, the exactly-once boundary, the mechanisms (deterministic messageId, liveness guards, push backstop), and proof obligations |
| 10 | 10-a2a-server.md | A2A server (Direction A): exposing Conductor workflows as A2A agents — one agent per workflow, opt-in, status mapping, idempotent-start durability, auth |
Docs 1–7 describe A2A as it exists. Docs 8–10 are repo-specific design/implementation (the Conductor A2A client in 8–9 and the server in 10).
Glossary (quick)
| Term | Meaning |
|---|---|
| Client agent | Initiates communication; formulates and sends tasks on behalf of a user |
| Remote agent (A2A server) | Exposes an A2A HTTP endpoint; receives requests, runs tasks, returns results |
| Agent Card | JSON descriptor of an agent's identity, skills, transports, and auth — the discovery unit |
| Skill | A discrete advertised capability of an agent |
| Task | A stateful unit of work with a unique id and a defined lifecycle |
| contextId | Server-generated id that groups related tasks/turns into one conversation/session |
| Message | One turn of communication (role user or agent), made of Parts |
| Part | Atomic content unit: TextPart, FilePart, or DataPart |
| Artifact | A tangible output produced by a task, made of Parts |
| Opaque agent | An agent treated as a black box — no shared memory/tools/state |