Add documentation for chat processing modes and typing indicators

Documents new features from cloudflare/agents#685:
- Chat processing modes (sequential and batch) for AIChatAgent
- Typing indicator support via onInputChange and inputProps
- Configuration options: chatProcessingMode, chatIdleTimeout, chatTypingTimeout
- Updated useAgentChat API reference with new return values
- Added comprehensive examples for both processing modes

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,21 @@ 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 - how to handle multiple incoming messages
+  // - "sequential": Process each message one-by-one (default)
+  // - "batch": Combine multiple rapid messages into one response
+  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
+  // Default: 1500ms (1.5 seconds)
+  chatTypingTimeout: number;
 }
 ```
 
@@ -865,6 +880,106 @@ class CustomerSupportAgent extends AIChatAgent<Env> {
 
 </TypeScriptExample>
 
+#### Chat processing modes
+
+The `AIChatAgent` supports two modes for handling multiple incoming chat messages:
+
+- **Sequential mode** (default): Processes each message one-by-one, with each message getting its own response. Messages are queued and processed in order, waiting for each response to complete before starting the next.
+
+- **Batch mode**: Combines multiple rapid messages into a single response. Uses debounce timing and optional typing indicators to intelligently batch messages, providing a better conversational experience when users send multiple short messages in quick succession.
+
+**Sequential mode example:**
+
+<TypeScriptExample>
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+class MyAgent extends AIChatAgent<Env> {
+  // Sequential mode is the default - no configuration needed
+  // Each message gets its own response
+  async onChatMessage(onFinish) {
+    // Process message and return response
+  }
+}
+```
+
+</TypeScriptExample>
+
+**Batch mode example:**
+
+<TypeScriptExample>
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+class MyAgent extends AIChatAgent<Env> {
+  // Enable batch mode
+  chatProcessingMode = "batch";
+
+  // Configure batching timeouts
+  chatIdleTimeout = 3000;    // 3 seconds - wait for user to start typing
+  chatTypingTimeout = 1500;   // 1.5 seconds - wait after typing stops
+
+  async onChatMessage(onFinish) {
+    // Messages sent within the batching window are combined
+    // Only the latest message (with full conversation) is processed
+  }
+}
+```
+
+</TypeScriptExample>
+
+**Batch mode with typing indicators:**
+
+For the best user experience in batch mode, use typing indicators to intelligently delay processing until the user finishes typing. This requires client-side integration:
+
+<TypeScriptExample>
+
+```tsx
+import { useAgentChat } from "agents/ai-react";
+import { useAgent } from "agents/react";
+
+function ChatInterface() {
+  const agent = useAgent({ agent: "my-agent", name: "user-123" });
+
+  const { input, handleInputChange, handleSubmit, onInputChange } = useAgentChat({
+    agent
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <textarea
+        value={input}
+        onChange={(e) => {
+          handleInputChange(e);
+          // Send typing indicator to enable smart batching
+          onInputChange(e);
+        }}
+      />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+</TypeScriptExample>
+
+**How batch mode timing works:**
+
+1. **Without typing indicators** (simple batching): All messages within `chatIdleTimeout` are batched together.
+
+2. **With typing indicators** (smart batching):
+   - After a message is sent, the agent waits up to `chatIdleTimeout` for the user to start typing
+   - Once typing is detected, it switches to the shorter `chatTypingTimeout`
+   - Each typing indicator resets the timer
+   - Processing begins after typing stops for `chatTypingTimeout` milliseconds
+
+This approach ensures that:
+- Multiple quick messages from the user are batched into one response
+- The agent waits for the user to finish their thought
+- Response generation happens promptly after the user stops typing
+
 ### Chat Agent React API
 
 #### useAgentChat
@@ -923,6 +1038,14 @@ function useAgentChat(options: UseAgentChatOptions): {
   addToolResult: ({ toolCallId, result }: { toolCallId: string; result: any }) => void;
   // Current error if any
   error: Error | undefined;
+  // Send a typing indicator to the agent (throttled to 500ms)
+  sendTypingIndicator: () => void;
+  // Input change handler that automatically sends typing indicators
+  onInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  // Props to spread onto your input element for automatic typing detection
+  inputProps: {
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  };
 };
 ```
 
@@ -949,7 +1072,8 @@ function ChatInterface() {
     handleSubmit,
     isLoading,
     error,
-    clearHistory
+    clearHistory,
+    onInputChange  // New: for typing indicators
   } = useAgentChat({
     agent: agentConnection,
     initialMessages: [
@@ -974,7 +1098,11 @@ function ChatInterface() {
       <form onSubmit={handleSubmit} className="message-input">
         <input
           value={input}
-          onChange={handleInputChange}
+          onChange={(e) => {
+            handleInputChange(e);
+            // Send typing indicators for batch mode agents
+            onInputChange(e);
+          }}
           placeholder="Type your message..."
           disabled={isLoading}
         />