Skip to content

docs(unstable-v2): say the Agent owns the reported user message - #2873

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-user-message-echo
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-user-message-echo

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

After a prompt is inserted, the Agent reports the user message with a user_message update. The prompt lifecycle page did not say whether that report must match the submitted prompt. Its own example made this harder to read: the session/prompt example has a text block and a resource block, and the user_message example right after it had only the text block.

Only the Prompt RFD said that the Agent's content wins.

Changes

Both are made in the stable page and its draft/ copy.

  • Example: the user_message example now carries the same two content blocks as the session/prompt example above it.
  • Ownership: a new paragraph after the example says:
    • the Agent owns the inserted message
    • its reported content usually repeats the submitted prompt, but can differ, for example when an adapter reports the message as its runtime recorded it
    • a Client MAY keep showing the prompt as it sent it, although a replay carries the Agent's content

Notes

  • This adds no requirement for Agents. The message upsert rules already say that a user_message update with content replaces what the Client holds for that messageId.
  • The migration guide is unchanged. Its Client checklist already says to render the user's message from the user_message acknowledgment.

Checks

  • Prettier and typos pass on the changed files.
  • All links and anchors in the changed files resolve.
  • The content of the user_message example equals the prompt of the session/prompt example in both copies.

The prompt lifecycle page did not say whether the `user_message` report
must match the submitted prompt, and its example dropped the prompt's
`resource` block without explanation.

- Make the `user_message` example carry the same content as the
  `session/prompt` example above it.
- Say that the Agent owns the inserted message, that its reported
  `content` can differ from the prompt, and that a Client may keep
  showing the prompt as it sent it.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 12:52
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 12:53
@benbrandt
benbrandt merged commit 6e88451 into main Nov 18, 2026
10 checks passed
@benbrandt
benbrandt deleted the docs/v2-user-message-echo branch November 18, 2026 12:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant