CopilotKit:用 AG-UI 协议把 Agent 接到 Web / Slack / Teams 的开源中间层
它解决什么问题
Agent 后端框架这两年卷得厉害——LangGraph、AutoGen、LlamaIndex、CrewAI,光选哪个就够头疼。前端这块一直没人管:Agent 输出的 token 流怎么渲染?Agent 想让用户确认一个操作怎么办?Agent 要弹表单、改图表,UI 那边怎么响应?
这些问题我被问了不下十次。大家写完 LangGraph agent,本地跑得欢,一接到 Web 上就懵——自己手撸 SSE、处理 tool_call、把中间态塞进 React state,三百行胶水代码下去,业务逻辑还没写。
CopilotKit 想当 Agent 和用户之间的中间层。同一个 Agent 既能驱动 React 网页,也能跑在 Slack、Microsoft Teams、iMessage 里,还能做 Human-in-the-loop 的审批流。它不抢 Agent 框架的活,只负责"最后一公里"——接住 Agent 的输出,再把 UI 的反馈送回去。
截至分析时,仓库 36,880 stars,MIT 协议,TypeScript 为主,同时提供 Python Runtime。
怎么用
一行 npx copilotkit@latest create 拉脚手架,配上 OpenAI 或 Anthropic 的 key 就能跑。
代码层面,最小例子:
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";
function App() {
return (
<CopilotKit runtimeUrl="/api/copilotkit">
<CopilotChat
instructions="你是一个订单助手,可以调用工具修改订单状态"
labels={{
title: "订单助手",
initial: "你好,问我任何订单问题",
}}
/>
</CopilotKit>
);
}
Python 后端用 FastAPI 挂载 Runtime:
from copilotkit import CopilotKitSDK, LangGraphAgent
from fastapi import FastAPI
app = FastAPI()
sdk = CopilotKitSDK(
agents=[
LangGraphAgent(
name="order_agent",
graph=my_langgraph,
# 关键:声明前端可调用的 tool
frontend_tools=["update_order_status", "render_invoice"],
)
]
)
app.mount("/api/copilotkit", sdk)
Agent 不只能调后端 tool,还能调"前端 tool"。比如 update_order_status——Agent 一调,UI 那边表格就实时高亮被改的行。不是 WebSocket 推事件让你自己解析,是 CopilotKit 直接帮你把状态同步好。
它怎么工作
架构分三层:
① AG-UI 协议层——基于 SSE 的事件流协议,定义 Agent 和前端之间的 16 种事件类型,覆盖消息、工具调用、状态同步、人工介入请求等。AG-UI 是 CopilotKit 团队今年 7 月捐出的开放协议,已被 Google、LangChain、AWS、Microsoft、Mastra、PydanticAI 采用。少有的开源主导的 Agent 通信标准。
② CopilotKit Runtime——Node 或 Python 后端,桥接你的 Agent 框架。不管用 LangGraph、AutoGen 还是自己写的 ReAct,只要包一层 LangGraphAgent 或 AutogenAgent,Runtime 就知道怎么把输出转成 AG-UI 事件。
③ 前端 SDK——React、Angular、Vue、React Native、Slack、Microsoft Teams 的适配层。核心包 @copilotkit/react-core 维护在 npm 公共 registry,把协议事件翻译成可渲染的 UI 组件。
这套架构里我觉得最值的不是 AG-UI 本身,是 Shared State。Agent 和前端共享同一个状态对象:Agent 能读懂 UI 状态(比如"用户当前在看哪个订单"),UI 也能响应 Agent 的状态变更(比如"Agent 把订单改成已发货")。双向同步,不需要你手写 reconcile。
它哪里好 / 哪里不好
好的地方:
- AG-UI 是少数开源主导的 Agent 通信标准。Google、AWS、Microsoft 一起点头,这在 Agent 圈很少见。
- 多端统一是真痛点。Web、Slack、Teams、iMessage 同一个 Agent,复用的是后端逻辑,不是 UI 代码。
- Generative UI(Agent 动态决定弹什么组件)做得比 Vercel AI SDK 深。Vercel 的
streamUI主要解决"渲染 token 流",CopilotKit 能让 Agent 主动生成完整的表单、图表、审批卡片。
不好的地方:
- 中文文档稀薄。官方 docs 英文优先,社区翻译断断续续。
- Angular、Vue、React Native 支持明显弱于 React。React 是 first-class,其他端能用但 API 不齐。
- 36.8K stars 里很大一部分来自 AG-UI 协议光环,实际 SDK 用法门槛比 LangChain 高。LangChain 概念简单,CopilotKit 要理解 Runtime、Agent、Tool、State 四层,新手曲线陡。
- 核心包
@copilotkit/react-coregzip 后大约 80KB。对 SDK 体积敏感的小项目,这个数字不小。
我试了下
跑了官方 create 脚手架,5 分钟内起了一个 React + Python FastAPI 后端的 demo。接上 LangGraph Agent,让它调用 update_order_status 前端 tool——UI 那边表格会实时高亮被改的行。
Shared State 同步延迟肉眼几乎不可见。我在 console 里打了时间戳,从 Agent 调 tool 到 React 组件收到 state 更新,间隔在 50ms 以内。
对比之前用纯 LangGraph 自己写 SSE 流处理,省了大约 200 行胶水代码——主要是 tool_call 解析、中间态累积、错误重试这三块。
一个意外发现:CopilotKit 的 Generative UI 不只是"渲染 token",它能让 Agent 主动生成 <form>、<button>、<chart> 这种完整组件。配上 human-in-the-loop 事件类型,Agent 可以中途停下来问用户"确认提交吗?",UI 弹确认框,用户点了之后 Agent 再继续。这个审批流不用你自己写状态机。
谁该用
适合:
- 做 ToB SaaS 想加 AI 助手、又不想给每个端(Web、Slack、Teams)重写一遍的团队。这是 CopilotKit 的杀手锏场景。
- 想做 Generative UI(Agent 自己决定弹什么表单/图表)的人。
- 想用 LangGraph/AutoGen 但前端集成搞不定的人。Runtime 已经帮你适配好。
不适合:
- 只想要一个聊天框。直接用 Vercel AI SDK 的
useChat更轻,依赖更少。 - 对 SDK 体积敏感的小项目(核心包 80KB gzip)。
- 完全不做多端的纯命令行/纯后端 Agent。CopilotKit 的价值在前端层,你用不到等于白装。
来源
- GitHub 仓库:https://github.com/CopilotKit/CopilotKit
- AG-UI 协议规范:仓库 docs 目录下有完整事件类型定义
- npm 包:https://www.npmjs.com/package/@copilotkit/react-core