[AIT-106] - Feature documentation accepting user input #3071
Conversation
GregHolmes
requested review from
franrob-projects,
mschristensen and
rainbowFi
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 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. Comment |
GregHolmes
changed the title
GregHolmes
changed the base branch from
main
to
AIT-129-AIT-Docs-release-branch
mschristensen
force-pushed
the
AIT-129-AIT-Docs-release-branch
branch
from
aebe2c1 to
ea0ac8d
Compare
mschristensen
left a comment
mschristensen
left a comment
There was a problem hiding this comment.
Looks really great so far, thanks Greg. Left some suggestions and comments.
| 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. |
There was a problem hiding this comment.
| 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"/> |
There was a problem hiding this comment.
I think this should appear after we've illustrated how the user input message was published.
| </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). |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
| 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. |
| 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"/> |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I've rewritten this section to use both patterns and explain why you would use each: a28b828
|
|
||
| // Track sent prompts | ||
| async function sendPrompt(prompt) { | ||
| const result = await channel.publish('user-input', { prompt }); |
There was a problem hiding this comment.
And here, can just be await channel.publish('user-input', prompt);
There was a problem hiding this comment.
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;
}
| // Track sent prompts | ||
| async function sendPrompt(prompt) { | ||
| const result = await channel.publish('user-input', { prompt }); | ||
| pendingPrompts.set(result.id, { prompt, sentAt: Date.now() }); |
There was a problem hiding this comment.
I think we should avoid adding unrelated functionality to code examples, so lets just store the prompt and exclude the sentAt
| </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. |
There was a problem hiding this comment.
| 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. |
| activeRequests.set(inputMessageId, { | ||
| userId, | ||
| prompt: message.data.prompt, | ||
| startedAt: Date.now() |
There was a problem hiding this comment.
Same here, this is superfluous to requirements
src/data/nav/aitransport.ts
Outdated
| name: 'Messaging', | ||
| pages: [ | ||
| { | ||
| name: 'User input', |
There was a problem hiding this comment.
On reflection, can we call this Accepting user input, which aligns with the style used in other sections?
There was a problem hiding this comment.
I've also renamed the file so it follows the same naming for the url.
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
16f6594 to
95627c1
Compare
|
Thank you @mschristensen I've updated most. There's a couple comments on others though. |
Description
Add documentation for user input messaging in AI Transport, covering how users send prompts to AI agents over Ably channels.
Topics covered:
clientId