@assistant-ui/mcp-docs-server 0.1.30 → 0.1.31

package/.docs/raw/docs/runtimes/ai-sdk/v6.mdx

@@ -3,37 +3,75 @@ title: AI SDK v6
 description: Integrate Vercel AI SDK v6 with assistant-ui for streaming chat.
 ---
 
+Current-version integration. Requires `ai@^6` and `@ai-sdk/react@^3`. For older versions see the [overview](/docs/runtimes/ai-sdk).
 
-## Overview
+## Quickstart
 
-Integration with the Vercel AI SDK v6 using the `useChatRuntime` hook from `@assistant-ui/react-ai-sdk`.
+<Steps>
+<Step>
 
-## Getting Started
+### Create a project
 
-<Steps>
-  <Step>
-  ### Create a Next.js project
+<PlatformTabs>
+<Tab value="React">
 
 ```sh
 npx create-next-app@latest my-app
 cd my-app
 ```
 
-  </Step>
-  <Step>
+</Tab>
+<Tab value="React Native">
+
+```sh
+npx create-expo-app@latest my-app
+cd my-app
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```sh
+mkdir my-app
+cd my-app
+npm init -y
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
 
 ### Install dependencies
 
+<PlatformTabs>
+<Tab value="React">
+
 <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk", "ai@^6", "@ai-sdk/react@^3", "@ai-sdk/openai", "zod"]} />
 
-  </Step>
-  <Step>
+</Tab>
+<Tab value="React Native">
 
-### Setup a backend route under `/api/chat`
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ai-sdk", "ai@^6", "@ai-sdk/react@^3", "@ai-sdk/openai", "zod"]} />
 
-`@/app/api/chat/route.ts`
+</Tab>
+<Tab value="React Ink">
 
-```tsx
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ai-sdk", "ai@^6", "@ai-sdk/react@^3", "@ai-sdk/openai", "zod", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set up the backend route
+
+For React Native and Ink, host this route in a separate backend project and
+point the client runtime at its absolute URL.
+
+```ts title="@/app/api/chat/route.ts"
 import { openai } from "@ai-sdk/openai";
 import {
   streamText,
@@ -50,16 +88,12 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-4o"),
-    messages: await convertToModelMessages(messages), // Note: async in v6
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages), // async in v6
     tools: {
       get_current_weather: tool({
         description: "Get the current weather",
-        inputSchema: zodSchema(
-          z.object({
-            city: z.string(),
-          }),
-        ),
+        inputSchema: zodSchema(z.object({ city: z.string() })),
         execute: async ({ city }) => {
           return `The weather in ${city} is sunny`;
         },
@@ -71,14 +105,15 @@ export async function POST(req: Request) {
 }
 ```
 
-  </Step>
-  <Step>
+</Step>
+<Step>
 
-### Setup the frontend
+### Set up the frontend
 
-`@/app/page.tsx`
+<PlatformTabs>
+<Tab value="React">
 
-```tsx
+```tsx title="@/app/page.tsx"
 "use client";
 
 import { Thread } from "@/components/assistant-ui/thread";
@@ -87,7 +122,6 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 export default function Home() {
   const runtime = useChatRuntime();
-
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <div className="h-full">
@@ -98,18 +132,192 @@ export default function Home() {
 }
 ```
 
-  </Step>
+</Tab>
+<Tab value="React Native">
+
+```tsx title="app/index.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import {
+  AssistantChatTransport,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { View } from "react-native";
+import { Thread } from "@/components/assistant-ui/thread";
+
+const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
+
+export default function Home() {
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: `${API_URL}/api/chat`,
+    }),
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <View style={{ flex: 1 }}>
+        <Thread />
+      </View>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="app.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import {
+  AssistantChatTransport,
+  useChatRuntime,
+} from "@assistant-ui/react-ai-sdk";
+import { Box } from "ink";
+import { Thread } from "./components/thread.js";
+
+export function App() {
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: "http://localhost:3000/api/chat",
+    }),
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Box flexDirection="column">
+        <Thread />
+      </Box>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set up UI components
+
+<PlatformTabs>
+<Tab value="React">
+
+Follow the [UI Components guide](/docs/ui/thread) to wire up the Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Native">
+
+Follow the [React Native setup](/docs/react-native) to add a native Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Ink">
+
+Follow the [Ink setup](/docs/ink) to add a terminal Thread, composer, and supporting primitives.
+
+</Tab>
+</PlatformTabs>
+
+</Step>
 </Steps>
 
-## Tracking Token Usage
+## Frontend tools and system messages
 
-assistant-ui exports a `useThreadTokenUsage` hook to access thread-level token usage on the client.
-<Steps>
-  <Step>
-Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`.
-```tsx
+`AssistantChatTransport` (used by default) forwards system messages and frontend tools to your backend on every request. Consume them with `frontendTools`:
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, zodSchema } from "ai";
+import type { UIMessage } from "ai";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+
+export async function POST(req: Request) {
+  const {
+    messages,
+    system,
+    tools,
+  }: {
+    messages: UIMessage[];
+    system?: string;
+    tools?: any;
+  } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    system,
+    messages: await convertToModelMessages(messages),
+    tools: {
+      ...frontendTools(tools),
+      // your backend tools...
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+Frontend tools are registered through `useAui` (see the [tools guide](/docs/guides/tools)) and serialized for the backend via `frontendTools`.
+
+## Multi-step tool calls
+
+AI SDK v6 supports running multiple tool-call rounds in a single request via `stopWhen`. Use `stepCountIs(N)` to cap iterations:
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import {
+  streamText,
+  convertToModelMessages,
+  stepCountIs,
+} from "ai";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(messages),
+    tools: {
+      /* ... */
+    },
+    stopWhen: stepCountIs(10), // cap at 10 tool-call iterations
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+Without a `stopWhen`, AI SDK runs a single inference step. Set `stepCountIs` (or one of AI SDK's other stop conditions) when your tools chain multiple calls.
+
+## Quote context
+
+assistant-ui's composer can attach quote metadata to user messages (e.g. when the user selects text and clicks "Quote"). On the server, `injectQuoteContext` flattens that metadata into a markdown blockquote prefix so the LLM sees the quoted text:
+
+```ts title="@/app/api/chat/route.ts"
+import {
+  streamText,
+  convertToModelMessages,
+} from "ai";
+import { injectQuoteContext } from "@assistant-ui/react-ai-sdk";
+import { openai } from "@ai-sdk/openai";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({
+    model: openai("gpt-5.4-mini"),
+    messages: await convertToModelMessages(injectQuoteContext(messages)),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+`injectQuoteContext` is idempotent: if the blockquote prefix is already present, it is not duplicated.
+
+## Token usage
+
+`useThreadTokenUsage` exposes thread-level token usage on the client. Attach `usage` and `modelId` via `messageMetadata` on the server:
+
+```ts title="@/app/api/chat/route.ts"
 import { streamText, convertToModelMessages } from "ai";
 import { frontendTools } from "@assistant-ui/react-ai-sdk";
+
 export async function POST(req: Request) {
   const { messages, tools, config } = await req.json();
   const result = streamText({
@@ -120,54 +328,72 @@ export async function POST(req: Request) {
   return result.toUIMessageStreamResponse({
     messageMetadata: ({ part }) => {
       if (part.type === "finish") {
-        return {
-          usage: part.totalUsage,
-        };
+        return { usage: part.totalUsage };
       }
       if (part.type === "finish-step") {
-        return {
-          modelId: part.response.modelId,
-        };
+        return { modelId: part.response.modelId };
       }
       return undefined;
     },
   });
 }
 ```
-  </Step>
-  <Step>
-Use `useThreadTokenUsage` to render token usage on the client.
 
-```tsx
+```tsx title="@/components/TokenCounter.tsx"
 "use client";
 
 import { useThreadTokenUsage } from "@assistant-ui/react-ai-sdk";
 
 export function TokenCounter() {
   const usage = useThreadTokenUsage();
-
   if (!usage) return null;
-
   return <div>{usage.totalTokens} total tokens</div>;
 }
 ```
-  </Step>
-</Steps>
 
-## Persisting Chat History
+`getThreadMessageTokenUsage(message)` returns per-message usage if you need to show it inline.
+
+## Attachments
+
+Attachments work through the standard [attachment adapter](/docs/runtimes/concepts/adapters#attachment-adapter). Pass it via `useChatRuntime`:
+
+```tsx
+const runtime = useChatRuntime({
+  adapters: { attachments: myAttachmentAdapter },
+});
+```
+
+Your attachment adapter's `send` should return `content` parts in the AI SDK shape, e.g. for files:
+
+```ts
+return {
+  ...attachment,
+  status: { type: "complete" },
+  content: [
+    {
+      type: "file",
+      mimeType: attachment.contentType ?? "",
+      filename: attachment.name,
+      data: await getFileDataURL(attachment.file),
+    },
+  ],
+};
+```
+
+For images, use `{ type: "image", image: <data url or remote url> }`. AI SDK will pass these to providers that accept multimodal content.
+
+## Persisting chat history
 
 By default, messages live only in memory and reset on reload. To persist and restore history per thread, provide a `ThreadHistoryAdapter` via `adapters.history`.
 
 <Callout type="warn">
-  The adapter **must** implement `withFormat`. `useChatRuntime` persists history through `withFormat(fmt)` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime — `load` / `append` on the top level are unused in the AI SDK path.
+The adapter **must** implement `withFormat`. `useChatRuntime` persists history through `withFormat(fmt)` so messages round-trip as AI SDK `UIMessage` objects. An adapter without `withFormat` throws at runtime; `load` and `append` on the top level are unused in the AI SDK path.
 </Callout>
 
 <Callout type="info">
-  For server-side cloud persistence with zero adapter code, see the [AssistantCloud integration](/docs/cloud/ai-sdk-assistant-ui).
+For server-side cloud persistence with zero adapter code, see the [AssistantCloud integration](/docs/cloud/ai-sdk-assistant-ui).
 </Callout>
 
-### Example
-
 ```tsx
 "use client";
 
@@ -181,7 +407,7 @@ const historyAdapter: ThreadHistoryAdapter = {
   },
   async append() {},
 
-  // `fmt` encodes UIMessage ↔ storage rows (ai-sdk/v6 format).
+  // fmt encodes UIMessage <-> storage rows (ai-sdk/v6 format).
   withFormat: (fmt) => ({
     async load() {
       const rows = await fetch("/api/history").then((r) => r.json());
@@ -202,90 +428,33 @@ const historyAdapter: ThreadHistoryAdapter = {
 };
 
 function Chat() {
-  const runtime = useChatRuntime({
-    adapters: { history: historyAdapter },
-  });
+  const runtime = useChatRuntime({ adapters: { history: historyAdapter } });
   // ...
 }
 ```
 
-Each persisted row follows `{ id, parent_id, format, content }`; `fmt.encode` produces the `content` payload and `fmt.decode` reverses it, so your backend never needs to know about `UIMessage` internals.
+Each persisted row follows `{ id, parent_id, format, content }`. `fmt.encode` produces the `content` payload and `fmt.decode` reverses it, so your backend never needs to know about `UIMessage` internals.
 
-## Key Changes from v5
+## Custom transport
 
-| Feature | v5 | v6 |
-|---------|----|----|
-| **ai package** | `ai@^5` | `ai@^6` |
-| **@ai-sdk/react** | `@ai-sdk/react@^2` | `@ai-sdk/react@^3` |
-| **convertToModelMessages** | Sync | Async (`await`) |
-| **Tool schema** | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
-
-## API Reference
-
-### useChatRuntime
-
-Creates a runtime integrated with AI SDK's `useChat` hook.
+`AssistantChatTransport` is the default. To point at a non-default endpoint, instantiate it with a custom `api`:
 
 ```tsx
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-
-const runtime = useChatRuntime();
-```
-
-### Custom API URL
-
-To use a different endpoint, pass a custom `AssistantChatTransport`:
-
-```tsx
-import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+import {
+  useChatRuntime,
+  AssistantChatTransport,
+} from "@assistant-ui/react-ai-sdk";
 
 const runtime = useChatRuntime({
-  transport: new AssistantChatTransport({
-    api: "/my-custom-api/chat",
-  }),
+  transport: new AssistantChatTransport({ api: "/my-custom-api/chat" }),
 });
 ```
 
-### System Messages and Frontend Tools
+If you need a transport that does not inherit from `AssistantChatTransport`, you forfeit automatic system-message and frontend-tool forwarding; the transport is then a regular AI SDK `ChatTransport` and you control everything explicitly.
 
-`AssistantChatTransport` (used by default) automatically forwards system messages and frontend tools to your backend. To consume them, update your backend route:
+## Advanced: useAISDKRuntime
 
-Backend route with system/tools forwarding:
-
-```tsx
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages, zodSchema } from "ai";
-import type { UIMessage } from "ai";
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
-
-export async function POST(req: Request) {
-  const {
-    messages,
-    system,
-    tools,
-  }: {
-    messages: UIMessage[];
-    system?: string;
-    tools?: any;
-  } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-4o"),
-    system,
-    messages: await convertToModelMessages(messages),
-    tools: {
-      ...frontendTools(tools),
-      // your backend tools...
-    },
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-```
-
-### useAISDKRuntime (Advanced)
-
-For advanced use cases where you need direct access to the `useChat` hook:
+When you need direct access to the `useChat` instance (e.g. to share it with non-assistant-ui code), drop down to `useAISDKRuntime`:
 
 ```tsx
 import { useChat } from "@ai-sdk/react";
@@ -295,6 +464,44 @@ const chat = useChat();
 const runtime = useAISDKRuntime(chat);
 ```
 
+`useAISDKRuntime` does not provide `cloud` or the higher-level adapter slots; those are part of `useChatRuntime`. If you need both your own `useChat` access AND cloud thread support, you generally want `useChatRuntime` and to read the chat state through assistant-ui hooks instead.
+
+## Adapter support
+
+| Adapter | Supported via |
+| --- | --- |
+| Attachments | `adapters.attachments` |
+| Speech | `adapters.speech` |
+| Dictation | `adapters.dictation` |
+| Feedback | `adapters.feedback` |
+| History | `adapters.history` (must implement `withFormat`) |
+| threadList | Via `cloud` (managed) or [RemoteThreadListRuntime](/docs/runtimes/concepts/threads) (custom DB) |
+
+## Key changes from v5
+
+| Feature | v5 | v6 |
+| --- | --- | --- |
+| `ai` package | `ai@^5` | `ai@^6` |
+| `@ai-sdk/react` | `@ai-sdk/react@^2` | `@ai-sdk/react@^3` |
+| `convertToModelMessages` | Sync | Async (`await`) |
+| Tool schema | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
+| Response | `toDataStreamResponse()` | `toUIMessageStreamResponse()` |
+
 ## Example
 
-For a complete example, check out the [AI SDK v6 example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6) in our repository.
+[`examples/with-ai-sdk-v6`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6) shows a complete reference implementation.
+
+## Next
+
+<Cards>
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, suggestions; one source of truth."
+    href="/docs/runtimes/concepts/adapters"
+  />
+  <Card
+    title="Threads"
+    description="Single-thread, AssistantCloud, custom thread list."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>