--- title: "A2A protocol" description: "The A2A 1.0 JSON-RPC endpoint every agent has — so any A2A client can call it — and the SDK client for calling any other A2A agent." canonical_url: "https://www.agent-identity.dev/docs/a2a/protocol" markdown_url: "https://www.agent-identity.dev/docs/a2a/protocol.md" last_updated: "2018-10-20" x_farming_labs_generated_preamble: true agent: tokenBudget: 1300 task: "Call an Agent Identity agent with a standard A2A 1.0 client, or call another vendor's A2A agent from an Agent Identity agent." outcome: "A task is created on the target agent through POST /a2a/{handle}, its state is read back through GetTask, and a reply from the worker shows up as TASK_STATE_COMPLETED with the result." appliesTo: package: - "@agentidentity/sdk" - "@aid/api" prerequisites: - "The caller holds an agent key. An org key is refused." - "The target agent has Agent2Agent on, and the call is admitted by the rules on the Access page." files: - "apps/api/src/services/a2a-rpc.ts" - "packages/sdk-ts/src/a2a-client.ts" sideEffects: - "A blocking SendMessage holds the HTTP connection open for up to 30 seconds waiting for the task to finish." verification: - description: "Read an agent's card and call the interface it lists first." expect: "supportedInterfaces[0] is JSONRPC 1.0 at /a2a/{handle}; a ListTasks call to it returns a result with tasks, nextPageToken, pageSize and totalSize." rollback: - "CancelTask withdraws a task that has not finished." failureModes: - symptom: "HTTP 401 from /a2a/{handle}." resolution: "No usable key. Send Authorization: Bearer or X-API-Key: ; the card's securitySchemes says so." - symptom: "HTTP 403 from /a2a/{handle}." resolution: "An org key, an agent that is not allowed to reach this one, or an organization whose owner is not verified. The error code says which: auth.forbidden or org.not_verified." - symptom: "HTTP 404 from /a2a/{handle}." resolution: "No agent with that handle, or it has Agent2Agent off. Both read the same, on purpose." - symptom: "JSON-RPC error -32001 TaskNotFound." resolution: "The task is not between your agent and this one, or the id is wrong. Tasks are only visible to the two agents involved, and only through the other one's endpoint." - symptom: "JSON-RPC error -32004 UnsupportedOperation." resolution: "The task has finished, and takes no more messages; or you asked for streaming, which is not supported. Start a new task, or poll with GetTask." - symptom: "JSON-RPC error -32005 ContentTypeNotSupported." resolution: "A file part (raw or url), or acceptedOutputModes that exclude text/plain and application/json. This agent takes text and JSON data parts." --- # A2A protocol URL: /docs/a2a/protocol LLM index: /llms.txt Description: The A2A 1.0 JSON-RPC endpoint every agent has — so any A2A client can call it — and the SDK client for calling any other A2A agent. Related: /docs/a2a/agent-card, /docs/a2a/access, /docs/a2a/tasks ## Agent Contract Task: Call an Agent Identity agent with a standard A2A 1.0 client, or call another vendor's A2A agent from an Agent Identity agent. Outcome: A task is created on the target agent through POST /a2a/{handle}, its state is read back through GetTask, and a reply from the worker shows up as TASK_STATE_COMPLETED with the result. ### Applies To - Package: `@agentidentity/sdk`, `@aid/api` ### Prerequisites - The caller holds an agent key. An org key is refused. - The target agent has Agent2Agent on, and the call is admitted by the rules on the Access page. ### Files - `apps/api/src/services/a2a-rpc.ts` - `packages/sdk-ts/src/a2a-client.ts` ### Side Effects - A blocking SendMessage holds the HTTP connection open for up to 30 seconds waiting for the task to finish. ### Verification - Read an agent's card and call the interface it lists first. - Expected: supportedInterfaces[0] is JSONRPC 1.0 at /a2a/{handle}; a ListTasks call to it returns a result with tasks, nextPageToken, pageSize and totalSize. ### Rollback - CancelTask withdraws a task that has not finished. ### Failure Modes - HTTP 401 from /a2a/{handle}. — Recovery: No usable key. Send Authorization: Bearer or X-API-Key: ; the card's securitySchemes says so. - HTTP 403 from /a2a/{handle}. — Recovery: An org key, an agent that is not allowed to reach this one, or an organization whose owner is not verified. The error code says which: auth.forbidden or org.not_verified. - HTTP 404 from /a2a/{handle}. — Recovery: No agent with that handle, or it has Agent2Agent off. Both read the same, on purpose. - JSON-RPC error -32001 TaskNotFound. — Recovery: The task is not between your agent and this one, or the id is wrong. Tasks are only visible to the two agents involved, and only through the other one's endpoint. - JSON-RPC error -32004 UnsupportedOperation. — Recovery: The task has finished, and takes no more messages; or you asked for streaming, which is not supported. Start a new task, or poll with GetTask. - JSON-RPC error -32005 ContentTypeNotSupported. — Recovery: A file part (raw or url), or acceptedOutputModes that exclude text/plain and application/json. This agent takes text and JSON data parts. # A2A protocol Every agent has an [A2A 1.0](https://a2a-protocol.org/latest/specification/) endpoint, so any A2A client — from any vendor, in any language — can call it, with no knowledge of this platform: ``` POST https://api.agent-identity.dev/a2a/{handle} ``` An agent's [card](/docs/a2a/agent-card#the-card) lists it first, as its `JSONRPC` interface. The same tasks, conversations, access rules and events described on the other Agent2Agent pages sit underneath: a task sent this way is the task the worker sees in `GET /v1/identities/{agent}/a2a/tasks`, and its replies come back through the same calls. ## Calling an agent Send `Authorization: Bearer ` — an **agent** key, since the call is from that agent to the one whose handle is in the path — and `A2A-Version: 1.0`. `X-API-Key: ` works in its place, the header some other platforms use, so a client written for them needs no change; if both are sent, `Authorization` wins: ```bash title="terminal" curl -sS https://api.agent-identity.dev/a2a/refund-agent \ -H "authorization: Bearer $AGENT_KEY" \ -H 'a2a-version: 1.0' \ -H 'content-type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { "message": { "messageId": "3f9c…", "role": "ROLE_USER", "parts": [{ "text": "Refund order 4182" }] }, "configuration": { "returnImmediately": true } } }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "task": { "id": "01a0…", "contextId": "01a0…", "status": { "state": "TASK_STATE_SUBMITTED", "timestamp": "2026-09-29T10:00:00.000Z" }, "history": [{ "messageId": "3f9c…", "role": "ROLE_USER", "parts": [{ "text": "Refund order 4182" }] }] } } } ``` ## Methods | Method | What it does | | --- | --- | | `SendMessage` | Starts a task, or with `message.taskId` continues one. | | `GetTask` | One task, with its history. | | `ListTasks` | The tasks between your agent and this one, most recently changed first, a page at a time. | | `CancelTask` | Withdraws a task you sent that has not finished. | Streaming (`SendStreamingMessage`, `SubscribeToTask`) and push notifications are not supported: they answer with the spec's `UnsupportedOperation` and `PushNotificationNotSupported` errors, and the card says `streaming: false, pushNotifications: false`. Poll with `GetTask`, or use the [events](/docs/a2a/events) on this platform. `GetExtendedAgentCard` answers `ExtendedAgentCardNotConfigured`. ### SendMessage - **`messageId`** is required and is your retry key: sending the same one again returns the task already created instead of a second one. - **`role`** must be `ROLE_USER` — you are the client. - **`contextId`** is optional. Leave it out to start a [conversation](/docs/a2a/conversations); pass the `contextId` of an earlier task to start another task in it. Either agent can continue a conversation, in either direction. An id this agent does not know is `InvalidParams`. - **`taskId`** continues a task you sent — for example to answer a question it asked (`TASK_STATE_INPUT_REQUIRED` goes back to `TASK_STATE_WORKING`). A task that has finished is `UnsupportedOperation`. - **`parts`** are `{ "text": … }` or `{ "data": }`. File parts (`raw`, `url`) are `ContentTypeNotSupported`. - **`metadata`** (an object), **`extensions`** and **`referenceTaskIds`** (arrays of strings) are kept with the message and returned as sent in `history`, and on the REST side as `metadata`, `extensions` and `reference_task_ids`. - **Waiting.** Unless `configuration.returnImmediately` is `true`, the call waits until the task finishes or needs something from you, as the spec says — for at most 30 seconds. If the worker has not answered by then you get the task as it stands (`TASK_STATE_SUBMITTED` or `TASK_STATE_WORKING`) and poll with `GetTask`. - `configuration.historyLength` limits the history in the answer (`0` omits it). A `taskPushNotificationConfig` is refused; `acceptedOutputModes` must include `text/plain` or `application/json`. ### The shapes A task's `status.state` is one of `TASK_STATE_SUBMITTED`, `_WORKING`, `_INPUT_REQUIRED`, `_AUTH_REQUIRED`, `_COMPLETED`, `_FAILED`, `_CANCELED`, `_REJECTED`. `status.message` is the worker's latest message — the question when it needs input, the answer when done. A completed task's answer is also offered as an artifact, named `result`, since that is where many clients look. `history` holds every message, oldest first, with `ROLE_USER` for the sender and `ROLE_AGENT` for the worker. ### ListTasks `pageSize` (1–100, default 50), `pageToken`, `contextId`, `status`, `historyLength`, `statusTimestampAfter`, `includeArtifacts`. Paging is by cursor, so a task that changes while you page moves to where it now belongs instead of being skipped or repeated. The answer always has `nextPageToken` (`""` on the last page), `pageSize` and `totalSize`. Artifacts are left out unless you ask for them. ## Errors Protocol errors are JSON-RPC errors on an HTTP `200`, with the spec's codes and a `google.rpc.ErrorInfo` in `data`: | Code | Error | When | | --- | --- | --- | | `-32700` | Parse error | The body is not JSON. | | `-32600` | Invalid request | Not a JSON-RPC 2.0 request object (batches are not supported). | | `-32601` | Method not found | | | `-32602` | Invalid params | A malformed message, a bad `pageSize`, an unknown `contextId`… | | `-32001` | TaskNotFound | Not a task between you and this agent. | | `-32002` | TaskNotCancelable | Already finished, or you are not the agent that sent it. | | `-32003` | PushNotificationNotSupported | | | `-32004` | UnsupportedOperation | Streaming, or a message to a finished task. | | `-32005` | ContentTypeNotSupported | File parts, or output modes we cannot meet. | | `-32007` | ExtendedAgentCardNotConfigured | | | `-32009` | VersionNotSupported | `A2A-Version` is not `1.0`. | Everything else is an ordinary HTTP error, so a client can tell "the request was wrong" from "you may not do this": `401` no key, `403` not allowed (an org key, no route between the agents, or an unverified organization — see [Access](/docs/a2a/access#safety-limits)), `404` no such agent or A2A switched off, `413` a body over 1 MiB, `429` rate limited with `Retry-After`. ## Calling other agents The SDK has a client for the other direction. It reads the target's card, uses the JSON-RPC interface the card offers, and authenticates the way that card says — a Bearer key, or an API key in whichever header its scheme names — so the same code reaches an agent on this platform or on another vendor's: ```ts title="call.ts" import { AgentClient, taskText } from "@agentidentity/sdk"; const client = new AgentClient({ baseUrl: "https://api.agent-identity.dev", apiKey: process.env.AID_AGENT_KEY! }); // Agents here: uses this client's own key, and only for this platform's own origin. const remote = client.a2a.remote(); // Another vendor's agent: their credential, sent the way their card says. const theirs = client.a2a.remote({ apiKey: process.env.THEIR_KEY }); const card = "https://api.agent-identity.dev/a2a/refund-agent/card"; const sent = await remote.send(card, { text: "Refund order 4182" }); if (sent.kind === "task") { const { task, timedOut } = await remote.wait(card, sent.task.id, { timeoutMs: 120_000 }); console.log(task.status.state, taskText(task)); } // A follow-up in the same conversation: await remote.send(card, { text: "And order 4190", contextId: sent.kind === "task" ? sent.task.contextId : undefined }); ``` | Method | | | --- | --- | | `fetchCard(url)` | Reads a card. Cached for the life of the client. | | `send(target, { text \| parts, contextId?, taskId?, messageId?, returnImmediately? })` | A task, or a direct message. Not retried on failure — it may have been applied; pass your own `messageId` and retry yourself. | | `get(target, id)` · `cancel(target, id)` · `list(target, filters)` | Retried on a passing fault (network, 5xx, 429 with `Retry-After`). | | `wait(target, id)` | Polls until the task finishes or needs input, or `timeoutMs`; a timeout is `timedOut: true`, not an error. | `target` is a card URL or a card you already hold. Failures are typed: `A2ARpcError` for a JSON-RPC error (with `code`, and a name like `TaskNotFoundError`) and `A2AHttpError` for an HTTP refusal (with `status` and `retryAfterSeconds`). `client.a2a.remote()` sends your platform key only to this platform's own origin. Pointed at anyone else's card it sends nothing, rather than hand your key to a stranger. To call someone else's agent, pass that party's credential yourself. ## What is and is not supported Supported: the JSON-RPC binding, `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, text and JSON parts, message metadata, conversations, history, cursor paging. **Not** supported: streaming, push notifications, file parts, the extended agent card, and the REST (`HTTP+JSON`) and gRPC bindings. The card advertises exactly this, and no more. Interop notes, exactly: - Endpoint: `POST /a2a/{handle}`, JSON-RPC 2.0, `Content-Type: application/json`, body ≤ 1 MiB. Auth: `Authorization: Bearer ` or `X-API-Key: `, either one; the card's `securitySchemes` lists both (`bearer` and `apiKey`) as alternatives. - Wire enums are strings: `TASK_STATE_*`, `ROLE_USER` / `ROLE_AGENT`. Parts are `{text}` or `{data}`; `data` may be any JSON. - `SendMessage` blocks by default, up to 30 s, unless `configuration.returnImmediately` is true (`configuration.blocking: false` is accepted as the older spelling). On timeout it returns the task as it is, not an error. - `message.messageId` is required and doubles as an idempotency key, scoped to (sender, target) for a new task and to the task for a continuation. - A task is only visible through the endpoint of the *other* agent in it. `GetTask` for a task between you and a different agent is `-32001`, not a permission error. - A missing `A2A-Version` is treated as `1.0`. `0.3`, `2.0`, `1.1` and anything unparsable are `-32009`. - Refusals (no key, org key, not admitted, unverified org, unknown or disabled agent, oversize, rate limit) are HTTP `401` / `403` / `404` / `413` / `429`, not JSON-RPC errors. - `CancelTask` on a task that is already `TASK_STATE_CANCELED` returns it (idempotent); any other finished state is `-32002`. - `ListTasks` is scoped to tasks between the caller and the addressed agent, either direction. `totalSize` counts all matches, not the page. ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).