From de9a678b298813b0e87306d7ed701a40a9887394 Mon Sep 17 00:00:00 2001
From: evgeny <khokhlov.e.n@gmail.com>
Date: Mon, 26 Jan 2026 12:07:55 +0000
Subject: [PATCH 1/2] [AIT-278][AIT-303] feat: Add Python and Java examples for
 AIT guides

- Added examples in Python and Java for processing user input, streaming responses, human-approval flows, and chain-of-thought reasoning.
- Covered annotations use cases, including citations with metadata.
- Updated documentation with code illustrating multi-channel communication.
---
 .../messaging/accepting-user-input.mdx        | 327 +++++++++++
 .../messaging/chain-of-thought.mdx            | 281 +++++++++
 .../docs/ai-transport/messaging/citations.mdx |  74 +++
 .../messaging/human-in-the-loop.mdx           | 216 +++++++
 .../ai-transport/messaging/tool-calls.mdx     | 325 +++++++++++
 .../identifying-users-and-agents.mdx          | 488 ++++++++++++++++
 .../sessions-identity/online-status.mdx       | 287 +++++++++
 .../sessions-identity/resuming-sessions.mdx   | 101 ++++
 .../token-streaming/message-per-response.mdx  | 542 +++++++++++++++++
 .../token-streaming/message-per-token.mdx     | 545 ++++++++++++++++++
 10 files changed, 3186 insertions(+)

diff --git a/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx b/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx
index 2a66b7f43d..9ec4af4b8f 100644
--- a/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx
+++ b/src/pages/docs/ai-transport/messaging/accepting-user-input.mdx
@@ -43,6 +43,15 @@ const claims = {
   'x-ably-clientId': 'user-123'
 };
 ```
+```python
+claims = {
+    'x-ably-clientId': 'user-123'
+}
+```
+```java
+Map<String, String> claims = new HashMap<>();
+claims.put("x-ably-clientId", "user-123");
+```
 </Code>
 
 The `clientId` is automatically attached to every message the user publishes, so agents can trust this identity.
@@ -58,6 +67,30 @@ await channel.subscribe('user-input', (message) => {
   processAndRespond(channel, text, promptId, userId);
 });
 ```
+```python
+def on_user_input(message):
+    user_id = message.client_id
+    # promptId is a user-generated UUID for correlating responses
+    prompt_id = message.data['promptId']
+    text = message.data['text']
+
+    print(f'Received prompt from user {user_id}')
+    process_and_respond(channel, text, prompt_id, user_id)
+
+await channel.subscribe('user-input', on_user_input)
+```
+```java
+channel.subscribe("user-input", message -> {
+    String userId = message.clientId;
+    // promptId is a user-generated UUID for correlating responses
+    JsonObject data = (JsonObject) message.data;
+    String promptId = data.get("promptId").getAsString();
+    String text = data.get("text").getAsString();
+
+    System.out.println("Received prompt from user " + userId);
+    processAndRespond(channel, text, promptId, userId);
+});
+```
 </Code>
 
 ### Verify by role <a id="verify-role"/>
@@ -72,6 +105,15 @@ const claims = {
   'ably.channel.*': 'user'
 };
 ```
+```python
+claims = {
+    'ably.channel.*': 'user'
+}
+```
+```java
+Map<String, String> claims = new HashMap<>();
+claims.put("ably.channel.*", "user");
+```
 </Code>
 
 The user claim is automatically attached to every message the user publishes, so agents can trust this role information.
@@ -91,6 +133,37 @@ await channel.subscribe('user-input', (message) => {
   processAndRespond(channel, text, promptId);
 });
 ```
+```python
+def on_user_input(message):
+    role = message.extras.get('userClaim')
+    # promptId is a user-generated UUID for correlating responses
+    prompt_id = message.data['promptId']
+    text = message.data['text']
+
+    if role != 'user':
+        print('Ignoring message from non-user')
+        return
+
+    process_and_respond(channel, text, prompt_id)
+
+await channel.subscribe('user-input', on_user_input)
+```
+```java
+channel.subscribe("user-input", message -> {
+    String role = message.extras.get("userClaim").getAsString();
+    // promptId is a user-generated UUID for correlating responses
+    JsonObject data = (JsonObject) message.data;
+    String promptId = data.get("promptId").getAsString();
+    String text = data.get("text").getAsString();
+
+    if (!role.equals("user")) {
+        System.out.println("Ignoring message from non-user");
+        return;
+    }
+
+    processAndRespond(channel, text, promptId);
+});
+```
 </Code>
 
 ## Publish user input <a id="publish"/>
@@ -107,6 +180,30 @@ await channel.publish('user-input', {
   text: 'What is the weather like today?'
 });
 ```
+```python
+import uuid
+
+channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+prompt_id = str(uuid.uuid4())
+message = Message(
+    name='user-input',
+    data={
+        'promptId': prompt_id,
+        'text': 'What is the weather like today?'
+    }
+)
+await channel.publish(message)
+```
+```java
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+String promptId = UUID.randomUUID().toString();
+JsonObject data = new JsonObject();
+data.addProperty("promptId", promptId);
+data.addProperty("text", "What is the weather like today?");
+channel.publish("user-input", data);
+```
 </Code>
 
 <Aside data-type="note">
@@ -136,6 +233,43 @@ await channel.subscribe('user-input', (message) => {
   processAndRespond(channel, text, promptId);
 });
 ```
+```python
+from ably import AblyRealtime
+
+ably = AblyRealtime(key='{{API_KEY}}')
+channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+def on_user_input(message):
+    prompt_id = message.data['promptId']
+    text = message.data['text']
+    user_id = message.client_id
+
+    print(f'Received prompt from {user_id}: {text}')
+
+    # Process the prompt and generate a response
+    process_and_respond(channel, text, prompt_id)
+
+await channel.subscribe('user-input', on_user_input)
+```
+```java
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.realtime.Channel;
+
+AblyRealtime ably = new AblyRealtime("{{API_KEY}}");
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe("user-input", message -> {
+    JsonObject data = (JsonObject) message.data;
+    String promptId = data.get("promptId").getAsString();
+    String text = data.get("text").getAsString();
+    String userId = message.clientId;
+
+    System.out.println("Received prompt from " + userId + ": " + text);
+
+    // Process the prompt and generate a response
+    processAndRespond(channel, text, promptId);
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -166,6 +300,40 @@ async function processAndRespond(channel, prompt, promptId) {
   });
 }
 ```
+```python
+async def process_and_respond(channel, prompt, prompt_id):
+    # Generate the response (e.g., call your AI model)
+    response = await generate_ai_response(prompt)
+
+    message = Message(
+        name='agent-response',
+        data=response,
+        extras={
+            'headers': {
+                'promptId': prompt_id
+            }
+        }
+    )
+
+    # Publish the response with the promptId for correlation
+    await channel.publish(message)
+```
+```java
+void processAndRespond(Channel channel, String prompt, String promptId) {
+    // Generate the response (e.g., call your AI model)
+    String response = generateAIResponse(prompt);
+
+    // Publish the response with the promptId for correlation
+    JsonObject extras = new JsonObject();
+    JsonObject headers = new JsonObject();
+    headers.addProperty("promptId", promptId);
+    extras.add("headers", headers);
+
+    Message message = new Message("agent-response", response, new MessageExtras(extras));
+
+    channel.publish(message);
+}
+```
 </Code>
 
 The user's client can then match responses to their original prompts:
@@ -193,6 +361,60 @@ await channel.subscribe('agent-response', (message) => {
   }
 });
 ```
+```python
+import uuid
+
+pending_prompts = {}
+
+# Send a prompt and track it
+async def send_prompt(text):
+    prompt_id = str(uuid.uuid4())
+    pending_prompts[prompt_id] = {'text': text}
+    message = Message(name='user-input', data={'promptId': prompt_id, 'text': text})
+    await channel.publish(message)
+    return prompt_id
+
+# Handle responses
+def on_agent_response(message):
+    prompt_id = message.extras.get('headers', {}).get('promptId')
+
+    if prompt_id and prompt_id in pending_prompts:
+        original_prompt = pending_prompts[prompt_id]
+        print(f'Response for "{original_prompt["text"]}": {message.data}')
+        del pending_prompts[prompt_id]
+
+await channel.subscribe('agent-response', on_agent_response)
+```
+```java
+Map<String, Map<String, String>> pendingPrompts = new ConcurrentHashMap<>();
+
+// Send a prompt and track it
+String sendPrompt(String text) {
+    String promptId = UUID.randomUUID().toString();
+    Map<String, String> promptData = new HashMap<>();
+    promptData.put("text", text);
+    pendingPrompts.put(promptId, promptData);
+
+    JsonObject data = new JsonObject();
+    data.addProperty("promptId", promptId);
+    data.addProperty("text", text);
+    channel.publish("user-input", data);
+
+    return promptId;
+}
+
+// Handle responses
+channel.subscribe("agent-response", message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers");
+    String promptId = headers != null ? headers.get("promptId").getAsString() : null;
+
+    if (promptId != null && pendingPrompts.containsKey(promptId)) {
+        Map<String, String> originalPrompt = pendingPrompts.get(promptId);
+        System.out.println("Response for \"" + originalPrompt.get("text") + "\": " + message.data);
+        pendingPrompts.remove(promptId);
+    }
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -233,6 +455,66 @@ async function streamResponse(channel, prompt, promptId) {
   }
 }
 ```
+```python
+async def stream_response(channel, prompt, prompt_id):
+    # Create initial message for message-per-response pattern
+    message = Message(
+        name='agent-response',
+        data='',
+        extras={
+            'headers': {
+                'promptId': prompt_id
+            }
+        }
+    )
+    result = await channel.publish(message)
+    message_serial = result.serials[0]
+
+    # Stream tokens by appending to the message
+    async for token in generate_tokens(prompt):
+        await channel.append_message(
+            serial=message_serial,
+            data=token,
+            extras={
+                'headers': {
+                    'promptId': prompt_id
+                }
+            }
+        )
+```
+```java
+void streamResponse(Channel channel, String prompt, String promptId) throws Exception {
+    // Create initial message for message-per-response pattern
+    JsonObject extras = new JsonObject();
+    JsonObject headers = new JsonObject();
+    headers.addProperty("promptId", promptId);
+    extras.add("headers", headers);
+
+    CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
+    channel.publish("agent-response", "", extras, new Callback<PublishResult>() {
+        @Override
+        public void onSuccess(PublishResult result) {
+            publishFuture.complete(result);
+        }
+
+        @Override
+        public void onError(ErrorInfo reason) {
+            publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
+        }
+    });
+    String messageSerial = publishFuture.get().serials[0];
+
+    // Stream tokens by appending to the message
+    for (String token : generateTokens(prompt)) {
+        JsonObject appendExtras = new JsonObject();
+        JsonObject appendHeaders = new JsonObject();
+        appendHeaders.addProperty("promptId", promptId);
+        appendExtras.add("headers", appendHeaders);
+
+        channel.appendMessage(messageSerial, token, appendExtras);
+    }
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -265,4 +547,49 @@ await channel.subscribe('user-input', async (message) => {
   }
 });
 ```
+```python
+# Agent handling multiple concurrent prompts
+active_requests = {}
+
+async def on_user_input(message):
+    prompt_id = message.data['promptId']
+    text = message.data['text']
+    user_id = message.client_id
+
+    # Track active request
+    active_requests[prompt_id] = {
+        'userId': user_id,
+        'text': text,
+    }
+
+    try:
+        await stream_response(channel, text, prompt_id)
+    finally:
+        del active_requests[prompt_id]
+
+await channel.subscribe('user-input', on_user_input)
+```
+```java
+// Agent handling multiple concurrent prompts
+Map<String, Map<String, String>> activeRequests = new ConcurrentHashMap<>();
+
+channel.subscribe("user-input", message -> {
+    JsonObject data = (JsonObject) message.data;
+    String promptId = data.get("promptId").getAsString();
+    String text = data.get("text").getAsString();
+    String userId = message.clientId;
+
+    // Track active request
+    Map<String, String> requestData = new HashMap<>();
+    requestData.put("userId", userId);
+    requestData.put("text", text);
+    activeRequests.put(promptId, requestData);
+
+    try {
+        streamResponse(channel, text, promptId);
+    } finally {
+        activeRequests.remove(promptId);
+    }
+});
+```
 </Code>
diff --git a/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx
index 15c40d0dc0..fa4cd254b1 100644
--- a/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/messaging/chain-of-thought.mdx
@@ -76,6 +76,63 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like:
+# { 'type': 'reasoning', 'text': "Let's break down the problem: 27 * 12", 'responseId': 'resp_abc123' }
+# { 'type': 'reasoning', 'text': 'First, I can split this into 27 * 10 + 27 * 2', 'responseId': 'resp_abc123' }
+# { 'type': 'reasoning', 'text': 'That gives us 270 + 54 = 324', 'responseId': 'resp_abc123' }
+# { 'type': 'message', 'text': '27 * 12 = 324', 'responseId': 'resp_abc123' }
+
+async for event in stream:
+    if event['type'] == 'reasoning':
+        # Publish reasoning messages
+        await channel.publish(
+            name='reasoning',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+    elif event['type'] == 'message':
+        # Publish model output messages
+        await channel.publish(
+            name='message',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like:
+// { type: 'reasoning', text: "Let's break down the problem: 27 * 12", responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'First, I can split this into 27 * 10 + 27 * 2', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'That gives us 270 + 54 = 324', responseId: 'resp_abc123' }
+// { type: 'message', text: '27 * 12 = 324', responseId: 'resp_abc123' }
+
+for (Event event : stream) {
+    JsonObject extras = new JsonObject();
+    JsonObject headers = new JsonObject();
+    headers.addProperty("responseId", event.getResponseId());
+    extras.add("headers", headers);
+
+    if (event.getType().equals("reasoning")) {
+        // Publish reasoning messages
+        channel.publish(new Message("reasoning", event.getText(), new MessageExtras(extras)));
+    } else if (event.getType().equals("message")) {
+        // Publish model output messages
+        channel.publish(new Message("message", event.getText(), new MessageExtras(extras)));
+    }
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -132,6 +189,74 @@ await channel.subscribe((message) => {
   console.log(`Response ${responseId}:`, response);
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by ID, each containing reasoning messages and final response
+responses = {}
+
+# Subscribe to all events on the channel
+def on_message(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Message missing responseId')
+        return
+
+    # Initialize response object if needed
+    if response_id not in responses:
+        responses[response_id] = {
+            'reasoning': [],
+            'message': ''
+        }
+
+    response = responses[response_id]
+
+    # Handle each message type
+    if message.name == 'message':
+        response['message'] = message.data
+    elif message.name == 'reasoning':
+        response['reasoning'].append(message.data)
+
+    # Display the reasoning and response for this turn
+    print(f'Response {response_id}:', response)
+
+await channel.subscribe(on_message)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by ID, each containing reasoning messages and final response
+Map<String, Response> responses = new ConcurrentHashMap<>();
+
+// Subscribe to all events on the channel
+channel.subscribe(message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Message missing responseId");
+        return;
+    }
+
+    // Initialize response object if needed
+    responses.putIfAbsent(responseId, new Response());
+    Response response = responses.get(responseId);
+
+    // Handle each message type
+    switch (message.name) {
+        case "message":
+            response.setMessage((String) message.data);
+            break;
+        case "reasoning":
+            response.getReasoning().add((String) message.data);
+            break;
+    }
+
+    // Display the reasoning and response for this turn
+    System.out.println("Response " + responseId + ": " + response);
+});
+```
 </Code>
 
 <Aside data-type="further-reading">
@@ -202,6 +327,82 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+conversation_channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like:
+# { 'type': 'start', 'responseId': 'resp_abc123' }
+# { 'type': 'reasoning', 'text': "Let's break down the problem: 27 * 12", 'responseId': 'resp_abc123' }
+# { 'type': 'reasoning', 'text': 'First, I can split this into 27 * 10 + 27 * 2', 'responseId': 'resp_abc123' }
+# { 'type': 'reasoning', 'text': 'That gives us 270 + 54 = 324', 'responseId': 'resp_abc123' }
+# { 'type': 'message', 'text': '27 * 12 = 324', 'responseId': 'resp_abc123' }
+
+async for event in stream:
+    if event['type'] == 'start':
+        # Publish response start control message
+        await conversation_channel.publish(
+            name='start',
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+    elif event['type'] == 'reasoning':
+        # Publish reasoning to separate reasoning channel
+        reasoning_channel = realtime.channels.get(f"{{{{RANDOM_CHANNEL_NAME}}}}:{event['responseId']}")
+
+        await reasoning_channel.publish(
+            name='reasoning',
+            data=event['text']
+        )
+    elif event['type'] == 'message':
+        # Publish model output to main channel
+        await conversation_channel.publish(
+            name='message',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+```
+```java
+Channel conversationChannel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like:
+// { type: 'start', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: "Let's break down the problem: 27 * 12", responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'First, I can split this into 27 * 10 + 27 * 2', responseId: 'resp_abc123' }
+// { type: 'reasoning', text: 'That gives us 270 + 54 = 324', responseId: 'resp_abc123' }
+// { type: 'message', text: '27 * 12 = 324', responseId: 'resp_abc123' }
+
+for (Event event : stream) {
+    if (event.getType().equals("start")) {
+        // Publish response start control message
+        JsonObject extras = new JsonObject();
+        JsonObject headers = new JsonObject();
+        headers.addProperty("responseId", event.getResponseId());
+        extras.add("headers", headers);
+
+        conversationChannel.publish("start", null, extras);
+    } else if (event.getType().equals("reasoning")) {
+        // Publish reasoning to separate reasoning channel
+        Channel reasoningChannel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}:" + event.getResponseId());
+
+        reasoningChannel.publish("reasoning", event.getText());
+    } else if (event.getType().equals("message")) {
+        // Publish model output to main channel
+        JsonObject extras = new JsonObject();
+        JsonObject headers = new JsonObject();
+        headers.addProperty("responseId", event.getResponseId());
+        extras.add("headers", headers);
+
+        conversationChannel.publish("message", event.getText(), extras);
+    }
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -259,6 +460,86 @@ async function onClickViewReasoning(responseId) {
   });
 }
 ```
+```python
+conversation_channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by ID
+responses = {}
+
+# Subscribe to all messages on the main channel
+def on_message(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Message missing responseId')
+        return
+
+    # Handle response start control message
+    if message.name == 'start':
+        responses[response_id] = ''
+
+    # Handle model output message
+    if message.name == 'message':
+        responses[response_id] = message.data
+
+await conversation_channel.subscribe(on_message)
+
+# Subscribe to reasoning on demand (e.g., when user clicks to view reasoning)
+async def on_click_view_reasoning(response_id):
+    # Derive reasoning channel name from responseId and
+    # use rewind to retrieve historical reasoning
+    reasoning_channel = realtime.channels.get(
+        f'{{{{RANDOM_CHANNEL_NAME}}}}:{response_id}',
+        params={'rewind': '2m'}
+    )
+
+    # Subscribe to reasoning messages
+    def on_reasoning(message):
+        print(f'[Reasoning]: {message.data}')
+
+    await reasoning_channel.subscribe(on_reasoning)
+```
+```java
+Channel conversationChannel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by ID
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+// Subscribe to all messages on the main channel
+conversationChannel.subscribe(message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Message missing responseId");
+        return;
+    }
+
+    // Handle response start control message
+    if (message.name.equals("start")) {
+        responses.put(responseId, "");
+    }
+
+    // Handle model output message
+    if (message.name.equals("message")) {
+        responses.put(responseId, (String) message.data);
+    }
+});
+
+// Subscribe to reasoning on demand (e.g., when user clicks to view reasoning)
+void onClickViewReasoning(String responseId) {
+    // Derive reasoning channel name from responseId and
+    // use rewind to retrieve historical reasoning
+    ChannelOptions options = new ChannelOptions();
+    options.params = Map.of("rewind", "2m");
+    Channel reasoningChannel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}:" + responseId, options);
+
+    // Subscribe to reasoning messages
+    reasoningChannel.subscribe(message -> {
+        System.out.println("[Reasoning]: " + message.data);
+    });
+}
+```
 </Code>
 
 <Aside data-type="further-reading">
diff --git a/src/pages/docs/ai-transport/messaging/citations.mdx b/src/pages/docs/ai-transport/messaging/citations.mdx
index 194e451385..4bf502ca2a 100644
--- a/src/pages/docs/ai-transport/messaging/citations.mdx
+++ b/src/pages/docs/ai-transport/messaging/citations.mdx
@@ -133,6 +133,52 @@ await channel.annotations.publish(msgSerial, {
   }
 });
 ```
+```java
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+
+// Publish the AI response message
+String response = "The James Webb Space Telescope launched in December 2021 and its first images were released in July 2022.";
+CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>()
+channel.publish("response", response, new Callback<PublishResult>() {
+    @Override
+    public void onSuccess(PublishResult result) {
+        publishFuture.complete(result);
+    }
+
+    @Override
+    public void onError(ErrorInfo reason) {
+        publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
+    }
+});
+String msgSerial = publishFuture.get().serials[0];
+
+// Add citations by annotating the response message
+JsonObject citation1Data = new JsonObject();
+citation1Data.addProperty("url", "https://science.nasa.gov/mission/webb/");
+citation1Data.addProperty("title", "James Webb Space Telescope - NASA Science");
+citation1Data.addProperty("startOffset", 43);
+citation1Data.addProperty("endOffset", 56);
+citation1Data.addProperty("snippet", "Webb launched on Dec. 25th 2021");
+
+Annotation citation1 = new Annotation();
+citation1.name = "science.nasa.gov";
+citation1.type = "citations:multiple.v1";
+citation1.data = citation1Data;
+channel.annotations.publish(msgSerial, citation1);
+
+JsonObject citation2Data = new JsonObject();
+citation2Data.addProperty("url", "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope");
+citation2Data.addProperty("title", "James Webb Space Telescope - Wikipedia");
+citation2Data.addProperty("startOffset", 95);
+citation2Data.addProperty("endOffset", 104);
+citation2Data.addProperty("snippet", "The telescope's first image was released to the public on 11 July 2022.");
+
+Annotation citation2 = new Annotation();
+citation2.name = "en.wikipedia.org";
+citation2.type = "citations:multiple.v1";
+citation2.data = citation2Data;
+channel.annotations.publish(msgSerial, citation2);
+```
 </Code>
 
 <Aside data-type="note">
@@ -171,6 +217,18 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```java
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe(message -> {
+    if (message.action == MessageAction.MESSAGE_SUMMARY) {
+        JsonObject citations = message.annotations.summary.get("citations:multiple.v1");
+        if (citations != null) {
+            System.out.println("Citation summary: " + citations);
+        }
+    }
+});
+```
 </Code>
 
 The `multiple.v1` summary groups counts by the annotation `name`, with totals and per-client breakdowns for each group:
@@ -227,6 +285,22 @@ await channel.annotations.subscribe((annotation) => {
   }
 });
 ```
+```java
+ChannelOptions options = new ChannelOptions();
+options.modes = new ChannelMode[]{ChannelMode.ANNOTATION_SUBSCRIBE};
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}", options);
+
+channel.annotations.subscribe(annotation -> {
+    if (annotation.action == AnnotationAction.ANNOTATION_CREATE &&
+        annotation.type.equals("citations:multiple.v1")) {
+        JsonObject data = annotation.data;
+        String url = data.get("url").getAsString();
+        String title = data.get("title").getAsString();
+        System.out.println("Citation: " + title + " (" + url + ")");
+        // Output: Citation: James Webb Space Telescope - Wikipedia (https://en.wikipedia.org/wiki/James_Webb_Space_Telescope)
+    }
+});
+```
 </Code>
 
 Each annotation event includes the `messageSerial` of the response message it is attached to, the `name` used for grouping in summaries, and the full citation `data` payload. This data can be used to render clickable source links or attach inline citation markers to specific portions of the response text:
diff --git a/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx
index 98207f1025..c81807289a 100644
--- a/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx
+++ b/src/pages/docs/ai-transport/messaging/human-in-the-loop.mdx
@@ -58,6 +58,38 @@ async function requestHumanApproval(toolCall) {
   });
 }
 ```
+```python
+import uuid
+
+channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+async def request_human_approval(tool_call):
+    request_id = str(uuid.uuid4())
+
+    await channel.publish('approval-request', {
+        'requestId': request_id,
+        'action': tool_call['name'],
+        'parameters': tool_call['parameters']
+    })
+
+    return request_id
+```
+```java
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+String requestHumanApproval(ToolCall toolCall) {
+    String requestId = UUID.randomUUID().toString();
+
+    JsonObject data = new JsonObject();
+    data.addProperty("requestId", requestId);
+    data.addProperty("action", toolCall.getName());
+    data.add("parameters", toolCall.getParameters());
+
+    channel.publish("approval-request", data);
+
+    return requestId;
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -77,6 +109,17 @@ const claims = {
   'ably.channel.*': 'user'
 };
 ```
+```python
+claims = {
+    'x-ably-clientId': 'user-123',
+    'ably.channel.*': 'user'
+}
+```
+```java
+Map<String, String> claims = new HashMap<>();
+claims.put("x-ably-clientId", "user-123");
+claims.put("ably.channel.*", "user");
+```
 </Code>
 
 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.
@@ -124,6 +167,51 @@ async function reject(toolCallId) {
   });
 }
 ```
+```python
+channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+def on_approval_request(message):
+    request = message.data
+    # Display request for human review
+    display_approval_ui(request)
+
+await channel.subscribe('approval-request', on_approval_request)
+
+async def approve(request_id):
+    await channel.publish('approval-response', {
+        'requestId': request_id,
+        'decision': 'approved'
+    })
+
+async def reject(request_id):
+    await channel.publish('approval-response', {
+        'requestId': request_id,
+        'decision': 'rejected'
+    })
+```
+```java
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe("approval-request", message -> {
+    JsonObject request = (JsonObject) message.data;
+    // Display request for human review
+    displayApprovalUI(request);
+});
+
+void approve(String requestId) {
+    JsonObject data = new JsonObject();
+    data.addProperty("requestId", requestId);
+    data.addProperty("decision", "approved");
+    channel.publish("approval-response", data);
+}
+
+void reject(String requestId) {
+    JsonObject data = new JsonObject();
+    data.addProperty("requestId", requestId);
+    data.addProperty("decision", "rejected");
+    channel.publish("approval-response", data);
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -178,6 +266,66 @@ await channel.subscribe('approval-response', async (message) => {
   pendingApprovals.delete(toolCallId);
 });
 ```
+```python
+pending_approvals = {}
+
+async def on_approval_response(message):
+    response = message.data
+    pending = pending_approvals.get(response['requestId'])
+
+    if not pending:
+        return
+
+    # The clientId is verified by Ably - this is the trusted approver identity
+    approver_id = message.client_id
+
+    # Look up user-specific permissions from your database
+    user_permissions = await get_user_permissions(approver_id)
+
+    if not user_permissions.can_approve(pending['toolCall']['name']):
+        print(f"User {approver_id} not authorized to approve {pending['toolCall']['name']}")
+        return
+
+    if response['decision'] == 'approved':
+        result = await execute_tool_call(pending['toolCall'])
+        print(f"Action approved by {approver_id}")
+    else:
+        print(f"Action rejected by {approver_id}")
+
+    del pending_approvals[response['requestId']]
+
+await channel.subscribe('approval-response', on_approval_response)
+```
+```java
+Map<String, PendingApproval> pendingApprovals = new ConcurrentHashMap<>();
+
+channel.subscribe("approval-response", message -> {
+    JsonObject response = (JsonObject) message.data;
+    PendingApproval pending = pendingApprovals.get(response.get("requestId").getAsString());
+
+    if (pending == null) return;
+
+    // The clientId is verified by Ably - this is the trusted approver identity
+    String approverId = message.clientId;
+
+    // Look up user-specific permissions from your database
+    UserPermissions userPermissions = getUserPermissions(approverId);
+
+    if (!userPermissions.canApprove(pending.getToolCall().getName())) {
+        System.out.println("User " + approverId + " not authorized to approve " + pending.getToolCall().getName());
+        return;
+    }
+
+    if (response.get("decision").getAsString().equals("approved")) {
+        Object result = executeToolCall(pending.getToolCall());
+        System.out.println("Action approved by " + approverId);
+    } else {
+        System.out.println("Action rejected by " + approverId);
+    }
+
+    pendingApprovals.remove(response.get("requestId").getAsString());
+});
+```
 </Code>
 
 ### Verify by role <a id="verify-role"/>
@@ -234,4 +382,72 @@ await channel.subscribe('approval-response', async (message) => {
   pendingApprovals.delete(toolCallId);
 });
 ```
+```python
+role_hierarchy = ['user', 'manager', 'admin']
+
+def can_approve(approver_role, required_role):
+    approver_level = role_hierarchy.index(approver_role)
+    required_level = role_hierarchy.index(required_role)
+
+    return approver_level >= required_level
+
+# When processing approval response
+async def on_approval_response(message):
+    response = message.data
+    pending = pending_approvals.get(response['requestId'])
+    policy = approval_policies[pending['toolCall']['name']]
+
+    # Get the trusted role from the JWT claim
+    approver_role = message.extras.get('userClaim')
+
+    # Verify the approver's role meets the minimum required role for this action
+    if not can_approve(approver_role, policy['minRole']):
+        print(f"Approver role '{approver_role}' insufficient for required '{policy['minRole']}'")
+        return
+
+    if response['decision'] == 'approved':
+        result = await execute_tool_call(pending['toolCall'])
+        print(f"Action approved by role {approver_role}")
+    else:
+        print(f"Action rejected by role {approver_role}")
+
+    del pending_approvals[response['requestId']]
+
+await channel.subscribe('approval-response', on_approval_response)
+```
+```java
+String[] roleHierarchy = {"user", "manager", "admin"};
+
+boolean canApprove(String approverRole, String requiredRole) {
+    int approverLevel = Arrays.asList(roleHierarchy).indexOf(approverRole);
+    int requiredLevel = Arrays.asList(roleHierarchy).indexOf(requiredRole);
+
+    return approverLevel >= requiredLevel;
+}
+
+// When processing approval response
+channel.subscribe("approval-response", message -> {
+    JsonObject response = (JsonObject) message.data;
+    PendingApproval pending = pendingApprovals.get(response.get("requestId").getAsString());
+    ApprovalPolicy policy = approvalPolicies.get(pending.getToolCall().getName());
+
+    // Get the trusted role from the JWT claim
+    String approverRole = message.extras.get("userClaim").getAsString();
+
+    // Verify the approver's role meets the minimum required role for this action
+    if (!canApprove(approverRole, policy.getMinRole())) {
+        System.out.println("Approver role '" + approverRole + "' insufficient for required '" + policy.getMinRole() + "'");
+        return;
+    }
+
+    if (response.get("decision").getAsString().equals("approved")) {
+        Object result = executeToolCall(pending.getToolCall());
+        System.out.println("Action approved by role " + approverRole);
+    } else {
+        System.out.println("Action rejected by role " + approverRole);
+    }
+
+    pendingApprovals.remove(response.get("requestId").getAsString());
+});
+```
 </Code>
diff --git a/src/pages/docs/ai-transport/messaging/tool-calls.mdx b/src/pages/docs/ai-transport/messaging/tool-calls.mdx
index 15de573ff2..9a00922a28 100644
--- a/src/pages/docs/ai-transport/messaging/tool-calls.mdx
+++ b/src/pages/docs/ai-transport/messaging/tool-calls.mdx
@@ -84,6 +84,103 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like:
+# { 'type': 'tool_call', 'name': 'get_weather', 'args': '{"location":"San Francisco"}', 'toolCallId': 'tool_123', 'responseId': 'resp_abc123' }
+# { 'type': 'tool_result', 'name': 'get_weather', 'result': '{"temp":72,"conditions":"sunny"}', 'toolCallId': 'tool_123', 'responseId': 'resp_abc123' }
+# { 'type': 'message', 'text': 'The weather in San Francisco is 72°F and sunny.', 'responseId': 'resp_abc123' }
+
+async for event in stream:
+    if event['type'] == 'tool_call':
+        # Publish tool call arguments
+        message = Message(
+            name='tool_call',
+            data={
+                'name': event['name'],
+                'args': event['args']
+            },
+            extras={
+                'headers': {
+                    'responseId': event['responseId'],
+                    'toolCallId': event['toolCallId']
+                }
+            }
+        )
+        await channel.publish(message)
+    elif event['type'] == 'tool_result':
+        # Publish tool call results
+        message = Message(
+            name='tool_result',
+            data={
+                'name': event['name'],
+                'result': event['result']
+            },
+            extras={
+                'headers': {
+                    'responseId': event['responseId'],
+                    'toolCallId': event['toolCallId']
+                }
+            }
+        )
+        await channel.publish(message)
+    elif event['type'] == 'message':
+        # Publish model output messages
+        message = Message(
+            name='message',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+        await channel.publish(message)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like:
+// { type: 'tool_call', name: 'get_weather', args: '{"location":"San Francisco"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
+// { type: 'tool_result', name: 'get_weather', result: '{"temp":72,"conditions":"sunny"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
+// { type: 'message', text: 'The weather in San Francisco is 72°F and sunny.', responseId: 'resp_abc123' }
+
+for (Event event : stream) {
+    JsonObject extras = new JsonObject();
+    JsonObject headers = new JsonObject();
+
+    if (event.getType().equals("tool_call")) {
+        // Publish tool call arguments
+        JsonObject data = new JsonObject();
+        data.addProperty("name", event.getName());
+        data.addProperty("args", event.getArgs());
+
+        headers.addProperty("responseId", event.getResponseId());
+        headers.addProperty("toolCallId", event.getToolCallId());
+        extras.add("headers", headers);
+
+        channel.publish(new Message("tool_call", data, new MessageExtras(extras)));
+    } else if (event.getType().equals("tool_result")) {
+        // Publish tool call results
+        JsonObject data = new JsonObject();
+        data.addProperty("name", event.getName());
+        data.addProperty("result", event.getResult());
+
+        headers.addProperty("responseId", event.getResponseId());
+        headers.addProperty("toolCallId", event.getToolCallId());
+        extras.add("headers", headers);
+
+        channel.publish(new Message("tool_result", data, new MessageExtras(extras)));
+    } else if (event.getType().equals("message")) {
+        // Publish model output messages
+        headers.addProperty("responseId", event.getResponseId());
+        extras.add("headers", headers);
+
+        channel.publish(new Message("message", event.getText(), new MessageExtras(extras)));
+    }
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -155,6 +252,96 @@ await channel.subscribe((message) => {
   console.log(`Response ${responseId}:`, response);
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by ID, each containing tool calls and final response
+responses = {}
+
+# Subscribe to all events on the channel
+def on_message(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Message missing responseId')
+        return
+
+    # Initialize response object if needed
+    if response_id not in responses:
+        responses[response_id] = {
+            'toolCalls': {},
+            'message': ''
+        }
+
+    response = responses[response_id]
+
+    # Handle each message type
+    if message.name == 'message':
+        response['message'] = message.data
+    elif message.name == 'tool_call':
+        tool_call_id = message.extras.get('headers', {}).get('toolCallId')
+        response['toolCalls'][tool_call_id] = {
+            'name': message.data['name'],
+            'args': message.data['args']
+        }
+    elif message.name == 'tool_result':
+        result_tool_call_id = message.extras.get('headers', {}).get('toolCallId')
+        tool_call = response['toolCalls'].get(result_tool_call_id)
+        if tool_call:
+            tool_call['result'] = message.data['result']
+
+    # Display the tool calls and response for this turn
+    print(f'Response {response_id}:', response)
+
+await channel.subscribe(on_message)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by ID, each containing tool calls and final response
+Map<String, Response> responses = new ConcurrentHashMap<>();
+
+// Subscribe to all events on the channel
+channel.subscribe(message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Message missing responseId");
+        return;
+    }
+
+    // Initialize response object if needed
+    responses.putIfAbsent(responseId, new Response());
+    Response response = responses.get(responseId);
+
+    // Handle each message type
+    switch (message.name) {
+        case "message":
+            response.setMessage((String) message.data);
+            break;
+        case "tool_call":
+            String toolCallId = headers.get("toolCallId").getAsString();
+            JsonObject data = (JsonObject) message.data;
+            ToolCall toolCall = new ToolCall();
+            toolCall.setName(data.get("name").getAsString());
+            toolCall.setArgs(data.get("args").getAsString());
+            response.getToolCalls().put(toolCallId, toolCall);
+            break;
+        case "tool_result":
+            String resultToolCallId = headers.get("toolCallId").getAsString();
+            ToolCall existingToolCall = response.getToolCalls().get(resultToolCallId);
+            if (existingToolCall != null) {
+                JsonObject resultData = (JsonObject) message.data;
+                existingToolCall.setResult(resultData.get("result").getAsString());
+            }
+            break;
+    }
+
+    // Display the tool calls and response for this turn
+    System.out.println("Response " + responseId + ": " + response);
+});
+```
 </Code>
 
 <Aside data-type="further-reading">
@@ -185,6 +372,45 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+def on_message(message):
+    # Render component when tool is invoked
+    if message.name == 'tool_call' and message.data['name'] == 'get_weather':
+        args = json.loads(message.data['args'])
+        render_weather_card({'location': args['location'], 'loading': True})
+
+    # Update component with results
+    if message.name == 'tool_result' and message.data['name'] == 'get_weather':
+        result = json.loads(message.data['result'])
+        render_weather_card(result)
+
+await channel.subscribe(on_message)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe(message -> {
+    // Render component when tool is invoked
+    if (message.name.equals("tool_call")) {
+        JsonObject data = (JsonObject) message.data;
+        if (data.get("name").getAsString().equals("get_weather")) {
+            JsonObject args = JsonParser.parseString(data.get("args").getAsString()).getAsJsonObject();
+            renderWeatherCard(args.get("location").getAsString(), true);
+        }
+    }
+
+    // Update component with results
+    if (message.name.equals("tool_result")) {
+        JsonObject data = (JsonObject) message.data;
+        if (data.get("name").getAsString().equals("get_weather")) {
+            JsonObject result = JsonParser.parseString(data.get("result").getAsString()).getAsJsonObject();
+            renderWeatherCard(result);
+        }
+    }
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -237,6 +463,68 @@ await channel.subscribe('tool_call', async (message) => {
   }
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+async def on_tool_call(message):
+    name = message.data['name']
+    args = message.data.get('args')
+    headers = message.extras.get('headers', {})
+    response_id = headers.get('responseId')
+    tool_call_id = headers.get('toolCallId')
+
+    if name == 'get_location':
+        result = await get_geolocation_position()
+        message = Message(
+            name='tool_result',
+            data={
+                'name': name,
+                'result': {
+                    'lat': result['coords']['latitude'],
+                    'lng': result['coords']['longitude']
+                }
+            },
+            extras={
+                'headers': {
+                    'responseId': response_id,
+                    'toolCallId': tool_call_id
+                }
+            }
+        )
+        await channel.publish(message)
+
+await channel.subscribe('tool_call', on_tool_call)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe("tool_call", message -> {
+    JsonObject data = (JsonObject) message.data;
+    String name = data.get("name").getAsString();
+    JsonObject headers = message.extras.asJsonObject().get("headers");
+    String responseId = headers.get("responseId").getAsString();
+    String toolCallId = headers.get("toolCallId").getAsString();
+
+    if (name.equals("get_location")) {
+        GeolocationPosition result = getGeolocationPosition();
+
+        JsonObject resultData = new JsonObject();
+        resultData.addProperty("name", name);
+        JsonObject resultValue = new JsonObject();
+        resultValue.addProperty("lat", result.getCoords().getLatitude());
+        resultValue.addProperty("lng", result.getCoords().getLongitude());
+        resultData.add("result", resultValue);
+
+        JsonObject resultExtras = new JsonObject();
+        JsonObject resultHeaders = new JsonObject();
+        resultHeaders.addProperty("responseId", responseId);
+        resultHeaders.addProperty("toolCallId", toolCallId);
+        resultExtras.add("headers", resultHeaders);
+
+        channel.publish(new Message("tool_result", resultData, new MessageExtras(resultExtras)));
+    }
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -265,6 +553,43 @@ await channel.subscribe('tool_result', (message) => {
   pendingToolCalls.delete(toolCallId);
 });
 ```
+```python
+pending_tool_calls = {}
+
+def on_tool_result(message):
+    tool_call_id = message.data.get('toolCallId')
+    result = message.data.get('result')
+    pending = pending_tool_calls.get(tool_call_id)
+
+    if not pending:
+        return
+
+    # Pass result back to the AI model to continue the conversation
+    process_result(pending['responseId'], tool_call_id, result)
+
+    del pending_tool_calls[tool_call_id]
+
+await channel.subscribe('tool_result', on_tool_result)
+```
+```java
+Map<String, PendingToolCall> pendingToolCalls = new ConcurrentHashMap<>();
+
+channel.subscribe("tool_result", message -> {
+    JsonObject data = (JsonObject) message.data;
+    String toolCallId = data.get("toolCallId").getAsString();
+    JsonObject result = data.get("result").getAsJsonObject();
+    PendingToolCall pending = pendingToolCalls.get(toolCallId);
+
+    if (pending == null) {
+        return;
+    }
+
+    // Pass result back to the AI model to continue the conversation
+    processResult(pending.getResponseId(), toolCallId, result);
+
+    pendingToolCalls.remove(toolCallId);
+});
+```
 </Code>
 
 ## Human-in-the-loop workflows <a id="human-in-the-loop"/>
diff --git a/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx b/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx
index f762d4ae87..f56caf3464 100644
--- a/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx
+++ b/src/pages/docs/ai-transport/sessions-identity/identifying-users-and-agents.mdx
@@ -63,6 +63,114 @@ app.get("/api/auth/token", authenticateUser, (req, res) => {
 
 app.listen(3001);
 ```
+```python
+# Server code
+from flask import Flask, request, session
+import jwt
+import time
+
+app = Flask(__name__)
+
+# Mock authentication middleware.
+# This should be replaced with your actual authentication logic.
+def authenticate_user():
+    # Assign a mock user ID for demonstration
+    session['user_id'] = 'user123'
+
+# Return the claims payload to embed in the signed JWT.
+def get_jwt_claims(user_id):
+    # Returns an empty payload, so the token
+    # inherits the capabilities of the signing key.
+    return {}
+
+# Define an auth endpoint used by the client to obtain a signed JWT
+# which it can use to authenticate with the Ably service.
+@app.route('/api/auth/token')
+def auth_token():
+    authenticate_user()
+
+    key_name, key_secret = "{{API_KEY}}".split(":")
+
+    # Sign a JWT using the secret part of the Ably API key.
+    token = jwt.encode(
+        get_jwt_claims(session['user_id']),
+        key_secret,
+        algorithm="HS256",
+        headers={"kid": key_name}
+    )
+
+    # Set expiration time (1 hour from now)
+    payload = get_jwt_claims(session['user_id'])
+    payload['exp'] = int(time.time()) + 3600
+
+    token = jwt.encode(
+        payload,
+        key_secret,
+        algorithm="HS256",
+        headers={"kid": key_name}
+    )
+
+    return token, 200, {'Content-Type': 'application/jwt'}
+
+if __name__ == '__main__':
+    app.run(port=3001)
+```
+```java
+// Server code
+import org.jose4j.jws.*;
+import org.jose4j.jwt.JwtClaims;
+import org.jose4j.keys.HmacKey;
+import spark.Spark;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class AuthServer {
+    public static void main(String[] args) {
+        Spark.port(3001);
+
+        // Define an auth endpoint used by the client to obtain a signed JWT
+        // which it can use to authenticate with the Ably service.
+        Spark.get("/api/auth/token", (req, res) -> {
+            // Mock authentication - assign a mock user ID for demonstration
+            String userId = authenticateUser(req);
+
+            String[] keyParts = "{{API_KEY}}".split(":");
+            String keyName = keyParts[0];
+            String keySecret = keyParts[1];
+
+            // Get the claims payload to embed in the signed JWT
+            JwtClaims claims = getJWTClaims(userId);
+            jwtClaims.setExpirationTimeMinutesInTheFuture(60); // 1 hour
+
+            JsonWebSignature jws = new JsonWebSignature();
+            jws.setPayload(jwtClaims.toJson());
+            jws.setKey(new HmacKey(keySecret.getBytes()));
+            jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);
+            jws.setHeader("kid", keyName);
+
+            String token = jws.getCompactSerialization();
+
+            res.type("application/jwt");
+            return token;
+        });
+    }
+
+    // Mock authentication middleware.
+    // This should be replaced with your actual authentication logic.
+    private static String authenticateUser(spark.Request req) {
+        // Assign a mock user ID for demonstration
+        return "user123";
+    }
+
+    // Return the claims payload to embed in the signed JWT.
+    private static JwtClaims getJWTClaims(String userId) {
+        // Returns an empty payload, so the token
+        // inherits the capabilities of the signing key.
+        return new JwtClaims();
+    }
+}
+```
 </Code>
 
 <Aside data-type="important">
@@ -98,6 +206,40 @@ ably.connection.on("connected", () => {
   console.log("Connected to Ably");
 });
 ```
+```python
+# Client code
+from ably import AblyRealtime
+import requests
+
+def auth_callback(token_params):
+    response = requests.get("/api/auth/token")
+    return response.text
+
+ably = AblyRealtime(auth_callback=auth_callback)
+
+def on_connected(state_change):
+    print("Connected to Ably")
+
+ably.connection.on('connected', on_connected)
+```
+```java
+// Client code
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.types.ClientOptions;
+
+ClientOptions options = new ClientOptions();
+options.authCallback = (tokenParams) -> {
+    // Make HTTP request to your auth endpoint
+    String response = makeHttpRequest("/api/auth/token");
+    return response;
+};
+
+AblyRealtime ably = new AblyRealtime(options);
+
+ably.connection.on(ConnectionState.connected, state -> {
+    System.out.println("Connected to Ably");
+});
+```
 </Code>
 
 ## Authenticating agents <a id="authenticating-agents"/>
@@ -117,6 +259,27 @@ ably.connection.on("connected", () => {
   console.log("Connected to Ably");
 });
 ```
+```python
+# Agent code
+from ably import AblyRealtime
+
+ably = AblyRealtime(key="{{API_KEY}}")
+
+def on_connected(state_change):
+    print("Connected to Ably")
+
+ably.connection.on('connected', on_connected)
+```
+```java
+// Agent code
+import io.ably.lib.realtime.AblyRealtime;
+
+AblyRealtime ably = new AblyRealtime("{{API_KEY}}");
+
+ably.connection.on(ConnectionState.connected, state -> {
+    System.out.println("Connected to Ably");
+});
+```
 </Code>
 
 <Aside data-type="important">
@@ -158,6 +321,50 @@ function getJWTClaims(userId) {
   };
 }
 ```
+```python
+# Server code
+import json
+
+# Return the claims payload to embed in the signed JWT.
+# Includes the `x-ably-capabilities` claim, which controls
+# which operations the user can perform on which channels.
+def get_jwt_claims(user_id):
+    org_id = "acme"  # Mock organization ID for demonstration
+    capabilities = {
+        # The user can publish and subscribe to channels within the organization,
+        # that is, any channel matching `org:acme:*`.
+        f"org:{org_id}:*": ["publish", "subscribe"],
+        # The user can only subscribe to the `announcements` channel.
+        "announcements": ["subscribe"],
+    }
+    return {
+        "x-ably-capability": json.dumps(capabilities),
+    }
+```
+```java
+// Server code
+import com.google.gson.Gson;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+// Return the claims payload to embed in the signed JWT.
+// Includes the `x-ably-capabilities` claim, which controls
+// which operations the user can perform on which channels.
+private static Map<String, Object> getJWTClaims(String userId) {
+    String orgId = "acme"; // Mock organization ID for demonstration
+    Map<String, List<String>> capabilities = new HashMap<>();
+    // The user can publish and subscribe to channels within the organization,
+    // that is, any channel matching `org:acme:*`.
+    capabilities.put("org:" + orgId + ":*", List.of("publish", "subscribe"));
+    // The user can only subscribe to the `announcements` channel.
+    capabilities.put("announcements", List.of("subscribe"));
+
+    Map<String, Object> claims = new HashMap<>();
+    claims.put("x-ably-capability", new Gson().toJson(capabilities));
+    return claims;
+}
+```
 </Code>
 
 When a client authenticates with this token, Ably enforces these capabilities server-side. Any attempt to perform unauthorized operations will be rejected. For example, a client with the capabilities above can publish to channels prefixed with `org:acme:`, but an attempt to publish to a channel prefixed with `org:foobar:` will fail with error code [`40160`](/docs/platform/errors/codes#40160):
@@ -175,6 +382,30 @@ const announcementsChannel = ably.channels.get("announcements");
 await announcementsChannel.publish("prompt", "What is the weather like today?"); // fails
 await announcementsChannel.subscribe((msg) => console.log(msg)); // succeeds
 ```
+```python
+# Client code
+acme_channel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}")
+await acme_channel.publish("prompt", "What is the weather like today?")  # succeeds
+
+foobar_channel = ably.channels.get("org:foobar:{{RANDOM_CHANNEL_NAME}}")
+await foobar_channel.publish("prompt", "What is the weather like today?")  # fails
+
+announcements_channel = ably.channels.get("announcements")
+await announcements_channel.publish("prompt", "What is the weather like today?")  # fails
+await announcements_channel.subscribe(lambda msg: print(msg))  # succeeds
+```
+```java
+// Client code
+Channel acmeChannel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}");
+acmeChannel.publish("prompt", "What is the weather like today?"); // succeeds
+
+Channel foobarChannel = ably.channels.get("org:foobar:{{RANDOM_CHANNEL_NAME}}");
+foobarChannel.publish("prompt", "What is the weather like today?"); // fails
+
+Channel announcementsChannel = ably.channels.get("announcements");
+announcementsChannel.publish("prompt", "What is the weather like today?"); // fails
+announcementsChannel.subscribe(msg -> System.out.println(msg)); // succeeds
+```
 </Code>
 
 <Aside data-type="note">
@@ -218,6 +449,26 @@ const otherChannel = ably.channels.get("org:acme:other:{{RANDOM_CHANNEL_NAME}}")
 await otherChannel.subscribe((msg) => console.log(msg)); // fails
 await otherChannel.publish("update", "It's raining in London"); // fails
 ```
+```python
+# Agent code
+weather_channel = ably.channels.get("org:acme:weather:{{RANDOM_CHANNEL_NAME}}")
+await weather_channel.subscribe(lambda msg: print(msg))  # succeeds
+await weather_channel.publish("update", "It's raining in London")  # succeeds
+
+other_channel = ably.channels.get("org:acme:other:{{RANDOM_CHANNEL_NAME}}")
+await other_channel.subscribe(lambda msg: print(msg))  # fails
+await other_channel.publish("update", "It's raining in London")  # fails
+```
+```java
+// Agent code
+Channel weatherChannel = ably.channels.get("org:acme:weather:{{RANDOM_CHANNEL_NAME}}");
+weatherChannel.subscribe(msg -> System.out.println(msg)); // succeeds
+weatherChannel.publish("update", "It's raining in London"); // succeeds
+
+Channel otherChannel = ably.channels.get("org:acme:other:{{RANDOM_CHANNEL_NAME}}");
+otherChannel.subscribe(msg -> System.out.println(msg)); // fails
+otherChannel.publish("update", "It's raining in London"); // fails
+```
 </Code>
 
 <Aside data-type="important">
@@ -241,6 +492,8 @@ Update your `getJWTClaims` function to specify a `clientId` for the user:
 
 <Code>
 ```javascript
+// Server code
+
 // Return the claims payload to embed in the signed JWT.
 function getJWTClaims(userId) {
   // Returns a payload with the `x-ably-clientId` claim, which ensures
@@ -249,6 +502,31 @@ function getJWTClaims(userId) {
   return { "x-ably-clientId": userId };
 }
 ```
+```python
+# Server code
+
+# Return the claims payload to embed in the signed JWT.
+def get_jwt_claims(user_id):
+    # Returns a payload with the `x-ably-clientId` claim, which ensures
+    # that the user's ID appears as the `clientId` on all messages
+    # published by the client using this token.
+    return {"x-ably-clientId": user_id}
+```
+```java
+// Server code
+import java.util.HashMap;
+import java.util.Map;
+
+// Return the claims payload to embed in the signed JWT.
+private static Map<String, Object> getJWTClaims(String userId) {
+    // Returns a payload with the `x-ably-clientId` claim, which ensures
+    // that the user's ID appears as the `clientId` on all messages
+    // published by the client using this token.
+    Map<String, Object> claims = new HashMap<>();
+    claims.put("x-ably-clientId", userId);
+    return claims;
+}
+```
 </Code>
 
 When a client authenticates using this token, Ably's servers automatically attach the `clientId` specified in the token to every message the user publishes:
@@ -261,6 +539,21 @@ const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
 // Publish a message - the clientId is automatically attached
 await channel.publish("prompt", "What is the weather like today?");
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Publish a message - the clientId is automatically attached
+message = Message(name="prompt", data="What is the weather like today?")
+await channel.publish(message)
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Publish a message - the clientId is automatically attached
+channel.publish("prompt", "What is the weather like today?");
+```
 </Code>
 
 Agents can then access this verified identity to identify the sender:
@@ -280,6 +573,35 @@ await channel.subscribe("prompt", (message) => {
   console.log(`Prompt:`, prompt);
 });
 ```
+```python
+# Agent code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Subscribe to messages from clients
+def on_prompt(message):
+    # Access the verified clientId from the message
+    user_id = message.client_id
+    prompt = message.data
+
+    print(f"Received message from user: {user_id}")
+    print(f"Prompt: {prompt}")
+
+await channel.subscribe("prompt", on_prompt)
+```
+```java
+// Agent code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to messages from clients
+channel.subscribe("prompt", message -> {
+    // Access the verified clientId from the message
+    String userId = message.clientId;
+    String prompt = (String) message.data;
+
+    System.out.println("Received message from user: " + userId);
+    System.out.println("Prompt: " + prompt);
+});
+```
 </Code>
 
 The `clientId` in the message can be trusted, so agents can use this identity to make decisions about what actions the user can take. For example, agents can check user permissions before executing tool calls, route messages to appropriate AI models based on subscription tiers, or maintain per-user conversation history and context.
@@ -299,6 +621,28 @@ const ably = new Ably.Realtime({
   clientId: "weather-agent"
 });
 ```
+```python
+# Agent code
+from ably import AblyRealtime
+
+ably = AblyRealtime(
+    key="{{API_KEY}}",
+    # Specify an identity for this agent
+    client_id="weather-agent"
+)
+```
+```java
+// Agent code
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.types.ClientOptions;
+
+ClientOptions options = new ClientOptions();
+options.key = "{{API_KEY}}";
+// Specify an identity for this agent
+options.clientId = "weather-agent";
+
+AblyRealtime ably = new AblyRealtime(options);
+```
 </Code>
 
 When subscribers receive messages, they can use the `clientId` to determine which agent published the message:
@@ -314,6 +658,26 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+def on_message(message):
+    if message.client_id == "weather-agent":
+        print("Weather agent response:", message.data)
+
+await channel.subscribe(on_message)
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe(message -> {
+    if ("weather-agent".equals(message.clientId)) {
+        System.out.println("Weather agent response: " + message.data);
+    }
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -334,6 +698,8 @@ Update your `getJWTClaims` function to specify some user claims:
 
 <Code>
 ```javascript
+// Server code
+
 // Return the claims payload to embed in the signed JWT.
 function getJWTClaims(userId) {
   // Returns a payload with `ably.channel.*` claims, which ensures that
@@ -347,6 +713,39 @@ function getJWTClaims(userId) {
   };
 }
 ```
+```python
+# Server code
+
+# Return the claims payload to embed in the signed JWT.
+def get_jwt_claims(user_id):
+    # Returns a payload with `ably.channel.*` claims, which ensures that
+    # the most specific claim appears as the `message.extras.userClaim`
+    # on all messages published by the client using this token.
+    return {
+        # The user is an editor on all acme channels.
+        "ably.channel.org:acme:*": "editor",
+        # The user is a guest on all other channels.
+        "ably.channel.*": "guest",
+    }
+```
+```java
+// Server code
+import java.util.HashMap;
+import java.util.Map;
+
+// Return the claims payload to embed in the signed JWT.
+private static Map<String, Object> getJWTClaims(String userId) {
+    // Returns a payload with `ably.channel.*` claims, which ensures that
+    // the most specific claim appears as the `message.extras.userClaim`
+    // on all messages published by the client using this token.
+    Map<String, Object> claims = new HashMap<>();
+    // The user is an editor on all acme channels.
+    claims.put("ably.channel.org:acme:*", "editor");
+    // The user is a guest on all other channels.
+    claims.put("ably.channel.*", "guest");
+    return claims;
+}
+```
 </Code>
 
 When a client authenticates with a JWT containing `ably.channel.*` claims, Ably automatically includes the most specific matching claim value in the `message.extras.userClaim` field on messages published by the client:
@@ -364,6 +763,31 @@ await channel.subscribe("prompt", async (message) => {
   console.log(`Message from user with role: ${role}`);
 });
 ```
+```python
+# Agent code
+channel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}")
+
+# Subscribe to user prompts
+async def on_prompt(message):
+    # Access the user's role from the user claim in message extras
+    role = message.extras.get('userClaim')
+
+    print(f"Message from user with role: {role}")
+
+await channel.subscribe("prompt", on_prompt)
+```
+```java
+// Agent code
+Channel channel = ably.channels.get("org:acme:{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to user prompts
+channel.subscribe("prompt", message -> {
+    // Access the user's role from the user claim in message extras
+    String role = message.extras.get("userClaim").getAsString();
+
+    System.out.println("Message from user with role: " + role);
+});
+```
 </Code>
 
 The `message.extras.userClaim` in the message can be trusted, so agents can rely on this information to make decisions about what actions the user can take. For example, an agent could allow users with an "editor" role to execute tool calls that modify documents, while restricting users with a "guest" role to read-only operations.
@@ -400,6 +824,47 @@ await channel.publish({
   }
 });
 ```
+```python
+# Agent code
+from ably import AblyRealtime
+
+ably = AblyRealtime(
+    key="{{API_KEY}}",
+    client_id="weather-agent"
+)
+
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+message = Message(
+    name="update",
+    data="It's raining in London",
+    extras={
+        "headers": {
+            "model": "gpt-4"
+        }
+    }
+)
+await channel.publish(message)
+```
+```java
+// Agent code
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.types.ClientOptions;
+
+ClientOptions options = new ClientOptions();
+options.key = "{{API_KEY}}";
+options.clientId = "weather-agent";
+
+AblyRealtime ably = new AblyRealtime(options);
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+JsonObject extras = new JsonObject();
+JsonObject headers = new JsonObject();
+headers.addProperty("model", "gpt-4");
+extras.add("headers", headers);
+
+channel.publish(new Message("update", "It's raining in London", new MessageExtras(extras)));
+```
 </Code>
 
 Clients and other agents can access this metadata when messages are received:
@@ -416,4 +881,27 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+def on_message(message):
+    if message.client_id == "weather-agent":
+        model = message.extras.get('headers', {}).get('model')
+        print(f"Response from weather agent using {model}: {message.data}")
+
+await channel.subscribe(on_message)
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.subscribe(message -> {
+    if ("weather-agent".equals(message.clientId)) {
+        JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+        String model = headers != null ? headers.get("model").getAsString() : null;
+        System.out.println("Response from weather agent using " + model + ": " + message.data);
+    }
+});
+```
 </Code>
diff --git a/src/pages/docs/ai-transport/sessions-identity/online-status.mdx b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx
index 3e9722d647..72cd20186a 100644
--- a/src/pages/docs/ai-transport/sessions-identity/online-status.mdx
+++ b/src/pages/docs/ai-transport/sessions-identity/online-status.mdx
@@ -42,6 +42,26 @@ await channel.presence.enter({
   platform: "ios"
 });
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Enter presence with metadata about the user's device
+await channel.presence.enter({
+    "device": "mobile",
+    "platform": "ios"
+})
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Enter presence with metadata about the user's device
+JsonObject data = new JsonObject();
+data.addProperty("device", "mobile");
+data.addProperty("platform", "ios");
+channel.presence.enter(data);
+```
 </Code>
 
 Similarly, an agent can enter presence to signal that it's online:
@@ -56,6 +76,24 @@ await channel.presence.enter({
   model: "gpt-4"
 });
 ```
+```python
+# Agent code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Enter presence with metadata about the agent
+await channel.presence.enter({
+    "model": "gpt-4"
+})
+```
+```java
+// Agent code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Enter presence with metadata about the agent
+JsonObject data = new JsonObject();
+data.addProperty("model", "gpt-4");
+channel.presence.enter(data);
+```
 </Code>
 
 ### Going online from multiple devices <a id="multiple-devices"/>
@@ -72,6 +110,18 @@ For example, when the user connects from their desktop browser:
 const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
 await channel.presence.enter({ device: "desktop" });
 ```
+```python
+# Client code (device 1: desktop browser)
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+await channel.presence.enter({"device": "desktop"})
+```
+```java
+// Client code (device 1: desktop browser)
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+JsonObject data = new JsonObject();
+data.addProperty("device", "desktop");
+channel.presence.enter(data);
+```
 </Code>
 
 And then connects from their mobile app while still connected on desktop:
@@ -82,6 +132,18 @@ And then connects from their mobile app while still connected on desktop:
 const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
 await channel.presence.enter({ device: "mobile" });
 ```
+```python
+# Client code (device 2: mobile app)
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+await channel.presence.enter({"device": "mobile"})
+```
+```java
+// Client code (device 2: mobile app)
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+JsonObject data = new JsonObject();
+data.addProperty("device", "mobile");
+channel.presence.enter(data);
+```
 </Code>
 
 Both devices are now members of the presence set with the same `clientId` but different `connectionId` values. When you query the presence set, you'll see two separate entries:
@@ -97,6 +159,25 @@ for (const { clientId, connectionId, data } of members) {
 // user-123 hd67s4!abcdef-0 { device: "desktop" }
 // user-123 hd67s4!ghijkl-1 { device: "mobile" }
 ```
+```python
+# Query presence to see both devices
+members = await channel.presence.get()
+for member in members:
+    print(member.client_id, member.connection_id, member.data)
+# Example output:
+# user-123 hd67s4!abcdef-0 { 'device': 'desktop' }
+# user-123 hd67s4!ghijkl-1 { 'device': 'mobile' }
+```
+```java
+// Query presence to see both devices
+PresenceMessage[] members = channel.presence.get();
+for (PresenceMessage member : members) {
+    System.out.println(member.clientId + " " + member.connectionId + " " + member.data);
+}
+// Example output:
+// user-123 hd67s4!abcdef-0 { device: "desktop" }
+// user-123 hd67s4!ghijkl-1 { device: "mobile" }
+```
 </Code>
 
 When either device leaves or disconnects, the other device remains in the presence set.
@@ -123,6 +204,20 @@ const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
 // Leave presence when the user marks themselves offline
 await channel.presence.leave();
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Leave presence when the user marks themselves offline
+await channel.presence.leave()
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Leave presence when the user marks themselves offline
+channel.presence.leave();
+```
 </Code>
 
 Similarly, an agent can leave presence when it completes its work or shuts down:
@@ -135,6 +230,20 @@ const channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
 // Leave presence when the agent shuts down
 await channel.presence.leave();
 ```
+```python
+# Agent code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Leave presence when the agent shuts down
+await channel.presence.leave()
+```
+```java
+// Agent code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Leave presence when the agent shuts down
+channel.presence.leave();
+```
 </Code>
 
 Optionally include data when leaving presence to communicate the reason for going offline. This data is delivered to presence subscribers listening to `leave` events and is also available in [presence history](/docs/presence-occupancy/presence#history):
@@ -147,6 +256,21 @@ await channel.presence.leave({
   timestamp: Date.now()
 });
 ```
+```python
+# Leave with a reason
+import time
+await channel.presence.leave({
+    "reason": "session-completed",
+    "timestamp": int(time.time() * 1000)
+})
+```
+```java
+// Leave with a reason
+JsonObject data = new JsonObject();
+data.addProperty("reason", "session-completed");
+data.addProperty("timestamp", System.currentTimeMillis());
+channel.presence.leave(data);
+```
 </Code>
 
 Subscribers receive the `leave` data in the presence message:
@@ -161,6 +285,25 @@ await channel.presence.subscribe("leave", (presenceMessage) => {
   }
 });
 ```
+```python
+# Subscribe to leave events to see why members left
+def on_leave(presence_message):
+    print(f"{presence_message.client_id} left")
+    if presence_message.data:
+        print(f"Reason: {presence_message.data['reason']}")
+
+await channel.presence.subscribe("leave", on_leave)
+```
+```java
+// Subscribe to leave events to see why members left
+channel.presence.subscribe("leave", presenceMessage -> {
+    System.out.println(presenceMessage.clientId + " left");
+    if (presenceMessage.data != null) {
+        JsonObject data = (JsonObject) presenceMessage.data;
+        System.out.println("Reason: " + data.get("reason").getAsString());
+    }
+});
+```
 </Code>
 
 ### Going offline after disconnection <a id="disconnection"/>
@@ -189,6 +332,27 @@ const ably = new Ably.Realtime({
   }
 });
 ```
+```python
+# Agent code
+ably = AblyRealtime(
+    key="{{API_KEY}}",
+    client_id="weather-agent",
+    # Allow 30 seconds for agent resume and reconnection
+    transport_params={
+        "remainPresentFor": 30000
+    }
+)
+```
+```java
+// Agent code
+ClientOptions options = new ClientOptions();
+options.key = "{{API_KEY}}";
+options.clientId = "weather-agent";
+// Allow 30 seconds for agent resume and reconnection
+options.transportParams = Map.of("remainPresentFor", "30000");
+
+AblyRealtime ably = new AblyRealtime(options);
+```
 </Code>
 
 ## Viewing who is online <a id="viewing-presence"/>
@@ -213,6 +377,23 @@ members.forEach((member) => {
   console.log(`${member.clientId} (connection: ${member.connectionId})`);
 });
 ```
+```python
+# Get all currently present members
+members = await channel.presence.get()
+
+# Display each member - the same user will appear once per distinct connection
+for member in members:
+    print(f"{member.client_id} (connection: {member.connection_id})")
+```
+```java
+// Get all currently present members
+PresenceMessage[] members = channel.presence.get();
+
+// Display each member - the same user will appear once per distinct connection
+for (PresenceMessage member : members) {
+    System.out.println(member.clientId + " (connection: " + member.connectionId + ")");
+}
+```
 </Code>
 
 ### Subscribing to presence changes <a id="presence-subscribe"/>
@@ -235,6 +416,40 @@ await channel.presence.subscribe(async (presenceMessage) => {
   });
 });
 ```
+```python
+# Client code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+# Subscribe to changes to the presence set
+async def on_presence_change(presence_message):
+    # Get the current synced presence set after any change
+    members = await channel.presence.get()
+
+    # Display each member - the same user will appear once per distinct connection
+    for member in members:
+        print(f"{member.client_id} (connection: {member.connection_id})")
+
+await channel.presence.subscribe(on_presence_change)
+```
+```java
+// Client code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to changes to the presence set
+channel.presence.subscribe(presenceMessage -> {
+    // Get the current synced presence set after any change
+    try {
+        PresenceMessage[] members = channel.presence.get();
+
+        // Display each member - the same user will appear once per distinct connection
+        for (PresenceMessage member : members) {
+            System.out.println(member.clientId + " (connection: " + member.connectionId + ")");
+        }
+    } catch (AblyException e) {
+        e.printStackTrace();
+    }
+});
+```
 </Code>
 
 You can also subscribe to specific presence events:
@@ -251,6 +466,30 @@ await channel.presence.subscribe("leave", (presenceMessage) => {
   console.log(`${presenceMessage.clientId} left on connection ${presenceMessage.connectionId}`);
 });
 ```
+```python
+# Subscribe only to enter events
+def on_enter(presence_message):
+    print(f"{presence_message.client_id} joined on connection {presence_message.connection_id}")
+
+await channel.presence.subscribe("enter", on_enter)
+
+# Subscribe only to leave events
+def on_leave(presence_message):
+    print(f"{presence_message.client_id} left on connection {presence_message.connection_id}")
+
+await channel.presence.subscribe("leave", on_leave)
+```
+```java
+// Subscribe only to enter events
+channel.presence.subscribe("enter", presenceMessage -> {
+    System.out.println(presenceMessage.clientId + " joined on connection " + presenceMessage.connectionId);
+});
+
+// Subscribe only to leave events
+channel.presence.subscribe("leave", presenceMessage -> {
+    System.out.println(presenceMessage.clientId + " left on connection " + presenceMessage.connectionId);
+});
+```
 </Code>
 
 ### Detecting when a user is offline on all devices <a id="detecting-offline"/>
@@ -277,4 +516,52 @@ await channel.presence.subscribe(async (presenceMessage) => {
   }
 });
 ```
+```python
+# Agent code
+channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}")
+
+async def on_presence_change(presence_message):
+    # Get the current synced presence set
+    members = await channel.presence.get()
+
+    # Check if all clients are offline
+    if len(members) == 0:
+        print("All clients are offline")
+
+    # Check if a specific client is offline
+    if target_user_id not in [m.client_id for m in members]:
+        print(f"{target_user_id} is now offline on all devices")
+
+await channel.presence.subscribe(on_presence_change)
+```
+```java
+// Agent code
+Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+channel.presence.subscribe(presenceMessage -> {
+    try {
+        // Get the current synced presence set
+        PresenceMessage[] members = channel.presence.get();
+
+        // Check if all clients are offline
+        if (members.length == 0) {
+            System.out.println("All clients are offline");
+        }
+
+        // Check if a specific client is offline
+        boolean found = false;
+        for (PresenceMessage member : members) {
+            if (member.clientId.equals(targetUserId)) {
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            System.out.println(targetUserId + " is now offline on all devices");
+        }
+    } catch (AblyException e) {
+        e.printStackTrace();
+    }
+});
+```
 </Code>
diff --git a/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx
index 56c99c93d4..1e218e0cb8 100644
--- a/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx
+++ b/src/pages/docs/ai-transport/sessions-identity/resuming-sessions.mdx
@@ -127,6 +127,107 @@ while (page) {
   page = page.hasNext() ? await page.next() : null;
 }
 ```
+```python
+# Agent code
+import os
+from ably import AblyRealtime
+
+ably = AblyRealtime(
+    key=os.environ.get("ABLY_API_KEY"),
+    client_id="agent:assistant"
+)
+
+# Load persisted session state
+channel_name = await load_channel_name()
+last_processed_timestamp = await load_last_processed_timestamp()
+
+# Use a channel in a namespace with persistence enabled
+# to access more than 2 minutes of message history
+channel = ably.channels.get(channel_name)
+
+# Subscribe to live messages (implicitly attaches the channel)
+def on_prompt(message):
+    # Process the live message
+    process_message(message)
+
+    # Persist the timestamp after successful processing
+    save_last_processed_timestamp(message.timestamp)
+
+await channel.subscribe("prompt", on_prompt)
+
+# Fetch history up until the point of attachment, starting from last checkpoint
+page = await channel.history(
+    until_attach=True,
+    start=last_processed_timestamp,
+    direction="forwards"
+)
+
+# Paginate through all missed messages
+while page:
+    for message in page.items:
+        # Process the historical message
+        await process_message(message)
+
+        # Persist the timestamp after successful processing
+        await save_last_processed_timestamp(message.timestamp)
+
+    # Move to next page if available
+    page = await page.next() if page.has_next() else None
+```
+```java
+// Agent code
+import io.ably.lib.realtime.AblyRealtime;
+import io.ably.lib.realtime.Channel;
+import io.ably.lib.types.ClientOptions;
+import io.ably.lib.types.Message;
+import io.ably.lib.types.PaginatedResult;
+import io.ably.lib.types.Param;
+
+ClientOptions options = new ClientOptions();
+options.key = System.getenv("ABLY_API_KEY");
+options.clientId = "agent:assistant";
+
+AblyRealtime ably = new AblyRealtime(options);
+
+// Load persisted session state
+String channelName = loadChannelName();
+long lastProcessedTimestamp = loadLastProcessedTimestamp();
+
+// Use a channel in a namespace with persistence enabled
+// to access more than 2 minutes of message history
+Channel channel = ably.channels.get(channelName);
+
+// Subscribe to live messages (implicitly attaches the channel)
+channel.subscribe("prompt", message -> {
+    // Process the live message
+    processMessage(message);
+
+    // Persist the timestamp after successful processing
+    saveLastProcessedTimestamp(message.timestamp);
+});
+
+// Fetch history up until the point of attachment, starting from last checkpoint
+Param[] params = new Param[] {
+    new Param("untilAttach", "true"),
+    new Param("start", String.valueOf(lastProcessedTimestamp)),
+    new Param("direction", "forwards")
+};
+PaginatedResult<Message> page = channel.history(params);
+
+// Paginate through all missed messages
+while (page != null) {
+    for (Message message : page.items()) {
+        // Process the historical message
+        processMessage(message);
+
+        // Persist the timestamp after successful processing
+        saveLastProcessedTimestamp(message.timestamp);
+    }
+
+    // Move to next page if available
+    page = page.hasNext() ? page.next() : null;
+}
+```
 </Code>
 
 <Aside data-type="note">
diff --git a/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx
index fb4fdd4cf5..a921222bd2 100644
--- a/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx
+++ b/src/pages/docs/ai-transport/token-streaming/message-per-response.mdx
@@ -53,6 +53,12 @@ Use the [`get()`](/docs/api/realtime-sdk/channels#get) method to create or retri
 ```javascript
 const channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}');
 ```
+```python
+channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}')
+```
+```java
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+```
 </Code>
 
 To start streaming an AI response, publish the initial message. The message is identified by a server-assigned identifier called a [`serial`](/docs/messages#properties). Use the `serial` to append each subsequent token to the message as it arrives from the AI model:
@@ -70,6 +76,42 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+# Publish initial message and capture the serial for appending tokens
+message = Message(name='response', data='')
+result = await channel.publish(message)
+msg_serial = result.serials[0]
+
+# Example: stream returns events like { 'type': 'token', 'text': 'Hello' }
+async for event in stream:
+    # Append each token as it arrives
+    if event['type'] == 'token':
+        channel.append_message(serial=msg_serial, data=event['text'])
+```
+```java
+// Publish initial message and capture the serial for appending tokens
+CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
+channel.publish("response", "", new Callback<PublishResult>() {
+    @Override
+    public void onSuccess(PublishResult result) {
+        publishFuture.complete(result);
+    }
+
+    @Override
+    public void onError(ErrorInfo reason) {
+        publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
+    }
+});
+String msgSerial = publishFuture.get().serials[0];
+
+// Example: stream returns events like { type: 'token', text: 'Hello' }
+for (Event event : stream) {
+    // Append each token as it arrives
+    if (event.getType().equals("token")) {
+        channel.appendMessage(msgSerial, event.getText());
+    }
+}
+```
 </Code>
 
 When publishing tokens, don't await the `channel.appendMessage()` call. Ably rolls up acknowledgments and debounces them for efficiency, which means awaiting each append would unnecessarily slow down your token stream. Messages are still published in the order that `appendMessage()` is called, so delivery order is not affected.
@@ -90,6 +132,44 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+# ✅ Do this - append without await for maximum throughput
+async for event in stream:
+    if event['type'] == 'token':
+        channel.append_message(serial=msg_serial, data=event['text'])
+
+# ❌ Don't do this - awaiting each append reduces throughput
+async for event in stream:
+    if event['type'] == 'token':
+        await channel.append_message(serial=msg_serial, data=event['text'])
+```
+```java
+// ✅ Do this - append without blocking for maximum throughput
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        channel.appendMessage(msgSerial, event.getText());
+    }
+}
+
+// ❌ Don't do this - blocking on each append reduces throughput
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        CompletableFuture<UpdateDeleteResult> appendFuture = new CompletableFuture<>();
+        channel.appendMessage(msgSerial, event.getText(), new Callback<UpdateDeleteResult>() {
+            @Override
+            public void onSuccess(UpdateDeleteResult result) {
+                appendFuture.complete(result);
+            }
+
+            @Override
+            public void onError(ErrorInfo reason) {
+                appendFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
+            }
+        });
+        appendFuture.get(); // blocking call
+    }
+}
+```
 </Code>
 
 <Aside data-type="important">
@@ -113,6 +193,18 @@ const realtime = new Ably.Realtime({
   transportParams: { appendRollupWindow: 100 } // 10 messages/s
 });
 ```
+```python
+realtime = AblyRealtime(
+    key='your-api-key',
+    transport_params={'appendRollupWindow': 100}  # 10 messages/s
+)
+```
+```java
+ClientOptions options = new ClientOptions();
+options.key = "your-api-key";
+options.transportParams = Map.of("appendRollupWindow", "100"); // 10 messages/s
+AblyRealtime realtime = new AblyRealtime(options);
+```
 </Code>
 
 The `appendRollupWindow` parameter controls how many tokens are combined into each published message for a given model output rate. This creates a trade-off between delivery smoothness and the number of concurrent model responses you can stream on a single connection:
@@ -160,6 +252,54 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by message serial
+responses = {}
+
+# Subscribe to live messages (implicitly attaches the channel)
+def on_message(message):
+    action = message.action
+
+    if action == 'message.create':
+        # New response started
+        responses[message.serial] = message.data
+    elif action == 'message.append':
+        # Append token to existing response
+        current = responses.get(message.serial, '')
+        responses[message.serial] = current + message.data
+    elif action == 'message.update':
+        # Replace entire response content
+        responses[message.serial] = message.data
+
+await channel.subscribe(on_message)
+```
+```java
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by message serial
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+// Subscribe to live messages (implicitly attaches the channel)
+channel.subscribe(message -> {
+    switch (message.action) {
+        case "message.create":
+            // New response started
+            responses.put(message.serial, (String) message.data);
+            break;
+        case "message.append":
+            // Append token to existing response
+            String current = responses.getOrDefault(message.serial, "");
+            responses.put(message.serial, current + (String) message.data);
+            break;
+        case "message.update":
+            // Replace entire response content
+            responses.put(message.serial, (String) message.data);
+            break;
+    }
+});
+```
 </Code>
 
 ## Client hydration <a id="hydration"/>
@@ -206,6 +346,60 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+# Use rewind to receive recent historical messages
+channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}', params={'rewind': '2m'})  # or rewind: '10' for message count
+
+# Track responses by message serial
+responses = {}
+
+# Subscribe to receive both recent historical and live messages,
+# which are delivered in order to the subscription
+def on_message(message):
+    action = message.action
+
+    if action == 'message.create':
+        # New response started
+        responses[message.serial] = message.data
+    elif action == 'message.append':
+        # Append token to existing response
+        current = responses.get(message.serial, '')
+        responses[message.serial] = current + message.data
+    elif action == 'message.update':
+        # Replace entire response content
+        responses[message.serial] = message.data
+
+await channel.subscribe(on_message)
+```
+```java
+// Use rewind to receive recent historical messages
+ChannelOptions options = new ChannelOptions();
+options.params = Map.of("rewind", "2m"); // or rewind: '10' for message count
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}", options);
+
+// Track responses by message serial
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+channel.subscribe(message -> {
+    switch (message.action) {
+        case "message.create":
+            // New response started
+            responses.put(message.serial, (String) message.data);
+            break;
+        case "message.append":
+            // Append token to existing response
+            String current = responses.getOrDefault(message.serial, "");
+            responses.put(message.serial, current + (String) message.data);
+            break;
+        case "message.update":
+            // Replace entire response content
+            responses.put(message.serial, (String) message.data);
+            break;
+    }
+});
+```
 </Code>
 
 Rewind supports two formats:
@@ -262,6 +456,82 @@ while (page) {
   page = page.hasNext() ? await page.next() : null;
 }
 ```
+```python
+channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by message serial
+responses = {}
+
+# Subscribe to live messages (implicitly attaches the channel)
+def on_message(message):
+    action = message.action
+
+    if action == 'message.create':
+        # New response started
+        responses[message.serial] = message.data
+    elif action == 'message.append':
+        # Append token to existing response
+        current = responses.get(message.serial, '')
+        responses[message.serial] = current + message.data
+    elif action == 'message.update':
+        # Replace entire response content
+        responses[message.serial] = message.data
+
+await channel.subscribe(on_message)
+
+# Fetch history up until the point of attachment
+page = await channel.history(until_attach=True)
+
+# Paginate backwards through history
+while page:
+    # Messages are newest-first
+    for message in page.items:
+        # message.data contains the full concatenated text
+        responses[message.serial] = message.data
+
+    # Move to next page if available
+    page = await page.next() if page.has_next() else None
+```
+```java
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by message serial
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+// Subscribe to live messages (implicitly attaches the channel)
+channel.subscribe(message -> {
+    switch (message.action) {
+        case "message.create":
+            // New response started
+            responses.put(message.serial, (String) message.data);
+            break;
+        case "message.append":
+            // Append token to existing response
+            String current = responses.getOrDefault(message.serial, "");
+            responses.put(message.serial, current + (String) message.data);
+            break;
+        case "message.update":
+            // Replace entire response content
+            responses.put(message.serial, (String) message.data);
+            break;
+    }
+});
+
+// Fetch history up until the point of attachment
+PaginatedResult<Message> page = channel.history(new Param("untilAttach", "true"));
+
+// Paginate backwards through history
+while (page != null) {
+    // Messages are newest-first
+    for (Message message : page.items()) {
+        // message.data contains the full concatenated text
+        responses.put(message.serial, (String) message.data);
+    }
+
+    // Move to next page if available
+    page = page.hasNext() ? page.next() : null;
+}
+```
 </Code>
 
 ### Hydrating an in-progress response <a id="in-progress-response"/>
@@ -300,6 +570,66 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+# Publish initial message with responseId in extras
+message = Message(
+    name='response',
+    data='',
+    extras={
+        'headers': {
+            'responseId': 'resp_abc123'  # Your database response ID
+        }
+    }
+)
+result = await channel.publish(message)
+msg_serial = result.serials[0]
+
+# Append tokens, including extras to preserve headers
+async for event in stream:
+    if event['type'] == 'token':
+        channel.append_message(
+            serial=msg_serial,
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': 'resp_abc123'
+                }
+            }
+        )
+```
+```java
+// Publish initial message with responseId in extras
+JsonObject extras = new JsonObject();
+JsonObject headers = new JsonObject();
+headers.addProperty("responseId", "resp_abc123"); // Your database response ID
+extras.add("headers", headers);
+
+CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
+channel.publish("response", "", extras, new Callback<PublishResult>() {
+    @Override
+    public void onSuccess(PublishResult result) {
+        publishFuture.complete(result);
+    }
+
+    @Override
+    public void onError(ErrorInfo reason) {
+        publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
+    }
+});
+String msgSerial = publishFuture.get().serials[0];
+
+// Append tokens, including extras to preserve headers
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        JsonObject appendExtras = new JsonObject();
+        JsonObject appendHeaders = new JsonObject();
+        appendHeaders.addProperty("responseId", "resp_abc123");
+        appendExtras.add("headers", appendHeaders);
+
+        channel.appendMessage(msgSerial, event.getText(), appendExtras);
+    }
+}
+```
 </Code>
 
 <Aside data-type="note">
@@ -354,6 +684,87 @@ await channel.subscribe((message) => {
   }
 });
 ```
+```python
+# Load completed responses from your database
+# completed_responses is a set of responseIds
+completed_responses = await load_responses_from_database()
+
+# Use rewind to receive recent historical messages
+channel = realtime.channels.get('ai:responses', params={'rewind': '2m'})
+
+# Track in-progress responses by responseId
+in_progress_responses = {}
+
+def on_message(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Message missing responseId')
+        return
+
+    # Skip messages for responses already loaded from database
+    if response_id in completed_responses:
+        return
+
+    action = message.action
+
+    if action == 'message.create':
+        # New response started
+        in_progress_responses[response_id] = message.data
+    elif action == 'message.append':
+        # Append token to existing response
+        current = in_progress_responses.get(response_id, '')
+        in_progress_responses[response_id] = current + message.data
+    elif action == 'message.update':
+        # Replace entire response content
+        in_progress_responses[response_id] = message.data
+
+await channel.subscribe(on_message)
+```
+```java
+// Load completed responses from your database
+// completedResponses is a Set of responseIds
+Set<String> completedResponses = loadResponsesFromDatabase();
+
+// Use rewind to receive recent historical messages
+ChannelOptions options = new ChannelOptions();
+options.params = Map.of("rewind", "2m");
+Channel channel = realtime.channels.get("ai:responses", options);
+
+// Track in-progress responses by responseId
+Map<String, String> inProgressResponses = new ConcurrentHashMap<>();
+
+channel.subscribe(message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Message missing responseId");
+        return;
+    }
+
+    // Skip messages for responses already loaded from database
+    if (completedResponses.contains(responseId)) {
+        return;
+    }
+
+    switch (message.action) {
+        case "message.create":
+            // New response started
+            inProgressResponses.put(responseId, (String) message.data);
+            break;
+        case "message.append":
+            // Append token to existing response
+            String current = inProgressResponses.getOrDefault(responseId, "");
+            inProgressResponses.put(responseId, current + (String) message.data);
+            break;
+        case "message.update":
+            // Replace entire response content
+            inProgressResponses.put(responseId, (String) message.data);
+            break;
+    }
+});
+```
 </Code>
 
 <Aside data-type="note">
@@ -433,6 +844,137 @@ while (page) {
   page = page.hasNext() ? await page.next() : null;
 }
 ```
+```python
+# Load completed responses from database (sorted by timestamp, oldest first)
+completed_responses = await load_responses_from_database()
+
+# Get the timestamp of the latest completed response
+latest_timestamp = completed_responses.latest().timestamp
+
+channel = realtime.channels.get('ai:{{RANDOM_CHANNEL_NAME}}')
+
+# Track in progress responses by ID
+in_progress_responses = {}
+
+# Subscribe to live messages (implicitly attaches)
+def on_message(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Message missing responseId')
+        return
+
+    # Skip messages for responses already loaded from database
+    if response_id in completed_responses:
+        return
+
+    action = message.action
+
+    if action == 'message.create':
+        # New response started
+        in_progress_responses[response_id] = message.data
+    elif action == 'message.append':
+        # Append token to existing response
+        current = in_progress_responses.get(response_id, '')
+        in_progress_responses[response_id] = current + message.data
+    elif action == 'message.update':
+        # Replace entire response content
+        in_progress_responses[response_id] = message.data
+
+await channel.subscribe(on_message)
+
+# Fetch history from the last completed response until attachment
+page = await channel.history(
+    until_attach=True,
+    start=latest_timestamp,
+    direction='forwards'
+)
+
+# Paginate through all missed messages
+while page:
+    for message in page.items:
+        response_id = message.extras.get('headers', {}).get('responseId')
+
+        if not response_id:
+            print('Message missing responseId')
+            continue
+
+        # message.data contains the full concatenated text so far
+        in_progress_responses[response_id] = message.data
+
+    # Move to next page if available
+    page = await page.next() if page.has_next() else None
+```
+```java
+// Load completed responses from database (sorted by timestamp, oldest first)
+List<Response> completedResponses = loadResponsesFromDatabase();
+
+// Get the timestamp of the latest completed response
+long latestTimestamp = completedResponses.get(completedResponses.size() - 1).getTimestamp();
+
+Channel channel = realtime.channels.get("ai:{{RANDOM_CHANNEL_NAME}}");
+
+// Track in progress responses by ID
+Map<String, String> inProgressResponses = new ConcurrentHashMap<>();
+
+// Subscribe to live messages (implicitly attaches)
+channel.subscribe(message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Message missing responseId");
+        return;
+    }
+
+    // Skip messages for responses already loaded from database
+    if (completedResponses.stream().anyMatch(r -> r.getId().equals(responseId))) {
+        return;
+    }
+
+    switch (message.action) {
+        case "message.create":
+            // New response started
+            inProgressResponses.put(responseId, (String) message.data);
+            break;
+        case "message.append":
+            // Append token to existing response
+            String current = inProgressResponses.getOrDefault(responseId, "");
+            inProgressResponses.put(responseId, current + (String) message.data);
+            break;
+        case "message.update":
+            // Replace entire response content
+            inProgressResponses.put(responseId, (String) message.data);
+            break;
+    }
+});
+
+// Fetch history from the last completed response until attachment
+PaginatedResult<Message> page = channel.history(
+    new Param("untilAttach", "true"),
+    new Param("start", String.valueOf(latestTimestamp)),
+    new Param("direction", "forwards")
+);
+
+// Paginate through all missed messages
+while (page != null) {
+    for (Message message : page.items()) {
+        JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+        String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+        if (responseId == null) {
+            System.err.println("Message missing responseId");
+            continue;
+        }
+
+        // message.data contains the full concatenated text so far
+        inProgressResponses.put(responseId, (String) message.data);
+    }
+
+    // Move to next page if available
+    page = page.hasNext() ? page.next() : null;
+}
+```
 </Code>
 
 <Aside data-type="note">
diff --git a/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx
index 8ea595cfc6..310bdccb1d 100644
--- a/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx
+++ b/src/pages/docs/ai-transport/token-streaming/message-per-token.mdx
@@ -24,6 +24,12 @@ Use the [`get()`](/docs/api/realtime-sdk/channels#get) method to create or retri
 ```javascript
 const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+```
 </Code>
 
 When publishing tokens, don't await the `channel.publish()` call. Ably rolls up acknowledgments and debounces them for efficiency, which means awaiting each publish would unnecessarily slow down your token stream. Messages are still published in the order that `publish()` is called, so delivery order is not affected.
@@ -44,6 +50,34 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+# ✅ Do this - publish without await for maximum throughput
+async for event in stream:
+    if event['type'] == 'token':
+        message = Message(name='token', data=event['text'])
+        channel.publish(message)
+
+# ❌ Don't do this - awaiting each publish reduces throughput
+async for event in stream:
+    if event['type'] == 'token':
+        message = Message(name='token', data=event['text'])
+        await channel.publish(message)
+```
+```java
+// ✅ Do this - publish without blocking for maximum throughput
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        channel.publish("token", event.getText());
+    }
+}
+
+// ❌ Don't do this - blocking on each publish reduces throughput
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        channel.publish("token", event.getText()).get(); // blocking call
+    }
+}
+```
 </Code>
 
 This approach maximizes throughput while maintaining ordering guarantees, allowing you to stream tokens as fast as your AI model generates them.
@@ -77,6 +111,24 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like { 'type': 'token', 'text': 'Hello' }
+async for event in stream:
+    if event['type'] == 'token':
+        channel.publish('token', event['text'])
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like { type: 'token', text: 'Hello' }
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        channel.publish("token", event.getText());
+    }
+}
+```
 </Code>
 
 #### Subscribe to tokens
@@ -91,6 +143,25 @@ await channel.subscribe('token', (message) => {
   console.log(token); // log each token as it arrives
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Subscribe to token messages
+def on_token(message):
+    token = message.data
+    print(token)  # log each token as it arrives
+
+await channel.subscribe('token', on_token)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Subscribe to token messages
+channel.subscribe("token", message -> {
+    String token = (String) message.data;
+    System.out.println(token); // log each token as it arrives
+});
+```
 </Code>
 
 This pattern is simple and works well when you're displaying a single, continuous stream of tokens.
@@ -120,6 +191,37 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like { 'type': 'token', 'text': 'Hello', 'responseId': 'resp_abc123' }
+async for event in stream:
+    if event['type'] == 'token':
+        channel.publish(
+            name='token',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like { type: 'token', text: 'Hello', responseId: 'resp_abc123' }
+for (Event event : stream) {
+    if (event.getType().equals("token")) {
+        JsonObject extras = new JsonObject();
+        JsonObject headers = new JsonObject();
+        headers.addProperty("responseId", event.getResponseId());
+        extras.add("headers", headers);
+
+        channel.publish(new Message("token", event.getText(), new MessageExtras(extras)));
+    }
+}
+```
 </Code>
 
 #### Subscribe to tokens
@@ -151,6 +253,52 @@ await channel.subscribe('token', (message) => {
   responses.set(responseId, responses.get(responseId) + token);
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Track responses by ID
+responses = {}
+
+def on_token(message):
+    token = message.data
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Token missing responseId')
+        return
+
+    # Create an empty response
+    if response_id not in responses:
+        responses[response_id] = ''
+
+    # Append token to response
+    responses[response_id] += token
+
+await channel.subscribe('token', on_token)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Track responses by ID
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+channel.subscribe("token", message -> {
+    String token = (String) message.data;
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Token missing responseId");
+        return;
+    }
+
+    // Create an empty response
+    responses.putIfAbsent(responseId, "");
+
+    // Append token to response
+    responses.put(responseId, responses.get(responseId) + token);
+});
+```
 </Code>
 
 ### Token stream with explicit start/stop events <a id="explicit-events"/>
@@ -203,6 +351,73 @@ for await (const event of stream) {
   }
 }
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+# Example: stream returns events like:
+# { 'type': 'message_start', 'responseId': 'resp_abc123' }
+# { 'type': 'message_delta', 'responseId': 'resp_abc123', 'text': 'Hello' }
+# { 'type': 'message_stop', 'responseId': 'resp_abc123' }
+
+async for event in stream:
+    if event['type'] == 'message_start':
+        # Publish response start
+        channel.publish(
+            name='start',
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+    elif event['type'] == 'message_delta':
+        # Publish tokens
+        channel.publish(
+            name='token',
+            data=event['text'],
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+    elif event['type'] == 'message_stop':
+        # Publish response stop
+        channel.publish(
+            name='stop',
+            extras={
+                'headers': {
+                    'responseId': event['responseId']
+                }
+            }
+        )
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+// Example: stream returns events like:
+// { type: 'message_start', responseId: 'resp_abc123' }
+// { type: 'message_delta', responseId: 'resp_abc123', text: 'Hello' }
+// { type: 'message_stop', responseId: 'resp_abc123' }
+
+for (Event event : stream) {
+    JsonObject extras = new JsonObject();
+    JsonObject headers = new JsonObject();
+    headers.addProperty("responseId", event.getResponseId());
+    extras.add("headers", headers);
+
+    if (event.getType().equals("message_start")) {
+        // Publish response start
+        channel.publish(new Message("start", null, new MessageExtras(extras)));
+    } else if (event.getType().equals("message_delta")) {
+        // Publish tokens
+        channel.publish(new Message("token", event.getText(), new MessageExtras(extras)));
+    } else if (event.getType().equals("message_stop")) {
+        // Publish response stop
+        channel.publish(new Message("stop", null, new MessageExtras(extras)));
+    }
+}
+```
 </Code>
 
 #### Subscribe to tokens
@@ -237,6 +452,66 @@ await channel.subscribe('stop', (message) => {
   console.log('Response complete:', finalText);
 });
 ```
+```python
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+
+responses = {}
+
+# Handle response start
+def on_start(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+    responses[response_id] = ''
+
+await channel.subscribe('start', on_start)
+
+# Handle tokens
+def on_token(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+    token = message.data
+
+    current_text = responses.get(response_id, '')
+    responses[response_id] = current_text + token
+
+await channel.subscribe('token', on_token)
+
+# Handle response stop
+def on_stop(message):
+    response_id = message.extras.get('headers', {}).get('responseId')
+    final_text = responses.get(response_id)
+    print('Response complete:', final_text)
+
+await channel.subscribe('stop', on_stop)
+```
+```java
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}");
+
+Map<String, String> responses = new ConcurrentHashMap<>();
+
+// Handle response start
+channel.subscribe("start", message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers.get("responseId").getAsString();
+    responses.put(responseId, "");
+});
+
+// Handle tokens
+channel.subscribe("token", message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers.get("responseId").getAsString();
+    String token = (String) message.data;
+
+    String currentText = responses.getOrDefault(responseId, "");
+    responses.put(responseId, currentText + token);
+});
+
+// Handle response stop
+channel.subscribe("stop", message -> {
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers.get("responseId").getAsString();
+    String finalText = responses.get(responseId);
+    System.out.println("Response complete: " + finalText);
+});
+```
 </Code>
 
 ## Client hydration <a id="hydration"/>
@@ -271,6 +546,35 @@ await channel.subscribe('token', (message) => {
   console.log('Token received:', token);
 });
 ```
+```python
+# Use rewind to receive recent historical messages
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', params={'rewind': '2m'})  # or rewind: 100 for message count
+
+# Subscribe to receive both recent historical and live messages,
+# which are delivered in order to the subscription
+def on_token(message):
+    token = message.data
+
+    # Process tokens from both recent history and live stream
+    print('Token received:', token)
+
+await channel.subscribe('token', on_token)
+```
+```java
+// Use rewind to receive recent historical messages
+ChannelOptions options = new ChannelOptions();
+options.params = Map.of("rewind", "2m"); // or rewind: 100 for message count
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}", options);
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+channel.subscribe("token", message -> {
+    String token = (String) message.data;
+
+    // Process tokens from both recent history and live stream
+    System.out.println("Token received: " + token);
+});
+```
 </Code>
 
 Rewind supports two formats:
@@ -315,6 +619,58 @@ while (page) {
   page = page.hasNext() ? await page.next() : null;
 }
 ```
+```python
+# Use a channel in a namespace called 'persisted', which has persistence enabled
+channel = realtime.channels.get('persisted:{{RANDOM_CHANNEL_NAME}}')
+
+response = ''
+
+# Subscribe to live messages (implicitly attaches the channel)
+def on_token(message):
+    global response
+    # Append the token to the end of the response
+    response += message.data
+
+await channel.subscribe('token', on_token)
+
+# Fetch history up until the point of attachment
+page = await channel.history(until_attach=True)
+
+# Paginate backwards through history
+while page:
+    # Messages are newest-first, so prepend them to response
+    for message in page.items:
+        response = message.data + response
+
+    # Move to next page if available
+    page = await page.next() if page.has_next() else None
+```
+```java
+// Use a channel in a namespace called 'persisted', which has persistence enabled
+Channel channel = realtime.channels.get("persisted:{{RANDOM_CHANNEL_NAME}}");
+
+StringBuilder response = new StringBuilder();
+
+// Subscribe to live messages (implicitly attaches the channel)
+channel.subscribe("token", message -> {
+    // Append the token to the end of the response
+    response.append((String) message.data);
+});
+
+// Fetch history up until the point of attachment
+PaginatedResult<Message> page = channel.history(new Param("untilAttach", "true"));
+
+// Paginate backwards through history
+while (page != null) {
+    // Messages are newest-first, so prepend them to response
+    for (Message message : page.items()) {
+        response.insert(0, (String) message.data);
+    }
+
+    // Move to next page if available
+    page = page.hasNext() ? page.next() : null;
+}
+```
 </Code>
 
 ### Hydrating an in-progress response <a id="in-progress-response"/>
@@ -367,6 +723,75 @@ await channel.subscribe('token', (message) => {
   inProgressResponses.set(responseId, inProgressResponses.get(responseId) + token);
 });
 ```
+```python
+# Load completed responses from database
+completed_responses = await load_responses_from_database()
+
+# Use rewind to receive recent historical messages
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', params={'rewind': '2m'})
+
+# Track in progress responses by ID
+in_progress_responses = {}
+
+# Subscribe to receive both recent historical and live messages,
+# which are delivered in order to the subscription
+def on_token(message):
+    token = message.data
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Token missing responseId')
+        return
+
+    # Skip tokens for responses already hydrated from database
+    if response_id in completed_responses:
+        return
+
+    # Create an empty in-progress response
+    if response_id not in in_progress_responses:
+        in_progress_responses[response_id] = ''
+
+    # Append tokens for new responses
+    in_progress_responses[response_id] += token
+
+await channel.subscribe('token', on_token)
+```
+```java
+// Load completed responses from database
+Set<String> completedResponses = loadResponsesFromDatabase();
+
+// Use rewind to receive recent historical messages
+ChannelOptions options = new ChannelOptions();
+options.params = Map.of("rewind", "2m");
+Channel channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}", options);
+
+// Track in progress responses by ID
+Map<String, String> inProgressResponses = new ConcurrentHashMap<>();
+
+// Subscribe to receive both recent historical and live messages,
+// which are delivered in order to the subscription
+channel.subscribe("token", message -> {
+    String token = (String) message.data;
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Token missing responseId");
+        return;
+    }
+
+    // Skip tokens for responses already hydrated from database
+    if (completedResponses.contains(responseId)) {
+        return;
+    }
+
+    // Create an empty in-progress response
+    inProgressResponses.putIfAbsent(responseId, "");
+
+    // Append tokens for new responses
+    inProgressResponses.put(responseId, inProgressResponses.get(responseId) + token);
+});
+```
 </Code>
 
 #### Hydrate using history
@@ -438,4 +863,124 @@ while (page && !done) {
   page = page.hasNext() ? await page.next() : null;
 }
 ```
+```python
+# Load completed responses from database
+completed_responses = await load_responses_from_database()
+
+# Use a channel in a namespace called 'persisted', which has persistence enabled
+channel = realtime.channels.get('persisted:{{RANDOM_CHANNEL_NAME}}')
+
+# Track in progress responses by ID
+in_progress_responses = {}
+
+# Subscribe to live tokens (implicitly attaches)
+def on_token(message):
+    token = message.data
+    response_id = message.extras.get('headers', {}).get('responseId')
+
+    if not response_id:
+        print('Token missing responseId')
+        return
+
+    # Skip tokens for responses already hydrated from database
+    if response_id in completed_responses:
+        return
+
+    # Create an empty in-progress response
+    if response_id not in in_progress_responses:
+        in_progress_responses[response_id] = ''
+
+    # Append live tokens for in-progress responses
+    in_progress_responses[response_id] += token
+
+await channel.subscribe('token', on_token)
+
+# Paginate backwards through history until we encounter a hydrated response
+page = await channel.history(until_attach=True)
+
+# Paginate backwards through history
+done = False
+while page and not done:
+    # Messages are newest-first, so prepend them to response
+    for message in page.items:
+        token = message.data
+        response_id = message.extras.get('headers', {}).get('responseId')
+
+        # Stop when we reach a response already loaded from database
+        if response_id in completed_responses:
+            done = True
+            break
+
+        # Create an empty in-progress response
+        if response_id not in in_progress_responses:
+            in_progress_responses[response_id] = ''
+
+        # Prepend historical tokens for in-progress responses
+        in_progress_responses[response_id] = token + in_progress_responses[response_id]
+
+    # Move to next page if available
+    page = await page.next() if page.has_next() else None
+```
+```java
+// Load completed responses from database
+Set<String> completedResponses = loadResponsesFromDatabase();
+
+// Use a channel in a namespace called 'persisted', which has persistence enabled
+Channel channel = realtime.channels.get("persisted:{{RANDOM_CHANNEL_NAME}}");
+
+// Track in progress responses by ID
+Map<String, String> inProgressResponses = new ConcurrentHashMap<>();
+
+// Subscribe to live tokens (implicitly attaches)
+channel.subscribe("token", message -> {
+    String token = (String) message.data;
+    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+    String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+    if (responseId == null) {
+        System.err.println("Token missing responseId");
+        return;
+    }
+
+    // Skip tokens for responses already hydrated from database
+    if (completedResponses.contains(responseId)) {
+        return;
+    }
+
+    // Create an empty in-progress response
+    inProgressResponses.putIfAbsent(responseId, "");
+
+    // Append live tokens for in-progress responses
+    inProgressResponses.put(responseId, inProgressResponses.get(responseId) + token);
+});
+
+// Paginate backwards through history until we encounter a hydrated response
+PaginatedResult<Message> page = channel.history(new Param("untilAttach", "true"));
+
+// Paginate backwards through history
+boolean done = false;
+while (page != null && !done) {
+    // Messages are newest-first, so prepend them to response
+    for (Message message : page.items()) {
+        String token = (String) message.data;
+        JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
+        String responseId = headers != null ? headers.get("responseId").getAsString() : null;
+
+        // Stop when we reach a response already loaded from database
+        if (completedResponses.contains(responseId)) {
+            done = true;
+            break;
+        }
+
+        // Create an empty in-progress response
+        inProgressResponses.putIfAbsent(responseId, "");
+
+        // Prepend historical tokens for in-progress responses
+        inProgressResponses.put(responseId, token + inProgressResponses.get(responseId));
+    }
+
+    // Move to next page if available
+    page = page.hasNext() ? page.next() : null;
+}
+```
 </Code>

From 27a0e481603a4f1bc90b0e2c582d1dd0e043bd7b Mon Sep 17 00:00:00 2001
From: Greg Holmes <iam@gregholmes.co.uk>
Date: Mon, 2 Feb 2026 09:54:27 +0000
Subject: [PATCH 2/2] Add Java and Python language support to AI Transport docs

- Add Java and Python to aiTransport language configuration to enable
  language dropdown on AI Transport documentation pages
- Add Python and Java code snippets for rollup configuration in
  token-rate-limits.mdx
---
 src/data/languages/languageData.ts                   |  2 ++
 .../token-streaming/token-rate-limits.mdx            | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts
index 0b08361592..507ce00839 100644
--- a/src/data/languages/languageData.ts
+++ b/src/data/languages/languageData.ts
@@ -44,6 +44,8 @@ export default {
   },
   aiTransport: {
     javascript: '2.11',
+    java: '1.6',
+    python: '3.0',
   },
   spaces: {
     javascript: '0.4',
diff --git a/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx b/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx
index 8ea7a13087..b6f095d170 100644
--- a/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx
+++ b/src/pages/docs/ai-transport/token-streaming/token-rate-limits.mdx
@@ -48,6 +48,18 @@ const ably = new Ably.Realtime(
   }
 );
 ```
+```python
+ably = AblyRealtime(
+    key='your-api-key',
+    transport_params={'appendRollupWindow': 100}
+)
+```
+```java
+ClientOptions options = new ClientOptions();
+options.key = "your-api-key";
+options.transportParams = Map.of("appendRollupWindow", "100");
+AblyRealtime ably = new AblyRealtime(options);
+```
 </Code>
 
 <Aside data-type="important">