一天一个开源项目(第262篇):AG-UI —— 把 AI Agent 接进前端的开放协议,和 MCP、A2A 并列的第三块拼图

引言

「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 和应用之间传输这些内容,以及其他所有东西。前者是「说什么」,后者是「怎么传」。

解决的问题

swift 复制代码
没有统一协议时:
  每个 Agent 框架的流式、工具调用、状态同步各有一套
  ↑ 前端要为每个框架写定制对接,换框架就要重写

用 AG-UI:
  Agent 发出类型化事件流 → 任何兼容的客户端都能渲染
  ↓ 同一个 Agent 可以接网页、移动端、终端、Slack
  ↑ 前端与 Agent 框架解耦

能力一览

README 把能力拆成几个「构件」,每个都对应一组事件,并在 Dojo 演示站里有示例:

能力 说明
流式聊天 多轮 Token 流式输出,支持取消和恢复
生成式 UI 类型化组件,或通过 A2UI、MCP Apps 做声明式界面
共享状态 前后端共读共写的类型化存储,通过快照和 JSON Patch 同步
前端工具 在应用端执行的工具,结果回传给 Agent
人工介入 一次运行以 interrupt 结束,用户批准、修改或拒绝,下一次运行从这里恢复
推理展示 实时显示推理过程,包括加密内容的往返
子 Agent 嵌套委派,事件带上子 Agent 运行的归属
多模态 输入和工具结果里可以有图片、音频、视频和文档

快速开始

方式一:脚手架,一条命令生成一个应用(CopilotKit 加 Next.js,或终端客户端):

bash 复制代码
npx create-ag-ui-app@latest
export OPENAI_API_KEY="sk-..."

方式二:最小 Python 服务端

bash 复制代码
pip install ag-ui-protocol fastapi uvicorn
uvicorn server:app --port 8000

README 说它是一个 FastAPI 端点:接收 RunAgentInput,用 EventEncoder 和 StreamingResponse 把事件流式发出去。

方式三:最小 TypeScript 客户端(需要 Node.js 20+)

bash 复制代码
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,它们的成熟度我没有逐个核实。


项目详细剖析

事件流:一次运行是怎么走完的

核心模型很简单:

  1. 应用发送一个 RunAgentInput,里面带着对话历史、前端工具、共享状态和上下文
  2. Agent 回应一条类型化事件流
  3. 只有「运行生命周期」事件是必需的,所以一个最小的 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 回答一个问题,并中途调用一次工具,事件的顺序大致是这样的(示意,不是真实抓包):

text 复制代码
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、community
  • integrations/:各框架的接入实现,另有 server-starter 和 server-starter-all-features 两个模板
  • middlewares/:中间件(MCP、A2UI 以及起步模板)
  • apps/dojo:在线演示(dojo.ag-ui.com)
  • spec/ 和 docs/:规范与文档

局限与注意事项

README 对局限着墨不多,我归纳几点:

  1. 不是每个框架都原生接入:README 提到可以用中间件去适配不支持的来源,这本身说明接入深度不一
  2. 规范绑定只有 SSE 和 Protobuf:用 WebSocket 等需要自己适配
  3. 项目由 CopilotKit 发起:许多集成文档会链到 CopilotKit 的文档。协议本身是 MIT 开源的,但如果你想用现成的前端脚手架,会自然落在 CopilotKit 的生态里,这一点选型时心里要有数
  4. 1.0 已冻结:好处是稳定,代价是新需求要等后续的草案规范;README 提到有公开路线图和草案规范,但没有描述内容

项目地址与资源


总结与展望

核心要点回顾

  1. 定位:MCP 管工具、A2A 管 Agent 之间、AG-UI 管 Agent 到用户,三者互补
  2. 核心设计:一次运行发出一条类型化事件流,只有生命周期事件是必需的,容易起步、易于扩展
  3. 覆盖面:流式文本、工具调用、共享状态、推理、人工介入、子 Agent、多模态
  4. 生态:TypeScript、Python、.NET SDK,加上大量框架的接入
  5. 留意:接入深度不一,且有 CopilotKit 的商业生态背景

适用人群

  • 要给 Agent 做前端界面、不想被某个框架绑定的开发者
  • 想让同一个 Agent 同时服务网页、终端和聊天工具的团队
  • 想了解 Agent 应用「前端协议」该怎么设计的人,这套事件模型值得参考

学习建议

先去 Dojo 演示站看各个能力的效果,再读规范里的事件定义。动手可以先用 npx create-ag-ui-app@latest 起一个脚手架,或者照 README 起一个最小的 FastAPI 服务端,用 TypeScript 客户端接上,把收到的事件逐条打印出来,亲眼看一遍一次运行里事件的顺序。最后再去 integrations/ 里找你正在用的框架,看它的接入有多完整。


欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场,所有内容均经过真实企业级工作流验证。没有噱头,只有真正有效的东西。

更多实用知识和有趣产品,欢迎访问我的个人主页

相关推荐
罗西的思考1 小时前
【轻量化复现大模型 / KIMI K3】MTP / EAGLE‑3 模块交互式演示
人工智能·深度学习·算法
RobinDevNotes2 小时前
Claude Code 剪视频,不上传、不要 API Key
人工智能·python·音视频·开发工具·ipython
stormzhangV2 小时前
Coding Agent,通往 AGI 的重要一环
人工智能·agent·ai编程
孟健3 小时前
用T3 Code手机远程控制Claude Code完成周报总结实测
开源·ai编程·claude
Bowen_J3 小时前
Apple Foundation Models:Apple AI核心框架
人工智能·ai编程·apple
IT_陈寒3 小时前
Redis那个过期删除策略,差点让我线上崩了
前端·人工智能·后端
阿里云大数据AI技术4 小时前
AI 原生大数据服务 ADA 快速入门:完成首次对话式数据分析
大数据·人工智能
字节跳动开源4 小时前
小红书/抖音图文排版利器——一个杂志风skill
人工智能·开源·设计
Bacon4 小时前
我把 Codex 塞进了 Touch Bar:一个 30pt 高的额度与对话面板
人工智能