a2a-task-lifecycle

name	a2a-task-lifecycle
description	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.

A2A Task Lifecycle

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for the Task object schema and state machine
2. Web-search site:github.com a2aproject A2A task lifecycle states for state transition rules
3. Web-search site:github.com a2aproject a2a-samples task for task handling examples
4. 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:

1. Client sends message/send or message/stream without taskId
2. Server creates a new task, assigns an ID
3. Task starts in submitted state
4. Server may immediately transition to working or return submitted

Task Continuation

When a client sends a message with an existing taskId:

1. The message is appended to the task's history
2. The server resumes processing
3. 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.