想快速给前端加个AI小助手？这个CopilotKit神器，跟着一步步实战，感觉比想象中简单多了！

最近你可能听过一个新的AG-UI（Agent-User InteractionProtocol）协议：定义了前端UI和后端Agent之间的集成标准。不过与MCP/A2A协议不同的是，AG-UI是从实际产品中提炼出来的标准。这个产品就是CopilotKit：一个强大的、用来集成前端UI与后端Agent的开源神器，也是AG-UI协议的参考实现。

本篇将结合实例，为你深入展示 CopilotKit 的核心能力。你不仅能掌握这一实用新工具，更能真正理解 AG-UI 协议的落地应用，摆脱停留在表面的概念认知。

• CopilotKit与AG-UI初探
• 构建一个CopilotKit的演示Demo
• CopilotKit能力之：前后端State共享
• CopilotKit能力之：调用前端“工具”
• CopilotKit能力之：基于Agent的生成式UI
• CopilotKit能力之：HITL（人类参与流程）
• 其他与总结

我们分成两篇一步步介绍（源代码见文末）。

开始前，欢迎了解本号重磅新作

01CopilotKit与AG-UI初探

【挑战在哪里】

MCP简化了Agent与工具间的集成；A2A则专注于Agent与Agent之间的互操作。但在实际应用中，还有一类集成：Agent与前端UI间的集成。这里的集成并非简单的通过FastAPI来调用Agent可以解决。比如：

一个财务分析助手，不仅需要在后台调用大模型和数据库，还需要在前端实时渲染逐步生成的分析报告、动态更新图表、插入交互式的问答面板，让用户可以点击“深入分析”或“重新计算”按钮。这要求 UI 和 Agent 之间能以流式、事件驱动的方式同步状态，而不仅仅是一问一答的API调用。

AG-UI协议与CopilotKit正是为了满足这种高频、细粒度、双向的人机协作需求而诞生。

【AG-UI协议】

AG-UI协议连接的目标就是前端UI（代表客户）与后端AI智能体，对它们之间的通信、事件、协作等进行标准化。AG-UI与MCP、A2A之间的区别与关系非常清晰：

【CopilotKit】

CopilotKit 可以被看作 AG-UI 协议实现的一个框架。它提供了完整的前后端集成方案，使开发者能够快速将 AI  Copilot引入应用，包括：TypeScript/React 前端组件库、Python/Node SDK、以及可选的云端代理服务等。

简单来说，CopilotKit 让你的应用可以在前端无缝嵌入一个 AI Copilot（聊天窗口、副驾驶面板等），并与后端任意 Agent 保持交互 。它支持目前主流的智能体框架（LangGraph、LlamaIndex、CrewAI等），并且开箱即用地支持事件流、多路 Agent、可插拔工具、HITL、生成式UI等高级功能 。

接下来将通过一个实际的例子，演示如何一步步利用 CopilotKit 快速集成一个前端 AI 助手和后端 AI Agent，并深入体验其核心能力。

  这份完整版的大模型 AI 学习资料已经上传ZEEKLOG，朋友们如果需要可以微信扫描下方ZEEKLOG官方认证二维码免费领取【保证100%免费】

0构建一个CopilotKit的演示Demo

我们通过一个实际的Demo来演示CopilotKit的能力。该Demo架构如下：

主要包括三个部分：

• 后端Agent：使用LangGraph构建的一个Workflow智能体。
• 前端应用：使用React+TS构建简单的Demo（也可以是你的现成应用）。
• Copilot助手：使用CopilotKit给前端应用嵌入的智能助手。

【后端Agent准备与启动】

准备一个简单的LangGraph Agent，这里交给它两个Tool，一个用来Web搜索，一个模拟查询天气。将该Agent保存在agent.py，并可以导出使用。

为了让Agent与前端UI实现通信和调用，我们仍然需要FastAPI。但这里需要使用CopilotKIt提供的FastAPI集成工具进行配置，方法如下：

...

注意这里的sample_agent.agent就是导入上面创建好的Agent。

接着正常启动（uvicorn.run）FastAPI服务即可：

【前端应用准备与启动】

接着来准备前端UI应用。你使用现成的ReactTS应用。这里我们直接用Next.js脚手架创建一个全新的React应用：

npx create-next-app@latest

我们对app/page.tsx稍作美化，让前端主页面展示如下：

现在你可以启动这个Next.js应用，并在浏览器中观察效果。

【集成AI Copilot】

现在给这个前端UI增加AI Copilot，并实现与后端Agent的基本互动。

步骤1：安装依赖包

给前端安装CopilotKit依赖包：

npm install @copilotkit/react-ui @copilotkit/react-core npm install @copilotkit/runtime class-validator

步骤2：增加路由到后端Agent

目的：让后面上Copilot的请求能够被发送到后端Agent。

方法：在app/api/copilotkit目录下增加route.ts文件，核心部分如下：

... const runtime = new CopilotRuntime({   remoteEndpoints: [{url: "http://localhost:8080/copilotkit"},], }); exportconst POST = async (req: NextRequest) => { const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({     runtime,     serviceAdapter,     endpoint: "/api/copilotkit",   }); return handleRequest(req); };

注意这里http://.../copilotkit就是上面FastAPI配置的端点。

步骤3：配置全局 CopilotKit 功能

目的：让应用中的页面都可以使用CopilotKit创建Copilot。

方法：在app/layout.tsx文件中的RootLayout函数中配置CopilotKit组件即可：

<CopilotKit   agent="sample_agent"     runtimeUrl="/api/copilotkit"   showDevConsole={false} >   {children} </CopilotKit>

注意这里agent是后端agent的名字；runtimeUrl与前面的路由匹配。

步骤4：给页面增加Copilot

现在我们可以给任何页面（这里只有一个主页面page.tsx）增加Copilot界面，与Agent对话，实现智能交互体验。你可以选择sidebar（边栏）、popup（弹出式）、chat（聊天）等多种UI形式。这里我们添加一个popup形式的Copilot到主页。

在app/page.tsx中添加一个CopilotPopup的UI组件即可：

... export defaultfunctionYourApp() { return (     <>     <Home/>      <CopilotPopup      defaultOpen={true}      instructions={"你是个智能助手，尽可能用已有的知识回答问题"}      labels={{        title: "智能AI Copilot",        initial: `  # 👋 您好！  我是你的智能Copilot。..........        `      }}    />      </>   ); } ...

前端效果测试

OK！这就是全部工作。你无需设计对话的UI、无需调试CSS、无需实现对后端Agent的调用、无需考虑流式展现...等等一系列问题。

打开主页面，会发现右下角有一个popup按钮，点击后出现Chat界面，简单测试：

接下来我们将探索CopilotKit的更多能力。

0CopilotKit能力之：State共享

【什么是State（状态）共享】

我们知道LangGraph的Agent会维护一个内部的自定义状态（State），用来在工作流运行期间传递与同步信息。借助CopilotKit，你可以实现在前端UI与后端Agent之间自动双向同步与共享这个自定义的State信息。

注意这里的前端UI并不仅仅是Copilot的Chat界面，而是整个应用。

【实例展示】

现在对上面的Demo做增强，来展示后端Agent状态如何实时同步到前端UI上展示。

步骤1：定义Agent的State

我们在后端Agent的State中增加一个信息用来保存搜索工具的调用历史：

class AgentState(MessagesState):     search_history: list[str] = [] # 搜索历史记录

然后在Agent的LLM调用节点中判断如果产生了搜索工具的调用需求，就增加一条搜索记录。大致如下）：

...     # 如果是搜索工具，保存搜索历史     if response.tool_calls[0].get("name") in ["tavily-search"]:            search_history = state.get("search_history", [])            search_query = response.tool_calls[0].get("args", {})            search_history.append(search_query["query"])            updated_state["search_history"] = search_history          return Command(goto="tool_node", update=updated_state) ...

步骤2：前端Hook设置

现在我们想把这个后端State中的搜索历史实时展示在前端UI上，只需要使用CopilotKit提供的useCoAgent这个hook函数（hook是前端React框架的状态管理机制）即可：

... type AgentState = {  search_history: string[], } function Home() {  #使用useCoAgent hook函数 const {state, setState} = useCoAgent<AgentState>({     name: "sample_agent",     initialState: {       search_history: []     },   })  #在UI部分使用state return ( <div>   ...{state.search_history} </div>

这段代码中：

• 定义与后端Agent匹配的AgentState，有一个对应的search_history
• 使用用useCoAgent设置前端状态，提供后端Agent名称与初始状态
• 接着就可以在UI部分使用state.search_history来直接展示后端State

前端效果测试

在Copilot的Chat界面中提出两个需要Web搜索的问题，很快就可以在左边的UI上看到后端Agent在调用工具时的搜索关键词，它被自动同步到了前端！

【更多功能】

以上展示了将后端Agent状态同步到前端。相反，你也可以将前端设置的状态实时更新给后端Agent使用，这是一种双向同步的机制。可以很方便的用到这些场景：

• 用户在前端UI上更改Agent设置，这些设置被自动同步给Agent。比如：更改Agent回复的语言或风格。
• 后端Agent运行时将当前进度保存到状态中，前端可以实时的获取并渲染Agent的运行状态，而不只是“加载中...”。

CopilotKit能力之：调用前端“工具”

【什么是前端工具】

Agent的基本能力之一是工具（Tool）的使用，CopilotKit可以让后端的LangGraph Agent拥有一项神奇的能力：它不仅可以调用后端设置的工具（比如搜索、访问数据库、MCP），还可以调用前端定义的UI“工具”（比如更改样式）！

【实例展示】

我们继续增强上面的Demo来展示这种能力。

步骤1：注册前端“工具”

使用useCopilotAction hook来注册一个前端Action。比如，我们创建一个前端Action向用户弹出简单的Alert消息：

useCopilotAction({   name: "sayHello", // Action 名称，Agent 将通过此名称来调用工具   description: "向指定用户问好", // 对该 Action 的描述（供 Agent 理解用途）   parameters: [ // 定义参数列表     { name: "name", type: "string", description: "要问好的对象名字" }   ],   render: "正在发送问候...", // (可选) 执行时在Chat中显示的提示文本   handler: async ({ name }) => { // 定义具体执行逻辑的函数（异步支持）         alert(`Hello, ${name}!`); // 这里在浏览器弹出提示框     return('问候已发送给' + name); // 返回给Agent的结果     } });

这个Action是不是非常像开发Agent时定义的工具呢？

上面代码在前端注册了一个名为 "sayHello" 的 Copilot 动作：它需要一个字符串参数 name。我们提供了 handler 函数，当 Agent 触发该工具时，handler 会被调用，在浏览器中弹出问候信息。render: "正在发送问候..." 则用于在 Chat 界面上显示一个临时消息提示，让用户知道Agent正在执行“问好”操作。

步骤2：给后端Agent添加工具

首先，你需要让Agent的State从CopilotState派生而不是之前LangGraph提供的MessagesState，其他无需改变：

from copilotkit import CopilotKitState class AgentState(CopilotKitState):     search_history: list[str] = [] # 搜索历史记录

其次，将前端Action作为工具给Agent使用。我们的例子中是通过LLM绑定：

... # 3. 绑定工具到模型 model_with_tools = model.bind_tools(     [         *state["copilotkit"]["actions"], # CopilotKit actions         *all_tools, # 其他后端的工具     ], )

这里只需要一行代码，就可以从State中获得前端的Action，并作为工具交给Agent使用。

前端效果测试

现在我们在前端Copilot的Chat界面中测试一个问题：

Agent 在理解意图后，会选择调用我们定义的前端sayHello 工具，并传入参数 { "name": "张三" }。前端CopilotKit 收到工具调用事件后，就会执行注册的 handler：

与此同时，CopilotKit 会把执行结果反馈给后端Agent，Agent 随后继续生成并在Chat界面显示结果：

注意我们并没有在后端 Agent 明确编写任何关于前端工具的逻辑：CopilotKit 自动完成了前端 Action 的注册和后端 Agent 之间的协议对接。

  这份完整版的大模型 AI 学习资料已经上传ZEEKLOG，朋友们如果需要可以微信扫描下方ZEEKLOG官方认证二维码免费领取【保证100%免费】

一、大模型风口已至：月薪30K+的AI岗正在批量诞生

2025年大模型应用呈现爆发式增长，根据工信部最新数据：

国内大模型相关岗位缺口达47万

初级工程师平均薪资28K

70%企业存在"能用模型不会调优"的痛点

真实案例：某二本机械专业学员，通过4个月系统学习，成功拿到某AI医疗公司大模型优化岗offer，薪资直接翻3倍！

二、如何学习大模型 AI ？

🔥AI取代的不是人类，而是不会用AI的人！麦肯锡最新报告显示：掌握AI工具的从业者生产效率提升47%，薪资溢价达34%！🚀

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

1️⃣ 提示词工程：把ChatGPT从玩具变成生产工具
2️⃣ RAG系统：让大模型精准输出行业知识
3️⃣ 智能体开发：用AutoGPT打造24小时数字员工

📦熬了三个大夜整理的《AI进化工具包》送你：
✔️ 大厂内部LLM落地手册（含58个真实案例）
✔️ 提示词设计模板库（覆盖12大应用场景）
✔️ 私藏学习路径图（0基础到项目实战仅需90天）

第一阶段（10天）：初阶应用

该阶段让大家对大模型 AI有一个最前沿的认识，对大模型 AI 的理解超过 95% 的人，可以在相关讨论时发表高级、不跟风、又接地气的见解，别人只会和 AI 聊天，而你能调教 AI，并能用代码将大模型和业务衔接。

*   大模型 AI 能干什么？
*   大模型是怎样获得「智能」的？
*   用好 AI 的核心心法
*   大模型应用业务架构
*   大模型应用技术架构
*   代码示例：向 GPT-3.5 灌入新知识
*   提示工程的意义和核心思想
*   Prompt 典型构成
*   指令调优方法论
*   思维链和思维树
*   Prompt 攻击和防范
*   …

第二阶段（30天）：高阶应用

该阶段我们正式进入大模型 AI 进阶实战学习，学会构造私有知识库，扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架，抓住最新的技术进展，适合 Python 和 JavaScript 程序员。

*   为什么要做 RAG
*   搭建一个简单的 ChatPDF
*   检索的基础概念
*   什么是向量表示（Embeddings）
*   向量数据库与向量检索
*   基于向量检索的 RAG
*   搭建 RAG 系统的扩展知识
*   混合检索与 RAG-Fusion 简介
*   向量模型本地部署
*   …

第三阶段（30天）：模型训练

恭喜你，如果学到这里，你基本可以找到一份大模型 AI相关的工作，自己也能训练 GPT 了！通过微调，训练自己的垂直大模型，能独立训练开源多模态大模型，掌握更多技术方案。

到此为止，大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗？

*   为什么要做 RAG
*   什么是模型
*   什么是模型训练
*   求解器 & 损失函数简介
*   小实验2：手写一个简单的神经网络并训练它
*   什么是训练/预训练/微调/轻量化微调
*   Transformer结构简介
*   轻量化微调
*   实验数据集的构建
*   …

第四阶段（20天）：商业闭环

对全球大模型从性能、吞吐量、成本等方面有一定的认知，可以在云端和本地等多种环境下部署大模型，找到适合自己的项目/创业方向，做一名被 AI 武装的产品经理。

*   硬件选型
*   带你了解全球大模型
*   使用国产大模型服务
*   搭建 OpenAI 代理
*   热身：基于阿里云 PAI 部署 Stable Diffusion
*   在本地计算机运行大模型
*   大模型的私有化部署
*   基于 vLLM 部署大模型
*   案例：如何优雅地在阿里云私有部署开源大模型
*   部署一套开源 LLM 项目
*   内容安全
*   互联网信息服务算法备案
*   …

学习是一个过程，只要学习就会有挑战。天道酬勤，你越努力，就会成为越优秀的自己。

如果你能在15天内完成所有的任务，那你堪称天才。然而，如果你能完成 60-70% 的内容，你就已经开始具备成为一名大模型 AI 的正确特征了。

这份完整版的大模型 AI 学习资料已经上传ZEEKLOG，朋友们如果需要可以微信扫描下方ZEEKLOG官方认证二维码免费领取【保证100%免费】