如何使用LangGraph实现生成式用户界面¶
生成式用户界面（Generative UI）允许代理超越文本，生成丰富的用户界面。这使得创建更交互性和上下文感知的应用程序成为可能，在这些应用程序中，UI 根据对话流程和 AI 响应进行调整。
LangGraph 平台支持将您的 React 组件与图代码并置。这使您能够专注于为图构建特定的 UI 组件，并轻松地连接到现有的聊天界面，如Agent Chat，并且只有在实际需要时才加载代码。
教程¶
1. 定义和配置UI组件¶
首先，创建您的第一个UI组件。对于每个组件，您需要提供一个唯一的标识符，该标识符将在图形代码中引用该组件。
const WeatherComponent = (props: { city: string }) => {
return <div>Weather for {props.city}</div>;
};
export default {
weather: WeatherComponent,
};
``
接下来，在您的`langgraph.json`配置中定义您的UI组件：
```json
{
"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。
2. 在您的图中发送UI组件¶
import uuid
from typing import Annotated, Sequence, TypedDict
from langchain_core.messages import AIMessage, 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-4o-mini")
.with_structured_output(WeatherOutput)
.with_config({"tags": ["nostream"]})
.ainvoke(state["messages"])
)
message = AIMessage(
id=str(uuid.uuid4()),
content=f"Here's the weather for {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元素：
import {
typedUi,
uiMessageReducer,
} from "@langchain/langgraph-sdk/react-ui/server";
import { ChatOpenAI } from "@langchain/openai";
import { v4 as uuidv4 } from "uuid";
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-4o-mini" })
.withStructuredOutput(z.object({ city: z.string() }))
.withConfig({ tags: ["nostream"] })
.invoke(state.messages);
const response = {
id: uuidv4(),
type: "ai",
content: `Here's the weather for ${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元素。
"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组件的JS和CSS，并在阴影DOM中渲染它们，从而确保样式与其他应用程序部分隔离。
操作指南¶
组件加载时显示加载界面¶
当组件正在加载时，您可以提供一个备用界面。
客户端提供自定义组件¶
如果您已经在客户端应用程序中加载了这些组件，则可以提供一个此类组件的映射表，以便直接渲染而无需从LangGraph平台获取UI代码。
const clientComponents = {
weather: WeatherComponent,
};
<LoadExternalComponent
stream={thread}
message={ui}
components={clientComponents}
/>;
自定义UI组件的命名空间¶
默认情况下，LoadExternalComponent 将使用 useStream() 钩子中的 assistantId 来获取UI组件的代码。您可以通过向 LoadExternalComponent 组件提供 namespace 属性来自定义此行为。
从UI组件访问和交互线程状态¶
您可以在UI组件内部通过使用 useStreamContext 钩子来访问线程状态。
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 属性来传递额外的上下文信息。
然后，您可以在UI组件中通过使用 useStreamContext 钩子来访问 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() 钩子的 onCustomEvent 回调在节点执行完成之前流式传输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消息¶
类似于通过附加 RemoveMessage 来从状态中移除消息的方式，您也可以通过调用 remove_ui_message / ui.delete 并传入UI消息的ID来从状态中移除UI消息。