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

package/.docs/raw/docs/runtimes/ag-ui/overview.mdx

@@ -0,0 +1,70 @@
+---
+title: AG-UI Agent Runtime
+description: Wire AG-UI (Agent-User Interaction) protocol agents into a React chat UI with assistant-ui — bidirectional events, generative UI, and human-in-the-loop.
+---
+
+`@assistant-ui/react-ag-ui` is a runtime adapter for the [AG-UI (Agent-User Interaction) protocol](https://github.com/ag-ui-protocol/ag-ui). It lets your assistant-ui frontend speak to any AG-UI-compliant agent server, including CopilotKit-based backends.
+
+## When to use it
+
+Pick the AG-UI runtime when:
+
+- Your backend implements the AG-UI protocol (e.g. CopilotKit agents, custom AG-UI servers).
+- You want streaming text, thinking events, reasoning events, tool calls, and state snapshots in one protocol.
+- You need agent-side state synchronization via `STATE_SNAPSHOT` and `STATE_DELTA` events.
+
+If your backend is not AG-UI-compliant, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
+
+## Architecture
+
+`@assistant-ui/react-ag-ui` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). The runtime owns AG-UI event parsing and message reconstruction; you provide an `HttpAgent` from `@ag-ui/client` and the adapter handles the wire protocol.
+
+Shared adapters (attachments, speech, dictation, feedback, history) work the same way described in [adapters](/docs/runtimes/concepts/adapters).
+
+## Requirements
+
+- An AG-UI-compatible agent server.
+- React 18 or 19.
+
+## Install
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ag-ui", "@ag-ui/client"]} />
+
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ag-ui", "@ag-ui/client"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ag-ui", "@ag-ui/client", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+## Example
+
+[`examples/with-ag-ui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ag-ui) shows a complete reference implementation. Or scaffold one directly:
+
+```sh
+npx assistant-ui@latest create my-app -e with-ag-ui
+```
+
+## Next
+
+<Cards>
+  <Card
+    title="Quickstart"
+    description="Minimal HttpAgent + useAgUiRuntime setup."
+    href="/docs/runtimes/ag-ui/quickstart"
+  />
+  <Card
+    title="Runtime options"
+    description="useAgUiRuntime options, adapters, events, thread list."
+    href="/docs/runtimes/ag-ui/runtime-options"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/ag-ui/quickstart.mdx

@@ -0,0 +1,243 @@
+---
+title: Quickstart
+description: Minimal HttpAgent + useAgUiRuntime setup against an AG-UI server.
+---
+
+Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui).
+
+<Steps>
+<Step>
+
+### Wire up the runtime provider
+
+Create an `HttpAgent` pointing at your AG-UI endpoint and pass it to `useAgUiRuntime`:
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
+
+import { useMemo } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
+import { HttpAgent } from "@ag-ui/client";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const agent = useMemo(
+    () =>
+      new HttpAgent({
+        url: "http://localhost:8000/agent",
+      }),
+    [],
+  );
+
+  const runtime = useAgUiRuntime({ agent });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { useMemo } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
+import { HttpAgent } from "@ag-ui/client";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const agent = useMemo(
+    () =>
+      new HttpAgent({
+        url: "http://localhost:8000/agent",
+      }),
+    [],
+  );
+
+  const runtime = useAgUiRuntime({ agent });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { useMemo } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
+import { HttpAgent } from "@ag-ui/client";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const agent = useMemo(
+    () =>
+      new HttpAgent({
+        url: "http://localhost:8000/agent",
+      }),
+    [],
+  );
+
+  const runtime = useAgUiRuntime({ agent });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Render the Thread
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/page.tsx"
+import { Thread } from "@/components/assistant-ui/thread";
+import { MyRuntimeProvider } from "./MyRuntimeProvider";
+
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <Thread />
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="app/index.tsx"
+import { View } from "react-native";
+import { Thread } from "@/components/assistant-ui/thread";
+import { MyRuntimeProvider } from "@/runtime/MyRuntimeProvider";
+
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <View style={{ flex: 1 }}>
+        <Thread />
+      </View>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="app.tsx"
+import { Box } from "ink";
+import { Thread } from "./components/thread.js";
+import { MyRuntimeProvider } from "./runtime/MyRuntimeProvider.js";
+
+export function App() {
+  return (
+    <MyRuntimeProvider>
+      <Box flexDirection="column">
+        <Thread />
+      </Box>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</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>
+
+Once your AG-UI server is reachable, the runtime parses incoming events (`TEXT_MESSAGE_*`, `TOOL_CALL_*`, `STATE_SNAPSHOT`, etc.) into assistant-ui messages.
+
+## Showing thinking and reasoning
+
+`showThinking` (default `true`) controls whether `THINKING_*` and `REASONING_*` events render as visible reasoning in the UI:
+
+```tsx
+const runtime = useAgUiRuntime({
+  agent,
+  showThinking: false, // hide thinking blocks
+});
+```
+
+## Adding adapters
+
+Attachments, speech, dictation, feedback, history, and a custom thread list are supported via the standard adapter slots. See [adapters](/docs/runtimes/concepts/adapters):
+
+```tsx
+const runtime = useAgUiRuntime({
+  agent,
+  adapters: { attachments, history, speech, feedback },
+});
+```
+
+For multi-thread, pass `adapters.threadList` (experimental); see [runtime options](/docs/runtimes/ag-ui/runtime-options#thread-list-experimental).
+
+## Next
+
+<Cards>
+  <Card
+    title="Runtime options"
+    description="useAgUiRuntime options, adapters, events, thread list."
+    href="/docs/runtimes/ag-ui/runtime-options"
+  />
+  <Card
+    title="Pick a runtime"
+    description="Compare AG-UI to other runtime options."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/ag-ui/runtime-options.mdx

@@ -0,0 +1,154 @@
+---
+title: Runtime options
+description: useAgUiRuntime options, adapters, supported events, thread list.
+---
+
+import { AguiIcon } from "@/components/icons/agui";
+
+Reference for the runtime's API surface. Start with [quickstart](/docs/runtimes/ag-ui/quickstart) if you have not already.
+
+## useAgUiRuntime options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `agent` | `HttpAgent` | An AG-UI client agent (from `@ag-ui/client`). Required. |
+| `logger` | `Partial<Logger>` | Optional logger overrides. The runtime logs event-parser warnings and run lifecycle events. |
+| `showThinking` | `boolean` | Whether to render `THINKING_*` and `REASONING_*` events as visible reasoning. Defaults to `true`. |
+| `onError` | `(e: Error) => void` | Error callback fired on `RUN_ERROR` events and protocol errors. |
+| `onCancel` | `() => void` | Cancellation callback fired when the user cancels a run. |
+| `adapters` | `UseAgUiRuntimeAdapters` | Standard adapter slots (see below). |
+
+## Adapter slots
+
+| Adapter | Slot | Notes |
+| --- | --- | --- |
+| Attachments | `adapters.attachments` | See [attachment adapter](/docs/runtimes/concepts/adapters#attachment-adapter). |
+| Speech | `adapters.speech` | Text-to-speech. See [speech adapter](/docs/runtimes/concepts/adapters#speech-adapter). |
+| Dictation | `adapters.dictation` | Speech-to-text input. |
+| Feedback | `adapters.feedback` | Thumbs up / down. See [feedback adapter](/docs/runtimes/concepts/adapters#feedback-adapter). |
+| History | `adapters.history` | Per-thread message persistence. |
+| Thread list | `adapters.threadList` | Multi-thread switching (experimental, see below). |
+
+## Thread list (experimental)
+
+<Callout type="warn">
+The thread list adapter is currently experimental and may change without notice.
+</Callout>
+
+`UseAgUiThreadListAdapter` lets you back the thread list with your own state.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `threadId` | `string` | The currently active thread ID. |
+| `onSwitchToNewThread` | `() => Promise<void>` | Called when the user creates a new thread. Reset your thread state here. |
+| `onSwitchToThread` | `(threadId: string) => Promise<{ messages, state? }>` | Called when the user switches threads. Return the persisted messages (and optional opaque state). |
+
+```tsx
+const runtime = useAgUiRuntime({
+  agent,
+  adapters: {
+    threadList: {
+      threadId: currentThreadId,
+      onSwitchToNewThread: async () => {
+        setCurrentThreadId(await createThread());
+      },
+      onSwitchToThread: async (id) => {
+        const { messages, state } = await loadThread(id);
+        setCurrentThreadId(id);
+        return { messages, state };
+      },
+    },
+  },
+});
+```
+
+## Interrupts (experimental)
+
+<Callout type="warn">
+The interrupt API is experimental and may change without notice.
+</Callout>
+
+When the agent emits `RUN_FINISHED` with `outcome = { type: "interrupt", interrupts: [...] }`, the active assistant message is marked `requires-action` with `reason: "interrupt"` and the `Interrupt[]` payload is written to `metadata.custom.agui.interrupts`. Render an approval / input UI from there.
+
+`useAgUiRuntime` returns an `AgUiAssistantRuntime` with two extra methods:
+
+| Method | Description |
+| --- | --- |
+| `unstable_getPendingInterrupts(): readonly AgUiInterrupt[]` | Snapshot of the open interrupts on the most recent assistant message. |
+| `unstable_submitInterruptResponses(responses: ResumeEntry[]): Promise<void>` | Submits one `ResumeEntry` per open interrupt and resumes the run. |
+
+`responses` must address every open interrupt; missing entries, unknown ids, or expired interrupts (`expiresAt`) reject before any network call. Each entry is `{ interruptId, status: "resolved" | "cancelled", payload? }`. The next `RunAgentInput` carries `resume: ResumeEntry[]`.
+
+```tsx
+const runtime = useAgUiRuntime({ agent });
+const pending = runtime.unstable_getPendingInterrupts();
+
+await runtime.unstable_submitInterruptResponses(
+  pending.map((i) => ({
+    interruptId: i.id,
+    status: "resolved",
+    payload: { approved: true },
+  })),
+);
+```
+
+## Supported events
+
+The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.
+
+| Event | Effect |
+| --- | --- |
+| `RUN_STARTED` / `RUN_FINISHED` | Toggles thread `isRunning`. `RUN_FINISHED.outcome` is honored (success / interrupt). |
+| `RUN_CANCELLED` | Marks the in-flight assistant message as cancelled. |
+| `RUN_ERROR` | Marks the message as errored; fires `onError`. |
+| `TEXT_MESSAGE_START` / `_CONTENT` / `_END` | Streams text content into an assistant message. |
+| `TEXT_MESSAGE_CHUNK` | Appends a delta without explicit lifecycle. |
+| `THINKING_START` / `_END` | Wraps reasoning blocks (when `showThinking` is on). |
+| `THINKING_TEXT_MESSAGE_*` | Streams thinking text deltas. |
+| `REASONING_START` / `_MESSAGE_*` / `_END` | Streams structured reasoning per message. |
+| `TOOL_CALL_START` / `_ARGS` / `_END` | Streams tool calls into the current assistant message. |
+| `TOOL_CALL_CHUNK` | Streams tool deltas without explicit lifecycle. |
+| `TOOL_CALL_RESULT` | Attaches a tool result to a tool call. |
+| `STATE_SNAPSHOT` | Replaces the agent's external state. |
+| `STATE_DELTA` | Applies a JSON-patch-style delta to the agent's state. |
+| `MESSAGES_SNAPSHOT` | Replaces the full message list (used for thread restore). |
+| `CUSTOM` | Forwarded to your custom event handling. |
+| `RAW` | Untyped passthrough for unrecognized events. |
+
+## Feature support
+
+| Feature | Supported |
+| --- | --- |
+| Streaming text | Yes |
+| Thinking / reasoning blocks | Yes |
+| Tool calls and results | Yes |
+| Tool result handoff (client-side execution) | Yes |
+| State snapshots and deltas | Yes |
+| Cancellation | Yes |
+| Message editing | Yes |
+| Message reload | Yes |
+| Run resumption | Yes |
+| Interrupts (human-in-the-loop) | Experimental (`unstable_*` API, see [Interrupts](#interrupts-experimental)) |
+| Multi-thread | Experimental (`adapters.threadList`) |
+| History persistence | Via [history adapter](/docs/runtimes/concepts/adapters#history-adapter) |
+
+## Related
+
+<Cards>
+  <Card
+    icon={<AguiIcon width={20} height={20} />}
+    title="AG-UI overview"
+    description="What AG-UI is and when to pick it."
+    href="/docs/runtimes/ag-ui"
+  />
+  <Card
+    title="Quickstart"
+    description="Minimal runtime + Thread setup."
+    href="/docs/runtimes/ag-ui/quickstart"
+  />
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, thread list."
+    href="/docs/runtimes/concepts/adapters"
+  />
+</Cards>

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

@@ -0,0 +1,52 @@
+---
+title: Vercel AI SDK Runtime
+description: Connect the Vercel AI SDK to a React chat UI via assistant-ui — useChat hooks, custom transports, frontend tools, attachments, multi-step agents, and token usage.
+---
+
+import { VercelIcon } from "@/components/icons/vercel";
+
+`@assistant-ui/react-ai-sdk` integrates assistant-ui with the [Vercel AI SDK](https://ai-sdk.dev/). It covers `useChat` flows, custom transports, frontend tools, attachments, quote context, multi-step agents, token usage, and cloud persistence.
+
+## Pick a version
+
+| AI SDK | Runtime package | Docs |
+| --- | --- | --- |
+| `ai@^6` + `@ai-sdk/react@^3` | `@assistant-ui/react-ai-sdk` (latest) | [v6 (current)](/docs/runtimes/ai-sdk/v6) |
+| `ai@^5` + `@ai-sdk/react@^2` | `@assistant-ui/react-ai-sdk@0.x` | [v5 (legacy)](/docs/runtimes/ai-sdk/v5-legacy) |
+| `ai@^4` | `@assistant-ui/react-data-stream` | [v4 (legacy)](/docs/runtimes/ai-sdk/v4-legacy) |
+
+New projects should target v6. v5 and v4 are documented for projects that have not migrated yet; both have known compatibility gaps and receive no new features.
+
+## Architecture
+
+`@assistant-ui/react-ai-sdk` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
+
+## Choosing useChatRuntime vs useAISDKRuntime
+
+Both ship in the same package.
+
+- **`useChatRuntime`** (recommended) wraps the AI SDK's `useChat` hook and adds cloud thread support, the standard adapter slots, and `AssistantChatTransport` (which forwards system messages and frontend tools by default). Use this unless you have a reason not to.
+- **`useAISDKRuntime`** is a lower-level hook that takes an existing `useChat` instance you control directly. Use it when you need to share the chat instance with non-assistant-ui code or wire in a custom transport that does not inherit from `AssistantChatTransport`.
+
+## Next
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v6 (current)"
+    description="Quickstart, frontend tools, attachments, quotes, history, multi-step, useAISDKRuntime."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v5 (legacy)"
+    description="Reference for projects still on AI SDK v5."
+    href="/docs/runtimes/ai-sdk/v5-legacy"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v4 (legacy)"
+    description="Reference for projects still on AI SDK v4."
+    href="/docs/runtimes/ai-sdk/v4-legacy"
+  />
+</Cards>