@assistant-ui/mcp-docs-server 0.1.9 → 0.1.10

package/.docs/raw/docs/migrations/react-langgraph-v0-7.mdx

@@ -0,0 +1,324 @@
+---
+title: Migrating to react-langgraph v0.7
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Steps, Step } from "fumadocs-ui/components/steps";
+
+## Overview
+
+This guide helps you migrate from the previous LangGraph integration pattern to the new simplified API introduced in `@assistant-ui/react-langgraph` v0.7. The new API consolidates thread management directly into `useLangGraphRuntime`, eliminating the need for separate runtime hooks and manual thread state management.
+
+## Key Changes
+
+### 1. Simplified Thread Management
+
+The `useLangGraphRuntime` hook now directly handles thread lifecycle:
+- No more `useRemoteThreadListRuntime` wrapper
+- No more separate runtime hook functions
+- Thread management is built into the core runtime
+
+### 2. New `initialize` Parameter
+
+The `stream` function now receives an `initialize` parameter that handles thread creation and loading automatically.
+
+### 3. Direct Cloud Integration
+
+Cloud persistence can now be configured directly in `useLangGraphRuntime` with the `cloud` parameter.
+
+## Migration Steps
+
+<Steps>
+
+<Step>
+
+### Update Your Runtime Implementation
+
+#### Before (Old Pattern)
+
+```tsx
+import {
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const useMyLangGraphRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+
+  const runtime = useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
+    onSwitchToThread: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages: state.values.messages,
+      };
+    },
+  });
+
+  return runtime;
+};
+
+// In your component:
+const runtime = useCloudThreadListRuntime({
+  cloud,
+  runtimeHook: useMyLangGraphRuntime,
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+});
+```
+
+#### After (New Pattern)
+
+```tsx
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+// Directly in your component:
+const runtime = useLangGraphRuntime({
+  cloud, // Optional: for cloud persistence
+  stream: async function* (messages, { initialize }) {
+    const { externalId } = await initialize();
+    if (!externalId) throw new Error("Thread not found");
+
+    return sendMessage({
+      threadId: externalId,
+      messages,
+    });
+  },
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+    };
+  },
+});
+```
+
+</Step>
+
+<Step>
+
+### Update Import Statements
+
+Remove unused imports:
+
+```diff
+- import {
+-   useCloudThreadListRuntime,
+-   useThreadListItemRuntime,
+- } from "@assistant-ui/react";
++ import { AssistantCloud } from "@assistant-ui/react";
+```
+
+</Step>
+
+<Step>
+
+### Simplify Component Structure
+
+You no longer need a separate runtime hook function. Everything can be defined directly in your component or provider:
+
+```tsx
+export function MyRuntimeProvider({ children }) {
+  const cloud = useMemo(
+    () => new AssistantCloud({
+      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
+    }),
+    []
+  );
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    // All configuration inline
+    stream: async function* (messages, { initialize }) {
+      // Your stream implementation
+    },
+    create: async () => {
+      // Your create implementation
+    },
+    load: async (externalId) => {
+      // Your load implementation
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+
+<Step>
+
+### Update Method Names
+
+Rename methods to match the new API:
+
+- `onSwitchToThread` → `load`
+- `onSwitchToNewThread` → handled automatically via `create`
+- Thread ID management is now automatic
+
+</Step>
+
+</Steps>
+
+## API Reference Changes
+
+### Old API
+
+```typescript
+type OldLangGraphRuntimeOptions = {
+  threadId?: string;
+  stream: (messages: Message[]) => AsyncGenerator;
+  onSwitchToNewThread?: () => Promise<void>;
+  onSwitchToThread?: (threadId: string) => Promise<ThreadState>;
+};
+```
+
+### New API
+
+```typescript
+type NewLangGraphRuntimeOptions = {
+  cloud?: AssistantCloud;
+  stream: (
+    messages: Message[],
+    context: {
+      initialize: () => Promise<{
+        remoteId: string;
+        externalId: string | undefined;
+      }>
+    }
+  ) => AsyncGenerator;
+  create?: () => Promise<{ externalId: string }>;
+  load?: (externalId: string) => Promise<ThreadState>;
+  delete?: (externalId: string) => Promise<void>;
+};
+```
+
+## Benefits of the New API
+
+1. **Simpler Setup**: No need for multiple runtime hooks and wrappers
+2. **Cleaner Code**: All configuration in one place
+3. **Better Type Safety**: More explicit types for thread management
+4. **Automatic Thread Handling**: The runtime manages thread lifecycle internally
+5. **Optional Cloud Integration**: Add cloud persistence with a single parameter
+
+## Common Migration Issues
+
+<Callout type="warning">
+  **Breaking Change**: The `threadId` and `onSwitchToNewThread` parameters are no longer supported. Use the new `create` and `load` methods instead.
+</Callout>
+
+### Issue: `threadListItemRuntime` is not defined
+
+**Solution**: Remove references to `useThreadListItemRuntime()`. Use the `initialize` parameter in the stream function instead.
+
+### Issue: Thread switching doesn't work
+
+**Solution**: Ensure you've implemented both `create` and `load` functions. The runtime needs both to manage thread lifecycle.
+
+### Issue: Cloud persistence not working
+
+**Solution**: Pass the `AssistantCloud` instance directly to `useLangGraphRuntime` via the `cloud` parameter.
+
+## Example: Complete Migration
+
+Here's a complete before and after example for a typical LangGraph integration:
+
+### Before
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const useMyRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+
+  return useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      // ... implementation
+    },
+    onSwitchToThread: async (externalId) => {
+      // ... implementation
+    },
+  });
+};
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useCloudThreadListRuntime({
+    cloud,
+    runtimeHook: useMyRuntime,
+    create: async () => { /* ... */ },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### After
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      // ... implementation
+    },
+    create: async () => { /* ... */ },
+    load: async (externalId) => {
+      // ... implementation (formerly onSwitchToThread)
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Need Help?
+
+If you encounter issues during migration:
+1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
+2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
+3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)

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

@@ -61,7 +61,6 @@ npm install @assistant-ui/react @assistant-ui/react-ui @assistant-ui/react-langg
 ```tsx twoslash title="@/api/api/[...path]/route.ts"
 import { NextRequest, NextResponse } from "next/server";
 
-
 function getCorsHeaders() {
   return {
     "Access-Control-Allow-Origin": "*",
@@ -188,7 +187,6 @@ export const sendMessage = async (params: {
 // ---cut---
 "use client";
 
-import { useRef } from "react";
 import { Thread } from "@/components/assistant-ui";
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
@@ -196,27 +194,21 @@ import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
 import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
 
 export function MyAssistant() {
-  const threadIdRef = useRef<string | undefined>();
   const runtime = useLangGraphRuntime({
-    threadId: threadIdRef.current,
-    stream: async (messages) => {
-      if (!threadIdRef.current) {
-        const { thread_id } = await createThread();
-        threadIdRef.current = thread_id;
-      }
-      const threadId = threadIdRef.current;
+    stream: async (messages, { initialize }) => {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
       return sendMessage({
-        threadId,
+        threadId: externalId,
         messages,
       });
     },
-    onSwitchToNewThread: async () => {
+    create: async () => {
       const { thread_id } = await createThread();
-      threadIdRef.current = thread_id;
+      return { externalId: thread_id };
     },
-    onSwitchToThread: async (threadId) => {
-      const state = await getThreadState(threadId);
-      threadIdRef.current = threadId;
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
       return {
         messages: state.values.messages,
         interrupts: state.tasks[0]?.interrupts,
@@ -306,14 +298,57 @@ import { convertLangChainMessages } from "@assistant-ui/react-langgraph";
 const threadMessage = convertLangChainMessages(langChainMessage);
 ```
 
-## Interrupt Persistence
+## Thread Management
+
+### Basic Thread Support
+
+The `useLangGraphRuntime` hook now includes built-in thread management capabilities:
+
+```typescript
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize }) => {
+    // initialize() creates or loads a thread and returns its IDs
+    const { remoteId, externalId } = await initialize();
+    // Use externalId (your backend's thread ID) for API calls
+    return sendMessage({ threadId: externalId, messages });
+  },
+  create: async () => {
+    // Called when creating a new thread
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    // Called when loading an existing thread
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
 
-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. This means that if a user switches away from a thread during an interaction (like waiting for user approval), the interaction state will be preserved when they return to that thread.
+### Cloud Persistence
+
+For persistent thread history across sessions, integrate with assistant-cloud:
+
+```typescript
+const runtime = useLangGraphRuntime({
+  cloud: new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
+  }),
+  // ... stream, create, load functions
+});
+```
+
+See the [Cloud Persistence guide](/docs/cloud/persistence/langgraph) for detailed setup instructions.
+
+## Interrupt Persistence
 
-To handle interrupts in your application:
+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 `onSwitchToThread` along with the messages
+2. Return the interrupts from the `load` function along with the messages
 3. The runtime will automatically restore the interrupt state when switching threads
 
 This feature is particularly useful for applications that require user approval flows, multi-step forms, or any other interactive elements that might span multiple thread switches.