From 0ee88bf65970cd833253a297bced7c340eb2ac4e Mon Sep 17 00:00:00 2001 From: Fiona Corden Date: Thu, 18 Jun 2026 15:59:21 +0100 Subject: [PATCH 1/3] docs: route users between AI Transport and Chat SDKs Users doing AI chat and users doing user-to-user chat currently land on either the AI Transport or Chat product docs, but the two SDKs cannot be used together yet. Steer each audience to the right product: - Add a steering note to the AI Transport and Chat landing pages pointing the other audience to the right SDK. - Add a 'Choosing between AI Transport and Chat SDKs' section to the product guidance page with a decision table and the support-scenario rule (who answers the user). - Note in the why-AI-Transport page that human-to-human chat belongs in the Chat SDK. Wording makes clear the products are separate today and that closer integration is coming, so it does not read as a permanent split. AIT-865 --- src/pages/docs/ai-transport/index.mdx | 4 ++++ src/pages/docs/ai-transport/why/index.mdx | 1 + src/pages/docs/chat/index.mdx | 4 ++++ src/pages/docs/platform/products/index.mdx | 25 ++++++++++++++++++---- 4 files changed, 30 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/ai-transport/index.mdx b/src/pages/docs/ai-transport/index.mdx index 3539a20887..6e2a80383b 100644 --- a/src/pages/docs/ai-transport/index.mdx +++ b/src/pages/docs/ai-transport/index.mdx @@ -9,6 +9,10 @@ AI Transport gives your AI agents a session that outlives the connection. Tokens It works with any AI model or framework: OpenAI, Anthropic, Vercel AI SDK, LangChain, or your own stack. AI Transport runs on Ably's [fault-tolerant](/docs/platform/architecture/fault-tolerance) global platform, with messaging at [low latency](/docs/platform/architecture/latency) across regions and [elastic scale](/docs/platform/architecture/platform-scalability). + + ![Before and after adding AI Transport](../../../images/content/diagrams/ai-transport-before-and-after.png) ## Get started diff --git a/src/pages/docs/ai-transport/why/index.mdx b/src/pages/docs/ai-transport/why/index.mdx index cfdc495ac9..4758060f5b 100644 --- a/src/pages/docs/ai-transport/why/index.mdx +++ b/src/pages/docs/ai-transport/why/index.mdx @@ -84,6 +84,7 @@ The SDK provides the abstractions that make the model practical: ## When you don't need this Quick, single-turn chatbots do not need this. AI Transport is for experiences that are long-lived, agentic, and interactive, where sessions span conversations, devices, and time. If your users start and finish in one request, direct HTTP streaming is the simpler choice. +AI Transport is also not the right tool for conversations between people: for human-to-human chat such as group messaging or human-staffed support, use the [Chat SDK](/docs/chat). ## Why Ably diff --git a/src/pages/docs/chat/index.mdx b/src/pages/docs/chat/index.mdx index c4b96234fa..a8b3b3ca00 100644 --- a/src/pages/docs/chat/index.mdx +++ b/src/pages/docs/chat/index.mdx @@ -9,6 +9,10 @@ Ably Chat is a product dedicated to making it quick and easy to build chat funct The Chat SDK contains a set of purpose-built APIs that abstract away the complexities involved in how you would architect chat features. It utilizes Ably's platform to benefit from all of the same performance guarantees and scaling potential. + + * [Getting started: Chat in JavaScript / TypeScript](/docs/chat/getting-started/javascript) * [Getting started: Chat in React](/docs/chat/getting-started/react) * [Getting started: Chat UI Kit in React](/docs/chat/getting-started/react-ui-kit) diff --git a/src/pages/docs/platform/products/index.mdx b/src/pages/docs/platform/products/index.mdx index 293a248cb6..c9d0234fe3 100644 --- a/src/pages/docs/platform/products/index.mdx +++ b/src/pages/docs/platform/products/index.mdx @@ -32,13 +32,13 @@ Pub/Sub is a good fit when: Pub/Sub gives you direct access to Ably's underlying messaging primitives, including [channels](/docs/channels), [presence](/docs/presence-occupancy/presence), and [history](/docs/storage-history/history), enabling you to design your own message architecture. -### Chat SDK +### Chat SDK [Ably Chat](/docs/chat) provides purpose-built APIs for building chat functionality, including rooms, messages, typing indicators, reactions, and presence. Chat is a good fit when you're building: -* 1:1 customer support chat. +* 1:1 customer support chat with human agents. * Group conversations. * Livestream chat with thousands of users. * Or any application requiring chat functionality. @@ -56,6 +56,8 @@ The Chat SDK provides: | [Room reactions](/docs/chat/rooms/reactions) | Broadcast ephemeral sentiments to a room | | [Moderation](/docs/chat/moderation) | Detect and manage inappropriate content | +If your chat will include streaming LLM responses to answer the user, consider the [AI Transport SDK](#ait) instead. + ### Spaces SDK [Ably Spaces](/docs/spaces) provides high-level APIs for building collaborative environments where users work together in realtime. @@ -109,7 +111,7 @@ LiveSync is a good fit when: * You want to enable optimistic updates in the UI. * You're using PostgreSQL or MongoDB. -### AI Transport +### AI Transport [Ably AI Transport](/docs/ai-transport) provides purpose-built APIs for streaming AI-generated content to users in realtime, handling token streaming, session management, and multi-user fan-out. @@ -119,6 +121,8 @@ AI Transport is a good fit when: * You need to manage AI chat sessions with identity and resumability. * You want to fan out AI-generated content to multiple subscribers. +If your chat is primarly between humans, even when AI moderates or assists behind the scenes, then consider the [Chat SDK](#chat). + ### Why use purpose-built SDKs Purpose-built SDKs provide an API optimized for specific use cases: @@ -233,7 +237,7 @@ Available protocol adapters: Protocol adapters do not support the full set of Ably features. For example, the MQTT protocol adapter does not support presence, and the SSE protocol does not support message publishing. -## Combining SDKs with Pub/Sub +## Combining SDKs with Pub/Sub Purpose-built SDKs like Chat and Spaces are built on top of the Ably Pub/Sub SDK. When you initialize a purpose-built SDK, it creates or accepts an underlying Ably Realtime client. This means you can use that same client to interact with Pub/Sub channels directly, sharing a single connection to Ably rather than opening multiple connections. Use your own channels for custom Pub/Sub features, but do not interact directly with channels managed by the purpose-built SDK. @@ -287,6 +291,19 @@ When combining SDKs with Pub/Sub: * **Consider message ordering**: Messages on SDK-managed channels and custom Pub/Sub channels are independent; design your application accordingly. * **Handle connection state once**: The underlying Realtime client manages connection state; don't add redundant connection handling for custom features. +## Choosing between AI Transport and Chat SDKs + +AI Transport and the Chat SDK both handle conversations but for different types of users. + +| You are building | Use | +| --- | --- | +| A user conversing with an AI agent: streaming responses, multi-turn, across devices | [AI Transport](/docs/ai-transport) | +| People conversing with each other: support staffed by humans, group chat, livestream chat | [Chat SDK](/docs/chat) | + +In support scenarios, if an AI answers the user then reach for AI Transport, even when a human can take over the conversation. If people staff the conversation, reach for the Chat SDK, even when AI moderates or assists behind the scenes. + +The two products run on the same Ably platform but are separate today, so you can [combine](#combine-pubsub) either of them with Pub/Sub but not with each other. Closer integration between AI Transport and Chat is coming soon, which will give applications that need both AI-driven and human-to-human messaging a simple implementation path. + ## Next steps * Follow the [getting started guide](/docs/getting-started) to start building with Ably Pub/Sub. From c7e4f05cc3a727d49059fe69a89814f148dc9bd1 Mon Sep 17 00:00:00 2001 From: Fiona Corden Date: Thu, 18 Jun 2026 22:16:32 +0100 Subject: [PATCH 2/3] docs: expand why each SDK suits its use case (AIT-865) Address Paddy's review: explain what the Chat SDK covers for human chat, and why agent applications need AI Transport (regeneration and conversation forking beyond message editing, runs and steps as control flow rather than just progress indicators). --- src/pages/docs/platform/products/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/pages/docs/platform/products/index.mdx b/src/pages/docs/platform/products/index.mdx index c9d0234fe3..6df7b05e0b 100644 --- a/src/pages/docs/platform/products/index.mdx +++ b/src/pages/docs/platform/products/index.mdx @@ -300,6 +300,10 @@ AI Transport and the Chat SDK both handle conversations but for different types | A user conversing with an AI agent: streaming responses, multi-turn, across devices | [AI Transport](/docs/ai-transport) | | People conversing with each other: support staffed by humans, group chat, livestream chat | [Chat SDK](/docs/chat) | +The Chat SDK provides support for operations that are commonly needed in chat applications: not just publishing and subscribing to messages, but moderation, typing indicators, emoji reactions, and editing and deleting messages. + +AI Transport supports interactions with AI agents that go beyond this. It is built for human-to-agent and client-to-agent interactions that support an agentic loop, tool calls, human-in-the-loop, interruption and steering, as well as streamed responses. Simple editing of messages, as supported by the Chat SDK, is not sufficient for agent applications, because of the need to support regeneration of responses and the resultant forking of conversations. Similarly, agentic applications have a much richer need to indicate progress than the simple typing indicators sufficient for human chat, and agentic interactions such as runs and steps are an intrinsic part of the control flow of an agent session, not just a visual indicator. + In support scenarios, if an AI answers the user then reach for AI Transport, even when a human can take over the conversation. If people staff the conversation, reach for the Chat SDK, even when AI moderates or assists behind the scenes. The two products run on the same Ably platform but are separate today, so you can [combine](#combine-pubsub) either of them with Pub/Sub but not with each other. Closer integration between AI Transport and Chat is coming soon, which will give applications that need both AI-driven and human-to-human messaging a simple implementation path. From bebc349acb231acdc98d2a730cd193fb637bdfbf Mon Sep 17 00:00:00 2001 From: Fiona Corden Date: Thu, 18 Jun 2026 22:49:30 +0100 Subject: [PATCH 3/3] docs: fix typo and tidy SDK naming in comparison section (AIT-865) Fix 'primarly' typo and use consistent article and naming for the AI Transport SDK and the Chat SDK. --- src/pages/docs/platform/products/index.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/platform/products/index.mdx b/src/pages/docs/platform/products/index.mdx index 6df7b05e0b..ecd81088d5 100644 --- a/src/pages/docs/platform/products/index.mdx +++ b/src/pages/docs/platform/products/index.mdx @@ -121,7 +121,7 @@ AI Transport is a good fit when: * You need to manage AI chat sessions with identity and resumability. * You want to fan out AI-generated content to multiple subscribers. -If your chat is primarly between humans, even when AI moderates or assists behind the scenes, then consider the [Chat SDK](#chat). +If your chat is primarily between humans, even when AI moderates or assists behind the scenes, then consider the [Chat SDK](#chat). ### Why use purpose-built SDKs @@ -291,19 +291,19 @@ When combining SDKs with Pub/Sub: * **Consider message ordering**: Messages on SDK-managed channels and custom Pub/Sub channels are independent; design your application accordingly. * **Handle connection state once**: The underlying Realtime client manages connection state; don't add redundant connection handling for custom features. -## Choosing between AI Transport and Chat SDKs +## Choosing between AI Transport and the Chat SDK -AI Transport and the Chat SDK both handle conversations but for different types of users. +The AI Transport SDK and the Chat SDK both handle conversations but for different types of users and operations. + +The Chat SDK provides support for common chat application operations: not just publishing and subscribing to messages, but moderation, typing indicators, emoji reactions, and editing or deleting messages. + +The AI Transport SDK enables interactions with AI agents that go beyond those operations. It is built for human-to-agent and client-to-agent interactions that support an agentic loop, tool calls, human-in-the-loop, interruption and steering, as well as streamed responses. Simple editing of messages, as supported by the Chat SDK, is not sufficient for agent applications, because of the need to support regeneration of responses and the resultant forking of conversations. Similarly, agentic applications have a much richer need to indicate progress than the simple typing indicators used for human chat, and agentic interactions such as runs and steps are an intrinsic part of the control flow of an agent session, not just a visual indicator. | You are building | Use | | --- | --- | | A user conversing with an AI agent: streaming responses, multi-turn, across devices | [AI Transport](/docs/ai-transport) | | People conversing with each other: support staffed by humans, group chat, livestream chat | [Chat SDK](/docs/chat) | -The Chat SDK provides support for operations that are commonly needed in chat applications: not just publishing and subscribing to messages, but moderation, typing indicators, emoji reactions, and editing and deleting messages. - -AI Transport supports interactions with AI agents that go beyond this. It is built for human-to-agent and client-to-agent interactions that support an agentic loop, tool calls, human-in-the-loop, interruption and steering, as well as streamed responses. Simple editing of messages, as supported by the Chat SDK, is not sufficient for agent applications, because of the need to support regeneration of responses and the resultant forking of conversations. Similarly, agentic applications have a much richer need to indicate progress than the simple typing indicators sufficient for human chat, and agentic interactions such as runs and steps are an intrinsic part of the control flow of an agent session, not just a visual indicator. - In support scenarios, if an AI answers the user then reach for AI Transport, even when a human can take over the conversation. If people staff the conversation, reach for the Chat SDK, even when AI moderates or assists behind the scenes. The two products run on the same Ably platform but are separate today, so you can [combine](#combine-pubsub) either of them with Pub/Sub but not with each other. Closer integration between AI Transport and Chat is coming soon, which will give applications that need both AI-driven and human-to-human messaging a simple implementation path.