【小白必看】CopilotKit：一行代码集成AI助手，你的应用也能拥有“智能大脑“，yyds！-开发者社区

前言

ChatGPT、Claude、Gemini 这些 AI 模型很强大，但它们都是独立的聊天界面。如果你想在自己的应用里集成一个 AI 助手，让它能实时获取应用数据、执行应用操作、与用户协作——这就是另一个技术难题了。

CopilotKit 正是为解决这个"最后一公里"问题而生：让 AI Agent 真正成为你应用的一部分，而不只是一个聊天窗口。

一、解决了什么问题？

1. AI Agent 难以融入应用

当前的 AI 开发生态主要聚焦后端：

LangChain、LangGraph构建 Agent 推理流程
CrewAI编排多 Agent 协作
OpenAI、Claude API提供强大的 LLM 能力

但这些工具都缺少一个关键环节：如何将 Agent 优雅地集成到用户界面中？

开发者面临的挑战：

实时流式输出：LLM 生成的 token 需要实时显示，而不是等待完整响应
工具调用可视化：Agent 调用 API、执行代码时，用户需要看到进度
人机协作：用户要能审批 Agent 的操作、修改共享状态
状态同步：Agent 生成的计划、表格需要增量更新，不能每次都传输完整数据
多 Agent 协调：不同 Agent 之间需要协作，UI 要统一管理

结果是：开发者要为每个 Agent 项目写大量自定义的 WebSocket、SSE、状态管理代码。这不仅耗时，而且容易出错。

2. 缺乏统一的 Agent-UI 协议

更严重的问题是，每个 Agent 框架都有自己的通信方式：

LangGraph 用一套格式
CrewAI 用另一套
自定义 Agent 又是一套

前端开发者需要为每种 Agent 框架写不同的集成代码，无法复用。这就像每个品牌的充电器都不兼容一样痛苦。

3. CopilotKit 的解决方案

CopilotKit 提供了完整的解决方案：

🎯 统一协议层 - AG-UI Protocol

CopilotKit 创建并推动了 AG-UI（Agent-User Interaction Protocol）这个开放标准，定义了 Agent 和 UI 之间的通信规范。就像 HTTP 统一了网络通信，AG-UI 统一了 Agent-UI 通信。

⚛️ React 组件库

提供开箱即用的 UI 组件和 Hooks：

useAgent- 连接任何 AG-UI 兼容的 Agent
CopilotChat- 完整的聊天界面
CopilotSidebar、CopilotPopup- 侧边栏、弹窗形式
Headless UI - 完全自定义的无头组件

🔌 一行命令快速启动

npx copilotkit@latest init

🌐 跨框架支持

支持所有主流 Agent 框架：

LangGraph（LangChain）
CrewAI
Microsoft Agent Framework
Pydantic AI
任何自定义 Agent

☁️ Copilot Cloud 托管服务

提供可选的云端服务，开箱即用，无需搭建后端基础设施。

二、CopilotKit 是什么？

核心定位

CopilotKit 是一个全栈 Agentic 应用框架，专注于解决 AI Agent 的"最后一公里"问题——让 Agent 能够真正与用户交互、协作。

它包含三个核心部分：

1. AG-UI Protocol（协议层）

一个开放、轻量的事件流协议，定义了 17 种标准事件类型：

生命周期事件：Agent 运行开始、结束、错误
文本消息事件：流式输出 token
工具调用事件：Agent 调用工具的开始、进度、结果
状态管理事件：同步应用和 Agent 之间的共享状态
特殊事件：自定义扩展

这些事件通过 HTTP SSE（Server-Sent Events）或 WebSocket 传输，保持 Agent 和 UI 的实时同步。

2. React SDK（前端库）

提供完整的 React 组件和 Hooks，开发者无需关心底层协议细节：

import { useAgent } from '@copilotkit/react-core'import { CopilotChat } from '@copilotkit/react-ui'function MyApp() { const { agent } = useAgent({ name: 'my-agent', publicApiKey: process.env.NEXT_PUBLIC_CPK_KEY }) return <CopilotChat />}

3. Runtime SDK（后端库）

提供 TypeScript 和 Python SDK，帮助 Agent 框架快速适配 AG-UI 协议：

自动处理事件流
中间件支持
与 LangGraph、CrewAI 等框架的原生集成

生态系统集成

CopilotKit 已与主流 Agent 框架深度集成：

框架	状态	特点
LangGraph	✅ 原生支持	流式状态、中间步骤展示
CrewAI	✅ 原生支持	多 Agent 协作可视化
Microsoft Agent Framework	✅ 官方集成	ASP.NET Core 中间件
Pydantic AI	✅ 支持	类型安全的状态管理
LlamaIndex	✅ 支持	RAG 应用集成
Mastra	✅ 支持	工作流编排

社区还提供了多语言 SDK：Kotlin、Go、Java、Rust 等。

数据表现

⭐25.7k+ GitHub Stars
👥100k+ 开发者使用
🏢超过 10% 的财富 500 强企业采用
📦@ag-ui/core 周均数千次下载

三、怎么用？

1. 快速开始：一行命令

CopilotKit 提供了 CLI 工具，可以一键初始化项目：

npx copilotkit@latest init

这个命令会：

安装必要的依赖
配置 CopilotKit Provider
创建示例代码
设置环境变量模板

2. 方式一：使用 Copilot Cloud（推荐）

最简单的方式是使用官方托管服务，无需搭建后端。

步骤 1：获取 API Key

访问 https://cloud.copilotkit.ai/ 注册并创建项目，获取 Public API Key。

步骤 2：配置环境变量

# .env.localNEXT_PUBLIC_CPK_PUBLIC_API_KEY=your_api_key_here

步骤 3：包裹应用

在app/layout.tsx中添加 CopilotKit Provider：

import { CopilotKit } from "@copilotkit/react-core"import "@copilotkit/react-ui/styles.css"export default function RootLayout({ children }) { return ( <html lang="zh"> <body> <CopilotKit publicApiKey={process.env.NEXT_PUBLIC_CPK_PUBLIC_API_KEY} > {children} </CopilotKit> </body> </html> )}

步骤 4：添加聊天界面

在任何页面组件中使用：

import { CopilotChat } from "@copilotkit/react-ui"export default function HomePage() { return ( <div> <h1>我的应用</h1> <CopilotChat instructions="你是一个友好的助手，帮助用户完成任务" /> </div> )}

就这么简单！现在你的应用已经有了一个可以对话的 AI 助手。

3. 方式二：连接自定义 Agent

如果你已经有了自己的 Agent（LangGraph、CrewAI 等），可以使用useAgentHook 连接。

后端：创建 AG-UI 兼容的 Agent

以 LangGraph 为例：

# agent/main.pyfrom langgraph.graph import StateGraphfrom copilotkit import CopilotKitSDK, LangGraphAgent# 定义你的 Agent 图workflow = StateGraph(AgentState)workflow.add_node("research", research_node)workflow.add_node("analyze", analyze_node)graph = workflow.compile()# 用 CopilotKit 包装agent = LangGraphAgent( name="research_agent", graph=graph, description="Research and analysis agent")# 创建 FastAPI 应用from fastapi import FastAPIapp = FastAPI()sdk = CopilotKitSDK(agents=[agent])app.include_router(sdk.router)

前端：使用 useAgent Hook

import { useAgent } from "@copilotkit/react-core"function ResearchPage() { const { messages, // 所有消息 isLoading, // 加载状态 sendMessage, // 发送消息函数 agentState // Agent 的共享状态 } = useAgent({ name: "research_agent", initialState: { topic: "" } }) return ( <div> <MessageList messages={messages} /> <input onSubmit={(text) => sendMessage(text)} disabled={isLoading} /> </div> )}

4. 核心功能示例

功能 1：Headless UI 完全自定义

如果不想用预制组件，可以完全自定义：

import { useCopilotChat } from "@copilotkit/react-core"function CustomChat() { const { visibleMessages, appendMessage, setMessages, isLoading } = useCopilotChat() return ( <div className="my-custom-chat"> {visibleMessages.map(msg => ( <div key={msg.id} className={msg.role}> {msg.content} </div> ))} {/* 你的自定义输入框 */} </div> )}

功能 2：共享状态同步

Agent 和应用共享同一个状态对象：

import { useCoAgent } from "@copilotkit/react-core"function WeatherApp() { const { agentState, updateAgentState } = useCoAgent({ name: "weather_agent", initialState: { city: "Beijing", temperature: null } }) // Agent 可以直接修改 agentState.temperature // 应用也可以调用 updateAgentState return ( <div> <h2>{agentState.city}</h2> <p>{agentState.temperature}°C</p> </div> )}

功能 3：Human-in-the-Loop 审批

用户可以审批 Agent 的操作：

import { useCopilotAction } from "@copilotkit/react-core"function EmailApp() { useCopilotAction({ name: "send_email", parameters: [ { name: "to", type: "string" }, { name: "subject", type: "string" }, { name: "body", type: "string" } ], renderAndWaitForResponse: ({ args, respond }) => { return ( <div className="email-preview"> <h3>发送邮件确认</h3> <p>收件人：{args.to}</p> <p>主题：{args.subject}</p> <div>{args.body}</div> <button onClick={() => respond({ approved: true })}> 发送 </button> <button onClick={() => respond({ approved: false })}> 取消 </button> </div> ) } })}

Agent 调用send_email工具时，会暂停并显示这个 UI 组件等待用户决策。

功能 4：Generative UI

Agent 可以动态生成 UI 组件：

import { useCoAgentStateRender } from "@copilotkit/react-core"useCoAgentStateRender({ name: "data_agent", render: ({ state }) => { if (state.chart_data) { return <ChartComponent data={state.chart_data} /> } if (state.table_data) { return <TableComponent data={state.table_data} /> } return null }})

Agent 更新状态时，UI 会自动渲染对应的组件。

功能 5：中间状态流式传输

显示 Agent 的推理过程：

import { copilotKitCustomizeConfig } from "@copilotkit/runtime"// 后端配置const modifiedConfig = copilotKitCustomizeConfig(config, { emitIntermediateState: [ { stateKey: "outline", tool: "set_outline", toolArgument: "outline" } ]})

前端会实时收到 Agent 生成大纲的每一步更新。

5. 实战案例：餐厅推荐 Agent

让我们构建一个完整的餐厅推荐应用，结合 CrewAI 和 CopilotKit。

后端：CrewAI Agent

# restaurant_finder/crew.pyfrom crewai import Agent, Task, Crewfrom crewai_tools import SerperDevToolsearch_tool = SerperDevTool()researcher = Agent( role='餐厅研究员', goal='找到符合用户需求的最佳餐厅', tools=[search_tool], verbose=True)analyzer = Agent( role='美食分析师', goal='分析餐厅评价和推荐理由', verbose=True)research_task = Task( description='搜索 {location} 附近的 {cuisine_type} 餐厅', agent=researcher, expected_output='餐厅列表及基本信息')analysis_task = Task( description='分析餐厅评价，给出推荐排名', agent=analyzer, expected_output='带推荐理由的排序列表')crew = Crew( agents=[researcher, analyzer], tasks=[research_task, analysis_task], verbose=True)

部署到 Copilot Cloud

# 提交到 CrewAI 企业平台crewai deploy

获取 Agent 名称（例如restaurant_finder）。

前端：Next.js 应用

// app/page.tsx'use client'import { CopilotChat } from "@copilotkit/react-ui"import "@copilotkit/react-ui/styles.css"export default function RestaurantFinder() { return ( <div className="container"> <h1>AI 餐厅推荐助手</h1> <CopilotChat instructions={` 你是一个专业的餐厅推荐助手。 当用户提供位置和菜系偏好时，你会： 1. 搜索该区域的相关餐厅 2. 分析评价和特色 3. 给出排序推荐和理由 请用友好的语气与用户交流。 `} labels={{ title: "餐厅推荐", initial: "你好！告诉我你想吃什么类型的菜，在哪个区域？" }} /> </div> )} ``````plaintext // app/layout.tsximport { CopilotKit } from "@copilotkit/react-core"export default function RootLayout({ children }) { return ( <html lang="zh"> <body> <CopilotKit agent="restaurant_finder" publicApiKey={process.env.NEXT_PUBLIC_CPK_KEY} > {children} </CopilotKit> </body> </html> )}

就这样！一个完整的多 Agent 协作应用就完成了。

6. 进阶功能

多 Agent 协调

在一个应用中使用多个专业 Agent：

<CopilotKit> <AgentSelector> <Agent name="researcher" /> <Agent name="writer" /> <Agent name="coder" /> </AgentSelector></CopilotKit>

自定义样式

CopilotKit 组件支持完整的 CSS 自定义：

<CopilotChat className="my-chat" styles={{ chatContainer: { maxHeight: '600px' }, messageInput: { borderRadius: '20px' } }}/>

安全防护

内置 Prompt Injection 防护和敏感数据过滤：

<CopilotKit guardrails={{ preventPromptInjection: true, blockSensitiveData: true, enforceCompliance: ['GDPR', 'CCPA'] }}>

分析和监控

集成了 AI 产品分析功能，追踪用户-Agent 交互：

<CopilotKit analytics={{ trackInteractions: true, logAgentSteps: true }}>

四、为什么选择 CopilotKit？

1. 极速上手，分钟级集成

npx copilotkit@latest init

一行命令，5 分钟内就能在应用中添加 AI 助手。

2. 生产级可靠性

✅ 内置安全防护
✅ 错误处理和重连
✅ 性能优化
✅ 类型安全（TypeScript）
✅ 云端托管可用

3. 完全开源，社区驱动

GitHub 25.7k+ Stars
活跃的 Discord 社区
持续更新和维护
透明的开发流程

4. 框架无关，生态丰富

兼容任何 Agent 框架
支持任何 LLM（OpenAI、Claude、Gemini、本地模型）
多语言 SDK 支持
与 LangGraph、CrewAI 等深度集成

5. 灵活性与可定制性

预制组件开箱即用
Headless UI 完全自定义
插件和中间件系统
无供应商锁定

6. 企业级支持

10%+ 财富 500 强企业使用
Copilot Cloud 提供托管服务
技术支持和咨询
合规和安全认证

五、AG-UI 协议：统一的标准

CopilotKit 的一个重要贡献是推动了AG-UI Protocol成为行业标准。

协议愿景

就像 HTTP 统一了 Web 通信，AG-UI 要统一 Agent-UI 通信：

任何 Agent 框架都可以发出 AG-UI 事件
任何 UI 框架都可以消费 AG-UI 事件
组件可互换、可复用

生态系统采纳

AG-UI 已被多个主流框架采纳：

官方支持：

Microsoft Agent Framework
LangGraph
CrewAI
Pydantic AI

社区集成：

AWS Strands（刚宣布集成）
Agno
Mastra
LlamaIndex

多语言 SDK：

TypeScript（官方）
Python（官方）
Kotlin
Go
Java
Rust

与其他协议的关系

AG-UI 与其他协议互补，不是竞争：

协议	作用	与 AG-UI 关系
MCP(Model Context Protocol)	模型访问上下文	互补，MCP 提供上下文，AG-UI 处理 UI 交互
A2A(Agent-to-Agent)	Agent 间协作	互补，A2A 处理 Agent 协调，AG-UI 处理用户交互
A2UI(Google)	生成式 UI 规范	互补，A2UI 定义 UI 组件，AG-UI 提供完整的双向连接

这些协议共同构建了完整的 Agentic 应用栈。

六、实际应用场景

场景 1：企业知识库助手

为内部知识库添加 AI 搜索和问答：

<CopilotChat instructions="搜索企业知识库，回答员工问题" context={{ knowledgeBase: companyDocs }} tools={[searchKnowledgeBase, createTicket]}/>

场景 2：代码审查助手

在代码编辑器中集成 AI 代码审查：

useCoAgent({ name: "code_reviewer", initialState: { currentFile: file }, tools: [analyzeCode, suggestRefactor]})

场景 3：客户支持 Bot

智能客服，能查询订单、处理退款：

<CopilotSidebar instructions="帮助客户解决订单问题" tools={[queryOrder, processRefund, escalateToHuman]}/>

场景 4：数据分析仪表板

自然语言查询数据库，生成可视化：

useCoAgentStateRender({ name: "data_analyst", render: ({ state }) => { if (state.chartType === 'bar') { return <BarChart data={state.data} /> } if (state.chartType === 'line') { return <LineChart data={state.data} /> } }})

场景 5：内容创作平台

辅助用户写作、编辑、发布：

<CopilotTextarea instructions="帮助用户撰写文章" autosuggest={true} tools={[research, generateOutline, proofread]}/>

七、最佳实践

1. 清晰的 Agent 指令

// ❌ 模糊instructions: "帮助用户"// ✅ 清晰instructions: ` 你是一个专业的数据分析助手。 - 用户提供数据集时，先理解数据结构 - 根据用户问题生成 SQL 查询 - 将结果可视化为图表 - 用简洁的语言解释发现`

2. 合理的工具设计

每个工具应该单一职责、参数清晰：

useCopilotAction({ name: "analyze_sentiment", description: "分析文本情感倾向", parameters: [ { name: "text", type: "string", description: "要分析的文本内容", required: true } ], handler: async ({ text }) => { const result = await analyzeSentiment(text) return { sentiment: result.label, confidence: result.score } }})

3. 优雅的错误处理

const { messages, error } = useAgent({ name: "my_agent" })if (error) { return <ErrorFallback error={error} />}

4. 性能优化

// 使用虚拟滚动处理大量消息import { VirtualizedMessageList } from "@copilotkit/react-ui"<VirtualizedMessageList messages={messages} maxHeight={600}/>

5. 测试策略

// 使用 Mock Provider 进行测试import { MockCopilotKitProvider } from "@copilotkit/react-core/test"test('chat interface works', () => { render( <MockCopilotKitProvider mockResponses={[ { role: 'assistant', content: 'Hello!' } ]} > <ChatComponent /> </MockCopilotKitProvider> )})

八、总结

CopilotKit 正在改变 AI Agent 的开发方式，让 Agent 真正走进用户应用，而不只是停留在聊天窗口。

核心价值

✅极速集成- 5 分钟内为应用添加 AI 能力
✅生产可用- 内置安全、监控、错误处理
✅开放标准- AG-UI 协议打破框架壁垒
✅全栈方案- 前端 + 后端 + 协议完整支持
✅生态丰富- 支持所有主流 Agent 框架和 LLM
✅企业级- 财富 500 强企业的选择

立即开始

# 1. 初始化项目npx copilotkit@latest init# 2. 获取 API Key# 访问 https://cloud.copilotkit.ai/# 3. 运行应用npm run dev

未来趋势

随着 AG-UI 协议被越来越多的框架采纳，我们即将看到：

组件市场- 可复用的 Agentic UI 组件
跨平台支持- 移动端、桌面端统一体验
多模态交互- 语音、图像、视频结合
自主学习- Agent 从用户反馈中持续改进

CopilotKit 不仅是一个工具，更是 Agentic 应用时代的基础设施。

相关链接：

官方网站：https://www.copilotkit.ai/
GitHub 仓库：https://github.com/CopilotKit/CopilotKit
文档：https://docs.copilotkit.ai/
AG-UI 协议：https://docs.ag-ui.com/
Discord 社区：https://discord.gg/copilotkit
Copilot Cloud：https://cloud.copilotkit.ai/

你准备好在应用中集成 AI Agent 了吗？试试 CopilotKit，体验 Agentic 应用开发的新方式！

如何学习大模型 AI ？

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

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

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

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

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

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

第一阶段（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 的正确特征了。

前言