Learn A2A - Task Lifecycle & Messages

#Introduction

In episode 3 we understood how an agent is discovered through the Agent Card. Now we enter the heart of execution: what happens after a client sends work. All of it is governed by the Task lifecycle and Message/Part.

Episode 4 answers two questions: where is a task in its journey? and how is the conversation's content represented? By mastering both concepts, you'll read and write A2A traffic without confusion.

#Task: The Unit of Work in A2A

A Task is a single unit of work in A2A — one request from a client agent completed by the remote agent. Each task carries an identifier, a status, and a message history. Because a task is a JSON object, its entire progress can be queried at any time.

{
  "id": "task-7f3a",
  "status": {
    "state": "working",
    "message": {
      "role": "agent",
      "parts": [
        {
          "text": "Sedang memproses laporan keuangan..."
        }
      ]
    }
  },
  "messages": [],
  "metadata": {
    "request_id": "req-0001"
  }
}

The id field anchors the entire conversation that follows. status reflects the task's current position, messages stores the full history, and metadata holds additional data agreed upon by both parties.

#Task State Machine

Task status flows through a standardized state machine. There is no status outside this list:

submitted --> working --> input-required <--+--> completed
                  |                            |
                  +-----> failed               |
                  +-----> canceled <-----------+

• submitted — the task was just received by the remote agent, not yet processed.
• working — the remote agent is working on the task.
• input-required — the agent needs additional information from the client before continuing; the task pauses, waiting for a new message.
• completed — the work is done and the final result is available.
• failed — an error occurred; the failure details are carried within the status.
• canceled — the task was canceled, either by the client or by the remote agent.

The transition from working to input-required is the primary mechanism for the human-in-the-loop pattern — when the agent encounters a problem that needs a human decision. A client receiving this status sends a reply message, and the task continues from working again. When you practice later, you can observe this transition directly with curl -s -N http://localhost:8080/sse?taskId=task-7f3a.

#Task Progress and Metadata

A long-running task can't just sit in silence. A2A provides two mechanisms to make progress visible:

{
  "status": {
    "state": "working",
    "progress": {
      "current": 2,
      "total": 5,
      "message": "Meringkas halaman 2 dari 5"
    }
  }
}

• progress — a current and total pair that shows how far the work has advanced.
• metadata — flexible space at the task level for storing request identity, trace ids, or other context data.

Both pieces of information are very useful for observability — for example, measuring the duration of each stage. Later in episode 15, we'll see how this metadata ties into OpenTelemetry for end-to-end tracing.

#Message and Roles

A conversation in a task is represented as a sequence of Messages. Each message has one role that indicates who sent it:

{
  "role": "agent",
  "parts": [
    { "text": "Analisis selesai. Berikut temuan utamanya..." }
  ]
}

These roles help both parties understand the conversation's context — and they also become important data for audit logs later on (the topic of episode 15). The order of messages inside task.messages reflects the chronology of the conversation.

#Part Types: Text, File, Structured

Each message contains one or more Parts, and each part holds one form of content. Three core types:

{
  "role": "agent",
  "parts": [
    {
      "text": "Berikut hasil analisis dalam beberapa format."
    },
    {
      "file": {
        "name": "laporan-triwulan.pdf",
        "mimeType": "application/pdf",
        "url": "https://analisis.example.com/dl/laporan.pdf"
      }
    },
    {
      "structured": {
        "data": {
          "risiko": "tinggi",
          "skor": 87
        }
      }
    }
  ]
}

• text — plain text content; the most commonly used.
• file — a reference to a file, either via URL or dataURI, complete with mimeType and file name.
• structured — JSON data conforming to a specific schema, avoiding free-text parsing.

The power of the Part model: a single message can send an explanation, a document, and structured data all at once — exactly what real agent collaboration needs. Episode 8 will dig deeper into these content types.

#Streaming Deltas

For long-running results, the client doesn't have to wait for the task to finish. With streaming, the remote agent sends partial messages incrementally over SSE — this is called a streaming delta.

agent   --> [delta 1] "Menganalisis..."
agent   --> [delta 2] "menemukan anomali pada"
agent   --> [delta 3] "cabang Surabaya."
agent   --> [status: completed]

Each delta is a working message carrying a fragment of the result. The client can display these fragments in real time while continuing to wait for the final completed status. This is the difference between a full-polling experience and a streaming experience that feels immediate.

#Conclusion

Here's the core takeaway:

• A Task is the unit of work with id, status, messages, and metadata.
• Task state machine: submitted, working, input-required, completed, failed, canceled.
• input-required is the basis for the human-in-the-loop pattern and continued inter-agent dialogue.
• Progress and metadata keep long-running tasks observable.
• Messages use the user and agent roles and carry one or more Parts.
• Parts support text, file, and structured data within a single conversation.
• Streaming deltas send partial results in real time before the task is completed.

In episode 5 we dissect the protocol layer: JSON-RPC methods & HTTP binding — the message/send, tasks/get, tasks/cancel, tasks/pushNotificationConfig, and messages/list methods, plus how POSTing to a single endpoint and SSE bring the whole lifecycle to life on top. See you there!