一、导读
2026-11-18 的 GitHub Trending 日榜上,ag-ui-protocol/ag-ui 以单日 +1444 星冲进前列——这不是又一个新框架,而是一份刚刚定稿的协议规范。它解决的是智能体工程里最琐碎的一段接线:不管智能体用 LangGraph、CrewAI 还是 Google ADK 写,前端都得靠各自的私有 WebSocket 胶水代码对接,换一次框架、前端重写一遍。AG-UI 用「一个请求进、一条有序类型化事件流出」把这段接线标准化,规范近期冻结为 1.0,昨日(2026-11-17)刚发布 @ag-ui/client 1.0.5 与首个 Cloudflare Agents 集成,涨星峰值正是这三件事叠加的结果。
二、项目速览
| 项目 | 内容 |
|---|---|
| 仓库 | ag-ui-protocol/ag-ui |
| 定位 | Agent-User Interaction Protocol:智能体与用户界面之间的开放事件协议 |
| 语言 / License | TypeScript(TS、Python、.NET 三方官方 SDK 均由 schema 生成)/ MIT |
| 热度(截至 2026-11-18) | ★19,968 · fork 2,066 · 当日 +1444 · 创建于 2025-05 |
| 采用度 | npm @ag-ui/core 周下载 663 万、@ag-ui/client 周下载 234 万;PyPI ag-ui-protocol 周下载 218 万 |
| 核心抽象 | RunAgentInput(入)+ 8 大事件族 31 种类型化事件(出) |
| 协议栈位置 | 与 MCP(智能体连工具)、A2A(智能体互联)并列的第三层协议 |
| 接入框架 | LangChain/LangGraph、CrewAI、Microsoft Agent Framework、Google ADK、Mastra、Pydantic AI、AWS Strands、Bedrock AgentCore、OpenAI Agents SDK、Claude Agent SDK 等 |
| 最新动态 | 1.0 规范冻结(含 JSON Schema 与行为规范);2026-11-17 发布 SDK 1.0.5 与 @ag-ui/cloudflare-agents 0.1.0 |
三、为什么是它:三条涨星动因
第一,时机踩在智能体产品化的痛点上。 2025 年是大模型应用从「聊天框」走向「工作台」的一年:智能体开始流式吐 token、中途调工具、维护共享状态、暂停等人审批、还会派出子智能体。这些行为没有一项能塞进 REST 的请求-响应模型,于是每个框架都自造一套前端事件格式,前端团队被逼着写 N 份胶水代码。AG-UI 在 2025-05 开源(文档记录的初始版本发布于 2025-04-09),18 个月里生态慢慢攒齐,1.0 冻结成了兑现时刻。
第二,生态背书链条完整。 项目由 CopilotKit 团队主导——CopilotKit 本身是 React 生态最流行的智能体前端库,AG-UI 相当于把它内部打磨多年的接线抽成公共协议。2025-11 微软 Agent Framework 官方宣布支持,2025-12 Google 发布 A2UI 时明确与 AG-UI 协同分工,AWS Strands、Bedrock AgentCore、Google ADK(Python 与 JS 双版本)均为一方适配。一方客户端有 CopilotKit、React Native、Slack/Teams 的 Channels SDK 与终端客户端;社区绑定已覆盖 Kotlin、Go、Dart、Java、Rust、Ruby、C++。
第三,生产流量与活跃维护是硬证据。 npm 核心包周下载 663 万说明这不是论文项目;看最近的提交与 Release 也很有说服力:2026-11-17 的 1.0.5 修的是「并行工具调用事件乱序」「增量被中途快照覆盖」这类只有真实生产流量才会暴露的并发问题,并顺手把大线程回放从全表扫描优化成 MessageLookup 索引。HN 上 2026-11-02 的实战帖《用 CopilotKit 和 AG-UI 替换 11,000 行 AI 聊天代码》则是社区侧的典型反馈。
四、架构原理
4.1 总体模型:单请求、单事件流
AG-UI 的协议模型可以压缩成一句话:应用方 POST 一个 RunAgentInput,智能体回一条按序排列的类型化事件流。文本、工具调用、推理过程、共享状态、执行进度、子智能体生命周期,全部走同一条双向流。它不是渲染规范——事件流是渲染无关的,所以 Web、移动端、终端、Slack 都能当消费端。

flowchart LR
subgraph FE["前端(任意客户端)"]
A["Web 应用(CopilotKit / React)"]
B["移动端 / Slack / 终端"]
end
subgraph BE["智能体后端(任意框架)"]
C["AG-UI 适配层 + EventEncoder"]
D["LangGraph / CrewAI / Google ADK / Mastra"]
end
E["MCP:工具与数据源"]
F["A2A:其他智能体"]
A -- "RunAgentInput(全量历史 + state + tools + resume)" --> C
B -- "RunAgentInput" --> C
C -- "31 种类型化事件(SSE / Protobuf)" --> A
C -- "同一条事件流" --> B
D --- C
D -- "调工具" --> E
D -- "委派任务" --> F
规范工程上有一个关键取舍:结构归 JSON Schema 管,行为归规范文本管。字段、必选性、类型判别式以 schema 为准(「结构有分歧时 schema 赢」);排序、生命周期、归因、错误处理、兼容性则用 BCP 14 的 MUST/SHOULD 语义写死在行为规范里。一致性按流判定——一条流里出现一次畸形 run 即整条不合规。三方 SDK 从同一份 schema 生成,0.x 时代三份手写的 AgentCapabilities 声明在 1.0 里收敛成了一份。
4.2 事件模型:8 大族、31 种类型
事件按「哪部分消费端需要它」分成八族,每族绑定一种事件模式(生命周期、流式三段、快照-增量、中断-恢复、独立透传):
| 事件族 | 代表事件类型 | 模式 | 消费方 |
|---|---|---|---|
| 运行与步骤 | RUN_STARTED / RUN_FINISHED / RUN_ERROR / STEP_STARTED / STEP_FINISHED | 生命周期 | 客户端核心 |
| 文本消息 | TEXT_MESSAGE_START / CONTENT / END | 流式三段 | UI |
| 工具调用 | TOOL_CALL_START / ARGS / END / RESULT | 流式三段 + 结果 | 应用 |
| 推理 | REASONING_MESSAGE_*、REASONING_ENCRYPTED_VALUE | 流式 | UI |
| 共享状态 | STATE_SNAPSHOT / STATE_DELTA / MESSAGES_SNAPSHOT | 快照-增量 | 应用状态库 |
| 执行活动 | ACTIVITY_SNAPSHOT / ACTIVITY_DELTA | 快照-增量 | UI |
| 子智能体 | SUBAGENT_STARTED / FINISHED / ERROR | 生命周期 | 客户端核心 |
| 透传 | RAW / CUSTOM | 独立 | 应用(需显式订阅) |
设计上有两条纪律值得注意。其一,只有运行生命周期是强制项:智能体没有工具调用就一个 TOOL_CALL_* 也不发,但消费端必须能接受全部 31 种——「无内容的族不是未知物」。其二,流式三段(START/CONTENT/END)让 token 级流式与结构化渲染共存:CONTENT 增量拼接出完整消息,START/END 携带 messageId 让并行消息互不串行。1.0 的一个破坏性变更是用 REASONING_* 取代 THINKING_*,并新增 REASONING_ENCRYPTED_VALUE——厂商的加密推理块(如 o 系列模型的 encrypted reasoning)可以原样透传而不暴露内容;退休的结构在兼容层被翻译而不是丢弃。
工具调用一族是整条流里语义最重的部分:TOOL_CALL_START 带调用 id 与工具名,TOOL_CALL_ARGS 按字符流式吐参数——前端可以实时渲染 JSON 参数的生成过程;TOOL_CALL_END 关闭参数;TOOL_CALL_RESULT 以一条独立消息回执,不重开调用,content 接受字符串或有序内容部件。前端工具与后端工具在这里分道:前端工具由应用执行,声明走 RunAgentInput.tools,执行权在用户手里;后端工具由智能体自己调用,前端只看到进度。1.0 还把安全纪律写进了规范正文:对有副作用的工具调用,应用应当取得用户显式同意,且「不得把未获批的动作呈现为用户已批准」——协议层给审批 UI 留了法定的位置。
4.3 RunAgentInput:一次输入携带全部上下文
入向只有一条消息。RunAgentInput 的字段设计体现了「无状态智能体」的假设:threadId 命名会话、runId 命名本次运行、parentRunId 声明子智能体派生关系;messages 是全量对话历史(没有增量会话协议),支持文本、图像、音频、视频、文档的多模态 ContentPart,可内联、走 URL 或用厂商文件句柄;tools 是前端愿意提供给智能体执行的「前端工具」清单(执行方是应用自己);context 是注入模型的地上下文;state 携带上一次商定的共享状态——在智能体发出第一个快照之前,所有增量都以它为基准计算;forwardedProps 是应用自定义的透传字段,中间件不得改动;resume 携带对上一次中断的回答;protocolVersion 缺失即「前版本时代的对端」,老结构照样能被解析。
宽容度规则也很明确:智能体消化不了的内容必须跳过而不是失败(没有视觉能力的模型收到图片,跳过、继续跑);无法识别的字段剥离后照常运行(向前兼容);只有已知结构的畸形值(比如流式中段 messageId 对不上)才是致命错误。
4.4 传输:SSE 为主,Protobuf 二进制为辅
HTTP + SSE 绑定的规则朴素而严格:POST 正文就是一个 UTF-8 的 RunAgentInput JSON;响应 200 后以 text/event-stream 逐条下发,每条 data: 载荷恰好一个完整的 JSON 事件,强制 LF 行尾,Keep-alive 注释可任意节奏插入。错误路径分成两段——流打开之前的失败(JSON 不合法、校验不过、鉴权拒绝)走普通 HTTP 状态码;流一旦打开,状态码已提交,后续失败只能以 RUN_ERROR 事件进流,所以「200 不代表成功」。值得记下的是它明确不支持断线续传:不用 Last-Event-ID,连接断了就是截断的 run,重连意味着新 runId 的新 run,状态靠消费端留存。
对延迟敏感的路径可以走 1.0 新增的 HTTP + Protobuf 二进制绑定:按媒体类型协商,4 字节长度前缀分帧,SDK 代码从 schema 生成,跨实现的一致性由一套共享字节语料钉死。这在移动端(省电量、省流量)与高吞吐场景是实打实的优化。
处理模型上,中间件先于强制校验运行,给代理、录制器与调试工具留了挂载点;无法识别的事件在强制层被丢弃并告警,「未识别的内容存活、已知结构的畸形致命」是整份规范的处理哲学;RAW 与 CUSTOM 两个逃生舱事件要求消费端显式订阅后才投递。这组规则让 0.x 与 1.0 之间双向兼容,也给未来扩展留了余地。
4.5 状态同步与中断恢复:1.0 收紧的两块
共享状态走「快照定基线、增量跟随」:STATE_SNAPSHOT 全量替换,STATE_DELTA 是一串 JSON Patch(RFC 6902)操作,按序原子应用,前端发现不一致就请求新快照。关键是双向:智能体可以把提案写进 state(比如一封待发邮件),用户改完再继续——智能体变成了前端可订阅的状态库。
需要人点头的场景,1.0 把「中断-恢复」定成一等模式:run 以 RUN_FINISHED 的 interrupt 结果收场,携带至少一个 Interrupt 对象(id、reason、可读提示 message、关联的 toolCallId、描述答案结构的 responseSchema,可带 expiresAt);恢复靠一次新 run,RunAgentInput.resume 里每个中断一条 ResumeEntry,且必须覆盖每一个中断——已答的带 payload,不答的也要显式标记 abandoned,「漏答不算放弃」,消费端必须在发送前拒绝覆盖不全的恢复输入。协议没有 run 中途的双向通道,连续性的账(threadId、消息、状态的延续)全部记在消费端头上;副作用操作「不得把未获批的动作伪装成用户已批准」则写进了安全原则。
五、应用场景

场景 1:多框架统一接入层——前端只认协议,不认框架
痛点:一个平台里,编排用 LangGraph、数据组用 CrewAI、特定场景用 Google ADK,每个框架回给前端的事件格式都不一样,前端要维护三套 WebSocket 胶水与渲染逻辑。解决:每个框架包一层 AG-UI 适配器,对外都是同一条事件流,前端把「会话、状态、工具回调」实现一次。最小示例——一个 30 行级的 Python 智能体端点(依官方 README 精简示意):
# pip install ag-ui-protocol fastapi uvicorn
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (RunStartedEvent, TextMessageStartEvent,
TextMessageContentEvent, TextMessageEndEvent,
RunFinishedEvent)
from ag_ui.encoder import EventEncoder
app = FastAPI()
@app.post("/")
async def run_agent(input_data, request: Request):
enc = EventEncoder(accept=request.headers.get("accept"))
async def events():
yield enc.encode(RunStartedEvent(thread_id=input_data.thread_id,
run_id=input_data.run_id))
yield enc.encode(TextMessageStartEvent(thread_id=input_data.thread_id,
run_id=input_data.run_id))
# 在这里逐 token 产出 TEXT_MESSAGE_CONTENT 增量
yield enc.encode(TextMessageEndEvent(thread_id=input_data.thread_id,
run_id=input_data.run_id))
yield enc.encode(RunFinishedEvent(thread_id=input_data.thread_id,
run_id=input_data.run_id))
return StreamingResponse(events(), media_type=enc.get_content_type())
收益:换框架时后端改适配层,前端零改动;接入新框架只写一次适配器。边界:没有现成适配层的小众框架要自己实现 EventEncoder 与事件排序,工作量主要在排序正确性上。
场景 2:共享状态驱动的智能体工作台
痛点:聊天框承载不了表格、看板、多步计划这类结构化输出;前后端状态各自维护,很快漂移。解决:把智能体当「可订阅的 state store」——STATE_SNAPSHOT 定基线,STATE_DELTA(JSON Patch)高频跟随,双向可写。CopilotKit 侧一行接住:
const { state: agentState, setState: setAgentState } = useCoAgent({
name: "research-agent",
initialState: { plan: [], sources: [] },
});
Python 侧用 copilotkit_emit_state 推送,底层走的就是同一对快照/增量事件。收益:HN 实战帖用这条路替换了 11,000 行自研聊天代码,维护面从「私有协议 + 状态机」缩成「订阅一个 state」。边界:高频 patch 要控制 patch 复杂度并自备冲突策略;规范明确建议敏感数据不要放进共享 state。
场景 3:高风险操作的人机审批闭环
痛点:转账、发邮件、改生产配置这类副作用操作,不能放给模型自治执行。解决:工具调用走到审批点,智能体结束本次 run(outcome=interrupt)并挂 Interrupt 对象;responseSchema 直接驱动前端渲染审批表单;用户点「批准」后,应用开新 run 并在 resume 里带答案继续。事件序列是:RUN_STARTED → TOOL_CALL_START(transfer_funds)→ RUN_FINISHED(interrupt,id=int-1)→ 应用渲染审批 UI → 新 run 携带 resume: [{interruptId: "int-1", payload: {"approved": true}}] → RUN_STARTED → … → RUN_FINISHED。收益:审批有结构化痕迹,每一次授权都能对到具体中断 id 与工具调用,审计友好;过期中断也必须显式 abandoned,不会出现「悬而未决却显示成功」。边界:协议没有 run 中途的输入通道,审批延迟就是一次完整的 run 边界;还要区分「前端工具停止」——应用可以让 run 以 success 收场并点名 pendingToolCallIds 等本地工具结果,那是等执行、不是等人审批,两种收场不可混用;追求毫秒级交互确认的场景要自己叠加 UI 层缓存。
场景 4:一次实现,多端分发
痛点:同一个助手要出现在 Web、App、Slack、终端,各端自己维护会话与流式同步,三端三种行为。解决:事件流渲染无关——官方 Channels SDK 直接把同一条流灌进 Slack/Teams,终端客户端与 React Native 客户端消费同一协议,移动端还可切 Protobuf 绑定省流量。收益:多端一致性不再靠人工对齐;新端接入是「再写一个消费者」而不是「再写一个协议」。边界:富 UI 能力(按钮、卡片、生成式组件)在纯文本端自然退化,需要在内容设计上做端别分层。
六、快速上手
最快的路径是脚手架:
npx create-ag-ui-app@latest
# 生成的模板默认调 OpenAI,先配好 key
export OPENAI_API_KEY="sk-..."
npm run dev
CLI 会生成一个 Next.js(CopilotKit)或终端客户端的前端骨架,并让你从支持的框架列表里挑智能体后端。后端已有 LangGraph/CrewAI/ADK 项目的,直接装对应适配包;自研后端按上文 30 行示例手写事件流即可。调试用官方 debugging 教程抓事件流逐条核对,配合 Cursor 教程可以边开发边看协议实况。1.0 接入记得显式声明 protocolVersion,别依赖「缺失即老对端」的兜底。
七、横向对比:智能体协议栈里的位置
| 维度 | AG-UI | MCP | A2A | 自研 WebSocket |
|---|---|---|---|---|
| 解决的问题 | 智能体 ↔ 用户界面 | 智能体 ↔ 工具/数据 | 智能体 ↔ 智能体 | 各家自定义 |
| 发起方与时间 | CopilotKit 团队,2025-04/05 | Anthropic,2024-11 | Google,2025-04 | — |
| 交互模型 | 单请求 + 有序类型化事件流 | JSON-RPC 工具调用与资源 | 任务与工件(artifact)模型 | 自定义 |
| 状态同步 | 快照 + JSON Patch,双向 | 资源读取为主 | 无内建 | 自定义 |
| 人机闭环 | interrupt-resume 一等模式 | elicitation(引导输入) | 未内建 | 自定义 |
| 多端分发 | Web/移动/Slack/终端同流 | 服务端内部 | 服务端内部 | 每端重写 |
三者是互补而非互斥:一条链路上,MCP 管工具与数据、A2A 管跨智能体协作、AG-UI 管面向人的呈现层。与 AG-UI 相邻还有 Google 的 A2UI(声明式生成式 UI 的交付规范)与 MCP Apps——它们管「UI 怎么描述、怎么送达」,AG-UI 管「交互事件怎么流转」,官方文档明确两者可以组合使用。
八、局限与风险
传输层无断线续传。 规范明确不用 Last-Event-ID,弱网移动场景断线即截断 run,重放语义完全压在消费端:要自己留存状态、自己决定是否重开 run。全量历史往返的成本。 每次 run 重发完整 messages,长对话的带宽与序列化开销线性增长;1.0.5 的 MessageLookup 索引与 compactEvents 压缩是客户端侧缓解,协议本身不提供会话分页。治理集中度。 项目由 CopilotKit 团队主导,协议演进与其商业产品同源,规范文本虽然措辞厂商中性,但路线图话语权集中是客观事实,重度依赖前值得持续观察治理结构变化。生态成熟度不均。 一方 SDK 只有 TS/Python/.NET 三份且由 schema 生成,质量有保障;社区绑定(Rust/Java/Kotlin 等)版本滞后,部分框架适配层只覆盖 31 种事件的子集,选型时要核对目标框架适配层的覆盖面。它不管渲染。 AG-UI 刻意不定义 UI 交付,生成式界面要另配 A2UI 或 MCP Apps,多规范组合的心智负担依然存在。
九、小结与行动建议
- 新项目直接按 1.0 起步:显式声明 protocolVersion,事件按 schema 生成代码,不要手写结构体。
- 0.x 存量项目对照迁移指南过一遍:重点核对 THINKING_* → REASONING_* 的翻译、subAgents → subagents 键名、以及流式中段判别式冲突从警告变致命的影响。
- 副作用操作一律走 interrupt-resume:不要用前端工具停止或取消结果来伪装审批,那在 1.0 里是不合规行为。
- 共享状态设计成「窄而深」:减少 patch 冲突面,快照只在基线与失同步时发,其余走增量。
- 移动端评估 Protobuf 绑定:4 字节分帧 + schema 生成代码,弱网与高吞吐场景收益明确。
参考资料
- GitHub 仓库:https://github.com/ag-ui-protocol/ag-ui (获取日期 2026-11-18)
- AG-UI 1.0 规范总览:https://docs.ag-ui.com/spec/1.0 (获取日期 2026-11-18)
- 1.0 相对 0.x 变更记录:https://docs.ag-ui.com/spec/1.0/changelog (获取日期 2026-11-18)
- RunAgentInput 规范:https://docs.ag-ui.com/spec/1.0/basic/run-input (获取日期 2026-11-18)
- HTTP + SSE 传输规范:https://docs.ag-ui.com/spec/1.0/basic/transports/http-sse (获取日期 2026-11-18)
- 中断-恢复模式规范:https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume (获取日期 2026-11-18)
- 事件族索引与共享状态概念:https://docs.ag-ui.com/spec/1.0/events/index 、https://docs.ag-ui.com/concepts/state (获取日期 2026-11-18)
- Release 2026-11-17(@ag-ui/client 1.0.5):https://github.com/ag-ui-protocol/ag-ui/releases/tag/release/2026-11-17 (获取日期 2026-11-18)
- HN:We replaced 11,000 lines of AI chat code with CopilotKit and AG-UI(2026-11-02):https://news.ycombinator.com/item?id=50340387 (获取日期 2026-11-18)
读者留言
COMMENTS 暂无还没有留言,来说第一句?