> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# A2UI（Agent to UI）

> 声明式 JSON 驱动的原生 React UI 渲染面，支持 16 种组件与用户交互回调

# A2UI — Agent to UI

A2UI 让 Agent 通过声明式 JSON 描述 UI 结构，前端将其渲染为原生 React 组件并嵌入聊天区。用户与组件交互（如点击按钮）时，事件回传给 Agent 进行后续处理。

## 工作原理

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Frontend
    participant User
    Agent->>Frontend: render_ui(components=[...])
    Frontend->>Frontend: 解析 JSON → 渲染 React 组件
    Frontend->>User: 展示结构化 UI
    User->>Frontend: 点击 Button(action="confirm")
    Frontend->>Agent: dispatch action event
    Agent->>Agent: 处理用户选择
```

## 基本用法

Agent 调用 `render_ui` 工具，传入组件数组：

```python theme={null}
render_ui(components=[
    {
        "type": "Card",
        "title": "当前套餐",
        "children": [
            {"type": "PlanBadge", "plan": "pro"},
            {"type": "Text", "content": "有效期至 2026-08-01"},
            {"type": "Button", "label": "升级套餐", "action": "upgrade", "variant": "primary"}
        ]
    }
])
```

工具返回结果包含 `a2ui` 字段，前端 `StageGroup` 检测到该字段后渲染 `A2UIRenderer` 组件。

## 组件目录

### 布局组件

#### Row

水平排列子组件。

| 属性         | 类型                             | 说明              |
| ---------- | ------------------------------ | --------------- |
| `gap`      | `number`                       | 子组件间距 (px)，默认 8 |
| `align`    | `"start" \| "center" \| "end"` | 垂直对齐方式          |
| `children` | `Component[]`                  | 子组件列表           |

#### Column

垂直排列子组件。

| 属性         | 类型            | 说明              |
| ---------- | ------------- | --------------- |
| `gap`      | `number`      | 子组件间距 (px)，默认 8 |
| `children` | `Component[]` | 子组件列表           |

#### Card

带标题和边框的容器。

| 属性         | 类型            | 说明   |
| ---------- | ------------- | ---- |
| `title`    | `string?`     | 卡片标题 |
| `subtitle` | `string?`     | 副标题  |
| `children` | `Component[]` | 卡片内容 |

### 内容组件

#### Text

文本展示，支持 Markdown。

| 属性        | 类型                                                          | 说明                |
| --------- | ----------------------------------------------------------- | ----------------- |
| `content` | `string`                                                    | 文本内容（支持 Markdown） |
| `size`    | `"sm" \| "md" \| "lg"`                                      | 字号，默认 `"md"`      |
| `weight`  | `"normal" \| "medium" \| "bold"`                            | 字重                |
| `color`   | `"default" \| "muted" \| "success" \| "warning" \| "error"` | 颜色语义              |

#### Image

图片展示。

| 属性       | 类型        | 说明      |
| -------- | --------- | ------- |
| `src`    | `string`  | 图片 URL  |
| `alt`    | `string?` | 替代文本    |
| `width`  | `number?` | 宽度 (px) |
| `height` | `number?` | 高度 (px) |

#### Divider

水平分割线。

| 属性      | 类型        | 说明      |
| ------- | --------- | ------- |
| `label` | `string?` | 分割线中间文字 |

#### Badge

标签/徽章。

| 属性        | 类型                                                         | 说明   |
| --------- | ---------------------------------------------------------- | ---- |
| `text`    | `string`                                                   | 徽章文字 |
| `variant` | `"default" \| "success" \| "warning" \| "error" \| "info"` | 样式变体 |

#### List

列表展示。

| 属性        | 类型         | 说明                |
| --------- | ---------- | ----------------- |
| `items`   | `string[]` | 列表项               |
| `ordered` | `boolean`  | 是否有序列表，默认 `false` |

#### Table

表格展示。

| 属性        | 类型                               | 说明              |
| --------- | -------------------------------- | --------------- |
| `columns` | `{key: string, label: string}[]` | 列定义             |
| `rows`    | `Record<string, string>[]`       | 行数据             |
| `compact` | `boolean`                        | 紧凑模式，默认 `false` |

### 交互组件

#### Button

可点击按钮，点击后触发 Action 回传。

| 属性         | 类型                                                     | 说明               |
| ---------- | ------------------------------------------------------ | ---------------- |
| `label`    | `string`                                               | 按钮文字             |
| `action`   | `string`                                               | 点击时回传的 action 标识 |
| `variant`  | `"primary" \| "secondary" \| "destructive" \| "ghost"` | 按钮样式             |
| `disabled` | `boolean`                                              | 是否禁用             |
| `payload`  | `Record<string, any>?`                                 | 回传时附加的数据         |

### Profy 业务组件

#### ExpertCard

专家信息卡片。

| 属性            | 类型        | 说明     |
| ------------- | --------- | ------ |
| `identifier`  | `string`  | 专家标识符  |
| `name`        | `string`  | 专家名称   |
| `avatar`      | `string?` | 头像 URL |
| `description` | `string?` | 简介     |

#### CreditDisplay

积分余额展示。

| 属性        | 类型       | 说明           |
| --------- | -------- | ------------ |
| `balance` | `number` | 当前余额         |
| `unit`    | `string` | 单位文字，默认 "积分" |

#### PlanBadge

套餐等级徽章。

| 属性     | 类型                                                     | 说明   |
| ------ | ------------------------------------------------------ | ---- |
| `plan` | `"free" \| "starter" \| "pro" \| "flagship" \| "team"` | 套餐代码 |

#### StatusIndicator

状态指示器。

| 属性       | 类型                                               | 说明   |
| -------- | ------------------------------------------------ | ---- |
| `status` | `"active" \| "inactive" \| "pending" \| "error"` | 状态   |
| `label`  | `string`                                         | 状态文字 |

#### PricingTable

定价对比表。

| 属性       | 类型                                          | 说明            |
| -------- | ------------------------------------------- | ------------- |
| `plans`  | `{name, price, features[], highlighted?}[]` | 套餐列表          |
| `action` | `string?`                                   | CTA 按钮 action |

#### ProgressBar

进度条。

| 属性      | 类型                                               | 说明          |
| ------- | ------------------------------------------------ | ----------- |
| `value` | `number`                                         | 当前值 (0-100) |
| `label` | `string?`                                        | 进度标签        |
| `color` | `"default" \| "success" \| "warning" \| "error"` | 颜色          |

## Action 处理

当用户点击带 `action` 属性的 Button，前端将事件分发给 Agent：

```json theme={null}
{
  "type": "a2ui_action",
  "action": "upgrade",
  "payload": {"plan": "pro"},
  "componentPath": "card.0.button.2"
}
```

Agent 在下一轮推理中可以读取该 action 并做出响应（如跳转到支付页、更新展示内容等）。

## 示例

### 套餐对比

```python theme={null}
render_ui(components=[
    {"type": "Text", "content": "选择适合你的套餐", "size": "lg", "weight": "bold"},
    {
        "type": "PricingTable",
        "plans": [
            {"name": "免费版", "price": "0", "features": ["每日 100 积分", "基础模型"]},
            {"name": "进阶版", "price": "49/月", "features": ["每月 5000 积分", "全部模型", "优先响应"], "highlighted": True},
            {"name": "旗舰版", "price": "199/月", "features": ["每月 20000 积分", "全部模型", "专属客服"]}
        ],
        "action": "select_plan"
    }
])
```

### 状态仪表盘

```python theme={null}
render_ui(components=[
    {
        "type": "Card",
        "title": "账户概览",
        "children": [
            {
                "type": "Row",
                "gap": 16,
                "children": [
                    {"type": "CreditDisplay", "balance": 4520},
                    {"type": "PlanBadge", "plan": "pro"},
                    {"type": "StatusIndicator", "status": "active", "label": "订阅生效中"}
                ]
            },
            {"type": "Divider"},
            {"type": "ProgressBar", "value": 68, "label": "本月用量 68%"},
            {
                "type": "Row",
                "gap": 8,
                "children": [
                    {"type": "Button", "label": "充值", "action": "recharge", "variant": "primary"},
                    {"type": "Button", "label": "查看明细", "action": "view_detail", "variant": "ghost"}
                ]
            }
        ]
    }
])
```

### 操作确认

```python theme={null}
render_ui(components=[
    {
        "type": "Card",
        "title": "确认操作",
        "children": [
            {"type": "Text", "content": "即将删除专家「财务顾问」，此操作不可撤销。", "color": "warning"},
            {
                "type": "Row",
                "gap": 8,
                "align": "end",
                "children": [
                    {"type": "Button", "label": "取消", "action": "cancel", "variant": "ghost"},
                    {"type": "Button", "label": "确认删除", "action": "confirm_delete", "variant": "destructive", "payload": {"identifier": "financial-advisor"}}
                ]
            }
        ]
    }
])
```

## 最佳实践

1. **优先使用 A2UI 而非 Inline Visualization**：当展示结构化数据（表格、列表、状态）时，A2UI 组件更一致且性能更优
2. **保持组件树浅层**：嵌套不超过 3 层，避免复杂度过高
3. **Action 命名使用 snake\_case**：如 `confirm_delete`、`select_plan`，便于 Agent 解析
4. **使用 payload 传递上下文**：Button 的 `payload` 字段可以携带 Agent 需要的额外数据，避免靠位置推断
5. **合理使用 Card 分组**：逻辑相关的组件放入同一个 Card，视觉上形成独立单元
6. **当需要自由绘图/Canvas/WebGL 时选择 Inline Visualization**：A2UI 只支持预定义组件集