Skip to content

Commit c05a9e2

Browse files
committed
Allow non-UUIDs as message ids
PR agentclientprotocol#244 introduced the `messageId` field and required both clients and agents to use the UUID format for IDs. It also states that the ID should be treated as an opaque value. I propose to drop the requirement on UUIDs and instead focus on IDs being unique with the exact format not being imposed by ACP. For example, OpenCode uses a different message ID format internally and I'm not sure if it would be worth the effort to add logic for using UUIDs just for ACP.
1 parent 4d1558a commit c05a9e2

1 file changed

Lines changed: 6 additions & 8 deletions

File tree

docs/rfds/message-id.mdx

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ The `messageId` field would be:
147147

148148
- **Optional** on `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` updates and `session/prompt` requests (as `messageId`)
149149
- **Optional** in `session/prompt` responses (as `userMessageId`)
150-
- **UUID format** - Both clients and agents MUST use UUID format to ensure collision avoidance
150+
- **Uniqueness** - Both clients and agents must ensure that generated IDs are unique per session, for example by using UUIDv4/v7
151151
- **Unique per message** within a session
152152
- **Stable across chunks** - all chunks belonging to the same message share the same `messageId`
153153
- **Opaque** - Implementations treat it as an identifier without parsing its structure
@@ -280,20 +280,18 @@ The proposed approach with `messageId` is:
280280
- **Simple** - Just one new field with clear semantics
281281
- **Flexible** - Enables future capabilities without further protocol changes
282282
- **Practical** - Clients generate IDs for their messages, agents for theirs
283-
- **Collision-safe** - UUID format ensures uniqueness across both sides
284283

285284
### Who generates message IDs?
286285

287286
**Both clients and agents can generate message IDs**, each for their own messages:
288287

289-
- **For user messages**: The Client generates a UUID and includes it as `messageId` in the `session/prompt` request. The Agent echoes this ID as `userMessageId` in the response to confirm it was recorded. If the client doesn't provide one, the Agent MAY assign one and return it in the response so the client knows the assigned ID.
290-
- **For agent messages**: The Agent generates the UUID when creating its response and includes it in session update chunks.
288+
- **For user messages**: The Client generates an ID and includes it as `messageId` in the `session/prompt` request. The Agent echoes this ID as `userMessageId` in the response to confirm it was recorded. If the client doesn't provide one, the Agent MAY assign one and return it in the response so the client knows the assigned ID.
289+
- **For agent messages**: The Agent generates the ID when creating its response and includes it in session update chunks.
291290

292291
This differs from other protocol identifiers (`sessionId`, `terminalId`, `toolCallId`) which are agent-generated, but provides practical benefits:
293292

294293
- **Immediate availability** - Clients have the ID as soon as they send the message, without waiting for a response
295294
- **Deduplication** - Clients can use IDs to deduplicate messages on `session/load` or when echoing to multiple clients
296-
- **Collision-safe** - UUID format ensures uniqueness without coordination
297295
- **Adapter-friendly** - Adapters for agents that don't support message IDs can simply not pass them through
298296

299297
### Should this field be required or optional?
@@ -304,13 +302,12 @@ Making this field required will be considered for a future v2 version of the pro
304302

305303
### What format should message IDs use?
306304

307-
Both clients and agents **MUST** use UUID format for message IDs. This is required because both sides can generate IDs, and UUID format ensures:
305+
Both clients and agents **SHOULD** use UUID format for message IDs. This is recommended because both sides can generate IDs, and UUID format ensures:
308306

309307
- **No collisions** - UUIDs are globally unique without coordination between client and agent
310-
- **Interoperability** - Both sides use the same format, so either side can rely on uniqueness guarantees
311308
- **Simplicity** - Standard libraries available in all languages
312309

313-
While `messageId` values are UUIDs, implementations **SHOULD** treat them as opaque strings when reading/comparing them, and not parse or interpret their internal structure.
310+
Implementations **MUST** treat them as opaque strings when reading/comparing them, and not parse or interpret their internal structure.
314311

315312
### What about message IDs across session loads?
316313

@@ -333,6 +330,7 @@ Future RFDs may propose extending `messageId` to other update types if use cases
333330

334331
## Revision history
335332

333+
- **2026-03-10**: Allow IDs to be any opaque string (not just UUID), but clarify that both client and server must ensure uniqueness.
336334
- **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`)
337335
- **2026-01-29**: Updated to allow both clients and agents to generate message IDs using UUID format
338336
- **2025-11-09**: Initial draft

0 commit comments

Comments
 (0)