Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 12 of 16

A2A tasks & artifacts

0 of 16 complete

Why it matters

A single HTTP response is a poor container for work that takes minutes, needs clarification or produces several files. Without a task abstraction, teams build ad hoc job tables and status endpoints per integration. A2A standardises the lifecycle so a caller can submit, observe, answer and collect in a predictable way, and so a timeout does not destroy the work.

Mental model

A task is a work order in a job shop: it gets a number, moves through stages, may wait for customer input and ends with a deliverable. The metaphor breaks because the customer and the shop are software agents, so the wait for input must be represented as data rather than a phone call.

How it works

The message that moves each task stateInteractive

A2A 1.0.0. Grey dotted rows are remote-side writes to the task record, not protocol messages. The caller only sees the task and the SSE events.

Caller

submits and answers

Remote

does the work

Task

durable record

Step 1/6 · TASK_STATE_SUBMITTED
stream · TASK_STATE_SUBMITTEDreturn · Remote → Caller
data: {"jsonrpc":"2.0","id":1,"result":{
  "task": {
    "id": "t-8842",
    "contextId": "c-17",
    "status": { "state": "TASK_STATE_SUBMITTED" },
    "history": [{
      "messageId": "m-01",
      "role": "ROLE_USER",
      "parts": [{ "text": "Reconcile March" }] }] } }}

Step 1: TASK_STATE_SUBMITTED. Hover, tap or tab to any message to inspect its payload.

Figure. Each state is written by the remote and reported to the caller; creation and resumption are caused by the caller's message. SendStreamingMessage opens the stream that carries TASK_STATE_WORKING, TASK_STATE_INPUT_REQUIRED, artifact and completion events, and the task record keeps the same id throughout.

What to notice. The failure is treating a pause as an ending. A caller that reads TASK_STATE_INPUT_REQUIRED as failure abandons a task that is still open, and one that retries task creation instead of answering duplicates the work. A long working state is normal; only an explicit terminal state means stop.

Text version

Sequence across Caller, Remote and a remote-side Task record in A2A 1.0. Step 1, TASK_STATE_SUBMITTED: Caller to Remote SendStreamingMessage with messageId m-01, ROLE_USER and a text part; Remote to Task an internal remote-side write creating the record in TASK_STATE_SUBMITTED with a Message history; Remote to Caller a SSE task event with taskId t-8842, contextId c-17 and TASK_STATE_SUBMITTED. Step 2, TASK_STATE_WORKING: Remote to Task an internal write to TASK_STATE_WORKING; Remote to Caller a SSE statusUpdate event with TASK_STATE_WORKING. Step 3, TASK_STATE_INPUT_REQUIRED: Remote to Caller a SSE statusUpdate event with TASK_STATE_INPUT_REQUIRED and a ROLE_AGENT message asking which entity; the task record keeps its id. Step 4, resume: Caller to Remote SendMessage with the answer on task t-8842; Remote to Task an internal write back to TASK_STATE_WORKING. Step 5, artifact: Remote to Caller a SSE artifactUpdate event with an Artifact and text part. Step 6, TASK_STATE_COMPLETED: Remote to Caller a SSE statusUpdate event with TASK_STATE_COMPLETED. Task writes are remote-side implementation, not protocol messages.

  1. Create the task with a message containing parts, and store the returned task id with the caller's own correlation id.
  2. Track state transitions: submitted, working, input-required, completed, failed, canceled and rejected.
  3. On input-required, read the requested schema and send the missing parts as a new message on the same task.
  4. Stream or poll status with a bounded interval, and treat a long working state as normal rather than as a failure.
  5. Collect artefacts by id or reference, and verify access before reading their content.
  6. Cancel explicitly when the caller no longer needs the result, and record the terminal state.

Trade-offs

ChoiceGood forCostFails when
Polling statusWorks everywhereLatency and wasted callsThe task changes state frequently
Streaming updatesFast feedbackConnection lifetime and reconnect logicThe client sits behind a short timeout
Push notification on completionEfficient for long tasksCallback security and delivery failureThe caller has no public endpoint
Large artefacts by referenceKeeps context smallExtra fetch and access controlThe artefact must be embedded in a report
Trade-off mapInteractive

Good for

Works everywhere

Cost

Latency and wasted calls

Fails when

The task changes state frequently

  1. The task changes state frequently
  2. The client sits behind a short timeout
  3. The caller has no public endpoint
  4. The artefact must be embedded in a report

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Polling status is good for Works everywhere, costs Latency and wasted calls, and fails when The task changes state frequently. Streaming updates is good for Fast feedback, costs Connection lifetime and reconnect logic, and fails when The client sits behind a short timeout. Push notification on completion is good for Efficient for long tasks, costs Callback security and delivery failure, and fails when The caller has no public endpoint. Large artefacts by reference is good for Keeps context small, costs Extra fetch and access control, and fails when The artefact must be embedded in a report

Failure modes

  • Duplicate task creation. A retry after a timeout creates a second task and the work happens twice. Debug: log client request ids and compare the count of created tasks per id.
  • Stuck input-required. The caller treats input-required as failure and never answers, leaving the task open. Debug: list tasks by state and age and alert on input-required beyond a threshold.
  • Artefact access unchecked. An artefact URL is guessable and readable without the caller's credentials. Debug: request an artefact with a different token and confirm denial.

In production

Monitor time in each state and the rate of tasks that never reach a terminal state. The specification defines the states and artefact model, while retention and reaping are implementation policy, so keep a reaper for abandoned tasks and a cap on artefacts per task.

Common misconceptions

People think: A task is just a long request.

Actually: It is a stateful object with a lifecycle, and the connection may close many times before it finishes.

People think: input-required means the task failed.

Actually: It is a pause for information; the caller resumes the same task rather than creating a new one.

Interview angle

A strong answer walks the state machine and explains idempotency, resumption and artefact handling. It also covers what happens when the caller disappears. Weak answers describe a request-response call with a longer timeout.

Sources