A2UI — Agent to UI

A2UI 让专家用一段声明式 JSON 描述界面，前端把它渲染成原生 React 组件直接嵌在对话里——不是 iframe，不是 HTML 字符串，所以视觉上和产品本身完全一致。由 profy-visualize 插件提供，工具名 render_ui。它与 visualize（自由 HTML / Canvas / WebGL）是两条并行的路：要「数据 + 布局」走 A2UI，要「自定义渲染逻辑」走 visualize。

当前能力边界：A2UI 是展示面，不是交互回路。 按钮点击会在前端派发一个 profy:a2ui-action 窗口事件，但代码里没有任何监听方——点击不会回传给专家，专家也不会因此进入下一轮推理。所以：把 A2UI 用于呈现（对比表、状态面板、结果摘要）是可靠的；把它当作「让用户点一下我就继续」的确认机制则不成立——需要用户确认时，请让专家用文字提问，或走人机确认（HITL）机制。

协议结构

render_ui 接收组件数组，返回一个 a2ui 载荷；前端 StageGroup 检测到该字段后用 A2uiSurfaceCard 渲染。

{
  "a2ui": {
    "messages": [
      {
        "version": "0.9.1",
        "type": "createSurface",
        "surfaceId": "<uuid4>",
        "components": [ /* 组件树 */ ]
      }
    ],
    "surfaceId": "<uuid4>"
  },
  "status": "rendered"
}

字段	说明
`version`	协议版本，当前固定 0.9.1
`type`	`createSurface`（初始化）或 `updateSurface`（替换整棵树）
`surfaceId`	未传时自动生成 uuid4；也是渲染卡片的标题文字
`messages`	多条消息时只有最后一条生效（last-write-wins，v1 语义）

组件节点的形状

这是最容易写错的一点——属性必须放在 props 里，不能平铺在节点上：

✓ 正确
{
  "type": "Button",
  "props": { "label": "升级套餐", "action": "upgrade", "variant": "secondary" }
}

✗ 错误（属性平铺）
{ "type": "Button", "label": "升级套餐", "action": "upgrade" }
  → 渲染器从 props 取值，取不到 label
  → 页面上出现一个写着 "Button" 的按钮，且不带 action

节点的三个可选字段：props（属性字典）、children（子组件数组）、actions（动作定义数组）。

唯一的入参校验

render_ui 只做一件事的校验：递归检查每个组件都有 type 字段。缺了就整体拒绝：

{
  "error": "Invalid component structure",
  "details": ["components[0].children[1]: missing required `type` field"]
}

除此之外不校验属性名和类型。写错属性名不会报错，只会静默渲染成空白或默认值——这是排查 A2UI 问题时最重要的一条认知。

组件目录（16 个）

以下属性名以渲染器实际读取的字段为准。

布局

组件	读取的属性	行为
`Row`	`gap`、`align`	横向 flex，自动换行
`Column`	`gap`	纵向 flex
`Card`	`title`	有 `title` 才渲染标题栏；不支持 subtitle
`Divider`	无	一条分隔线，传什么属性都忽略

gap 只认 0 / 1 / 2 / 3 / 4 / 6 / 8 这几个值（对应 Tailwind 间距档位），其余任意数字一律回落到 3。所以 gap: 16 不会得到 16px，而是默认间距。 align 认 center / end（或 bottom）/ stretch，其余回落 start。

内容

组件	读取的属性	行为
`Text`	`content`、`variant`、`weight`	`variant: "heading"` 渲染 h3，`"caption"` 渲染小号灰字，其余为正文段落
`Image`	`src`、`alt`、`width`、`height`	无 `src` 时不渲染；加载失败自动隐藏，不出破图
`Badge`	`label`、`variant`	变体只认 `secondary` / `destructive` / `outline`，其余为默认
`List`	`ordered`	`true` 渲染 `<ol>`，否则 `<ul>`；条目用 `ListItem` 子组件
`ListItem`	`content`	单个列表项
`Table`	`headers`、`rows`	`headers` 是字符串数组，`rows` 是二维字符串数组

Text 的 weight 认 bold / semibold / medium，其余不加粗。注意 variant 没有 code 这一档——传了会当正文渲染。

交互

组件	读取的属性	行为
`Button`	`label`、`action`、`variant`	无 `label` 时显示字面量 “Button”；无 `action` 时点击无任何反应

变体只认 secondary / destructive / outline；传 primary 或 ghost 都会落到默认样式（视觉上等同 primary）。按钮尺寸固定为 sm，不可调。

Profy 业务组件

组件	读取的属性	行为
`ExpertCard`	`name`、`avatar`、`description`、`rating`	`rating` 渲染成 5 星（四舍五入、上限 5）；头像加载失败自动隐藏
`CreditDisplay`	`amount`、`label`	数字带千分位，`label` 为后缀小字
`PlanBadge`	`planCode`	直接显示 code 文本；认 `free` / `pro` / `advanced` / `flagship` / `team` 的配色，其余走 outline
`StatusIndicator`	`status`、`label`	圆点配色认 `active` / `success` / `warning` / `error` / `inactive` / `pending`，其余灰色；无 `label` 时显示 status 本身
`PricingTable`	`plans`	把每个 plan 对象的键并集当表头，值统一 `String()` 后填入单元格

PricingTable 没有「高亮推荐档」的能力，也不会把 features 数组渲染成条目列表——数组会被 String() 成 a,b,c 一行文本。要漂亮的功能对比，用 Table 自己排版更可控。

不存在的组件会怎样

渲染器找不到该类型时，会渲染一个虚线框写着 Unknown component: <类型名>，并继续渲染它的子组件，不会整块崩掉。所以看到虚线框，就是类型名拼错或用了不存在的组件（例如 ProgressBar —— 目录里没有这个组件）。

完整示例

账户状态面板

render_ui(components=[
    {
        "type": "Card",
        "props": {"title": "账户概览"},
        "children": [
            {
                "type": "Row",
                "props": {"gap": 4, "align": "center"},
                "children": [
                    {"type": "CreditDisplay", "props": {"amount": 4520, "label": "积分"}},
                    {"type": "PlanBadge", "props": {"planCode": "pro"}},
                    {"type": "StatusIndicator", "props": {"status": "active", "label": "订阅生效中"}},
                ],
            },
            {"type": "Divider"},
            {"type": "Text", "props": {"content": "本月已用 68%", "variant": "caption"}},
        ],
    }
])

数据表格

注意 headers / rows 的形状——这是最常写错的地方：

render_ui(components=[
    {
        "type": "Table",
        "props": {
            "headers": ["模型", "计费单位", "适用场景"],
            "rows": [
                ["文本模型", "token_split", "对话、写作、分析"],
                ["图片模型", "per_call", "海报、插图"],
                ["视频模型", "duration_second", "短片、动效"],
            ],
        },
    }
])

列表

render_ui(components=[
    {
        "type": "Card",
        "props": {"title": "本次检查发现"},
        "children": [
            {
                "type": "List",
                "props": {"ordered": True},
                "children": [
                    {"type": "ListItem", "props": {"content": "3 个链接指向已删除页面"}},
                    {"type": "ListItem", "props": {"content": "1 张封面图缺少 alt 文本"}},
                ],
            }
        ],
    }
])

关键数值

项目	数值
组件类型总数	16 个（布局 4 + 内容 6 + 交互 1 + 业务 5）
协议版本	0.9.1
`gap` 可用档位	7 档（0 / 1 / 2 / 3 / 4 / 6 / 8），其余回落 3
按钮变体	3 个被识别（secondary / destructive / outline），其余走默认
星级上限	5 星（ExpertCard 的 rating 超过 5 按 5 计）
入参校验项	1 项（每个组件必须有 `type`）
生效的 message	最后 1 条（多条时前面的被覆盖）

失败与对策

现象	原因	对策
按钮点了没反应	动作事件目前无监听方，A2UI 是展示面	需要确认动作时改用文字提问
出现虚线框 `Unknown component`	类型名拼错，或用了目录外的组件（如 `ProgressBar`）	对照上面 16 个组件名
按钮上写着字面量 “Button”	属性平铺了，没放进 `props`	所有属性移进 `props`
表格是空的	`headers` / `rows` 形状不对（传了对象数组而非字符串二维数组）	按 `headers: string[]` + `rows: string[][]` 写
徽章没有文字	用了 `text` 而不是 `label`	改成 `label`
套餐徽章永远显示 free	用了 `plan` 而不是 `planCode`	改成 `planCode`
积分显示成 0	用了 `balance` 而不是 `amount`	改成 `amount`
间距和预期不一致	`gap` 传了档位外的数字	用 0/1/2/3/4/6/8
整个渲染失败并返回 error	某个组件缺 `type`	看 `details` 里的路径，如 `components[0].children[1]`
图片位置空白	`src` 为空，或加载失败被自动隐藏	检查 URL 可访问性

模型看到的组件说明与渲染器存在已知偏差。 注入给模型的 A2UI 提示词里列的部分属性名（如 Badge 的 color、Table 的 columns、PlanBadge 的 plan、CreditDisplay 的 unit）与渲染器实际读取的字段不一致，且属性写成平铺形式。由于 render_ui 只校验 type，这类偏差不会报错，只会静默渲染成空白或默认值。如果你看到 A2UI 面板缺内容，先按本页的属性名核对，而不是怀疑数据本身有问题。

最佳实践

属性一律放 props，这是所有静默失败的第一来源。
用 Card 做顶层容器，逻辑相关的组件放进同一个 Card 形成视觉单元。
嵌套别超过 3 层，深层布局既脆弱又难读。
只用它呈现，不依赖它交互——需要用户决策时用文字提问。
要图表 / 3D / 动画走 visualize，A2UI 只有这 16 个预定义组件。
面板之后补一句话总结，A2UI 是叠加的展示层，不替代解释。

核对日期 2026-08-12。来源：apps/web/src/lib/a2ui/{definitions.ts,renderers.tsx}、apps/web/src/components/agent/chat-area/card/A2uiSurfaceCard.tsx、packages/types/src/a2ui.ts、services/agent-runtime/src/plugins/builtin/visualize/tools/render_ui.py。

可视化插件

自由 HTML / Canvas / WebGL 渲染面

插件全表

28 个内置插件的完整清单

开始使用

核心概念

使用指南

平台与账户

深入了解

A2UI（Agent to UI）

A2UI — Agent to UI

协议结构

组件节点的形状

唯一的入参校验

组件目录（16 个）

布局

内容

交互

Profy 业务组件

不存在的组件会怎样

完整示例

账户状态面板

数据表格

列表

关键数值

失败与对策

最佳实践

相关

可视化插件

插件全表

​A2UI — Agent to UI

​协议结构

​组件节点的形状

​唯一的入参校验

​组件目录（16 个）

​布局

​内容

​交互

​Profy 业务组件

​不存在的组件会怎样

​完整示例

​账户状态面板

​数据表格

​列表

​关键数值

​失败与对策

​最佳实践

​相关

可视化插件

插件全表

A2UI — Agent to UI

协议结构

组件节点的形状

唯一的入参校验

组件目录（16 个）

布局

内容

交互

Profy 业务组件

不存在的组件会怎样

完整示例

账户状态面板

数据表格

列表

关键数值

失败与对策

最佳实践

相关