ai 6.0.31 → 6.0.33

package/docs/04-ai-sdk-ui/21-transport.mdx

@@ -0,0 +1,174 @@
+---
+title: Transport
+description: Learn how to use custom transports with useChat.
+---
+
+# Transport
+
+The `useChat` transport system provides fine-grained control over how messages are sent to your API endpoints and how responses are processed. This is particularly useful for alternative communication protocols like WebSockets, custom authentication patterns, or specialized backend integrations.
+
+## Default Transport
+
+By default, `useChat` uses HTTP POST requests to send messages to `/api/chat`:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+
+// Uses default HTTP transport
+const { messages, sendMessage } = useChat();
+```
+
+This is equivalent to:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+  }),
+});
+```
+
+## Custom Transport Configuration
+
+Configure the default transport with custom options:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/custom-chat',
+    headers: {
+      Authorization: 'Bearer your-token',
+      'X-API-Version': '2024-01',
+    },
+    credentials: 'include',
+  }),
+});
+```
+
+### Dynamic Configuration
+
+You can also provide functions that return configuration values. This is useful for authentication tokens that need to be refreshed, or for configuration that depends on runtime conditions:
+
+```tsx
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    headers: () => ({
+      Authorization: `Bearer ${getAuthToken()}`,
+      'X-User-ID': getCurrentUserId(),
+    }),
+    body: () => ({
+      sessionId: getCurrentSessionId(),
+      preferences: getUserPreferences(),
+    }),
+    credentials: () => 'include',
+  }),
+});
+```
+
+### Request Transformation
+
+Transform requests before sending to your API:
+
+```tsx
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    prepareSendMessagesRequest: ({ id, messages, trigger, messageId }) => {
+      return {
+        headers: {
+          'X-Session-ID': id,
+        },
+        body: {
+          messages: messages.slice(-10), // Only send last 10 messages
+          trigger,
+          messageId,
+        },
+      };
+    },
+  }),
+});
+```
+
+## Direct Agent Transport
+
+For scenarios where you want to communicate directly with an [Agent](/docs/reference/ai-sdk-core/agent) without going through HTTP, you can use `DirectChatTransport`. This transport invokes the agent's `stream()` method directly in-process.
+
+This is useful for:
+
+- **Server-side rendering**: Run the agent on the server without an API endpoint
+- **Testing**: Test chat functionality without network requests
+- **Single-process applications**: Desktop or CLI apps where client and agent run together
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport, ToolLoopAgent } from 'ai';
+__PROVIDER_IMPORT__;
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  instructions: 'You are a helpful assistant.',
+  tools: {
+    weather: weatherTool,
+  },
+});
+
+const { messages, sendMessage } = useChat({
+  transport: new DirectChatTransport({ agent }),
+});
+```
+
+### How It Works
+
+Unlike `DefaultChatTransport` which sends HTTP requests:
+
+1. `DirectChatTransport` validates incoming UI messages
+2. Converts them to model messages using `convertToModelMessages`
+3. Calls the agent's `stream()` method directly
+4. Returns the result as a UI message stream via `toUIMessageStream()`
+
+### Configuration Options
+
+You can pass additional options to customize the stream output:
+
+```tsx
+const transport = new DirectChatTransport({
+  agent,
+  // Pass options to the agent
+  options: { customOption: 'value' },
+  // Configure what's sent to the client
+  sendReasoning: true,
+  sendSources: true,
+});
+```
+
+<Note>
+  `DirectChatTransport` does not support stream reconnection since there is no
+  persistent server-side stream. The `reconnectToStream()` method always returns
+  `null`.
+</Note>
+
+For complete API details, see the [DirectChatTransport reference](/docs/reference/ai-sdk-ui/direct-chat-transport).
+
+## Building Custom Transports
+
+To understand how to build your own transport, refer to the source code of the default implementation:
+
+- **[DefaultChatTransport](https://github.com/vercel/ai/blob/main/packages/ai/src/ui/default-chat-transport.ts)** - The complete default HTTP transport implementation
+- **[HttpChatTransport](https://github.com/vercel/ai/blob/main/packages/ai/src/ui/http-chat-transport.ts)** - Base HTTP transport with request handling
+- **[ChatTransport Interface](https://github.com/vercel/ai/blob/main/packages/ai/src/ui/chat-transport.ts)** - The transport interface you need to implement
+
+These implementations show you exactly how to:
+
+- Handle the `sendMessages` method
+- Process UI message streams
+- Transform requests and responses
+- Handle errors and connection management
+
+The transport system gives you complete control over how your chat application communicates, enabling integration with any backend protocol or service.

package/docs/04-ai-sdk-ui/24-reading-ui-message-streams.mdx

@@ -0,0 +1,104 @@
+---
+title: Reading UIMessage Streams
+description: Learn how to read UIMessage streams.
+---
+
+# Reading UI Message Streams
+
+`UIMessage` streams are useful outside of traditional chat use cases. You can consume them for terminal UIs, custom stream processing on the client, or React Server Components (RSC).
+
+The `readUIMessageStream` helper transforms a stream of `UIMessageChunk` objects into an `AsyncIterableStream` of `UIMessage` objects, allowing you to process messages as they're being constructed.
+
+## Basic Usage
+
+```tsx
+import { readUIMessageStream, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+async function main() {
+  const result = streamText({
+    model: __MODEL__,
+    prompt: 'Write a short story about a robot.',
+  });
+
+  for await (const uiMessage of readUIMessageStream({
+    stream: result.toUIMessageStream(),
+  })) {
+    console.log('Current message state:', uiMessage);
+  }
+}
+```
+
+## Tool Calls Integration
+
+Handle streaming responses that include tool calls:
+
+```tsx
+import { readUIMessageStream, streamText, tool } from 'ai';
+__PROVIDER_IMPORT__;
+import { z } from 'zod';
+
+async function handleToolCalls() {
+  const result = streamText({
+    model: __MODEL__,
+    tools: {
+      weather: tool({
+        description: 'Get the weather in a location',
+        inputSchema: z.object({
+          location: z.string().describe('The location to get the weather for'),
+        }),
+        execute: ({ location }) => ({
+          location,
+          temperature: 72 + Math.floor(Math.random() * 21) - 10,
+        }),
+      }),
+    },
+    prompt: 'What is the weather in Tokyo?',
+  });
+
+  for await (const uiMessage of readUIMessageStream({
+    stream: result.toUIMessageStream(),
+  })) {
+    // Handle different part types
+    uiMessage.parts.forEach(part => {
+      switch (part.type) {
+        case 'text':
+          console.log('Text:', part.text);
+          break;
+        case 'tool-call':
+          console.log('Tool called:', part.toolName, 'with args:', part.args);
+          break;
+        case 'tool-result':
+          console.log('Tool result:', part.result);
+          break;
+      }
+    });
+  }
+}
+```
+
+## Resuming Conversations
+
+Resume streaming from a previous message state:
+
+```tsx
+import { readUIMessageStream, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+async function resumeConversation(lastMessage: UIMessage) {
+  const result = streamText({
+    model: __MODEL__,
+    messages: [
+      { role: 'user', content: 'Continue our previous conversation.' },
+    ],
+  });
+
+  // Resume from the last message
+  for await (const uiMessage of readUIMessageStream({
+    stream: result.toUIMessageStream(),
+    message: lastMessage, // Resume from this message
+  })) {
+    console.log('Resumed message:', uiMessage);
+  }
+}
+```

package/docs/04-ai-sdk-ui/25-message-metadata.mdx

@@ -0,0 +1,152 @@
+---
+title: Message Metadata
+description: Learn how to attach and use metadata with messages in AI SDK UI
+---
+
+# Message Metadata
+
+Message metadata allows you to attach custom information to messages at the message level. This is useful for tracking timestamps, model information, token usage, user context, and other message-level data.
+
+## Overview
+
+Message metadata differs from [data parts](/docs/ai-sdk-ui/streaming-data) in that it's attached at the message level rather than being part of the message content. While data parts are ideal for dynamic content that forms part of the message, metadata is perfect for information about the message itself.
+
+## Getting Started
+
+Here's a simple example of using message metadata to track timestamps and model information:
+
+### Defining Metadata Types
+
+First, define your metadata type for type safety:
+
+```tsx filename="app/types.ts"
+import { UIMessage } from 'ai';
+import { z } from 'zod';
+
+// Define your metadata schema
+export const messageMetadataSchema = z.object({
+  createdAt: z.number().optional(),
+  model: z.string().optional(),
+  totalTokens: z.number().optional(),
+});
+
+export type MessageMetadata = z.infer<typeof messageMetadataSchema>;
+
+// Create a typed UIMessage
+export type MyUIMessage = UIMessage<MessageMetadata>;
+```
+
+### Sending Metadata from the Server
+
+Use the `messageMetadata` callback in `toUIMessageStreamResponse` to send metadata at different streaming stages:
+
+```ts filename="app/api/chat/route.ts" highlight="11-20"
+import { convertToModelMessages, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+import type { MyUIMessage } from '@/types';
+
+export async function POST(req: Request) {
+  const { messages }: { messages: MyUIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages, // pass this in for type-safe return objects
+    messageMetadata: ({ part }) => {
+      // Send metadata when streaming starts
+      if (part.type === 'start') {
+        return {
+          createdAt: Date.now(),
+          model: 'your-model-id',
+        };
+      }
+
+      // Send additional metadata when streaming completes
+      if (part.type === 'finish') {
+        return {
+          totalTokens: part.totalUsage.totalTokens,
+        };
+      }
+    },
+  });
+}
+```
+
+<Note>
+  To enable type-safe metadata return object in `messageMetadata`, pass in the
+  `originalMessages` parameter typed to your UIMessage type.
+</Note>
+
+### Accessing Metadata on the Client
+
+Access metadata through the `message.metadata` property:
+
+```tsx filename="app/page.tsx" highlight="8,18-23"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import type { MyUIMessage } from '@/types';
+
+export default function Chat() {
+  const { messages } = useChat<MyUIMessage>({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          <div>
+            {message.role === 'user' ? 'User: ' : 'AI: '}
+            {message.metadata?.createdAt && (
+              <span className="text-sm text-gray-500">
+                {new Date(message.metadata.createdAt).toLocaleTimeString()}
+              </span>
+            )}
+          </div>
+
+          {/* Render message content */}
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <div key={index}>{part.text}</div> : null,
+          )}
+
+          {/* Display additional metadata */}
+          {message.metadata?.totalTokens && (
+            <div className="text-xs text-gray-400">
+              {message.metadata.totalTokens} tokens
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+<Note>
+  For streaming arbitrary data that changes during generation, consider using
+  [data parts](/docs/ai-sdk-ui/streaming-data) instead.
+</Note>
+
+## Common Use Cases
+
+Message metadata is ideal for:
+
+- **Timestamps**: When messages were created or completed
+- **Model Information**: Which AI model was used
+- **Token Usage**: Track costs and usage limits
+- **User Context**: User IDs, session information
+- **Performance Metrics**: Generation time, time to first token
+- **Quality Indicators**: Finish reason, confidence scores
+
+## See Also
+
+- [Chatbot Guide](/docs/ai-sdk-ui/chatbot#message-metadata) - Message metadata in the context of building chatbots
+- [Streaming Data](/docs/ai-sdk-ui/streaming-data#message-metadata-vs-data-parts) - Comparison with data parts
+- [UIMessage Reference](/docs/reference/ai-sdk-core/ui-message) - Complete UIMessage type reference