A2A Task: Lifecycle, States, and Operations
A Task is the core unit of action in A2A. It has an identity, a current status, the results produced so far, and the messages exchanged along the way. An agent does not have to create a task for every request: it can answer a Message directly, or start a task when the work needs to be tracked over time. Life of a Task explains when each fits.
Implementing task execution? The Task runtime guide connects states, messages, event streams and recovery. For duplicate requests and restart behavior, use Task idempotency and recovery .
Fields
| Field | Required | Description |
|---|---|---|
id | Yes | Unique identifier, generated by the server when it creates the task |
contextId | No | Groups the tasks and messages that belong to one conversation or session |
status | Yes | A TaskStatus: the current state, an optional message, and an optional timestamp |
artifacts | No | The outputs produced for this task, as Artifacts |
history | No | The Messages exchanged during the task |
metadata | No | A key-value object for custom metadata |
The timestamp in TaskStatus is an ISO 8601 UTC string, for example 2024-03-15T11:00:00Z.
Task states
Every task is in exactly one of eight states. A terminal state ends the task. An interrupted state pauses it until the client acts.
| State | Kind | Meaning |
|---|---|---|
TASK_STATE_SUBMITTED | Active | The task has been submitted and acknowledged |
TASK_STATE_WORKING | Active | The agent is processing the task |
TASK_STATE_INPUT_REQUIRED | Interrupted | The agent needs more input from the user to continue |
TASK_STATE_AUTH_REQUIRED | Interrupted | Authentication is required to continue |
TASK_STATE_COMPLETED | Terminal | Finished successfully |
TASK_STATE_FAILED | Terminal | Finished with an error |
TASK_STATE_CANCELED | Terminal | Canceled before completion |
TASK_STATE_REJECTED | Terminal | The agent decided not to perform the task, at creation or later |
There is also TASK_STATE_UNSPECIFIED, which means the state is unknown. It is not part of a normal lifecycle.
Once a task is terminal it cannot restart. A refinement or follow-up starts a new task in the same contextId, which keeps every task a clear, immutable unit of work. Sending a message to a task in a terminal state returns UnsupportedOperationError.
Creating a task
A client does not create a task directly. It sends a message with SendMessage (or SendStreamingMessage) and the agent decides whether to answer with a Task or a Message. Two identifier rules follow from the specification:
- Task IDs are always server-generated. A client-provided
taskIdfor creating a new task is not supported. - When a client puts a
taskIdin a message, it MUST reference an existing task. Otherwise the agent returnsTaskNotFoundError.
A task that completes immediately
This is the specification’s basic scenario: the client asks a question and the response is a completed task that already carries an artifact. The request:
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
Authorization: Bearer token
{
"message": {
"role": "ROLE_USER",
"parts": [{"text": "What is the weather today?"}],
"messageId": "msg-uuid"
}
}The response:
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"task": {
"id": "task-uuid",
"contextId": "context-uuid",
"status": {"state": "TASK_STATE_COMPLETED"},
"artifacts": [{
"artifactId": "artifact-uuid",
"name": "Weather Report",
"parts": [{"text": "Today will be sunny with a high of 75°F"}]
}]
}
}A task that needs more input
When the agent cannot finish without more information, it moves the task to TASK_STATE_INPUT_REQUIRED and explains what it needs in the status message. The client continues by sending a new message with the same taskId (and contextId). The first request:
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
Authorization: Bearer token
{
"message": {
"role": "ROLE_USER",
"parts": [{"text": "Book me a flight"}],
"messageId": "msg-1"
}
}The agent responds with an interrupted task:
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"task": {
"id": "task-uuid",
"status": {
"state": "TASK_STATE_INPUT_REQUIRED",
"message": {
"role": "ROLE_AGENT",
"parts": [{"text": "I need more details. Where would you like to fly from and to?"}]
}
}
}
}The follow-up carries the taskId:
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
Authorization: Bearer token
{
"message": {
"taskId": "task-uuid",
"role": "ROLE_USER",
"parts": [{"text": "From San Francisco to New York"}],
"messageId": "msg-2"
}
}The same contextId and taskId rules apply across turns:
- If only
taskIdis provided, the agent inferscontextIdfrom the task. - If both are provided and they do not match, the agent MUST reject the message.
- A client can send a
contextIdwithout ataskIdto start a new task inside an existing conversation.
Reading, listing, and canceling tasks
| Operation | What it does | Notable rules |
|---|---|---|
GetTask | Returns the current state of one task, including status, artifacts, and optionally history | historyLength unset means no client limit, 0 means no history, and a positive number returns at most that many recent messages |
ListTasks | Lists tasks the authenticated client can see, with filters and pagination | Filter by contextId, status, or statusTimestampAfter; cursor-based pagination with pageSize (default 50, maximum 100) and pageToken; newest status first; artifacts are omitted unless includeArtifacts is true; nextPageToken is an empty string on the last page |
CancelTask | Requests cancellation of a running task | Not guaranteed to succeed; a task that cannot be canceled returns TaskNotCancelableError |
SubscribeToTask | Opens a stream of updates for an existing task | Requires capabilities.streaming; returns UnsupportedOperationError for a task already in a terminal state |
Getting updates
A2A offers three complementary ways to follow a task:
- Polling with
GetTask: simple, works with every binding, with higher latency. - Streaming with
SendStreamingMessageandSubscribeToTask: low latency, needs a persistent connection andcapabilities.streaming: true. - Push notifications: the agent sends an HTTP POST to a webhook the client registered. They need
capabilities.pushNotifications: true.
A streaming response starts with either a single Message or a Task. For a task, the stream begins with the Task object, continues with zero or more statusUpdate and artifactUpdate events, and closes when the task reaches a terminal state. At an interrupted state the specification is not uniform about closing, so a client reads the last state instead of treating a closed stream as a verdict. Events are delivered in the order they were generated. This trace shows one artifact streamed in two chunks with the same artifactId, then the terminal state:
HTTP/1.1 200 OK
Content-Type: text/event-stream
data: {"task": {"id": "task-8f20", "contextId": "ctx-41ab", "status": {"state": "TASK_STATE_WORKING"}}}
data: {"artifactUpdate": {"taskId": "task-8f20", "contextId": "ctx-41ab", "artifact": {"artifactId": "artifact-77c3", "name": "trip-plan.md", "parts": [{"text": "# Trip Plan\n\nDay 1: "}]}}}
data: {"artifactUpdate": {"taskId": "task-8f20", "contextId": "ctx-41ab", "append": true, "lastChunk": true, "artifact": {"artifactId": "artifact-77c3", "name": "trip-plan.md", "parts": [{"text": "arrive, check in, sunset walk."}]}}}
data: {"statusUpdate": {"taskId": "task-8f20", "contextId": "ctx-41ab", "status": {"state": "TASK_STATE_COMPLETED"}}}The same trace appears on the Artifact and Streaming and Asynchronous Operations pages. When a stream ends or drops, the runtime guide’s recovery path picks the next client action from the task state.
Send options that affect tasks
SendMessage takes an optional configuration:
returnImmediately: whentrue, the call returns right after the task is created. Whenfalse(the default), the agent waits until the task reaches a terminal or interrupted state before returning.historyLength: the maximum number of recent history messages to include in the response.acceptedOutputModes: the media types the client can accept, which the agent should use to tailor its output.taskPushNotificationConfig: the webhook to notify about task updates.
Choose the next client action from the state
A task state should drive the client’s next action, rather than merely the label shown in a user interface. The following decision table combines the lifecycle and identifier rules above into a client implementation aid.
| Observation | Client action | Mistake to avoid |
|---|---|---|
SUBMITTED or WORKING | Continue with the agreed polling, streaming, or push delivery path | Treating a delayed update as proof that the server failed |
INPUT_REQUIRED | Read the status message, obtain the missing input, and send a new message referring to the existing task | Resubmitting the original request as unrelated work |
AUTH_REQUIRED | Resolve the requested authentication outside ordinary message text, then follow the server’s documented continuation flow | Putting passwords or tokens into task history |
COMPLETED | Read the available artifacts and check them against the application’s requested result | Assuming every completed task must produce a file or that a nonempty artifact proves correctness |
FAILED, CANCELED, or REJECTED | Present the outcome and decide whether a separate new request is appropriate | Trying to reopen the terminal task by reusing its ID |
The stream closes with an interrupted state (INPUT_REQUIRED or AUTH_REQUIRED) | Answer it as an interrupted task: provide the input or resolve the authentication, then continue per the server’s documented behavior | Treating the closed stream as cancellation or completion |
| The event connection closes without a terminal or interrupted state | Retrieve the current task before deciding whether work needs to be resubmitted | Equating a lost connection with task cancellation |
State names in this table omit the TASK_STATE_ prefix for readability. The protocol defines the states; timeouts, retry budgets, and the decision to create replacement work belong to the application. A retry policy must also consider whether a previous request may already have produced side effects. See Task idempotency and recovery
before automatically submitting another message.
Work through an interrupted task and a lost response
Consider the flight-booking exchange above. The server creates a task, asks for departure and destination, and reports TASK_STATE_INPUT_REQUIRED. The client’s useful next step is to collect those details and send a new message referring to the same task. The client does not manufacture another task ID to mean “turn two.”
Now suppose the connection drops after that follow-up was sent. The client cannot infer whether the server accepted it. If it retained the task ID, it can use GetTask to inspect the current state. A working task calls for continued observation; another input-required state calls for reading the new question; a terminal task calls for handling that outcome. A missing task is a distinct error to investigate, including task identity, endpoint, and authorization, rather than evidence that the original operation had no effect.
Three checks make this sequence easier to diagnose:
- Keep identity separate from content. Retain the server-generated task ID and any context ID separately from message text. When both IDs are supplied, they must refer to the same context. A new task can share the old context without sharing the old task ID.
- Distinguish transport outcome from task outcome. HTTP errors, a closed stream, and task states answer different questions. Record the operation and last known state before deciding to retry. A cancellation request can fail and is not itself evidence of
TASK_STATE_CANCELED. - Verify the result after completion. Read the artifacts that are available and validate the requested business outcome. If the user asks for a refinement after completion, start new work in the same context rather than mutating the old terminal task.
These are worked diagnosis cases derived from the specification, not a runnable booking service or a claim of live interoperability testing. For executable event validation and more failure cases, continue with the Task runtime guide .
Related pages
- Task Runtime Guide : delivery modes, what each state allows, a runnable event-stream validator, and fixes for common failures.
- Message , Part , and Artifact : the objects a task carries.
- Data Structures and Common Workflows and Examples : the field reference and more full exchanges.
Source: A2A official specification: Core Objects, Operations, and Multi-Turn Interactions and Life of a Task