Getting Started

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);

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

const threadMessage = convertLangChainMessages(langChainMessage);

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.
      // For pipe-namespaced events emitted by subgraphs (e.g. `messages|tools:call_abc`),
      // `metadata.namespace` holds the suffix ("tools:call_abc"). Use it to attribute
      // a chunk to a specific subgraph.
    },
    onValues: (values) => {
      // Fired when a top-level `values` event is received.
      // Subgraph `values` events are routed to `onSubgraphValues` instead.
    },
    onUpdates: (updates) => {
      // Fired when a top-level `updates` event is received.
      // Subgraph `updates` events are routed to `onSubgraphUpdates` instead.
    },
    onSubgraphValues: (namespace, values) => {
      // Fired when a subgraph `values|<namespace>` event is received
      // (e.g. `namespace === "tools:call_abc"`). Use this to observe
      // subgraph-internal state without mixing it into `onValues`.
    },
    onSubgraphUpdates: (namespace, updates) => {
      // Fired when a subgraph `updates|<namespace>` event is received.
    },
    onMetadata: (metadata) => { /* thread metadata */ },
    onInfo: (info) => { /* informational messages */ },
    onError: (error) => {
      // Fired for both top-level and subgraph errors.
    },
    onSubgraphError: (namespace, error) => {
      // Additionally fired for subgraph errors with the namespace.
      // Use to attribute a subgraph failure to its source without marking
      // the parent message as incomplete (that only happens for top-level errors).
    },
    onCustomEvent: (type, data) => { /* custom events */ },
  },
});

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

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

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,
    };
  },
});

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

import type { RemoteThreadListAdapter } from "@assistant-ui/react";
import { Client } from "@langchain/langgraph-sdk";

const client = new Client({ apiUrl: process.env.NEXT_PUBLIC_LANGGRAPH_API_URL });

const threadListAdapter: RemoteThreadListAdapter = {
  async list() {
    const threads = await client.threads.search({ limit: 50 });
    return {
      threads: threads.map((t) => ({
        status: "regular",
        remoteId: t.thread_id,
        externalId: t.thread_id,
        title: (t.metadata as { title?: string } | undefined)?.title,
      })),
    };
  },
  async initialize() {
    const t = await client.threads.create();
    return { remoteId: t.thread_id, externalId: t.thread_id };
  },
  async delete(remoteId) {
    await client.threads.delete(remoteId);
  },
  // rename, archive, unarchive, fetch, generateTitle — see link below
};

const runtime = useLangGraphRuntime({
  stream: async function* (messages, { initialize }) { /* ... */ },
  load: async (externalId) => { /* ... */ },
  unstable_threadListAdapter: threadListAdapter,
});

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;
  },
});

streamMode: ["messages", "updates", "custom"]

const runtime = useLangGraphRuntime({
  stream: async function* (messages, { initialize }) { /* ... */ },
  uiStateKey: "my_ui",
});

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]}

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] };
}

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>
  ),
});

<AssistantRuntimeProvider runtime={runtime}>
  <ChartUI />
  <Thread />
</AssistantRuntimeProvider>

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} />,
    },
  },
});

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} />,
    },
  },
});

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,
    };
  },
});

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

function Sidebar() {
  const uiMessages = useLangGraphUIMessages();
  // Filter, group, or render UI messages outside the thread
  return <>{uiMessages.map(/* ... */)}</>;
}