🎯 今日核心问题
- 如果每个写操作都要人点一下,Agent 的价值就没了——闸门该设在哪?
- 暂停等审批时,ReAct 循环的上下文怎么保存?进程重启了怎么办?
- 审批人看到的应该是原始参数还是模型的解释?为什么这两个都要给?
📖 精读提纲
【一】闸门设在动作前,而不是结果后
HITL 的核心决策是「在哪暂停」。设在结果之后(先生成答复再让人审)只能纠错不能防损;设在动作之前才能真正拦住不可逆操作。判断标准是三问:可逆吗?金额/影响面大吗?用户预期明确吗?三个条件里满足两个以上才需要人工,其余靠幂等和权限兜住即可。用这套标准,通常 5%-10% 的调用会进闸门,不会拖垮体验。
另一个容易忽略的点:一次审批应该覆盖一整批动作,而不是每个工具一次。比如「退款 100 元 + 发一张 20 元券 + 发送短信」是一个业务承诺,应该作为一张审批单呈现,否则审批人会被碎片化的弹窗搞到麻木,最后闭眼点通过。
【二】暂停 = 持久化状态,不是线程阻塞
最朴素的做法是 Thread.sleep 等审批,这在 Spring Boot 里是灾难:线程被占、超时后被网关掐断、重启后状态全丢。正确做法是把暂停做成状态机 + 事件驱动:Agent 执行到闸门时,把「已完成的 trace + 待执行的工具 + 参数 + 幂等键」序列化落库,状态置 WAITING_APPROVAL,然后直接返回(HTTP 202 或消息队列继续)。审批通过时再触发一次「从断点恢复」,重放 trace 并只执行被批准的动作。
恢复时必须复用同一个幂等键——因为审批和重试可能交错发生(审批通过的瞬间网络抖动导致重投),没有幂等键就会执行两次。这和 D4 是同一套基础设施,不要另写一套。
【三】审批界面要「可核验」,不是「可欣赏」
给审批人看模型写的「我准备为用户退款 100 元,因为物流延误」不够——这是模型的自我陈述,可能是幻觉。必须同时给三样东西:结构化参数(原样,不含修饰)、支撑证据(本轮相关 Observation 原文,特别是金额与状态)、模型理由(作为参考,明确标注为模型生成)。再加一个「拒绝并说明原因」的输入框,拒绝原因回流到评估集,是最便宜的训练数据来源。
审批结果要有三种,而不是两种:通过、拒绝、修改后通过(审批人直接改金额/参数)。第三种最容易被忽略但最重要——真实业务里 60% 的情况是「方向对、数字要调」,只能通过/拒绝的二元设计会逼审批人反复拒绝再让 Agent 重跑,成本高且不稳定。
【四】常见误区
- ❌ 审批超时不处理。必须定义默认动作:超时一律视为拒绝(fail-closed),不能默认通过。
- ❌ 审批链接用可猜的 id 且无有效期。审批是特权操作,链接必须带签名 token + 过期时间 + 一次性消费。
- ❌ 恢复时重新跑一遍 ReAct 循环。模型可能这次给出不同参数,导致审批内容和执行内容不一致——必须严格用审批时快照的参数执行。
- ❌ 只看审批通过率,不看「审批耗时」和「修改率」。修改率高说明前序判断不稳,需要去补校验或检索。
💻 代码示例
审批单实体 + 暂停/恢复的实现。
@Entity
@Table(name = "agent_approval")
public class ApprovalTask {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String sessionId;
private String userId;
private String toolName;
@Column(columnDefinition = "json") private String argsJson;
@Column(columnDefinition = "json") private String traceJson; // 已完成步骤
@Column(columnDefinition = "json") private String evidenceJson; // 支撑 Observation
private String idemKey;
@Enumerated(EnumType.STRING) private Status status; // PENDING/APPROVED/REJECTED/EXPIRED
private String reviewer;
private String rejectReason;
private Instant expireAt;
private Instant createdAt;
public enum Status { PENDING, APPROVED, REJECTED, EXPIRED }
}
闸门:命中策略就落库并中断,返回 202。
@Service
@RequiredArgsConstructor
public class ApprovalGate {
private final ApprovalRepository repo;
private final AgentTraceSerializer serializer;
/** @return 非 null 表示已暂停,调用方应直接返回该结果 */
public ApprovalTask maybePause(ToolSpec spec, JsonNode args, AgentTrace trace) {
if (!requiresApproval(spec, args)) return null;
ApprovalTask t = new ApprovalTask();
t.setSessionId(trace.sessionId());
t.setUserId(trace.userId());
t.setToolName(spec.name());
t.setArgsJson(args.toString());
t.setTraceJson(serializer.write(trace));
t.setEvidenceJson(serializer.writeEvidence(trace.recentObservations(3)));
t.setIdemKey(IdemKeys.of(trace, spec, args));
t.setStatus(ApprovalTask.Status.PENDING);
t.setExpireAt(Instant.now().plus(Duration.ofHours(4)));
t.setCreatedAt(Instant.now());
return repo.save(t);
}
private boolean requiresApproval(ToolSpec spec, JsonNode args) {
if (spec.risk() == Risk.HIGH) return true;
if (spec.risk() == Risk.MEDIUM) {
BigDecimal amount = args.has("amount") ? args.get("amount").decimalValue() : BigDecimal.ZERO;
return amount.compareTo(new BigDecimal("200")) >= 0;
}
return false;
}
}
恢复:严格用快照参数,走同一幂等键。
@Service
@RequiredArgsConstructor
public class ApprovalResumeService {
private final ApprovalRepository repo;
private final IdempotentExecutor idem;
private final ToolRegistry registry;
@Transactional
public void resume(Long taskId, Long reviewerId, ApprovalDecision decision) {
ApprovalTask t = repo.findById(taskId).orElseThrow();
// 乐观锁 + 状态机,防止两人同时审批
int updated = repo.updateStatus(taskId, ApprovalTask.Status.PENDING,
decision.status(), reviewerId, decision.rejectReason());
if (updated == 0) throw new ConflictException("审批单已被处理");
if (decision.status() != ApprovalTask.Status.APPROVED) {
traceStore.close(t.getSessionId(), decision.rejectReason());
return;
}
// 审批人可修改参数,但只能改白名单字段
String args = decision.patchedArgs() != null
? PatchGuard.applyWhitelist(t.getArgsJson(), decision.patchedArgs(), Set.of("amount", "reason"))
: t.getArgsJson();
String result = idem.run(t.getIdemKey(), t.getToolName(), args,
() -> registry.invoke(t.getToolName(), args));
traceStore.continueFrom(t.getSessionId(), t.getTraceJson(), result);
}
}
超时扫描(Spring @Scheduled)——超时一律 fail-closed:
@Scheduled(fixedDelay = 60_000)
public void expire() {
int n = repo.expirePending(Instant.now());
if (n > 0) log.warn("approval expired, count={}", n);
}
✏️ 今日动手
① 用 D5 的 HIGH 风险工具接上闸门,跑一笔 500 元退款,确认接口返回 202、库里出现 PENDING 记录、Agent 上下文已序列化;② 重启应用,再点通过,确认能正确恢复且只执行一次;③ 同时点两次通过,确认第二次返回 409;④ 造一个已过期的单子,确认状态变 EXPIRED 且不执行;⑤ 统计你在历史工单里预估的 HITL 触发率,超过 15% 就回去调阈值。
🔖 明日预告
本周收官:把 D1-D6 的防线串成一张上线清单,按「阻断型/告警型」分级,逐条给出验收方法。清单不全等于没上过线。