@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/raw/docs/cloud/langgraph.mdx

@@ -1,554 +0,0 @@
----
-title: LangGraph + assistant-ui
-description: Integrate cloud persistence and thread management with LangGraph Cloud.
----
-
-
-## Overview
-
-This guide shows how to integrate Assistant Cloud with [LangGraph Cloud](https://docs.langchain.com/langsmith/deploy-to-cloud-overview) using assistant-ui's runtime system and pre-built UI components.
-
-## Prerequisites
-
-<Callout type="info">
-  You need an assistant-cloud account to follow this guide. [Sign up
-  here](https://cloud.assistant-ui.com/) to get started.
-</Callout>
-
-## Setup Guide
-
-<Steps>
-
-<Step>
-
-### Create a Cloud Project
-
-Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy:
-
-- **Frontend API URL**: `https://proj-[ID].assistant-api.com`
-- **API Key**: For server-side operations
-
-</Step>
-
-<Step>
-
-### Configure Environment Variables
-
-Add the following environment variables to your project:
-
-<PlatformTabs>
-<Tab value="React">
-
-```bash title=".env.local"
-# Frontend API URL from your cloud project settings
-NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
-
-# API key for server-side operations
-ASSISTANT_API_KEY=your-api-key-here
-```
-
-</Tab>
-<Tab value="React Native">
-
-```bash title=".env"
-# Client API URL from your cloud project settings
-EXPO_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
-
-# API key for server-side operations; do not ship this in your app bundle
-ASSISTANT_API_KEY=your-api-key-here
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```bash title=".env"
-# Client API URL from your cloud project settings
-ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
-
-# API key for server-side operations; do not ship this in your CLI bundle
-ASSISTANT_API_KEY=your-api-key-here
-```
-
-</Tab>
-</PlatformTabs>
-
-</Step>
-
-<Step>
-
-### Install Dependencies
-
-Install the required packages:
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-langgraph", "assistant-cloud"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-langgraph", "assistant-cloud", "ink", "react"]} />
-
-</Tab>
-</PlatformTabs>
-
-</Step>
-
-<Step>
-
-### Create the Runtime Provider
-
-Create a runtime provider that integrates LangGraph with assistant-cloud. Choose between anonymous mode for demos/prototypes or authenticated mode for production:
-
-<PlatformTabs>
-<Tab value="React">
-
-<Tabs items={["Anonymous", "Authenticated (Clerk)"]}>
-
-<Tab value="Anonymous">
-
-```tsx title="app/chat/runtime-provider.tsx"
-"use client";
-
-import {
-  AssistantCloud,
-  AssistantRuntimeProvider,
-} from "@assistant-ui/react";
-import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
-import { LangChainMessage } from "@assistant-ui/react-langgraph";
-import { useMemo } from "react";
-
-export function MyRuntimeProvider({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  const cloud = useMemo(
-    () =>
-      new AssistantCloud({
-        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
-        anonymous: true, // Creates browser session-based user ID
-      }),
-    [],
-  );
-
-  const runtime = useLangGraphRuntime({
-    cloud,
-    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 as { messages?: LangChainMessage[] }).messages ?? [],
-      };
-    },
-    delete: async (externalId) => {
-      await deleteThread(externalId);
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-
-<Tab value="Authenticated (Clerk)">
-
-```tsx title="app/chat/runtime-provider.tsx"
-"use client";
-
-import {
-  AssistantCloud,
-  AssistantRuntimeProvider,
-} from "@assistant-ui/react";
-import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
-import { LangChainMessage } from "@assistant-ui/react-langgraph";
-import { useAuth } from "@clerk/nextjs";
-import { useMemo } from "react";
-
-export function MyRuntimeProvider({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  const { getToken } = useAuth();
-
-  const cloud = useMemo(
-    () =>
-      new AssistantCloud({
-        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
-        authToken: async () => getToken({ template: "assistant-ui" }),
-      }),
-    [getToken],
-  );
-
-  const runtime = useLangGraphRuntime({
-    cloud,
-    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 as { messages?: LangChainMessage[] }).messages ?? [],
-      };
-    },
-    delete: async (externalId) => {
-      await deleteThread(externalId);
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-<Callout type="info">
-  For Clerk authentication, configure the `"assistant-ui"` token template in
-  your Clerk dashboard.
-</Callout>
-
-</Tab>
-
-</Tabs>
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="components/runtime-provider.tsx"
-import { useMemo, type ReactNode } from "react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import { AssistantCloud } from "assistant-cloud";
-import {
-  type LangChainMessage,
-  useLangGraphRuntime,
-} from "@assistant-ui/react-langgraph";
-import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
-
-async function getAssistantToken() {
-  // Return a user token from your auth provider.
-  return "...";
-}
-
-export function MyRuntimeProvider({ children }: { children: ReactNode }) {
-  const cloud = useMemo(
-    () =>
-      new AssistantCloud({
-        baseUrl: process.env.EXPO_PUBLIC_ASSISTANT_BASE_URL!,
-        authToken: getAssistantToken,
-      }),
-    [],
-  );
-
-  const runtime = useLangGraphRuntime({
-    cloud,
-    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 as { messages?: LangChainMessage[] }).messages ?? [],
-      };
-    },
-    delete: async (externalId) => {
-      await deleteThread(externalId);
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="runtime-provider.tsx"
-import { useMemo, type ReactNode } from "react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
-import { AssistantCloud } from "assistant-cloud";
-import {
-  type LangChainMessage,
-  useLangGraphRuntime,
-} from "@assistant-ui/react-langgraph";
-import { createThread, deleteThread, getThreadState, sendMessage } from "./chat-api.js";
-
-async function getAssistantToken() {
-  // Return a user token from your auth provider.
-  return "...";
-}
-
-export function MyRuntimeProvider({ children }: { children: ReactNode }) {
-  const cloud = useMemo(
-    () =>
-      new AssistantCloud({
-        baseUrl: process.env.ASSISTANT_BASE_URL!,
-        authToken: getAssistantToken,
-      }),
-    [],
-  );
-
-  const runtime = useLangGraphRuntime({
-    cloud,
-    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 as { messages?: LangChainMessage[] }).messages ?? [],
-      };
-    },
-    delete: async (externalId) => {
-      await deleteThread(externalId);
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-<Callout type="info">
-  The `useLangGraphRuntime` hook accepts `cloud`, `create`, `load`, and `delete` parameters for simplified thread management. The runtime handles the thread lifecycle internally.
-
-  - **`create`**: Called when creating a new thread. Returns `{ externalId }` with your backend's thread ID.
-  - **`load`**: Called when switching to an existing thread. Returns the thread's messages (and optionally interrupts).
-  - **`delete`**: Called when deleting a thread. Receives the thread's `externalId`. When provided, users can delete threads from the thread list UI.
-</Callout>
-
-</Step>
-
-<Step>
-
-### Add Thread UI Components
-
-Install the thread list component:
-
-<PlatformTabs>
-<Tab value="React">
-
-<Tabs items={["assistant-ui", "shadcn (namespace)", "shadcn"]}>
-  <Tab>
-
-```sh
-npx assistant-ui@latest add thread-list
-```
-
-  </Tab>
-  <Tab>
-
-```sh
-npx shadcn@latest add @assistant-ui/thread-list
-```
-
-The `@assistant-ui` namespace resolves through the registry entry configured in [Manual Setup](/docs/installation#manual-setup).
-
-  </Tab>
-  <Tab>
-
-```sh
-npx shadcn@latest add https://r.assistant-ui.com/thread-list.json
-```
-
-  </Tab>
-</Tabs>
-
-Then add it to your application layout:
-
-```tsx title="app/chat/page.tsx"
-import { Thread } from "@/components/assistant-ui/thread";
-import { ThreadList } from "@/components/assistant-ui/thread-list";
-
-export default function ChatPage() {
-  return (
-    <div className="grid h-dvh grid-cols-[250px_1fr] gap-x-2">
-      <ThreadList />
-      <Thread />
-    </div>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-Follow the [React Native setup](/docs/react-native) for `Thread`, then compose it with the native thread-list primitives:
-
-```tsx title="app/chat.tsx"
-import { Text, View } from "react-native";
-import {
-  ThreadListItemPrimitive,
-  ThreadListPrimitive,
-} from "@assistant-ui/react-native";
-import { Thread } from "@/components/assistant-ui/thread";
-
-function ThreadList() {
-  return (
-    <ThreadListPrimitive.Root>
-      <ThreadListPrimitive.New>
-        <Text>New chat</Text>
-      </ThreadListPrimitive.New>
-      <ThreadListPrimitive.Items
-        renderItem={({ threadId }) => (
-          <ThreadListItemPrimitive.Root key={threadId}>
-            <ThreadListItemPrimitive.Trigger>
-              <ThreadListItemPrimitive.Title fallback="New conversation" />
-            </ThreadListItemPrimitive.Trigger>
-          </ThreadListItemPrimitive.Root>
-        )}
-      />
-    </ThreadListPrimitive.Root>
-  );
-}
-
-export default function ChatPage() {
-  return (
-    <MyRuntimeProvider>
-      <View style={{ flex: 1 }}>
-        <ThreadList />
-        <Thread />
-      </View>
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-Follow the [Ink setup](/docs/ink) for `Thread`, then compose it with the terminal thread-list primitives:
-
-```tsx title="chat.tsx"
-import { Box, Text } from "ink";
-import {
-  ThreadListItemPrimitive,
-  ThreadListPrimitive,
-} from "@assistant-ui/react-ink";
-import { Thread } from "./components/thread.js";
-
-function ThreadList() {
-  return (
-    <ThreadListPrimitive.Root>
-      <ThreadListPrimitive.New>
-        <Text color="green">[New chat]</Text>
-      </ThreadListPrimitive.New>
-      <ThreadListPrimitive.Items
-        renderItem={({ threadId }) => (
-          <ThreadListItemPrimitive.Root key={threadId}>
-            <ThreadListItemPrimitive.Trigger>
-              <ThreadListItemPrimitive.Title fallback="New conversation" />
-            </ThreadListItemPrimitive.Trigger>
-          </ThreadListItemPrimitive.Root>
-        )}
-      />
-    </ThreadListPrimitive.Root>
-  );
-}
-
-export function ChatPage() {
-  return (
-    <MyRuntimeProvider>
-      <Box flexDirection="column">
-        <ThreadList />
-        <Thread />
-      </Box>
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-</Step>
-
-</Steps>
-
-## Authentication
-
-The React runtime-provider tab shows two authentication modes:
-
-- **Anonymous**: Suitable for React demos and prototypes. Creates a browser session-based user ID.
-- **Authenticated**: For production use with user accounts. The authenticated example uses [Clerk](https://clerk.com/), but you can integrate any auth provider.
-
-The React Native and React Ink tabs use explicit `authToken` callbacks, which is the recommended shape outside browser-session-based demos.
-
-For other authentication providers or custom implementations, see the [Cloud Authorization](/docs/cloud/authorization) guide.
-
-## Next Steps
-
-- Learn about [LangGraph runtime setup](/docs/runtimes/langgraph/overview) for your application
-- Explore [ThreadListRuntime](/docs/api-reference/runtimes/thread-list-runtime) for advanced thread management
-- Check out the [LangGraph example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph) on GitHub