2026 年，AI Agent 已经可以从容完成复杂的编码、推理和工具调用任务。但一个核心问题依然困扰着开发者：如何让用户自然地与这些 Agent 交互？

传统的方案是聊天界面——用户发送消息，Agent 回复。但这远远不够。真正的智能应用需要：

  • 实时状态同步：用户能看到 Agent 正在思考什么
  • 流式响应：文字和结果像打字机一样逐字显示
  • 工具执行可视化：Agent 调用工具时，用户能看得见
  • 双向交互：Agent 可以主动请求用户确认或补充信息

这就是 AG-UI（Agent-User Interaction）协议 要解决的问题。

一、为什么需要 AG-UI？

1.1 传统前端与 Agent 的鸿沟

在 AG-UI 出现之前，开发者需要自己解决 Agent 与前端之间的通信问题：

  • 轮询（Polling）：前端不断问 Agent"有没有新消息"——效率低，延迟高
  • WebSocket 手动实现：实时通信没问题，但事件格式、数据结构、状态管理都要自己设计
  • 各家方案不同：LangGraph 有一种做法，CrewAI 有另一种，Microsoft Agent Framework 又不一样

结果是：每个团队都在重复造轮子，而且造出来的轮子互相不兼容。

1.2 AG-UI 的诞生

AG-UI 由 CopilotKit 团队提出，是一个开放的事件驱动协议，旨在标准化 用户界面与 Agent 后端之间的双向通信。

它的核心思路是：把 Agent 的每一次"思考"、“输出”、“工具调用"都变成一个可订阅的事件，前端只需要监听这些事件，就能实时渲染用户界面。

二、AG-UI 的核心概念

2.1 事件驱动架构

AG-UI 本质上是一个基于事件的协议。Agent 的每一次动作——开始运行、输出文字、调用工具、思考推理——都会被封装成一个事件，推送给前端。

前端像订阅 RSS 一样订阅这些事件，实时更新界面。

2.2 五大事件类型

AG-UI 定义了约 16 种事件，分为五大类：

1. 生命周期事件（Lifecycle Events）

  • RUN_STARTED：Agent 开始运行
  • RUN_FINISHED：Agent 运行结束
  • RUN_ERROR：运行出错
  • STEP_STARTED：某个步骤开始
  • STEP_FINISHED：某个步骤结束

2. 文本消息事件（Text Message Events）

  • TEXT_MESSAGE_START：开始输出文本
  • TEXT_MESSAGE_CONTENT：文本内容（流式传输，每次一个 delta）
  • TEXT_MESSAGE_END：文本输出结束

3. 工具调用事件（Tool Call Events）

  • TOOL_CALL_START：Agent 开始调用工具
  • TOOL_CALL_ARGS：工具参数（流式）
  • TOOL_CALL_END：工具调用结束
  • TOOL_CALL_RESULT：工具返回结果

4. 状态管理事件（State Management Events）

  • STATE_SNAPSHOT：完整状态快照
  • STATE_DELTA：状态变化增量
  • MESSAGES_SNAPSHOT：消息历史快照
  • ACTIVITY_SNAPSHOT：活动状态快照

5. 推理事件（Reasoning Events）

  • REASONING_START：开始推理
  • REASONING_MESSAGE_START：推理消息开始
  • REASONING_MESSAGE_CONTENT：推理内容（流式）
  • REASONING_END：推理结束

这些事件让前端可以精确地渲染 Agent 的每一个状态，实现真正的"实时可见”。

三、AG-UI vs MCP vs A2A：各司其职

很多初学者会混淆这三个协议。它们不是竞争关系，而是互补关系：

协议作用类比
MCPAgent ↔ 工具/数据USB 接口——把各种外设（工具、数据）接入 Agent
A2AAgent ↔ AgentHTTP 协议——让不同的 Agent 互相通信
AG-UIAgent ↔ 用户界面浏览器渲染引擎——把 Agent 的行为实时展示给用户

简单来说：

  • MCP 解决 Agent"用什么工具"
  • A2A 解决 Agent"和谁协作"
  • AG-UI 解决 Agent"如何与用户沟通"

四、AG-UI 的技术细节

4.1 协议栈位置

AG-UI 位于用户应用与 Agent Runtime 之间：

用户界面 (React/Vue/Angular)
        ↓
    AG-UI 协议层
        ↓
    Agent Runtime (LangGraph / CrewAI / Microsoft Agent Framework / AWS Strands ...)
        ↓
    MCP 协议层（可选）
        ↓
    工具和数据源

4.2 支持的框架

AG-UI 不是只有 CopilotKit 能用。它已经被多家主流框架采纳：

  • LangGraph
  • Microsoft Agent Framework
  • AWS Strands
  • CrewAI
  • Agno
  • LlamaIndex
  • Mastra
  • Pydantic AI

这就是协议的力量——一旦标准化，任何框架都可以实现它。

4.3 三种生成式 UI 模式

AG-UI 是整个"生成式 UI"（Generative UI）技术栈的底层协议。在它之上，有三种实现方式：

1. AG-UI（静态方式）

  • Agent 返回结构化数据，前端根据类型渲染对应组件
  • 最成熟，兼容性最好

2. A2UI（声明式）

  • Google 提出的规范，Agent 返回 JSONL 格式的 UI 描述
  • 前端"声明式"渲染

3. MCP Apps + Open JSON（开放式）

  • Agent 直接描述想要的 UI，前端灵活渲染
  • 最灵活，但需要更多前端逻辑

五、实战：用 AG-UI 构建智能应用

5.1 快速开始

CopilotKit 提供了开箱即用的 AG-UI 集成：

npx create-ag-ui-app my-agent-app

这会创建一个完整的示例应用，包含：

  • React 前端（已集成 AG-UI 客户端）
  • Agent 后端（LangGraph 示例）
  • 实时事件流展示

5.2 手动集成

如果你想在自己的项目中使用 AG-UI，只需要：

1. 安装 SDK

npm install @ag-ui/core

2. 连接 Agent

import { AgentClient } from '@ag-ui/core';

const client = new AgentClient({
  url: 'http://localhost:8000/ag-ui',
});

// 订阅事件
client.on('TEXT_MESSAGE_CONTENT', (event) => {
  // 流式显示 Agent 的输出
  appendToChat(event.delta.content);
});

client.on('TOOL_CALL_START', (event) => {
  // 显示 Agent 正在调用工具
  showToolCallIndicator(event.tool_name);
});

client.on('REASONING_MESSAGE_CONTENT', (event) => {
  // 显示 Agent 的思考过程
  showThinking(event.delta.content);
});

// 发送用户消息
await client.runAgent({
  messages: [{ role: 'user', content: '帮我写一个排序算法' }]
});

3. 后端实现（Python 示例）

from ag_ui_core import EventType, TextMessageContentEvent

async def stream_response():
    # 发送文本开始事件
    yield TextMessageStartEvent(message_id="msg_1")
    
    # 流式发送内容
    for chunk in response_chunks:
        yield TextMessageContentEvent(
            message_id="msg_1",
            delta=chunk
        )
    
    # 发送结束事件
    yield TextMessageEndEvent(message_id="msg_1")

六、企业级应用场景

6.1 客服 Agent

传统的客服 chatbot 只能处理简单的问答。借助 AG-UI，客服 Agent 可以：

  • 实时展示"正在查询订单…"
  • 显示"正在为您生成解决方案…"
  • 在必要时暂停，等待用户确认
  • 调用多个工具时，逐一展示执行过程

6.2 代码助手

IDE 中的 AI 助手可以通过 AG-UI 实现：

  • 流式显示代码补全
  • 展示代码审查的思考过程
  • 工具调用时显示正在搜索的上下文

6.3 业务流程自动化

企业级工作流 Agent 可以通过 AG-UI：

  • 让用户实时看到流程进度
  • 在关键节点暂停，等待审批
  • 显示每个步骤的执行结果

七、为什么 AG-UI 对企业至关重要

7.1 可观测性

企业需要对 AI Agent 的行为有清晰的可见性。AG-UI 把 Agent 的每一个动作都变成可追踪的事件，这对调试、审计、合规都非常重要。

7.2 安全与控制

AG-UI 在用户与 Agent 之间建立了一个"边界层"（boundary）。企业可以：

  • 在关键操作前暂停 Agent
  • 插入人工审核步骤
  • 实时监控 Agent 行为

7.3 防止碎片化

如果没有标准协议，每个供应商都会发明自己的"Agent-UI"方案。AG-UI 试图在早期就建立标准，避免未来的集成噩梦。

八、总结与展望

AG-UI 是 AI Agent 生态中不可或缺的一环。它解决了一个根本问题：如何让用户自然地与 Agent 协作？

随着 AI Agent 在企业中的普及，AG-UI 的重要性只会增加。它不仅是技术协议，更是人机协作的基础设施。

如果你正在构建面向用户的 AI 应用，AG-UI 值得你深入了解。

相关资源