Solon v4.0.5

team - 人工介入（HITL）

</> markdown
2026年8月3日 下午5:14:49

在多智能体协作中，人工介入（Human-In-The-Loop） 的本质是“协作流”与“执行流”的深度联动。由于 TeamAgent 本身不直接调用工具，其 HITL 机制本质上是借助底层 ReActAgent 的拦截能力，结合 TeamTrace 的状态断点实现的。

更多可参考：ReActAgent 人工介入（HITL）

1、核心原理：协同拦截与断点恢复

  • 原子拦截（借力 ReAct）：

任务在团队中流转到某个 ReActAgent 时，若其试图调用敏感工具，会被 HITLInterceptor 捕捉。此时，拦截器会通过 session.pending(true, summary) 挂起当前会话，并向团队协议发出挂起信号。

  • 协作挂起（Pending）：

协作流程（如 SequentialProtocol / SupervisorTask）在每步流转前检查 session.isPending()，一旦发现挂起立即停止继续派发任务，形成“协作断点”。断点状态存放在 AgentSession 上（TeamTrace 本身不提供 isPending），而不是靠 FlowContext.stop() 这类方法。

  • 精准恢复：

当人类回填决策后，再次调用 financeTeam.prompt().session(session).call()（不传 prompt 即静默续传）。HITLInterceptor.onAgentStart 会检测到“全部待批任务均已决策”，强制把底层出纳 Agent 的路由切回 ACTION，确保团队直接在“正在握着工具”的那个 Agent 节点上原位复活，而不需要重新推理。

2、代码实现详解

  • 第一步：为执行层配置拦截器
// 1. 定义拦截器（只有 ReAct 会用到工具拦截）
HITLInterceptor hitl = new HITLInterceptor()
 .onSensitiveTool("transfer", "refund");

// 2. 配置执行层 Agent
ReActAgent cashier = ReActAgent.of(chatModel)
 .name("cashier")
 .defaultInterceptorAdd(hitl) // 拦截器挂载到具体干活的 Agent 上
 .build();

// 3. 配置管理层 Agent（编排流转）
TeamAgent financeTeam = TeamAgent.of(chatModel)
 .protocol(TeamProtocols.SEQUENTIAL)
 .agentAdd(accountant) // 会计不拦截
 .agentAdd(cashier) // 出纳负责拦截
 .build();
  • 第二步：识别团队挂起状态
AgentSession session = InMemoryAgentSession.of("sid_001");
TeamResponse resp = financeTeam.prompt("查余额并转账 3000 元").session(session).call();

 // 尽管拦截发生在 cashier 内部，但我们只需检查会话状态
 if (session.isPending()){
    // 此时会计的工作已记录在 trace 中，流程停在了出纳执行工具前
    HITLTask task = HITL.getPendingTask(session); 
    System.out.println("团队协作暂停，等待审批工具: "+task.getToolName());
}
  • 第三步：决策回填与团队唤醒
// 1. 人类提交决策（如：修改金额为 1000）
//    注意：决策主键是 callUuid，必须面向 HITLTask 提交；
//    modifiedArgs 接收 Map，而非 (key, value) 两参
HITLTask task = HITL.getPendingTask(session);
Map<String, Object> newArgs = new HashMap<>();
newArgs.put("amount", 1000);
HITL.submit(session, task, HITLDecision.approve().modifiedArgs(newArgs));

// 2. 团队原位恢复
// 拦截器在 onAgentStart 发现全部已决策后，直接让出纳 Agent 执行修正后的工具
TeamResponse respFinal = financeTeam.prompt().session(session).call();

4、协作闭环的优势

  • 精准定位断点：

由于借助了 ReAct 的拦截，断点精确发生在“工具执行前”。这意味着会计（Accountant）查余额的操作已经落库，恢复后不会重复查询，节省 Token。

  • 职责分离：

TeamAgent 负责把球传给谁，ReActAgent 负责球怎么踢。HITL 解决了“球踢到一半”需要人看一眼的问题。

  • 状态透明化：

通过 TeamTrace，人类可以追溯到是哪个 Agent 在哪一个步骤、因为哪一个参数被挂起的，提供了完整的协作链路审计。