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

package/.docs/raw/docs/runtimes/langgraph/generative-ui.mdx

@@ -0,0 +1,305 @@
+---
+title: Generative UI
+description: Render structured UI components emitted by LangGraph alongside assistant messages.
+---
+
+LangGraph's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) lets your graph emit structured UI components alongside assistant messages via `push_ui_message` (Python) or `typedUi().push()` (TypeScript). The assistant-ui adapter translates these into [`DataMessagePart`s](/docs/guides/tool-ui) on the associated assistant message, which you render with the existing `makeAssistantDataUI` API.
+
+## Enable the `custom` stream mode
+
+UI messages are emitted through LangGraph's `custom` stream channel. Make sure your `sendMessage` helper includes `"custom"` in `streamMode`:
+
+```ts
+streamMode: ["messages", "updates", "custom"];
+```
+
+If your graph accumulates UI messages in state under the `ui` key (the default for `typedUi`), `"values"` also works; the adapter reads both paths.
+
+## Custom state key
+
+If your graph uses a non-default `stateKey` with `typedUi(config, { stateKey: "my_ui" })` on the server, pass the matching `uiStateKey` option to `useLangGraphRuntime`:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) {
+    /* ... */
+  },
+  uiStateKey: "my_ui",
+});
+```
+
+This only affects the `values` stream path; the `custom` channel carries each UI event individually and does not rely on the state key.
+
+## Emit a UI message from your graph
+
+<Tabs items={["Python", "TypeScript"]}>
+<Tab value="Python">
+
+```python
+from langgraph.graph.ui import push_ui_message
+from langchain_core.messages import AIMessage
+
+async def chart_node(state, config):
+    message = AIMessage(id="msg-1", content="Here's your chart.")
+    push_ui_message(
+        "chart",
+        {"series": [1, 2, 3], "title": "Sales"},
+        message=message,  # Links the UI to this AI message
+    )
+    return {"messages": [message]}
+```
+
+</Tab>
+<Tab value="TypeScript">
+
+```ts
+import { typedUi } from "@langchain/langgraph-sdk/react-ui/server";
+import type { ComponentRegistry } from "./components";
+
+export async function chartNode(state, config) {
+  const ui = typedUi<ComponentRegistry>(config);
+  const message = { id: "msg-1", type: "ai", content: "Here's your chart." };
+  ui.push(
+    { name: "chart", props: { series: [1, 2, 3], title: "Sales" } },
+    { message },
+  );
+  return { messages: [message] };
+}
+```
+
+</Tab>
+</Tabs>
+
+Passing `message` (Python) or `{ message }` (TypeScript) is what links the UI component to a specific assistant message. The adapter reads `metadata.message_id` to attach the generated `DataMessagePart` to the correct message in the thread.
+
+## Register a renderer on the client
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="@/components/ChartUI.tsx"
+import { makeAssistantDataUI } from "@assistant-ui/react";
+
+type ChartProps = {
+  series: number[];
+  title: string;
+};
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <div>
+      <h3>{data.title}</h3>
+      <Chart series={data.series} />
+    </div>
+  ),
+});
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/ChartUI.tsx"
+import { makeAssistantDataUI } from "@assistant-ui/react-native";
+import { Text, View } from "react-native";
+
+type ChartProps = {
+  series: number[];
+  title: string;
+};
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <View>
+      <Text>{data.title}</Text>
+      <Chart series={data.series} />
+    </View>
+  ),
+});
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="components/chart-ui.tsx"
+import { makeAssistantDataUI } from "@assistant-ui/react-ink";
+import { Box, Text } from "ink";
+
+type ChartProps = {
+  series: number[];
+  title: string;
+};
+
+export const ChartUI = makeAssistantDataUI<ChartProps>({
+  name: "chart",
+  render: ({ data }) => (
+    <Box flexDirection="column">
+      <Text bold>{data.title}</Text>
+      <Chart series={data.series} />
+    </Box>
+  ),
+});
+```
+
+</Tab>
+</PlatformTabs>
+
+Mount the component once somewhere inside the `AssistantRuntimeProvider` tree. It renders nothing itself; it only registers the renderer:
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="@/components/MyAssistant.tsx"
+<AssistantRuntimeProvider runtime={runtime}>
+  <ChartUI />
+  <Thread />
+</AssistantRuntimeProvider>
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/MyAssistant.tsx"
+import { View } from "react-native";
+import { Thread } from "@/components/assistant-ui/thread";
+
+<AssistantRuntimeProvider runtime={runtime}>
+  <ChartUI />
+  <View style={{ flex: 1 }}>
+    <Thread />
+  </View>
+</AssistantRuntimeProvider>;
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="components/my-assistant.tsx"
+import { Box } from "ink";
+import { Thread } from "./thread.js";
+
+<AssistantRuntimeProvider runtime={runtime}>
+  <ChartUI />
+  <Box flexDirection="column">
+    <Thread />
+  </Box>
+</AssistantRuntimeProvider>;
+```
+
+</Tab>
+</PlatformTabs>
+
+When a matching UI message arrives, the adapter appends a `{ type: "data", name: "chart", data: { series, title } }` part to the parent assistant message and the registered component renders inline.
+
+## Register renderers via `uiComponents`
+
+Instead of mounting separate `makeAssistantDataUI` components, register renderers directly on the runtime hook:
+
+```tsx
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) {
+    /* ... */
+  },
+  uiComponents: {
+    renderers: {
+      chart: ({ data }) => <Chart series={data.series} title={data.title} />,
+      table: ({ data }) => <DataTable rows={data.rows} />,
+    },
+  },
+});
+```
+
+Static `renderers` are matched by `ui_message` name. If no match is found, the part renders nothing unless a `fallback` is provided.
+
+## Dynamic loading with `fallback`
+
+LangSmith's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) supports colocating UI code with your graph and loading it at runtime via `LoadExternalComponent`. The `fallback` option handles any `ui_message` name that has no static renderer:
+
+```tsx
+import { LoadExternalComponent } from "@langchain/langgraph-sdk/react-ui";
+
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) {
+    /* ... */
+  },
+  uiComponents: {
+    fallback: ({ name, data }) => (
+      <LoadExternalComponent name={name} props={data} />
+    ),
+    renderers: {
+      chart: ({ data }) => <Chart {...data} />,
+    },
+  },
+});
+```
+
+With this setup:
+
+- A `ui_message` with `name: "chart"` renders the static `Chart` component.
+- Any other name (e.g. `"dashboard"`, `"form"`) is handled by `fallback`, which fetches the component from LangSmith at runtime.
+
+`fallback` receives the same props as any data renderer: `name`, `data`, and part state metadata.
+
+## Semantics
+
+The adapter mirrors the reducer in `@langchain/langgraph-sdk/react-ui` exactly:
+
+- UI messages are keyed by their own `id`. Pushing the same id again **replaces** the existing entry.
+- Passing `metadata: { merge: true }` shallow-merges `props` onto the previous entry.
+- Emitting `{ type: "remove-ui", id }` (via `delete_ui_message` or `ui.delete(id)`) removes the entry.
+- UI messages without `metadata.message_id` are held in the runtime but not injected into any message; use `useLangGraphUIMessages()` to access the raw list if needed.
+
+## Restore persisted UI messages on thread switch
+
+If your graph persists UI messages in state via `typedUi`, return them from the `load` callback so they are restored when the user switches threads or refreshes the page:
+
+```tsx
+const runtime = useLangGraphRuntime({
+  stream: async function* (messages, { initialize }) {
+    /* ... */
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      uiMessages: state.values.ui,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
+
+Without this, each reload starts with an empty UI list even though the messages themselves are loaded.
+
+## Escape hatch: `useLangGraphUIMessages`
+
+```tsx
+import { useLangGraphUIMessages } from "@assistant-ui/react-langgraph";
+
+function Sidebar() {
+  const uiMessages = useLangGraphUIMessages();
+  // Filter, group, or render UI messages outside the thread
+  return <>{uiMessages.map(/* ... */)}</>;
+}
+```
+
+## Related
+
+<Cards>
+  <Card
+    title="Streaming"
+    description="Event handlers, message accumulator, conversion, metadata."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Interrupts"
+    description="Interrupt persistence and checkpoint-based message editing."
+    href="/docs/runtimes/langgraph/interrupts"
+  />
+  <Card
+    title="Threads"
+    description="Basic thread support, AssistantCloud, custom thread list adapter."
+    href="/docs/runtimes/langgraph/threads"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/langgraph/interrupts.mdx

@@ -0,0 +1,104 @@
+---
+title: Interrupts and message editing
+description: Interrupt persistence and checkpoint-based message editing.
+---
+
+Both interrupt persistence and message editing rely on LangGraph's server-side checkpoints. Once you have one wired up, the other is mostly free.
+
+## Interrupt persistence
+
+LangGraph supports interrupting the execution flow to request user input or handle specific interactions. These interrupts can be persisted and restored when switching between threads:
+
+1. Make sure your thread state type includes the `interrupts` field.
+2. Return the interrupts from the `load` function along with the messages.
+3. The runtime automatically restores the interrupt state when switching threads.
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    /* ... */
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
+
+This is particularly useful for applications that require user approval flows, multi-step forms, or other interactive elements that span multiple thread switches.
+
+## Message editing and regeneration
+
+LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+    return sendMessage({ threadId: externalId, messages, config });
+  },
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+  getCheckpointId: async (threadId, parentMessages) => {
+    const client = createClient();
+    const history = await client.threads.getHistory(threadId);
+    for (const state of history) {
+      const stateMessages = state.values.messages;
+      if (!stateMessages || stateMessages.length !== parentMessages.length) {
+        continue;
+      }
+      const hasStableIds =
+        parentMessages.every((m) => typeof m.id === "string") &&
+        stateMessages.every((m) => typeof m.id === "string");
+      if (!hasStableIds) continue;
+
+      const isMatch = parentMessages.every(
+        (m, i) => m.id === stateMessages[i]?.id,
+      );
+      if (isMatch) {
+        return state.checkpoint.checkpoint_id ?? null;
+      }
+    }
+    return null;
+  },
+});
+```
+
+When `getCheckpointId` is provided:
+
+- **Edit buttons** appear on user messages, allowing users to edit and resend from that point.
+- **Regenerate buttons** appear on assistant messages, allowing users to regenerate the response.
+
+The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`. Your `sendMessage` helper should map it to the LangGraph SDK's `checkpoint_id` parameter (see [quickstart](/docs/runtimes/langgraph/quickstart) for the helper).
+
+<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>
+
+## Next
+
+<Cards>
+  <Card
+    title="Threads"
+    description="Basic thread support, AssistantCloud, custom thread list adapter."
+    href="/docs/runtimes/langgraph/threads"
+  />
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, generative UI."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+</Cards>

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

@@ -0,0 +1,84 @@
+---
+title: Overview
+description: Connect to LangGraph Cloud for agent workflows with streaming.
+---
+
+`@assistant-ui/react-langgraph` integrates with [`@langchain/langgraph-sdk`](https://docs.langchain.com/oss/javascript/langgraph-sdk) directly, exposing the full LangGraph Cloud feature set in assistant-ui: streaming, subgraph events, UI messages, message metadata, interrupts, and end-to-end cancellation.
+
+<Callout type="info">
+**Migrating from LangServe?** LangChain has deprecated `RemoteRunnable` upstream and consolidated the chain and agent execution stories under LangGraph. Rebuild your chain as a LangGraph graph (LangChain's [LangServe → LangGraph migration guide](https://github.com/langchain-ai/langserve/blob/main/MIGRATION.md) covers the shape change), deploy via LangGraph Cloud or self-host LangGraph Studio, and use this runtime on the frontend. The runtime ships streaming, interrupts, generative UI, message metadata, and end-to-end cancellation out of the box.
+</Callout>
+
+## When to use it
+
+Pick the LangGraph runtime when:
+
+- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
+- Your graph state has a `messages` key with LangChain-alike messages.
+- You want generative UI (`ui_message`), per-message metadata, subgraph events, or checkpoint-based message editing.
+
+<Callout type="info">
+If you are already using `@langchain/react`'s `useStream` hook, the alternative [`@assistant-ui/react-langchain`](/docs/runtimes/langchain) adapter may fit better. It delegates the stream plumbing to the upstream hook; the feature surface differs, see [LangChain useStream](/docs/runtimes/langchain) for the comparison table.
+</Callout>
+
+## Architecture
+
+`@assistant-ui/react-langgraph` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Graph state is the source of truth; the runtime renders messages from `state.values.messages` and submits user input back to the graph.
+
+Shared adapters (attachments, speech, feedback, history) work the same way described in [adapters](/docs/runtimes/concepts/adapters).
+
+## Requirements
+
+- A LangGraph Cloud API server.
+- React 18 or 19.
+- The graph state must include a `messages` key with LangChain-alike messages.
+
+## Install
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
+
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+## Next
+
+<Cards>
+  <Card
+    title="Quickstart"
+    description="From-template and manual setup paths to a working LangGraph chat."
+    href="/docs/runtimes/langgraph/quickstart"
+  />
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, generative UI."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Interrupts"
+    description="Interrupt persistence and checkpoint-based message editing."
+    href="/docs/runtimes/langgraph/interrupts"
+  />
+  <Card
+    title="Threads"
+    description="Basic thread support, AssistantCloud, custom thread list adapter."
+    href="/docs/runtimes/langgraph/threads"
+  />
+  <Card
+    title="Tutorial: Stockbroker"
+    description="End-to-end stockbroker assistant with generative UI and approval flows."
+    href="/docs/runtimes/langgraph/tutorial/introduction"
+  />
+</Cards>