Task lifecycle

A task is a stateful unit of work performed by an agent. When you send a message to an agent, the response is either a direct Message (for quick operations) or a Task (for longer-running work). Tasks have a defined lifecycle, can produce artifacts, and can be streamed in real time.

What is a task

A task represents work that an agent performs in response to a message. It has:

A unique prefixed UUIDv7 identifier (task.0192f4c8-...)
A contextId linking it to a context for conversation continuity
A status with a current state and timestamp
A history array of messages exchanged during the task
An artifacts array of outputs produced by the task
metadata including token and credit accounting under $usage

The agent decides whether to respond with a Task or a Message. Quick operations (short completions, classifications) often return a Message directly. Longer workflows return a Task that you monitor for completion.

Task states

A task moves through the following states:

State	Description
`TASK_STATE_SUBMITTED`	The task has been accepted by the agent but processing has not started
`TASK_STATE_WORKING`	The agent is actively processing the task
`TASK_STATE_COMPLETED`	The task finished successfully; artifacts are available
`TASK_STATE_FAILED`	The task failed; check the status message for error details
`TASK_STATE_CANCELED`	The task was canceled by the client
`TASK_STATE_INPUT_REQUIRED`	The agent needs additional input before it can continue
`TASK_STATE_AUTH_REQUIRED`	An MCP connector requires authentication; the task pauses until auth is provided
`TASK_STATE_REJECTED`	The task was rejected before processing (insufficient credits or invalid agent configuration)

TASK_STATE_REJECTED and TASK_STATE_AUTH_REQUIRED are only visible on the JSON-RPC binding. On the REST (HTTP+JSON) binding, both are mapped to TASK_STATE_FAILED with a descriptive status message.

Terminal vs non-terminal states

Category	States
Terminal (immutable, cannot be canceled or resumed)	`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`
Non-terminal (can be resumed or canceled)	`TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING`, `TASK_STATE_INPUT_REQUIRED`, `TASK_STATE_AUTH_REQUIRED`

Canceling a task in a terminal state returns 409 Conflict.

State transitions

A task transitions through states as follows:

TASK_STATE_SUBMITTED to TASK_STATE_WORKING: The agent begins processing.
TASK_STATE_SUBMITTED to TASK_STATE_REJECTED: The task was rejected before processing (insufficient credits or invalid configuration).
TASK_STATE_SUBMITTED to TASK_STATE_AUTH_REQUIRED: An MCP connector requires authentication before the agent can proceed.
TASK_STATE_WORKING to TASK_STATE_COMPLETED: The task finishes successfully.
TASK_STATE_WORKING to TASK_STATE_FAILED: An error occurred during processing.
TASK_STATE_WORKING to TASK_STATE_INPUT_REQUIRED: The agent paused and needs user input.
TASK_STATE_WORKING to TASK_STATE_AUTH_REQUIRED: An MCP connector encountered an auth error during execution.
TASK_STATE_AUTH_REQUIRED to TASK_STATE_WORKING: Auth is resolved and the agent resumes.
TASK_STATE_INPUT_REQUIRED to TASK_STATE_WORKING: The user provides input and the agent resumes.
Any non-terminal state to TASK_STATE_CANCELED: The client cancels the task via tasks/{id}:cancel.

A task in TASK_STATE_INPUT_REQUIRED or TASK_STATE_AUTH_REQUIRED state is not terminated. Send a new message with the required input (for TASK_STATE_INPUT_REQUIRED) or resolve the connector authentication (for TASK_STATE_AUTH_REQUIRED) to resume processing. The SSE stream closes when either state is reached; you must send a new message or re-subscribe to continue receiving updates.

Task history and messages

The history array contains all messages exchanged during the task, oldest first. Each message has:

messageId: A prefixed UUIDv7 (e.g. msg.0192f4c8-...)
role: Either ROLE_USER (sent by the client) or ROLE_AGENT (sent by the agent)
parts: An ordered list of content parts (text, file, or data)
metadata: Free-form metadata, including Corti’s $timestamp for timing

You can control how much history the agent considers by setting configuration.historyLength on the message send request.

Artifacts

Artifacts are the tangible outputs a task produces. Each artifact has:

artifactId: A prefixed UUIDv7 (e.g. art.0192f4c8-...)
name: An optional human-readable name
parts: Content parts containing the artifact data

Artifacts are closely tied to the task lifecycle. In production scenarios, artifacts typically correspond to business outputs like notes, coding suggestions, or extracted facts. You can retrieve a specific artifact via:

GET /v2/agentic/contexts/{contextId}/tasks/{taskId}/artifacts/{artifactId}

Inline citations

When the orchestrator answers using data it retrieved from connectors, the answer artifact’s text part carries citation metadata that links each claim to its source data part. The text part metadata contains a citations array of entries, each with data_part_id (the GID of the cited part), offset (character offset into the joined artifact text), and locator (a JSON Pointer or line range). Each cited data part is a sibling part in the same artifact, carrying its GID in metadata.dataPartId. Resolve a citation by joining data_part_id to the part whose metadata.dataPartId matches.

Inline citations are produced by the orchestrator only. Connector (expert) sub-answers do not embed citation markers; their outputs are data parts that the orchestrator then cites or passes through.

See Render inline citations for the marker format, the full metadata shape, and rendering recipes.

Streaming events

When you stream a message via message:stream or subscribe to an existing task via tasks/{id}:subscribe, the server sends Server-Sent Events (SSE). Each event carries an A2AStreamResponse with exactly one of the following fields:

Field	Description
`task`	The full task object, sent when the task is first created or when its state changes
`message`	A direct message response (no task lifecycle)
`statusUpdate`	An incremental status change with `taskId`, `contextId`, `status`, and `metadata` (no `final` flag; clients infer finality from the task state)
`artifactUpdate`	An incremental artifact update with `taskId`, `contextId`, `artifact`, `append`, and `lastChunk`

Token-by-token streaming

As the model generates its answer, the answer text streams as a sequence of artifactUpdate events (one text fragment per event) rather than as status updates. The first delta sets append to false (the artifact is being created); each subsequent delta sets append to true. A closing event with lastChunk: true consolidates the deltas into a single canonical text part (append: false = replace). lastChunk closes one artifact, not the run. A run may emit several lastChunk: true artifacts, for example an intermediate-thinking narration followed by the final answer. The run ends on the closing statusUpdate with a terminal state (TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED), or an interrupted state (TASK_STATE_INPUT_REQUIRED, TASK_STATE_AUTH_REQUIRED) that also closes the stream.

On the v1.0 (A2A 1.0) surface, a TASK_STATE_COMPLETED statusUpdate carries no answer message. The answer is the completion artifact whose lastChunk: true event preceded the terminal status. The statusUpdate carries usage and credit metadata in metadata.

If the model streamed text and then called a tool, or ended in TASK_STATE_INPUT_REQUIRED or TASK_STATE_FAILED, the streamed narration is closed as an intermediate-thinking artifact (with artifact.metadata.type: "intermediate-thinking") before the terminal status. Do not render it as the final answer. See Stream responses for the full delta event format, append/lastChunk semantics, and client best practices.

SSE event format

Each SSE frame follows the W3C SSE wire format:

Field	Description
`data`	The JSON-encoded payload (an `A2AStreamResponse`)
`event`	Event type (declared for forward compatibility; not currently sent by the server)
`id`	Opaque event ID (the server writes event IDs but does not yet read `Last-Event-ID` for resumption)
`retry`	Reconnection interval (declared for forward compatibility; not currently sent by the server)

Example SSE event

For a streamed answer, the server emits one artifactUpdate per token delta, then a closing lastChunk event with the consolidated text, then the terminal statusUpdate:

data: {"task":{"id":"task.0192f4c8-...","contextId":"ctx.0192f4c8-...","status":{"state":"TASK_STATE_WORKING","timestamp":"2026-05-19T12:00:00Z"}}}

data: {"artifactUpdate":{"taskId":"task.0192f4c8-...","contextId":"ctx.0192f4c8-...","artifact":{"artifactId":"art.0192f4c8-...","parts":[{"text":"J45.909"}]}}}

data: {"artifactUpdate":{"taskId":"task.0192f4c8-...","contextId":"ctx.0192f4c8-...","append":true,"artifact":{"artifactId":"art.0192f4c8-...","parts":[{"text":" — mild intermittent asthma."}]}}}

data: {"artifactUpdate":{"taskId":"task.0192f4c8-...","contextId":"ctx.0192f4c8-...","lastChunk":true,"artifact":{"artifactId":"art.0192f4c8-...","parts":[{"text":"J45.909 — mild intermittent asthma."}]}}}

data: {"statusUpdate":{"taskId":"task.0192f4c8-...","contextId":"ctx.0192f4c8-...","status":{"state":"TASK_STATE_COMPLETED","timestamp":"2026-05-19T12:00:01Z"}}}

For answers that arrive whole (for example, a single completion-tool result with no token streaming), the artifact arrives in one lastChunk: true event as shown in the streaming guide.

Resumption with Last-Event-ID

The server writes event IDs but does not yet read the Last-Event-ID request header, so resumption without gaps is not implemented. The section below describes the intended design for when this feature ships.

The intended resumption mechanism is to send the Last-Event-ID header with the most recent event ID you received. The server will replay events from that point forward once implemented. This will work with both message:stream and tasks/{id}:subscribe. See Stream responses for implementation details.

Task metadata and usage

Each task carries metadata with Corti’s first-party keys prefixed with $. The $usage object provides token and credit accounting:

Field	Description
`model`	The model identifier that served the request
`inputTokens`	Prompt tokens consumed
`outputTokens`	Completion tokens produced
`cachedInputTokens`	Subset of `inputTokens` served from the prompt cache (a discount)
`cacheCreationInputTokens`	Input tokens written to the prompt cache (cache-write surcharge)
`totalTokens`	Total tokens billed (`inputTokens` + `outputTokens`)
`credits`	Corti billing credits charged for the task

{
  "$usage": {
    "model": "corti-default",
    "inputTokens": 100,
    "outputTokens": 20,
    "cachedInputTokens": 64,
    "cacheCreationInputTokens": 0,
    "totalTokens": 120,
    "credits": 1.2
  }
}

You can use this data for cost tracking, budget monitoring, and evaluating cache effectiveness across your agents.

Next steps

Learn how to send a message and handle task or message responses
Learn how to stream responses via SSE
Read about contexts to understand how tasks are grouped

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

What is a task

Task states

Terminal vs non-terminal states

State transitions

Task history and messages

Artifacts

Inline citations

Streaming events

Token-by-token streaming

SSE event format

Example SSE event

Resumption with Last-Event-ID

Task metadata and usage

Next steps

​What is a task

​Task states

​Terminal vs non-terminal states

​State transitions

​Task history and messages

​Artifacts

​Inline citations

​Streaming events

​Token-by-token streaming

​SSE event format

​Example SSE event

​Resumption with Last-Event-ID

​Task metadata and usage

​Next steps

What is a task

Task states

Terminal vs non-terminal states

State transitions

Task history and messages

Artifacts

Inline citations

Streaming events

Token-by-token streaming

SSE event format

Example SSE event

Resumption with Last-Event-ID

Task metadata and usage

Next steps