引言
「Bring Agents into Frontend Applications.」
这是「一天一个开源项目」系列的第 262 篇。今天的项目是 ag-ui-protocol 的 AG-UI。
做过聊天界面的人都踩过这个坑:Agent 不是一次请求、一次响应那么简单。它会一个字一个字地流式输出,说到一半去调用工具,中途更新某份共享状态,停下来等用户确认,还可能派出子 Agent。每个 Agent 框架处理这些的方式都不一样,前端就得为每个框架写一套定制代码。
AG-UI 想做的事,是把这一层标准化:Agent 往外发一条类型化的事件流,任何前端都能按同一套约定来渲染。同一个 Agent 因此可以接到网页、手机应用、终端,甚至 Slack 里,而不必重新对接。
本文基于 README 和仓库目录整理,我没有安装并实际跑过其中的命令。
你将学到什么
- AG-UI 解决什么问题,和 MCP、A2A 是什么关系
- 「事件流」是怎么设计的:一次运行里会出现哪几类事件
- 流式聊天、共享状态、前端工具、人工介入等能力如何落到事件上
- 怎么用 TypeScript 和 Python 起一个最小的服务端和客户端
- 项目的边界,以及它背后的商业背景
前置知识
- 了解 AI Agent 的基本概念,用过工具调用(Function Calling)
- 对 SSE(Server-Sent Events)和前端流式渲染有基本认识
- 可选:了解 MCP 与 A2A
项目背景
项目简介
README 的定义是:一个开放、轻量、基于事件的协议,把 AI Agent 与面向用户的应用对接起来。它采用 MIT 协议,由 CopilotKit 创建,并与社区一起公开开发。
当前版本是 AG-UI 1.0。README 称它是「稳定、冻结的规范」,有 JSON Schema 支撑,并且双向向后兼容:0.x 的 Agent 能配 1.0 的客户端,反过来也行。
项目数据
- ⭐ GitHub Stars:约 19,107
- 🍴 Forks:约 1,969
- 💻 语言:TypeScript(Monorepo)
- 📅 创建时间:2025-05-07,最近一次推送为 2026-11-16,最新发布标签
release/2026-11-13 - 📄 许可证:MIT
- 👤 发起方:CopilotKit,社区共同开发
- 🌐 官网:ag-ui.com;文档:docs.ag-ui.com
主要功能
和 MCP、A2A 的关系
README 把 AG-UI 放进一个三件套里:
| 协议 | 解决什么 |
|---|---|
| MCP | 给 Agent 提供工具和上下文 |
| A2A | 让 Agent 与其他 Agent 协作 |
| AG-UI | 把 Agent 交付给用户 |
三者互补,一个 Agent 常常三个都会用,AG-UI 也可以放在说 MCP 或 A2A 的 Agent 前面。
它和 A2UI 的关系需要单独说清楚:A2UI、MCP Apps、Open-JSON-UI 是生成式 UI 的规格,描述「Agent 想展示什么界面」;AG-UI 是运行时协议,负责在 Agent 和应用之间传输这些内容,以及其他所有东西。前者是「说什么」,后者是「怎么传」。
解决的问题
没有统一协议时:
每个 Agent 框架的流式、工具调用、状态同步各有一套
↑ 前端要为每个框架写定制对接,换框架就要重写
用 AG-UI:
Agent 发出类型化事件流 → 任何兼容的客户端都能渲染
↓ 同一个 Agent 可以接网页、移动端、终端、Slack
↑ 前端与 Agent 框架解耦
能力一览
README 把能力拆成几个「构件」,每个都对应一组事件,并在 Dojo 演示站里有示例:
| 能力 | 说明 |
|---|---|
| 流式聊天 | 多轮 Token 流式输出,支持取消和恢复 |
| 生成式 UI | 类型化组件,或通过 A2UI、MCP Apps 做声明式界面 |
| 共享状态 | 前后端共读共写的类型化存储,通过快照和 JSON Patch 同步 |
| 前端工具 | 在应用端执行的工具,结果回传给 Agent |
| 人工介入 | 一次运行以 interrupt 结束,用户批准、修改或拒绝,下一次运行从这里恢复 |
| 推理展示 | 实时显示推理过程,包括加密内容的往返 |
| 子 Agent | 嵌套委派,事件带上子 Agent 运行的归属 |
| 多模态 | 输入和工具结果里可以有图片、音频、视频和文档 |
快速开始
方式一:脚手架,一条命令生成一个应用(CopilotKit 加 Next.js,或终端客户端):
npx create-ag-ui-app@latest
export OPENAI_API_KEY="sk-..."
方式二:最小 Python 服务端
pip install ag-ui-protocol fastapi uvicorn
uvicorn server:app --port 8000
README 说它是一个 FastAPI 端点:接收 RunAgentInput,用 EventEncoder 和 StreamingResponse 把事件流式发出去。
方式三:最小 TypeScript 客户端(需要 Node.js 20+)
npm init -y && npm pkg set type=module
npm install @ag-ui/client tsx
npx tsx client.ts
客户端用 HttpAgent,并通过 onRunStartedEvent、onTextMessageContentEvent 这样的回调接收事件。
SDK
| 语言 | 安装命令 |
|---|---|
| TypeScript | npm install @ag-ui/client(另有 @ag-ui/core) |
| Python | pip install ag-ui-protocol |
| .NET | dotnet add package AGUI.Client |
这三个 SDK 都是由规范生成的。社区 SDK 覆盖 Kotlin、Go、Java、Dart、Rust、Ruby、C++、Swift,它们的成熟度我没有逐个核实。
项目详细剖析
事件流:一次运行是怎么走完的
核心模型很简单:
- 应用发送一个
RunAgentInput,里面带着对话历史、前端工具、共享状态和上下文 - Agent 回应一条类型化事件流
- 只有「运行生命周期」事件是必需的,所以一个最小的 Agent 只要发出几个事件就能跑起来,再逐步扩展
README 称 AG-UI 1.0 定义了 31 种事件,分八个族:
| 族 | 事件 |
|---|---|
| 运行与步骤 | RUN_STARTED RUN_FINISHED RUN_ERROR STEP_STARTED STEP_FINISHED |
| 文本消息 | TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END TEXT_MESSAGE_CHUNK |
| 工具调用 | TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END TOOL_CALL_RESULT TOOL_CALL_CHUNK |
| 状态 | STATE_SNAPSHOT STATE_DELTA(JSON Patch) MESSAGES_SNAPSHOT |
| 推理 | REASONING_START REASONING_MESSAGE_* REASONING_ENCRYPTED_VALUE REASONING_END |
| 活动 | ACTIVITY_SNAPSHOT ACTIVITY_DELTA |
| 子 Agent | SUBAGENT_STARTED SUBAGENT_FINISHED SUBAGENT_ERROR |
| 透传 | RAW CUSTOM |
这里有一处我自己核对的细节:表里除了 REASONING_MESSAGE_* 这个通配写法之外,一共是 27 个事件名。README 说总数是 31,意味着通配符展开后应有 4 个,但 README 没有逐个列出,所以我没有写出它们的名字,需要时请查官方规范页。
用一个例子体会这条流:让 Agent 回答一个问题,并中途调用一次工具,事件的顺序大致是这样的(示意,不是真实抓包):
RUN_STARTED
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT "我先查一下……"
TEXT_MESSAGE_END
TOOL_CALL_START
TOOL_CALL_ARGS
TOOL_CALL_END
TOOL_CALL_RESULT
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT "结果是……"
TEXT_MESSAGE_END
RUN_FINISHED
前端不需要知道背后是 LangGraph 还是 CrewAI,只要认得这些事件,就能把文字逐字显示、把工具调用画成一张卡片、把状态变化同步到界面。
状态同步用 JSON Patch
共享状态通过两种事件同步:STATE_SNAPSHOT 给出完整状态,STATE_DELTA 只发变化部分,格式是 JSON Patch。这样大状态不用每次整体重传,是一个很实用的设计。
人工介入:用 interrupt 结束一次运行
人工介入的做法比较有意思:它不是让 Agent 挂在那里等,而是让这一次运行以 interrupt 结局结束,用户批准、修改或拒绝之后,再发起下一次运行从这里接着走。这样服务端不必长时间持有一条挂起的连接。
传输层
AG-UI 不绑定传输方式。规范里定义了两种绑定:HTTP 加 SSE,以及 HTTP 加 Protobuf(二进制)。README 也提到可以用中间件把任意来源的事件适配进来,并提到 WebSocket 等其他传输,但只有 SSE 和 Protobuf 被列为规范绑定。
生态与接入
README 称 AG-UI 被 Google、Microsoft、Amazon、Oracle 等采用,并内置在大多数 Agent 框架里:
- 合作方:LangChain、CrewAI
- 内置支持:Microsoft Agent Framework、Google ADK、AWS Strands Agents、Mastra、Pydantic AI、Agno、LlamaIndex、AG2 等
- 更多框架:Claude Agent SDK、IBM watsonx Orchestrate、Langroid、Spring AI、Cloudflare Agents、OpenAI Agents 等
- 客户端:CopilotKit(React、Angular、Vue、React Native)、Slack 和 Teams、终端等
仓库的 integrations/ 目录里能看到对应的子目录,比如 langgraph、crew-ai、mastra、microsoft-agent-framework、openai-agents、claude-agent-sdk、vercel-ai-sdk。注意「被采用」是 README 的说法,具体每个集成的完成度我没有核实,用到时要看对应目录里的文档。
仓库结构
sdks/:typescript、python、dotnet、communityintegrations/:各框架的接入实现,另有server-starter和server-starter-all-features两个模板middlewares/:中间件(MCP、A2UI 以及起步模板)apps/dojo:在线演示(dojo.ag-ui.com)spec/和docs/:规范与文档
局限与注意事项
README 对局限着墨不多,我归纳几点:
- 不是每个框架都原生接入:README 提到可以用中间件去适配不支持的来源,这本身说明接入深度不一
- 规范绑定只有 SSE 和 Protobuf:用 WebSocket 等需要自己适配
- 项目由 CopilotKit 发起:许多集成文档会链到 CopilotKit 的文档。协议本身是 MIT 开源的,但如果你想用现成的前端脚手架,会自然落在 CopilotKit 的生态里,这一点选型时心里要有数
- 1.0 已冻结:好处是稳定,代价是新需求要等后续的草案规范;README 提到有公开路线图和草案规范,但没有描述内容
项目地址与资源
- 🌟 GitHub:github.com/ag-ui-proto…
- 🌐 官网:ag-ui.com
- 📚 文档:docs.ag-ui.com(规范 1.0:docs.ag-ui.com/spec/1.0)
- 🎮 在线演示:dojo.ag-ui.com
- 💬 社区:Discord、GitHub Discussions、GitHub Issues
- 📄 许可证:MIT
总结与展望
核心要点回顾
- 定位:MCP 管工具、A2A 管 Agent 之间、AG-UI 管 Agent 到用户,三者互补
- 核心设计:一次运行发出一条类型化事件流,只有生命周期事件是必需的,容易起步、易于扩展
- 覆盖面:流式文本、工具调用、共享状态、推理、人工介入、子 Agent、多模态
- 生态:TypeScript、Python、.NET SDK,加上大量框架的接入
- 留意:接入深度不一,且有 CopilotKit 的商业生态背景
适用人群
- 要给 Agent 做前端界面、不想被某个框架绑定的开发者
- 想让同一个 Agent 同时服务网页、终端和聊天工具的团队
- 想了解 Agent 应用「前端协议」该怎么设计的人,这套事件模型值得参考
学习建议
先去 Dojo 演示站看各个能力的效果,再读规范里的事件定义。动手可以先用 npx create-ag-ui-app@latest 起一个脚手架,或者照 README 起一个最小的 FastAPI 服务端,用 TypeScript 客户端接上,把收到的事件逐条打印出来,亲眼看一遍一次运行里事件的顺序。最后再去 integrations/ 里找你正在用的框架,看它的接入有多完整。
欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场,所有内容均经过真实企业级工作流验证。没有噱头,只有真正有效的东西。
更多实用知识和有趣产品,欢迎访问我的个人主页