夜雨聆风
CopilotKit + AG-UI 源码解读：让 Agent 驱动 UI
在 Agentic 协议栈里，Anthropic 的 MCP 管"Agent 怎么调工具"，Google 的 A2A 管"Agent 之间怎么协作"。但有一个空白——Agent 的推理过程和决策结果，怎么变成用户能看见、能交互的界面？
AG-UI 填的就是这个空白。它把 Agent 和 UI 之间的通信抽象成 35 种标准事件。任何 Agent 只要输出这组事件，任何 UI 只要理解这组事件，就能对接。
整个协议的心智模型是一行类型签名：
type RunAgent = (input: RunAgentInput) => Observable<BaseEvent>Observable 是关键——Agent 做一点就发一点，UI 收到一点就渲染一点。Promise 是"做完了再告诉你"，Observable 是"边做边告诉你"。
一、35 个事件：16 个核心 + 19 个扩展
AG-UI 的 35 个事件不是散装的——16 个核心事件覆盖了 Agent-UI 的全部基本交互模式，剩余的 19 个是扩展和辅助。
| 生命周期 | RUN_STARTEDRUN_FINISHEDRUN_ERRORSTEP_STARTEDSTEP_FINISHED | ||
| 文本消息 | TEXT_MESSAGE_STARTTEXT_MESSAGE_CONTENTTEXT_MESSAGE_END | TEXT_MESSAGE_CHUNKREASONING_MESSAGE_STARTREASONING_MESSAGE_CONTENTREASONING_MESSAGE_ENDREASONING_MESSAGE_CHUNK | |
| 工具调用 | TOOL_CALL_STARTTOOL_CALL_ARGSTOOL_CALL_ENDTOOL_CALL_RESULT | TOOL_CALL_CHUNK | |
| 状态管理 | STATE_SNAPSHOTSTATE_DELTAMESSAGES_SNAPSHOT | ||
| 活动/自定义 | ACTIVITY_SNAPSHOTACTIVITY_DELTACUSTOMRUN_STARTEDparentRunId 变体等 |
35个事件体系
16 个核心事件里有几个关键设计：
一个反向事件。TOOL_CALL_RESULT 的方向是 UI → Agent。Agent 调了工具，工具在前端执行（比如调用一个 React 组件暴露的按钮点击），结果回传给 Agent。35 个事件里只有它是反向的。
三种 RUN_FINISHED 结果。success（正常结束）、interrupt（暂停等人操作）、omitted（被跳过）。interrupt 是整个 Human-in-the-Loop 机制的基础——Agent 说"我需要用户确认"，前端弹出确认框，用户操作完前端用 resume 数组重启 Agent。这和之前在 Superpowers 文章里分析过的"硬门控"是同一个模式——Agent 不是完全自主的，关键节点必须等人。
二、五个设计决策
五个设计决策
决策 1：Start-Content-End 流式三部曲
要解决的问题：前端不知道该什么时候开始渲染、什么时候结束。
LLM 生成文本是逐 token 输出的——"你好"可能先出"你"，200ms 后出"好"。前端如果不知道"这条消息从哪儿开始、到哪儿结束"，就只能等全部 token 到齐再渲染，用户看着白屏干等。
AG-UI 的解法：给每段流式内容一个 START 事件（携带 messageId 和元信息）和一个 END 事件（标记完成）。前端在 START 到达时立即创建占位 UI（消息气泡），CONTENT 到达时往里填文字，END 到达时标记完成。
这不是 AG-UI 的发明——GPT 的 streaming API 也是这种模式。但 AG-UI 把它从"OpenAI 的私有实现"提升为跨模型、跨 UI 框架的通用协议。任何 Agent（Claude、GPT、Gemini）只要输出这个事件序列，任何 UI（React、Vue、原生 APP）只要理解这个事件序列，就能实现流式渲染。
决策 2：Snapshot-Delta 双轨状态同步
要解决的问题：每次状态变化都发全量数据太浪费。
比如理赔进度有 12 个状态字段，这次只更新了 currentStep 从 2 变成 3。发全量就是 11 个字段的无效传输。
AG-UI 的解法：分两条轨道。
- 首次连接或断线重连
：发 STATE_SNAPSHOT，全量快照，一次性把整个状态给前端。 - 后续运行时
：发 STATE_DELTA，只包含变化的部分。Delta 用 RFC 6902 JSON Patch 格式表达——比如{"op": "replace", "path": "/currentStep", "value": 3}。前端收到后把 Patch 合并到当前状态，只重新渲染变化的部分。
这和 React Virtual DOM Diff 同一思想——通信的是差异，不是全量。React 比较新旧虚拟 DOM 算最小操作集，AG-UI 比较新旧状态 JSON 算最小 Patch。对于保险 APP，Agent 更新理赔进度时，不需要重新生成整个页面——只更新进度条和状态文字。
补充一个技术细节：
STATE_DELTA的 Schema 定义为z.array(z.any())，弱类型。这意味着协议层面不校验 Delta 的格式——任何 JSON Patch 操作都能通过类型检查，真正的校验靠运行时的fast-json-patch。这个权衡有其合理性：如果 Schema 写死特定 Patch 格式，第三方框架接入时就要改造自己的状态结构来匹配——和下面要讲的 Loose Event Matching 冲突了。
决策 3：Loose Event Matching——"兼容"比"精确"重要
这是 AG-UI 最重要的一个设计决策。
协议规定：Agent 发出的事件不需要精确匹配 AG-UI 的标准格式，只需要"兼容"。
什么叫"兼容"？以 LangGraph 为例。LangGraph 内部有自己的事件系统——on_chat_model_start、on_tool_start、on_chain_end 等等。如果 AG-UI 要求精确匹配它的 35 个事件名，LangGraph 就得把所有内部事件重命名一遍——这不现实。
AG-UI 的做法：定义一套事件语义标准——"文本消息""工具调用""状态变更"的语义边界——但不要求事件名完全一致。LangGraph 只需要写一个薄适配层，把 on_chat_model_stream 映射为 TEXT_MESSAGE_CONTENT，把 on_tool_end 映射为 TOOL_CALL_RESULT。
具体实现分两层：
第一层：语义映射。 适配层维护一个"框架事件 → AG-UI 事件"的映射表。AG-UI 协议本身不感知适配层的存在。
第二层：格式兼容。 事件携带的字段也不需要完全匹配。AG-UI 定义了一套 Zod Schema，但 EventVerifier（下文会讲）只验证关键字段——type、messageId、toolCallId——其他字段有就解析，没有就跳过。这让不同框架的适配层可以逐步支持——今天先映射核心事件，明天再补边缘字段。
代价和收益。 Loose 策略降低了协议的一致性——两个"兼容 AG-UI"的 Agent 实现可能产生细微的行为差异。但收益是 AG-UI 在半年内被 Google、LangChain、AWS、Microsoft 等 12+ 框架集成——靠的就是"不强求你重写"的姿态。在 Agent 基础设施远未定型的今天，生态速度优先于学术纯净度。这个话题我之前在 CS146S 的笔记里写过——"协议之争的本质不是技术优劣，是生态采纳速度"。
决策 4：Transport Agnostic——Agent 不变，传输层随便换
要解决的问题：不同环境需要不同的传输方式。 开发调试用 SSE——curl 能直接看到事件流。生产环境追求性能——HTTP binary 体积小、解析快。
AG-UI 的做法：协议只定义事件序列的语义，不绑定传输层。Agent 只管 emit 事件流，用什么协议把这些事件传到 UI 是传输层的事。
CopilotKit 的 ProxiedCopilotRuntimeAgent 实现了三种传输模式：
const runUrl = transport === "single" ? normalizedRuntimeUrl // single: 所有 Agent 走同一个端点 : `${normalizedRuntimeUrl}/agent/${routedId}/run`; // REST: 每个 Agent 独立 URLREST 模式给每个 Agent 分配独立路径（/agent/policy-advisor/run），single 模式所有 Agent 共享一个端点（POST JSON-RPC 包），还有 auto 模式——先 GET /info 探测，成功走 REST，失败降级到 single。
关键是：无论哪种传输模式，Agent 核心逻辑一行代码都不用改。开发时用 SSE 调试，上线前切 HTTP binary——改的是传输层配置，不是 Agent 逻辑。
决策 5：Chunk 简化事件——方便 Agent 开发者
注：Chunk 是英文计算机术语，指"数据块"。这里指一种 syntactic sugar——不增加新能力、只让调用更简洁的封装。
要解决的问题：大部分 Agent 只输出内容片段，不想手动管理 START/END 生命周期。
LLM 输出流里只有 token 序列——"你" → "好" → "请" → "问"。Agent 开发者只想 emit 内容，不想每次 emit 都先发 START 再发 END。
AG-UI 的解法：增加 TEXT_MESSAGE_CHUNK 和 TOOL_CALL_CHUNK 两个简化事件。Agent emit 一个 Chunk 事件，协议层的 ChunkTransformer（~150 行）自动把它展开为完整的 START → CONTENT → END 三部曲。
工作原理：ChunkTransformer 维护每种 chunk 类型的"当前活跃 ID"。新 chunk 的 ID 变了 → 自动发出上一 ID 的 END → 发出新 ID 的 START 和 CONTENT。Agent 只管 emit chunk，协议层补全生命周期。
三、三个源码模块
3.1 ProxiedCopilotRuntimeAgent（654 行）：传输层心脏
ProxiedCopilotRuntimeAgent 继承 AG-UI 的 HttpAgent，是 CopilotKit 和外界通信的唯一入口。三种传输模式已在上文展开，这里讲它另一个重要设计：Intelligence 模式的 Bridge 代理。
当运行时为 Intelligence（WebSocket 长连接模式），ProxiedCopilotRuntimeAgent 本身不直接处理 WebSocket——它创建一个 delegate（真正的 WebSocket agent），自己退化为 proxy：
const bridgeSub = delegate.subscribe({ ... }); // 桥接订阅：同步 delegate state 到 proxy const forwardedSubs = this.subscribers.map(s => delegate.subscribe(s)); // 转发 UI 订阅Bridge 必须先于 UI 订阅创建。UI 组件可能在订阅后立即读取 agent state——如果 bridge 还没到位，UI 读到的是旧 state。先 bridge 后 UI，保证第一次读取就是最新 state。
3.2 EventVerifier（~200 行）：事件防火墙
verify.ts 是事件流进入 React 之前的最后一道检查。Agent 的输出不可控——可能在消息没写完时就发 RUN_FINISHED，可能对同一个 messageId 发两次 START。这些错误流入 React 组件树会导致难以排查的渲染 bug。
EventVerifier 是一个有限状态机，维护三组追踪（messageId、toolCallId、step 映射表）和两个全局标志（runStarted、runFinished）。六条规则：
第一条事件必须是 RUN_STARTED或RUN_ERRORRUN_ERROR之后拒收一切 RUN_FINISHED之后只接受 RUN_ERROR和新的RUN_STARTEDRUN_FINISHED时不能残留未完成的子流 禁止重复 ID 的 START END 只能关已 START 的 ID
设计哲学：Agent 不可控，协议入口必须可控。
3.3 useAgent Hook（245 行）：Provisional Agent
Agent 连接是异步的。React 组件挂载时 Agent 可能还没连上。常规做法是 if (!agent) return <Loading />。
useAgent 不走这条路——没连上就返回一个"临时 agent"（provisional agent）。临时 agent 有完整 API（runAgent()、subscribe()、setState()），只是底层连接未建立。UI 不感知差异，正常渲染和调用。Agent 连上后，引用通过 useMemo 自动切换。连接状态对 UI 透明。
流式 Agent 高频触发状态变更通知。同一 microtask 内多个通知到达时，useAgent 用 queueMicrotask 做轻量批处理——只触发一次 React re-render，不引入额外依赖。
四、Generative UI 的三种安全分级
不是三种并列模式。是一条光谱——安全预算递减，自由度递增。
Static：最安全。开发者通过 useCopilotAction 注册组件，Agent 只能调用已注册的。Agent 传组件名和参数，React 渲染对应组件。Agent 不能创建新组件，不能修改组件行为。
Declarative (A2UI)：Agent 发 JSON 组件清单（"显示确认按钮、条款链接、风险提示卡片"），前端通过 Zod Schema 校验后渲染。Google A2UI 的"Agent 不发代码只发组件清单"就是指这个模式。Agent 可以创造界面，但界面元素必须在预审批的组件目录里。
Open-Ended：Agent 生成完整 HTML/CSS/JS，在前端 iframe 里渲染。双重沙箱——CSS 阶段的 preview sandbox 和完整 HTML 的 final sandbox 互不干扰，旧 sandbox 销毁后才创建新的。
三种模式的选择，本质上是"信任 Agent 到什么程度"。保险 APP 的合规确认页应该停在 Static——确认按钮的样式、免责声明的字体、取消按钮的存在，由组件保证，Agent 不能绕过。理赔进度页可以用 Declarative——Agent 动态生成进度组件，但组件目录是预审批的。Open-Ended 不该出现在任何需要监管合规的场景里。
AG-UI 的 35 个事件背后是一个判断：Agent 的输出不完美，协议要做的是在不完美的输出上构建可靠 UI。 Start-Content-End 解决"不知道什么时候开始和结束"，Snapshot-Delta 解决"全量重传浪费带宽"，Loose Event Matching 解决"强求精确格式会杀死生态"，Transport Agnostic 解决"不同环境需要不同传输协议"。
三种 Generative UI 模式把这个判断又往前推了一步——不完美的 Agent，在不同场景需要不同信任级别。Static 给最小权限，Declarative 给中等权限，Open-Ended 给最大权限但用沙箱隔离。Agent 可以推理任何事，但呈现给用户的，只能是预审批的组件目录里的东西。
五、局限与风险
React 中心化。 虽然协议层面支持多框架，但 CopilotKit 的实现以 React 为一等公民。Vue、Angular 的实现和文档明显滞后。如果你的自营平台是小程序原生开发，CopilotKit 目前不能直接用。
协议栈碎片化。 AG-UI、A2UI（Google）、MCP-UI（Microsoft+Shopify）、Open-JSON-UI（OpenAI）——四个 Generative UI 规范在各自推进。AG-UI 目前生态最强（12+ 框架集成），但协议层的碎片化是未来风险。选边站队太早，观望太久又可能落后。
商业云平台依赖风险。 CopilotKit 的核心框架是 MIT 开源、可自托管的。但 Self-Learning（让 Agent 从用户反馈中持续学习的 CLHF 机制）和 Enterprise Intelligence Platform（团队管理、用量分析、安全审计）仅在其商业云平台上提供，开源版无法使用。如果未来核心能力持续向商业云倾斜，自托管版本可能退化——这是所有开源商业公司的经典路径。
复杂度与场景匹配。 AG-UI 的 35 个事件 + Snapshot-Delta + Interrupt + Middleware 是一套完整的体系。但对一个简单的 FAQ 机器人，这套东西严重过度设计。不是所有 Agent 都需要 35 个事件。
课后随想
CopilotKit + AG-UI 解决的是一个被低估的问题：Agent 生态里，MCP 解决了 Agent 怎么用工具，A2A 解决了 Agent 怎么跟 Agent 说话，但"Agent 怎么跟人交互"这个最基础的问题，过去大家都用土办法——字符串拼接、自定义 WebSocket、每个项目自造轮子。
AG-UI 的价值不是技术有多深，是标准化了一个不该被反复发明的东西。就像 HTTP 标准化了浏览器怎么跟服务器说话，AG-UI 标准化了 Agent 怎么跟 App 说话。
源码层面，CopilotKit 的实现质量很高——provisional agent 的容错设计、microtask 批处理、bridge 订阅的顺序保证、EventVerifier 状态机的完整性、ChunkTransformer 的自动展开。这些都是生产级的基础设施。
欢迎讨论～
