跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 08

08-03|实战:给退款流程加入人工审批

完成 Support Agent V0.8:把 Week 05 退款状态机升级为可持久暂停、授权审批、拒绝、超时与安全恢复的流程。

实战 · Human Approval · V0.8

Business Goal

Week 05 已建立退款 State 与 waiting_for_approval 边界,教学 Mock 负责产生审批事件。本课把这条边界升级成完整运营流程:创建审批任务、持久暂停、向获授权审核员展示证据、批准或拒绝、处理超时,再安全恢复原退款实例。

完成后得到 Support Agent V0.8 Human Approval。退款执行继续使用幂等 Mock,不连接生产支付。

Current Architecture

V0.5 Refund Workflow + State
  refund_requested → eligibility_checked → waiting_for_approval
  只有状态边界与 Mock approval event

V0.6 Context / Memory + V0.7 Knowledge Grounding
  提供连续任务上下文和政策证据

This Lesson Change

refund_requested
↓
eligibility_checked
↓ high risk
waiting_for_approval
↙ approved       rejected ↘
approved → execute_refund  rejected → close / escalate
↓ timeout
approval_expired → re-evaluate

图 1|暂停是持久业务状态;进程重启、跨天审批和拒绝都保留清晰下一步。

Codex Task

在 Support Agent V0.7 上完成 V0.8 refund approval。

继承:V0.5 refundId、State/Transition、idempotency;
      V0.6 trusted identity;V0.7 policy evidence。

实现:
- 高风险退款创建 approvalRequest,绑定 refundId、stateVersion、
  immutable action fingerprint、amount、reason、evidenceRefs、expiresAt。
- Workflow 持久化 waiting_for_approval 后暂停。
- Approver 必须来自可信 operator identity,并通过 role / amount scope。
- 支持 approve、reject、timeout;决定包含 actor、reason、timestamp。
- Resume 前重检审批完整性、状态版本、订单与幂等键。
- duplicate decision 返回已有结果;冲突决定显式拒绝。
- expired approval 不执行,回到重新评估或人工升级。
- 完整 Audit Record 不记录多余客户敏感正文。
- 不连接真实支付系统。

实现前报告数据结构、状态表和失败恢复策略;实现后运行测试与标准验证。

Approval Contract

{
  "approvalId": "AP-RF-9-V3",
  "refundId": "RF-9",
  "stateVersion": 3,
  "action": "execute_refund",
  "actionFingerprint": "sha256:...",
  "amount": 500,
  "evidenceRefs": ["EL-7", "POL-DE-2026-10"],
  "status": "pending",
  "expiresAt": "2026-10-19T10:00:00Z"
}

审批界面只获得审核员有权查看的动作详情和证据摘要。完整 RunState 保留在服务端可信存储,浏览器只持有不可猜测的引用。

Pause / Resume Timeline

T0Agent 提出退款;Runtime 判定高风险
T1保存 refund State 与 approvalRequest;提交事务后暂停
T2获授权审核员查看证据并 approve / reject
T3服务端写入一次性决定;发布 resume event
T4Workflow 重检 version / permission / expiry;幂等执行
T5保存 refunded 或 rejected 与 Audit Record
图 2|决定和恢复可以发生在不同进程;持久 State 才能跨越等待时间。

Test Cases

  1. 合法审核员批准:恢复后 Mock refund 只执行一次。
  2. 审核员拒绝:进入 rejected,执行 handler 从未调用。
  3. 未授权审核员提交批准:返回 forbidden,不改变 State。
  4. 审批过期:拒绝恢复,进入 approval_expired 处理路径。
  5. 同一批准重复提交:返回已有决定,不重复发布事件。
  6. 先批准后拒绝:第二个冲突决定被拒绝并审计。
  7. 等待期间订单状态变化:version / fact recheck 失败,重新评估。
  8. 审批服务响应丢失:客户端重试不会创建第二个决定。

Agent Proposal
↓
Risk + Permission Policy
↓ pause
Approval Service + Authorized Human
↓ signed decision
Workflow Resume Validator
↓
Idempotent Refund Mock + Audit

图 3|人承担决定,Runtime 验证和执行;自然语言回复不参与授权链。

Failure Lab

把 RunState 整份发到浏览器再传回来

为什么诱人: 前端保存状态,后端实现更简单。

为什么失败: 客户端可能篡改 Tool 参数、审批决定或身份字段,也扩大敏感数据暴露。

更合理设计: 完整状态保留在可信服务端;前端使用 opaque approvalId 提交决定。

批准后不检查审批是否过期

为什么诱人: 人已经点击同意,直接执行最顺畅。

为什么失败: 等待期间订单、金额或政策可能变化,旧决定不再适用。

更合理设计: Resume 时验证 expiry、stateVersion、action fingerprint 和关键事实。

重复点击批准触发两次退款

为什么诱人: 每次 HTTP 请求都独立处理,实现直接。

为什么失败: 网络重试和用户连点会产生重复副作用。

更合理设计: 决定写入与退款执行都使用稳定业务 ID 和幂等键。

Acceptance Criteria

  • ☐ 直接继承 V0.5 refundId、状态机和幂等执行,没有新建孤立 Demo。
  • ☐ waiting_for_approval 可跨进程、跨天恢复。
  • ☐ Approval 绑定不可变动作、State 版本、证据和过期时间。
  • ☐ Approver 身份、角色与金额范围由服务端验证。
  • ☐ Approve、Reject、Timeout、Duplicate 与 Unauthorized 均有测试。
  • ☐ Resume 前重检 State 和关键业务事实。
  • ☐ Audit Record 能回答谁在何时基于什么批准了什么。
  • ☐ 未连接生产支付系统,Mock 副作用保持幂等。

Architecture After This Lesson

Support Agent V0.8
  V0.5 Refund Workflow + State
    + V0.6 Trusted Context
    + V0.7 Policy Evidence
      → Risk / Permission
        → Durable Pause
          → Authorized Human Decision
            → Validated Resume → Idempotent Execution

Checkpoint 02

为查看 FAQ、查询本人订单、修改地址、取消订单、普通退款、大额退款和法律承诺分别选择:Fully Automated、Agent Assisted、Human Approval 或 Human Only,并写出责任人和失败路径。

Week 08 完成。下一周将用固定测试集、业务指标和 Trace 证明这套系统在修改前后是否仍然可靠。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 人工决定必须绑定明确动作,暂停可持久,恢复前重新验证,副作用保持幂等。当前实现方式: RunState 与 approval API 会演化,本课以应用自己的 Approval Contract 保持稳定。