无耳 Solon (OpenSolon) | react - ReActAgent 人工介入（HITL）

在自动化程度极高的 AI Agent 应用中，人工介入（Human-In-The-Loop, HITL）是确保业务安全、合规的最后一道防线。对于涉及资金退款、删除数据或发送重要邮件等敏感操作，我们不希望 Agent “擅作主张”，而是需要在执行前获得人类的明确许可。

Solon AI 的 ReActAgent 基于底层的 FlowEngine 设计，提供了两种优雅的人工介入方式：拦截器模式与自定义任务节点模式。

1、为什么需要人工介入？

当 Agent 拥有了调用工具（Action）的能力，它就像是一个拥有权限的员工。但在以下场景，我们必须引入“审批”流程：

高价值操作：如执行退款、转账、大额采购。
不可逆行为：如物理删除数据库记录、注销账户。
高风险沟通：向大客户发送正式合同或答复。

2、核心原理：中断与延续

如何中断？

人工介入的核心在于利用 FlowContext 的挂起机制。当流程调用 ctx.stop() 时，当前的执行状态（包括推理进度、工具调用参数、变量等）会被完整保留在 AgentSession 中。此时，由于流程处于停止状态，后续的模型调用或工具执行将被阻断。

如何恢复？

无论何种 Agent，恢复逻辑均遵循 agent.call(session)。即在恢复执行时，不传递提示词（Prompt）。Agent 会自动识别 session 中的执行轨迹（Trace），从上次中断的节点处“断点续传”。

3、方式一：拦截器模式中断（轻量、灵活）

拦截器模式通过实现 ReActInterceptor，在 Agent 运行的特定生命周期点（如工具执行前后）进行“切面”控制。

核心逻辑：

监听节点：在 onNodeEnd 回调中监听工具执行节点（ReActAgent.ID_ACTION）。
检查信号：从 FlowContext 中检查是否存在人工批准信号（如 is_approved）。
执行中断：若无信号，调用 ctx.stop() 中断当前执行流。

代码实现要点：

ReActInterceptor hitlInterceptor = new ReActInterceptor() {
    @Override
    public void onNodeEnd(FlowContext ctx, Node node) {
        // 只有进入工具执行环节，才进行审批检查
        if (ReActAgent.ID_ACTION.equals(node.getId())) {
            if (ctx.getAs("is_approved") == null) {
                System.out.println("[系统] 敏感操作拦截：等待人工审批...");
                ctx.stop(); // 关键：中断流程，状态保留在 session 中
            }
        }
    }
};

4、方式二：自定义任务节点模式中断（规范、解耦）

如果你希望将“人工审核”作为流程图中一个标准且显式的环节，可以使用 graphAdjuster 修改执行图，在执行工具之前/之后插入自定义任务逻辑。

核心逻辑：

定义任务：实现 TaskComponent 接口，编写审核逻辑。
调整图结构：通过 graphAdjuster 将自定义任务替换掉原有的占位节点（如 ID_ACTION_AFT）。

代码实现要点：

ReActAgent agent = ReActAgent.of(chatModel)
        .defaultToolAdd(new RefundTools())
        .graphAdjuster(spec -> {
            // 在 Action 之前的切入点插入人工审核任务
            spec.getNode(ReActAgent.ID_ACTION_AFT).task(new HumanAuditTask());
        })
        .build();

static class HumanAuditTask implements TaskComponent {
    @Override
    public void run(FlowContext ctx, Node node) throws Throwable {
        if (ctx.getAs("is_approved") == null) {
            ctx.stop(); // 逻辑同上，中断等待
        }
    }
}

5. 业务落地流程：中断与恢复

无论是哪种方式，人工介入的业务闭环通常分为三个阶段：

阶段一：初次触发与状态持久化

用户发起请求（如“帮我退款”），Agent 解析意图并准备调用退款工具。此时拦截器触发 ctx.stop()。由于使用了 AgentSession（如 InMemoryAgentSession 或 RedisAgentSession），当前的思考进度、工具参数都被完整保留。

阶段二：人工审批

后台管理系统通过 UI 提醒审核员。审核员点击“批准”后，程序向该 Session 的 FlowContext 中注入批准标志：

// 恢复上下文并注入信号
session.getSnapshot().put("is_approved", true);

阶段三：恢复执行

再次调用 Agent 时，传入相同的 session。Agent 会识别到之前未完成的状态，并从中断的节点继续运行。此时审核逻辑检测到 is_approved 为 true，顺利通过，完成退款。

6、总结（两种方式的区别）

特性	拦截器模式	自定义任务模式
耦合度	较低，作为扩展组件注入	较高，直接修改执行图逻辑
控制粒度	极细，可以控制任意生命周期点	较粗，基于节点粒度控制
适用场景	通用的安全策略（如全局操作审计）	业务强相关的审批流（如特定的财务审批）

Solon AI 的这一设计，让 Agent 既能拥有 ReAct 的高效推理能力，又能像传统业务流程一样被严密监管，真正实现了“自主但不失控”。

Solon v3.9.0