AG-UI 1.0 统一智能体与前端通信
AG-UI 用双向事件流传递模型输出、工具调用、共享状态和人工介入等事件,让同一智能体适配多种客户端。1.0 版以 JSON Schema 固化规范,据项目介绍可与 0.x 客户端和智能体双向兼容。
AI 深度解读
AI Agent 回答到一半可能会调用工具、更新界面状态,或者停下来等人确认。前端如果只接收文本流,就得为这些动作另写一套接线逻辑。AG-UI 把运行过程定义成一系列带类型的事件,让不同框架实现的 Agent 可以接入同一套客户端。
原文最值得看的,是 AG-UI 1.0 冻结了协议规范,以及一个无需 API Key 的 Python 示例如何把运行和消息拆成事件。对前端和全栈开发者来说,这能帮你判断项目什么时候需要一套事件协议。

前端为什么需要收到「发生了什么」
普通请求通常等后端返回一个结果。文本流能让回答逐段显示,但如果中途还有工具调用、共享状态更新、人工确认或子 Agent,界面还得知道每条数据对应什么动作。比如收到一段文字时,前端应该把它追加到正在显示的回答里。收到消息结束事件时,才可以把这条消息标记为完成。
AG-UI 为这些交互定义了一套双向事件协议。最小接入只需要一个 HTTP 端点,接收 RunAgentInput,再将带类型的事件流式返回。前端按事件类型更新界面,Agent 团队则可以用自己选的框架实现业务逻辑。按这个设计,同一个 Agent 可以接 Web、移动端、终端或 Slack,各端仍需各自决定怎么呈现事件。
1.0 固定了什么,怎么跑起来
AG-UI 1.0 冻结了规范,并用 JSON Schema 定义数据结构。TypeScript、Python 和 .NET SDK 都从这份 Schema 生成。原文称,兼容性是双向的,0.x Agent 能接 1.0 客户端,1.0 Agent 也能接 0.x 客户端。
如果想先看前端接线,下面的命令会生成一个项目,可选 Next.js 上的 CopilotKit 前端或终端客户端,再接上选定的 Agent 框架。
npx create-ag-ui-app@latest
这行命令里的 @latest 用来获取最新的脚手架。生成后按终端提示继续,模板调用 OpenAI,因此在执行 npm run dev 前,需要用下面这行设置模型密钥。
export OPENAI_API_KEY="sk-..."
把这一行里的 sk-... 换成自己的 key。只想读懂事件流,可以看原文的无密钥示例。它要求 Python 3.9+,依赖通过 pip install ag-ui-protocol fastapi uvicorn 安装。
示例用 FastAPI 接收 RunAgentInput,并把请求的 accept 头传给 EventEncoder。RunStartedEvent 带上 thread_id、run_id 和由 PROTOCOL_VERSION 提供的 protocol_version。接着,TextMessageStartEvent 用 role="assistant" 开始一条消息,TextMessageContentEvent 用同一个 message_id 发送三段 delta,最后由 TextMessageEndEvent 收尾。原文在构造 RunFinishedEvent 时截断了,贴出的 Python 代码无法直接运行。
我的判断
如果团队要维护多个客户端,或者已经在为不同 Agent 框架维护多套事件映射,统一事件类型有实际价值。如果只有一个页面和一个后端,功能也只是持续追加文本,现有的流式接口通常就够用。原文展示了协议和最小示例,没有给出延迟、接入成本或跨版本测试数据。双向兼容是原文给出的协议声明,升级时仍应拿项目正在用的 SDK 组合跑一遍。
原文提到社区遇过事件流重叠后 pending_tool_calls 没有清理的问题,但没有交代复现条件或解决方案。示例只演示了一次运行里的顺序文本事件。对有工具调用的界面,并发、取消和失败后的状态清理都需要单独验证。
能拿来做什么
- 在 React 或 Next.js 里,先用固定事件驱动一条消息。收到开始事件时创建消息,收到
delta时按message_id追加,收到结束事件时标记完成。 - 如果 Node 服务已经在向前端转发 Agent 输出,先盘点界面是否需要呈现工具调用、人工确认或共享状态,再决定是否把现有输出映射到 AG-UI 事件。
- 如果同一个界面允许两次运行重叠,验证其中一次取消或失败后,另一条消息能否继续更新,以及取消的运行是否还残留待处理工具调用。