@assistant-ui/mcp-docs-server 0.2.3 → 0.3.1

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

@@ -1,731 +0,0 @@
----
-title: AI SDK v7
-description: Integrate Vercel AI SDK v7 with assistant-ui for streaming chat.
----
-
-Current-version integration. Requires `ai@^7` and `@ai-sdk/react@^4`. For older versions see the [overview](/docs/runtimes/ai-sdk/overview).
-
-## Quickstart
-
-<Steps>
-<Step>
-
-### Create a project
-
-<PlatformTabs>
-<Tab value="React">
-
-```sh
-npx create-next-app@latest my-app
-cd my-app
-```
-
-</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/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@ai-sdk/openai", "zod"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/ai-sdk", "ai@^7", "@ai-sdk/react@^4", "@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,
-  convertToModelMessages,
-  tool,
-  zodSchema,
-  createUIMessageStreamResponse,
-  toUIMessageStream,
-} from "ai";
-import type { UIMessage } from "ai";
-import { z } from "zod";
-
-export const maxDuration = 30;
-
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages), // async in v7
-    tools: {
-      get_current_weather: tool({
-        description: "Get the current weather",
-        inputSchema: zodSchema(z.object({ city: z.string() })),
-        execute: async ({ city }) => {
-          return `The weather in ${city} is sunny`;
-        },
-      }),
-    },
-  });
-
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({ stream: result.stream }),
-  });
-}
-```
-
-</Step>
-<Step>
-
-### Set up the frontend
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="@/app/page.tsx"
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-
-export default function Home() {
-  const runtime = useChatRuntime();
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <div className="h-full">
-        <Thread />
-      </div>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="app/index.tsx"
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import {
-  AssistantChatTransport,
-  useChatRuntime,
-} from "@assistant-ui/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/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>
-
-## Frontend tools and system messages
-
-`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, createUIMessageStreamResponse, toUIMessageStream } from "ai";
-import type { UIMessage } from "ai";
-import { frontendTools } from "@assistant-ui/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.6-luna"),
-    system,
-    messages: await convertToModelMessages(messages),
-    tools: {
-      ...frontendTools(tools),
-      // your backend tools...
-    },
-  });
-
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({ stream: result.stream }),
-  });
-}
-```
-
-Frontend tools are registered through the provider's `config` (see the [tools guide](/docs/tools/defining-tools)) and serialized for the backend via `frontendTools`.
-
-## Multi-step tool calls
-
-AI SDK v7 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,
-  createUIMessageStreamResponse,
-  toUIMessageStream,
-} from "ai";
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-    tools: {
-      /* ... */
-    },
-    stopWhen: stepCountIs(10), // cap at 10 tool-call iterations
-  });
-
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({ stream: result.stream }),
-  });
-}
-```
-
-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.
-
-## Server-side tool approval
-
-AI SDK v7 gates tool execution with the call-level `toolApproval` option. The server pauses, emits an `approval-requested` part, and resumes once the client posts an approval response. assistant-ui surfaces the gate as `approval` on the tool part and adds a `respondToApproval` prop on the renderer, so tool components stay decoupled from `chatHelpers`.
-
-On the backend, configure the gate with the call-level `toolApproval` option (per-tool status or function):
-
-```ts title="@/app/api/chat/route.ts"
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages, tool, createUIMessageStreamResponse, toUIMessageStream } from "ai";
-import { z } from "zod";
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-    tools: {
-      deploy: tool({
-        description: "Deploy the current build to an environment.",
-        inputSchema: z.object({ target: z.string() }),
-        execute: async ({ target }) => ({ deployed: target }),
-      }),
-    },
-    toolApproval: {
-      deploy: (input) =>
-        input.target === "production" ? "user-approval" : "not-applicable",
-    },
-  });
-
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({ stream: result.stream }),
-  });
-}
-```
-
-On the client, configure `useChat` with `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses` so the response is sent back to the server when the user decides:
-
-```tsx title="@/app/page.tsx"
-"use client";
-
-import { useChat } from "@ai-sdk/react";
-import {
-  AssistantRuntimeProvider,
-  useAISDKRuntime,
-} from "@assistant-ui/ai-sdk";
-import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
-import { Thread } from "@/components/assistant-ui/thread";
-
-export default function Page() {
-  const chat = useChat({
-    api: "/api/chat",
-    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
-  });
-  const runtime = useAISDKRuntime(chat);
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-Render the gate with a toolkit entry. The `approval` field carries the gate state, and `respondToApproval` is the only correct way to acknowledge it (it reads the approval id from the part):
-
-```tsx title="@/app/page.tsx"
-"use client";
-
-import { useChat } from "@ai-sdk/react";
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  defineToolkit,
-  Tools,
-} from "@assistant-ui/react";
-import { useAISDKRuntime } from "@assistant-ui/ai-sdk";
-import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
-import { Thread } from "@/components/assistant-ui/thread";
-
-const toolkit = defineToolkit({
-  deploy: {
-    type: "backend",
-    render: ({ args, approval, respondToApproval, result }) => {
-      if (approval?.approved === undefined) {
-        return (
-          <div>
-            <p>Approve deploy to {args.target}?</p>
-            <button onClick={() => respondToApproval({ approved: true })}>
-              Approve
-            </button>
-            <button
-              onClick={() =>
-                respondToApproval({ approved: false, reason: "user denied" })
-              }
-            >
-              Deny
-            </button>
-          </div>
-        );
-      }
-      if (approval?.approved === false) return <p>Denied</p>;
-      if (result === undefined) return <p>Approved, deploying…</p>;
-      return <p>Deployed {result.deployed}</p>;
-    },
-  },
-});
-
-export default function Page() {
-  const chat = useChat({
-    api: "/api/chat",
-    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
-  });
-  const runtime = useAISDKRuntime(chat);
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-See the [tool UI guide](/docs/tools/tool-ui#server-side-approval-gates) for the full three-state semantics of `approval.approved` and the `isAutomatic` flag.
-
-## 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,
-  createUIMessageStreamResponse,
-  toUIMessageStream,
-} from "ai";
-import { injectQuoteContext } from "@assistant-ui/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.6-luna"),
-    messages: await convertToModelMessages(injectQuoteContext(messages)),
-  });
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({ stream: result.stream }),
-  });
-}
-```
-
-`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, createUIMessageStreamResponse, toUIMessageStream } from "ai";
-import { frontendTools } from "@assistant-ui/ai-sdk";
-
-export async function POST(req: Request) {
-  const { messages, tools, config } = await req.json();
-  const result = streamText({
-    model: getModel(config?.modelName),
-    messages: await convertToModelMessages(messages),
-    tools: frontendTools(tools),
-  });
-  return createUIMessageStreamResponse({
-    stream: toUIMessageStream({
-      stream: result.stream,
-      messageMetadata: ({ part }) => {
-        if (part.type === "finish") {
-          return { usage: part.totalUsage };
-        }
-        if (part.type === "finish-step") {
-          return { modelId: part.response.modelId };
-        }
-        return undefined;
-      },
-    }),
-  });
-}
-```
-
-```tsx title="@/components/TokenCounter.tsx"
-"use client";
-
-import { useThreadTokenUsage } from "@assistant-ui/ai-sdk";
-
-export function TokenCounter() {
-  const usage = useThreadTokenUsage();
-  if (!usage) return null;
-  return <div>{usage.totalTokens} total tokens</div>;
-}
-```
-
-`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` 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).
-</Callout>
-
-```tsx
-"use client";
-
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-import type { ThreadHistoryAdapter } from "@assistant-ui/react";
-
-const historyAdapter: ThreadHistoryAdapter = {
-  // Required by the type — unused by useChatRuntime.
-  async load() {
-    return { headId: null, messages: [] };
-  },
-  async append() {},
-
-  // fmt encodes UIMessage <-> storage rows (ai-sdk/v6 format).
-  withFormat: (fmt) => ({
-    async load() {
-      const rows = await fetch("/api/history").then((r) => r.json());
-      return { messages: rows.map(fmt.decode) };
-    },
-    async append(item) {
-      await fetch("/api/history", {
-        method: "POST",
-        body: JSON.stringify({
-          id: fmt.getId(item.message),
-          parent_id: item.parentId,
-          format: fmt.format,
-          content: fmt.encode(item),
-        }),
-      });
-    },
-  }),
-};
-
-function Chat() {
-  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.
-
-## Custom transport
-
-`AssistantChatTransport` is the default. To point at a non-default endpoint, instantiate it with a custom `api`:
-
-```tsx
-import {
-  useChatRuntime,
-  AssistantChatTransport,
-} from "@assistant-ui/ai-sdk";
-
-const runtime = useChatRuntime({
-  transport: new AssistantChatTransport({ api: "/my-custom-api/chat" }),
-});
-```
-
-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.
-
-## Runtime options
-
-Beyond transports and adapters, `useChatRuntime` accepts options that control thread routing, message grouping, and run resumption.
-
-### onThreadIdChange
-
-Called whenever the runtime changes the active thread's settled ID, e.g. to sync the active thread to a URL query param. Changes supplied through the controlled `threadId` option are not echoed back through this callback.
-
-```tsx
-const runtime = useChatRuntime({
-  onThreadIdChange: (threadId) => {
-    const url = new URL(window.location.href);
-    if (threadId) {
-      url.searchParams.set("thread", threadId);
-    } else {
-      url.searchParams.delete("thread");
-    }
-    window.history.replaceState(null, "", url);
-  },
-});
-```
-
-Only the settled ID is emitted: while a freshly created thread has not been initialized yet, the value is `undefined`, and the real ID is emitted once the thread initializes (with [AssistantCloud](/docs/cloud/ai-sdk-assistant-ui), this is the cloud thread ID). The transient local ID is never surfaced.
-
-### joinStrategy
-
-Controls how consecutive assistant messages are rendered:
-
-```tsx
-const runtime = useChatRuntime({
-  joinStrategy: "none",
-});
-```
-
-`"concat-content"` (the default) merges consecutive assistant messages into a single thread message. `"none"` keeps each assistant message as its own thread message, which is useful when a backend persists proactive or consecutive assistant messages as separate entries. See the [external store guide](/docs/runtimes/custom/external-store#useexternalmessageconverter-with-join-strategy) for the underlying join semantics.
-
-### onResume
-
-Called when `runtime.thread.resumeRun(config)` is invoked. Provide it to bridge resume invocations into a custom replay channel, for example an SSE reconnect endpoint keyed by turn id:
-
-```tsx
-const runtime = useChatRuntime({
-  onResume: async (config) => {
-    await reconnectToRun(config.runConfig);
-  },
-});
-```
-
-When omitted, `resumeRun` throws `"Runtime does not support resuming runs."`. For streams that should survive a page reload without a custom channel, use the built-in transport-level path instead: see [Resumable streams](/docs/guides/resumable-streams), which reconnects automatically on mount and reports failures via `onResumeError`.
-
-### messageRepository
-
-Import a branch-aware AI SDK message tree once, and only when `useChat` is empty. After that seed, live updates come only from `useChat`. Clearing the chat or passing a new object identity does not reload the tree. Persisted threads that already go through `adapters.history` do not need this.
-
-```tsx
-const runtime = useChatRuntime({
-  messageRepository: storedTree,
-  unstable_onBranchChange: ({ headId }) => {
-    saveSelectedBranch(headId);
-  },
-});
-```
-
-`unstable_onBranchChange` fires after an explicit `switchToBranch` (for example a BranchPicker click). It complements `setMessages` and does not enable switching by itself. The callback is unstable and may change without notice.
-
-## Advanced: useAISDKRuntime
-
-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";
-import { useAISDKRuntime } from "@assistant-ui/ai-sdk";
-
-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.
-
-`useAISDKRuntime` accepts `joinStrategy`, `onResume`, `messageRepository`, and `unstable_onBranchChange` (see [Runtime options](#runtime-options)) plus one option of its own, `cancelPendingToolCallsOnSend`:
-
-```tsx
-const runtime = useAISDKRuntime(chat, {
-  cancelPendingToolCallsOnSend: false,
-});
-```
-
-When enabled (the default), sending a new message marks any pending interactive tool calls as failed with an error indicating the user cancelled them. Set it to `false` to leave pending tool calls untouched when the user sends a new message.
-
-## 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 | v7 |
-| --- | --- | --- |
-| `ai` package | `ai@^5` | `ai@^7` |
-| `@ai-sdk/react` | `@ai-sdk/react@^2` | `@ai-sdk/react@^4` |
-| `convertToModelMessages` | Sync | Async (`await`) |
-| Tool schema | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
-| Response | `toDataStreamResponse()` | `createUIMessageStreamResponse()` |
-
-## Example
-
-[`examples/with-ai-sdk-v7`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v7) shows a complete reference implementation.
-
-For responses that should survive a page reload mid-stream, see [Resumable streams](/docs/guides/resumable-streams), which wraps the same v7 byte stream in `assistant-stream/resumable`.
-
-## 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"
-  />
-  <Card
-    title="Resumable streams"
-    description="Survive page reloads and connection drops mid-response."
-    href="/docs/guides/resumable-streams"
-  />
-</Cards>