How to read this manual

Every claim in this manual traces to a ranked source, and every request, response, and stream frame comes from a capture kit you can run yourself.

This manual explains the Agent2Agent protocol, A2A, at release 1.0.1, through one system: a planner that gives work to three agents it cannot see inside.

Who this manual is for

You have built an agent that calls tools or a model API, and you know HTTP and JSON. Now you want to give work to an agent that another team owns.

After the last part, you can:

Read an agent card and say what the agent offers, how to reach it, and what it requires.
Predict which state a task is in at any point of a run, and what a client can do next.
Choose between a blocking call, polling, streaming, and push notifications for a given job.
Read any A2A request, response, or stream frame line by line, in either JSON binding.
Name the errors a client must handle and the rules a server can break without noticing.

The A2A lesson predates version 1.0, so where the two differ, follow this manual.

How it was made

The manual pins tag v1.0.1 of the A2A repository, commit 3303592. In requests and cards, that release is protocol version 1.0, because requests, responses, and Agent Cards should not carry a patch version number. The facts were also checked against the main branch at commit 679ab3a of 2026-10-05, where v1.0.1 was still the latest release.

Facts come from five sources, ranked by authority. When two of them disagree, the higher one wins and the text says so.

Rank	Source	What the manual takes from it	Source key
1	`specification/a2a.proto` at v1.0.1	every object, field, enum value, and method	`proto` and a message or enum name
2	`docs/specification.md` at v1.0.1	every behavior rule, stated in our own words	`spec` and a section number
3	the project's documentation pages at v1.0.1	the project's own framing, flagged where a page is out of date	`docs` and a page name
4	the reference SDK, a2a-python 1.2.2	what a production implementation does where the specification is silent	`sdk` and a source file
5	the capture kit in `capture/`	every request, response, and stream frame the manual shows	the capture file name

The proto, the specification, and the documentation pages are vendored unchanged in the repository.

The specification disagrees with itself or the proto on the HTTP verb for SubscribeToTask (conflict D1) and on whether a send waits (conflict D2). It also disagrees on when a stream closes (conflict D3) and on the name of the card's security field (conflict D6). The sources reference lists all forty conflicts with the section that discusses each.

The capture kit

The capture kit runs three remote agents and a recording client on your machine, with the Python standard library only and no network or keys.

Agent	Port	What it does	What its runs show
`test-runner`	41241	runs a test suite and streams the log	streaming, artifacts in chunks, polling, cancel, push notifications, both JSON bindings
`code-reviewer`	41242	reviews a diff against a base branch	direct message replies, `TASK_STATE_INPUT_REQUIRED`, rejected content types, no push support
`deployer`	41243	deploys a build to staging after an operator approves	bearer authentication, `TASK_STATE_AUTH_REQUIRED` with approval outside A2A, rejection, extended and signed cards

A client walks through the real planner.

Seeded ids and a fixed clock make two runs byte-identical. The kit README lists where the kit differs from the reference SDK.

Conventions

Each section records its sources in the manual source, where the audit checks every quote and number. The sections do not show them. The sources reference lists them.

A listing copies lines from a capture file unchanged, and a … marks a cut that the note explains.

Field names and enum values are set in code type as they travel, such as messageId. Figures shorten task and context ids to 8 characters, so 728ba084-97eb-422b-b94b-b0fe9153ce2c appears as 728ba084.

Figures animate on the web, where a Replay button runs the steps again, and print and reduced motion show the final frame.

A first run

The kit needs Python 3 and four free ports on 127.0.0.1: 41241 to 41243 for the agents and 41250 for the webhook receiver. From the repository root, run it and check it:

cd manuals/a2a-101
python3 capture/run.py
python3 capture/run.py --check

Open capture/out/02-message-reply.http first: a question to code-reviewer and a direct answer, with no task. Then open capture/out/05-streaming.http, where a request to test-runner opens a stream of nine data: lines:

the start of a streamhttpFull log

POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0
Accept: text/event-stream
…
HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"jsonrpc": "2.0", "id": 1, "result": {"task": {"id": "728ba084-97eb-422b-b94b-b0fe9153ce2c", … "state": "TASK_STATE_SUBMITTED", …

The request body and the rest of the first frame are cut. Frames 2 to 9 follow it in the file.

The first frame is the task itself, and one task, request by request reads all nine.

How the parts are ordered

Part 1 gives you the whole protocol. Parts 2 to 6 each take one layer, from the AgentCard to security and extensions, and Part 7 builds a client and a server:

Part	What it covers
1 · The Protocol on One Page	A2A standardizes how one agent finds another agent, gives it work, and follows that work, and it leaves the agent itself out of scope.
2 · AgentCard	Before a client sends a message, the AgentCard tells it what the agent offers, where to reach it, and what it requires.
3 · Data Model	Every A2A exchange is built from five objects: Message, Part, Artifact, Task, and the contextId that groups tasks.
4 · Operations	Eleven operations create, read, cancel, and follow tasks, and each one has rules that a client must know before it calls.
5 · Bindings	The same operations travel over JSON-RPC, HTTP+JSON, and gRPC, with two headers and one error model shared by all three.
6 · Security and Extensions	The card declares how to authenticate and which extensions apply, and the specification lists what each side must check.
7 · Implementing A2A	A client and a server follow the rules of the earlier parts, and the official test kit checks the server against them.
R · Reference	Operations by binding, objects and fields, task states, errors, a glossary, the sources, and the index of figures.

Colour in figures

Each hue keeps one meaning in every figure:

violet	the client agent and what it sends
blue	remote agents, their cards, and the messages they send back
green	parts and artifacts: the content a task produces
amber	tasks, task states, and transitions
teal	the server's stored task records
indigo	streams, subscriptions, and push notifications
plum	the model or logic inside an agent, which A2A never shows
olive	tools and systems an agent calls on its own: CI, Git, MCP servers
rose	errors, failure, rejection, and cancellation
grey	the operator, the host, and anything outside the protocol

Figure 0.1 teaches seven of the eight arrow styles. It leaves out solid plum, because A2A never carries a model call.

Fig. 0.1reading a sequence figure in this manualsequence

Each of the seven arrow styles marks one kind of exchange, and the label on each arrow is a real name from a run of the kit. Read each numbered row from the tail of the arrow to its head. The note under a label gives the style and its meaning. The rows come from 03-blocking-task.http, 05-streaming.http, 15-push.http, 19-planner.log, and 11-errors.http, and the task store is the kit's own store inside test-runner.

A2A protocol 1.0.1 · 3303592 · 2026-05-28 · Edition 2026.10