A2UI对接后端工程化最佳实践：从协议到落地的完整指南

用户操作 → 前端(Renderer) → 传输层(AG-UI/A2A/SSE) → 后端(Agent)
                                                        ↓
                                                   LLM / 业务逻辑
                                                        ↓
后端生成A2UI JSON → 传输层 → 前端Renderer → 原生UI组件

{"version":"v0.9.1","createSurface":{"surfaceId":"booking","catalogId":"https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"}}
{"version":"v0.9.1","updateComponents":{"surfaceId":"booking","components":[{"id":"title","component":"Text","text":"预订餐厅"},{"id":"date-input","component":"DateTimeInput","label":"选择日期","enableDate":true,"path":"/booking/date"},{"id":"submit","component":"Button","child":"submit-text","action":{"event":{"name":"confirm_booking"}}}]}}
{"version":"v0.9.1","updateDataModel":{"surfaceId":"booking","path":"/booking","value":{"date":"2026-07-02","guests":2}}}
{"version":"v0.9.1","beginRendering":{"surfaceId":"booking","root":"title"}}

{
  "Column": {
    "children": [
      {"Text": {"text": "你好"}},
      {"Row": {
        "children": [
          {"Button": {"text": "取消"}},
          {"Button": {"text": "确认"}}
        ]
      }}
    ]
  }
}

[
  {"id": "root", "component": "Column", "children": ["greeting", "buttons"]},
  {"id": "greeting", "component": "Text", "text": "你好"},
  {"id": "buttons", "component": "Row", "children": ["cancel-btn", "ok-btn"]},
  {"id": "cancel-btn", "component": "Button", "child": "cancel-text"},
  {"id": "ok-btn", "component": "Button", "child": "ok-text"},
  {"id": "cancel-text", "component": "Text", "text": "取消"},
  {"id": "ok-text", "component": "Text", "text": "确认"}
]

{"text": {"literalString": "欢迎光临"}}

{"text": {"path": "/user/name"}}

<!-- pom.xml 关键依赖 -->
<dependency>
    <groupId>io.github.vishalmysore</groupId>
    <artifactId>a2ajava</artifactId>
    <version>最新版本</version>
</dependency>

src/main/java/com/example/
├── agent/                    # Agent服务层
│   ├── OrderAgent.java       # 订单Agent（核心业务）
│   └── CustomerAgent.java    # 客户Agent
├── a2ui/                     # A2UI构建器
│   ├── ComponentBuilder.java # 组件构建工具类
│   └── SurfaceFactory.java   # 页面工厂
├── config/                   # 配置
│   └── A2UIConfig.java
└── controller/               # 入口
    └── AgentController.java

@Service
@Agent(groupName = "orderService",
       groupDescription = "处理订单查询和操作")
publicclass OrderAgent implements A2UIDisplay {

    @Autowired
    private OrderRepository orderRepo;

    @Action(description = "查询订单详情")
    public Object queryOrder(String orderId) {
        Order order = orderRepo.findById(orderId);

        // 关键：双模式响应
        if (isUICallback(callback)) {
            returnbuildOrderDetailUI(order);  // A2UI客户端 → 返回UI
        }
        return order.toString();  // 普通客户端 → 返回文本
    }

    private Map<String, Object> buildOrderDetailUI(Order order) {
        List<Map<String, Object>> components = new ArrayList<>();

        // 标题
        components.add(createTextComponent("title",
            "订单详情 #" + order.getId(), "h2"));

        // 订单信息
        components.add(createTextComponent("status",
            "状态：" + order.getStatus(), "body"));
        components.add(createTextComponent("amount",
            "金额：¥" + order.getAmount(), "body"));

        // 操作按钮
        Map<String, String> ctx = Map.of("orderId", "/order/id");
        components.add(createButtonComponent("cancel-btn",
            "取消订单", "cancelOrder", ctx));
        components.add(createTextComponent("cancel-btn_text", "取消订单"));

        // 构建完整消息
        Map<String, Object> data = Map.of("/order/id", order.getId());
        returnbuildA2UIMessageWithData("order_detail", "title", components, data);
    }
}

@Action(description = "获取用户信息")
public Object getUserInfo(String userId) {
    User user = userService.getById(userId);
 
    if (isUICallback(callback)) {
        // A2UI客户端：返回带表单的交互界面
        return buildUserProfileUI(user);
    }
    // CLI/API客户端：返回纯文本
    return String.format("用户：%s，邮箱：%s", user.getName(), user.getEmail());
}

private Map<String, Object> buildBookingFormUI() {
    List<Map<String, Object>> components = new ArrayList<>();

    // 表单字段——通过path绑定数据
    components.add(createTextFieldComponent("name-input",
        "姓名", "/form/name"));
    components.add(createTextFieldComponent("phone-input",
        "手机号", "/form/phone"));
    components.add(createTextComponent("date-label", "选择日期", "body"));

    // 提交按钮——context提取表单数据
    Map<String, String> formContext = new LinkedHashMap<>();
    formContext.put("name", "/form/name");
    formContext.put("phone", "/form/phone");
    components.add(createButtonComponent("submit",
        "提交预订", "submitBooking", formContext));
    components.add(createTextComponent("submit_text", "提交预订"));

    // 初始化空数据
    Map<String, Object> initData = Map.of(
        "/form/name", "",
        "/form/phone", ""
    );

    returnbuildA2UIMessageWithData("booking_form", "name-input",
        components, initData);
}

// 表单提交处理
@Action(description = "提交预订")
public Object submitBooking(String name, String phone) {
    // 参数由框架从context绑定自动提取
    Booking booking = bookingService.create(name, phone);

    if (isUICallback(callback)) {
        returnbuildConfirmationUI(booking);  // 返回确认页面
    }
    return"预订成功：" + booking.getId();
}

# agent.py
from google.adk import Agent
from google.adk.a2ui import SurfaceUpdate, DataModelUpdate

agent = Agent(name="booking_agent", model="gemini-2.5-flash")

@agent.tool
defcreate_booking_form():
    """创建预订表单"""
    surface = SurfaceUpdate(
        surface_id="booking",
        components=[
            {"id": "title", "component": "Text",
             "text": "餐厅预订", "usageHint": "h1"},
            {"id": "date-input", "component": "DateTimeInput",
             "label": "选择日期", "enableDate": True,
             "path": "/booking/date"},
            {"id": "guests-input", "component": "TextField",
             "label": "用餐人数", "path": "/booking/guests"},
            {"id": "submit", "component": "Button",
             "child": "submit-text",
             "action": {"event": {"name": "confirm_booking"}}},
            {"id": "submit-text", "component": "Text",
             "text": "确认预订"}
        ]
    )

    data = DataModelUpdate(
        surface_id="booking",
        path="/booking",
        value={"date": "2026-07-02", "guests": 2}
    )

    return [surface, data]

# server.py
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json

app = FastAPI()

defgenerate_a2ui_stream(user_input: str):
    """生成A2UI JSONL消息流"""

    # Step 1: 创建Surface
    yield json.dumps({
        "version": "v0.9.1",
        "createSurface": {
            "surfaceId": "main",
            "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
        }
    }) + "\n"

    # Step 2: 发送组件
    yield json.dumps({
        "version": "v0.9.1",
        "updateComponents": {
            "surfaceId": "main",
            "components": [
                {"id": "header", "component": "Text",
                 "text": f"搜索结果：{user_input}", "usageHint": "h1"},
                {"id": "result-card", "component": "Card",
                 "child": "result-content"},
                {"id": "result-content", "component": "Text",
                 "text": {"path": "/result/content"}}
            ]
        }
    }) + "\n"

    # Step 3: 填充数据（可以异步获取后再发送）
    result = search_service.query(user_input)
    yield json.dumps({
        "version": "v0.9.1",
        "updateDataModel": {
            "surfaceId": "main",
            "path": "/result",
            "value": {"content": result}
        }
    }) + "\n"

    # Step 4: 通知渲染
    yield json.dumps({
        "version": "v0.9.1",
        "beginRendering": {"surfaceId": "main", "root": "header"}
    }) + "\n"

@app.post("/agent/chat")
asyncdefchat(request: dict):
    returnStreamingResponse(
        generate_a2ui_stream(request["message"]),
        media_type="application/x-ndjson"
    )

{
  "catalogId": "https://your-company.com/a2ui/catalog/v1",
  "components": {
    "Text": { "allowed": true, "maxLength": 5000 },
    "Button": { "allowed": true, "allowedActions": ["submit", "cancel", "navigate"] },
    "TextField": { "allowed": true, "maxDataPaths": ["/form/*"] },
    "Card": { "allowed": true },
    "Image": { "allowed": true, "allowedDomains": ["cdn.your-company.com"] },
    "Script": { "allowed": false },
    "IFrame": { "allowed": false }
  }
}

你的系统有多个Agent协作吗？
├── 是 → 用A2A作为Agent间通信 + AG-UI/SSE作为前端通信
└── 否 → 前端需要实时推送事件给后端吗？
         ├── 是 → 用AG-UI（双向SSE + WebSocket）
         └── 否 → 用裸SSE（最简单）

# ❌ 错误：等全部生成完再发
defgenerate_ui():
    components = build_all_components()    # 耗时2秒
    data = fetch_all_data()                # 耗时3秒
    return [components, data, render]      # 用户等了5秒才看到UI

# ✅ 正确：流式逐步发送
defgenerate_ui_stream():
    yieldcreate_surface()                  # 立即发送
    yieldbuild_skeleton_components()       # 先发骨架，用户0.1秒看到框架
    yieldbuild_detail_components()         # 再发细节
    data = fetch_data()                     # 异步获取数据
    yielddata_model_update(data)           # 数据就绪后发送
    yieldbegin_rendering()                 # 通知渲染

# ❌ 全量替换：重新发送整个组件树
yield update_components(surface_id="main", components=ALL_COMPONENTS)
 
# ✅ 增量更新：只发变化的组件
yield update_components(surface_id="main", components=[
    {"id": "status-text", "component": "Text",
     "text": "订单已确认"}  # 只更新这一个组件
])

# ❌ 粗粒度：更新整个数据树
yield update_data_model(path="/", value=entire_data_tree)
 
# ✅ 细粒度：只更新变化的路径
yield update_data_model(path="/order/status", value="confirmed")
yield update_data_model(path="/order/updated_at", value="2026-07-02T10:30:00Z")