@fondation-io/ai 7.0.0-beta.45

package/docs/04-ai-sdk-ui/03-chatbot-message-persistence.mdx

@@ -0,0 +1,534 @@
+---
+title: Chatbot Message Persistence
+description: Learn how to store and load chat messages in a chatbot.
+---
+
+# Chatbot Message Persistence
+
+Being able to store and load chat messages is crucial for most AI chatbots.
+In this guide, we'll show how to implement message persistence with `useChat` and `streamText`.
+
+<Note>
+  This guide does not cover authorization, error handling, or other real-world
+  considerations. It is intended to be a simple example of how to implement
+  message persistence.
+</Note>
+
+## Starting a new chat
+
+When the user navigates to the chat page without providing a chat ID,
+we need to create a new chat and redirect to the chat page with the new chat ID.
+
+```tsx filename="app/chat/page.tsx"
+import { redirect } from 'next/navigation';
+import { createChat } from '@util/chat-store';
+
+export default async function Page() {
+  const id = await createChat(); // create a new chat
+  redirect(`/chat/${id}`); // redirect to chat page, see below
+}
+```
+
+Our example chat store implementation uses files to store the chat messages.
+In a real-world application, you would use a database or a cloud storage service,
+and get the chat ID from the database.
+That being said, the function interfaces are designed to be easily replaced with other implementations.
+
+```tsx filename="util/chat-store.ts"
+import { generateId } from 'ai';
+import { existsSync, mkdirSync } from 'fs';
+import { writeFile } from 'fs/promises';
+import path from 'path';
+
+export async function createChat(): Promise<string> {
+  const id = generateId(); // generate a unique chat ID
+  await writeFile(getChatFile(id), '[]'); // create an empty chat file
+  return id;
+}
+
+function getChatFile(id: string): string {
+  const chatDir = path.join(process.cwd(), '.chats');
+  if (!existsSync(chatDir)) mkdirSync(chatDir, { recursive: true });
+  return path.join(chatDir, `${id}.json`);
+}
+```
+
+## Loading an existing chat
+
+When the user navigates to the chat page with a chat ID, we need to load the chat messages from storage.
+
+The `loadChat` function in our file-based chat store is implemented as follows:
+
+```tsx filename="util/chat-store.ts"
+import { UIMessage } from 'ai';
+import { readFile } from 'fs/promises';
+
+export async function loadChat(id: string): Promise<UIMessage[]> {
+  return JSON.parse(await readFile(getChatFile(id), 'utf8'));
+}
+
+// ... rest of the file
+```
+
+## Validating messages on the server
+
+When processing messages on the server that contain tool calls, custom metadata, or data parts, you should validate them using `validateUIMessages` before sending them to the model.
+
+### Validation with tools
+
+When your messages include tool calls, validate them against your tool definitions:
+
+```tsx filename="app/api/chat/route.ts" highlight="7-25,32-37"
+import {
+  convertToModelMessages,
+  streamText,
+  UIMessage,
+  validateUIMessages,
+  tool,
+} from 'ai';
+import { z } from 'zod';
+import { loadChat, saveChat } from '@util/chat-store';
+import { dataPartsSchema, metadataSchema } from '@util/schemas';
+
+// Define your tools
+const tools = {
+  weather: tool({
+    description: 'Get weather information',
+    parameters: z.object({
+      location: z.string(),
+      units: z.enum(['celsius', 'fahrenheit']),
+    }),
+    execute: async ({ location, units }) => {
+      /* tool implementation */
+    },
+  }),
+  // other tools
+};
+
+export async function POST(req: Request) {
+  const { message, id } = await req.json();
+
+  // Load previous messages from database
+  const previousMessages = await loadChat(id);
+
+  // Append new message to previousMessages messages
+  const messages = [...previousMessages, message];
+
+  // Validate loaded messages against
+  // tools, data parts schema, and metadata schema
+  const validatedMessages = await validateUIMessages({
+    messages,
+    tools, // Ensures tool calls in messages match current schemas
+    dataPartsSchema,
+    metadataSchema,
+  });
+
+  const result = streamText({
+    model: 'openai/gpt-5-mini',
+    messages: convertToModelMessages(validatedMessages),
+    tools,
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages,
+    onFinish: ({ messages }) => {
+      saveChat({ chatId: id, messages });
+    },
+  });
+}
+```
+
+### Handling validation errors
+
+Handle validation errors gracefully when messages from the database don't match current schemas:
+
+```tsx filename="app/api/chat/route.ts" highlight="3,10-24"
+import {
+  convertToModelMessages,
+  streamText,
+  validateUIMessages,
+  TypeValidationError,
+} from 'ai';
+import { type MyUIMessage } from '@/types';
+
+export async function POST(req: Request) {
+  const { message, id } = await req.json();
+
+  // Load and validate messages from database
+  let validatedMessages: MyUIMessage[];
+
+  try {
+    const previousMessages = await loadMessagesFromDB(id);
+    validatedMessages = await validateUIMessages({
+      // append the new message to the previous messages:
+      messages: [...previousMessages, message],
+      tools,
+      metadataSchema,
+    });
+  } catch (error) {
+    if (error instanceof TypeValidationError) {
+      // Log validation error for monitoring
+      console.error('Database messages validation failed:', error);
+      // Could implement message migration or filtering here
+      // For now, start with empty history
+      validatedMessages = [];
+    } else {
+      throw error;
+    }
+  }
+
+  // Continue with validated messages...
+}
+```
+
+## Displaying the chat
+
+Once messages are loaded from storage, you can display them in your chat UI. Here's how to set up the page component and the chat display:
+
+```tsx filename="app/chat/[id]/page.tsx"
+import { loadChat } from '@util/chat-store';
+import Chat from '@ui/chat';
+
+export default async function Page(props: { params: Promise<{ id: string }> }) {
+  const { id } = await props.params;
+  const messages = await loadChat(id);
+  return <Chat id={id} initialMessages={messages} />;
+}
+```
+
+The chat component uses the `useChat` hook to manage the conversation:
+
+```tsx filename="ui/chat.tsx" highlight="10-16"
+'use client';
+
+import { UIMessage, useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import { useState } from 'react';
+
+export default function Chat({
+  id,
+  initialMessages,
+}: { id?: string | undefined; initialMessages?: UIMessage[] } = {}) {
+  const [input, setInput] = useState('');
+  const { sendMessage, messages } = useChat({
+    id, // use the provided chat ID
+    messages: initialMessages, // load initial messages
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (input.trim()) {
+      sendMessage({ text: input });
+      setInput('');
+    }
+  };
+
+  // simplified rendering code, extend as needed:
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          {m.role === 'user' ? 'User: ' : 'AI: '}
+          {m.parts
+            .map(part => (part.type === 'text' ? part.text : ''))
+            .join('')}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Storing messages
+
+`useChat` sends the chat id and the messages to the backend.
+
+<Note>
+  The `useChat` message format is different from the `ModelMessage` format. The
+  `useChat` message format is designed for frontend display, and contains
+  additional fields such as `id` and `createdAt`. We recommend storing the
+  messages in the `useChat` message format.
+
+When loading messages from storage that contain tools, metadata, or custom data
+parts, validate them using `validateUIMessages` before processing (see the
+[validation section](#validating-messages-from-database) above).
+
+</Note>
+
+Storing messages is done in the `onFinish` callback of the `toUIMessageStreamResponse` function.
+`onFinish` receives the complete messages including the new AI response as `UIMessage[]`.
+
+```tsx filename="app/api/chat/route.ts" highlight="6,11-17"
+import { openai } from '@ai-sdk/openai';
+import { saveChat } from '@util/chat-store';
+import { convertToModelMessages, streamText, UIMessage } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages, chatId }: { messages: UIMessage[]; chatId: string } =
+    await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-5-mini',
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages,
+    onFinish: ({ messages }) => {
+      saveChat({ chatId, messages });
+    },
+  });
+}
+```
+
+The actual storage of the messages is done in the `saveChat` function, which in
+our file-based chat store is implemented as follows:
+
+```tsx filename="util/chat-store.ts"
+import { UIMessage } from 'ai';
+import { writeFile } from 'fs/promises';
+
+export async function saveChat({
+  chatId,
+  messages,
+}: {
+  chatId: string;
+  messages: UIMessage[];
+}): Promise<void> {
+  const content = JSON.stringify(messages, null, 2);
+  await writeFile(getChatFile(chatId), content);
+}
+
+// ... rest of the file
+```
+
+## Message IDs
+
+In addition to a chat ID, each message has an ID.
+You can use this message ID to e.g. manipulate individual messages.
+
+### Client-side vs Server-side ID Generation
+
+By default, message IDs are generated client-side:
+
+- User message IDs are generated by the `useChat` hook on the client
+- AI response message IDs are generated by `streamText` on the server
+
+For applications without persistence, client-side ID generation works perfectly.
+However, **for persistence, you need server-side generated IDs** to ensure consistency across sessions and prevent ID conflicts when messages are stored and retrieved.
+
+### Setting Up Server-side ID Generation
+
+When implementing persistence, you have two options for generating server-side IDs:
+
+1. **Using `generateMessageId` in `toUIMessageStreamResponse`**
+2. **Setting IDs in your start message part with `createUIMessageStream`**
+
+#### Option 1: Using `generateMessageId` in `toUIMessageStreamResponse`
+
+You can control the ID format by providing ID generators using [`createIdGenerator()`](/docs/reference/ai-sdk-core/create-id-generator):
+
+```tsx filename="app/api/chat/route.ts" highlight="7-11"
+import { createIdGenerator, streamText } from 'ai';
+
+export async function POST(req: Request) {
+  // ...
+  const result = streamText({
+    // ...
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages,
+    // Generate consistent server-side IDs for persistence:
+    generateMessageId: createIdGenerator({
+      prefix: 'msg',
+      size: 16,
+    }),
+    onFinish: ({ messages }) => {
+      saveChat({ chatId, messages });
+    },
+  });
+}
+```
+
+#### Option 2: Setting IDs with `createUIMessageStream`
+
+Alternatively, you can use `createUIMessageStream` to control the message ID by writing a start message part:
+
+```tsx filename="app/api/chat/route.ts" highlight="8-18"
+import {
+  generateId,
+  streamText,
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+} from 'ai';
+
+export async function POST(req: Request) {
+  const { messages, chatId } = await req.json();
+
+  const stream = createUIMessageStream({
+    execute: ({ writer }) => {
+      // Write start message part with custom ID
+      writer.write({
+        type: 'start',
+        messageId: generateId(), // Generate server-side ID for persistence
+      });
+
+      const result = streamText({
+        model: 'openai/gpt-5-mini',
+        messages: await convertToModelMessages(messages),
+      });
+
+      writer.merge(result.toUIMessageStream({ sendStart: false })); // omit start message part
+    },
+    originalMessages: messages,
+    onFinish: ({ responseMessage }) => {
+      // save your chat here
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+<Note>
+  For client-side applications that don't require persistence, you can still customize client-side ID generation:
+
+```tsx filename="ui/chat.tsx"
+import { createIdGenerator } from 'ai';
+import { useChat } from '@ai-sdk/react';
+
+const { ... } = useChat({
+  generateId: createIdGenerator({
+    prefix: 'msgc',
+    size: 16,
+  }),
+  // ...
+});
+```
+
+</Note>
+
+## Sending only the last message
+
+Once you have implemented message persistence, you might want to send only the last message to the server.
+This reduces the amount of data sent to the server on each request and can improve performance.
+
+To achieve this, you can provide a `prepareSendMessagesRequest` function to the transport.
+This function receives the messages and the chat ID, and returns the request body to be sent to the server.
+
+```tsx filename="ui/chat.tsx" highlight="7-12"
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const {
+  // ...
+} = useChat({
+  // ...
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    // only send the last message to the server:
+    prepareSendMessagesRequest({ messages, id }) {
+      return { body: { message: messages[messages.length - 1], id } };
+    },
+  }),
+});
+```
+
+On the server, you can then load the previous messages and append the new message to the previous messages. If your messages contain tools, metadata, or custom data parts, you should validate them:
+
+```tsx filename="app/api/chat/route.ts" highlight="2-11,14-18"
+import { convertToModelMessages, UIMessage, validateUIMessages } from 'ai';
+// import your tools and schemas
+
+export async function POST(req: Request) {
+  // get the last message from the client:
+  const { message, id } = await req.json();
+
+  // load the previous messages from the server:
+  const previousMessages = await loadChat(id);
+
+  // validate messages if they contain tools, metadata, or data parts:
+  const validatedMessages = await validateUIMessages({
+    // append the new message to the previous messages:
+    messages: [...previousMessages, message],
+    tools, // if using tools
+    metadataSchema, // if using custom metadata
+    dataSchemas, // if using custom data parts
+  });
+
+  const result = streamText({
+    // ...
+    messages: convertToModelMessages(validatedMessages),
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: validatedMessages,
+    onFinish: ({ messages }) => {
+      saveChat({ chatId: id, messages });
+    },
+  });
+}
+```
+
+## Handling client disconnects
+
+By default, the AI SDK `streamText` function uses backpressure to the language model provider to prevent
+the consumption of tokens that are not yet requested.
+
+However, this means that when the client disconnects, e.g. by closing the browser tab or because of a network issue,
+the stream from the LLM will be aborted and the conversation may end up in a broken state.
+
+Assuming that you have a [storage solution](#storing-messages) in place, you can use the `consumeStream` method to consume the stream on the backend,
+and then save the result as usual.
+`consumeStream` effectively removes the backpressure,
+meaning that the result is stored even when the client has already disconnected.
+
+```tsx filename="app/api/chat/route.ts" highlight="19-21"
+import { convertToModelMessages, streamText, UIMessage } from 'ai';
+import { saveChat } from '@util/chat-store';
+
+export async function POST(req: Request) {
+  const { messages, chatId }: { messages: UIMessage[]; chatId: string } =
+    await req.json();
+
+  const result = streamText({
+    model,
+    messages: await convertToModelMessages(messages),
+  });
+
+  // consume the stream to ensure it runs to completion & triggers onFinish
+  // even when the client response is aborted:
+  result.consumeStream(); // no await
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages,
+    onFinish: ({ messages }) => {
+      saveChat({ chatId, messages });
+    },
+  });
+}
+```
+
+When the client reloads the page after a disconnect, the chat will be restored from the storage solution.
+
+<Note>
+  In production applications, you would also track the state of the request (in
+  progress, complete) in your stored messages and use it on the client to cover
+  the case where the client reloads the page after a disconnection, but the
+  streaming is not yet complete.
+</Note>
+
+For more robust handling of disconnects, you may want to add resumability on disconnects. Check out the [Chatbot Resume Streams](/docs/ai-sdk-ui/chatbot-resume-streams) documentation to learn more.