🎯 今日核心问题

  1. 如果每个写操作都要人点一下,Agent 的价值就没了——闸门该设在哪?
  2. 暂停等审批时,ReAct 循环的上下文怎么保存?进程重启了怎么办?
  3. 审批人看到的应该是原始参数还是模型的解释?为什么这两个都要给?

📖 精读提纲

【一】闸门设在动作前,而不是结果后

HITL 的核心决策是「在哪暂停」。设在结果之后(先生成答复再让人审)只能纠错不能防损;设在动作之前才能真正拦住不可逆操作。判断标准是三问:可逆吗?金额/影响面大吗?用户预期明确吗?三个条件里满足两个以上才需要人工,其余靠幂等和权限兜住即可。用这套标准,通常 5%-10% 的调用会进闸门,不会拖垮体验。

另一个容易忽略的点:一次审批应该覆盖一整批动作,而不是每个工具一次。比如「退款 100 元 + 发一张 20 元券 + 发送短信」是一个业务承诺,应该作为一张审批单呈现,否则审批人会被碎片化的弹窗搞到麻木,最后闭眼点通过。

【二】暂停 = 持久化状态,不是线程阻塞

最朴素的做法是 Thread.sleep 等审批,这在 Spring Boot 里是灾难:线程被占、超时后被网关掐断、重启后状态全丢。正确做法是把暂停做成状态机 + 事件驱动:Agent 执行到闸门时,把「已完成的 trace + 待执行的工具 + 参数 + 幂等键」序列化落库,状态置 WAITING_APPROVAL,然后直接返回(HTTP 202 或消息队列继续)。审批通过时再触发一次「从断点恢复」,重放 trace 并只执行被批准的动作。

恢复时必须复用同一个幂等键——因为审批和重试可能交错发生(审批通过的瞬间网络抖动导致重投),没有幂等键就会执行两次。这和 D4 是同一套基础设施,不要另写一套。

【三】审批界面要「可核验」,不是「可欣赏」

给审批人看模型写的「我准备为用户退款 100 元,因为物流延误」不够——这是模型的自我陈述,可能是幻觉。必须同时给三样东西:结构化参数(原样,不含修饰)、支撑证据(本轮相关 Observation 原文,特别是金额与状态)、模型理由(作为参考,明确标注为模型生成)。再加一个「拒绝并说明原因」的输入框,拒绝原因回流到评估集,是最便宜的训练数据来源。

审批结果要有三种,而不是两种:通过、拒绝、修改后通过(审批人直接改金额/参数)。第三种最容易被忽略但最重要——真实业务里 60% 的情况是「方向对、数字要调」,只能通过/拒绝的二元设计会逼审批人反复拒绝再让 Agent 重跑,成本高且不稳定。

【四】常见误区

💻 代码示例

审批单实体 + 暂停/恢复的实现。

@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 的防线串成一张上线清单,按「阻断型/告警型」分级,逐条给出验收方法。清单不全等于没上过线。