随着AI智能体日益强大，足以处理真实工作流，一个新的基础设施挑战随之浮现：人类和智能体如何在执行过程中通信——不只是在开始和结束时，而是贯穿整个过程？
AG-UI协议是一套专为解决这一问题而设计的开放规范。它定义了AI智能体如何实时向前端应用和人类操作员流式传输事件、请求输入并展示状态的标准。如果MCP（Model Context Protocol）规范了智能体访问工具的方式，那么AG-UI就规范了智能体与用户沟通的方式。
本指南将介绍AG-UI是什么、为何重要、如何运作，以及如何在您的智能体技术栈中开始使用它。
AG-UI解决了什么问题
在AG-UI出现之前，每个构建面向用户的AI智能体应用的团队都不得不自行发明通信协议。智能体如何让前端知道它正在"思考"？如何请求人类决策？用户如何在任务执行中途发送修正指令？进度如何展示？
每个团队的答案各不相同——往往是临时拼凑的，文档不足，难以复用。这造成了一个碎片化的生态系统：
- 智能体框架无法共享前端组件
- 开发者每个项目都要从头重建流式UI基础设施
- 用户在不同智能体驱动产品中体验不一致
- 调试智能体行为需要在每个实现中编写自定义日志
AG-UI建立了共同的词汇表和事件结构，使任何智能体框架都能产生任何AG-UI兼容前端可以渲染的事件——无需自定义集成代码。
什么是AG-UI？
AG-UI是一种开放的流式事件协议，定义了AI智能体与面向用户的界面之间交换消息的格式和语义。
它是：
- 传输无关的：可通过HTTP（Server-Sent Events）、WebSocket或任何流式传输协议运行
- 框架无关的：可在任何语言或智能体框架中实现
- 双向的：智能体向前端发送事件；用户向智能体发送消息和中断指令
- 有状态的：协议包含状态快照，使前端能够随时重建完整的智能体上下文
它不是：
- 工具协议（那是MCP的职责）
- 智能体框架本身
- UI组件库（尽管存在参考实现）
AG-UI vs. MCP：理解两者的区别
常见的混淆点在于AG-UI与Anthropic的Model Context Protocol（MCP）的关系。
| 维度 | MCP | AG-UI |
|---|---|---|
| 目的 | 智能体 ↔ 工具通信 | 智能体 ↔ 人类/前端通信 |
| 方向 | 智能体调用工具，接收结果 | 智能体流式传输事件；人类发送消息 |
| 受众 | 工具/服务器开发者 | 前端和智能体框架开发者 |
| 关注点 | 智能体可以使用哪些能力 | 智能体如何传达其状态和进度 |
| 关系 | 处理智能体的"工具"侧 | 处理智能体的"用户界面"侧 |
两者相辅相成。在生产环境中运行的智能体通常使用MCP访问工具（网络搜索、图像生成、代码执行），使用AG-UI传达进度并请求人类输入。
AG-UI的核心概念
事件类型
AG-UI定义了智能体发出的一套标准事件类型：
生命周期事件：
RUN_STARTED/RUN_FINISHED— 智能体已开始或完成执行STEP_STARTED/STEP_FINISHED— 工作流中的一个离散步骤已开始或结束RUN_ERROR— 智能体遇到了不可恢复的错误
消息事件：
TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT/TEXT_MESSAGE_END— 来自智能体的流式文本输出TOOL_CALL_START/TOOL_CALL_ARGS/TOOL_CALL_END— 智能体正在调用工具
状态事件：
STATE_SNAPSHOT— 当前智能体状态的完整快照STATE_DELTA— 状态的增量更新MESSAGES_SNAPSHOT— 特定时间点的完整对话历史
自定义事件：
CUSTOM— 用于标准集合未涵盖的应用特定事件
人类轮次
AG-UI还规范了人类与运行中的智能体交互的方式。前端发送AgentInput以在执行过程中中断、重定向或向智能体提供信息。这与新的对话轮次不同——智能体正在运行，而人类正在影响其当前任务。
基于线程的架构
AG-UI将智能体运行组织成线程——跨多次运行维护状态的持久对话上下文。AG-UI中的线程大致相当于其他框架中的会话或对话，但具有对恢复、分支和重放的明确协议支持。
AG-UI的工作原理：典型流程
1. 用户通过前端提交任务
2. 前端向智能体后端发送包含RunAgentInput的InitialRun请求
3. 智能体开始执行并发出RUN_STARTED事件
4. 智能体为每个规划步骤发出STEP_STARTED
5. 智能体调用工具 → 发出TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END
6. 智能体生成文本 → 发出TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT（流式传输）、TEXT_MESSAGE_END
7. 智能体发出STATE_DELTA以实时更新前端状态
8. 用户决定重定向智能体 → 发送包含修正的AgentInput
9. 智能体采纳修正并继续
10. 智能体发出RUN_FINISHED
前端将这些事件作为流接收并逐步渲染——实时显示工具调用、流式传输文本，并根据步骤事件更新进度指示器。
实现AG-UI
框架支持
AG-UI正在各主要智能体框架中获得支持：
- LangGraph：可使用AG-UI Python SDK从图节点发出AG-UI事件
- AG-UI CopilotKit集成：CopilotKit（一个面向AI的React前端框架）原生支持AG-UI
- 自定义实现：AG-UI规范是开放的；任何框架都可以使用事件类型定义来实现它
快速入门（Python）
from ag_ui.core import (
RunAgentInput, EventType,
RunStartedEvent, TextMessageStartEvent,
TextMessageContentEvent, TextMessageEndEvent,
RunFinishedEvent,
)
import uuid
async def run_agent(input: RunAgentInput):
run_id = str(uuid.uuid4())
yield RunStartedEvent(
type=EventType.RUN_STARTED,
thread_id=input.thread_id,
run_id=run_id,
)
msg_id = str(uuid.uuid4())
yield TextMessageStartEvent(type=EventType.TEXT_MESSAGE_START, message_id=msg_id, role="assistant")
for chunk in agent.stream(input.messages):
yield TextMessageContentEvent(
type=EventType.TEXT_MESSAGE_CONTENT,
message_id=msg_id,
delta=chunk
)
yield TextMessageEndEvent(type=EventType.TEXT_MESSAGE_END, message_id=msg_id)
yield RunFinishedEvent(type=EventType.RUN_FINISHED, thread_id=input.thread_id, run_id=run_id)
连接AnyCap
当您的AG-UI智能体需要现实世界的能力——网络搜索、图像生成、文件存储——时，AnyCap作为工具层集成在编排层之下。智能体在执行循环中调用AnyCap工具，并发出相应的TOOL_CALL_*事件，让前端显示正在发生的事情：
用户："研究排名前五的AI框架并创建一张摘要图片"
智能体发出：TOOL_CALL_START（tool: "anycap_search"，args: {...}）
智能体发出：TOOL_CALL_END（result: 搜索结果）
智能体发出：TOOL_CALL_START（tool: "anycap_image_generate"，args: {...}）
智能体发出：TOOL_CALL_END（result: 图片URL）
智能体发出：TEXT_MESSAGE（嵌入图片的流式摘要）
这种完全透明性——通过AG-UI事件呈现——正是可信赖的人机交互界面与"黑盒"的本质区别。
为什么AG-UI对生产级智能体应用至关重要
如果您正在构建智能体驱动的产品，AG-UI提供了：
组件可复用性。 按AG-UI规范构建的前端组件可与任何兼容后端配合使用。只需构建一次流式聊天UI，即可在LangGraph、CrewAI和AutoGen中无需修改地使用。
一致的用户体验。 由于事件类型已标准化，用户在不同智能体工作流中看到相同的交互模式。
调试能力。 AG-UI的状态快照和事件流为您提供智能体执行的完整记录。重放事件流可以精确查看智能体在每个步骤中看到了什么、做了什么。
人类监督。 用于任务执行中途人类干预的AgentInput机制已内置于协议中——而非事后补充。
结语
AG-UI填补了智能体AI基础设施栈中真实存在的空白。随着智能体变得更加强大并日益面向用户，传达其状态并接收人类输入的协议变得与其可访问的工具同等重要。
对于2026年构建智能体驱动产品的开发者来说，提早采用AG-UI意味着在生态系统正在汇聚的基础上构建——而非维护一套随产品增长而成为负担的定制通信层。
延伸阅读：