04. A2A Messages, Tasks & Execution Lifecycle¶
A remote agent receives: “Review this invoice, explain the discrepancy, and attach a reconciliation report.”
What comes back? Not necessarily one neat string.
The agent may acknowledge the request, ask for the purchase order, spend time checking records, report progress, attach a report—or fail because a downstream service is unavailable. A2A models these outcomes explicitly instead of pretending every agent interaction is a synchronous function call.
The mental model is simple: Messages communicate. Tasks track work. Parts carry content. Contexts connect related interactions. Artifacts hold results.
1. A2A Message Architecture¶
A Message is one unit of communication between a client and an agent. It can initiate work, provide clarification, or add information to an existing task.
A Task is different: it represents work whose progress and outcome may need to be tracked.
| Object | Think of it as |
|---|---|
| Message | A communication turn |
| Task | A tracked unit of work |
| Part | One content segment |
| Context | A logical conversation grouping |
| Artifact | A task output |
flowchart LR
C["Client"] -->|"Message"| A["A2A Agent"]
A --> T["Task"]
T --> S["Status"]
T --> O["Artifacts"]
C <-->|"Follow-up messages"| A
C -. "contextId groups related work" .-> T A SendMessage operation returns either a direct Message or a Task. It does not return both in the same response. Simple interactions can avoid task tracking; longer or stateful work benefits from a Task. A2A v1.0 specification
2. Message Roles and Structure¶
A Message includes a unique messageId, a sender role, and one or more parts. It may also carry contextId, taskId, metadata, extensions and references to related tasks.
| Field | Purpose |
|---|---|
messageId | Unique identifier created by the message sender |
role | ROLE_USER or ROLE_AGENT |
parts | Content segments |
contextId | Associates the message with a conversation context |
taskId | Associates it with an existing task |
referenceTaskIds | References related tasks |
metadata | Optional application or extension data |
A client request might look like this:
{
"message": {
"messageId": "msg-7f21",
"role": "ROLE_USER",
"contextId": "ctx-invoice-42",
"parts": [
{
"text": "Explain the variance in invoice INV-2048.",
"mediaType": "text/plain"
}
]
}
}
The role identifies who sent the message—not whether its content is trustworthy. Treat remote content as untrusted input, validate it, and enforce authorization independently.
3. Parts and Multimodal Content¶
A Part is a content segment inside a Message or Artifact. One message can combine text, a file and structured data.
A2A v1.0 defines four content forms:
text— human-readable text.raw— file bytes, base64-encoded in JSON.url— a reference to externally hosted content.data— structured JSON content.
{
"messageId": "msg-evidence-18",
"role": "ROLE_USER",
"parts": [
{"text": "Compare the invoice with this evidence."},
{
"url": "https://files.example.com/invoice-2048.pdf",
"mediaType": "application/pdf",
"filename": "invoice-2048.pdf"
},
{
"data": {"invoiceId": "INV-2048", "currency": "EUR"},
"mediaType": "application/json"
}
]
}
The mediaType tells the receiver how to interpret the content. It does not guarantee that the agent can process it. Check the agent's advertised input modes and validate the actual content type.
A URL is not permission to fetch arbitrary resources. Apply host allow-lists, authentication, payload limits, MIME validation and malware scanning. For raw file content, limit size and avoid logging file bytes.
4. Contexts and Conversation Continuity¶
A contextId groups related Messages and Tasks. A taskId identifies one specific unit of work. They are related, but not interchangeable.
For an invoice investigation:
ctx-42groups the overall conversation.task-101retrieves the invoice.task-102compares a purchase order supplied later.msg-103carries the user's clarification.
flowchart TB
C["contextId: ctx-42"]
C --> T1["taskId: task-101"]
C --> T2["taskId: task-102"]
C --> M["Message: msg-103"]
T1 --> A1["Invoice summary"]
T2 --> A2["Reconciliation report"] The agent may generate a context when the client does not provide one; if it does, the returned Task or Message must include it. An agent may accept a client-provided context or reject it if it cannot support it. It must not silently replace an unsupported client context with a different one.
Practical rule: treat server-generated context IDs as opaque. Clients should not invent context IDs unless they understand how that server handles them. A client can use a known contextId to start another task in the same conversation, or include a taskId to continue a particular task. If both are supplied, they must refer to the same context.
A context ID is not an authorization token or a guaranteed memory store. Persistence, tenant isolation and context expiry remain implementation responsibilities.
5. Task Creation and Identification¶
When an interaction needs tracking, the server creates a Task and assigns its unique id. The Task includes a status and may include history, artifacts and metadata.
{
"id": "task-101",
"contextId": "ctx-42",
"status": {
"state": "TASK_STATE_SUBMITTED",
"timestamp": "2026-11-14T10:15:00Z"
},
"history": []
}
The client should persist the returned task ID if it needs to retrieve status, continue the interaction or request cancellation. A message ID identifies a message; a task ID identifies work. Never substitute one for the other.
6. Task States and Lifecycle Transitions¶
A2A v1.0 defines these Task states:
| State | Meaning | Lifecycle |
|---|---|---|
TASK_STATE_SUBMITTED | Request acknowledged | Non-terminal |
TASK_STATE_WORKING | Agent is processing | Non-terminal |
TASK_STATE_INPUT_REQUIRED | More user input is needed | Interrupted |
TASK_STATE_AUTH_REQUIRED | Authentication is needed | Interrupted |
TASK_STATE_COMPLETED | Work succeeded | Terminal |
TASK_STATE_FAILED | Work ended with an error | Terminal |
TASK_STATE_CANCELED | Work was canceled | Terminal |
TASK_STATE_REJECTED | Agent declined the work | Terminal |
stateDiagram-v2
[*] --> SUBMITTED
SUBMITTED --> WORKING
SUBMITTED --> REJECTED
WORKING --> INPUT_REQUIRED
INPUT_REQUIRED --> WORKING
WORKING --> AUTH_REQUIRED
AUTH_REQUIRED --> WORKING
WORKING --> COMPLETED
WORKING --> FAILED
WORKING --> CANCELED
COMPLETED --> [*]
FAILED --> [*]
CANCELED --> [*]
REJECTED --> [*] This is a conceptual path, not a mandatory sequence every Task must follow. An agent can reject work early; it can pause for input or authentication and resume later. Terminal states mean that Task is finished. A new unit of work requires a new Task, though it can belong to the same Context.
7. Task Status Updates¶
A TaskStatus contains the current state, an optional explanatory Message and a timestamp. A TaskStatusUpdateEvent identifies the taskId and contextId and carries the new status.
Good progress updates answer “what changed?”:
- “Invoice located; validating line items.”
- “Waiting for the purchase order attachment.”
- “Reconciliation completed.”
Keep status messages useful and safe. They are not a place for internal reasoning, secrets, raw database output or debug traces.
A client may receive status and artifact events while work is running. These events are covered here as lifecycle concepts; detailed streaming, reconnection and push-delivery design belongs in Chapter 41.
8. Artifacts and Generated Outputs¶
Messages are for communication. Artifacts are for task outputs. A Task can produce one or more Artifacts, each containing one or more Parts.
{
"artifactId": "reconciliation-report",
"name": "Invoice reconciliation",
"description": "Comparison of invoice and purchase order line items",
"parts": [
{
"data": {
"invoiceId": "INV-2048",
"currency": "EUR",
"variance": 125.50,
"finding": "Shipping charge differs from purchase order"
},
"mediaType": "application/json"
}
]
}
An artifact can be a document, image, text result or structured payload. It may arrive as a complete object or as incremental artifact updates. The update includes the artifact and can indicate whether content should be appended and whether the last chunk has arrived.
Do not mistake a progress message for the deliverable. A2A separates status communication from task outputs so clients can track work and consume results independently.
9. Multi-Turn Interactions¶
Suppose the invoice agent cannot proceed until it knows the currency. It moves the Task to TASK_STATE_INPUT_REQUIRED and explains what it needs. The client replies with a new Message that references the same task and context.
sequenceDiagram
participant U as Client
participant A as Invoice Agent
U->>A: Review invoice (message, context ctx-42)
A-->>U: Task task-101: INPUT_REQUIRED
U->>A: Currency is EUR (task-101)
A->>A: Resume investigation
A-->>U: Task task-101: WORKING
A-->>U: Task task-101: COMPLETED
A-->>U: Reconciliation artifact A follow-up message can reference taskId alone; the server infers the task's context. If the client sends both identifiers, they must match. A client can also send only a known contextId to begin a new Task within that conversation.
The protocol provides correlation, not unlimited memory. The agent decides what history to retain and how to use it. Define retention, expiry and tenant isolation explicitly.
10. Task Cancellation and Failure Handling¶
A cancellation request does not prove that work has stopped. The task may already have completed, the agent may be unable to interrupt a downstream operation, or cancellation may be rejected. Check the resulting Task state.
For task management, the core operations include:
| Operation | Purpose |
|---|---|
GetTask | Retrieve current task state and available results |
CancelTask | Request cancellation |
The JSON-RPC binding exposes these as GetTask and CancelTask methods. For example, a task lookup uses the task ID:
{
"jsonrpc": "2.0",
"id": 12,
"method": "GetTask",
"params": {
"id": "task-101",
"historyLength": 10
}
}
A robust client distinguishes three failure classes:
- Transport failure: timeout, connection reset or DNS failure. The remote outcome may be unknown.
- Protocol failure: malformed request, unsupported operation, authentication or authorization error.
- Task failure: the agent accepted the work but could not complete it; the Task reaches
TASK_STATE_FAILED.
A timeout is not an A2A Task state. It describes what the caller knows: the response did not arrive. The remote Task may still be running or may already have completed. If the task ID is known, retrieve its status before deciding to resubmit. For side-effecting operations, add application-level idempotency and duplicate detection.
Key Takeaways¶
- Messages carry communication; Tasks track work; Artifacts carry outputs.
- Parts support text, raw files, URLs and structured data.
contextIdgroups related interactions;taskIdidentifies one unit of work.- Task states distinguish active, interrupted and terminal outcomes.
- Status messages report progress; Artifacts carry deliverables.
- Cancellation is a request, not confirmation.
- A timeout leaves the remote outcome uncertain; it does not prove task failure.
Review Questions¶
- How does a Message differ from a Task and an Artifact?
- What content forms can a Part carry?
- Why are
contextIdandtaskIdseparate identifiers? - Which Task states are terminal, and which represent interruption?
- Why should a client not treat a status message as the final output?
- How can a client continue a Task that requires more input?
- Why is retrying a timed-out side-effecting request dangerous?
References¶
- A2A Protocol v1.0 Specification — Data Model and Operations
- A2A Protocol — Life of a Task
- A2A Protocol — Core Concepts
🧠Chapter Navigation¶
⬅️ Previous: 03. Building A2A Agents & Clients
📚 Part: AI Engineering Frameworks & Tooling
➡️ Next: 05. A2A Streaming & Asynchronous Communication
Enterprise AI Engineering Handbook
Building Production-Grade Enterprise AI Systems — One Chapter at a Time.