Agent 系统设计方法

第一步：把“做一个 Agent”变成可设计的问题

先把需求改写成任务契约，而不是接受“做一个智能客服”这样的能力名词。以教学场景“协助一线工程师处理云资源告警”为例，读者要先确认使用者是谁、每天发生多少次、当前人工流程耗时在哪里、最终业务结果是恢复服务还是只给建议。频率决定容量与投资边界，业务结果决定系统应该验证什么。

第二组问题决定自主性：系统是提供证据、生成变更计划，还是可以直接执行重启和扩容。高影响、难逆转或权限广的动作默认保留审批；若收益只来自信息聚合，先做只读协助通常比授予写权限更合理。NIST AI RMF Core要求在 Map 阶段理解使用情境、影响与可行的非 AI 替代方案，这正是设计的起点。

设计稿应显式列出假设，例如“峰值每秒 20 个任务”“写操作必须由值班工程师确认”。假设不是事实，必须绑定验证方式和 Owner；无法验证又会显著改变架构的假设，应在评审前升级为阻塞问题。

第二步：确定系统类型和责任边界

默认推荐“确定性骨架包住概率性决策”。身份验证、租户隔离、业务规则、事务提交、幂等、预算和终态判定由代码与权威系统负责；模型承担自然语言理解、候选生成、证据归纳、有限集合中的 Tool 选择或计划建议。这样既保留模型处理模糊输入的价值，也不让它成为账本与权限的事实源。

纯 Workflow 适合步骤稳定、分支可枚举且错误成本高的流程。Agent 适合输入开放、需要在运行时基于观察选择下一步、且结果可以验证的环节。全 Agent 的问题是把本可编码的不变量交给概率系统；全 Workflow 的问题是分支爆炸并无法适应长尾。推荐不是二选一，而是把不确定性限制在真正需要它的位置。

第三步：走通一条端到端主链

主链从带身份的任务进入开始：API 创建不可变的任务意图与预算，Context Builder 只装配当前身份可见的信息，策略层给出可用 Tool，模型提出下一步，Runtime 执行并提交状态，UI 展示证据与审批，Verifier 查询权威系统确认结果。先让这一条链闭环，再讨论多 Agent、长期记忆或复杂路由。

这条链同时是 Trace 设计。每一段都要留下输入引用、版本、责任主体、耗时、结果和错误类别。OpenTelemetry Semantic Conventions 1.44.0提供跨 HTTP、Messaging、Database 等通用语义；GenAI 语义仍在演进，工程上需要固定约定版本，并用内部业务字段补充任务终态。

第四步：把模糊交互变成状态与契约

Run 表示一次业务任务，Step 表示有明确输入与输出的逻辑动作，Attempt 表示一次可重试执行。Run 至少区分运行、等待审批、待对账、已取消、成功与明确失败；不能把进程退出、HTTP 200 或模型说“完成”当作业务终态。

// 教学用简化契约，省略存储与鉴权实现
type RunState =
  | 'running' | 'waiting_approval' | 'reconciling'
  | 'succeeded' | 'failed' | 'cancelled';

type ToolCommand = {
  runId: string;
  idempotencyKey: string;
  toolVersion: string;
  expectedResourceVersion?: string;
  input: unknown;
};

Tool、Model、Event 与 Artifact 都要有版本化 Schema。写操作绑定幂等键和资源版本，审批绑定即将执行的参数摘要，Artifact 保存可审查的大对象，事件只承载状态变化与引用。并发更新使用乐观锁或条件写；恢复时从已提交状态继续，而不是重放整段自然语言对话。

第五步：沿主链注入失败

失败分析从“最后一个可信状态”开始。为每个边界写清检测信号、立即处置、恢复路径和验证证据。仅列“超时、重试、降级”不够，因为重试本身可能重复副作用，降级也可能违反业务正确性。

模型失败

模型失败分为服务不可用与行为不符合任务。两者的恢复策略不同：前者可以在总 Deadline 内有限重试或切换兼容 Provider，后者需要结构校验、能力约束、证据核验或人工接管，不能用更多相同重试掩盖。

可用性

超时、限流和流中断必须共享剩余时间与 Token 预算。Fallback 只有在输入输出契约、工具能力和安全策略兼容时才安全；预算耗尽时返回明确的可恢复状态，不能静默截断后继续执行写操作。

行为

拒答、结构错误、错误 Tool 或虚假的完成声明都属于行为失败。Schema 校验只证明形状正确，业务校验还要检查事实、权限、参数范围和后置条件。错误样本进入对应切片的 Eval，而不是只修改 Prompt 后凭肉眼判断。

Tool 失败

Tool 失败的关键不是错误码，而是外部世界是否已经改变。调用前记录意图与幂等键，调用后保存权威回执；响应丢失时进入待对账，禁止模型凭猜测继续。

调用

参数错误是契约或决策问题，不应重试；限流和暂时故障可以在 Deadline 内按退避策略重试；鉴权失败应停止并审计。每次 Attempt 都关联同一 Step，防止观测系统把重试当作多个独立动作。

副作用

重复、未知结果和部分成功需要对账、补偿或人工接管。补偿不是数据库回滚的同义词，它是新的显式业务动作，同样可能失败。不可逆操作应在执行前缩小影响面、预览差异并提高审批等级。

第六步：把 NFR 落到机制

非功能需求（Non-Functional Requirements，NFR）要翻译成机制和证据。成功率拆成业务终态、未知结果和人工接管；延迟拆成排队、模型首 Token、Tool 与审批；容量设计包含并发上限、队列、背压和每租户配额；成本以“每个验证成功任务”而不是每次调用计算。

安全部分从数据流与信任边界开始，列出身份传播、最小 Tool、Sandbox、敏感数据处理、审计和紧急停机。NIST AI 600-1 GenAI Profile强调贯穿生命周期的治理、测量与管理；Threat Model、Eval、Trace、发布门禁、SLO 和 Runbook 因而应在设计阶段出现，而不是上线前补文档。

第七步：按成熟度演进

第一阶段只读 PoC 证明问题值得解决；第二阶段受控 Pilot 加入小范围身份、真实 Tool、审批和评测；第三阶段生产单 Agent 补齐状态、SLO、Runbook 与安全响应；只有多个团队出现可复用需求时，再沉淀 Gateway、Tool Registry、Trace 与 Golden Path。

增加多 Agent、自适应路由或长期自治必须由瓶颈证据触发。每阶段保留 Provider Adapter、数据导出、回滚与停用路径。若 Pilot 无法在质量、时延、成本或采用上优于非 Agent 基线，正确决定可能是缩小范围或退出，而不是继续堆复杂度。

第八步：让设计可评审

评审材料先给推荐与决策摘要，再给主链、信任边界和最难状态，最后给替代方案、Failure、验证计划、Owner 与阶段门禁。架构图只承担关系，ADR 记录为什么选择与何时重审，风险登记表记录残余风险，不把所有信息塞进一张图。

限时练习可以用 45 分钟完成：10 分钟澄清，10 分钟边界与主链，10 分钟状态和最危险失败，10 分钟 NFR 与演进，5 分钟自我反驳。交付物必须明确是设计练习，任何容量数字都是待压测假设，不包装成生产成绩。