Add session abandonment documentation for AI Transport

src/data/index.ts

@@ -1,4 +1,12 @@
-import { chatNavData, liveObjectsNavData, liveSyncNavData, platformNavData, pubsubNavData, spacesNavData } from './nav';
+import {
+  aiTransportNavData,
+  chatNavData,
+  liveObjectsNavData,
+  liveSyncNavData,
+  platformNavData,
+  pubsubNavData,
+  spacesNavData,
+} from './nav';
 import { languageData } from './languages';
 import { PageData, ProductData } from './types';
 import homepageContentData from './content/homepage';
@@ -16,6 +24,10 @@ export const productData = {
     nav: chatNavData,
     languages: languageData.chat,
   },
+  aiTransport: {
+    nav: aiTransportNavData,
+    languages: languageData.aiTransport,
+  },
   spaces: {
     nav: spacesNavData,
     languages: languageData.spaces,

src/data/languages/languageData.ts

@@ -29,6 +29,9 @@ export default {
     swift: '1.0',
     kotlin: '1.0',
   },
+  aiTransport: {
+    javascript: '2.11',
+  },
   spaces: {
     javascript: '0.4',
     react: '0.4',

src/data/nav/aitransport.ts

@@ -0,0 +1,36 @@
+import { NavProduct } from './types';
+
+export default {
+  name: 'Ably AI Transport',
+  link: '/docs/ai-transport',
+  icon: {
+    closed: 'icon-gui-prod-ai-transport-outline',
+    open: 'icon-gui-prod-ai-transport-solid',
+  },
+  content: [
+    {
+      name: 'Introduction',
+      pages: [
+        {
+          name: 'About AI Transport',
+          link: '/docs/ai-transport',
+          index: true,
+        },
+      ],
+    },
+    {
+      name: 'Sessions & Identity',
+      pages: [
+        {
+          name: 'Overview',
+          link: '/docs/ai-transport/sessions-identity/overview',
+        },
+        {
+          name: 'Session abandonment',
+          link: '/docs/ai-transport/sessions-identity/session-abandonment',
+        },
+      ],
+    },
+  ],
+  api: [],
+} satisfies NavProduct;

src/data/nav/index.ts

@@ -1,8 +1,17 @@
 import platformNavData from './platform';
 import pubsubNavData from './pubsub';
 import chatNavData from './chat';
+import aiTransportNavData from './aitransport';
 import liveObjectsNavData from './liveobjects';
 import spacesNavData from './spaces';
 import liveSyncNavData from './livesync';
 
-export { platformNavData, pubsubNavData, chatNavData, liveObjectsNavData, spacesNavData, liveSyncNavData };
+export {
+  platformNavData,
+  pubsubNavData,
+  chatNavData,
+  aiTransportNavData,
+  liveObjectsNavData,
+  spacesNavData,
+  liveSyncNavData,
+};

src/data/types.ts

@@ -3,7 +3,7 @@ import { LanguageData } from './languages/types';
 import { NavProduct } from './nav/types';
 
 const pageKeys = ['homepage'] as const;
-const productKeys = ['platform', 'pubsub', 'chat', 'spaces', 'liveObjects', 'liveSync'] as const;
+const productKeys = ['platform', 'pubsub', 'chat', 'aiTransport', 'spaces', 'liveObjects', 'liveSync'] as const;
 
 export type ProductKey = (typeof productKeys)[number];
 type PageKey = (typeof pageKeys)[number];

src/pages/docs/ai-transport/index.mdx

@@ -0,0 +1,6 @@
+---
+title: About AI Transport
+meta_description: "Learn more about Ably's AI Transport and the features that enable you to quickly build functionality into new and existing applications."
+redirect_from:
+  - /docs/products/ai-transport
+---

src/pages/docs/ai-transport/sessions-identity/overview.mdx

@@ -0,0 +1,65 @@
+---
+title: "Sessions & identity overview"
+meta_description: "Manage session lifecycle and identity in decoupled AI architectures"
+---
+
+Ably AI Transport provides robust session management and identity capabilities designed for modern AI applications. Sessions persist beyond individual connections, enabling agents and clients to connect independently through shared channels. Built-in token-based authentication provides verified user identity and fine-grained authorization for channel operations.
+
+## What is a session?
+
+A session is an interaction between a user (or multiple users) and an AI agent where messages and data are exchanged, building up shared context over time. In AI Transport, sessions are designed to persist beyond the boundaries of individual connections, enabling modern AI experiences where users expect to:
+
+- **Resume conversations across devices** - Start a conversation on mobile and seamlessly continue on desktop with full context preserved
+- **Return to long-running work** - Close the browser while agents continue processing in the background, delivering results when you return
+- **Recover from interruptions** - Experience connection drops, browser refreshes, or network instability without losing conversation progress
+- **Collaborate in shared sessions** - Multiple users can participate in the same conversation simultaneously and remain in sync
+
+These capabilities represent a fundamental shift from traditional request/response AI experiences to continuous, resumable interactions that follow users wherever they go. Sessions have a lifecycle: they begin when a user starts interacting with an agent, remain active while the interaction continues, and can persist even when users disconnect - enabling truly asynchronous AI workflows.
+
+Managing this lifecycle in AI Transport's decoupled architecture involves detecting when users are present, deciding when to stop or continue agent work, and handling scenarios where users disconnect and return.
+
+## Connection-oriented vs channel-oriented sessions
+
+In traditional connection-oriented architectures, sessions are bound to the lifecycle of a WebSocket or SSE connection:
+
+1. Client opens connection to agent server to establish a session
+2. Agent streams response over the connection
+3. When the connection closes, the session ends
+
+This tight coupling means network interruptions terminate sessions, agents can't continue work after disconnections, and supporting multiple devices or users introduces significant complexity.
+
+![Traditional HTTP streaming architecture](../../../../images/content/ai-transport/ait-http-streaming.webp)
+
+
+AI Transport uses a channel-oriented model where sessions persist independently of individual connections. Clients and agents communicate through [Channels](/docs/channels):
+
+1. Client sends a single request to agent server to establish a session
+2. Server responds with a unique ID for the session, which is used to identify the channel
+3. All further communication happens over the channel
+
+In this model, sessions are associated with the channel, enabling seamless reconnection, background agent work, and multi-device access without additional complexity.
+
+![AI Transport architecture](../../../../images/content/ai-transport/ait-with-ait.webp)
+
+
+The channel-oriented model provides key benefits for modern AI applications: sessions maintain continuity in the face of disconnections, users can refresh or navigate back to the ongoing session, multiple users or devices can participate in the same session, and agents can continue long-running or asynchronous workloads even when clients disconnect.
+
+The following table compares how each architecture addresses the engineering challenges of delivering these capabilities:
+
+| Challenge | Connection-oriented sessions | Channel-oriented sessions |
+|-----------|------------------------------|---------------------------|
+| **Routing** | Agents must track which instance holds each session. Reconnecting clients need routing logic to find the correct agent instance across your infrastructure. | Agents and clients only need the channel name. Ably handles message delivery to all subscribers without agents tracking sessions or implementing routing logic. |
+| **Message resume** | Agents must buffer sent messages and implement replay logic. When clients reconnect, agents must determine what was missed and retransmit without duplicates or gaps, distinctly for each connection. | When clients reconnect, they automatically receive messages published while disconnected. The channel maintains history without agents implementing buffering or replay logic, eliminating the need for server-side session state. |
+| **Abandonment detection** | Agents must implement logic to distinguish between brief network interruptions and users who have actually left, so they can decide whether to continue work or clean up resources. | Built-in presence tracking signals when users enter and leave channels, providing clear lifecycle events to agents without custom detection logic. |
+| **Multi-user and multi-device** | Agents must manage multiple concurrent connections from the same user across devices, or from multiple users in collaborative sessions. This requires tracking connections, synchronizing state, and ensuring all participants receive consistent updates. | Multiple users and devices can connect to the same channel. The channel handles message delivery to all participants, simplifying agent logic for multi-user and multi-device scenarios. |
+
+## Identity in channel-oriented sessions
+
+In connection-oriented architectures, the agent server handles authentication directly when establishing the connection. When the connection is opened, the server verifies credentials and associates the authenticated user identity with that specific connection.
+
+In channel-oriented sessions, agents don't manage connections or handle authentication directly. Instead, your server authenticates users and issues tokens that control their access to channels. Ably enforces these authorization rules and provides verified identity information to agents, giving you powerful capabilities for managing who can participate in sessions and what they can do:
+
+- **Verified identity**: Agents automatically receive the authenticated identity of message senders, with cryptographic guarantees that identities cannot be spoofed
+- **Granular authorization**: Control precisely what operations each user can perform on specific channels through fine-grained capabilities
+- **Rich user attributes**: Pass authenticated user data to agents for personalized behavior without building custom token systems
+- **Role-based participation**: Distinguish between different types of participants, such as users and agents, to customize behaviour based on their role