ably · rainbowFi · Jun 18, 2026 · Jun 18, 2026 · Jun 18, 2026
diff --git 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).
 
+<Aside data-type='note'>
+AI Transport is for conversations between a user and an AI agent. If you are building conversations between people, such as human-staffed support, group chat, or livestream chat, use the [Chat SDK](/docs/chat). The two are separate products today; see [choosing between AI Transport and Chat](/docs/platform/products#ait-vs-chat).
+</Aside>
+
 ![Before and after adding AI Transport](../../../images/content/diagrams/ai-transport-before-and-after.png)
 
 ## Get started <a id="get-started"/>

diff --git 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 <a id="when-you-dont-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 <a id="why-ably"/>
 

diff --git 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.
 
+<Aside data-type='note'>
+The Chat SDK is for conversations between people. If you are building conversations between a user and an AI agent, such as an AI assistant or AI-driven support that streams model responses, use [AI Transport](/docs/ai-transport). The two are separate products today; see [choosing between AI Transport and Chat](/docs/platform/products#ait-vs-chat).
+</Aside>
+
 * [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
@@ -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 <a id="chat"/>
 
 [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 <a id="ait"/>
 
 [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 primarily 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 <a id="combine-pubsub"/>
 
 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,23 @@ 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 the Chat SDK <a id="ait-vs-chat"/>
+
+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) |
+
+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.