A2A Task Lifecycle
Before writing code
Fetch live docs:
- Fetch
https://a2a-protocol.org/latest/specification/ for the Task object schema and state machine
- Web-search
site:github.com a2aproject A2A task lifecycle states for state transition rules
- Web-search
site:github.com a2aproject a2a-samples task for task handling examples
- Fetch SDK docs for task-related classes and state management utilities
Conceptual Architecture
What a Task Is
A Task is the central unit of work in A2A. It represents a request from a client agent to a server agent, tracks progress through well-defined states, accumulates messages and artifacts, and reaches a terminal state when complete.
Task Structure
Key fields of a Task object:
- id — Unique task identifier (set by client or server)
- status — Current state object containing
state enum and optional message
- messages — Array of messages exchanged (if
stateTransitionHistory enabled)
- artifacts — Array of output artifacts produced by the agent
- metadata — Optional key-value pairs for custom data
The 9 States
| State |
Terminal? |
Description |
submitted |
No |
Task received, queued for processing |
working |
No |
Agent actively processing |
input-required |
No |
Agent needs more input (multi-turn) |
auth-required |
No |
Authentication needed |
completed |
Yes |
Task finished successfully |
failed |
Yes |
Task encountered an unrecoverable error |
canceled |
Yes |
Task was canceled |
rejected |
Yes |
Server refused the task |
unknown |
— |
Default/unknown state |
Valid State Transitions
submitted → working
submitted → rejected
submitted → canceled
working → completed
working → failed
working → canceled
working → input-required
input-required → working (when client provides more input)
input-required → canceled
auth-required → working (when auth is provided)
auth-required → canceled
Rules:
- Terminal states (
completed, failed, canceled, rejected) are final — no transitions out
- Only the server transitions the task state (except
canceled which client can request)
input-required → working happens when the client sends a follow-up message
Task Creation
Tasks are created implicitly when a client sends a message without a taskId:
- Client sends
message/send or message/stream without taskId
- Server creates a new task, assigns an ID
- Task starts in
submitted state
- Server may immediately transition to
working or return submitted
Task Continuation
When a client sends a message with an existing taskId:
- The message is appended to the task's history
- The server resumes processing
- State typically transitions from
input-required back to working
Artifacts
Artifacts are the outputs of a task:
- Produced during
working state
- Each artifact has
id, name, optional description, and parts
- Parts can be TextPart, FilePart, or DataPart
- In streaming mode, artifacts are delivered incrementally via
TaskArtifactUpdateEvent
- Multiple artifacts can be produced per task
State Transition History
If the agent declares stateTransitionHistory: true in its Agent Card:
- The task object includes a complete history of all state transitions
- Each transition records the state, timestamp, and optional message
- Useful for auditing and debugging
Best Practices
- Always validate state transitions — reject invalid ones with appropriate errors
- Use task IDs that are globally unique (UUIDs recommended)
- Store task state durably for production (not just in-memory)
- Set timeouts for tasks stuck in non-terminal states
- Clean up old tasks to prevent unbounded storage growth
- Include meaningful messages in status updates (not just the state enum)
- Use artifacts for structured outputs, messages for conversational exchanges
- Implement idempotency — handle duplicate messages for the same task gracefully
Fetch the specification for the exact Task object schema, state enum values, and transition validation rules before implementing.
1---2name: a2a-task-lifecycle3description: Implement A2A task lifecycle management — task creation, state transitions, terminal states, history, and artifacts. Use when building task state machines, handling state transitions, or managing task persistence.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/a2a-task-lifecycle7---89# A2A Task Lifecycle1011## Before writing code1213**Fetch live docs**:141. Fetch `https://a2a-protocol.org/latest/specification/` for the Task object schema and state machine152. Web-search `site:github.com a2aproject A2A task lifecycle states` for state transition rules163. Web-search `site:github.com a2aproject a2a-samples task` for task handling examples174. Fetch SDK docs for task-related classes and state management utilities1819## Conceptual Architecture2021### What a Task Is2223A Task is the **central unit of work** in A2A. It represents a request from a client agent to a server agent, tracks progress through well-defined states, accumulates messages and artifacts, and reaches a terminal state when complete.2425### Task Structure2627Key fields of a Task object:28- **id** — Unique task identifier (set by client or server)29- **status** — Current state object containing `state` enum and optional `message`30- **messages** — Array of messages exchanged (if `stateTransitionHistory` enabled)31- **artifacts** — Array of output artifacts produced by the agent32- **metadata** — Optional key-value pairs for custom data3334### The 9 States3536| State | Terminal? | Description |37|-------|-----------|-------------|38| `submitted` | No | Task received, queued for processing |39| `working` | No | Agent actively processing |40| `input-required` | No | Agent needs more input (multi-turn) |41| `auth-required` | No | Authentication needed |42| `completed` | Yes | Task finished successfully |43| `failed` | Yes | Task encountered an unrecoverable error |44| `canceled` | Yes | Task was canceled |45| `rejected` | Yes | Server refused the task |46| `unknown` | — | Default/unknown state |4748### Valid State Transitions4950```51submitted → working52submitted → rejected53submitted → canceled5455working → completed56working → failed57working → canceled58working → input-required5960input-required → working (when client provides more input)61input-required → canceled6263auth-required → working (when auth is provided)64auth-required → canceled65```6667**Rules:**68- Terminal states (`completed`, `failed`, `canceled`, `rejected`) are final — no transitions out69- Only the server transitions the task state (except `canceled` which client can request)70- `input-required` → `working` happens when the client sends a follow-up message7172### Task Creation7374Tasks are created implicitly when a client sends a message without a `taskId`:751. Client sends `message/send` or `message/stream` without `taskId`762. Server creates a new task, assigns an ID773. Task starts in `submitted` state784. Server may immediately transition to `working` or return `submitted`7980### Task Continuation8182When a client sends a message with an existing `taskId`:831. The message is appended to the task's history842. The server resumes processing853. State typically transitions from `input-required` back to `working`8687### Artifacts8889Artifacts are the **outputs** of a task:90- Produced during `working` state91- Each artifact has `id`, `name`, optional `description`, and `parts`92- Parts can be TextPart, FilePart, or DataPart93- In streaming mode, artifacts are delivered incrementally via `TaskArtifactUpdateEvent`94- Multiple artifacts can be produced per task9596### State Transition History9798If the agent declares `stateTransitionHistory: true` in its Agent Card:99- The task object includes a complete history of all state transitions100- Each transition records the state, timestamp, and optional message101- Useful for auditing and debugging102103### Best Practices104105- Always validate state transitions — reject invalid ones with appropriate errors106- Use task IDs that are globally unique (UUIDs recommended)107- Store task state durably for production (not just in-memory)108- Set timeouts for tasks stuck in non-terminal states109- Clean up old tasks to prevent unbounded storage growth110- Include meaningful messages in status updates (not just the state enum)111- Use artifacts for structured outputs, messages for conversational exchanges112- Implement idempotency — handle duplicate messages for the same task gracefully113114Fetch the specification for the exact Task object schema, state enum values, and transition validation rules before implementing.