AI agent 正在迅速从令人惊叹的演示演进到大规模的生产级应用，而 LangGraph 让这一转变比以往更顺畅。但在此之前，把这些 agent 接到一个 frontend（并为用户提供实时交互）往往需要一堆杂乱的 API、state management，以及运气。
现在介绍 useAgent —— 一个简单的 React hook，能让你的 frontend 直接连接到 LangGraph agent。无需连线。无需样板代码。无痛集成。
可以把它理解为： React - LangGraph，完全同步，完全实时。
在本指南中，我们将解释该 hook 的工作原理，并通过实用示例演示消息展示、state 同步、event 监听、tool 渲染以及 interrupt 处理。
让我们开始吧。
什么是 useAgent？
useAgent 是来自 @copilotkit/react-core/v2 的一个 React hook，使你的组件能够实时访问 LangGraph agent。
这意味着你可以：
-
读取 messages -
发送 commands -
跟踪 status -
同步 state -
处理 interrupts -
渲染 tool calls -
构建 dashboards
把你的 agent 看作后端的大脑。useAgent 则是 frontend 与它沟通的方式。
1. 在任意组件中访问你的 agent
首先，引入该 hook：
import { useAgent } from "@copilotkit/react-core/v2";
然后这样调用：
export function AgentInfo() {
const { agent } = useAgent();
return (
<div>
<p>Agent ID: {agent.id}</p>
<p>Thread ID: {agent.threadId}</p>
<p>Status: {agent.isRunning ? "Running" : "Idle"}</p>
<p>Messages: {agent.messages.length}</p>
</div>
);
}
无需空值检查。 无需等待初始化。 如果你的 agent 未配置，hook 会立即抛出错误。
2. 显示消息（像聊天应用一样）
每个 agent 都有消息历史。你可以直接遍历它：
export functionMessageList() {
const { agent } = useAgent();
return (
<div>
{agent.messages.map((msg) => (
<div key={msg.id}>
<strong>{msg.role}:</strong>
<span>{msg.content}</span>
</div>
))}
</div>
);
}
搞定——你已经实现了一个实时的聊天历史。
3. 展示 agent 运行状态
agent 需要时间“思考”。你的 UI 可以这样提示：
export functionAgentStatus() {
const { agent } = useAgent();
return (
<div>
{agent.isRunning ? (
<div>
<div className="spinner" />
<span>Agent is processing...</span>
</div>
) : (
<span>Ready</span>
)}
</div>
);
}
这对 UX 非常有帮助。
4. 读取与更新共享 state
你的 agent 与 UI 共享同一个 state 对象。
-
React 更新它——agent 就能看到。 -
agent 更新它——React 会重新渲染。
读取 state：
export function StateDisplay() {
const { agent } = useAgent();
return (
<div>
<h3>Agent State</h3>
<pre>{JSON.stringify(agent.state, null, 2)}</pre>
{agent.state.user_name && <p>User: {agent.state.user_name}</p>}
{agent.state.preferences && <p>Preferences: {JSON.stringify(agent.state.preferences)}</p>}
</div>
);
}
更新 state：
export functionThemeSelector() {
const { agent } = useAgent();
constupdateTheme = (theme: string) => {
agent.setState({
...agent.state,
user_theme: theme,
});
};
return (
<div>
<button onClick={() => updateTheme("dark")}>Dark Mode</button>
<button onClick={() => updateTheme("light")}>Light Mode</button>
<p>Current: {agent.state.user_theme || "default"}</p>
</div>
);
}
这非常强大，因为你的 agent 能够记住上下文、偏好和过往决策。
5. 订阅 agent events
agent 会发出 events，例如：
-
run started -
run finalized -
state changed -
messages changed -
custom events
你可以用一小段代码订阅：
export functionEventLogger() {
const { agent } = useAgent();
useEffect(() => {
constsubscriber: AgentSubscriber = {
onCustomEvent: ({ event }) => {
console.log("Custom event:", event.name, event.value);
},
onRunStartedEvent: () => {
console.log("Agent started running");
},
onRunFinalized: () => {
console.log("Agent finished running");
},
onStateChanged: (state) => {
console.log("State changed:", state);
},
};
const { unsubscribe } = agent.subscribe(subscriber);
return() =>unsubscribe();
}, []);
returnnull;
}
这正是你构建 observability dashboards 的方式。
6. 渲染 tool calls（天气示例）
agent 不只是回复——它还会运行 tools。 你可以在 UI 中完全自定义每个 tool 的外观。
定义一个 renderer：
export const weatherToolRender = defineToolCallRenderer({
name: "get_weather",
render: ({ args, status }) => {
return <WeatherCard location={args.location} status={status} />;
},
});
然后注册它：
<CopilotKit
runtimeUrl="/api/copilotkit"
renderToolCalls={[weatherToolRender]}
>
并渲染 tool outputs：
{renderToolCall({ toolCall, toolMessage })}
现在，你的 AI 可以动态激活 UI 组件——比如卡片、图表、警示等。
7. 构建一个完整的 dashboard
把以上概念组合起来就能做出一个完整的 UI：
export default function AgentDashboard() {
const { agent } = useAgent();
return (
<div className="p-8 max-w-4xl mx-auto space-y-6">
...
</div>
);
}
这正是让 MVP 级应用升级为生产级 dashboards 的方式。
8. 处理 LangGraph interrupts（动态输入！）
LangGraph 可以暂停自身（interrupt）并向用户请求更多信息。
你可以这样处理：
if (event.name === "on_interrupt") {
const response = prompt(event.value);
...
}
或者构建一个自定义 UI：
export function CustomInterruptHandler() {
...
}
这非常适合如下流程：
-
“我应该使用哪个文件？” -
“请选择一个分类：” -
“是否继续？”
你的 agent 会变得真正交互式，而不只是对话式。
结语
useAgent 这个 hook 是打造 AI agent 应用最简单却又最强大的工具之一。它把 LangGraph 变成一个真正意义上的全栈框架：
-
无需手写 manual polling -
无需繁琐 websockets -
无需自建 state management -
无需重体力活
只需将 React 组件直接连接到你的 agent 大脑。
如果你在 2026 年开发 AI 应用，这就是值得采用的方式。