Agent 控制台前端设计：步骤、状态与可中断操作的工程化实践

一、为什么 Agent 需要“控制台”而不是“聊天框”

在 demo 阶段，聊天框足够；在生产阶段，聊天框会暴露三个问题：

• 任务状态不可见：卡住还是运行中，用户无法判断
• 操作不可控：缺少取消、重试、审批入口
• 问题不可复盘：失败后只有一段自然语言解释

因此，Agent 产品进入真实业务后，前端重心应从“对话展示”转到“任务控制”。

一个可运营的 Agent Console，本质是执行状态机的可视化外壳。

二、信息架构：三层视图，先控场再细看

1）任务层（Task）

展示任务整体生命周期：

• Pending / Running / WaitingApproval / Succeeded / Failed / Canceled
• 总耗时、成本、重试次数

2）步骤层（Step）

展示关键执行链路：

• 当前步骤
• 前后依赖
• 失败原因摘要

3）事件层（Event）

只在需要时展开：

• 工具调用事件
• 回执摘要
• 错误与重试记录

这三层对应三类用户需求：

• 业务用户关心任务是否完成
• 运营关心哪个步骤拖慢或失败
• 工程师关心具体事件链

三、状态机设计：别只做颜色标签

很多界面把状态机简化成“绿色成功、红色失败”，这会掩盖关键语义。

建议最小状态机包含：

• running
• waiting_user
• retrying
• partial_success
• failed_recoverable
• failed_terminal
• canceled

特别是 failed_recoverable 与 failed_terminal 必须区分：

• 前者可重试/可降级
• 后者需要人工介入或重新规划

这直接决定前端该展示 Retry 还是 Create Follow-up Task。

四、可中断操作：先定义语义，再做按钮

在 Agent 产品里，“中断”至少有三种含义：

1. Stop Streaming：停止前端流式显示（任务仍可能在执行）
2. Cancel Execution：请求后端停止后续步骤
3. Compensate / Undo：对已落地副作用做补偿

如果这三种动作混成一个“停止”按钮，会导致责任不清。

推荐交互：

• 主按钮：取消任务
• 二级入口：仅停止实时输出
• 失败后：执行补偿（仅在可补偿场景出现）

五、审计回放：为排障和面试准备“证据链”

控制台要支持“回放一次任务”，至少包括：

• 任务参数快照（脱敏）
• 步骤状态变化时间线
• 工具回执摘要
• 人工确认记录

回放不是为了炫技，而是为了回答三个核心问题：

• 为什么失败？
• 失败是否可恢复？
• 这次改动是否让下一次更稳？

可以联动阅读：

• Agent 日志不是聊天记录：事件模型怎么建，才能调试与复盘

六、前端实现建议：Event Store + 派生视图

不要把流式数据直接拼 DOM，建议采用：

• 事件入库（Pinia store）
• 按任务/步骤聚合
• UI 读取派生状态

这样能自然支持：

• 断线重连
• 回放
• 多任务并行显示
• 可观测埋点

建议埋点最少包括：

• task_cancel_clicked
• step_retry_clicked
• approval_opened
• approval_confirmed
• replay_started

七、MVP 清单：两周可落地版本

• 任务层卡片 + 关键状态
• 步骤列表 + 失败摘要
• 取消/重试/确认三类操作
• 事件回放抽屉
• 基础操作埋点

做到这一步，你的 Agent 前端就从“会聊”升级为“可运营”。

更多实践见 /articles，或在 /apps/new 体验产品流程。