diff --git a/src/data/nav/aitransport.ts b/src/data/nav/aitransport.ts index e049109ea2..1a4c7a0db0 100644 --- a/src/data/nav/aitransport.ts +++ b/src/data/nav/aitransport.ts @@ -23,16 +23,16 @@ export default { pages: [ { name: 'Overview', - link: '/docs/ai-transport/features/token-streaming', + link: '/docs/ai-transport/token-streaming', index: true, }, { name: 'Message per response', - link: '/docs/ai-transport/features/token-streaming/message-per-response', + link: '/docs/ai-transport/token-streaming/message-per-response', }, { name: 'Message per token', - link: '/docs/ai-transport/features/token-streaming/message-per-token', + link: '/docs/ai-transport/token-streaming/message-per-token', }, ], }, @@ -41,19 +41,19 @@ export default { pages: [ { name: 'Overview', - link: '/docs/ai-transport/features/sessions-identity', + link: '/docs/ai-transport/sessions-identity', }, { name: 'Identifying users and agents', - link: '/docs/ai-transport/features/sessions-identity/identifying-users-and-agents', + link: '/docs/ai-transport/sessions-identity/identifying-users-and-agents', }, { name: 'Online status', - link: '/docs/ai-transport/features/sessions-identity/online-status', + link: '/docs/ai-transport/sessions-identity/online-status', }, { name: 'Resuming sessions', - link: '/docs/ai-transport/features/sessions-identity/resuming-sessions', + link: '/docs/ai-transport/sessions-identity/resuming-sessions', }, ], }, @@ -62,23 +62,23 @@ export default { pages: [ { name: 'Accepting user input', - link: '/docs/ai-transport/features/messaging/accepting-user-input', + link: '/docs/ai-transport/messaging/accepting-user-input', }, { name: 'Tool calls', - link: '/docs/ai-transport/features/messaging/tool-calls', + link: '/docs/ai-transport/messaging/tool-calls', }, { name: 'Human-in-the-loop', - link: '/docs/ai-transport/features/messaging/human-in-the-loop', + link: '/docs/ai-transport/messaging/human-in-the-loop', }, { name: 'Chain of thought', - link: '/docs/ai-transport/features/messaging/chain-of-thought', + link: '/docs/ai-transport/messaging/chain-of-thought', }, { name: 'Citations', - link: '/docs/ai-transport/features/messaging/citations', + link: '/docs/ai-transport/messaging/citations', }, ], }, diff --git a/src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx b/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx similarity index 81% rename from src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx rename to src/pages/docs/ai-transport/messaging/accepting-user-input.mdx index 7442b12ab9..f13c8e3c70 100644 --- a/src/pages/docs/ai-transport/features/messaging/accepting-user-input.mdx +++ b/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx @@ -6,7 +6,7 @@ meta_keywords: "user input, AI prompts, message correlation, identified clients, User input enables users to send prompts and requests to AI agents over Ably channels. The agent subscribes to a channel to receive user messages, processes them, and sends responses back. This pattern uses [Ably Pub/Sub](/docs/basics) for realtime, bi-directional communication between users and agents. -User input works alongside [token streaming](/docs/ai-transport/features/token-streaming) patterns to create complete conversational AI experiences. While token streaming handles agent-to-user output, user input handles user-to-agent prompts. +User input works alongside [token streaming](/docs/ai-transport/token-streaming) patterns to create complete conversational AI experiences. While token streaming handles agent-to-user output, user input handles user-to-agent prompts. ## How it works @@ -20,22 +20,22 @@ User input follows a channel-based pattern where both users and agents connect t 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. ## Identify the user -Agents need to verify that incoming messages are from legitimate users. Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) or [user claims](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-claims) to establish a verified identity or role for the user. +Agents need to verify that incoming messages are from legitimate users. Use [identified clients](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-identity) or [user claims](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-claims) to establish a verified identity or role for the user. ### Verify by user identity Use the `clientId` to identify the user who sent a message. This enables personalized responses, per-user rate limiting, or looking up user-specific preferences from your database. -When a user [authenticates with Ably](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#authenticating), embed their identity in the JWT: +When a user [authenticates with Ably](/docs/ai-transport/sessions-identity/identifying-users-and-agents#authenticating), embed their identity in the JWT: ```javascript @@ -62,9 +62,9 @@ await channel.subscribe('user-input', (message) => { ### Verify by role -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 useful when the agent needs to distinguish message sources without needing the specific user identity. +Use [user claims](/docs/ai-transport/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 useful when the agent needs to distinguish message sources without needing the specific user identity. -When a user [authenticates with Ably](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#authenticating), embed their role in the JWT: +When a user [authenticates with Ably](/docs/ai-transport/sessions-identity/identifying-users-and-agents#authenticating), embed their role in the JWT: ```javascript @@ -135,7 +135,7 @@ await channel.subscribe('user-input', (message) => { ## Publish agent responses @@ -195,7 +195,7 @@ await channel.subscribe('agent-response', (message) => { For longer AI responses, you'll typically want to stream tokens back to the user rather than waiting for the complete response. The `promptId` correlation allows users to associate streamed tokens with their original prompt. -When streaming tokens using [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) or [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) patterns, include the `promptId` in the message extras: +When streaming tokens using [message-per-response](/docs/ai-transport/token-streaming/message-per-response) or [message-per-token](/docs/ai-transport/token-streaming/message-per-token) patterns, include the `promptId` in the message extras: ```javascript @@ -228,7 +228,7 @@ async function streamResponse(channel, prompt, promptId) { ## Handle multiple concurrent prompts diff --git a/src/pages/docs/ai-transport/features/messaging/chain-of-thought.mdx b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx similarity index 94% rename from src/pages/docs/ai-transport/features/messaging/chain-of-thought.mdx rename to src/pages/docs/ai-transport/messaging/chain-of-thought.mdx index e058e9e39f..49a9bf1aaa 100644 --- a/src/pages/docs/ai-transport/features/messaging/chain-of-thought.mdx +++ b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx @@ -79,7 +79,7 @@ for await (const event of stream) { #### Subscribing @@ -131,7 +131,7 @@ await channel.subscribe((message) => { ### Threading pattern @@ -201,7 +201,7 @@ for await (const event of stream) { #### Subscribing @@ -254,5 +254,5 @@ async function onClickViewReasoning(responseId) { diff --git a/src/pages/docs/ai-transport/features/messaging/citations.mdx b/src/pages/docs/ai-transport/messaging/citations.mdx similarity index 98% rename from src/pages/docs/ai-transport/features/messaging/citations.mdx rename to src/pages/docs/ai-transport/messaging/citations.mdx index d44f85e614..a71ae51795 100644 --- a/src/pages/docs/ai-transport/features/messaging/citations.mdx +++ b/src/pages/docs/ai-transport/messaging/citations.mdx @@ -136,11 +136,11 @@ await channel.annotations.publish(msgSerial, { ## Subscribing to summaries diff --git a/src/pages/docs/ai-transport/features/messaging/human-in-the-loop.mdx b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx similarity index 89% rename from src/pages/docs/ai-transport/features/messaging/human-in-the-loop.mdx rename to src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx index ba1d7ceec2..b896366da3 100644 --- a/src/pages/docs/ai-transport/features/messaging/human-in-the-loop.mdx +++ b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx @@ -56,7 +56,7 @@ async function requestHumanApproval(toolCall) { Authorized humans subscribe to approval requests on the conversation channel and publish their decisions. The `requestId` correlates the response with the original request. -Use [identified clients](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-identity) or [user claims](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#user-claims) to establish a verified identity or role for the approver. For example, when a user [authenticates with Ably](/docs/ai-transport/features/sessions-identity/identifying-users-and-agents#authenticating), embed their identity and role in the JWT: +Use [identified clients](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-identity) or [user claims](/docs/ai-transport/sessions-identity/identifying-users-and-agents#user-claims) to establish a verified identity or role for the approver. For example, when a user [authenticates with Ably](/docs/ai-transport/sessions-identity/identifying-users-and-agents#authenticating), embed their identity and role in the JWT: ```javascript @@ -70,7 +70,7 @@ const claims = { The `clientId` and user claims are automatically attached to every message the user publishes and cannot be forged, so agents can trust this identity and role information. @@ -112,7 +112,7 @@ For audit trails, use [integration rules](/docs/integrations) to stream approval Use the `clientId` to identify the approver and look up their permissions in your database or user management system. This approach is useful when permissions are managed externally or change frequently. @@ -153,7 +153,7 @@ await channel.subscribe('approval-response', async (message) => { Use [user claims](/docs/auth/capabilities#custom-restrictions-on-channels-) to embed roles directly in the JWT for role-based access control (RBAC). This approach is useful when permissions are role-based rather than user-specific, allowing you to make authorization decisions based on the user's role without looking up individual user permissions. Different actions may require different authorization levels - for example, a user might approve low-value purchases, a manager might approve purchases up to a certain limit, while an admin can approve any purchase amount. When an approval arrives, compare the approver's role against the minimum required role for that action type: diff --git a/src/pages/docs/ai-transport/features/messaging/tool-calls.mdx b/src/pages/docs/ai-transport/messaging/tool-calls.mdx similarity index 93% rename from src/pages/docs/ai-transport/features/messaging/tool-calls.mdx rename to src/pages/docs/ai-transport/messaging/tool-calls.mdx index 36fc09784a..dddbcfc7eb 100644 --- a/src/pages/docs/ai-transport/features/messaging/tool-calls.mdx +++ b/src/pages/docs/ai-transport/messaging/tool-calls.mdx @@ -21,7 +21,7 @@ As an application developer, you decide how to surface tool calls to users. You Surfacing tool calls supports: - Trust and transparency: Users see what actions the AI is taking, building confidence in the agent -- Human-in-the-loop workflows: Expose tool calls [resolved by humans](/docs/ai-transport/features/messaging/human-in-the-loop) where users can review and approve tool execution before it happens +- Human-in-the-loop workflows: Expose tool calls [resolved by humans](/docs/ai-transport/messaging/human-in-the-loop) where users can review and approve tool execution before it happens - Generative UI: Build dynamic, contextual UI components based on the structured tool data ## Publishing tool calls @@ -91,7 +91,7 @@ Model APIs like OpenAI's [Responses API](https://platform.openai.com/docs/api-re ## Subscribing to tool calls @@ -154,7 +154,7 @@ await channel.subscribe((message) => { ## Generative UI @@ -184,7 +184,7 @@ await channel.subscribe((message) => { ## Client-side tools @@ -199,7 +199,7 @@ Client-side tool calls follow a request-response pattern over Ably channels: 4. The agent receives the result and continues processing. The client subscribes to tool call requests, executes the tool using device APIs, and publishes the result back to the channel. The `toolCallId` enables correlation between tool call requests and results: @@ -266,5 +266,5 @@ Tool calls resolved by humans are one approach to implementing human-in-the-loop For example, a tool that modifies data, performs financial transactions, or accesses sensitive resources might require explicit user approval before execution. The tool call information is surfaced to the user, who can then approve or reject the action. diff --git a/src/pages/docs/ai-transport/features/sessions-identity/identifying-users-and-agents.mdx b/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx similarity index 100% rename from src/pages/docs/ai-transport/features/sessions-identity/identifying-users-and-agents.mdx rename to src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx diff --git a/src/pages/docs/ai-transport/features/sessions-identity/index.mdx b/src/pages/docs/ai-transport/sessions-identity/index.mdx similarity index 100% rename from src/pages/docs/ai-transport/features/sessions-identity/index.mdx rename to src/pages/docs/ai-transport/sessions-identity/index.mdx diff --git a/src/pages/docs/ai-transport/features/sessions-identity/online-status.mdx b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx similarity index 99% rename from src/pages/docs/ai-transport/features/sessions-identity/online-status.mdx rename to src/pages/docs/ai-transport/sessions-identity/online-status.mdx index 7a852d482f..3e9722d647 100644 --- a/src/pages/docs/ai-transport/features/sessions-identity/online-status.mdx +++ b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx @@ -20,7 +20,7 @@ In channel-oriented sessions, online status serves several critical purposes: Use the [`enter()`](/docs/presence-occupancy/presence#enter) method to signal that a user or agent is online. When a client enters presence, they are added to the presence set and identified by their `clientId`. You can optionally include data when entering presence to communicate additional context. You have flexibility in when to enter presence. For example, an agent might choose to appear as online only while processing a specific task, or remain present for the duration of the entire session. Users typically enter presence when they connect to a session and remain present until they disconnect. diff --git a/src/pages/docs/ai-transport/features/sessions-identity/resuming-sessions.mdx b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx similarity index 97% rename from src/pages/docs/ai-transport/features/sessions-identity/resuming-sessions.mdx rename to src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx index 6883634eee..e5e4fbd159 100644 --- a/src/pages/docs/ai-transport/features/sessions-identity/resuming-sessions.mdx +++ b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx @@ -30,8 +30,8 @@ The hydration strategy you choose depends on your application model and your cho - Hydrate in-progress responses from the channel: Load completed messages from your database and catch up on any in-progress responses from the channel. For detailed examples of hydrating the token stream, see the token streaming documentation: -- [Message-per-response hydration](/docs/ai-transport/features/token-streaming/message-per-response#hydration) -- [Message-per-token hydration](/docs/ai-transport/features/token-streaming/message-per-token#hydration) +- [Message-per-response hydration](/docs/ai-transport/token-streaming/message-per-response#hydration) +- [Message-per-token hydration](/docs/ai-transport/token-streaming/message-per-token#hydration) ## Agent resumes a session diff --git a/src/pages/docs/ai-transport/features/token-streaming/index.mdx b/src/pages/docs/ai-transport/token-streaming/index.mdx similarity index 90% rename from src/pages/docs/ai-transport/features/token-streaming/index.mdx rename to src/pages/docs/ai-transport/token-streaming/index.mdx index 16d3bce087..b727224e71 100644 --- a/src/pages/docs/ai-transport/features/token-streaming/index.mdx +++ b/src/pages/docs/ai-transport/token-streaming/index.mdx @@ -52,7 +52,7 @@ The Realtime client maintains a persistent connection to the Ably service, enabl ### Message-per-response -[Message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) streams tokens as they arrive while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended. This results in efficient storage and straightforward retrieval of complete responses. +[Message-per-response](/docs/ai-transport/token-streaming/message-per-response) streams tokens as they arrive while maintaining a clean, compacted message history. Each LLM response becomes a single message on an Ably channel that grows as tokens are appended. This results in efficient storage and straightforward retrieval of complete responses. This pattern is the recommended approach for most applications. It excels when: @@ -67,7 +67,7 @@ Example use cases: ### Message-per-token -[Message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) publishes every generated token as an independent Ably message. Each token appears as a separate message in channel history. +[Message-per-token](/docs/ai-transport/token-streaming/message-per-token) publishes every generated token as an independent Ably message. Each token appears as a separate message in channel history. This pattern is useful when: @@ -87,6 +87,6 @@ Different models and frameworks use different events to signal streaming state, ## Next steps -- Implement token streaming with [message-per-response](/docs/ai-transport/features/token-streaming/message-per-response) (recommended for most applications) -- Implement token streaming with [message-per-token](/docs/ai-transport/features/token-streaming/message-per-token) for sliding-window use cases +- Implement token streaming with [message-per-response](/docs/ai-transport/token-streaming/message-per-response) (recommended for most applications) +- Implement token streaming with [message-per-token](/docs/ai-transport/token-streaming/message-per-token) for sliding-window use cases - Explore the guides for integration with specific models and frameworks diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx similarity index 100% rename from src/pages/docs/ai-transport/features/token-streaming/message-per-response.mdx rename to src/pages/docs/ai-transport/token-streaming/message-per-response.mdx diff --git a/src/pages/docs/ai-transport/features/token-streaming/message-per-token.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx similarity index 99% rename from src/pages/docs/ai-transport/features/token-streaming/message-per-token.mdx rename to src/pages/docs/ai-transport/token-streaming/message-per-token.mdx index 66232ff5a2..e7d9efe93d 100644 --- a/src/pages/docs/ai-transport/features/token-streaming/message-per-token.mdx +++ b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx @@ -240,7 +240,7 @@ For brief disconnections, Ably's automatic [connection recovery](docs/connect/st ### Using rewind for recent history diff --git a/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx b/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx index 7cc7579371..b8ac5f7c9f 100644 --- a/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx +++ b/src/pages/docs/guides/ai-transport/anthropic-message-per-response.mdx @@ -4,12 +4,12 @@ meta_description: "Stream tokens from the Anthropic Messages API over Ably in re meta_keywords: "AI, token streaming, Anthropic, Claude, Messages API, AI transport, Ably, realtime, message appends" --- -This guide shows you how to stream AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) over Ably using the [message-per-response pattern](/docs/ai-transport/features/token-streaming/message-per-response). Specifically, it appends each response token to a single Ably message, creating a complete AI response that grows incrementally while delivering tokens in realtime. +This guide shows you how to stream AI responses from Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) over Ably using the [message-per-response pattern](/docs/ai-transport/token-streaming/message-per-response). Specifically, it appends each response token to a single Ably message, creating a complete AI response that grows incrementally while delivering tokens in realtime. Using Ably to distribute tokens from the Anthropic SDK enables you to broadcast AI responses to thousands of concurrent subscribers with reliable message delivery and ordering guarantees. This approach stores each complete response as a single message in channel history, making it easy to retrieve conversation history without processing thousands of individual token messages. ## Prerequisites @@ -246,7 +246,7 @@ This implementation: - Appends each token to the original message