ai 6.0.30 → 6.0.32

package/docs/07-reference/02-ai-sdk-ui/50-direct-chat-transport.mdx

@@ -0,0 +1,333 @@
+---
+title: DirectChatTransport
+description: API Reference for the DirectChatTransport class.
+---
+
+# `DirectChatTransport`
+
+A transport that directly communicates with an [Agent](/docs/reference/ai-sdk-core/agent) in-process, without going through HTTP. This is useful for:
+
+- Server-side rendering scenarios
+- Testing without network
+- Single-process applications
+
+Unlike `DefaultChatTransport` which sends HTTP requests to an API endpoint, `DirectChatTransport` invokes the agent's `stream()` method directly and converts the result to a UI message stream.
+
+```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.',
+});
+
+export default function Chat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DirectChatTransport({ agent }),
+  });
+
+  // ... render chat UI
+}
+```
+
+## Import
+
+<Snippet text={`import { DirectChatTransport } from "ai"`} prompt={false} />
+
+## Constructor
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'agent',
+      type: 'Agent',
+      isRequired: true,
+      description:
+        'The Agent instance to use for generating responses. The agent will be called with `stream()` for each message.',
+    },
+    {
+      name: 'options',
+      type: 'CALL_OPTIONS',
+      isOptional: true,
+      description:
+        'Options to pass to the agent when calling it. These are agent-specific options defined when creating the agent.',
+    },
+    {
+      name: 'originalMessages',
+      type: 'UIMessage[]',
+      isOptional: true,
+      description:
+        'The original messages. If provided, persistence mode is assumed, and a message ID is provided for the response message.',
+    },
+    {
+      name: 'generateMessageId',
+      type: 'IdGenerator',
+      isOptional: true,
+      description:
+        'Generate a message ID for the response message. If not provided, no message ID will be set for the response message.',
+    },
+    {
+      name: 'messageMetadata',
+      type: '(options: { part: TextStreamPart }) => METADATA | undefined',
+      isOptional: true,
+      description:
+        'Extracts message metadata that will be sent to the client. Called on `start` and `finish` events.',
+    },
+    {
+      name: 'sendReasoning',
+      type: 'boolean',
+      isOptional: true,
+      description: 'Send reasoning parts to the client. Defaults to true.',
+    },
+    {
+      name: 'sendSources',
+      type: 'boolean',
+      isOptional: true,
+      description: 'Send source parts to the client. Defaults to false.',
+    },
+    {
+      name: 'sendFinish',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Send the finish event to the client. Set to false if you are using additional streamText calls that send additional data. Defaults to true.',
+    },
+    {
+      name: 'sendStart',
+      type: 'boolean',
+      isOptional: true,
+      description:
+        'Send the message start event to the client. Set to false if you are using additional streamText calls and the message start event has already been sent. Defaults to true.',
+    },
+    {
+      name: 'onError',
+      type: '(error: unknown) => string',
+      isOptional: true,
+      description:
+        "Process an error, e.g. to log it. Defaults to `() => 'An error occurred.'`. Return the error message to include in the data stream.",
+    },
+  ]}
+/>
+
+## Methods
+
+### `sendMessages()`
+
+Sends messages to the agent and returns a streaming response. This method validates and converts UI messages to model messages, calls the agent's `stream()` method, and returns the result as a UI message stream.
+
+```ts
+const stream = await transport.sendMessages({
+  chatId: 'chat-123',
+  trigger: 'submit-message',
+  messages: [...],
+  abortSignal: controller.signal,
+});
+```
+
+<PropertiesTable
+  content={[
+    {
+      name: 'chatId',
+      type: 'string',
+      description: 'Unique identifier for the chat session.',
+    },
+    {
+      name: 'trigger',
+      type: "'submit-message' | 'regenerate-message'",
+      description:
+        'The type of message submission - either new message or regeneration.',
+    },
+    {
+      name: 'messageId',
+      type: 'string | undefined',
+      description:
+        'ID of the message to regenerate, or undefined for new messages.',
+    },
+    {
+      name: 'messages',
+      type: 'UIMessage[]',
+      description:
+        'Array of UI messages representing the conversation history.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal | undefined',
+      description: 'Signal to abort the request if needed.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string> | Headers',
+      isOptional: true,
+      description: 'Additional headers (ignored by DirectChatTransport).',
+    },
+    {
+      name: 'body',
+      type: 'object',
+      isOptional: true,
+      description:
+        'Additional body properties (ignored by DirectChatTransport).',
+    },
+    {
+      name: 'metadata',
+      type: 'unknown',
+      isOptional: true,
+      description: 'Custom metadata (ignored by DirectChatTransport).',
+    },
+  ]}
+/>
+
+#### Returns
+
+Returns a `Promise<ReadableStream<UIMessageChunk>>` - a stream of UI message chunks that can be processed by the chat UI.
+
+### `reconnectToStream()`
+
+Direct transport does not support reconnection since there is no persistent server-side stream to reconnect to.
+
+#### Returns
+
+Always returns `Promise<null>`.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport, ToolLoopAgent } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const agent = new ToolLoopAgent({
+  model: openai('gpt-4o'),
+  instructions: 'You are a helpful assistant.',
+});
+
+export default function Chat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DirectChatTransport({ agent }),
+  });
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <span key={index}>{part.text}</span> : null,
+          )}
+        </div>
+      ))}
+      <button onClick={() => sendMessage({ text: 'Hello!' })}>Send</button>
+    </div>
+  );
+}
+```
+
+### With Agent Tools
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport, ToolLoopAgent, tool } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const weatherTool = tool({
+  description: 'Get the current weather',
+  parameters: z.object({
+    location: z.string().describe('The city and state'),
+  }),
+  execute: async ({ location }) => {
+    return `The weather in ${location} is sunny and 72°F.`;
+  },
+});
+
+const agent = new ToolLoopAgent({
+  model: openai('gpt-4o'),
+  instructions: 'You are a helpful assistant with access to weather data.',
+  tools: { weather: weatherTool },
+});
+
+export default function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DirectChatTransport({ agent }),
+  });
+
+  // ... render chat UI with tool results
+}
+```
+
+### With Custom Agent Options
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport, ToolLoopAgent } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const agent = new ToolLoopAgent<{ userId: string }>({
+  model: openai('gpt-4o'),
+  prepareCall: ({ options, ...rest }) => ({
+    ...rest,
+    providerOptions: {
+      openai: { user: options.userId },
+    },
+  }),
+});
+
+export default function Chat({ userId }: { userId: string }) {
+  const { messages, sendMessage } = useChat({
+    transport: new DirectChatTransport({
+      agent,
+      options: { userId },
+    }),
+  });
+
+  // ... render chat UI
+}
+```
+
+### With Reasoning
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DirectChatTransport, ToolLoopAgent } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const agent = new ToolLoopAgent({
+  model: openai('o1-preview'),
+});
+
+export default function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DirectChatTransport({
+      agent,
+      sendReasoning: true,
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            if (part.type === 'text') {
+              return <p key={index}>{part.text}</p>;
+            }
+            if (part.type === 'reasoning') {
+              return (
+                <pre key={index} style={{ opacity: 0.6 }}>
+                  {part.text}
+                </pre>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```

package/docs/07-reference/02-ai-sdk-ui/index.mdx

@@ -0,0 +1,89 @@
+---
+title: AI SDK UI
+description: Reference documentation for the AI SDK UI
+collapsed: true
+---
+
+# AI SDK UI
+
+[AI SDK UI](/docs/ai-sdk-ui) is designed to help you build interactive chat, completion, and assistant applications with ease.
+It is framework-agnostic toolkit, streamlining the integration of advanced AI functionalities into your applications.
+
+AI SDK UI contains the following hooks:
+
+<IndexCards
+  cards={[
+    {
+      title: 'useChat',
+      description:
+        'Use a hook to interact with language models in a chat interface.',
+      href: '/docs/reference/ai-sdk-ui/use-chat',
+    },
+    {
+      title: 'useCompletion',
+      description:
+        'Use a hook to interact with language models in a completion interface.',
+      href: '/docs/reference/ai-sdk-ui/use-completion',
+    },
+    {
+      title: 'useObject',
+      description: 'Use a hook for consuming a streamed JSON objects.',
+      href: '/docs/reference/ai-sdk-ui/use-object',
+    },
+    {
+      title: 'convertToModelMessages',
+      description:
+        'Convert useChat messages to ModelMessages for AI functions.',
+      href: '/docs/reference/ai-sdk-ui/convert-to-model-messages',
+    },
+    {
+      title: 'pruneMessages',
+      description: 'Prunes model messages from a list of model messages.',
+      href: '/docs/reference/ai-sdk-ui/prune-messages',
+    },
+    {
+      title: 'createUIMessageStream',
+      description:
+        'Create a UI message stream to stream additional data to the client.',
+      href: '/docs/reference/ai-sdk-ui/create-ui-message-stream',
+    },
+    {
+      title: 'createUIMessageStreamResponse',
+      description:
+        'Create a response object to stream UI messages to the client.',
+      href: '/docs/reference/ai-sdk-ui/create-ui-message-stream-response',
+    },
+    {
+      title: 'pipeUIMessageStreamToResponse',
+      description:
+        'Pipe a UI message stream to a Node.js ServerResponse object.',
+      href: '/docs/reference/ai-sdk-ui/pipe-ui-message-stream-to-response',
+    },
+    {
+      title: 'readUIMessageStream',
+      description:
+        'Transform a stream of UIMessageChunk objects into an AsyncIterableStream of UIMessage objects.',
+      href: '/docs/reference/ai-sdk-ui/read-ui-message-stream',
+    },
+  ]}
+/>
+
+## UI Framework Support
+
+AI SDK UI supports the following frameworks: [React](https://react.dev/), [Svelte](https://svelte.dev/), [Vue.js](https://vuejs.org/),
+[Angular](https://angular.dev/), and [SolidJS](https://www.solidjs.com/).
+
+Here is a comparison of the supported functions across these frameworks:
+
+|                                                                 | [useChat](/docs/reference/ai-sdk-ui/use-chat) | [useCompletion](/docs/reference/ai-sdk-ui/use-completion) | [useObject](/docs/reference/ai-sdk-ui/use-object) |
+| --------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------- |
+| React `@ai-sdk/react`                                           | <Check size={18} />                           | <Check size={18} />                                       | <Check size={18} />                               |
+| Vue.js `@ai-sdk/vue`                                            | <Check size={18} />                           | <Check size={18} />                                       | <Check size={18} />                               |
+| Svelte `@ai-sdk/svelte`                                         | <Check size={18} /> Chat                      | <Check size={18} /> Completion                            | <Check size={18} /> StructuredObject              |
+| Angular `@ai-sdk/angular`                                       | <Check size={18} /> Chat                      | <Check size={18} /> Completion                            | <Check size={18} /> StructuredObject              |
+| [SolidJS](https://github.com/kodehort/ai-sdk-solid) (community) | <Check size={18} />                           | <Check size={18} />                                       | <Check size={18} />                               |
+
+<Note>
+  [Contributions](https://github.com/vercel/ai/blob/main/CONTRIBUTING.md) are
+  welcome to implement missing features for non-React frameworks.
+</Note>