You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: docs/rfds/message-id.mdx
+6-8Lines changed: 6 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -147,7 +147,7 @@ The `messageId` field would be:
147
147
148
148
-**Optional** on `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` updates and `session/prompt` requests (as `messageId`)
149
149
-**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
151
151
-**Unique per message** within a session
152
152
-**Stable across chunks** - all chunks belonging to the same message share the same `messageId`
153
153
-**Opaque** - Implementations treat it as an identifier without parsing its structure
@@ -280,20 +280,18 @@ The proposed approach with `messageId` is:
280
280
-**Simple** - Just one new field with clear semantics
281
281
-**Flexible** - Enables future capabilities without further protocol changes
282
282
-**Practical** - Clients generate IDs for their messages, agents for theirs
283
-
-**Collision-safe** - UUID format ensures uniqueness across both sides
284
283
285
284
### Who generates message IDs?
286
285
287
286
**Both clients and agents can generate message IDs**, each for their own messages:
288
287
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.
291
290
292
291
This differs from other protocol identifiers (`sessionId`, `terminalId`, `toolCallId`) which are agent-generated, but provides practical benefits:
293
292
294
293
-**Immediate availability** - Clients have the ID as soon as they send the message, without waiting for a response
295
294
-**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
297
295
-**Adapter-friendly** - Adapters for agents that don't support message IDs can simply not pass them through
298
296
299
297
### 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
304
302
305
303
### What format should message IDs use?
306
304
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:
308
306
309
307
-**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
311
308
-**Simplicity** - Standard libraries available in all languages
312
309
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.
314
311
315
312
### What about message IDs across session loads?
316
313
@@ -333,6 +330,7 @@ Future RFDs may propose extending `messageId` to other update types if use cases
333
330
334
331
## Revision history
335
332
333
+
-**2026-03-10**: Allow IDs to be any opaque string (not just UUID), but clarify that both client and server must ensure uniqueness.
336
334
-**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`)
337
335
-**2026-01-29**: Updated to allow both clients and agents to generate message IDs using UUID format
0 commit comments