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

package/.docs/raw/docs/runtimes/a2a/overview.mdx

@@ -0,0 +1,60 @@
+---
+title: Overview
+description: Connect to any A2A v1.0 protocol-compliant agent server.
+---
+
+`@assistant-ui/react-a2a` is a runtime adapter for the [A2A (Agent-to-Agent) v1.0 protocol](https://github.com/a2aproject/A2A). Use it when your backend speaks A2A; the adapter handles the wire protocol so you can focus on the UI.
+
+## When to use it
+
+Pick the A2A runtime when:
+
+- You have an A2A v1.0 compatible agent server, or you are building one and want a reference client.
+- You want streaming task state, artifacts, and the protocol's full state machine surfaced in the UI.
+- You need multi-tenant or extension-aware A2A clients.
+
+If your backend is not A2A-compliant, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
+
+## Architecture
+
+`@assistant-ui/react-a2a` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters (attachments, speech, feedback, history, threads) work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
+
+## Requirements
+
+- An A2A v1.0 compatible agent server.
+- React 18 or 19.
+
+## Install
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-a2a"]} />
+
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-a2a"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-a2a", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+## Next
+
+<Cards>
+  <Card
+    title="Quickstart"
+    description="Minimal runtime setup with a Thread component."
+    href="/docs/runtimes/a2a/quickstart"
+  />
+  <Card
+    title="Client and hooks"
+    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
+    href="/docs/runtimes/a2a/client-and-hooks"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/a2a/quickstart.mdx

@@ -0,0 +1,216 @@
+---
+title: Quickstart
+description: Minimal runtime and Thread setup against an A2A server.
+---
+
+Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a).
+
+<Steps>
+<Step>
+
+### Wire up the runtime provider
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  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 A2A server is reachable, the runtime negotiates streaming vs non-streaming based on the agent card's `capabilities.streaming` flag and starts forwarding messages.
+
+## Auth and headers
+
+Pass static or dynamic headers when your server expects auth:
+
+```tsx
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## Adding adapters
+
+Attachments, speech, feedback, history, and a custom thread list are all supported via the standard adapter slots. See [adapters](/docs/runtimes/concepts/adapters) for the contracts; pass them on `useA2ARuntime`:
+
+```tsx
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  adapters: { attachments, history, speech, feedback },
+});
+```
+
+For multi-thread, see [threads](/docs/runtimes/concepts/threads) and pass `adapters.threadList`.
+
+## Next
+
+<Cards>
+  <Card
+    title="Client and hooks"
+    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
+    href="/docs/runtimes/a2a/client-and-hooks"
+  />
+  <Card
+    title="Pick a runtime"
+    description="Compare A2A to other runtime options."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+</Cards>

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

@@ -0,0 +1,70 @@
+---
+title: Overview
+description: Connect to AG-UI (Agent-User Interaction) protocol agents.
+---
+
+`@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,123 @@
+---
+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 };
+      },
+    },
+  },
+});
+```
+
+## 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_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 |
+| 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>