【LangGraph】Implement generative UI with LangGraph：用 LangGraph 实现生成用户界面

AI小编 · 发表于昨天 22:43

作者：彬彬侠
如何使用 LangGraph 实现生成用户界面（How to implement Generative User Interfaces with LangGraph）

Prerequisites

LangGraph PlatformLangGraph ServeruseStream() React Hook

生成用户界面（Generative UI）允许代理超越文本，生成丰富的用户界面。这使得创建更具交互性和上下文感知的应用成为可能，其中 UI 根据对话流程和 AI 响应动态适应。

【LangGraph】Implement generative UI with LangGraph：用 LangGraph 实现生成用户界面-1.png

LangGraph 平台支持将你的 React 组件与图代码共同托管。这允许你专注于为图构建特定的 UI 组件，同时轻松接入现有聊天界面（如 Agent Chat），并仅在需要时加载代码。
教程

1. 定义和配置 UI 组件

首先，创建你的第一个 UI 组件。每个组件需要提供一个唯一标识符，用于在图代码中引用该组件。
src/agent/ui.tsx

const WeatherComponent = (props: { city: string }) => {
return <div>Weather for {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 组件命名空间。
LangGraph 平台会自动打包你的 UI 组件代码和样式，并将其作为外部资产提供，可通过 LoadExternalComponent 组件加载。某些依赖（如 react 和 react-dom）会自动从打包中排除。
CSS 和 Tailwind 4.x 也受开箱支持，因此你可以在 UI 组件中自由使用 Tailwind 类以及 shadcn/ui。

src/agent/ui.tsx（带样式）
1. import "./styles.css";
3. const WeatherComponent = (props: { city: string }) => {
4. return <div className="bg-red-500">Weather for {props.city}</div>;
5. };
7. export default {
8. weather: WeatherComponent,
9. };
复制代码
styles.css
1. @import"tailwindcss";
复制代码

2. 在图中发送 UI 组件

在图代码中，使用 push_ui_message（Python）或 ui.push（TypeScript）将 UI 组件与消息关联发送。

（Python）src/agent.py
1. import uuid
2. from typing import Annotated, Sequence, TypedDict
4. from langchain_core.messages import AIMessage, BaseMessage
5. from langchain_openai import ChatOpenAI
6. from langgraph.graph import StateGraph
7. from langgraph.graph.message import add_messages
8. from langgraph.graph.ui import AnyUIMessage, ui_message_reducer, push_ui_message
10. classAgentState(TypedDict):# noqa: D101
11. messages: Annotated[Sequence[BaseMessage], add_messages]
12. ui: Annotated[Sequence[AnyUIMessage], ui_message_reducer]asyncdefweather(state: AgentState):classWeatherOutput(TypedDict):
13. city:str
15. weather: WeatherOutput =(await ChatOpenAI(model="gpt-4o-mini").with_structured_output(WeatherOutput).with_config({"tags":["nostream"]}).ainvoke(state["messages"]))
17. message = AIMessage(id=str(uuid.uuid4()),
18. content=f"Here's the weather for {weather['city']}",)# 发出与消息关联的 UI 元素
19. push_ui_message("weather", weather, message=message)return{"messages":[message]}
21. workflow = StateGraph(AgentState)
22. workflow.add_node(weather)
23. workflow.add_edge("__start__","weather")
24. graph = workflow.compile()
复制代码

在 TypeScript 中，使用 typedUi 工具确保 UI 元素推送的类型安全：

（TypeScript）src/agent/index.ts
1. import{
2. typedUi,
3. uiMessageReducer,}from"@langchain/langgraph-sdk/react-ui/server";import{ ChatOpenAI }from"@langchain/openai";import{ v4 as uuidv4 }from"uuid";import{ z }from"zod";importtypeComponentMapfrom"./ui.js";import{
4. Annotation,
5. MessagesAnnotation,
6. StateGraph,typeLangGraphRunnableConfig,}from"@langchain/langgraph";const AgentState = Annotation.Root({...MessagesAnnotation.spec,
7. ui:Annotation({ reducer: uiMessageReducer,default:()=>[]}),});exportconst graph =newStateGraph(AgentState).addNode("weather",async(state, config)=>{// 提供组件映射的类型以确保// `ui.push()` 调用的类型安全，以及// 将消息推送到 `ui` 并发送自定义事件const ui =typedUi<typeof ComponentMap>(config);const weather =awaitnewChatOpenAI({ model:"gpt-4o-mini"}).withStructuredOutput(z.object({ city: z.string()})).withConfig({ tags:["nostream"]}).invoke(state.messages);const response ={
8. id:uuidv4(),
9. type:"ai",
10. content:`Here's the weather for ${weather.city}`,};// 发出与 AI 消息关联的 UI 元素
11. 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 会从 LangGraph 平台获取 UI 组件的 JavaScript 和 CSS 代码，并在一个影子 DOM 中渲染它们，从而确保与应用其余部分的样式隔离。
操作指南

在客户端提供自定义组件

如果你已经在客户端应用中加载了组件，可以提供一个组件映射，直接渲染而无需从 LangGraph 平台获取 UI 代码。

const clientComponents = {
weather: WeatherComponent,
};
<LoadExternalComponent
stream={thread}
message={ui}
components={clientComponents}
/>;

复制代码

在组件加载时显示加载 UI

你可以提供一个回退 UI，在组件加载时渲染。

<LoadExternalComponent
stream={thread}
message={ui}
fallback={<div>Loading...</div>}
/>

复制代码

自定义 UI 组件的命名空间

默认情况下，LoadExternalComponent 会使用 useStream() 钩子中的 assistantId 获取 UI 组件代码。你可以通过为 LoadExternalComponent 组件提供 namespace 属性自定义此行为。

src/app/page.tsx
1. <LoadExternalComponent
2. stream={thread}
3. message={ui}
4. namespace="custom-namespace"
5. />
复制代码
langgraph.json
1. {"ui":{"custom-namespace":"./src/agent/ui.tsx"}}
复制代码

从 UI 组件访问和交互线程状态

你可以通过 useStreamContext 钩子在 UI 组件内访问线程状态。

import { useStreamContext } from "@langchain/langgraph-sdk/react-ui";
const WeatherComponent = (props: { city: string }) => {
const { thread, submit } = useStreamContext();
return (
<>
<div>Weather for {props.city}</div>
<button
onClick={() => {
const newMessage = {
type: "human",
content: `What's the weather in ${props.city}?`,
};
submit({ messages: [newMessage] });
}}
>
Retry
</button>
</>
);
};

复制代码

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

你可以通过为 LoadExternalComponent 组件提供 meta 属性向客户端组件传递额外上下文。

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

复制代码

然后，你可以通过 useStreamContext 钩子在 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>
Weather for {props.city} (user: {meta?.userId})
</div>
);
};

复制代码

从服务器流式传输 UI 消息

你可以通过 useStream() 钩子的 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()（TypeScript）或 push_ui_message()（Python）并使用与要更新的 UI 消息相同的 ID 来推送 UI 组件的更新。
Python 示例

from typing import Annotated, Sequence, TypedDict
from langchain_anthropic import ChatAnthropic
from langchain_core.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
classAgentState(TypedDict):# noqa: D101
messages: Annotated[Sequence[BaseMessage], add_messages]
ui: Annotated[Sequence[AnyUIMessage], ui_message_reducer]classCreateTextDocument(TypedDict):"""为用户准备文档标题。"""
title:strasyncdefwriter_node(state: AgentState):
model = ChatAnthropic(model="claude-3-5-sonnet-latest")
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"Create a document with the title: {tool_call['title']}")
content: AIMessageChunk |None=Noneasyncfor 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]}

复制代码

TypeScript 示例

import{
Annotation,
MessagesAnnotation,typeLangGraphRunnableConfig,}from"@langchain/langgraph";import{ z }from"zod";import{ ChatAnthropic }from"@langchain/anthropic";import{
typedUi,
uiMessageReducer,}from"@langchain/langgraph-sdk/react-ui/server";importtype{ AIMessageChunk }from"@langchain/core/messages";importtypeComponentMapfrom"./ui";const AgentState = Annotation.Root({...MessagesAnnotation.spec,
ui:Annotation({ reducer: uiMessageReducer,default:()=>[]}),});asyncfunctionwriterNode(
state:typeof AgentState.State,
config: LangGraphRunnableConfig
):Promise<typeof AgentState.Update>{const ui =typedUi<typeof ComponentMap>(config);const model =newChatAnthropic({ model:"claude-3-5-sonnet-latest"});const message =await model
.bindTools([{
name:"create_text_document",
description:"Prepare a document heading for the user.",
schema: z.object({ title: z.string()}),},],{ tool_choice:{ type:"tool", name:"create_text_document"}}).invoke(state.messages);typeToolCall={ 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(`Create a short poem with the topic: ${message.text}`);let content: AIMessageChunk |undefined;forawait(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]};}

复制代码

UI 组件示例

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

复制代码

从状态中移除 UI 消息

与通过追加 RemoveMessage 从状态中移除消息类似，你可以通过调用 delete_ui_message（Python）或 ui.delete（TypeScript）并提供 UI 消息的 ID 来从状态中移除 UI 消息。
Python 示例

from langgraph.graph.ui import push_ui_message, delete_ui_message
# 推送消息
message = push_ui_message("weather",{"city":"London"})# 移除该消息
delete_ui_message(message["id"])

复制代码

TypeScript 示例

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

复制代码

Learn more

JS/TS SDK Reference

总结

生成 UI 机制

核心步骤：
- 定义和配置 UI 组件：
- 在图中发送 UI 组件：
- 在 React 应用中处理 UI 元素：
操作指南：
- 流式 UI 消息：
  移除 UI 消息：使用 delete_ui_message（Python）或 ui.delete（TypeScript）移除 UI 消息。
使用建议：
- 生产部署：
  调试：结合 LangSmith（需 LANGSMITH_API_KEY）跟踪 UI 消息和图运行，分析性能。
注意事项：

参考资料：

原文地址：https://blog.csdn.net/u013172930/article/details/148141911

25位大厂高管转战生成式AI创业！吸金猛，不

【LangGraph】Implement generative UI with LangGraph：用 LangGraph 实现生成用户界面

【AI 大模型】LangChain 框架 ① ( LangCha

关于我们

产品与服务

解决方案

产品与服务