A2UI 回复

用 "output_format": "a2ui"（默认）创建的会话里，回复除了文字还可以是界面：卡片、列表、图片、按钮和表单，由你的应用原生渲染。界面用 A2UI 描述——一个由助手编写界面、由客户端渲染的开放协议——版本 1.0，使用其基础组件目录（Text、Image、Icon、Video、AudioPlayer、Row、Column、List、Card、Tabs、Modal、Divider、Button、TextField、CheckBox、ChoicePicker、Slider、DateTimeInput）。

任何支持基础组件目录的 A2UI 1.0 渲染器都能渲染这些回复。

界面数据从哪里来

• 每当任务的界面数据变化，事件流上的 ui.updated 帧都会带来它的完整界面数据：一组 A2UI 消息。请用新列表替换你为这个任务渲染的内容——不要合并。
• 结束帧（task.completed 或 task.stopped）在回复的 text 旁边带着最终的 ui。
• a2ui 回复的文字是纯文本：回复在界面之外说的话。请把它作为文字显示在界面旁边。

{
  "task_id": "exec-5a2c…",
  "ui": [
    {
      "version": "v1.0",
      "createSurface": {
        "surfaceId": "exec-5a2c…/t0/main",
        "catalogId": "https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json"
      }
    },
    {
      "version": "v1.0",
      "updateComponents": {
        "surfaceId": "exec-5a2c…/t0/main",
        "components": [
          { "id": "root", "component": "Card", "child": "body" },
          { "id": "body", "component": "Column", "children": ["title", "photo", "more"] },
          { "id": "title", "component": "Text", "text": "**Leek and potato soup**" },
          { "id": "photo", "component": "Image", "url": { "path": "/media/s0/url" } },
          {
            "id": "more",
            "component": "Button",
            "child": "more_label",
            "action": { "event": { "name": "show_steps", "context": {} } }
          },
          { "id": "more_label", "component": "Text", "text": "Show the steps" }
        ]
      }
    },
    {
      "version": "v1.0",
      "updateDataModel": {
        "surfaceId": "exec-5a2c…/t0/main",
        "path": "/media/s0",
        "value": { "url": "https://…", "status": "ready", "kind": "image" }
      }
    }
  ]
}

• 界面的 surfaceId 在会话内唯一。请把它当作不透明的字符串。
• 任务生成的媒体出现在界面的数据模型里，路径为 /media/<slot>，带 url（会过期的签名下载链接）、status 和 kind。组件绑定到这些数据，所以图片生成完成后就会显示——这个变化以一个新的 ui.updated 到达。
• 同样的媒体也会在 media.updated 帧里逐个报告。

把用户的操作发回

当用户操作一个带 action 的组件——点 Button、提交表单——你的渲染器会产生一条 A2UI 操作消息。把它原样放进 a2ui_action 发送，并把用户看到自己发出的内容（例如按钮上的文字）作为 text：

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Show the steps",
    "a2ui_action": {
      "version": "v1.0",
      "action": {
        "name": "show_steps",
        "surfaceId": "exec-5a2c…/t0/main",
        "sourceComponentId": "more",
        "timestamp": "2026-10-19T08:03:00Z",
        "context": {}
      }
    }
  }'

• action.name 是组件的 action.event.name；surfaceId 和 sourceComponentId 说明用户在哪里操作。
• action.context 是事件的 context，其中的数据绑定已解析为用户选择或输入的值。以 JSON 计最多 4,000 个字符，最多嵌套 8 层。
• A2UI 规范允许出现在操作消息里的其他字段都会被接受。
• 只有 a2ui 会话接受 a2ui_action；markdown 会话会拒绝它，返回 422 validation_failed。

这条消息和其他消息一样开启一个任务，回复也以同样的方式流式返回。

如何选择输出形式

	a2ui	markdown
回复	界面数据加纯文本	Markdown 文字
你的应用需要	A2UI 渲染器	Markdown 渲染器
可交互元素	按钮、表单、选择器——以 a2ui_action 发回	无：用户自己输入下一条消息

输出形式在创建会话时确定。