Manuals / A2A 101 / Part 3 · Data Model
3.5

contextId

A contextId groups many tasks into one conversation, a taskId groups many messages into one job, and only the server creates a task id.

code-reviewer stops halfway through a review and asks your planner which base branch to use. The answer must reach that same review. Later the diff changes, and the planner wants a second review that remembers the first. Two ids carry this: the task id for the job and the context id for the conversation.

When you finish this section, you can continue a task, start a follow-up in the same context, and know who creates each id.

Two ids, two scopes

Context: an optional identifier that groups related tasks and messages. Tasks and messages with the same contextId should count as one conversational session.

Task id: the id of one stateful job. The server generates the task id when it creates a new task in response to a message. Message gives the rules for sending one back.

The server usually creates the context too. An agent is allowed to generate a new contextId for a message that has none, and the response must carry it. In the kit, every first message carries no ids, and every answer, even the direct reply in 02-message-reply.http, brings back a new context.

A client should treat a contextId from the server as an opaque identifier. Behind the id, the agent can keep internal state, conversation history, or LLM context across many interactions.

Propose your own context id only when you understand how the server will process it. A server that cannot take it must reject the request with an error, and it must not generate a new contextId for the response. The concept guide describes the context id as an identifier that the server generates, which leaves no room for a proposal (conflict D28). The specification wins, so expect either answer.

Continuing a task

When a task waits for you, answer on that same task and send both of its ids, as Message explains. Interrupted states follows the review's answer.

Only a task that is not terminal takes more messages. A message to a finished task fails with UnsupportedOperationError, as CancelTask and terminal states shows.

A follow-up is a new task

Once the review completes, a second round cannot reopen it. A refinement must start a new task in the same contextId. The specification gives the client two fields for that. A client is allowed to send a contextId without a taskId to start a new task in an existing context. A client should use the referenceTaskIds field of the message to point to related tasks.

The captures stop before such a follow-up. The kit's server would accept one: given a contextId and no taskId, its send creates a new task in that context. The kit's server code shows this. Figure 3.6 draws the captured review beside the follow-up a client would send next.

Fig. 3.6one context, two taskstree
One context, two tasks A tree. The root is context 49c5a238. Its first child is the review task e5c95b09, completed, whose history holds four messages from two SendMessage calls: the planner request with the diff and the agent question, then the planner answer main carrying taskId and contextId and the agent reply, followed by the artifact review.json. Its second child, drawn dashed because the captures stop before it, is a follow-up task in the same context whose first message carries contextId 49c5a238 and referenceTaskIds naming e5c95b09 and no taskId. context 49c5a238 created by code-reviewer, opaque to you task e5c95b09 · review TASK_STATE_COMPLETED, status: 2 findings Violet: sent by the planner. Blue: sent by code-reviewer. Ids shortened to 8 characters. CALL 1 · REVIEW A DIFF ROLE_USER · 14a03569 text and raw refunds.diff, no ids sent ROLE_AGENT · 46494a30 asks which base branch to use CALL 2 · ANSWER THE QUESTION ROLE_USER · 096d3737 · main taskId e5c95b09, contextId 49c5a238 ROLE_AGENT · 8f9ee658 Comparing the diff against main RESULT artifact review.json a text part and a data part a follow-up task id created by the server ITS FIRST MESSAGE ROLE_USER · a new messageId contextId 49c5a238 referenceTaskIds [e5c95b09] no taskId A message with taskId e5c95b09 now fails: the task is terminal.
The review task holds both exchanges of the conversation, and a follow-up review joins the same context as a new task, because the review task is terminal. Read top down: the context, its tasks, and each task's history in order. The dashed task and its message show what a client sends next, because the captures stop before it. Ids shortened to 8 characters.

Nothing limits a context to one task at a time: agents can create a separate, parallel task for each follow-up message.

What the agent keeps

The review task keeps its four messages in history, and GetTask and ListTasks shows how to read them. Do not treat that history as a full transcript, because the agent decides which messages it keeps in the task history. In particular, messages from before the task was created can be missing from the history.

Contexts do not live forever either. An agent is allowed to expire or clean up contexts, and it should document any such policy. Check the agent's documentation before you rely on an old context id.

A2A protocol 1.0.1 · 3303592 · 2026-05-28 · Edition 2026.10