contextId

contextId is the A2A identifier that groups related tasks and messages into one conversational context. Agents use it to keep state, history or model context across a series of interactions, and clients use it to show that a new request continues an earlier one.

Who creates it. Usually the agent (specification section 3.4.1). When a message arrives without a contextId, the agent may generate one, and if it does it must return it in the Task or Message it sends back. Clients should treat server-generated values as opaque. An agent may accept a contextId that the client made up, but clients should only send one if they know how the server will handle it. If an agent cannot accept a client-provided value, it must reject the request with an error and must not substitute a new one.

How it combines with taskId. Section 3.4.3 sets these rules for client messages:

• taskId only: continue that task. The agent infers the context from the task.
• contextId only: start a new task inside the existing context.
• Both: continue the task. The two must match, or the agent must reject the message.

This illustrative follow-up starts a new task in an existing context, after the earlier task has finished, and points back at it with referenceTaskIds:

{
  "message": {
    "messageId": "msg-u3",
    "contextId": "ctx-42b9",
    "referenceTaskIds": ["task-7c1e"],
    "role": "ROLE_USER",
    "parts": [{"text": "Book the same delivery slot for order PO-5519."}]
  }
}

Scope and lifetime. All tasks and messages that share a contextId should be treated as one conversational session. Agents may expire contexts or clean them up, and should document that policy. In the proto, messages sent by the agent must include a contextId, and every streamed status or artifact update event carries the contextId of its task.