使用 useAgent 与 LangGraph 构建全栈 AI Agent 应用

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 与它沟通的方式。

在任意组件中访问你的 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 会立即抛出错误。

显示消息（像聊天应用一样）

每个 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> );}

搞定——你已经实现了一个实时的聊天历史。

展示 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 非常有帮助。

读取与更新共享 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 能够记住上下文、偏好和过往决策。

订阅 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 的方式。

渲染 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 组件——比如卡片、图表、警示等。

构建一个完整的 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 的方式。

处理 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 应用，这就是值得采用的方式。

想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2025 年AI 大模型全套学习资料已整理完毕，从学习路线到面试真题，从工具教程到行业报告，一站式覆盖你的所有需求，现在全部免费分享！

👇👇扫码免费领取全部内容👇👇

一、学习必备：100+本大模型电子书+26 份行业报告 + 600+ 套技术PPT，帮你看透 AI 趋势

想了解大模型的行业动态、商业落地案例？大模型电子书？这份资料帮你站在 “行业高度” 学 AI：

1. 100+本大模型方向电子书

2. 26 份行业研究报告：覆盖多领域实践与趋势

报告包含阿里、DeepSeek 等权威机构发布的核心内容，涵盖：

职业趋势：《AI + 职业趋势报告》《中国 AI 人才粮仓模型解析》；
商业落地：《生成式 AI 商业落地白皮书》《AI Agent 应用落地技术白皮书》；
领域细分：《AGI 在金融领域的应用报告》《AI GC 实践案例集》；
行业监测：《2024 年中国大模型季度监测报告》《2025 年中国技术市场发展趋势》。

3. 600+套技术大会 PPT：听行业大咖讲实战

PPT 整理自 2024-2025 年热门技术大会，包含百度、腾讯、字节等企业的一线实践：

安全方向：《端侧大模型的安全建设》《大模型驱动安全升级（腾讯代码安全实践）》；
产品与创新：《大模型产品如何创新与创收》《AI 时代的新范式：构建 AI 产品》；
多模态与 Agent：《Step-Video 开源模型（视频生成进展）》《Agentic RAG 的现在与未来》；
工程落地：《从原型到生产：AgentOps 加速字节 AI 应用落地》《智能代码助手 CodeFuse 的架构设计》。

二、求职必看：大厂 AI 岗面试 “弹药库”，300 + 真题 + 107 道面经直接抱走

想冲字节、腾讯、阿里、蔚来等大厂 AI 岗？这份面试资料帮你提前 “押题”，拒绝临场慌！

1. 107 道大厂面经：覆盖 Prompt、RAG、大模型应用工程师等热门岗位

面经整理自 2021-2025 年真实面试场景，包含 TPlink、字节、腾讯、蔚来、虾皮、中兴、科大讯飞、京东等企业的高频考题，每道题都附带思路解析：

2. 102 道 AI 大模型真题：直击大模型核心考点

针对大模型专属考题，从概念到实践全面覆盖，帮你理清底层逻辑：

3. 97 道 LLMs 真题：聚焦大型语言模型高频问题

专门拆解 LLMs 的核心痛点与解决方案，比如让很多人头疼的 “复读机问题”：

三、路线必明： AI 大模型学习路线图，1 张图理清核心内容

刚接触 AI 大模型，不知道该从哪学起？这份「AI大模型学习路线图」直接帮你划重点，不用再盲目摸索！

路线图涵盖 5 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。

L1阶段:启航篇丨极速破界AI新时代

L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。

L2阶段：攻坚篇丨RAG开发实战工坊

L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。

L3阶段：跃迁篇丨Agent智能体架构设计

L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。

L4阶段：精进篇丨模型微调与私有化部署

L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。

L5阶段：专题集丨特训篇【录播课】

四、资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇

2025 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！