React与LangGraph的无缝连接：useAgent Hook实现全栈AI Agent实时交互

AI agent 正在迅速从令人惊叹的演示演进到大规模的生产级应用，而 LangGraph 让这一转变比以往更顺畅。但在此之前，将这些 agent 连接到前端并为用户提供实时交互，往往需要处理复杂的 API、状态管理，并依赖一定的运气。

现在介绍 useAgent —— 一个简单的 React Hook，能让你的前端直接连接到 LangGraph agent。无需复杂的配置。无需样板代码。实现无痛集成。

可以将其理解为：React 与 LangGraph 完全同步、完全实时。

在本指南中，我们将解释该 Hook 的工作原理，并通过实用示例演示消息展示、状态同步、事件监听、工具渲染以及中断处理。

让我们开始吧。

什么是 useAgent？

useAgent 是来自 @copilotkit/react-core/v2 的一个 React Hook，使你的组件能够实时访问 LangGraph agent。

这意味着你可以：

• 读取消息
• 发送指令
• 跟踪状态
• 同步状态
• 处理中断
• 渲染工具调用
• 构建仪表板

将你的 agent 视为后端的大脑。useAgent 则是前端与其沟通的桥梁。

1. 在任意组件中访问你的 agent

首先，引入该 Hook：

javascript
import { useAgent } from "@copilotkit/react-core/v2";

然后这样调用：

javascript
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 都有消息历史。你可以直接遍历它：

javascript
export function MessageList() {
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 可以这样提示：

javascript
export function AgentStatus() {
const { agent } = useAgent();
return (
<div>
{agent.isRunning ? (
<div>
<div className="spinner" />
<span>Agent is processing...</span>
</div>
) : (
<span>Ready</span>
)}
</div>
);
}

这对用户体验非常有帮助。

4. 读取与更新共享状态

你的 agent 与 UI 共享同一个状态对象。

• React 更新它——agent 就能看到。
• agent 更新它——React 会重新渲染。

读取状态：

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

更新状态：

javascript
export function ThemeSelector() {
const { agent } = useAgent();
const updateTheme = (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 事件

agent 会发出事件，例如：

• run started
• run finalized
• state changed
• messages changed
• custom events

“`markdown
你可以用一小段代码订阅：

javascript
export function EventLogger() {
const { agent } = useAgent();
useEffect(() => {
const subscriber: 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();
}, []);
return null;
}

这正是你构建可观测性仪表盘的方式。

6. 渲染工具调用（天气示例）

Agent 不仅能回复，还能运行工具。你可以在 UI 中完全自定义每个工具的外观。

定义一个渲染器：

javascript
export const weatherToolRender = defineToolCallRenderer({
name: "get_weather",
render: ({ args, status }) => {
return <WeatherCard location={args.location} status={status} />;
},
});

然后注册它：

“`jsx
<CopilotKit
runtimeUrl=”/api/copilotkit”
renderToolCalls={[weatherToolRender]}

“`

并渲染工具输出：

jsx
{renderToolCall({ toolCall, toolMessage })}

现在，你的 AI 可以动态激活 UI 组件——比如卡片、图表、警示等。

7. 构建一个完整的仪表盘

将以上概念组合起来，就能构建一个完整的 UI：

jsx
export default function AgentDashboard() {
const { agent } = useAgent();
return (
<div className="p-8 max-w-4xl mx-auto space-y-6">
...
</div>
);
}

这正是将 MVP 级应用升级为生产级仪表盘的方式。

8. 处理 LangGraph 中断（动态输入！）

LangGraph 可以暂停自身（中断）并向用户请求更多信息。

你可以这样处理：

javascript
if (event.name === "on_interrupt") {
const response = prompt(event.value);
...
}

或者构建一个自定义 UI：

jsx
export function CustomInterruptHandler() {
...
}

这非常适合如下流程：

• “我应该使用哪个文件？”
• “请选择一个分类：”
• “是否继续？”

你的 Agent 将变得真正具有交互性，而不仅仅是对话式。

结语

useAgent 这个 Hook 是打造 AI Agent 应用最简单却又最强大的工具之一。它将 LangGraph 转变为一个真正意义上的全栈框架：

• 无需手动轮询
• 无需繁琐的 WebSocket 连接
• 无需自建状态管理
• 无需繁重的体力活

只需将 React 组件直接连接到你的 Agent 大脑。

如果你在 2026 年开发 AI 应用，这就是值得采用的方式。
“`

关注“鲸栖”小程序，掌握最新AI资讯