A2UI 和 AG-UI:给 Agent 接前端的两个协议怎么用

A2UI 和 AG-UI:给 Agent 接前端的两个协议怎么用

两个协议的名字像得让人怀疑是故意的:AG-UI 管 Agent 和前端之间怎么传事件,A2UI 管 Agent 往前端画什么。把这对"管道与载荷"的分工理清楚,agent 应用的前端架构就定了一半。

过去一年做 agent 应用的人大概都撞过同一堵墙:聊天窗口只能显示 markdown,用户真正想要的是一个能点的按钮、一张能调数量的卡片、一个跟着意图变的表单。为解决这个问题,业界冒出两个名字很像的协议:AG-UI(Agent-User Interaction Protocol)和 A2UI(Agent-to-UI)。AG-UI 官方文档专门写了一段"Confused about A2UI and AG-UI?"来澄清,可见混淆的人真不少。一句话分工:AG-UI 是管道,A2UI 是管道里跑的一种载荷。

按四件套走:是什么、怎么用、值得学什么、同类怎么选。

本文提纲

  1. 是什么:三层协议地图里各自占哪一层
  2. 怎么用 AG-UI:16 类事件打天下,附最小服务端和客户端代码
  3. 怎么用 A2UI:目录、技能、编译、渲染、回传五步
  4. 值得学什么:目录即护栏、布局与数据分离、事件即需求清单
  5. 同类比较:AG-UI、A2UI、CopilotKit、手写 SSE 怎么选

是什么:一个管怎么传,一个管画什么

先看两个协议的底子。

AG-UI 出自 CopilotKit 团队,仓库 2 万+ stars(2026 年 11 月 18 日查,下同),定位是"开放的、轻量的、基于事件的协议",标准化 agent 与用户端应用之间的双向连接。今年发布了 1.0 稳定版规范,官方博客说 Google、Microsoft、Amazon、Oracle 都已采用。npm 上 @ag-ui/core 和 @ag-ui/client 都是 1.0.5,PyPI 上 ag-ui-protocol 是 1.0.0。

A2UI 出自 Google,仓库 1.7 万+ stars,Apache-2.0 协议,CopilotKit 团队也参与共建。它的定位是"生成式 UI 框架":agent 输出声明式的界面描述(一串 JSON 消息),客户端用自己注册的原生组件渲染,规范目前在 v1.0。渲染器覆盖 React、Lit、Angular、Flutter、SwiftUI、Jetpack Compose 六端。

放回整张协议地图里,AG-UI 文档给的三层表格最清楚:

层 协议 管什么
Agent ↔ 用户 AG-UI agent 与前端应用之间的事件流:文本流、工具调用、状态同步、生命周期
Agent ↔ 工具和数据 MCP agent 连外部系统:工具、工作流、数据源
Agent ↔ Agent A2A 分布式 agent 之间协调分工

A2UI 不在这张表里,它解决的是另一件事:agent 怎么把界面"画"到你屏幕上,而且画出来的东西用你的组件库、走你的安全模型。AG-UI 文档把 A2UI 归在 Generative UI 集成一类,A2UI 官网也把 AG-UI 列为自己的传输层之一,两个协议互为补位。A2UI 官方五分钟示例的架构图里,消息流长这样:

MERMAID_BLOCK_0

一句话读图:AG-UI 是前端和 agent 后端之间那条双向事件总线,聊天流、状态、工具调用都从这走;A2UI 的界面消息同样可以搭这条总线过去,到前端后由 A2UI 渲染器画成原生组件。

怎么用 AG-UI:事件即接口

AG-UI 的核心契约一句话能说完:你的 agent 后端暴露一个 POST 端点,收一个 RunAgentInput,吐一串带类型的 BaseEvent。官方把这套抽象写成 run(input: RunAgentInput) -> Observable<BaseEvent>,传输层不绑定,SSE、WebSocket、HTTP 二进制都行。

16 类事件就是全部词汇表

官方架构文档把核心事件定为 16 类,按用途分组:

分组 事件 干什么
生命周期 RUN_STARTED / RUN_FINISHED / RUN_ERROR / STEP_STARTED / STEP_FINISHED 一次 agent 运行的边界和阶段
文本消息 TEXT_MESSAGE_START / CONTENT / END 流式吐字,START 和 END 之间的 CONTENT 逐段拼接
工具调用 TOOL_CALL_START / ARGS / END agent 调工具的实时进展,参数也是流式的
状态同步 STATE_SNAPSHOT / STATE_DELTA / MESSAGES_SNAPSHOT 共享状态全量与增量,增量用 JSON Patch(RFC 6902)
特殊 RAW / CUSTOM 透传原始事件和自定义事件

事件文档在这个基础上还在长:ToolCallResult 补上工具执行结果、TEXT_MESSAGE_CHUNK / TOOL_CALL_CHUNK 是"一条顶三条"的便捷事件、reasoning 事件暴露思考过程、subagent 事件追踪子 agent 的输出归属。16 类是骨架,其余是血肉。

服务端:一个 FastAPI 端点就够

按官方 quickstart,pip install ag-ui-protocol 之后,一个最小的流式聊天端点长这样:

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (
    RunAgentInput, EventType,
    RunStartedEvent, TextMessageChunkEvent, RunFinishedEvent, RunErrorEvent,
)
from ag_ui.encoder import EventEncoder

app = FastAPI()

@app.post("/")
async def agent_endpoint(input_data: RunAgentInput, request: Request):
    encoder = EventEncoder(accept=request.headers.get("accept"))

    async def event_generator():
        try:
            yield encoder.encode(RunStartedEvent(
                type=EventType.RUN_STARTED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id,
            ))
            # 这里换成你自己的模型调用:拿到一段 delta 就转发一段
            async for delta in your_llm_stream(input_data.messages):
                yield encoder.encode(TextMessageChunkEvent(
                    type=EventType.TEXT_MESSAGE_CHUNK,
                    message_id="msg_1",
                    delta=delta,
                ))
            yield encoder.encode(RunFinishedEvent(
                type=EventType.RUN_FINISHED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id,
            ))
        except Exception as error:
            yield encoder.encode(RunErrorEvent(type=EventType.RUN_ERROR, message=str(error)))

    return StreamingResponse(event_generator(), media_type=encoder.get_content_type())

input_data 里除了消息,还带着前端定义的 tools、共享 state 和自定义 context,前端传什么、后端就能用什么,这就是"双向"的由来。

客户端:HttpAgent 十几行接完

TypeScript 侧用 @ag-ui/client 的 HttpAgent 指向你的端点,订阅事件流:

import { HttpAgent } from "@ag-ui/client";
import { EventType } from "@ag-ui/core";

const agent = new HttpAgent({ url: "http://localhost:8000/" });

agent.runAgent({
  messages: [{ id: "msg_1", role: "user", content: "帮我把这周订单改成素食" }],
}).subscribe({
  next: (event) => {
    switch (event.type) {
      case EventType.TEXT_MESSAGE_CHUNK:
        process.stdout.write(event.delta); // 逐字上屏
        break;
      case EventType.STATE_DELTA:
        // RFC 6902 JSON Patch,按补丁更新前端共享状态
        break;
    }
  },
  error: console.error,
  complete: () => console.log("done"),
});

不想手写组件的话,CopilotKit 是官方的 AG-UI 客户端,React、Angular、Vue、React Native 都有现成组件;npx create-ag-ui-app@latest 一条命令脚手架出前后端;AG-UI Dojo 里有每个特性的在线 demo 和源码,调试时先对齐它最省事。

生态:从 LangGraph 到 Claude Agent SDK

AG-UI 起家靠 LangChain/LangGraph 和 CrewAI 两家合作,现在集成列表已经很长:Microsoft Agent Framework、Google ADK、AWS Strands、AWS Bedrock AgentCore、Mastra、Pydantic AI、Agno、LlamaIndex、AG2 是第一方,Claude Agent SDK、Claude Managed Agents、OpenAI Agents SDK、Cloudflare Agents 在社区目录,Go、Rust、Dart、Kotlin、Java、Ruby、C++、.NET 的社区 SDK 也有维护。接现成框架的话,你不用手写上面那个端点,装对应的中间件包就行。

怎么用 A2UI:从目录到界面五步

A2UI 的用法不是"装个包调个函数",而是一条五步管线。官方概念页用一个订机票的例子走完全程:

MERMAID_BLOCK_1

第 1 步:定义组件目录 catalog.json

目录声明客户端能渲染哪些组件,每个组件用 JSON Schema 写清属性。这是 A2UI 安全模型的根:

{
  "protocolVersion": "1.0",
  "catalogId": "https://example.com/catalogs/travel/v1/catalog.json",
  "components": {
    "FlightCard": {
      "type": "object",
      "description": "Displays a flight segment with fare and passenger count.",
      "properties": {
        "component": {"const": "FlightCard"},
        "flightNumber": {"$ref": "common_types.json#/$defs/DynamicString"},
        "price": {"$ref": "common_types.json#/$defs/DynamicNumber"},
        "passengers": {"$ref": "common_types.json#/$defs/DynamicNumber"}
      },
      "required": ["component", "flightNumber", "origin", "destination", "price", "passengers"]
    }
  }
}

第 2 步:把目录变成技能

Agent SDK 的 skill 生成器读目录,产出一份给模型看的提示词技能:A2UI 的语法规则(变量赋值、数据绑定以 $ 开头引用数据模型路径)加上目录里每个组件的签名,比如 FlightCard(flightNumber, origin, destination, price, passengers)。模型照着这份技能写界面,等于照着你的组件库写,而不是凭记忆瞎编标签。Agent SDK 有 TypeScript、Python、Dart 三种,Python 的 a2ui-agent-sdk 0.12.0 是 2026 年 11 月 17 日刚发的。

第 3 步:模型输出 Express DSL

模型不用直接写线上的 JSON,A2UI Express 这种紧凑 DSL 让模型少打很多字:

<a2ui>
$/outbound/pax = 1
$/outbound/price = 455
$/return/pax = 2
$/return/price = 970

root = Card(Column([
  FlightCard(flightNumber="LH 454", origin="BER", destination="SFO",
             price=$/outbound/price, passengers=$/outbound/pax),
  FlightCard(flightNumber="UA 901", origin="SFO", destination="BER",
             price=$/return/price, passengers=$/return/pax),
  Button(Text("Confirm booking"), variant="primary",
         action=Event("confirm_booking", {
           outboundPax: $/outbound/pax, returnPax: $/return/pax
         }))
]))
</a2ui>

第 4 步:编译校验,产出三种消息

Agent SDK 的编译器边收流边解析,逐个检查组件和属性是否在目录里、类型对不对,不合法的当场报。校验通过后产出三类线上消息:

{"version": "1.0", "createSurface": {"surfaceId": "flight-booking-surface", "catalogId": "https://example.com/catalogs/travel/v1/catalog.json"}}
{"version": "1.0", "updateComponents": {"surfaceId": "flight-booking-surface", "components": [
  {"id": "root", "component": "Card", "child": "layout_col"},
  {"id": "layout_col", "component": "Column", "children": ["flight_outbound", "flight_return", "submit_btn"]},
  {"id": "flight_outbound", "component": "FlightCard", "flightNumber": "LH 454", "origin": "BER", "destination": "SFO",
   "price": {"@path": "/outbound/price"}, "passengers": {"@path": "/outbound/pax"}}
]}}
{"version": "1.0", "updateDataModel": {"surfaceId": "flight-booking-surface", "path": "/", "value": {"outbound": {"pax": 1, "price": 455}}}}

注意组件树是扁平列表靠 id 串成树,@path 是数据绑定。这些消息跑在 AG-UI、A2A、MCP 或 WebSocket 任意一种传输上。

第 5 步:渲染与回传

客户端的渲染器(比如 yarn add @a2ui/react @a2ui/web_core 装的 React 渲染器)收到消息后,把扁平列表解析成节点树、绑上数据模型,用原生组件画出来:

import {MessageProcessor} from '@a2ui/web_core/v0_9';
import {basicCatalog} from '@a2ui/web_core/v0_9/basic_catalog';
import {A2uiSurface} from '@a2ui/react/v0_9';

const processor = new MessageProcessor([basicCatalog]);
processor.processMessages(agentMessages); // agent 发来的 A2UI 消息流

// 每个 surface 是一个独立渲染区,用 A2uiSurface 画出来
<A2uiSurface key={surface.id} surface={surface} />

之后的交互分两种:用户在卡片上点"+"把乘客从 1 调到 2,渲染器直接改本地数据模型 /outbound/pax,所有绑到这个路径的组件原地更新,一个字节都不发给 agent;用户点"Confirm booking"按钮,渲染器才发一条 action 消息回 agent:

{"version": "1.0", "action": {"name": "confirm_booking", "surfaceId": "flight-booking-surface", "sourceComponentId": "submit_btn", "context": {"outboundPax": 2, "returnPax": 2}}}

本地编辑不打扰、确认动作才回传,这是 A2UI 交互模型里最值得琢磨的一刀。想不动手先看效果,A2UI 官网的 quickstart 让你把一份提示词丢给 Claude Code 或 Cursor,十分钟跑起一个带 React 和 Flutter 双客户端的行程规划应用;也可以直接玩在线 Playground 和可检查消息流的 Composer。给编码 agent 装规则的话,一行 npx skills add a2ui-project/a2ui。

值得学什么

目录即护栏。 A2UI 把"agent 能画什么"收进一个 JSON Schema 目录,模型输出先过编译器校验再上屏,非法组件到不了用户屏幕。对比让模型直接生成 HTML/JS 的路线,这条路的失控半径小得多:界面用的是你注册的组件,样式走你的设计系统,跨 React、Flutter、SwiftUI 还是同一份消息流。ByteDance、Atlassian 都在用它。

布局与数据分离。 组件列表是扁平的、数据在独立的模型里、两边靠 @path 绑定。这个设计让"加一个乘客"这种交互纯本地完成,不打扰 agent;agent 只在用户做出确认类动作时才被唤醒。做 agent 前端的人可以原样借走这套思路,哪怕不用 A2UI。

生成式 UI 的光谱。 A2UI 官网把 agent 出界面分成三档:调预置 widget(100% 宿主控制)、从目录组合编排(A2UI 主场)、沙箱里跑生成的 HTML/JS(MCP Apps 可嵌进 surface)。三档各有得失,按风险选档,比"要不要上生成式 UI"这种二元问题务实得多。

16 类事件是一份自研协议需求清单。 想给自己的 agent 后端定前端契约时,AG-UI 这 16 类就是现成的 checklist:生命周期怎么封口、文本和工具参数怎么流、状态全量和增量怎么补、透传和自定义留什么口子。CHUNK 便捷事件和 metadata 的"最后写入赢"合并规则,都是"让接入方少写代码"的具体妥协,值得抄。另一个设计决定是 middleware 思路:不逼框架改造成原生 AG-UI 事件,只要能转成兼容事件就行,这让 LangGraph 们接入的成本从重构降到适配。

同类比较:到底该接哪个

维度 AG-UI A2UI 手写 SSE 端点
解决什么 agent 与前端的双向事件契约 agent 生成声明式 UI 的消息规范 无契约,两端各写各的
形态 事件类型 + TS/Python SDK + 各框架中间件 消息规范 + 编译器 + 六端渲染器 自己封装
状态同步 STATE_SNAPSHOT / DELTA(JSON Patch) surface 数据模型 + @path 绑定 自己设计
安全边界 事件流本身不含可执行代码 目录校验 + 声明式 JSON,无代码执行 自己把关
成熟度 规范 1.0,@ag-ui/* 1.0.5 规范 1.0,npm 渲染器文档还在 v0.9 路径 取决于你
出身 CopilotKit 系,Google/Microsoft/Amazon/Oracle 采用 Google 系,CopilotKit 参与 -

选型判断:

  • 只做聊天加流式输出,或想给现有框架接前端:AG-UI,或直接上 CopilotKit 全家桶,现成组件最多。
  • 要 agent 主导界面(订票表单、购物车、审批面板),又不想让它写 HTML/JS:A2UI,用目录把它的手圈住。
  • 两个都要:AG-UI 当管道,A2UI 当载荷,官方就是这么组合的,A2UI 文档的传输一栏明确写着 AG-UI。
  • UI 的使用方是第三方 MCP server:看 MCP Apps,A2UI surface 里可以直接嵌 MCP App。
  • 一次性 demo:手写 SSE 没问题;要做产品,两端契约漂移得很快,事件类型、状态补丁、中断恢复、子 agent 归属,这些坑 AG-UI 都替你踩过了。

丑话说在前面:A2UI 规范已到 v1.0,但 npm 上 @a2ui/react 0.15.0 的 README 还在用 v0_9 的导入路径,各端 SDK 追规范有先后,动手前以官方 quickstart 为准;AG-UI 集成列表长,但各家中间件成熟度不一,接之前先跑一遍 Dojo 里对应框架的 demo。文中 stars 和版本号都是 2026 年 11 月 18 日查的,时效自负。

参考文档与链接

你的 agent 输出还只是一段 markdown,还是已经用组件目录圈住了它的手?评论区聊聊你的前端选型。觉得有用点个赞。


作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top

posted @ 2026-11-18 22:38  iTech  阅读(3)  评论(0)    收藏  举报