A2A Task: Lifecycle, States, and Operations

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

FieldRequiredDescription
idYesUnique identifier, generated by the server when it creates the task
contextIdNoGroups the tasks and messages that belong to one conversation or session
statusYesA TaskStatus: the current state, an optional message, and an optional timestamp
artifactsNoThe outputs produced for this task, as Artifacts
historyNoThe Messages exchanged during the task
metadataNoA 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.

StateKindMeaning
TASK_STATE_SUBMITTEDActiveThe task has been submitted and acknowledged
TASK_STATE_WORKINGActiveThe agent is processing the task
TASK_STATE_INPUT_REQUIREDInterruptedThe agent needs more input from the user to continue
TASK_STATE_AUTH_REQUIREDInterruptedAuthentication is required to continue
TASK_STATE_COMPLETEDTerminalFinished successfully
TASK_STATE_FAILEDTerminalFinished with an error
TASK_STATE_CANCELEDTerminalCanceled before completion
TASK_STATE_REJECTEDTerminalThe 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 taskId for creating a new task is not supported.
  • When a client puts a taskId in a message, it MUST reference an existing task. Otherwise the agent returns TaskNotFoundError.

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 taskId is provided, the agent infers contextId from the task.
  • If both are provided and they do not match, the agent MUST reject the message.
  • A client can send a contextId without a taskId to start a new task inside an existing conversation.

Reading, listing, and canceling tasks

OperationWhat it doesNotable rules
GetTaskReturns the current state of one task, including status, artifacts, and optionally historyhistoryLength unset means no client limit, 0 means no history, and a positive number returns at most that many recent messages
ListTasksLists tasks the authenticated client can see, with filters and paginationFilter 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
CancelTaskRequests cancellation of a running taskNot guaranteed to succeed; a task that cannot be canceled returns TaskNotCancelableError
SubscribeToTaskOpens a stream of updates for an existing taskRequires 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 SendStreamingMessage and SubscribeToTask: low latency, needs a persistent connection and capabilities.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: when true, the call returns right after the task is created. When false (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.

ObservationClient actionMistake to avoid
SUBMITTED or WORKINGContinue with the agreed polling, streaming, or push delivery pathTreating a delayed update as proof that the server failed
INPUT_REQUIREDRead the status message, obtain the missing input, and send a new message referring to the existing taskResubmitting the original request as unrelated work
AUTH_REQUIREDResolve the requested authentication outside ordinary message text, then follow the server’s documented continuation flowPutting passwords or tokens into task history
COMPLETEDRead the available artifacts and check them against the application’s requested resultAssuming every completed task must produce a file or that a nonempty artifact proves correctness
FAILED, CANCELED, or REJECTEDPresent the outcome and decide whether a separate new request is appropriateTrying 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 behaviorTreating the closed stream as cancellation or completion
The event connection closes without a terminal or interrupted stateRetrieve the current task before deciding whether work needs to be resubmittedEquating 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:

  1. 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.
  2. 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.
  3. 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

Source: A2A official specification: Core Objects, Operations, and Multi-Turn Interactions and Life of a Task