Message ID

• Author(s): @michelTho, @nemtecl
• Champion: @benbrandt

Elevator pitch

Add a messageId field to agent_message_chunk, user_message_chunk, agent_thought_chunk session updates to uniquely identify individual messages within a conversation. Only agents generate message IDs, and the IDs are opaque strings. This enables clients to distinguish between different messages beyond changes in update type and lays the groundwork for future capabilities like message editing and session deduplication.

Status quo

Currently, when an Agent sends message chunks via session/update notifications, there is no explicit identifier for the message being streamed:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": {
        "type": "text",
        "text": "Let me analyze your code..."
      }
    }
  }
}

This creates several limitations:

1. Ambiguous message boundaries - When the Agent sends multiple messages in sequence (e.g., alternating between agent and user messages, or multiple agent messages), Clients can only infer message boundaries by detecting a change in the sessionUpdate type. If an Agent sends consecutive messages of the same type, Clients cannot distinguish where one message ends and another begins.

2. Non-standard workarounds - Currently, implementations rely on the _meta field to work around this limitation. While functional, this approach is not standardized and each implementation may use different conventions.

3. Limited future capabilities - Without stable message identifiers, it’s difficult to build features like:

   • Message editing or updates
   • Message-specific metadata or annotations
   • Message threading or references
   • Undo/redo functionality

As an example, consider this sequence where a Client cannot reliably determine message boundaries:

// First agent message chunk
{ "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Analyzing..." } }

// More chunks... but is this still the same message or a new one?
{ "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Found issues." } }

// Tool call happens
{ "sessionUpdate": "tool_call", ... }

// Another agent message - definitely a new message
{ "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Fixed the issues." } }

What we propose to do about it

Add a messageId field to AgentMessageChunk, UserMessageChunk, and AgentThoughtChunk session updates. This field would:

1. Provide stable message identification - Each message gets a unique identifier that remains constant across all chunks of that message.

2. Enable reliable message boundary detection - Clients can definitively determine when a new message starts by observing a change in messageId.

3. Create an extension point for future features - Message IDs can be referenced in future protocol enhancements.

Proposed Structure

The session/prompt response does not include a message ID. In v1, there won’t be a message ID for user-submitted messages. In v2, the agent will replay the message and attach the appropriate message ID to the user message.

If the Agent sends user_message_chunk updates (e.g., during session/load), it uses the user message ID:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "user_message_chunk",
      "messageId": "msg_user_8f7a1",
      "content": {
        "type": "text",
        "text": "Can you analyze this code?"
      }
    }
  }
}

For agent message chunks, the Agent also generates and includes a messageId:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "messageId": "msg_agent_c42b9",
      "content": {
        "type": "text",
        "text": "Let me analyze your code..."
      }
    }
  }
}

The messageId field would be:

• Optional in v1 on agent_message_chunk, user_message_chunk, and agent_thought_chunk updates. An omitted messageId and an explicit null are equivalent and both mean the Agent did not provide a message ID for that chunk.
• Required in v2 on agent_message_chunk, user_message_chunk, and agent_thought_chunk updates. The field MUST be present and MUST be a non-null string.
• Agent-generated - the Agent is the only participant that creates protocol message IDs
• Unique per message within a session
• Stable across chunks - all chunks belonging to the same message share the same messageId
• Opaque - Implementations treat it as an identifier without parsing its structure

In v1, if an Agent supports message IDs and emits an accepted or replayed user message through session/update, it SHOULD include messageId on that user message update. In v2, every streamed user, agent, and thought message chunk MUST include a messageId.

Shiny future

Once this feature exists:

1. Clear message boundaries - Clients can reliably render distinct message bubbles in the UI, even when multiple messages of the same type are sent consecutively.

2. Better streaming UX - Clients know exactly which message element to append chunks to, enabling smoother visual updates.

3. Foundation for editing - With stable message identifiers, future protocol versions could add:

   • message/edit - Agent updates the content of a previously sent message
   • message/delete - Agent removes a message from the conversation
   • message/replace - Agent replaces an entire message with new content

4. Message metadata - Future capabilities could reference messages by ID:

   • Annotations or reactions to specific messages
   • Citation or cross-reference between messages
   • Tool calls that reference which message triggered them

5. Enhanced debugging - Implementations can trace message flow more easily with explicit IDs in logs and debugging tools.

Example future editing capability:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "message_update",
      "messageId": "ea87d0e7-beb8-484a-a404-94a30b78a5a8",
      "updateType": "replace",
      "content": {
        "type": "text",
        "text": "Actually, let me correct that analysis..."
      }
    }
  }
}

Implementation details and plan

Phase 1: Core Protocol Changes

1. Update schema (schema/schema.json):

   • Add optional messageId field (type: string) to v1 ContentChunk (used by AgentMessageChunk, UserMessageChunk, AgentThoughtChunk)
   • Add required messageId field (type: string) to v2 ContentChunk

2. Update Rust SDK (rust/client.rs and rust/agent.rs):

   • Add a dedicated MessageId newtype
   • Add message_id: Option<MessageId> field to the v1 ContentChunk struct
   • Add message_id: MessageId field to the v2 ContentChunk struct
   • Update serialization to include messageId in JSON output when present for v1 and always for v2

3. Update TypeScript SDK (if applicable):

   • Add messageId field to corresponding session update types

4. Update documentation (docs/protocol/prompt-turn.mdx):

   • Document the messageId field and its semantics
   • Add examples showing message boundaries
   • Explain that messageId changes indicate new messages

Phase 2: Reference Implementation

5. Update example agents:

   • Modify example agents to generate and include messageId in chunks
   • Demonstrate consistent IDs across chunks of the same message

6. Update example clients:

   • Update clients to consume messageId field
   • Use IDs to properly group chunks into messages
   • Demonstrate clear message boundary rendering

Backward Compatibility

The messageId field is optional in v1 to ensure this is a non-breaking change. Agents SHOULD include the messageId field on message chunks they can identify, but it is not required for v1 compatibility. Features that rely on messageId (such as future message editing capabilities) will implicitly require the field to be present - Agents that don’t provide it simply won’t support those features.

The field is required in v2, where breaking protocol changes are allowed. v2 agents MUST include messageId on every streamed message chunk, and v2 clients can reject chunks where the field is omitted or null.

Frequently asked questions

What alternative approaches did you consider, and why did you settle on this one?

1. Continue using _meta field - This is the current workaround but:

   • Not standardized across implementations
   • Doesn’t signal semantic importance
   • Easy to overlook or implement inconsistently

2. Detect message boundaries heuristically - Clients could infer boundaries from timing, content types, or session state:

   • Unreliable and fragile
   • Doesn’t work for all scenarios (e.g., consecutive same-type messages)
   • Creates inconsistent behavior across implementations

3. Use explicit “message start/end” markers - Wrap messages with begin/end notifications:

   • More complex protocol interaction
   • Requires additional notifications
   • More state to track on both sides

4. Client-generated prompt IDs - Let Clients generate IDs for session/prompt requests:

   • Creates two sources of truth for protocol IDs
   • Requires agreement on uniqueness across clients and agents
   • Conflicts with the Agent’s role as owner of the session history

The proposed approach with messageId is:

• Simple - Just one new field with clear semantics
• Flexible - Enables future capabilities without further protocol changes
• Practical - IDs come from the same side that owns and emits session history
• Format-agnostic - Agents can use identifiers that fit their own storage model

Who generates message IDs?

Only the Agent generates protocol message IDs.

• For user messages: The Client sends a prompt without a message ID. If the Agent emits that accepted or replayed user message as a session/update, the Agent generates the message ID and includes it in that notification.
• For agent messages and thoughts: The Agent generates the ID when creating the message or thought and includes it in session update chunks.

This matches other protocol identifiers (sessionId, terminalId, toolCallId) which are agent-generated, and provides practical benefits:

• Single source of truth - The Agent owns session persistence and message ordering
• No format coordination - The protocol does not need to standardize UUIDs or another shared ID format
• Adapter-friendly - Adapters for agents that don’t support message IDs can simply omit them

Should this field be required or optional?

The field is optional for v1 to ensure backward compatibility. Agents SHOULD include messageId, but it is not required. In v1, omitting messageId and sending null are equivalent and both mean no message ID was provided.

The field is required for v2. The key MUST be present and its value MUST be a non-null string.

What format should message IDs use?

Message IDs are opaque strings generated by the Agent.

Clients MUST compare message IDs as opaque strings and MUST NOT parse or infer meaning from their structure.

Because IDs only come from the Agent, collision avoidance is the Agent’s responsibility within the session.

What about message IDs across session loads?

When a session is loaded via session/load, the Agent may:

• Preserve original message IDs if replaying the conversation history
• Generate new message IDs if only exposing current state

The protocol doesn’t require message IDs to be stable across session loads, though Agents MAY choose to make them stable if their implementation supports it.

Does this apply to other session updates like tool calls or plan updates?

This RFD addresses agent_message_chunk, user_message_chunk, and agent_thought_chunk updates. Other session update types (like tool_call, plan) already have their own identification mechanisms:

• Tool calls use toolCallId
• Plan entries can be tracked by their position in the entries array

Future RFDs may propose extending messageId to other update types if use cases emerge.

Revision history

• 2026-06-03: Moved the RFD out of the v2 Draft group while keeping v2-specific behavior; added a dedicated MessageId type, and made v2 require message IDs on streamed message chunks while v1 keeps optional message IDs for compatibility
• 2026-06-02: Updated the proposal so message IDs are Agent-generated only, removed client-provided prompt IDs and prompt response acknowledgments, and removed the UUID requirement in favor of opaque strings
• 2026-02-17: Added “Message ID Acknowledgment” section to clarify that presence/absence of userMessageId in response indicates whether the Agent recorded the ID; clarified that UUID format is MUST (not SHOULD) since both sides generate IDs; renamed response field to userMessageId for clarity (request keeps messageId)
• 2026-01-29: Updated to allow both clients and agents to generate message IDs using UUID format
• 2025-11-09: Initial draft