team - TeamAgen 人工介入

在多智能体协作的复杂业务场景中，我们往往不希望 AI “一口气跑到黑”。例如在起草公文、合同签署或高额退款等场景下，需要引入 人工介入（Human-in-the-Loop, HITL） 机制：AI 完成阶段性工作后挂起，由人类审批通过后再继续执行。

Solon AI 通过 TeamInterceptor（拦截器）与 FlowContext（流程上下文）的挂起恢复机制，完美支持了这一高阶需求。

1、核心设计思路

实现人工介入的核心在于 “拦截、挂起、持久化、恢复” 四个步骤：

• 拦截 (Intercept)：使用拦截器在 Agent 切换或特定节点开始前进行逻辑判断。
• 挂起 (Suspend)：通过 FlowContext.stop() 强制中止当前执行流。
• 持久化 (Persistence)：将当前的 FlowContext（包含 Trace 轨迹、变量等）序列化为 JSON 存入数据库。
• 恢复 (Resume)：人工审批后，从数据库加载 JSON 恢复上下文，并调用 teamAgent.call(null, session) 继续执行。

2、代码实现详解

第一步：定义 HITL 拦截器

拦截器的职责是检查当前状态，若符合挂起条件（如：初稿已产出且未见审批信号），则调用 ctx.stop()。

// 构建团队并注入人工介入逻辑
TeamAgent teamAgent = TeamAgent.of(chatModel)
        .name("approval_team")
        .agentAdd(ReActAgent.of(chatModel).name("worker").title("初稿撰写").build())
        .agentAdd(ReActAgent.of(chatModel).name("approver").title("修辞优化").build())
        .defaultInterceptorAdd(new TeamInterceptor() {
            @Override
            public void onNodeStart(FlowContext ctx, Node n) {
                TeamTrace trace = TeamTrace.getCurrent(ctx);
                // 逻辑：只要检测到已有阶段性产出（RecordCount > 0），且没有审批信号，则挂起
                if (trace != null && trace.getRecordCount() > 0) {
                    if (!ctx.containsKey("manager_ok")) {
                        System.out.println("[HITL] 检测到初稿已产出，挂起流程等待人工审批...");
                        ctx.stop(); // 关键：挂起流程
                    }
                }
            }
        })
        .build();

第二步：触发挂起并持久化

当流程执行到拦截点时，teamAgent.call 会立即返回，此时状态为 isStopped。

AgentSession session = InMemoryAgentSession.of("order_001");
teamAgent.call(Prompt.of("请起草一份周报内容"), session);

FlowContext context = session.getSnapshot();
if (context.isStopped()) {
    // 模拟持久化：将上下文转为 JSON 存入数据库
    String jsonState = context.toJson(); 
    saveToDb("order_001", jsonState); 
}

第三步：恢复执行

人工审批通过后，后端接收到请求，恢复上下文并注入信号。

// 1. 从数据库恢复状态并重建上下文
String jsonState = getFromDb("order_001");
FlowContext restoredContext = FlowContext.fromJson(jsonState);

// 2. 注入审批通过信号
restoredContext.put("manager_ok", true);

// 3. 恢复执行：不传 Prompt，Agent 会自动从 Trace 的断点处继续推理
AgentSession restoredSession = InMemoryAgentSession.of(restoredContext);
String finalResult = teamAgent.call(restoredSession).getContent();

3、HITL 模式的优势

真正的断点续传：TeamTrace 记录了完整的思考轨迹，恢复执行后 AI 知道之前做了什么，不会重复消耗 Token 重新开始。

状态透明：通过 context.toJson() 捕获的是整个执行图的状态，包括所有 Agent 的中间产出。

业务合规：将关键决策权交回人类，符合金融、法律等严谨行业的合规要求。

4、常用 API 参考