AG-UI协议详解：人机代理交互界面的全新标准
随着AI智能体（AI Agent）能够处理真实工作流，一个新的基础设施挑战随之出现：人类与智能体在执行过程中如何通信——不仅仅是在开始和结束时，而是贯穿始终？
AG-UI协议是一个专为解决这一问题而设计的开放规范。它定义了AI智能体如何实时向前端应用和人类操作员流式传输事件、请求输入以及呈现状态的标准。如果说MCP（模型上下文协议）规范了智能体访问工具的方式，AG-UI则规范了智能体与用户通信的方式。
本指南将解释AG-UI是什么、为何重要、如何运作，以及如何在您的智能体技术栈中开始使用它。
AG-UI解决的问题
在AG-UI出现之前，每个构建面向用户的AI智能体应用的团队都必须自行发明通信协议。智能体如何告知前端它正在思考？如何请求人类决策？用户如何在任务进行中发送修正？进度如何展示？
每个团队的答案各不相同——通常是临时方案，文档匮乏，难以复用。这催生了一个碎片化的生态系统，其中：
- 智能体框架无法共享前端组件
- 开发者每次项目都要从头重建流式UI基础设施
- 用户在不同智能体产品中获得不一致的体验
- 调试智能体行为需要在每个实现中编写自定义日志
AG-UI建立了统一的词汇表和事件结构，使任何智能体框架生成的事件都能被任何AG-UI兼容的前端渲染——无需自定义集成代码。
AG-UI是什么？
AG-UI是一个开放的流式事件协议，定义了AI智能体与用户界面之间交换消息的格式和语义。
它的特点：
- 传输无关：支持HTTP（服务端推送事件）、WebSocket或任何流式传输协议
- 框架无关：可在任何语言或智能体框架中实现
- 双向通信：智能体向前端发送事件；用户向智能体发送消息和中断指令
- 有状态：协议包含状态快照，前端可在任意时刻重建完整的智能体上下文
它不是：
- 工具协议（那是MCP的职责）
- 智能体框架本身
- UI组件库（尽管参考实现存在）
AG-UI与MCP：理解区别
AG-UI与Anthropic的模型上下文协议（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— 用于标准事件集未涵盖的应用特定事件
人类介入（Human Turn）
AG-UI同样规范了人类与运行中的智能体的交互方式。前端发送AgentInput来中断、重定向或在执行过程中向智能体提供信息。这与新一轮对话不同——智能体正在运行，人类在影响其当前任务。
基于线程的架构
AG-UI将智能体运行组织成线程（Thread）——跨多次运行维持状态的持久对话上下文。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_*事件，让前端清晰显示正在发生的事情：
用户："研究排名前5的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意味着在生态系统正在汇聚的基础上构建——而非维护一个随产品增长而成为负担的定制通信层。
延伸阅读：