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

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

@@ -0,0 +1,71 @@
+---
+title: Overview
+description: Four ways to wire assistant-ui to a backend without a framework adapter.
+---
+
+If no [framework adapter](/docs/runtimes/pick-a-runtime) fits your backend, this section gives you four building blocks. All four are built on one of the two core runtimes; understanding the layering (see [architecture](/docs/runtimes/concepts/architecture)) makes the choice clear.
+
+## The four paths
+
+| Path | Layered on | Wire shape | Choose when |
+| --- | --- | --- | --- |
+| [`LocalRuntime`](/docs/runtimes/custom/local-runtime) | Core | You write a `ChatModelAdapter.run` function | The simplest case: you have a `fetch` call to make, want assistant-ui to handle state |
+| [`ExternalStoreRuntime`](/docs/runtimes/custom/external-store) | Core | You provide messages + callbacks | You already have state in redux, zustand, tanstack-query, or anywhere |
+| [`DataStream`](/docs/runtimes/custom/data-stream) | LocalRuntime + protocol | Your backend emits the data stream protocol | You want a thin message-stream contract, or you are migrating from AI SDK v4 |
+| [`AssistantTransport`](/docs/runtimes/custom/assistant-transport) | ExternalStoreRuntime + protocol | Your backend streams agent state snapshots | Your agent has rich internal state and you want it surfaced in the UI; or you need bidirectional commands |
+
+## Decision tree
+
+```text
+do you have an AI SDK / LangGraph / Google ADK / A2A backend?
+└── yes → use that framework adapter; you do not need this section
+└── no → continue
+    │
+    do you already have message state in redux / zustand / tanstack-query?
+    └── yes → ExternalStoreRuntime
+    └── no → continue
+        │
+        do you control the backend wire format?
+        └── yes, and i want simple fetch calls → LocalRuntime
+        └── yes, and i want to stream a structured agent state → AssistantTransport
+        └── no, the backend already speaks data stream protocol → DataStream
+```
+
+## What each path gives you
+
+**`LocalRuntime`** is the lowest-friction path. You implement one method (`run` or `async *run`). Branching, editing, regeneration, multi-thread, and adapter slots all work without extra code.
+
+**`ExternalStoreRuntime`** is the inverse: you own the message array and provide callbacks for each interaction. UI features turn on based on which callbacks you provide. Ideal when chat state is a first-class entity in your existing store.
+
+**`DataStream`** is `LocalRuntime` plus a wire protocol. You do not write a `ChatModelAdapter`; your backend emits a standardized stream of message parts and the runtime consumes it directly.
+
+**`AssistantTransport`** is `ExternalStoreRuntime` plus a state-streaming protocol. Instead of sending message parts, your backend sends snapshots of its full agent state. The UI is a stateless view on top of that state. Supports custom commands beyond the built-in `add-message` and `add-tool-result`.
+
+## Common building blocks
+
+Regardless of which path you pick, the [adapter](/docs/runtimes/concepts/adapters) and [thread](/docs/runtimes/concepts/threads) interfaces work the same way. Wire attachments, history, speech, feedback, suggestions, and multi-thread support through those shared contracts.
+
+## Next
+
+<Cards>
+  <Card
+    title="LocalRuntime"
+    description="Write a single ChatModelAdapter.run function."
+    href="/docs/runtimes/custom/local-runtime"
+  />
+  <Card
+    title="ExternalStoreRuntime"
+    description="Bring redux, zustand, tanstack-query, or your own state."
+    href="/docs/runtimes/custom/external-store"
+  />
+  <Card
+    title="Data Stream"
+    description="Standard message-stream protocol on top of LocalRuntime."
+    href="/docs/runtimes/custom/data-stream"
+  />
+  <Card
+    title="Assistant Transport"
+    description="Stream full agent state snapshots and bidirectional commands."
+    href="/docs/runtimes/custom/assistant-transport"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/google-adk/api.mdx

@@ -0,0 +1,256 @@
+---
+title: API reference
+description: createAdkStream, server helpers, session adapter, threads, message editing.
+---
+
+Reference for the runtime's wire-up surface. Start with [quickstart](/docs/runtimes/google-adk/quickstart) if you have not already.
+
+## createAdkStream
+
+Creates an `AdkStreamCallback` that connects to an ADK endpoint via SSE. Supports two modes.
+
+**proxy mode** — POST to your own API route:
+
+```ts
+import { createAdkStream } from "@assistant-ui/react-google-adk";
+
+const stream = createAdkStream({ api: "/api/chat" });
+```
+
+**direct mode** — connect directly to an ADK server:
+
+```ts
+const stream = createAdkStream({
+  api: "http://localhost:8000",
+  appName: "my-app",
+  userId: "user-1",
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `api` | `string` | URL to POST to (proxy route or ADK server base URL). |
+| `appName` | `string?` | ADK app name (enables direct mode when set). |
+| `userId` | `string?` | ADK user ID (required with `appName`). |
+| `headers` | `Record<string, string>` or `() => ...` | Static or dynamic request headers. |
+
+## Direct ADK server connection
+
+When connecting directly to an ADK server (without a proxy API route), use `createAdkSessionAdapter` to back your thread list with ADK sessions:
+
+```tsx
+import {
+  useAdkRuntime,
+  createAdkStream,
+  createAdkSessionAdapter,
+} from "@assistant-ui/react-google-adk";
+
+const ADK_URL = "http://localhost:8000";
+
+const { adapter, load, artifacts } = createAdkSessionAdapter({
+  apiUrl: ADK_URL,
+  appName: "my-app",
+  userId: "user-1",
+});
+
+const runtime = useAdkRuntime({
+  stream: createAdkStream({
+    api: ADK_URL,
+    appName: "my-app",
+    userId: "user-1",
+  }),
+  sessionAdapter: adapter,
+  load,
+});
+```
+
+The session adapter maps ADK sessions to assistant-ui threads:
+
+- **`adapter`** is a `RemoteThreadListAdapter` that uses ADK's session REST API for thread CRUD.
+- **`load`** reconstructs messages from session events via `AdkEventAccumulator`.
+- **`artifacts`** are functions to fetch, list, and delete session artifacts (see [hooks → artifacts](/docs/runtimes/google-adk/hooks#artifacts)).
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string` | ADK server base URL. |
+| `appName` | `string` | ADK app name. |
+| `userId` | `string` | ADK user ID. |
+| `headers` | `Record<string, string>` or `() => ...` | Static or dynamic request headers. |
+
+## Server helpers
+
+Server helpers live under the `/server` subpath:
+
+```ts
+import {
+  createAdkApiRoute,
+  adkEventStream,
+  parseAdkRequest,
+  toAdkContent,
+} from "@assistant-ui/react-google-adk/server";
+```
+
+### createAdkApiRoute
+
+One-liner API route handler that combines request parsing and SSE streaming:
+
+```ts
+export const POST = createAdkApiRoute({
+  runner,
+  userId: "default-user",
+  sessionId: (req) =>
+    new URL(req.url).searchParams.get("sessionId") ?? "default",
+});
+```
+
+Both `userId` and `sessionId` accept a static string or a function `(req: Request) => string` for dynamic resolution.
+
+### adkEventStream
+
+Converts an `AsyncGenerator<Event>` from ADK's `Runner.runAsync()` into an SSE `Response`. Sends an initial `:ok` comment to keep connections alive through proxies.
+
+```ts
+const events = runner.runAsync({ userId, sessionId, newMessage });
+return adkEventStream(events);
+```
+
+### parseAdkRequest and toAdkContent
+
+Lower-level helpers for custom API routes. `parseAdkRequest` parses incoming requests; `toAdkContent` converts to ADK's `Content` format. Supports user messages, tool results, `stateDelta`, `checkpointId`, and multimodal content:
+
+```ts
+const parsed = await parseAdkRequest(req);
+// parsed.type is "message" or "tool-result"
+// parsed.config contains runConfig, checkpointId
+// parsed.stateDelta contains session state changes
+
+const newMessage = toAdkContent(parsed);
+const events = runner.runAsync({
+  userId,
+  sessionId,
+  newMessage,
+  stateDelta: parsed.stateDelta,
+});
+return adkEventStream(events);
+```
+
+## Thread management
+
+Three options, picked by what you want to own. See [threads](/docs/runtimes/concepts/threads) for the general model.
+
+### ADK session adapter
+
+Use `createAdkSessionAdapter` to persist threads via ADK's session API; see [Direct ADK server connection](#direct-adk-server-connection) above.
+
+### Custom thread management
+
+```ts
+const runtime = useAdkRuntime({
+  stream: createAdkStream({ api: "/api/chat" }),
+  create: async () => {
+    const sessionId = await createSession();
+    return { externalId: sessionId };
+  },
+  load: async (externalId) => {
+    const history = await loadSession(externalId);
+    return { messages: history };
+  },
+  delete: async (externalId) => {
+    await deleteSession(externalId);
+  },
+});
+```
+
+### Cloud persistence
+
+For persistent thread history via assistant-cloud, pass a `cloud` instance:
+
+```ts
+const runtime = useAdkRuntime({
+  cloud, // see "AssistantCloud" in /docs/runtimes/concepts/threads
+  stream: createAdkStream({ api: "/api/chat" }),
+});
+```
+
+## Message editing and regeneration
+
+Provide a `getCheckpointId` callback to enable edit and regenerate buttons:
+
+```ts
+const runtime = useAdkRuntime({
+  stream: createAdkStream({ api: "/api/chat" }),
+  getCheckpointId: async (threadId, parentMessages) => {
+    // Resolve checkpoint ID for server-side forking
+    return checkpointId;
+  },
+});
+```
+
+When `getCheckpointId` is provided:
+
+- **Edit buttons** appear on user messages.
+- **Regenerate buttons** appear on assistant messages.
+
+The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`.
+
+<Callout type="info">
+Without `getCheckpointId`, edit and regenerate buttons will not appear. This is intentional; truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
+</Callout>
+
+## Event handlers
+
+Listen to streaming events:
+
+```ts
+const runtime = useAdkRuntime({
+  stream: createAdkStream({ api: "/api/chat" }),
+  eventHandlers: {
+    onError: (error) => {
+      console.error("Stream error:", error);
+    },
+    onAgentTransfer: (toAgent) => {
+      console.log("Agent transferred to:", toAgent);
+    },
+    onCustomEvent: (key, value) => {
+      // Fired for each entry in event.customMetadata
+      console.log("Custom metadata:", key, value);
+    },
+  },
+});
+```
+
+## RunConfig and stateDelta
+
+Pass `AdkRunConfig` to control agent behavior, and `stateDelta` to mutate session state along with messages:
+
+```ts
+import { useAdkSend } from "@assistant-ui/react-google-adk";
+
+const send = useAdkSend();
+
+send(messages, {
+  runConfig: {
+    streamingMode: "sse",
+    maxLlmCalls: 10,
+    pauseOnToolCalls: true,
+  },
+  stateDelta: { taskId: "abc", mode: "verbose" },
+});
+```
+
+`stateDelta` maps to ADK's `stateDelta` parameter on `/run_sse`.
+
+## Next
+
+<Cards>
+  <Card
+    title="Hooks"
+    description="Tool confirmations, auth, input requests, artifacts, escalation, metadata."
+    href="/docs/runtimes/google-adk/hooks"
+  />
+  <Card
+    title="Threads"
+    description="General model for multi-thread support across runtimes."
+    href="/docs/runtimes/concepts/threads"
+  />
+</Cards>