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

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

@@ -0,0 +1,533 @@
+---
+title: LangChain useStream
+description: Lighter-weight LangGraph adapter that wraps @langchain/react's useStream hook.
+---
+
+import { LangGraphIcon } from "@/components/icons/langgraph";
+
+`@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. It targets the same backend as [`@assistant-ui/react-langgraph`](/docs/runtimes/langgraph) (LangGraph Cloud) but at a higher level, delegating stream plumbing to the upstream hook.
+
+## When to use it
+
+Pick `react-langchain` over `react-langgraph` when:
+
+- Your app already depends on `@langchain/react` and uses `useStream` elsewhere.
+- You want to read custom state keys (`todos`, `files`, plans) reactively with `useLangChainState<T>(key)`.
+- You prefer a thin wrapper that stays pinned to upstream behavior.
+
+Pick `react-langgraph` instead when:
+
+- You are scaffolding via `npx create-assistant-ui -t langgraph` (the template uses it).
+- You need subgraph events, generative UI messages, message metadata, or end-to-end cancellation today.
+
+Both adapters are first-class. `react-langchain` is newer and thinner; some features have not been ported yet (the [comparison](#comparison-with-react-langgraph) below has the full table).
+
+## Architecture
+
+`@assistant-ui/react-langchain` 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) work the same way described in [adapters](/docs/runtimes/concepts/adapters). Cloud thread persistence is built in.
+
+## Requirements
+
+- A LangGraph Cloud API server (locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith)).
+- The graph state must include a `messages` key with LangChain-alike messages, or pass a custom `messagesKey`.
+
+## Quickstart
+
+<Steps>
+<Step>
+
+### Install dependencies
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langchain", "@langchain/react", "@langchain/langgraph-sdk"]} />
+
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-langchain", "@langchain/react", "@langchain/langgraph-sdk"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-langchain", "@langchain/react", "@langchain/langgraph-sdk", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Define the assistant component
+
+<PlatformTabs>
+<Tab value="React">
+
+```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>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/MyAssistant.tsx"
+import { Thread } from "@/components/assistant-ui/thread";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import { useStreamRuntime } from "@assistant-ui/react-langchain";
+
+export function MyAssistant() {
+  const runtime = useStreamRuntime({
+    assistantId: process.env.EXPO_PUBLIC_LANGGRAPH_ASSISTANT_ID!,
+    apiUrl: process.env.EXPO_PUBLIC_LANGGRAPH_API_URL,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="components/MyAssistant.tsx"
+import { Thread } from "./thread.js";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { useStreamRuntime } from "@assistant-ui/react-langchain";
+
+export function MyAssistant() {
+  const runtime = useStreamRuntime({
+    assistantId: process.env.LANGGRAPH_ASSISTANT_ID!,
+    apiUrl: process.env.LANGGRAPH_API_URL,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Mount the component
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="@/app/page.tsx"
+import { MyAssistant } from "@/components/MyAssistant";
+
+export default function Home() {
+  return (
+    <main className="h-dvh">
+      <MyAssistant />
+    </main>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="app/index.tsx"
+import { View } from "react-native";
+import { MyAssistant } from "@/components/MyAssistant";
+
+export default function Home() {
+  return (
+    <View style={{ flex: 1 }}>
+      <MyAssistant />
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="app.tsx"
+import { Box } from "ink";
+import { MyAssistant } from "./components/MyAssistant.js";
+
+export function App() {
+  return (
+    <Box flexDirection="column">
+      <MyAssistant />
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set environment variables
+
+<PlatformTabs>
+<Tab value="React">
+
+```sh title=".env.local"
+NEXT_PUBLIC_LANGGRAPH_API_URL=http://localhost:2024
+NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+</Tab>
+<Tab value="React Native">
+
+```sh title=".env"
+EXPO_PUBLIC_LANGGRAPH_API_URL=http://localhost:2024
+EXPO_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```sh title=".env"
+LANGGRAPH_API_URL=http://localhost:2024
+LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set up UI components
+
+<PlatformTabs>
+<Tab value="React">
+
+Follow the [UI Components guide](/docs/ui/thread).
+
+</Tab>
+<Tab value="React Native">
+
+Follow the [React Native setup](/docs/react-native).
+
+</Tab>
+<Tab value="React Ink">
+
+Follow the [Ink setup](/docs/ink).
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+</Steps>
+
+## `useStreamRuntime` options
+
+`useStreamRuntime` accepts every option upstream `useStream` 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.
+
+<PlatformTabs>
+<Tab value="React">
+
+```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>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+import { Text, View } from "react-native";
+
+type Todo = { id: string; title: string; done: boolean };
+
+function TodoList() {
+  const todos = useLangChainState<Todo[]>("todos", []);
+  return (
+    <View>
+      {todos.map((t) => (
+        <Text key={t.id}>
+          {t.done ? "✓" : "○"} {t.title}
+        </Text>
+      ))}
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+import { Box, Text } from "ink";
+
+type Todo = { id: string; title: string; done: boolean };
+
+function TodoList() {
+  const todos = useLangChainState<Todo[]>("todos", []);
+  return (
+    <Box flexDirection="column">
+      {todos.map((t) => (
+        <Text key={t.id}>
+          {t.done ? "✓" : "○"} {t.title}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+Signatures:
+
+```ts
+useLangChainState<T>(key: string): T | undefined;
+useLangChainState<T>(key: string, defaultValue: T): T;
+```
+
+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.
+
+<PlatformTabs>
+<Tab value="React">
+
+```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>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx
+import {
+  useLangChainInterruptState,
+  useLangChainSubmit,
+} from "@assistant-ui/react-langchain";
+import { Command } from "@langchain/langgraph-sdk";
+import { Pressable, Text, View } from "react-native";
+
+function InterruptPrompt() {
+  const interrupt = useLangChainInterruptState();
+  const submit = useLangChainSubmit();
+  if (!interrupt) return null;
+  return (
+    <View>
+      <Text>{JSON.stringify(interrupt.value, null, 2)}</Text>
+      <Pressable
+        onPress={() =>
+          submit(null, { command: new Command({ resume: "approved" }) })
+        }
+      >
+        <Text>Approve</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx
+import {
+  useLangChainInterruptState,
+  useLangChainSubmit,
+} from "@assistant-ui/react-langchain";
+import { Command } from "@langchain/langgraph-sdk";
+import { Box, Text, useInput } from "ink";
+
+function InterruptPrompt() {
+  const interrupt = useLangChainInterruptState();
+  const submit = useLangChainSubmit();
+
+  useInput((input) => {
+    if (!interrupt || input !== "a") return;
+    submit(null, { command: new Command({ resume: "approved" }) });
+  });
+
+  if (!interrupt) return null;
+  return (
+    <Box flexDirection="column">
+      <Text>{JSON.stringify(interrupt.value, null, 2)}</Text>
+      <Text>Press a to approve.</Text>
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+## Message conversion
+
+`convertLangChainBaseMessage` transforms a LangChain `BaseMessage` into an assistant-ui message. Use it when building a custom `ExternalStoreAdapter` that consumes LangChain messages outside `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
+// see "AssistantCloud" in /docs/runtimes/concepts/threads for cloud setup
+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",
+});
+```
+
+## Comparison with `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 | `react-langgraph` | `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` | No template yet |
+
+### Feature coverage
+
+| Feature | `react-langgraph` | `react-langchain` |
+| --- | --- | --- |
+| Stream messages | Yes (`useLangGraphRuntime`) | Yes (`useStreamRuntime`) |
+| Interrupt state | Yes | Yes |
+| Send raw state update / resume command | Yes | Yes (`useLangChainSubmit`) |
+| Read arbitrary custom state key | No | Yes (`useLangChainState<T>(key)`) |
+| Per-message metadata (`messages-tuple`) | Yes | Not exposed |
+| Generative UI messages (LangSmith) | Yes | Not exposed |
+| Subgraph / namespaced stream events | Yes (via `eventHandlers`) | Not exposed |
+| End-to-end cancellation primitive | Yes (`unstable_createLangGraphStream`) | Not exposed |
+| Message accumulator utility | Yes (`LangGraphMessageAccumulator`) | Not exposed |
+| Cloud thread persistence | Yes | Yes |
+
+`react-langchain` is the newer, thinner wrapper. It delegates to upstream `useStream` rather than re-implementing the stream plumbing, which is why its footprint is smaller. Features absent today have not been ported, not deprecated.
+
+### Hook name mapping
+
+| `react-langgraph` | `react-langchain` | Notes |
+| --- | --- | --- |
+| `useLangGraphRuntime` | `useStreamRuntime` | Options extend upstream `UseStreamOptions`; no `stream` / `create` / `load` to write. |
+| `useLangGraphInterruptState` | `useLangChainInterruptState` | Same return shape. |
+| `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. |
+
+## Related
+
+<Cards>
+  <Card
+    icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
+    title="LangGraph"
+    description="The full-featured adapter with subgraph events, UI messages, metadata."
+    href="/docs/runtimes/langgraph"
+  />
+  <Card
+    title="ExternalStoreRuntime"
+    description="The core runtime react-langchain is built on."
+    href="/docs/runtimes/custom/external-store"
+  />
+</Cards>