Getting Started

Connect to LangGraph Cloud API for agent workflows with streaming.

Requirements

You need a LangGraph Cloud API server. You can start a server locally via LangGraph Studio or use 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.

New project from template

Create a new project based on the LangGraph assistant-ui template

npx create-assistant-ui@latest -t langgraph my-app

Set environment variables

Create a .env.local file in your project with the following variables:

# LANGCHAIN_API_KEY=your_api_key # for production
# LANGGRAPH_API_URL=your_api_url # for production
NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id

Installation in existing React project

Install dependencies

npm install @assistant-ui/react @assistant-ui/react-langgraph @langchain/langgraph-sdk

Setup a proxy backend endpoint (optional, for production)

This example forwards every request to the LangGraph server directly from the browser. For production use-cases, you should limit the API calls to the subset of endpoints that you need and perform authorization checks.

@/api/api/[...path]/route.ts

import { ,  } from "next/server";

function () {
  return {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
    "Access-Control-Allow-Headers": "*",
  };
}

async function (: , : string) {
  try {
    const  = ...(/^\/?api\//, "");
    const  = new (.);
    const  = new (.);
    .("_path");
    .("nxtP_path");
    const  = .()
      ? `?${.()}`
      : "";

    const : RequestInit = {
      ,
      : {
        "x-api-key": .["LANGCHAIN_API_KEY"] || "",
      },
    };

    if (["POST", "PUT", "PATCH"].()) {
      . = await .();
    }

    const  = await (
      `${.["LANGGRAPH_API_URL"]}/${}${}`,
      ,
    );

    return new (., {
      : .,
      : .,
      : {
        ....,
        ...(),
      },
    });
  } catch (: any) {
    return .({ : .message }, { : .status ?? 500 });
  }
}

export const  = (: ) => (, "GET");
export const  = (: ) => (, "POST");
export const  = (: ) => (, "PUT");
export const  = (: ) => (, "PATCH");
export const  = (: ) => (, "DELETE");

// Add a new OPTIONS handler
export const  = () => {
  return new (null, {
    : 204,
    : {
      ...(),
    },
  });
};

Setup helper functions

@/lib/chatApi.ts

import {  } from "@langchain/langgraph-sdk";
import { ,  } from "@assistant-ui/react-langgraph";

const  = () => {
  const  = .["NEXT_PUBLIC_LANGGRAPH_API_URL"] || "/api";
  return new ({
    ,
  });
};

export const  = async () => {
  const  = ();
  return ..();
};

export const  = async (
  : string,
): <<{ : [] }>> => {
  const  = ();
  return ..();
};

export const  = async (: {
  : string;
  : [];
  ?: ;
}) => {
  const  = ();
  const { , ... } = . ?? {};
  return ..(
    .,
    .["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
    {
      : .. > 0
        ? { : . }
        : null,
      : "messages-tuple",
      ...( && { :  }),
      ...,
    },
  );
};

Define a `MyAssistant` component

@/components/MyAssistant.tsx

"use client";

import {  } from "@/components/assistant-ui/thread";
import {  } from "@assistant-ui/react";
import {  } from "@assistant-ui/react-langgraph";

import { , ,  } from "@/lib/chatApi";

export function () {
  const  = ({
    : async (, { , ... }) => {
      const {  } = await ();
      if (!) throw new ("Thread not found");
      return ({
        : ,
        ,
        
      });
    },
    : async () => {
      const {  } = await ();
      return { :  };
    },
    : async () => {
      const  = await ();
      return {
        : .values.messages,
        : .tasks[0]?.interrupts,
      };
    },
  });

  return (
    < ={}>
      < />
    </AssistantRuntimeProvider>
  );
}

Use the `MyAssistant` component

@/app/page.tsx

import {  } from "@/components/MyAssistant";

export default function () {
  return (
    < ="h-dvh">
      < />
    </>
  );
}

Setup environment variables

Create a .env.local file in your project with the following variables:

# LANGCHAIN_API_KEY=your_api_key # for production
# LANGGRAPH_API_URL=your_api_url # for production
NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id

Setup UI components

Follow the UI Components guide to setup the UI components.

Advanced APIs

Message Accumulator

The LangGraphMessageAccumulator lets you append messages incoming from the server to replicate the messages state client side.

import {
  LangGraphMessageAccumulator,
  appendLangChainChunk,
} from "@assistant-ui/react-langgraph";

const accumulator = new LangGraphMessageAccumulator({
  appendMessage: appendLangChainChunk,
});

// Add new chunks from the server
if (event.event === "messages/partial") accumulator.addMessages(event.data);

Message Conversion

Use convertLangChainMessages to transform LangChain messages to assistant-ui format:

import { convertLangChainMessages } from "@assistant-ui/react-langgraph";

const threadMessage = convertLangChainMessages(langChainMessage);

Event Handlers

You can listen to streaming events by passing eventHandlers to useLangGraphRuntime:

const runtime = useLangGraphRuntime({
  stream: async (messages, { initialize, ...config }) => { /* ... */ },
  eventHandlers: {
    onMessageChunk: (chunk, metadata) => {
      // Fired for each chunk in messages-tuple mode
      // metadata contains langgraph_step, langgraph_node, ls_model_name, etc.
    },
    onValues: (values) => {
      // Fired when a "values" event is received
    },
    onUpdates: (updates) => {
      // Fired when an "updates" event is received
    },
    onMetadata: (metadata) => { /* thread metadata */ },
    onError: (error) => { /* stream errors */ },
    onCustomEvent: (type, data) => { /* custom events */ },
  },
});

Message Metadata

When using streamMode: "messages-tuple", each chunk includes metadata from the LangGraph server. Access accumulated metadata per message with the useLangGraphMessageMetadata hook:

import { useLangGraphMessageMetadata } from "@assistant-ui/react-langgraph";

function MyComponent() {
  const metadata = useLangGraphMessageMetadata();
  // Map<string, LangGraphTupleMetadata> keyed by message ID
}

Thread Management

Basic Thread Support

The useLangGraphRuntime hook now includes built-in thread management capabilities:

const runtime = useLangGraphRuntime({
  stream: async (messages, { initialize, ...config }) => {
    // 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, config });
  },
  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,
    };
  },
});

Cloud Persistence

For persistent thread history across sessions, integrate with assistant-cloud:

const runtime = useLangGraphRuntime({
  cloud: new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
  }),
  // ... stream, create, load functions
});

See the Cloud Persistence guide for detailed setup instructions.

Message Editing & Regeneration

LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, you need to provide a getCheckpointId callback that resolves the appropriate checkpoint for server-side forking.

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();
    // Get the thread state history and find the checkpoint
    // that matches the parent messages by exact message ID sequence.
    // If IDs are missing, return null and skip edit/reload for safety.
    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((message) => typeof message.id === "string") &&
        stateMessages.every((message) => typeof message.id === "string");
      if (!hasStableIds) {
        continue;
      }

      const isMatch = parentMessages.every(
        (message, index) => message.id === stateMessages[index]?.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 the helper function in the setup section above).

Without getCheckpointId, the edit and regenerate buttons will not appear. This is intentional — simply truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.

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:

Make sure your thread state type includes the interrupts field
Return the interrupts from the load function along with the messages
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.