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

package/.docs/raw/docs/runtimes/custom/custom-thread-list.mdx

@@ -216,12 +216,58 @@ When the hook mounts it calls `list()` on your adapter, hydrates existing thread
 
 ## Thread Lifecycle Cheatsheet
 
-- `list()` hydrates threads on mount and during refreshes.
+- `list()` hydrates threads on mount. It runs once; call `runtime.threads.reload()` to re-fetch.
 - Creating a new conversation calls `initialize()` once the user sends the first message.
 - `archive`, `unarchive`, and `delete` are called optimistically; throw to revert the UI.
 - `generateTitle()` powers the automatic title button and expects an `AssistantStream`.
 - Provide a `runtimeHook` that always returns a fresh runtime instance per active thread.
 
+## Reloading After Async Authentication
+
+If your adapter depends on an authenticated user (e.g. an OIDC provider, `better-auth`, `next-auth`) and the auth state resolves asynchronously after `useRemoteThreadListRuntime` has mounted, the initial `list()` call may run before the user is available. Call `aui.threads().reload()` when auth completes to re-fetch with the authenticated request.
+
+```tsx title="app/ThreadListProvider.tsx"
+"use client";
+
+import { useEffect } from "react";
+import { useAuth } from "react-oidc-context";
+import {
+  AssistantRuntimeProvider,
+  useAui,
+  useLocalRuntime,
+  useRemoteThreadListRuntime,
+} from "@assistant-ui/react";
+
+function ReloadOnAuth() {
+  const aui = useAui();
+  const { isLoading, user } = useAuth();
+
+  useEffect(() => {
+    if (!isLoading && user) {
+      aui.threads().reload();
+    }
+  }, [isLoading, user?.id]);
+
+  return null;
+}
+
+export function ThreadListProvider({ children }) {
+  const runtime = useRemoteThreadListRuntime({
+    runtimeHook: () => useLocalRuntime(myModelAdapter),
+    adapter: useThreadListAdapter(),
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ReloadOnAuth />
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+`reload()` replaces the cached load promise and discards any in-flight response from a superseded call, so it is safe to invoke multiple times (for example, on logout followed by a new login). `useAui` must be called inside `AssistantRuntimeProvider`, so the effect lives in a child component.
+
 ## Avoiding Race Conditions in History Adapters
 
 <Callout type="warn">
@@ -238,12 +284,12 @@ const aui = useAui();
 
 const history = useMemo<ThreadHistoryAdapter>(
   () => ({
-    async append(message) {
+    async append({ message, parentId }) {
       // Wait for initialization to complete and get the remoteId
       const { remoteId } = await aui.threadListItem().initialize();
 
       // Now safe to save the message using the remoteId
-      await saveMessageToDatabase(remoteId, message);
+      await saveMessageToDatabase(remoteId, parentId, message);
     },
     // ...
   }),

package/.docs/raw/docs/runtimes/custom/external-store.mdx

@@ -424,6 +424,44 @@ const onEdit = async (message: AppendMessage) => {
 };
 ```
 
+### Branching Support
+
+The `messages` array path assumes a linear conversation — each message's parent is the previous message. To support branching (e.g. regenerating responses creates alternative branches), use `ExportedMessageRepository.fromBranchableArray()` combined with `thread.import()`.
+
+Each message must have an explicit `id` and `parentId`. Messages with the same `parentId` create branches:
+
+```tsx
+import {
+  ExportedMessageRepository,
+  useExternalStoreRuntime,
+} from "@assistant-ui/react";
+
+// Your messages from the backend, each with an id and parentId
+const backendMessages = [
+  { id: "user-1", role: "user", content: "Hello", parentId: null },
+  { id: "asst-1", role: "assistant", content: "Hi!", parentId: "user-1" },
+  // A second response to the same user message = a branch
+  { id: "asst-2", role: "assistant", content: "Hey!", parentId: "user-1" },
+];
+
+// Convert to ExportedMessageRepository
+const repo = ExportedMessageRepository.fromBranchableArray(
+  backendMessages.map((m) => ({
+    message: { id: m.id, role: m.role, content: m.content },
+    parentId: m.parentId,
+  })),
+  { headId: "asst-1" }, // which branch to display initially
+);
+
+// Import into the runtime
+runtime.thread.import(repo);
+```
+
+<Callout type="warn">
+  Messages in the array must be ordered so that parents appear before their
+  children. Each message **must** have an `id` field set.
+</Callout>
+
 ### Tool Calling
 
 Support tool calls with proper result handling:
@@ -1409,7 +1447,7 @@ The main interface for connecting your state to assistant-ui.
       name: "isRunning",
       type: "boolean",
       description:
-        "Whether the assistant is currently generating a response. When true, shows optimistic assistant message",
+        "Whether the assistant is currently generating a response. When true, shows an optimistic assistant message and flows directly to `thread.isRunning`, so the thread stays in a running state even after the last assistant message has completed (e.g. while suggestions or metadata chunks are still arriving). When omitted, `thread.isRunning` falls back to the last-message-status heuristic.",
       default: "false",
     },
     {

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

@@ -501,26 +501,69 @@ export function MyRuntimeProvider({ children }) {
               const { remoteId } = aui.threadListItem().getState();
               if (!remoteId) return { messages: [] };
 
-              const messages = await db.messages.findByThreadId(remoteId);
+              const rows = await db.messages.findByThreadId(remoteId);
               return {
-                messages: messages.map((m) => ({
-                  role: m.role,
-                  content: m.content,
-                  id: m.id,
-                  createdAt: new Date(m.createdAt),
-                })),
+                messages: rows.map((row) => {
+                  const common = {
+                    id: row.id,
+                    createdAt: new Date(row.createdAt),
+                  };
+                  // `content` is stored as JSON — parse back into message parts
+                  const content = JSON.parse(row.content);
+
+                  if (row.role === "user") {
+                    return {
+                      parentId: row.parentId,
+                      message: {
+                        ...common,
+                        role: "user" as const,
+                        content,
+                        attachments: [],
+                        metadata: { custom: {} },
+                      },
+                    };
+                  }
+                  if (row.role === "assistant") {
+                    return {
+                      parentId: row.parentId,
+                      message: {
+                        ...common,
+                        role: "assistant" as const,
+                        content,
+                        status: { type: "complete", reason: "stop" } as const,
+                        metadata: {
+                          custom: {},
+                          unstable_state: null,
+                          unstable_annotations: [],
+                          unstable_data: [],
+                          steps: [],
+                        },
+                      },
+                    };
+                  }
+                  return {
+                    parentId: row.parentId,
+                    message: {
+                      ...common,
+                      role: "system" as const,
+                      content,
+                      metadata: { custom: {} },
+                    },
+                  };
+                }),
               };
             },
 
-            async append(message) {
+            async append({ message, parentId }) {
               // Wait for initialization to get remoteId (safe to call multiple times)
               const { remoteId } = await aui.threadListItem().initialize();
 
               await db.messages.create({
                 threadId: remoteId,
-                role: message.role,
-                content: message.content,
+                parentId,
                 id: message.id,
+                role: message.role,
+                content: JSON.stringify(message.content),
                 createdAt: message.createdAt,
               });
             },
@@ -584,10 +627,10 @@ const aui = useAui();
 
 const history = useMemo<ThreadHistoryAdapter>(
   () => ({
-    async append(message) {
+    async append({ message, parentId }) {
       // Wait for initialization - safe to call multiple times
       const { remoteId } = await aui.threadListItem().initialize();
-      await db.messages.create({ threadId: remoteId, ...message });
+      await db.messages.create({ threadId: remoteId, parentId, ...message });
     },
     // ...
   }),
@@ -613,8 +656,9 @@ interface ThreadRecord {
 interface MessageRecord {
   id: string;
   threadId: string;
+  parentId: string | null;
   role: "user" | "assistant" | "system";
-  content: any; // Store as JSON
+  content: string; // JSON-encoded message content parts
   createdAt: Date;
 }
 ```
@@ -693,18 +737,21 @@ Persist and resume conversations:
 ```tsx
 const historyAdapter: ThreadHistoryAdapter = {
   async load() {
-    // Load messages from your storage
+    // Load messages from your storage.
+    // The API must return `{ messages: { parentId, message }[] }`
+    // where each `message` is a full ThreadMessage
+    // (including `metadata.custom`, plus `attachments` on user messages
+    // and `status` + the rest of `metadata` on assistant messages).
     const response = await fetch(`/api/thread/current`);
-    const { messages } = await response.json();
-    return { messages };
+    return await response.json();
   },
 
-  async append(message) {
+  async append({ message, parentId }) {
     // Save new message to storage
     await fetch(`/api/thread/messages`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ message }),
+      body: JSON.stringify({ message, parentId }),
     });
   },
 

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

@@ -317,6 +317,64 @@ function AuthUI() {
 
 `AdkAuthCredential` supports all ADK auth types: `apiKey`, `http`, `oauth2`, `openIdConnect`, `serviceAccount`.
 
+### Input Requests
+
+When an ADK Python 2.0+ Workflow's `RequestInput` node pauses execution to ask the user a question, ADK emits an `adk_request_input` function call marked as long-running. Respond with `useAdkSubmitInput` inside a tool UI — the helper wraps the answer as `{ result }` to match ADK's `unwrap_response` contract, so the Workflow node resumes with the unwrapped value:
+
+```tsx
+import { makeAssistantToolUI } from "@assistant-ui/react";
+import { useAdkSubmitInput } from "@assistant-ui/react-google-adk";
+
+type RequestInputArgs = {
+  interrupt_id?: string;
+  message?: string;
+  payload?: unknown;
+  response_schema?: unknown;
+};
+
+export const RequestInputToolUI = makeAssistantToolUI<RequestInputArgs, unknown>({
+  toolName: "adk_request_input",
+  render: function RequestInputUI({ toolCallId, args, result }) {
+    const submitInput = useAdkSubmitInput();
+
+    if (result !== undefined) {
+      return <p>Answered: {String(result)}</p>;
+    }
+
+    return (
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          const value = (
+            e.currentTarget.elements.namedItem("answer") as HTMLInputElement
+          ).value;
+          submitInput(toolCallId, value);
+        }}
+      >
+        <p>{args.message ?? "Please provide input:"}</p>
+        <input name="answer" autoFocus />
+        <button type="submit">Submit</button>
+      </form>
+    );
+  },
+});
+```
+
+Register the tool UI inside `AssistantRuntimeProvider`:
+
+```tsx
+<AssistantRuntimeProvider runtime={runtime}>
+  <RequestInputToolUI />
+  <Thread />
+</AssistantRuntimeProvider>
+```
+
+<Callout type="info">
+  `adk_request_input` is emitted only by ADK Python 2.0+ Workflow `RequestInput` nodes — ADK JS has no equivalent. Always respond via a tool UI with `useAdkSubmitInput`; HITL interrupts are automatically exempt from `autoCancelPendingToolCalls`, so typing a normal message in the composer will not overwrite the pending interrupt.
+</Callout>
+
+`useAdkSubmitInput` is sugar over the generic `addResult` — if you prefer, you can call `addResult({ result: value })` from inside the render function directly. The `{ result }` wrapper is required either way: the adapter JSON-stringifies the value before sending, and ADK's `unwrap_response` unwraps it on the backend before the Workflow node resumes.
+
 ### Artifacts
 
 Track file artifacts created or modified by the agent:
@@ -384,6 +442,8 @@ function PendingToolsIndicator() {
 }
 ```
 
+This hook reports every tool call ADK marked via `long_running_tool_ids`, including HITL interrupts. To respond to a specific HITL type, see [Tool Confirmations](#tool-confirmations), [Auth Requests](#auth-requests), or [Input Requests](#input-requests).
+
 ### Per-Message Metadata
 
 Access grounding, citation, and token usage metadata per message:
@@ -581,6 +641,7 @@ The resolved `checkpointId` is passed to your `stream` callback via `config.chec
 | `useAdkSend()` | Send raw ADK messages |
 | `useAdkConfirmTool()` | Confirm or deny a pending tool confirmation |
 | `useAdkSubmitAuth()` | Submit auth credentials for a pending auth request |
+| `useAdkSubmitInput()` | Submit the user's answer for a pending `adk_request_input` HITL interrupt |
 | `useAdkToolConfirmations()` | Pending tool confirmation requests |
 | `useAdkAuthRequests()` | Pending auth credential requests |
 | `useAdkLongRunningToolIds()` | IDs of long-running tools awaiting input |
@@ -596,6 +657,7 @@ The resolved `checkpointId` is passed to your `stream` callback via `config.chec
 | Tool calls & results | Supported |
 | Tool confirmations (`useAdkConfirmTool`) | Supported |
 | Auth credential flow (`useAdkSubmitAuth`) | Supported |
+| Workflow input requests (`useAdkSubmitInput`, ADK Python 2.0+) | Supported |
 | Multi-agent (author/branch tracking) | Supported |
 | Agent transfer events | Supported |
 | Escalation detection | Supported |

package/.docs/raw/docs/runtimes/langchain/comparison.mdx

@@ -0,0 +1,60 @@
+---
+title: Comparison with `react-langgraph`
+description: How `@assistant-ui/react-langchain` differs from `@assistant-ui/react-langgraph`.
+---
+
+Both packages connect assistant-ui to LangGraph backends. They are **independent adapters for different upstream libraries** — one is not a successor to the other.
+
+| Aspect                         | `@assistant-ui/react-langgraph`                              | `@assistant-ui/react-langchain`                       |
+| ------------------------------ | ------------------------------------------------------------ | ----------------------------------------------------- |
+| Wraps                          | `@langchain/langgraph-sdk` (raw SDK)                         | `@langchain/react` (`useStream` hook)                 |
+| Age                            | Sept 2024 onward                                             | April 2026 onward                                     |
+| Version                        | `0.13.x`                                                     | `0.0.x`                                               |
+| Lines of source                | ~7,500                                                       | ~600                                                  |
+| Built on                       | `useExternalStoreRuntime`                                    | `useExternalStoreRuntime`                             |
+| `create-assistant-ui` template | `-t langgraph` ships this package                            | No template yet                                       |
+
+## Feature coverage
+
+| Feature                                 | `react-langgraph`                | `react-langchain`                   |
+| --------------------------------------- | -------------------------------- | ----------------------------------- |
+| Stream messages                         | ✅ `useLangGraphRuntime`          | ✅ `useStreamRuntime`                |
+| Interrupt state                         | ✅ `useLangGraphInterruptState`   | ✅ `useLangChainInterruptState`      |
+| Send raw state update / resume command  | ✅ `useLangGraphSendCommand`      | ✅ `useLangChainSubmit`              |
+| Read arbitrary custom state key         | ❌                                | ✅ `useLangChainState<T>(key)`       |
+| Per-message metadata (`messages-tuple`) | ✅ `useLangGraphMessageMetadata`  | ❌ not exposed                       |
+| Generative UI messages (LangSmith)      | ✅ `useLangGraphUIMessages`       | ❌ not exposed                       |
+| Subgraph / namespaced stream events     | ✅ via `eventHandlers`            | ❌ not exposed                       |
+| End-to-end cancellation primitive       | ✅ `unstable_createLangGraphStream` | ❌ not exposed                     |
+| Message accumulator utility             | ✅ `LangGraphMessageAccumulator`  | ❌ not exposed                       |
+| Cloud thread persistence                | ✅ `cloud` option                 | ✅ `cloud` option                    |
+
+`react-langchain` is the newer, thinner wrapper — it delegates to the upstream `useStream` hook rather than re-implementing the stream plumbing. That is why its footprint is smaller and its surface area is narrower today. Features that exist in `react-langgraph` but not `react-langchain` are absent because they have not yet been ported, not because they are deprecated.
+
+## Choosing between them
+
+Use `@assistant-ui/react-langgraph` when:
+
+- You are scaffolding via `npx create-assistant-ui -t langgraph`.
+- You want the broader feature set today (subgraph events, UI messages, message metadata, cancellation).
+- You prefer integrating with `@langchain/langgraph-sdk` directly.
+
+Use `@assistant-ui/react-langchain` when:
+
+- Your app already depends on `@langchain/react` and uses `useStream` elsewhere.
+- You want to read custom state keys (`todos`, `files`, plans, ...) with `useLangChainState<T>(key)` without reconstructing them from tool-call streams.
+- You prefer a thin wrapper that stays pinned to upstream behavior.
+
+## Hook name mapping
+
+If you are moving code between the two adapters, most hooks have a counterpart — but note the feature gaps above.
+
+| `react-langgraph`                  | `react-langchain`                   | Notes                                                       |
+| ---------------------------------- | ----------------------------------- | ----------------------------------------------------------- |
+| `useLangGraphRuntime`              | `useStreamRuntime`                  | Options extend upstream `UseStreamOptions`; no `stream` / `create` / `load` to write. |
+| `useLangGraphInterruptState`       | `useLangChainInterruptState`        | Same return shape: `{ value?: unknown } \| undefined`.      |
+| `useLangGraphSendCommand`          | `useLangChainSubmit`                | `submit(values, { command })` replaces the dedicated hook.  |
+| `useLangGraphSend`                 | _(use `runtime.thread.append`)_     | No direct equivalent; send turns through the runtime.       |
+| `useLangGraphMessageMetadata`      | _(not available)_                   | Open an issue if you rely on this.                          |
+| `useLangGraphUIMessages`           | _(not available)_                   | Open an issue if you rely on this.                          |
+| _(none)_                           | `useLangChainState<T>(key)`         | New — reads any custom state key reactively.                |

package/.docs/raw/docs/runtimes/langchain/index.mdx

@@ -0,0 +1,210 @@
+---
+title: Getting Started
+description: Adapter for LangChain's `useStream` hook, exposed as an assistant-ui runtime.
+---
+
+`@assistant-ui/react-langchain` wraps [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` and exposes it as an assistant-ui runtime. Use this package if you are already integrating your app with `@langchain/react` and want assistant-ui on top of the upstream hook.
+
+<Callout type="info">
+  assistant-ui ships two adapters for LangGraph backends:
+  - **[`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph)** integrates with `@langchain/langgraph-sdk` directly and exposes features like subgraph events, UI messages, message metadata, and end-to-end cancellation.
+  - **`@assistant-ui/react-langchain`** (this page) wraps `@langchain/react`'s `useStream`. It is lighter-weight and stays aligned with upstream, but currently does not expose every `react-langgraph` feature.
+
+  See [the comparison doc](/docs/runtimes/langchain/comparison) for a feature gap table.
+</Callout>
+
+## Requirements
+
+You need a LangGraph Cloud API server. You can start a server locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or use [LangSmith](https://www.langchain.com/langsmith) for a hosted version.
+
+The state of the graph you are using must have a `messages` key with a list of LangChain-alike messages (or pass a custom `messagesKey`).
+
+## Installation
+
+<Steps>
+  <Step>
+
+### Install dependencies
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langchain", "@langchain/react", "@langchain/langgraph-sdk"]} />
+
+  </Step>
+  <Step>
+
+### Define a `MyAssistant` component
+
+```tsx title="@/components/MyAssistant.tsx"
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useStreamRuntime } from "@assistant-ui/react-langchain";
+
+export function MyAssistant() {
+  const runtime = useStreamRuntime({
+    assistantId: process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
+    apiUrl: process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"],
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+  <Step>
+
+### Use the `MyAssistant` component
+
+```tsx title="@/app/page.tsx"
+import { MyAssistant } from "@/components/MyAssistant";
+
+export default function Home() {
+  return (
+    <main className="h-dvh">
+      <MyAssistant />
+    </main>
+  );
+}
+```
+
+  </Step>
+  <Step>
+
+### Set environment variables
+
+Create a `.env.local` file in your project with the following variables:
+
+```sh
+NEXT_PUBLIC_LANGGRAPH_API_URL=http://localhost:2024
+NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+  </Step>
+  <Step>
+
+### Set up UI components
+
+Follow the [UI Components](/docs/ui/thread) guide to set up the UI components.
+
+  </Step>
+</Steps>
+
+## `useStreamRuntime` options
+
+`useStreamRuntime` accepts every option [`useStream`](https://docs.langchain.com/oss/javascript/langgraph-sdk/react-stream) from `@langchain/react` does, plus three assistant-ui-specific fields:
+
+| Option        | Type                                           | Description                                                              |
+| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
+| `cloud`       | `AssistantCloud`                               | Optional — persists threads via assistant-cloud.                         |
+| `adapters`    | `{ attachments?, speech?, feedback? }`         | Optional — attachment, speech, and feedback adapters.                    |
+| `messagesKey` | `string`                                       | The state key that holds messages. Defaults to `"messages"`.             |
+
+## Reading custom state keys
+
+LangGraph agents often expose structured state beyond messages (plans, todos, scratch files, generative-UI artifacts). Read them directly with `useLangChainState`. It mirrors `useStream().values[key]` upstream and updates when the stream emits new state.
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+
+type Todo = { id: string; title: string; done: boolean };
+
+function TodoList() {
+  const todos = useLangChainState<Todo[]>("todos", []);
+
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>
+          {t.done ? "✓" : "○"} {t.title}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Signatures:
+
+```ts
+useLangChainState<T>(key: string): T | undefined;
+useLangChainState<T>(key: string, defaultValue: T): T;
+```
+
+This hook is especially useful with the [`deepagents`](https://docs.langchain.com/oss/python/deepagents) middleware, whose `write_todos` step updates `state.todos` alongside the tool-call stream. Reading the state key directly avoids reconstructing the list from partial tool-call args.
+
+<Callout type="info">
+  Added in v0.0.2 — see issue [#3862](https://github.com/assistant-ui/assistant-ui/issues/3862) for motivation.
+</Callout>
+
+## Interrupts
+
+LangGraph interrupts pause the graph and wait for client input. `useLangChainInterruptState` exposes the current interrupt; `useLangChainSubmit` resumes the graph with a raw state update.
+
+```tsx
+import {
+  useLangChainInterruptState,
+  useLangChainSubmit,
+} from "@assistant-ui/react-langchain";
+import { Command } from "@langchain/langgraph-sdk";
+
+function InterruptPrompt() {
+  const interrupt = useLangChainInterruptState();
+  const submit = useLangChainSubmit();
+
+  if (!interrupt) return null;
+
+  return (
+    <div>
+      <pre>{JSON.stringify(interrupt.value, null, 2)}</pre>
+      <button
+        onClick={() =>
+          submit(null, { command: new Command({ resume: "approved" }) })
+        }
+      >
+        Approve
+      </button>
+    </div>
+  );
+}
+```
+
+## Message conversion
+
+`convertLangChainBaseMessage` transforms a LangChain `BaseMessage` into an assistant-ui message. Use it when building a custom `ExternalStoreAdapter` that needs to consume LangChain messages outside of `useStreamRuntime`.
+
+```ts
+import { convertLangChainBaseMessage } from "@assistant-ui/react-langchain";
+```
+
+## Cloud persistence
+
+Pass an `AssistantCloud` instance to persist threads across sessions. The runtime automatically wires thread list management and resumes state from the cloud.
+
+```tsx
+import { AssistantCloud } from "assistant-cloud";
+import { useStreamRuntime } from "@assistant-ui/react-langchain";
+
+const cloud = new AssistantCloud({ baseUrl: "/api/cloud" });
+
+const runtime = useStreamRuntime({
+  cloud,
+  assistantId: "agent",
+  apiUrl: "http://localhost:2024",
+});
+```
+
+## Custom `messagesKey`
+
+If your graph stores messages under a non-default key, pass `messagesKey` so the runtime submits tool results and human turns to the correct state slot:
+
+```tsx
+const runtime = useStreamRuntime({
+  assistantId: "agent",
+  apiUrl: "http://localhost:2024",
+  messagesKey: "chat_messages",
+});
+```