Agent2Agent (A2A) Protocol
Open protocol for agents from different vendors to discover each other via Agent Cards and delegate stateful, long-running Tasks over JSON-RPC, gRPC or REST; the horizontal complement to MCP.
Contents
The Agent2Agent (A2A) protocol is an open standard that lets one agent (the client) discover another agent (the remote agent) and delegate work to it, even when the two come from different vendors or frameworks and neither can see the other’s internals. The remote agent publishes a JSON Agent Card that describes its skills, endpoints and auth. The client sends Messages made of Parts. Longer work is tracked as a Task with a defined state machine and produces Artifacts (spec). Google launched A2A on 2025-04-09 with 50+ partners (announcement). It is now an Apache-2.0 Linux Foundation project inside the Agentic AI Foundation, alongside MCP (repo). The current line is v1.0 (spec).
Why it exists, and how it differs from MCP
MCP is vertical: it connects one agent to tools, which have structured inputs and outputs and are usually stateless. A2A is horizontal: it connects agents, which reason, plan and hold multi-turn state (A2A and MCP). The design principles say agents should collaborate without being reduced to a tool. They also call for building on HTTP, SSE and JSON-RPC, being secure by default, supporting tasks that run for hours or days with humans in the loop, and staying modality agnostic (announcement).
| MCP | A2A | |
|---|---|---|
| Connects | Agent → tools/data | Agent → agent |
| Counterpart | Transparent function with schema | Opaque agent with skills |
| State | Stateless calls; explicit handles if needed (MCP in practice) | Task lifecycle + contextId conversations |
| Discovery | tools/list on a known server | Agent Card at a well-known URL or a registry |
| Long work | Tasks extension | Core: streaming, polling, push webhooks |
| Output | content / structuredContent | Messages and Artifacts made of Parts |
The two are designed to be combined. Agents talk to each other over A2A, and each one reaches its own tools over MCP (A2A and MCP, notebook).
flowchart LR
U["User"] --> M["Shop manager agent"]
M -- "A2A task" --> X["Mechanic agent"]
X -- "MCP" --> T1["Diagnostic scanner tool"]
X -- "MCP" --> T2["Repair manual DB"]
X -- "A2A task" --> P["Parts supplier agent"](The auto-repair example from the A2A docs.)
The Agent Card
Discovery works in three ways: the card at https://{domain}/.well-known/agent-card.json, a registry, or direct configuration (spec). Required fields (all of the groups below except security):
- Identity:
name,description,version. - Content types:
defaultInputModes/defaultOutputModes(media types). - Skills: each has
id,name,descriptionandtags, with optionalexamplesand per-skill modes. Routing agents use skills and examples to decide where to send work, so write them carefully (builder’s guide). supportedInterfaces: an ordered list of{url, protocolBinding, protocolVersion, tenant?}with bindingsJSONRPC,GRPCorHTTP+JSON. The first entry is preferred. All bindings must be functionally equivalent, and the SDK client picks the first one it supports (builder’s guide).capabilities:streaming,pushNotifications,extendedAgentCard. These are commitments. If push is advertised as false, push calls must fail withPushNotificationNotSupportedError.securitySchemes/security: API key, HTTP auth, OAuth 2.0 (authorization code, client credentials, device code), OpenID Connect, mTLS.
Cards can be signed with JWS (RFC 7515) over RFC 8785 (JCS) canonical JSON, excluding the signatures field, and clients should verify a signature before trusting a card. An authenticated GetExtendedAgentCard call can reveal skills that are not shown publicly (spec).
Tasks, messages and artifacts
- Message: has
role(user/agent),parts, and optionalcontextId,taskIdandreferenceTaskIds. A Part holds exactly one oftext,rawbytes,urlordata(JSON), plus an optionalmediaType. This is how agents negotiate modality (spec, announcement). - Task: has
id,contextId,status,historyandartifacts.contextIdgroups several tasks into one conversation, and a contextId/taskId mismatch must be rejected. - Artifact: has an
artifactIdand one or more Parts. It is the deliverable. - A simple request may get back a bare Message with no Task, so clients must handle both shapes (builder’s guide).
flowchart LR
S["SUBMITTED"] --> W["WORKING"]
W --> IR["INPUT_REQUIRED"]
W --> AR["AUTH_REQUIRED"]
IR -- "client sends message" --> W
AR -- "credential out of band" --> W
W --> C["COMPLETED"]
W --> F["FAILED"]
W --> X["CANCELED"]
S --> R["REJECTED"]Synthesis: transitions drawn from the state list in the spec. The spec groups the states as active, interrupted and terminal. Sending a message to a terminal task returns UnsupportedOperationError, and cancelling one returns TaskNotCancelableError (builder’s guide).
Operations and bindings
The abstract operations are SendMessage, SendStreamingMessage, GetTask, ListTasks (cursor-paginated), CancelTask, SubscribeToTask, push-notification config create/get/list/delete, and GetExtendedAgentCard. In the REST binding these become paths such as POST /message:send, POST /message:stream, GET /tasks/{id} and POST /tasks/{id}:cancel. JSON-RPC and REST stream over SSE, and each event is a StreamResponse delivered in order (spec).
There are three ways to follow long work (builder’s guide):
- Polling
GetTaskworks everywhere, including behind firewalls that block inbound traffic. - Streaming over SSE needs
capabilities.streaming. A task stream opens with the Task, then sends status and artifact updates, and closes at a terminal state. - Push notifications: the agent POSTs
StreamResponsepayloads to the client’s webhook. The client needs no open connection. The agent authenticates the call, uses 10–30 s timeouts with backoff, and refuses private address ranges. The receiver returns 2xx and deduplicates.
Versioning: clients send A2A-Version: 1.0. A missing header is treated as 0.3, which makes a 1.0-only agent answer VersionNotSupportedError. To fix this, add a second interface entry that declares 0.3 and enable the SDK’s compatibility flag (builder’s guide). Migrating from 0.3 to 1.0 also changed the card: supportedInterfaces replaces the single url + preferredTransport (spec). The well-known path had already moved from agent.json to agent-card.json in 0.3 (July 2025), and v1.0 registered it as a well-known URI (builder’s guide). The owner’s notebook still shows the older pre-0.3 agent.json shape.
Security
- Transport and identity: production requires TLS (1.3+ recommended), certificate validation and signed cards (spec).
- In-task authorization: when the remote agent needs extra credentials mid-task, it moves the task to
AUTH_REQUIREDand explains why. The credential should arrive out of band, and the state itself grants nothing (spec). - Card route vs protocol route: keep the public card route outside the protocol endpoint’s auth middleware, or new clients cannot discover the agent (builder’s guide).
Synthesis: a remote agent’s Messages and Artifacts are untrusted input, exactly like MCP tool output, so the same prompt injection and guardrail discipline applies at every A2A boundary.
SDKs
Official SDKs as of 2026-11-14 (repo):
| Language | Package |
|---|---|
| Python | a2a-sdk |
| Go | github.com/a2aproject/a2a-go |
| JavaScript | @a2a-js/sdk |
| Java | a2a-java repo (Maven) |
| .NET | A2A |
| Rust | a2a-lf |
A Python server has three parts: a card, an executor, and routes. The executor receives a RequestContext and writes events to an EventQueue, and those events become the wire output. A client resolves the card, builds a client from it, and iterates the stream until it sees a terminal status (builder’s guide).
Failure modes
- Gateway timeouts:
SendMessageblocks until a terminal or interrupted state by default. SetreturnImmediately: trueinSendMessageConfiguration(then poll, subscribe or use push) or stream for long tasks (builder’s guide). - Invalid stream shapes: mixing a Message with task events in one stream, or sending several Messages, raises
InvalidAgentResponseErrorat runtime (builder’s guide). - Silent 0.3 fallback when the version header is omitted (above).
- Harder to reason about: opaque agents are harder to debug than typed tool calls, and multi-agent hops add latency and failure modes. The ecosystem is still young (notebook).
When to use / when not
- Use A2A to delegate to an agent owned by another team, vendor or organisation, to expose your agent for others to call, or when the work is long-running, multi-turn, needs mid-task input or auth, or returns rich artifacts (A2A and MCP, notebook).
- Use MCP instead when the capability is a well-defined, stateless function. A2A agents can even expose such skills MCP-style (A2A and MCP).
- Use in-process subagents when all the agents live in one codebase you control. Synthesis: a network protocol adds auth, versioning and latency that buy nothing inside a single process. See agent design patterns.