如何使用 LangGraph 实现生成式用户界面

前置条件

生成式用户界面（Generative UI）让智能体不再局限于文本，还能够生成丰富的用户界面。这使得我们可以创建更加交互式且能够感知上下文的应用程序，让 UI 根据对话流程和 AI 响应动态调整。 Agent Chat 展示了一个关于预订住宿的提示，并以内嵌 UI 组件的形式渲染了一组生成的酒店列表卡片（包括图片、标题、价格和位置）。

Agent Chat 展示了一个关于预订住宿的提示，并以内嵌 UI 组件的形式渲染了一组生成的酒店列表卡片（包括图片、标题、价格和位置）。

LangSmith 支持将 React 组件与图代码放在一起。这样，你可以专注于为图构建特定的 UI 组件，同时轻松接入现有的聊天界面，例如 Agent Chat，并且只在实际需要时加载代码。

教程

1. 定义并配置 UI 组件

首先，创建你的第一个 UI 组件。对于每个组件，你都需要提供一个唯一标识符，图代码将使用它来引用该组件。

src/agent/ui.tsx

const WeatherComponent = (props: { city: string }) => {
  return <div>{props.city}的天气</div>;
};

export default {
  weather: WeatherComponent,
};

接下来，在 langgraph.json 配置中定义 UI 组件：

{
  "node_version": "20",
  "graphs": {
    "agent": "./src/agent/index.ts:graph"
  },
  "ui": {
    "agent": "./src/agent/ui.tsx"
  }
}

ui 部分指向图将使用的 UI 组件。默认情况下，我们建议使用与图名称相同的键，但你也可以按照自己的需求拆分组件。详情请参阅自定义 UI 组件的命名空间。 LangSmith 会自动打包 UI 组件代码和样式，并将它们作为外部资源提供，供 LoadExternalComponent 组件加载。某些依赖（例如 react 和 react-dom）会自动从打包结果中排除。 CSS 和 Tailwind 4.x 也可以直接使用，因此你可以在 UI 组件中自由使用 Tailwind 类以及 shadcn/ui。

src/agent/ui.tsx
src/agent/styles.css

import "./styles.css";

const WeatherComponent = (props: { city: string }) => {
  return <div className="bg-red-500">{props.city}的天气</div>;
};

export default {
  weather: WeatherComponent,
};

@import "tailwindcss";

2. 在图中发送 UI 组件

Python
JS

src/agent.py

import uuid
from typing import Annotated, Sequence, TypedDict

from langchain.messages import AIMessage
from langchain_core.messages import BaseMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph
from langgraph.graph.message import add_messages
from langgraph.graph.ui import AnyUIMessage, ui_message_reducer, push_ui_message


class AgentState(TypedDict):  # noqa: D101
    messages: Annotated[Sequence[BaseMessage], add_messages]
    ui: Annotated[Sequence[AnyUIMessage], ui_message_reducer]


async def weather(state: AgentState):
    class WeatherOutput(TypedDict):
        city: str

    weather: WeatherOutput = (
        await ChatOpenAI(model="gpt-5.4-mini")
        .with_structured_output(WeatherOutput)
        .with_config({"tags": ["nostream"]})
        .ainvoke(state["messages"])
    )

    message = AIMessage(
        id=str(uuid.uuid4()),
        content=f"这是 {weather['city']} 的天气",
    )

    # 发出与消息关联的 UI 元素
    push_ui_message("weather", weather, message=message)
    return {"messages": [message]}


workflow = StateGraph(AgentState)
workflow.add_node(weather)
workflow.add_edge("__start__", "weather")
graph = workflow.compile()

使用 typedUi 工具函数从智能体节点发出 UI 元素：

src/agent/index.ts

import {
  typedUi,
  uiMessageReducer,
} from "@langchain/langgraph-sdk/react-ui/server";

import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

import type ComponentMap from "./ui.js";

import {
  Annotation,
  MessagesAnnotation,
  StateGraph,
  type LangGraphRunnableConfig,
} from "@langchain/langgraph";

const AgentState = Annotation.Root({
  ...MessagesAnnotation.spec,
  ui: Annotation({ reducer: uiMessageReducer, default: () => [] }),
});

export const graph = new StateGraph(AgentState)
  .addNode("weather", async (state, config) => {
    // 提供组件映射的类型，以确保 `ui.push()` 调用的类型安全，
    // 同时将消息推送到 `ui` 并发送自定义事件。
    const ui = typedUi<typeof ComponentMap>(config);

    const weather = await new ChatOpenAI({ model: "gpt-5.4-mini" })
      .withStructuredOutput(z.object({ city: z.string() }))
      .withConfig({ tags: ["nostream"] })
      .invoke(state.messages);

    const response = {
      id: crypto.randomUUID(),
      type: "ai",
      content: `这是 ${weather.city} 的天气`,
    };

    // 发出与 AI 消息关联的 UI 元素
    ui.push({ name: "weather", props: weather }, { message: response });

    return { messages: [response] };
  })
  .addEdge("__start__", "weather")
  .compile();

3. 在 React 应用中处理 UI 元素

在客户端，你可以使用 useStream() 和 LoadExternalComponent 来显示 UI 元素。

src/app/page.tsx

"use client";

import { useStream } from "@langchain/langgraph-sdk/react";
import { LoadExternalComponent } from "@langchain/langgraph-sdk/react-ui";

export default function Page() {
  const { thread, values } = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
  });

  return (
    <div>
      {thread.messages.map((message) => (
        <div key={message.id}>
          {message.content}
          {values.ui
            ?.filter((ui) => ui.metadata?.message_id === message.id)
            .map((ui) => (
              <LoadExternalComponent key={ui.id} stream={thread} message={ui} />
            ))}
        </div>
      ))}
    </div>
  );
}

在幕后，LoadExternalComponent 会从 LangSmith 获取 UI 组件的 JS 和 CSS，并在 shadow DOM 中渲染它们，从而确保样式与应用的其他部分相互隔离。

操作指南

在客户端提供自定义组件

如果你的客户端应用中已经加载了这些组件，可以提供一个组件映射，直接渲染它们，而无需从 LangSmith 获取 UI 代码。

const clientComponents = {
  weather: WeatherComponent,
};

<LoadExternalComponent
  stream={thread}
  message={ui}
  components={clientComponents}
/>;

组件加载时显示加载 UI

你可以提供一个备用 UI，在组件加载期间进行渲染。

<LoadExternalComponent
  stream={thread}
  message={ui}
  fallback={<div>加载中...</div>}
/>

自定义 UI 组件的命名空间

默认情况下，LoadExternalComponent 会使用 useStream() hook 中的 assistantId 来获取 UI 组件代码。你可以向 LoadExternalComponent 组件提供 namespace 属性来进行自定义。

src/app/page.tsx
langgraph.json

<LoadExternalComponent
  stream={thread}
  message={ui}
  namespace="custom-namespace"
/>

{
  "ui": {
    "custom-namespace": "./src/agent/ui.tsx"
  }
}

从 UI 组件访问并操作线程状态

你可以使用 useStreamContext hook 在 UI 组件内部访问线程状态。

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

const WeatherComponent = (props: { city: string }) => {
  const { thread, submit } = useStreamContext();
  return (
    <>
      <div>{props.city}的天气</div>

      <button
        onClick={() => {
          const newMessage = {
            type: "human",
            content: `${props.city}的天气怎么样？`,
          };

          submit({ messages: [newMessage] });
        }}
      >
        重试
      </button>
    </>
  );
};

向客户端组件传递额外上下文

你可以向 LoadExternalComponent 组件提供 meta 属性，以便向客户端组件传递额外的上下文。

<LoadExternalComponent stream={thread} message={ui} meta={{ userId: "123" }} />

然后，你可以使用 useStreamContext hook 在 UI 组件中访问 meta 属性。

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

const WeatherComponent = (props: { city: string }) => {
  const { meta } = useStreamContext<
    { city: string },
    { MetaType: { userId?: string } }
  >();

  return (
    <div>
      {props.city}的天气（用户：{meta?.userId}）
    </div>
  );
};

从服务器流式传输 UI 消息

你可以使用 useStream() hook 的 onCustomEvent 回调，在节点执行完成之前就流式传输 UI 消息。当 LLM 正在生成响应时需要更新 UI 组件，这种方式尤其有用。

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

const { thread, submit } = useStream({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  onCustomEvent: (event, options) => {
    options.mutate((prev) => {
      const ui = uiMessageReducer(prev.ui ?? [], event);
      return { ...prev, ui };
    });
  },
});

然后，你可以通过调用 ui.push() / push_ui_message()，并使用与要更新的 UI 消息相同的 ID，向 UI 组件推送更新。

Python
JS
ui.tsx

from typing import Annotated, Sequence, TypedDict

from langchain_anthropic import ChatAnthropic
from langchain.messages import AIMessage, AIMessageChunk, BaseMessage
from langgraph.graph import StateGraph
from langgraph.graph.message import add_messages
from langgraph.graph.ui import AnyUIMessage, push_ui_message, ui_message_reducer


class AgentState(TypedDict):  # noqa: D101
    messages: Annotated[Sequence[BaseMessage], add_messages]
    ui: Annotated[Sequence[AnyUIMessage], ui_message_reducer]


class CreateTextDocument(TypedDict):
    """为用户准备文档标题。"""

    title: str


async def writer_node(state: AgentState):
    model = ChatAnthropic(model="claude-sonnet-4-6")
    message: AIMessage = await model.bind_tools(
        tools=[CreateTextDocument],
        tool_choice={"type": "tool", "name": "CreateTextDocument"},
    ).ainvoke(state["messages"])

    tool_call = next(
        (x["args"] for x in message.tool_calls if x["name"] == "CreateTextDocument"),
        None,
    )

    if tool_call:
        ui_message = push_ui_message("writer", tool_call, message=message)
        ui_message_id = ui_message["id"]

        # 我们已经通过 UI 消息将 LLM 响应流式传输到客户端
        # 因此不需要再将其流式传输到 `messages` 流模式。
        content_stream = model.with_config({"tags": ["nostream"]}).astream(
            f"创建一份标题为“{tool_call['title']}”的文档"
        )

        content: AIMessageChunk | None = None
        async for chunk in content_stream:
            content = content + chunk if content else chunk

            push_ui_message(
                "writer",
                {"content": content.text()},
                id=ui_message_id,
                message=message,
                # 使用 `merge=True` 将属性合并到现有 UI 消息中
                merge=True,
            )

    return {"messages": [message]}

import {
  Annotation,
  MessagesAnnotation,
  type LangGraphRunnableConfig,
} from "@langchain/langgraph";
import { z } from "zod";
import { ChatAnthropic } from "@langchain/anthropic";
import {
  typedUi,
  uiMessageReducer,
} from "@langchain/langgraph-sdk/react-ui/server";
import type { AIMessageChunk } from "@langchain/core/messages";

import type ComponentMap from "./ui";

const AgentState = Annotation.Root({
  ...MessagesAnnotation.spec,
  ui: Annotation({ reducer: uiMessageReducer, default: () => [] }),
});

async function writerNode(
  state: typeof AgentState.State,
  config: LangGraphRunnableConfig
): Promise<typeof AgentState.Update> {
  const ui = typedUi<typeof ComponentMap>(config);

  const model = new ChatAnthropic({ model: "claude-sonnet-4-6" });
  const message = await model
    .bindTools(
      [
        {
          name: "create_text_document",
          description: "为用户准备文档标题。",
          schema: z.object({ title: z.string() }),
        },
      ],
      { tool_choice: { type: "tool", name: "create_text_document" } }
    )
    .invoke(state.messages);

  type ToolCall = { name: "create_text_document"; args: { title: string } };
  const toolCall = message.tool_calls?.find(
    (tool): tool is ToolCall => tool.name === "create_text_document"
  );

  if (toolCall) {
    const { id, name } = ui.push(
      { name: "writer", props: { title: toolCall.args.title } },
      { message }
    );

    const contentStream = await model
      // 我们已经通过 UI 消息将 LLM 响应流式传输到客户端
      // 因此不需要再将其流式传输到 `messages` 流模式。
      .withConfig({ tags: ["nostream"] })
      .stream(`以 ${message.text} 为主题创作一首短诗`);

    let content: AIMessageChunk | undefined;
    for await (const chunk of contentStream) {
      content = content?.concat(chunk) ?? chunk;

      ui.push(
        { id, name, props: { content: content?.text } },
        // 使用 `merge: true` 将属性合并到现有 UI 消息中
        { message, merge: true }
      );
    }
  }

  return { messages: [message] };
}

function WriterComponent(props: { title: string; content?: string }) {
  return (
    <article>
      <h2>{props.title}</h2>
      <p style={{ whiteSpace: "pre-wrap" }}>{props.content}</p>
    </article>
  );
}

export default {
  weather: WriterComponent,
};

从状态中移除 UI 消息

与通过追加 RemoveMessage 来从状态中移除消息类似，你可以调用 remove_ui_message / ui.delete，并传入 UI 消息的 ID，从状态中移除 UI 消息。

Python
JS

from langgraph.graph.ui import push_ui_message, delete_ui_message

# 推送消息
message = push_ui_message("weather", {"city": "London"})

# 移除该消息
delete_ui_message(message["id"])

// 推送消息
const message = ui.push({ name: "weather", props: { city: "London" } });

// 移除该消息
ui.delete(message.id);

了解更多

JS/TS SDK 参考

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Develop your application

Capabilities

How to build

Auth & access control

Server customization

如何使用 LangGraph 实现生成式用户界面

教程

1. 定义并配置 UI 组件

2. 在图中发送 UI 组件

3. 在 React 应用中处理 UI 元素

操作指南

在客户端提供自定义组件

组件加载时显示加载 UI

自定义 UI 组件的命名空间

从 UI 组件访问并操作线程状态

向客户端组件传递额外上下文

从服务器流式传输 UI 消息

从状态中移除 UI 消息

了解更多

​教程

​1. 定义并配置 UI 组件

​2. 在图中发送 UI 组件

​3. 在 React 应用中处理 UI 元素

​操作指南

​在客户端提供自定义组件

​组件加载时显示加载 UI

​自定义 UI 组件的命名空间

​从 UI 组件访问并操作线程状态

​向客户端组件传递额外上下文

​从服务器流式传输 UI 消息

​从状态中移除 UI 消息

​了解更多

教程

1. 定义并配置 UI 组件

2. 在图中发送 UI 组件

3. 在 React 应用中处理 UI 元素

操作指南

在客户端提供自定义组件

组件加载时显示加载 UI

自定义 UI 组件的命名空间

从 UI 组件访问并操作线程状态

向客户端组件传递额外上下文

从服务器流式传输 UI 消息

从状态中移除 UI 消息

了解更多