Document chat processing modes and typing indicators for AIChatAgent

This update documents new features from PR #685 (cloudflare/agents):
- Chat processing modes (sequential vs batch)
- Typing indicators for smart message batching
- New AIChatAgent properties: chatProcessingMode, chatIdleTimeout, chatTypingTimeout
- New useAgentChat returns: onInputChange, inputProps, sendTypingIndicator

The documentation includes:
- API reference updates for AIChatAgent class properties
- Examples showing sequential and batch processing modes
- React examples demonstrating typing indicator integration
- Use cases and best practices for each mode

These features enable better handling of conversational chat patterns where
users send multiple rapid messages.

Related PR: cloudflare/agents#685

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: github-actions[bot]

src/content/docs/agents/api-reference/agents-api.mdx

@@ -809,6 +809,22 @@ class AIChatAgent<Env = unknown, State = unknown> extends Agent<Env, State> {
 
   // Persist messages within the Agent's local storage.
   async saveMessages(messages: Message[]): Promise<void>;
+
+  // Chat processing mode - controls how multiple incoming messages are handled
+  // "sequential": Each message gets its own response (default)
+  // "batch": Combine rapid messages into one response using debounce timing
+  chatProcessingMode: "sequential" | "batch";
+
+  // Idle timeout in milliseconds (batch mode only)
+  // How long to wait after a message is sent before processing
+  // Default: 5000ms (5 seconds)
+  chatIdleTimeout: number;
+
+  // Typing timeout in milliseconds (batch mode only)
+  // How long to wait after user stops typing before processing
+  // Requires client to send typing indicators via onInputChange
+  // Default: 1500ms (1.5 seconds)
+  chatTypingTimeout: number;
 }
 ```
 
@@ -865,6 +881,75 @@ class CustomerSupportAgent extends AIChatAgent<Env> {
 
 </TypeScriptExample>
 
+##### Chat Processing Modes
+
+`AIChatAgent` supports two modes for handling multiple incoming messages:
+
+**Sequential Mode (Default)**
+
+In sequential mode, each message gets its own response. Messages are queued and processed one at a time, waiting for each response to fully complete before processing the next. No client changes required.
+
+<TypeScriptExample>
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+class SequentialAgent extends AIChatAgent<Env> {
+  // Sequential is the default - no configuration needed
+  chatProcessingMode = "sequential";
+
+  async onChatMessage(onFinish) {
+    // Each message will be processed independently
+    // Users will get separate responses for each message
+    return await this.generateResponse();
+  }
+}
+```
+
+</TypeScriptExample>
+
+**Batch Mode**
+
+In batch mode, multiple rapid messages are combined into one response. This is better for conversational UX where users send multiple short messages in quick succession.
+
+There are two ways to use batch mode:
+
+1. **Simple batching** - Set a fixed time window (no client changes required)
+2. **Smart batching** - Use typing indicators for more responsive batching (requires client changes)
+
+<TypeScriptExample>
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+// Simple batching - 3 second window
+class SimpleBatchAgent extends AIChatAgent<Env> {
+  chatProcessingMode = "batch";
+  chatIdleTimeout = 3000; // 3 seconds to batch messages
+
+  async onChatMessage(onFinish) {
+    // All messages within 3 seconds will be batched
+    // this.messages contains all batched messages
+    return await this.generateResponse();
+  }
+}
+
+// Smart batching - with typing indicators
+class SmartBatchAgent extends AIChatAgent<Env> {
+  chatProcessingMode = "batch";
+  chatIdleTimeout = 5000;  // 5s max wait for user to start typing
+  chatTypingTimeout = 1500; // 1.5s after typing stops
+
+  async onChatMessage(onFinish) {
+    // Once user starts typing, switches to shorter 1.5s timeout
+    // More responsive to user typing patterns
+    return await this.generateResponse();
+  }
+}
+```
+
+</TypeScriptExample>
+
 ### Chat Agent React API
 
 #### useAgentChat
@@ -923,6 +1008,14 @@ function useAgentChat(options: UseAgentChatOptions): {
   addToolResult: ({ toolCallId, result }: { toolCallId: string; result: any }) => void;
   // Current error if any
   error: Error | undefined;
+  // Manually send a typing indicator to the agent (throttled)
+  sendTypingIndicator: () => void;
+  // Input change handler that automatically sends typing indicators
+  onInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  // Props to spread onto input element for automatic typing detection
+  inputProps: {
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  };
 };
 ```
 
@@ -992,6 +1085,89 @@ function ChatInterface() {
 
 </TypeScriptExample>
 
+##### Typing Indicators for Smart Batching
+
+When using batch mode with typing indicators on your agent, you can use the `onInputChange` handler or `inputProps` to automatically send typing signals. This allows the agent to intelligently batch messages while remaining responsive to user typing.
+
+<TypeScriptExample>
+
+```tsx
+// Using onInputChange for manual control
+import { useAgentChat } from "agents/ai-react";
+import { useAgent } from "agents/react";
+import { useState } from "react";
+
+function SmartBatchingChat() {
+  const agent = useAgent({
+    agent: "smart-batch-agent",
+    name: "user-123"
+  });
+
+  const {
+    messages,
+    input,
+    setInput,
+    handleSubmit,
+    onInputChange // New: typing indicator handler
+  } = useAgentChat({ agent });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={input}
+        onChange={(e) => {
+          setInput(e.target.value); // Update input value
+          onInputChange(e); // Send typing indicator to agent
+        }}
+        placeholder="Type your message..."
+      />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+
+// Using inputProps for automatic setup
+function SimplerSmartBatchingChat() {
+  const agent = useAgent({
+    agent: "smart-batch-agent",
+    name: "user-123"
+  });
+
+  const {
+    messages,
+    input,
+    setInput,
+    handleSubmit,
+    inputProps // New: contains onChange with typing indicator
+  } = useAgentChat({ agent });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={input}
+        onChange={(e) => {
+          setInput(e.target.value);
+          inputProps.onChange(e); // Automatically sends typing indicators
+        }}
+        placeholder="Type your message..."
+      />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+</TypeScriptExample>
+
+**How it works:**
+
+- **Without typing indicators**: Agent waits `chatIdleTimeout` (default 5s) after receiving a message
+- **With typing indicators**: Agent switches to `chatTypingTimeout` (default 1.5s) once typing is detected
+- **Throttling**: Typing indicators are throttled to 500ms to avoid excessive network traffic
+- **Use cases**:
+  - Users sending multiple quick messages ("Hey", "Can you help", "With this issue?")
+  - Conversational interfaces where rapid-fire messaging is common
+  - Mobile chat interfaces with auto-correct/suggestions
 
 ### Next steps