AI / Agent UX 设计
从不确定输出、流式执行、工具调用、人类确认、长任务、错误恢复和信任管理理解 AI / Agent 产品的交互设计。
[!info] related notes
- 所属 MOC: ui-ux-moc
- 工程组成: agent-interaction-ui
- 决策边界: ask-user-tool, approval-workflow
- 流式界面: ai-chat-and-streaming-ui
AI / Agent UX 设计
一句话理解 Agent UX
传统软件的核心交互通常比较确定：
User
↓
UI
↓
Known Action
↓
Known ResultAgent 产品则更像：
User Intent
↓
Agent starts work
↓
collects context / uses tools
↓
intermediate states
↓
may need user confirmation
↓
uncertain result
↓
user accepts / corrects / continues所以 Agent UX 的核心不只是“把 AI 回复放进聊天框”，而是：
让一个具有不确定性、会调用工具、可能运行较久、可能需要人类介入的系统，仍然让用户感到清楚、可控、可信并且能够恢复。
Agent UX 和普通 Chat UI 的区别
普通聊天界面可以只关注：
输入 → 消息 → 回复Agent 产品往往还需要处理：
- streaming；
- retrieval；
- tool call；
- approval；
- ask user；
- long-running task；
- progress；
- interrupt；
- retry；
- partial result；
- artifact；
- uncertainty；
- memory / context；
- correction；
- resume。
已有 Agent Interaction UI 已经整理了 Chat、Tool Call、Approval、Artifact、Status 和 Controls 的界面组成；本篇更关注这些东西为什么存在以及怎样组合成好的体验。
第一原则：把不确定性设计进产品，而不是假装不存在
AI 输出不是传统函数式 UI 那样完全确定。
因此不能默认：
AI 输出 = 正确事实更健康的产品模型是：
AI Output
↓
可能可靠 / 可能不完整 / 可能需要确认
↓
UI 提供上下文、依据和后续动作已有 AI 输出不确定性与交互设计 的最短原则是：
前端不只是显示答案，还要管理用户对答案的理解、信任和后续动作。
1. Status：用户必须知道 Agent 现在在做什么
长时间没有反馈是 Agent 产品最糟糕的体验之一。
对用户有意义的状态可以是：
已收到
正在分析输入
正在查找相关资料
正在处理数据
需要你确认
正在生成结果
已完成
失败，可重试不要把“透明”误解成展示 Chain of Thought
用户不需要、产品也不应该把模型内部私有推理逐字暴露出来。
真正有价值的是：
- 当前阶段；
- 已执行的外部动作；
- 需要用户介入的原因；
- 重要结果；
- 可验证依据；
- 下一步动作。
可以记成：
Show progress and actions, not private reasoning.
2. Controllability：Agent 自动化越强，用户控制越重要
用户至少需要在适当场景拥有：
Stop
Cancel
Edit
Retry
Regenerate
Reject
Confirm
Correct
Continue长任务应提供与运行时能力一致的停止和恢复入口。点击取消后先显示“正在请求取消”；只有服务端确认后才显示“已取消”。取消不等于撤销已经完成的外部动作，无法停止的动作应说明当前状态。
3. Ask User：缺信息时不要硬猜
Agent 最大的能力之一，就是发现缺失信息后主动提问。
以 BodySense 的交互设计为例（不是对当前部署能力的核验）：
“肩膀最近不舒服”如果系统需要知道左右侧，却没有足够上下文：
Agent detects ambiguity
↓
Ask User
↓
左侧 / 右侧 / 双侧？
↓
用户确认
↓
继续处理这适用于答案会改变处理正确性的关键缺失信息。可以从现有上下文确认的信息应先复用；低影响偏好可使用说明过的默认值，避免每一步都要求用户回答。
已有 Ask User Tool 可继续从 Agent 工程视角深入。
4. Tool Call：用户真正关心的是现实动作
Agent 调工具意味着系统可能已经开始影响现实世界或读取外部信息。
UI 至少要区分：
准备执行
正在执行
执行成功
执行失败
需要批准不同工具风险不同：
- 搜索资料通常低风险；
- 修改用户数据风险更高；
- 删除、支付、发送外部消息等不可逆动作需要更强控制。
所以 Tool UI 不能只是为了“炫技展示 Agent 在工作”，它应该帮助用户理解动作、风险和结果。
5. Approval：确认应该放在决策边界上
不是所有 Tool Call 都要用户批准。
先判断已有授权、具体参数与产品策略，再结合影响和可逆性决定是否询问。一个实用思路：
低风险 + 可逆
→ 可以自动执行并提供结果/Undo
中风险
→ 视上下文要求确认
超出已有授权 / 策略要求确认
→ 执行前明确 Approval
已有授权覆盖且参数未发生实质变化
→ 按授权执行；记录结果并提供可用的恢复入口Approval UI 应回答：
- Agent 想做什么？
- 为什么现在需要做？
- 会影响什么？
- 用户可以修改参数吗？
- Confirm / Reject 后分别发生什么？
确认必须绑定实际动作、对象和参数；实质变化后应重新判断授权。UI 的 Confirm 不能代替服务端权限校验。已有 Human Approval UI 和 Approval Workflow 可继续深入。
6. Progress：长任务不要只给一个 Spinner
对于几秒以上甚至更长的 Agent 工作，单纯：
Thinking...很快会失去信息价值。
更好的进度表达可以是：
已接收请求
→ 正在检索相关资料
→ 已找到 6 条候选依据
→ 正在整理结果重点不是制造虚假的百分比，而是让用户知道任务是否仍在推进。
如果系统无法可靠估计完成比例，就不要伪造“83%”。
7. Interrupt / Resume：Agent 不是只能等它跑完
用户可能在中途发现：
- 输入错了；
- 方向不对；
- 已经不需要结果；
- 需要补充新信息。
所以长任务应考虑：
running
├─ completed
├─ failed
├─ cancel_requested → cancelled（服务端确认）
└─ interrupted → user input → resumed断流只表示失去更新，不证明任务已停止；恢复前需查询权威状态，并避免重放已产生副作用的动作。设计背景可结合 BodySense Consultation Streaming Architecture。
8. Partial Result：部分结果也可能有价值
Agent 工作失败并不意味着所有中间成果都应该消失。
例如：
已完成症状信息提取
证据检索失败UI 可以保留已确认的部分，同时明确哪个部分没有完成。
这比整页变成：
Something went wrong更诚实、更容易恢复。
9. Error Recovery：错误不仅要说明，还要能继续
Agent 错误可能来自：
- network；
- provider；
- tool；
- permission；
- validation；
- timeout；
- model output；
- 用户取消（通常是主动终止状态，不应一律当作系统故障）。
用户界面不需要展示所有内部堆栈，但要告诉用户：
现在什么没完成？
已有结果是否保留？
可以重试什么？
是否需要修改输入？
是否能稍后继续？已有 AI 产品前端稳定性 与 前端交互状态统一处理 可以复用。
10. Trust：信任来自可理解、可纠正和可验证
提高用户信任不是多写一句“AI 可能犯错”。
更有效的是：
- 显示必要来源和证据；
- 清楚区分事实、推断和待确认信息；
- 用户能够纠错；
- 不确定时主动问；
- 高风险场景降低自动化；
- 失败时诚实表达；
- 不把系统包装成比实际更确定。
BodySense：Agent UX 为什么尤其重要
BodySense 涉及身体健康相关信息，这意味着产品不能把普通聊天产品的“自信回答”习惯直接搬过来。
用户真正需要的是：
我说了什么
系统确认了什么
系统还不确定什么
用了哪些相关依据
哪些地方需要我补充
什么只是记录和组织
什么时候应该升级到专业医疗判断界面应避免把 AI 推断视觉包装成“已经医学确诊”的事实。
一个更合理的事实层级
用户明确陈述
→ user-reported statement（确认来源是用户，不等于医学事实已证实）
多轮对话中持续出现
→ repeated report（保留时间与来源，重复本身不提高真实性）
AI 推断但证据不足
→ needs confirmation / hypothesis
需要安全升级
→ safety escalation（处理决策，和事实可信度不是同一维度）这些语义首先应该由业务和 Agent contract 定义，UI 再选择恰当表达，而不是前端自己用颜色创造医学含义。
BodySense Consultation 的 UX 状态机
以下是用户视角的设计示意；实际状态名、持久化和恢复能力需与运行时合同核对：
idle
↓ user sends message
submitting
↓
streaming
├─ needs more context → waiting_user
├─ retrieval/tool → working
├─ needs confirmation → waiting_confirmation
├─ error → recoverable_error
├─ cancel requested → cancelling → cancelled（确认后）
└─ completed → completed
↓
user continues / corrects这里每个状态都应该有：
- 用户看见什么；
- 用户能做什么；
- 下一步允许到哪里；
- 数据是否持久化；
- 是否能恢复。
BodySense：身体记录更新的 Agent UX
假设用户在对话中说：
“最近抬手时左肩前侧会痛。”可以设计成：
消息进入 Consultation
↓
AI 正在处理
↓
提取到 left shoulder + movement-related discomfort
↓
如果语义足够明确且符合写入授权 / 校验规则
→ 持久化相关观察，记录来源与时间
如果部位/含义不明确
→ 请求用户确认
↓
写入成功后，Body Map 更新（失败则说明未保存）
↓
用户可查看 / 更正 / 继续补充用户看到的是“系统如何处理我的信息和产生了什么结果”，而不是模型内部完整思考文本。
设计 Agent 功能时的 Interaction Spec
每一个 Agent 能力都可以写：
User Intent:
用户希望 Agent 帮他完成什么？
Agent Action:
Agent 会做哪些对用户有意义的动作？
Visible Status:
用户在每个阶段看到什么？
Tool / Side Effect:
是否调用工具？是否影响外部世界或持久数据？
Approval:
哪一步需要用户确认？为什么？
Uncertainty:
哪些结果可能不确定？怎样表达？
Evidence:
哪些地方应该展示依据？
Control:
用户能否 stop / cancel / edit / retry / correct？
Failure:
每一步失败后保留什么？
Recovery:
如何重试或恢复？
Completion:
用户怎么知道任务真的完成？Agent UX Review
- 用户是否知道 Agent 当前在做什么？
- 是否把内部“Thinking”当成了唯一状态？
- 用户是否能停止、纠正和继续？
- 不确定时 Agent 是猜，还是主动获取信息？
- Tool Call 的现实影响是否清楚？
- Approval 是否只放在真正需要的决策边界？
- 长任务是否持续有意义的反馈？
- Partial Result 是否被无理由丢弃？
- Error 后是否有恢复路径？
- AI 的事实、推断和待确认信息是否被混在一起？
- 是否展示了必要证据，而不是要求用户盲信？
- UI 是否错误地制造了“AI 很确定”的错觉？
最短记忆
传统 UX 设计任务；Agent UX 还要设计不确定性、执行过程、控制权、工具副作用、人类介入和恢复。
再压缩成一句：
Agent UX = make autonomous behavior observable, controllable, correctable and recoverable.
Digital Biome