[AIT-106] - Feature documentation accepting user input #3071

GregHolmes · 2026-01-05T15:58:35Z

Description

Add documentation for user input messaging in AI Transport, covering how users send prompts to AI agents over Ably channels.

Topics covered:

Agent subscription to receive user messages
User identification with verified clientId
Publishing prompts with message correlation
Correlating agent responses to original input
Streaming responses with input correlation
Handling multiple concurrent prompts

coderabbitai · 2026-01-05T15:58:44Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mschristensen

Looks really great so far, thanks Greg. Left some suggestions and comments.

mschristensen · 2026-01-07T11:40:16Z

src/pages/docs/ai-transport/features/messaging/user-input.mdx

+3. The agent receives the message, processes it, and generates a response.
+4. The agent publishes the response back to the channel, correlating it to the original input.
+
+This decoupled approach means agents don't need persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.


Suggested change

This decoupled approach means agents don't need persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.

This decoupled approach means agents don't need to manage persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.

<Aside data-type="further-reading">

Learn more about channel-based communication in [channel-oriented sessions](/docs/ai-transport/features/sessions-identity#connection-oriented-vs-channel-oriented-sessions).

</Aside>

mschristensen · 2026-01-07T11:55:45Z

src/pages/docs/ai-transport/features/messaging/user-input.mdx

+
+This decoupled approach means agents don't need persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.
+
+## Subscribe to user input <a id="subscribe"/>


I think this should appear after we've illustrated how the user input message was published.

mschristensen · 2026-01-07T11:57:53Z

src/pages/docs/ai-transport/features/messaging/user-input.mdx

+</Code>
+
+<Aside data-type="note">
+The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents).


Suggested change

The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents).

The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity).

mschristensen · 2026-01-07T12:00:44Z

src/pages/docs/ai-transport/features/messaging/user-input.mdx

+
+## Identify the user <a id="identify-user"/>
+
+Users must be [identified clients](/docs/auth/identified-clients) to send input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.


Suggested change

Users must be [identified clients](/docs/auth/identified-clients) to send input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.

Use [identified clients](/docs/auth/identified-clients) to establish a verified identity for each user client that sends input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.

mschristensen · 2026-01-07T14:03:37Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents).
+</Aside>
+
+## Identify the user <a id="identify-user"/>


I think the simplest requirement is that the sender has a verified role: /docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-claims i.e. so that the agent can determine the message is from a "user" rather than e.g. another agent sharing the channel. If the agent needs to wants to know the identity of a specific user that sent a message, then verified clients should be used.

Do you think we can describe both patterns in these docs?

I've rewritten this section to use both patterns and explain why you would use each: a28b828

mschristensen · 2026-01-07T14:22:51Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+
+// Track sent prompts
+async function sendPrompt(prompt) {
+  const result = await channel.publish('user-input', { prompt });


And here, can just be await channel.publish('user-input', prompt);

Would we not want the result if we're using the newer version of Ably-js?

Such as:

async function sendPrompt(prompt) { const result = await channel.publish('user-input', prompt); pendingPrompts.set(result.serial, { prompt }); return result.serial; }

mschristensen · 2026-01-07T14:23:43Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+// Track sent prompts
+async function sendPrompt(prompt) {
+  const result = await channel.publish('user-input', { prompt });
+  pendingPrompts.set(result.id, { prompt, sentAt: Date.now() });


I think we should avoid adding unrelated functionality to code examples, so lets just store the prompt and exclude the sentAt

mschristensen · 2026-01-07T14:25:07Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+</Code>
+
+<Aside data-type="note">
+When appending tokens, include the `extras` with all headers to preserve them on the message. If you omit `extras` from an append operation, any existing headers will be removed. See [token streaming](/docs/ai-transport/features/token-streaming/message-per-response) for more details.


Suggested change

When appending tokens, include the `extras` with all headers to preserve them on the message. If you omit `extras` from an append operation, any existing headers will be removed. See [token streaming](/docs/ai-transport/features/token-streaming/message-per-response) for more details.

When appending tokens, include the `extras` with all headers to preserve them on the message. If you omit `extras` from an append operation, any existing headers will be removed. See token streaming with the [message per response](/docs/ai-transport/features/token-streaming/message-per-response) pattern for more details.

mschristensen · 2026-01-07T14:26:42Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+  activeRequests.set(inputMessageId, {
+    userId,
+    prompt: message.data.prompt,
+    startedAt: Date.now()


Same here, this is superfluous to requirements

mschristensen · 2026-01-07T14:28:04Z

src/data/nav/aitransport.ts

+      name: 'Messaging',
+      pages: [
+        {
+          name: 'User input',


On reflection, can we call this Accepting user input, which aligns with the style used in other sections?

8885c59

I've also renamed the file so it follows the same naming for the url.

GregHolmes · 2026-01-08T14:15:53Z

Thank you @mschristensen I've updated most. There's a couple comments on others though.

mschristensen

Looks good, a couple of last comments but approving ahead of that

mschristensen · 2026-01-12T10:03:00Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+
+### Establish user identity <a id="user-identity"/>
+
+Use [identified clients](/docs/auth/identified-clients) when the agent needs to know which specific user sent a message. This enables personalized responses, per-user rate limiting, or access control based on user identity.


For parity with the section above, I think this should link to the docs on the sessions & identity section: /docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity

And then the link at the end of this section can link to /docs/auth/identified-clients

mschristensen · 2026-01-12T10:03:54Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+function getJWTClaims(userId) {
+  return {
+    "x-ably-clientId": userId,
+    "ably.channel.*": "user",


We shouldn't include the user claim here, as that is not what is being documented, and is covered in the section above. Requires a few small tweaks to the following content.

(In general I think it works well when each section is orthogonal, so that the reader doesn't have to rely on context in one section that was introduced in some prior section)

mschristensen · 2026-01-12T10:07:15Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+const channel = ably.channels.get('conversation:{{RANDOM_CHANNEL_NAME}}');
+
+const result = await channel.publish('user-input', 'What is the weather like today?');
+console.log(`Published message with serial: ${result.serial}`);


This should be:

Suggested change

console.log(`Published message with serial: ${result.serial}`);

console.log(`Published message with serial: ${result.serials[0]}`);

mschristensen · 2026-01-12T10:11:20Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity).
+</Aside>
+
+## Correlate responses to input <a id="correlate"/>


I think this should be "Publish agent responses"

mschristensen

One more thing - I know I suggested using the serial. However I noticed that most other docs use a user-generated UUID for correlation (e.g. in the HITL docs). I think we should use that approach here too, instead of the serial:

Removes dependency on a specific SDK version
Handles the case when the ACK arrives after the response (unlikely, but I think possible)
Avoids dependency on Ably-assigned identifiers. I know we use them in appends for the message-per-response model, but we plan to add support for a client-specified identifier in this case too.

GregHolmes · 2026-01-13T12:36:50Z

One more thing - I know I suggested using the serial. However I noticed that most other docs use a user-generated UUID for correlation (e.g. in the HITL docs). I think we should use that approach here too, instead of the serial:

Removes dependency on a specific SDK version

Handles the case when the ACK arrives after the response (unlikely, but I think possible)

Avoids dependency on Ably-assigned identifiers. I know we use them in appends for the message-per-response model, but we plan to add support for a client-specified identifier in this case too.

I've updated the page to use a promptId which is user-generated UUID. All changes for this can be found in: 609ad8e

mschristensen

Looks good, last couple of comments mostly to align with the improvements we ended up making on the HITL docs

mschristensen · 2026-01-13T12:54:51Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+```
+</Code>
+
+### Establish user identity <a id="user-identity"/>


For alignment with the preceding heading, I think this should be:

Suggested change

### Establish user identity <a id="user-identity"/>

### Verify user identity <a id="verify-identity"/>

mschristensen · 2026-01-13T12:56:19Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+
+### Establish user identity <a id="user-identity"/>
+
+Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) when the agent needs to know which specific user sent a message. This enables personalized responses, per-user rate limiting, or access control based on user identity.


I don't think we should mention rate limiting, to avoid potential confusion with Ably rate limits, and avoid referencing access control, which is not specifically a concern wrt. user input:

Suggested change

Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) when the agent needs to know which specific user sent a message. This enables personalized responses, per-user rate limiting, or access control based on user identity.

Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) when the agent needs to know which specific user sent a message. This enables personalized responses or custom behaviour based on user identity.

mschristensen · 2026-01-13T12:59:31Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+
+Use [user claims](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-claims) to verify that a message comes from a user rather than another agent sharing the channel. This is the simplest approach when the agent only needs to distinguish message sources.
+
+Your auth server embeds a role claim in the user's token:


Can we align the role/identity stuff with the approach we used in HITL?

docs/src/pages/docs/ai-transport/features/messaging/human-in-the-loop.mdx

Line 61 in 9915388

<Code>

I.e. an Aside with links to the relevant sections, code snippet with just the claim object definitions, and leaving out the auth endpoint definition which is covered elsewhere? Can probably align some of the copy here too

mschristensen · 2026-01-13T13:00:43Z

src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx

+  // The auth endpoint returns a token with the user's clientId embedded
+});
+
+const channel = ably.channels.get('conversation:{{RANDOM_CHANNEL_NAME}}');


Is there a reason for the conversation: prefix? We excluded in HITL and can do so here (and any claim can be specified on ably.channels.*)

I think I had this in before we removed it from HITL. Removed and will ensure I don't add it in future

Document how users send prompts to AI agents over Ably channels, including identified clients, message correlation, and handling concurrent prompts.

GregHolmes requested review from franrob-projects, mschristensen and rainbowFi January 5, 2026 15:58

GregHolmes self-assigned this Jan 5, 2026

GregHolmes added the review-app Create a Heroku review app label Jan 5, 2026

GregHolmes changed the title ~~Ait 106 feature documentation accepting user input~~ [AIT-106] - Feature documentation accepting user input Jan 5, 2026

ably-ci temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 5, 2026 15:59 Inactive

GregHolmes changed the base branch from main to AIT-129-AIT-Docs-release-branch January 6, 2026 14:20

mschristensen force-pushed the AIT-129-AIT-Docs-release-branch branch from aebe2c1 to ea0ac8d Compare January 7, 2026 11:48

mschristensen requested changes Jan 7, 2026

View reviewed changes

GregHolmes force-pushed the AIT-106-Feature-documentation-accepting-user-input branch from 16f6594 to 95627c1 Compare January 8, 2026 10:38

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 10:38 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 11:12 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 11:14 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 11:19 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 11:32 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 13:42 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 14:07 Inactive

GregHolmes requested a review from mschristensen January 8, 2026 14:15

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 8, 2026 14:15 Inactive

mschristensen approved these changes Jan 12, 2026

View reviewed changes

mschristensen requested changes Jan 12, 2026

View reviewed changes

GregHolmes force-pushed the AIT-106-Feature-documentation-accepting-user-input branch from faaa6a7 to f346f14 Compare January 13, 2026 11:25

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 11:26 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 12:22 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 12:24 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 12:25 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 12:36 Inactive

GregHolmes requested a review from mschristensen January 13, 2026 12:36

mschristensen requested changes Jan 13, 2026

View reviewed changes

GregHolmes force-pushed the AIT-106-Feature-documentation-accepting-user-input branch from 609ad8e to f87aaf0 Compare January 13, 2026 13:29

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 13:29 Inactive

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 13:32 Inactive

GregHolmes requested a review from mschristensen January 13, 2026 14:25

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 14:25 Inactive

mschristensen approved these changes Jan 13, 2026

View reviewed changes

docs: add user input page for AI Transport

7486a62

Document how users send prompts to AI agents over Ably channels, including identified clients, message correlation, and handling concurrent prompts.

GregHolmes force-pushed the AIT-106-Feature-documentation-accepting-user-input branch from 47bf288 to 7486a62 Compare January 13, 2026 16:04

GregHolmes temporarily deployed to ably-docs-ait-106-featu-wfvmlm January 13, 2026 16:04 Inactive

GregHolmes merged commit 15363db into AIT-129-AIT-Docs-release-branch Jan 13, 2026
7 checks passed

GregHolmes deleted the AIT-106-Feature-documentation-accepting-user-input branch January 13, 2026 16:18

-This decoupled approach means agents don't need persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.
+This decoupled approach means agents don't need to manage persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.
+<Aside data-type="further-reading">
+Learn more about channel-based communication in [channel-oriented sessions](/docs/ai-transport/features/sessions-identity#connection-oriented-vs-channel-oriented-sessions).
+</Aside>


		This decoupled approach means agents don't need persistent connections to individual users. Instead, they subscribe to channels and respond to messages as they arrive.

		## Subscribe to user input <a id="subscribe"/>

	The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents).
	The agent can use the `message.clientId` to identify which user sent the prompt. This is a verified identity when using [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity).


		## Identify the user <a id="identify-user"/>

		Users must be [identified clients](/docs/auth/identified-clients) to send input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.

	Users must be [identified clients](/docs/auth/identified-clients) to send input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.
	Use [identified clients](/docs/auth/identified-clients) to establish a verified identity for each user client that sends input to agents. This ensures the agent can trust the identity of message senders and prevents users from impersonating others.

	When appending tokens, include the `extras` with all headers to preserve them on the message. If you omit `extras` from an append operation, any existing headers will be removed. See [token streaming](/docs/ai-transport/features/token-streaming/message-per-response) for more details.
	When appending tokens, include the `extras` with all headers to preserve them on the message. If you omit `extras` from an append operation, any existing headers will be removed. See token streaming with the [message per response](/docs/ai-transport/features/token-streaming/message-per-response) pattern for more details.


		### Establish user identity <a id="user-identity"/>

		Use [identified clients](/docs/auth/identified-clients) when the agent needs to know which specific user sent a message. This enables personalized responses, per-user rate limiting, or access control based on user identity.

	console.log(`Published message with serial: ${result.serial}`);
	console.log(`Published message with serial: ${result.serials[0]}`);

	### Establish user identity <a id="user-identity"/>
	### Verify user identity <a id="verify-identity"/>


		### Establish user identity <a id="user-identity"/>

		Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) when the agent needs to know which specific user sent a message. This enables personalized responses, per-user rate limiting, or access control based on user identity.


		Use [user claims](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-claims) to verify that a message comes from a user rather than another agent sharing the channel. This is the simplest approach when the agent only needs to distinguish message sources.

		Your auth server embeds a role claim in the user's token:

[AIT-106] - Feature documentation accepting user input #3071

[AIT-106] - Feature documentation accepting user input #3071

Conversation

GregHolmes commented Jan 5, 2026

Description

Uh oh!

coderabbitai bot commented Jan 5, 2026

Review skipped

Uh oh!

mschristensen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GregHolmes commented Jan 8, 2026

Uh oh!

mschristensen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mschristensen left a comment

Choose a reason for hiding this comment

Uh oh!

GregHolmes commented Jan 13, 2026

Uh oh!

mschristensen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!