Cover passing a custom message ID generator

Author: ericallam

docs/ai-chat/backend.mdx

@@ -917,6 +917,51 @@ export const myChat = chat.agent({
 });
 ```
 
+##### Custom message IDs
+
+By default, response message IDs are generated using the AI SDK's built-in `generateId`. Pass a custom `generateMessageId` function to use your own ID format (e.g. UUID-v7):
+
+```ts
+import { v7 as uuidv7 } from "uuid";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  uiMessageStreamOptions: {
+    generateMessageId: () => uuidv7(),
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+  },
+});
+```
+
+With the `.withUIMessage()` builder, set it under `streamOptions`:
+
+```ts
+import { v7 as uuidv7 } from "uuid";
+
+export const myChat = chat
+  .withUIMessage<MyChatUIMessage>({
+    streamOptions: {
+      generateMessageId: () => uuidv7(),
+      sendReasoning: true,
+    },
+  })
+  .agent({
+    id: "my-chat",
+    run: async ({ messages, signal }) => {
+      return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+    },
+  });
+```
+
+<Info>
+  The generated ID is sent to the frontend in the stream's `start` chunk, so frontend and backend
+  always reference the same ID for each message. This is important for features like tool
+  approvals, where the frontend resends an assistant message and the backend needs to match it
+  by ID in the conversation accumulator.
+</Info>
+
 ##### Per-turn overrides
 
 Override per-turn with `chat.setUIMessageStreamOptions()` — per-turn values merge with the static config (per-turn wins on conflicts). The override is cleared automatically after each turn.

docs/ai-chat/reference.mdx

@@ -433,16 +433,17 @@ Use with `useChat<Msg>({ transport })` when using [`chat.withUIMessage`](/ai-cha
 
 Options for customizing `toUIMessageStream()`. Set as static defaults via `uiMessageStreamOptions` on `chat.agent()`, or override per-turn via `chat.setUIMessageStreamOptions()`. See [Stream options](/ai-chat/backend#stream-options) for usage examples.
 
-Derived from the AI SDK's `UIMessageStreamOptions` with `onFinish`, `originalMessages`, and `generateMessageId` omitted (managed internally).
-
-| Option            | Type                              | Default           | Description                                                                                                                         |
-| ----------------- | --------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `onError`         | `(error: unknown) => string`      | Raw error message | Called on LLM errors and tool execution errors. Return a sanitized string — sent as `{ type: "error", errorText }` to the frontend. |
-| `sendReasoning`   | `boolean`                         | `true`            | Send reasoning parts to the client                                                                                                  |
-| `sendSources`     | `boolean`                         | `false`           | Send source parts to the client                                                                                                     |
-| `sendFinish`      | `boolean`                         | `true`            | Send the finish event. Set to `false` when chaining multiple `streamText` calls.                                                    |
-| `sendStart`       | `boolean`                         | `true`            | Send the message start event. Set to `false` when chaining.                                                                         |
-| `messageMetadata` | `(options: { part }) => metadata` | —                 | Extract message metadata to send to the client. Called on `start` and `finish` events.                                              |
+Derived from the AI SDK's `UIMessageStreamOptions` with `onFinish` and `originalMessages` omitted (managed internally — `onFinish` for response capture, `originalMessages` for cross-turn message ID reuse).
+
+| Option              | Type                              | Default              | Description                                                                                                                         |
+| ------------------- | --------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `onError`           | `(error: unknown) => string`      | Raw error message    | Called on LLM errors and tool execution errors. Return a sanitized string — sent as `{ type: "error", errorText }` to the frontend. |
+| `sendReasoning`     | `boolean`                         | `true`               | Send reasoning parts to the client                                                                                                  |
+| `sendSources`       | `boolean`                         | `false`              | Send source parts to the client                                                                                                     |
+| `sendFinish`        | `boolean`                         | `true`               | Send the finish event. Set to `false` when chaining multiple `streamText` calls.                                                    |
+| `sendStart`         | `boolean`                         | `true`               | Send the message start event. Set to `false` when chaining.                                                                         |
+| `messageMetadata`   | `(options: { part }) => metadata` | —                    | Extract message metadata to send to the client. Called on `start` and `finish` events.                                              |
+| `generateMessageId` | `() => string`                    | AI SDK's `generateId` | Custom message ID generator for response messages (e.g. UUID-v7). IDs are shared between frontend and backend via the stream's `start` chunk. |
 
 ## TriggerChatTransport options