react - 示例3 - 人工介入（HITL）

在自动化 AI Agent 应用中，人工介入（Human-In-The-Loop, HITL） 是确保业务合规的最后一道防线。对于涉及大额转账、删除数据等敏感操作，系统会暂停执行并等待人类审批。

Solon AI 通过 HITLInterceptor 实现了标准化的 “拦截 - 决策 - 续传” 流程。

1、核心原理

• 声明式拦截：通过拦截器配置敏感工具。当 Agent 尝试调用这些工具时，若无审批记录，则自动中断并生成 HITLTask 快照。
• 状态保持：利用 AgentSession（如内存或 Redis）保留 Agent 的思考进度。
• 断点续传：管理员提交 HITLDecision 后，再次调用 agent.call()，Agent 会识别决策并继续完成剩余的任务。

2、示例代码

import demo.ai.llm.LlmUtil;
import org.noear.solon.annotation.*;
import org.noear.solon.ai.agent.AgentSession;
import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.agent.react.ReActResponse;
import org.noear.solon.ai.agent.react.intercept.*;
import org.noear.solon.ai.agent.session.InMemoryAgentSession;
import org.noear.solon.core.handle.Result;

import java.util.LinkedHashMap;
import java.util.Map;

@Controller
@Mapping("/ai/hitl")
public class HitlWebController {

    // 假设这是我们的 Agent 实例（实际开发中可由 Bean 注入）
    private final ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
            .defaultInterceptorAdd(new HITLInterceptor()
                    .onTool("transfer", (trace, args) -> {
                        double amount = Double.parseDouble(args.get("amount").toString());
                        return amount > 1000 ? "大额转账审批" : null;
                    }))
            .build();

    private final Map<String, AgentSession> agentSessionMap = new ConcurrentHashMap<>();

    private final AgentSession getSession(String sid) {
        return agentSessionMap.computeIfAbsent(sid, k -> InMemoryAgentSession.of(k));
    }

    /**
     * 1. 提问接口：用户输入指令
     * 如果触发转账 > 1000，Response 会返回中断状态，前端应引导至审批流
     */
    @Post
    @Mapping("ask")
    public Result ask(String sid, String prompt) throws Throwable {
        AgentSession session = getSession(sid);

        // 执行 Agent 逻辑
        ReActResponse resp = agent.prompt(prompt).session(session).call();

        if (resp.getTrace().isPending()) {
            return Result.failure("REQUIRED_APPROVAL", HITL.getPendingTask(session));
        }

        return Result.succeed(resp.getContent());
    }

    /**
     * 2. 任务查询：获取当前会话中挂起的任务详情
     */
    @Get
    @Mapping("task")
    public HITLTask getTask(String sid) {
        AgentSession session = getSession(sid);
        return HITL.getPendingTask(session);
    }

    /**
     * 3. 决策提交：管理员进行操作
     *
     * @param action:       approve / reject
     * @param modifiedArgs: 修正后的参数（可选）
     */
    @Post
    @Mapping("approve")
    public Result approve(String sid, String action, @Body Map<String, Object> modifiedArgs) throws Throwable {
        AgentSession session = getSession(sid);
        HITLTask task = HITL.getPendingTask(session);

        if (task == null) return Result.failure("没有挂起的任务");

        // 构建决策
        HITLDecision decision;
        if ("approve".equals(action)) {
            decision = HITLDecision.approve().comment("管理员已核实");
            if (modifiedArgs != null && !modifiedArgs.isEmpty()) {
                decision.modifiedArgs(modifiedArgs);
            }
        } else {
            decision = HITLDecision.reject("风险操作，已被管理员驳回");
        }

        // 提交决策
        HITL.submit(session, task.getToolName(), decision);

        // 提交后，通常自动触发一次“静默续传”，让 AI 完成后续动作
        try {
            ReActResponse resp = agent.prompt()
                    .session(session)
                    .call();

            return Result.succeed(resp.getContent());
        } catch (Exception e) {
            // 如果是拒绝产生的异常，直接返回拒绝理由
            return Result.succeed(e.getMessage());
        }
    }
}

3、交互流程解析

• 触发阶段：用户输入“给老王转账 2000 元”。Agent 解析出 transfer(amount=2000)，拦截器发现金额超限，抛出中断并保存 HITLTask。
• 审批阶段：管理员调用 approve 接口。可以根据实际情况在 modifiedArgs 中修正参数（例如将账号改为实名认证后的账号）。
• 恢复阶段：代码执行 agent.prompt(null).call()。拦截器识别到 HITLDecision，将修正参数注入，执行真实工具调用。
• 闭环阶段：Agent 拿到工具返回的 Observation，继续思考并给出最终答复：“转账已完成，这是流水号...”。