\n );\n}\n```\n\n### Wrangler Config\n\n```jsonc\n// wrangler.jsonc\n{\n \"ai\": { \"binding\": \"AI\" },\n \"durable_objects\": {\n \"bindings\": [{ \"name\": \"ChatAgent\", \"class_name\": \"ChatAgent\" }]\n },\n \"migrations\": [\n {\n \"tag\": \"v1\",\n \"new_sqlite_classes\": [\"ChatAgent\"]\n }\n ]\n}\n```\n\n## Tools\n\n### Server-side tools\n\nTools with an `execute` function run on the server automatically:\n\n```typescript\nimport { createWorkersAI } from \"workers-ai-provider\";\nimport { streamText, convertToModelMessages, tool } from \"ai\";\nimport { z } from \"zod\";\n\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage() {\n const workersai = createWorkersAI({ binding: this.env.AI });\n\n const result = streamText({\n model: workersai(\"@cf/moonshotai/kimi-k2.6\"),\n messages: await convertToModelMessages(this.messages),\n tools: {\n getWeather: tool({\n description: \"Get weather for a city\",\n inputSchema: z.object({ city: z.string() }),\n execute: async ({ city }) => {\n const data = await fetchWeather(city);\n return { temperature: data.temp, condition: data.condition };\n }\n })\n },\n maxSteps: 5\n });\n\n return result.toUIMessageStreamResponse();\n }\n}\n```\n\n### Client-side tools\n\nTools without `execute` are handled on the client via `onToolCall`. Use this for tools that need browser APIs (geolocation, clipboard, camera):\n\n```typescript\n// Server: define tool without execute\ngetLocation: tool({\n description: \"Get the user's location from their browser\",\n inputSchema: z.object({})\n // No execute -- client handles it\n});\n```\n\n```tsx\n// Client: handle via onToolCall\nconst { messages, sendMessage } = useAgentChat({\n agent,\n onToolCall: async ({ toolCall, addToolOutput }) => {\n if (toolCall.toolName === \"getLocation\") {\n const pos = await new Promise((resolve, reject) =>\n navigator.geolocation.getCurrentPosition(resolve, reject)\n );\n addToolOutput({\n toolCallId: toolCall.toolCallId,\n output: { lat: pos.coords.latitude, lng: pos.coords.longitude }\n });\n }\n }\n});\n```\n\n### Tool approval (human-in-the-loop)\n\nUse `needsApproval` for tools that require user confirmation before executing:\n\n```typescript\n// Server\nprocessPayment: tool({\n description: \"Process a payment\",\n inputSchema: z.object({ amount: z.number(), recipient: z.string() }),\n needsApproval: async ({ amount }) => amount > 100, // Only require approval for large amounts\n execute: async ({ amount, recipient }) => charge(amount, recipient)\n});\n```\n\n```tsx\n// Client\nconst { messages, addToolApprovalResponse } = useAgentChat({ agent });\n\n// When rendering tool parts with state === \"approval-requested\":\n\n\n```\n\n## Resumable Streaming\n\nStreams automatically resume on disconnect/reconnect. No configuration needed.\n\nWhen a client disconnects mid-stream, chunks are buffered in SQLite. On reconnect, the client receives all buffered chunks and continues receiving the live stream.\n\nDisable with `resume: false`:\n\n```tsx\nconst { messages } = useAgentChat({ agent, resume: false });\n```\n\n## Overlapping Messages\n\nWhen users submit a new message while another turn is still active, `AIChatAgent`\ncan queue, collapse, or drop the overlap server-side:\n\n```typescript\nexport class ChatAgent extends AIChatAgent {\n messageConcurrency = \"latest\";\n\n async onChatMessage() {\n // ...\n }\n}\n```\n\nAvailable strategies:\n\n- `\"queue\"` (default) — process every submit in order\n- `\"latest\"` — keep only the newest overlapping submit and skip any older queued overlap turns\n- `\"merge\"` — queue overlapping submits, then collapse their queued user messages into one combined follow-up user turn\n- `\"drop\"` — ignore overlapping submits\n- `{ strategy: \"debounce\", debounceMs: 750 }` — wait for a quiet window, then run only the latest submit\n\n**Choosing a strategy:** Use `\"latest\"` for focused assistants where the user\ncan correct themselves mid-stream. Use `\"queue\"` or `\"merge\"` for messaging\napps where every message matters. Use `\"drop\"` to prevent double-sends. Use\n`\"debounce\"` when users send bursts of short messages.\n\n**What the user sees:** With `\"queue\"`, every message gets its own response.\nWith `\"latest\"`, all messages appear but only the last overlapping one gets a\nresponse. With `\"merge\"`, overlapping messages are collapsed into one. With\n`\"drop\"`, the overlapping message briefly appears then disappears (rollback).\n\nThis setting only affects overlapping `sendMessage()` submits. Regenerate,\ntool continuations, approvals, and programmatic `saveMessages()` calls keep the\nexisting serialized behavior. When `debounceMs` is missing or invalid,\n`AIChatAgent` falls back to the default `750` ms window.\n\nPass a function to `saveMessages()` to derive from the latest transcript when\nthe turn actually starts — useful for schedule callbacks and webhook handlers\nwhere messages may have changed since the call was made:\n\n```typescript\nawait this.saveMessages((messages) => [\n ...messages,\n {\n id: crypto.randomUUID(),\n role: \"user\",\n parts: [{ type: \"text\", text: \"Scheduled follow-up\" }]\n }\n]);\n```\n\n`saveMessages()` returns `{ requestId, status }` — check `status` to detect\nwhether the turn was skipped (e.g. because the chat was cleared while queued).\n\n## Storage Management\n\n### Limiting stored messages\n\nCap the number of messages kept in SQLite:\n\n```typescript\nexport class ChatAgent extends AIChatAgent {\n maxPersistedMessages = 200; // Keep last 200 messages\n\n async onChatMessage() {\n // ...\n }\n}\n```\n\nOldest messages are deleted when the count exceeds the limit. This controls storage only -- it does not affect what is sent to the LLM.\n\n### Controlling LLM context\n\nUse the AI SDK's `pruneMessages()` to control what is sent to the model, independently of what is stored:\n\n```typescript\nimport { createWorkersAI } from \"workers-ai-provider\";\nimport { streamText, convertToModelMessages, pruneMessages } from \"ai\";\n\nexport class ChatAgent extends AIChatAgent {\n maxPersistedMessages = 200;\n\n async onChatMessage() {\n const workersai = createWorkersAI({ binding: this.env.AI });\n\n const result = streamText({\n model: workersai(\"@cf/moonshotai/kimi-k2.6\"),\n messages: pruneMessages({\n messages: await convertToModelMessages(this.messages),\n reasoning: \"before-last-message\",\n toolCalls: \"before-last-2-messages\"\n })\n });\n\n return result.toUIMessageStreamResponse();\n }\n}\n```\n\n### Row size protection\n\nMessages approaching SQLite's 2MB row limit are automatically compacted. Large tool outputs are replaced with an LLM-friendly summary that instructs the model to suggest re-running the tool. Compacted messages include `metadata.compactedToolOutputs` so clients can detect and display this gracefully.\n\n## Custom Request Data\n\nInclude custom data with every chat request using the `body` option:\n\n```tsx\nconst { messages, sendMessage } = useAgentChat({\n agent,\n body: {\n timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,\n userId: \"abc\"\n }\n});\n\n// Or use a function for dynamic values:\nbody: () => ({ token: getAuthToken(), timestamp: Date.now() });\n```\n\nAccess these fields on the server via `options.body`:\n\n```typescript\nasync onChatMessage(onFinish, options) {\n const { timezone, userId } = options?.body ?? {};\n}\n```\n\n## API Reference\n\n### `AIChatAgent`\n\nExtends `Agent` from the `agents` package.\n\n| Property / Method | Type | Description |\n| ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------- |\n| `messages` | `ChatMessage[]` | Current conversation messages (loaded from SQLite) |\n| `maxPersistedMessages` | `number \\| undefined` | Max messages to keep in SQLite. Default: unlimited |\n| `messageConcurrency` | `MessageConcurrency` | Concurrency strategy for `sendMessage()` submits. Default: `\"queue\"` |\n| `onChatMessage(onFinish?, options?)` | Override | Handle incoming chat messages. Return a `Response`. `onFinish` is optional. |\n| `onChatResponse(result)` | Override | Called after a chat turn completes. `result` has `message`, `requestId`, `status`, `continuation` |\n| `persistMessages(messages)` | `Promise` | Manually persist messages (usually automatic) |\n| `saveMessages(messages)` | `Promise` | Persist messages and trigger `onChatMessage`. Accepts array or function. |\n| `waitUntilStable()` | `Promise` | Protected helper to wait until the conversation is fully stable |\n| `resetTurnState()` | `void` | Protected helper to abort the active turn and invalidate queued continuations |\n| `hasPendingInteraction()` | `boolean` | Protected helper to detect pending tool input or approval in assistant messages |\n\n### `useAgentChat(options)`\n\nReact hook for chat interactions. Wraps the AI SDK's `useChat` with WebSocket transport.\n\n**Options:**\n\n| Option | Type | Description |\n| ----------------------------- | --------------------------------------- | -------------------------------------------------------- |\n| `agent` | `ReturnType` | Agent connection (required) |\n| `onToolCall` | `({ toolCall, addToolOutput }) => void` | Handle client-side tool execution |\n| `autoContinueAfterToolResult` | `boolean` | Auto-continue after client tool results. Default: `true` |\n| `resume` | `boolean` | Enable stream resumption. Default: `true` |\n| `body` | `object \\| () => object` | Custom data sent with every request (see below) |\n| `prepareSendMessagesRequest` | `(options) => { body?, headers? }` | Advanced per-request customization |\n| `getInitialMessages` | `(options) => Promise` | Custom initial message loader |\n\n**Returns:**\n\n| Property | Type | Description |\n| ------------------------- | ---------------------------------- | ------------------------------------------------------- |\n| `messages` | `ChatMessage[]` | Chat messages |\n| `sendMessage` | `(message) => void` | Send a message |\n| `clearHistory` | `() => void` | Clear conversation |\n| `addToolOutput` | `({ toolCallId, output }) => void` | Provide tool output |\n| `addToolApprovalResponse` | `({ id, approved }) => void` | Approve/reject a tool |\n| `setMessages` | `(messages \\| updater) => void` | Set messages (syncs to server) |\n| `status` | `string` | `\"idle\"` \\| `\"submitted\"` \\| `\"streaming\"` \\| `\"error\"` |\n\n### Exports\n\n| Import path | What it provides |\n| --------------------------- | ------------------------------------------------------------ |\n| `@cloudflare/ai-chat` | `AIChatAgent`, `ChatMessage`, `createToolsFromClientSchemas` |\n| `@cloudflare/ai-chat/react` | `useAgentChat` |\n| `@cloudflare/ai-chat/types` | `MessageType`, `OutgoingMessage`, `IncomingMessage` |\n\n## Examples\n\n- [Resumable streaming chat](../../examples/resumable-stream-chat/) -- automatic stream resumption\n- [Human-in-the-loop guide](../../guides/human-in-the-loop/) -- tool approval with `needsApproval` + `onToolCall`\n- [Playground](../../examples/playground/) -- kitchen-sink demo of all SDK features\n\n## License\n\nMIT\n","readmeFilename":"README.md"}