AG-UI 协议详解：人机代理界面的新标准

AG-UI 是 AI 代理与前端 UI 之间进行实时流式通信的开放协议。本文将解释事件模型如何工作、支持哪些消息类型，以及它为何对智能体应用开发者如此重要。

by AnyCap

AG-UI 协议架构图——展示 UI 前端与 AI 代理之间的双向流式事件

随着 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 与 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_* 事件，让前端能够展示当前正在发生什么：

User: "研究前 5 个 AI 框架并创建一张总结图片"

Agent emits: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agent emits: TOOL_CALL_END (result: search results)
Agent emits: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agent emits: TOOL_CALL_END (result: image URL)
Agent emits: TEXT_MESSAGE (streaming summary with embedded image)

这种通过 AG-UI 事件呈现出来的完全透明性，正是值得信赖的人机代理界面与黑箱系统之间的关键区别。

为什么 AG-UI 对生产级代理应用很重要

如果你正在构建代理驱动产品，AG-UI 提供了以下价值：

组件可复用性。 按照 AG-UI 规范构建的前端组件可以与任何兼容后端配合使用。只需构建一次流式聊天 UI，就可以在 LangGraph、CrewAI 和 AutoGen 上无修改复用。

一致的用户体验。 由于事件类型已经标准化，用户在不同代理工作流中会看到相同的交互模式。

调试能力。 AG-UI 的状态快照和事件流为你提供代理执行的完整记录。回放一个事件流，就能准确看到代理在每一步看到了什么、做了什么。

人工监督。 用于任务中途人工干预的 AgentInput 机制，是协议原生内置的，而不是事后拼接上去的。

总结

AG-UI 填补了智能体 AI 基础设施栈中的一个真实空白。随着代理变得更强大、也更直接面向用户，代理如何传达状态、如何接收人工输入的协议，会变得和它们能访问哪些工具一样重要。

对于在 2026 年构建代理驱动产品的开发者来说，尽早采用 AG-UI，意味着你是在一个整个生态都正在汇聚的基础之上构建，而不是继续维护一层随着产品增长而逐渐成为负担的定制通信层。

延伸阅读：