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..ecd81088d5 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 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 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 + +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.