从前端架构到 Agent 交互：状态、可观察性与工具权限

十余年企业软件研发与架构交付，让我长期面对状态同步、模块边界和故障定位。我做过 Vue、React、微前端、组件库与低代码，也参与过团队任务规划和工程规范建设。下面是将这些经验用于 Agent 交互的设计方法，不是某个已上线 Agent 平台的成绩总结。

先画状态转移，再画聊天气泡

一个任务至少要区分准备中、执行中、等待输入、完成、失败与取消。每次转移记录任务标识和事件序号，界面据此处理重连、重复事件与迟到结果。流式文字结束只能说明本次输出结束；业务完成应由执行状态确认。用户点击取消后，若工具仍在运行，页面应显示“正在取消”及已有结果，不能立即给出已经停止的承诺。

让用户与开发者看到同一项工作

用户需要知道正在检索、调用工具还是等待确认；开发者需要对应的耗时、错误和关联标识。推荐将一次任务的模型请求与工具调用组织成 trace 和 span，并用统一标识关联日志。OpenTelemetry 提供了这些可观察性概念。界面只展示可验证的阶段与结果，无需展示内部推理。记录参数时也应限制字段并脱敏，避免为了排障把敏感业务内容复制到日志里。

工具契约要覆盖输入、权限和结果

组件有属性契约，工具也应明确参数结构、目标资源、可能副作用与返回结构。接入 MCP 可以统一工具发现和调用方式，但权限判断仍需宿主与服务端落实。我的建议是将授权绑定到具体动作及资源，展示待执行的关键参数；参数或目标变化后重新判定授权是否适用。工具描述与返回内容都不能自行扩大权限，页面上的禁用按钮也不能代替后端校验。

模块边界围绕变化来源划分

前端架构中，拆分模块的价值来自独立演进；Agent 产品同样可以把会话展示、任务编排、工具适配和审计记录分开。模型供应或工具接口变化时，优先让适配层消化差异，保持任务状态协议稳定。多个 Agent 也应共享明确的结果结构、超时与交接规则。如果一个确定性步骤足够完成工作，就保留普通函数，让编排复杂度与实际收益相称。

用故障场景验收交互

推荐先验证断网重连、事件乱序、工具超时、局部成功和授权过期。尤其要区分“失败可重试”与“结果未知”：前者可能重新执行，后者需要先核对外部状态。对多步骤任务，还要明确哪些结果能保留、哪些操作需要补偿。最终验收标准是用户能否知道已经发生了什么、还能做什么，以及下一次恢复会从哪里开始。这些问题应进入交互设计与接口评审。

技术参考：OpenTelemetry 可观察性基础；MCP 工具规范。状态与权限方案为个人工程建议。