A2A Protocol · AI Engineering

Cards, messages, tasks, states, the three bindings, errors and the 0.3 layer of A2A 1.0.1. Facts from the manual.

Protocol architecture

Nodes and connections

Node	Role	Kind
Planner	client, reads cards	client
AgentCard	/.well-known/agent-card.json	client
JSON-RPC	/a2a/jsonrpc	process
Handler	checks, then executor	process
HTTP+JSON	/a2a/rest	process
Task store	record of each task	store

From	To	Connection
Planner	AgentCard	GET
Planner	JSON-RPC	POST
JSON-RPC	Handler	method
HTTP+JSON	Handler	route
Handler	Task store	task

Sources

Send and read a task

Task	Code
Read the agent card	`GET /.well-known/agent-card.json HTTP/1.1`
Send one message	`"method": "SendMessage"` posted to `/a2a/jsonrpc`
Send the version	`A2A-Version: 1.0`
Send and return at once	`"returnImmediately": true` in `configuration`
Open a stream	`"method": "SendStreamingMessage"`

Sources

Commands over HTTP+JSON

Command	What it does
`POST /a2a/rest/message:send`	Sends a message. The reply is a task or a message.
`POST /a2a/rest/tasks/<task id>:cancel`	Asks the server to stop a task that is not terminal.
`GET /.well-known/agent-card.json`	Reads the agent card from the well-known path.
`POST /a2a/rest/tasks/<task id>:cancel`	Returns a task error when the task is already terminal.

Sources

Settings and defaults

Setting	Default	Note
`returnImmediately`	false	A send waits for a terminal or interrupted state
`historyLength`	unset	The server decides how much history to return. `0` returns no history.
`pageSize`	50	The maximum in `ListTasks` is 100
`includeArtifacts`	false	Artifacts are left out of list results
`A2A-Version`	1.0	Required on every request, with no patch number

Sources

Compare the bindings

Factor	JSON-RPC	HTTP+JSON	gRPC
Operation named by	`method`, such as `SendMessage`	route, such as `POST /message:send`	rpc `SendMessage` in `A2AService`
Where it is sent	one URL, `/a2a/jsonrpc` in the kit	one route per operation	`lf.a2a.v1.A2AService` over HTTP/2 with TLS
Stream frame	a `data:` line with a full JSON-RPC response	a `data:` line with the `StreamResponse` alone	a server-streaming rpc of `StreamResponse`
`TaskNotFoundError`	`-32001` with HTTP 200	HTTP 404	`NOT_FOUND`
Version header	`A2A-Version` header	`A2A-Version` header	`a2a-version` metadata key

Sources

Task states

Active: TASK_STATE_SUBMITTED and TASK_STATE_WORKING. The agent is still working.
Interrupted: TASK_STATE_INPUT_REQUIRED and TASK_STATE_AUTH_REQUIRED. The task waits for you.
Terminal: TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED. The task never changes again.
TASK_STATE_UNSPECIFIED: never sent by the kit. Treat it as an error.

Sources

One task, step by step

Client sends a blocking SendMessage with a new messageId and no taskId.
Server creates the task and mints its taskId and contextId.
Agent stops at TASK_STATE_INPUT_REQUIRED, and the call returns the task with its question.
Client answers with a second SendMessage with the same taskId and contextId.
Server returns the same task in TASK_STATE_COMPLETED, with its artifact.
Client calls GetTask with the taskId to read the stored task again.

Sources

JSON-RPC request

curl -s http://localhost:41242/a2a/jsonrpc \one URL for every operation

-H 'Content-Type: application/json' \JSON body

-H 'A2A-Version: 1.0' \required on every request

-d '{

"jsonrpc": "2.0",envelope version, always 2.0

"id": 1,the reply repeats this id

"method": "SendMessage",PascalCase operation name

"params": {"message": {

"messageId": "d95bafc8-f2a4-427b-9cf4-bb99f4bea973",minted by the client

"role": "ROLE_USER",the client always sends ROLE_USER

"parts": [{"text": "What languages can you review?"}]at least one part

}}

}'

Sources

Troubleshooting

Symptom	Cause	Fix
`-32009` on every call	No `A2A-Version` header	Send `A2A-Version: 1.0`
`-32601` with `message/send`	A 0.3 method name	Send `SendMessage`
`-32004` on a finished task	The task is terminal	Start a task with `referenceTaskIds` in the same context
`-32003` on a push config call	The card has no `pushNotifications` flag	Read the card before the call
`-32602` with a `BadRequest` detail	`message.messageId` is missing	Mint a `messageId` for every message
`-32001` or HTTP 404	The id is unknown, purged, or hidden	Check the id, then stop

Sources

Questions and answers

Why does a send wait?: The default returnImmediately is false. The call holds until a terminal or interrupted state.
Where is the result?: In artifacts. A message should not carry a task's output.
Why answer TaskNotFoundError for another caller's task?: The spec forbids revealing that a resource exists.

Sources

Tips

Mint a new messageId for each new message. Reuse it only to retry.
Send ROLE_USER from the client and ROLE_AGENT from the server.
Send historyLength 0 for a status check.
Read the card and check its capability flags before an optional call.

Sources

Original source

---
id: a2a
title: A2A Protocol
code: AP
subtitle: Cards, messages, tasks, states, the three bindings, errors and the 0.3 layer of A2A 1.0.1. Facts from the manual.
hue: 200
sources: manuals/a2a-101
source_hash: ad21d385000c4e28
---

## Protocol architecture
type: architecture
from: manuals/a2a-101/sections/1-1-what-a2a-standardizes.md, manuals/a2a-101/sections/2-1-agentcard-fields.md, manuals/a2a-101/sections/2-2-discovery-and-supported-interfaces.md, manuals/a2a-101/sections/5-1-json-rpc.md, manuals/a2a-101/sections/5-2-http-json.md, manuals/a2a-101/sections/7-2-a-server.md

```arch
node | planner | 1,1 | Planner | client, reads cards | client
node | card | 1,2 | AgentCard | /.well-known/agent-card.json | client
node | jsonrpc | 2,1 | JSON-RPC | /a2a/jsonrpc | process
node | handler | 3,1 | Handler | checks, then executor | process
node | rest | 3,2 | HTTP+JSON | /a2a/rest | process
node | store | 4,1 | Task store | record of each task | store
edge | planner | card | GET
edge | planner | jsonrpc | POST
edge | jsonrpc | handler | method
edge | rest | handler | route
edge | handler | store | task
```

## Send and read a task
type: task-table
from: manuals/a2a-101/sections/2-2-discovery-and-supported-interfaces.md, manuals/a2a-101/sections/4-1-send-message.md, manuals/a2a-101/sections/5-1-json-rpc.md, manuals/a2a-101/sections/5-4-version-and-extension-headers.md, manuals/a2a-101/capture/out/01-agent-cards.http

| Task | Code |
|---|---|
| Read the agent card | `GET /.well-known/agent-card.json HTTP/1.1` |
| Send one message | `"method": "SendMessage"` posted to `/a2a/jsonrpc` |
| Send the version | `A2A-Version: 1.0` |
| Send and return at once | `"returnImmediately": true` in `configuration` |
| Open a stream | `"method": "SendStreamingMessage"` |

## Commands over HTTP+JSON
type: command-table
from: manuals/a2a-101/sections/5-2-http-json.md, manuals/a2a-101/sections/4-4-cancel-task-and-terminal-states.md, manuals/a2a-101/capture/out/16-rest-binding.http

| Command | What it does |
|---|---|
| `POST /a2a/rest/message:send` | Sends a message. The reply is a task or a message. |
| `POST /a2a/rest/tasks/<task id>:cancel` | Asks the server to stop a task that is not terminal. |
| `GET /.well-known/agent-card.json` | Reads the agent card from the well-known path. |
| `POST /a2a/rest/tasks/<task id>:cancel` | Returns a task error when the task is already terminal. |

## Settings and defaults
type: defaults
from: manuals/a2a-101/sections/4-1-send-message.md, manuals/a2a-101/sections/4-3-get-task-and-list-tasks.md, manuals/a2a-101/sections/2-1-agentcard-fields.md, manuals/a2a-101/sections/5-4-version-and-extension-headers.md

| Setting | Default | Note |
|---|---|---|
| `returnImmediately` | false | A send waits for a terminal or interrupted state |
| `historyLength` | unset | The server decides how much history to return. `0` returns no history. |
| `pageSize` | 50 | The maximum in `ListTasks` is 100 |
| `includeArtifacts` | false | Artifacts are left out of list results |
| `A2A-Version` | 1.0 | Required on every request, with no patch number |

## Compare the bindings
type: comparison
from: manuals/a2a-101/sections/5-1-json-rpc.md, manuals/a2a-101/sections/5-2-http-json.md, manuals/a2a-101/sections/5-3-grpc.md, manuals/a2a-101/sections/5-5-errors.md, manuals/a2a-101/sections/5-4-version-and-extension-headers.md

| Factor | JSON-RPC | HTTP+JSON | gRPC |
|---|---|---|---|
| Operation named by | `method`, such as `SendMessage` | route, such as `POST /message:send` | rpc `SendMessage` in `A2AService` |
| Where it is sent | one URL, `/a2a/jsonrpc` in the kit | one route per operation | `lf.a2a.v1.A2AService` over HTTP/2 with TLS |
| Stream frame | a `data:` line with a full JSON-RPC response | a `data:` line with the `StreamResponse` alone | a server-streaming rpc of `StreamResponse` |
| `TaskNotFoundError` | `-32001` with HTTP 200 | HTTP 404 | `NOT_FOUND` |
| Version header | `A2A-Version` header | `A2A-Version` header | `a2a-version` metadata key |

## Task states
type: concepts
from: manuals/a2a-101/sections/3-4-task-and-task-state.md, manuals/a2a-101/sections/4-2-input-required-and-auth-required.md, manuals/a2a-101/sections/4-4-cancel-task-and-terminal-states.md

- **Active**: `TASK_STATE_SUBMITTED` and `TASK_STATE_WORKING`. The agent is still working.
- **Interrupted**: `TASK_STATE_INPUT_REQUIRED` and `TASK_STATE_AUTH_REQUIRED`. The task waits for you.
- **Terminal**: `TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`. The task never changes again.
- **TASK_STATE_UNSPECIFIED**: never sent by the kit. Treat it as an error.

## One task, step by step
type: flow
from: manuals/a2a-101/sections/1-1-what-a2a-standardizes.md, manuals/a2a-101/sections/3-1-message.md, manuals/a2a-101/sections/4-1-send-message.md, manuals/a2a-101/sections/4-2-input-required-and-auth-required.md, manuals/a2a-101/sections/4-3-get-task-and-list-tasks.md

1. **Client**: sends a blocking `SendMessage` with a new `messageId` and no `taskId`.
2. **Server**: creates the task and mints its `taskId` and `contextId`.
3. **Agent**: stops at `TASK_STATE_INPUT_REQUIRED`, and the call returns the task with its question.
4. **Client**: answers with a second `SendMessage` with the same `taskId` and `contextId`.
5. **Server**: returns the same task in `TASK_STATE_COMPLETED`, with its artifact.
6. **Client**: calls `GetTask` with the `taskId` to read the stored task again.

## JSON-RPC request
type: annotated-code
lang: bash
from: manuals/a2a-101/sections/5-1-json-rpc.md, manuals/a2a-101/sections/3-1-message.md, manuals/a2a-101/sections/5-4-version-and-extension-headers.md, manuals/a2a-101/capture/out/02-message-reply.http

```bash
curl -s http://localhost:41242/a2a/jsonrpc \  # one URL for every operation
  -H 'Content-Type: application/json' \  # JSON body
  -H 'A2A-Version: 1.0' \  # required on every request
  -d '{
    "jsonrpc": "2.0",  # envelope version, always 2.0
    "id": 1,  # the reply repeats this id
    "method": "SendMessage",  # PascalCase operation name
    "params": {"message": {
      "messageId": "d95bafc8-f2a4-427b-9cf4-bb99f4bea973",  # minted by the client
      "role": "ROLE_USER",  # the client always sends ROLE_USER
      "parts": [{"text": "What languages can you review?"}]  # at least one part
    }}
  }'
```

## Troubleshooting
type: troubleshooting
from: manuals/a2a-101/sections/5-4-version-and-extension-headers.md, manuals/a2a-101/sections/5-5-errors.md, manuals/a2a-101/sections/4-4-cancel-task-and-terminal-states.md, manuals/a2a-101/sections/7-4-from-0-3-to-1-0.md, manuals/a2a-101/sections/3-5-context-id.md

| Symptom | Cause | Fix |
|---|---|---|
| `-32009` on every call | No `A2A-Version` header | Send `A2A-Version: 1.0` |
| `-32601` with `message/send` | A 0.3 method name | Send `SendMessage` |
| `-32004` on a finished task | The task is terminal | Start a task with `referenceTaskIds` in the same context |
| `-32003` on a push config call | The card has no `pushNotifications` flag | Read the card before the call |
| `-32602` with a `BadRequest` detail | `message.messageId` is missing | Mint a `messageId` for every message |
| `-32001` or HTTP 404 | The id is unknown, purged, or hidden | Check the id, then stop |

## Questions and answers
type: qa
from: manuals/a2a-101/sections/4-1-send-message.md, manuals/a2a-101/sections/3-1-message.md, manuals/a2a-101/sections/3-3-artifact-and-chunks.md, manuals/a2a-101/sections/6-1-security-schemes-and-in-task-authorization.md

- **Why does a send wait?** The default `returnImmediately` is false. The call holds until a terminal or interrupted state.
- **Where is the result?** In `artifacts`. A message should not carry a task's output.
- **Why answer `TaskNotFoundError` for another caller's task?** The spec forbids revealing that a resource exists.

## Tips
type: tips
from: manuals/a2a-101/sections/3-1-message.md, manuals/a2a-101/sections/3-2-part.md, manuals/a2a-101/sections/4-3-get-task-and-list-tasks.md, manuals/a2a-101/sections/2-2-discovery-and-supported-interfaces.md

- Mint a new `messageId` for each new message. Reuse it only to retry.
- Send `ROLE_USER` from the client and `ROLE_AGENT` from the server.
- Send `historyLength` 0 for a status check.
- Read the card and check its capability flags before an optional call.