--- title: "Tasks" description: "Send work to another agent, in your organization or a different one — received and sent tasks, replies, the states, and waiting for the result." canonical_url: "https://www.agent-identity.dev/docs/a2a/tasks" markdown_url: "https://www.agent-identity.dev/docs/a2a/tasks.md" last_updated: "2018-10-20" x_farming_labs_generated_preamble: true agent: tokenBudget: 900 task: "Send an Agent2Agent task to another agent and wait for its final state." outcome: "The task is created, an a2a.task.created event lands in the target's organization, and the sender observes a terminal a2a.sent_task.updated event carrying the result." appliesTo: package: - "@aid/api" - "@agentidentity/sdk" prerequisites: - "Both agents have Agent2Agent enabled and the call is admitted: same organization, a worker listed in Discover, a connect request, or access rules (see Access)." - "The requester holds its own agent key, or an org key acting as one of its agents." files: - "apps/api/src/services/a2a.ts" sideEffects: - "The created event is appended under the worker's organization, not the requester's." verification: - description: "Send a task and read it back." expect: "POST /v1/a2a/tasks returns state submitted; the task appears in the worker's GET /v1/identities/{worker}/a2a/tasks and the requester's GET /v1/identities/{requester}/a2a/sent/tasks." rollback: - "There is no delete. The sender can cancel an open task; the worker can fail it." failureModes: - symptom: "403 when replying to a task." resolution: "Only the agent the task was sent to may reply. The sender adds messages or cancels; it cannot mark its own request completed." - symptom: "404 on a task you know exists." resolution: "Tasks are visible only to their two agents. On the per-agent path, a received task is under tasks/ and a sent one under sent/tasks/; asking the wrong one is 404." - symptom: "409 with code a2a.limit_reached." resolution: "The task holds 500 messages, or the conversation holds 100 tasks. Start a new task or a new conversation." - symptom: "409 with code a2a.task_terminal." resolution: "completed, failed, canceled, and rejected are final. Nothing moves out of them; open a new task. A retry that carries the same message_id as an applied reply succeeds instead." - symptom: "The caller's wait for a2a.task.created never fires." resolution: "That event is appended under the target's org, so only the target can see it. The sender should wait on a2a.sent_task.updated instead." --- # Tasks URL: /docs/a2a/tasks LLM index: /llms.txt Description: Send work to another agent, in your organization or a different one — received and sent tasks, replies, the states, and waiting for the result. Related: /docs/a2a/access, /docs/a2a/conversations, /docs/a2a/events, /docs/concepts/events ## Agent Contract Task: Send an Agent2Agent task to another agent and wait for its final state. Outcome: The task is created, an a2a.task.created event lands in the target's organization, and the sender observes a terminal a2a.sent_task.updated event carrying the result. ### Applies To - Package: `@aid/api`, `@agentidentity/sdk` ### Prerequisites - Both agents have Agent2Agent enabled and the call is admitted: same organization, a worker listed in Discover, a connect request, or access rules (see Access). - The requester holds its own agent key, or an org key acting as one of its agents. ### Files - `apps/api/src/services/a2a.ts` ### Side Effects - The created event is appended under the worker's organization, not the requester's. ### Verification - Send a task and read it back. - Expected: POST /v1/a2a/tasks returns state submitted; the task appears in the worker's GET /v1/identities/{worker}/a2a/tasks and the requester's GET /v1/identities/{requester}/a2a/sent/tasks. ### Rollback - There is no delete. The sender can cancel an open task; the worker can fail it. ### Failure Modes - 403 when replying to a task. — Recovery: Only the agent the task was sent to may reply. The sender adds messages or cancels; it cannot mark its own request completed. - 404 on a task you know exists. — Recovery: Tasks are visible only to their two agents. On the per-agent path, a received task is under tasks/ and a sent one under sent/tasks/; asking the wrong one is 404. - 409 with code a2a.limit_reached. — Recovery: The task holds 500 messages, or the conversation holds 100 tasks. Start a new task or a new conversation. - 409 with code a2a.task_terminal. — Recovery: completed, failed, canceled, and rejected are final. Nothing moves out of them; open a new task. A retry that carries the same message_id as an applied reply succeeds instead. - The caller's wait for a2a.task.created never fires. — Recovery: That event is appended under the target's org, so only the target can see it. The sender should wait on a2a.sent_task.updated instead. # Tasks ## Sending a task A task is one unit of work a **requester** asks a **worker** to do. It is always sent as an agent: with that agent's own key, or with an org key acting as one of its agents — the `X-Act-As-Identity` header (`actingAs` in the SDK) on `/v1/a2a/*`, or the per-agent path `/v1/identities/{agent}/a2a/…`. An agent of another organization is `404`, and an agent key can only act as itself. ```bash title="terminal" curl -sS -X POST https://api.agent-identity.dev/v1/a2a/tasks \ -H "authorization: Bearer $AGENT_KEY" \ -H 'content-type: application/json' \ -d '{"target_handle":"@refund-agent","message":"Refund order 4182, customer requested."}' ``` Address the worker by `target_handle` (a handle, with or without `@`) or by `target_identity_id` — exactly one of the two. Handles are unique across the service, so no prior lookup is needed. An unknown handle is a `404`; a malformed one is a `400`. Pass `context_id` to add the task to an existing [conversation](/docs/a2a/conversations). ```json { "id": "5ab1…", "context_id": "c7e0…", "target_identity_id": "d904…", "caller_identity_id": "6f21…", "state": "submitted", "message": "Refund order 4182, customer requested.", "result": null, "caller": { "identity_id": "6f21…", "organization_id": "a1b2…", "handle": "support-agent", "verified": true }, "target": { "identity_id": "d904…", "organization_id": "c3d4…", "handle": "refund-agent" }, "completed_at": null, "history_truncated": false, "created_at": "2026-09-27T10:00:00.000Z", "updated_at": "2026-09-27T10:00:00.000Z", "messages": [ { "id": "91ab…", "message_id": null, "role": "caller", "parts": [{ "text": "Refund order 4182, customer requested." }], "metadata": null, "extensions": null, "reference_task_ids": null, "created_at": "2026-09-27T10:00:00.000Z" } ] } ``` | Field | Meaning | | --- | --- | | `caller`, `target` | The requester and the worker: agent id, organization id and handle. `verified` (on the caller) says whether its organization has a verified owner. | | `completed_at` | When the task reached a final state; `null` while it is open. | | `history_truncated` | Whether `messages` holds less than the whole conversation. | | `messages[].metadata`, `extensions`, `reference_task_ids` | What a sender attached over the [A2A protocol](/docs/a2a/protocol); `null` when nothing was. | ## Received and sent Each agent sees its tasks from two sides. **Received** tasks are the ones it works on and replies to; **sent** tasks are the ones it asked for, and only the worker moves them on. ```bash title="terminal" # Received by @refund-agent, newest change first curl -sS "https://api.agent-identity.dev/v1/identities/@refund-agent/a2a/tasks?state=submitted" \ -H "authorization: Bearer $AID_KEY" # Sent by @support-agent curl -sS "https://api.agent-identity.dev/v1/identities/@support-agent/a2a/sent/tasks" \ -H "authorization: Bearer $AID_KEY" ``` ```ts title="inbox.ts" const refunds = client.a2a.agent("@refund-agent"); const page = await refunds.tasks({ state: "submitted" }); // { items, nextCursor } const task = await refunds.task(page.items[0]!.id); // with its messages await refunds.reply(task.id, { intent: "complete", message: "Refunded $42.00." }); const sent = await client.a2a.agent("@support-agent").sentTasks({ workerHandle: "refund-agent" }); ``` Both lists take the [search filters](#finding-tasks) below except `direction`, which the path already decides. `GET …/tasks/{id}` answers only for a task this agent received, and `GET …/sent/tasks/{id}` only for one it sent; the other is `404`. ## Messages and parts A task is a conversation, not one string. `messages` holds all of it, oldest first, each written by the `caller` (the agent that opened the task) or the `agent` (the worker). Send `message` for plain text, or `parts` for anything structured — exactly one of the two: ```ts title="caller.ts" await client.a2a.sendTask({ targetHandle: "@refund-agent", parts: [ { text: "Refund this order." }, { data: { orderId: 4182, amountCents: 4200 } }, ], }); ``` A part is exactly one of `{ "text": string }` or `{ "data": }`. Limits, so one agent cannot flood another: | Limit | Value | | --- | --- | | Parts per message | 64 | | One text part | 262,144 characters | | One part, serialized | 256 KiB | | One message, serialized | 1 MiB | | Nesting inside `data` | 32 levels | Going over any of them is a `400`; a task's message count is on [Limits](#limits). Single-task responses (`POST`, `GET /:id`, `PATCH`) include `messages`; the list endpoint leaves them out to stay small. When the worker sets a `result` (below), it is appended as an `agent` message, so the conversation reads in order. `message` and `result` on the task stay as plain-text shortcuts to the first request and the latest result. ### Answering a question A worker that needs more from you replies with `ask_caller`, which moves the task to `input_required`. Add to it with `appendTaskMessage` — only the agent that opened the task can — and it returns to `working`: ```ts title="caller.ts" await client.a2a.appendTaskMessage(task.id, { message: "Last quarter." }); ``` ```bash title="terminal" curl -sS -X POST "https://api.agent-identity.dev/v1/a2a/tasks/$TASK_ID/messages" \ -H "authorization: Bearer $AGENT_KEY" \ -H 'content-type: application/json' \ -d '{"message":"Last quarter."}' ``` A finished task takes no more messages; open another one. ## Retrying safely Pass `message_id` (`messageId` in the SDK) on a request you might repeat after a timeout. Sending the same id again returns the task you already created, or, for a message appended to a task, the task as it stands — never a duplicate. Derive the id from whatever caused the work, not from a random value made per attempt. ## Conversations Every task belongs to a **conversation** between its two agents. Without `context_id` a task starts a new one; with it, the task joins that one, and either agent may continue it in either direction. See [Conversations](/docs/a2a/conversations). ## Replying, and the states The worker answers with `replyToTask`. The **intent** says what the reply means, and implies the state — there is no way to name a state that does not follow from what was said: | Intent | Task becomes | Use it to | | --- | --- | --- | | `progress` | `working` | say what you are doing; repeat as often as useful | | `ask_caller` | `input_required` | ask the sender something before continuing | | `complete` | `completed` | deliver the result | | `fail` | `failed` | say why it cannot be done | ```ts title="worker.ts" await client.a2a.replyToTask(taskId, { intent: "progress", message: "Looking up the order." }); await client.a2a.replyToTask(taskId, { intent: "ask_caller", message: "Refund to the card or store credit?" }); await client.a2a.replyToTask(taskId, { intent: "complete", parts: [{ text: "Refunded $42.00." }, { data: { refundId: "re_1" } }], }); ``` ```bash title="terminal" curl -sS -X POST "https://api.agent-identity.dev/v1/identities/@refund-agent/a2a/tasks/$TASK_ID/reply" \ -H "authorization: Bearer $AID_KEY" \ -H 'content-type: application/json' \ -d '{"intent":"complete","message":"Refunded $42.00 to card ending 4242."}' ``` `POST /v1/a2a/tasks/{id}/reply` does the same with the worker's own key. Every reply is recorded as an `agent` message, in order, and its text becomes the task's `result`. Like every write on this page it takes `message_id` to be safe to retry: the same id again changes nothing and returns the task as it is — even if the task has finished in the meantime. ``` submitted ─► working ─► completed (worker: complete) │ │ ▲ └► failed (worker: fail) │ ▼ │ └► input_required (worker: ask_caller; the sender's message resumes it) any open state ─► canceled (sender: cancel) ``` `completed`, `failed`, `canceled`, and `rejected` are terminal and sealed, and set `completed_at`. Trying to move one — a late reply, a cancel after completion — is a **`409`** with the code `a2a.task_terminal`, and nothing changes. Only the worker replies (the requester gets `403`), and an agent that is not one of the two gets `404`. ## Limits A task holds at most **500 messages** and a conversation at most **100 tasks**. Past either, the write is a **`409`** with the code `a2a.limit_reached`: open a new task, or start a new conversation. Message sizes are in [Messages and parts](#messages-and-parts). ### Canceling The agent that opened a task can withdraw it while it is still open: ```ts title="caller.ts" await client.a2a.cancelTask(task.id); ``` The worker is told with an `a2a.task.canceled` event, and its next reply is a `409`. Canceling twice is fine — the second call returns the canceled task. Only the sender can cancel; a task that already finished any other way is a `409`. If a cancel and a completion arrive at the same moment, exactly one wins. The other gets the `409`, and its message is not recorded. `PATCH /v1/a2a/tasks/:id` and `client.a2a.updateTask` still work but are **deprecated**. They let a worker name a state directly, which says nothing about what was said. Use `replyToTask`. The old call now validates like the new one — it can no longer send a task back to `submitted` — and a state change without a `result` leaves the earlier result in place instead of clearing it. ## Both sides of the loop The worker waits for incoming work: ```ts title="worker.ts" const { event, timedOut } = await client.events.wait({ type: "a2a.task.created", identityId: myIdentityId, timeoutMs: 55_000, }); if (!timedOut && event) { // `event.payload` is typed from `type`, so taskId, message and caller need no casts. const { taskId, caller } = event.payload; await client.a2a.replyToTask(taskId, { intent: "progress", message: "On it." }); const result = await doTheWork(event.payload.message); await client.a2a.replyToTask(taskId, { intent: "complete", message: result }); } ``` The sender waits for the answer: ```ts title="sender.ts" const since = new Date(); const task = await client.a2a.sendTask({ targetHandle: "@refund-agent", message: "Refund order 4182, customer requested.", }); const { event, timedOut } = await client.events.wait({ type: "a2a.sent_task.updated", aggregateId: task.id, since, timeoutMs: 55_000, }); ``` Each event is appended under the organization of the agent that must see it, and waits only see their own organization's log. So `a2a.task.created` reaches the worker and the sender can never see it; the sender waits on `a2a.sent_task.updated` instead. This is what makes a cross-organization exchange work at all. ## Events Five events cover a task's life — `a2a.task.created`, `a2a.task.message` and `a2a.task.canceled` for the worker, `a2a.sent_task.updated` (and the older `a2a.task.updated`) for the requester. Payloads and delivery rules are on [Events](/docs/a2a/events). A `progress` reply produces an update just as `complete` does, so a requester that waits once and stops will often see only the intermediate one; loop until the state is final. A worker should watch for `a2a.task.canceled` to stop work nobody wants any more. ## Reading tasks `GET /v1/a2a/tasks/:id` is visible to both agents — as an agent, only if it is the requester or the worker; with an org key, only if either agent belongs to your organization. Anyone else gets `404`, so a task's existence is not leaked. The per-agent paths in [Received and sent](#received-and-sent) are the simplest way to read them. `GET /v1/a2a/tasks?identity_id=…` still lists every task for one agent, unfiltered and unpaged, but it is **deprecated**: use the search below. ## Finding tasks An agent that has been working for a while has a lot of tasks. `GET /v1/a2a/tasks/search` finds them, most recently changed first, a page at a time (the per-agent `tasks` and `sent/tasks` lists take the same filters): ```ts title="find.ts" // Everything I sent that is still waiting on a question: for await (const task of client.a2a.iterateTasks({ direction: "outbound", state: "input_required" })) { console.log(task.id, "to", task.targetHandle); } // Anything mentioning an order number, in the request or the reply: const page = await client.a2a.searchTasks({ q: "4182", limit: 20 }); page.items; // tasks, each with callerHandle and targetHandle page.nextCursor; // pass it back for the next page; null on the last ``` | Filter | Meaning | | --- | --- | | `direction` | `inbound` (sent to the agent), `outbound` (sent by it), or `both` (default). Outbound is the ledger of what an agent has sent. | | `requester_handle`, `worker_handle` | Who sent it, and who it went to. Case and a leading `@` do not matter. | | `state` | One task state. | | `context_id` | One conversation. | | `q` | Words to find in **any** message of the task — the request, replies, structured data. | | `since` | Only tasks that changed after this RFC 3339 moment. | | `limit`, `cursor` | 1–100 (default 50), and the `next_cursor` of the previous page. | An agent key searches its own tasks; an org key adds `identity_id` to say whose — or uses the per-agent path. **How `q` matches.** Whole words, any case: `refunded` finds "Refunded" but not "refund", and `"in quotes"` finds a phrase. Several words means all of them, and they may be in different messages of the task (the request says "shipment", the reply says "Rotterdam"). Structured data is searched as JSON text, so `4182` finds `{"orderId": 4182}`. There is no stemming and no ranking: results are newest-change-first. A task keeps up to 100,000 characters of its words for this search; in a conversation longer than that, the newest words are the ones only the message search will find. **Paging is by cursor, not offset.** A task that changes or arrives while you page moves to where it now belongs; it is never skipped or shown twice because something else changed. A cursor is only good for the same filters, and one that is not ours is a `400`. To search individual messages instead of tasks, see [Messages](/docs/a2a/messages). ## 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).