给企业级智能体装一道「人工确认」闸门:HITL 暂停与恢复的工程实现
当 Agent 真的能写库、能发公告、能替对外渠道回消息时,问题就不再是「它答得对不对」,而是「它动手之前,谁点了头」。本文拆解 BizBuddy(纯 Java 企业级 AI 平台)里这套写操作人工确认的完整链路——包括框架级暂停、Redis 暂存、SSE 事件、恢复消息构造,以及几个踩过的坑。
一、为什么不能靠提示词约定
大多数 Agent Demo 处理写操作的思路是「在提示词里叮嘱模型:涉及写操作先问用户」。这条路在企业里走不通,原因很实在:
- 不可强制。提示词是「建议」,模型可以不听;用户一句「别问了直接发」就能绕过;
- 不是暂停点。提示词层面的「先问一句」只是模型多输出一段文本,会话并没有真正停下来,状态也没被保存;
- 不可审计。到底有没有问过?用户答了什么?数据库里查不到。
企业要的是:写操作默认必须有人点头,这个「点头」发生在链路的暂停点上,且全程留痕。
BizBuddy 的做法是直接使用 AgentScope Harness 框架原生的权限三态与 HITL(Human-in-the-Loop)暂停/恢复机制,而不是自己发明一套提示词约定。
二、先讲清楚「谁可见」,再讲「要不要确认」
禁止档的工具根本不注册进 Toolkit——模型看不到它,谈不上被诱导调用。这比「注册后运行时拒绝」安全得多,因为工具的 JSON Schema 在装配期就固定了,运行期无法绕过。
进入可见面的工具,才按「智能体 × 工具」的三档决策生成权限规则(表 ai_agent_tool.decision):
| 决策 | 值 | 行为 |
|---|---|---|
| 允许 | 0 | 直接执行 |
| 需确认 | 1 | 命中即暂停,等人工确认(HITL) |
| 禁止 | 2 | 不注册(模型不可见) |
三档的语义天然贴近企业:不是「能不能用」的布尔开关,而是「用之前要不要人点头」。档位来源有优先级——会话资源集直接选中 > 场景包内决策 > 智能体绑定决策,越显式越优先。
三、一次 HITL 的完整链路
mermaid
sequenceDiagram
participant M as 模型
participant F as AgentScope 框架
participant B as BizBuddy 后端
participant U as 用户
M->>F: 调用写工具(如 create_notice)
F->>F: 命中 ask 规则 → 暂停 Agent
F-->>B: RequireUserConfirmEvent
B->>B: 落库助手消息 + Redis 暂存待确认
B-->>U: SSE 下发 tool_confirm
U->>B: POST /ai/chat/session/{id}/confirm
B->>B: 回写权限决策日志 + 落「记住该工具」信任
B-->>F: 恢复消息(ConfirmResult + metadata.confirm_results)
F->>F: 放行 → 真正执行工具
F-->>U: 工具卡片 + 继续作答拆开看,关键节点如下。
3.1 装配期写入规则
工具类不需要手写任何确认逻辑:
java
// 工具侧只管业务,确认与否由框架按装配期写入的权限规则判定
public class CreateNoticeTool extends ToolBase { /* ... */ }确认是链路的暂停点,不是工具方法里的一个 if。
3.2 暂停:事件与留痕
框架暂停后,后端做两件事:
落库一条助手消息,前端据此渲染;专家链路用平台固定文案,避免用户看到「暂停后续写的半截回答」:
专家准备执行的操作需要你确认后才会继续,请在下方确认卡片中处置。
把待确认状态写入 Redis,键为
bizbuddy:ai:confirm:pending:{sessionId}:{messageId},带 TTL(超时后确认入口会明确提示「已过期」,避免出现无法操作的悬挂卡片)。
再通过 SSE 下发 tool_confirm 事件,前端把它渲染成一张确认卡片:
js
case 'tool_confirm': {
// 工具被配置为「需人工确认」:本轮暂停,等待用户处置后再恢复
msg.parts.push({
kind: 'confirm',
messageId: event.messageId,
toolCalls: event.toolCalls ?? [],
confirmState: 'pending'
});
finishStream();
break;
}3.3 处置:三种选择
用户在这张卡片上做选择,前端调 POST /ai/chat/session/{sessionId}/confirm:
| 选择 | 效果 |
|---|---|
| 允许本次 | 本次执行;不沉淀信任 |
| 记住该工具 | 本次执行 + 落「用户 × 智能体 × 工具」信任,之后该用户不再弹卡 |
| 拒绝 | 不执行;可填拒绝原因,原因随恢复消息回传给模型 |
同时,后端把处置结果回写权限决策日志(applyConfirm):更新该消息下 decision=ASK 的记录,写入 confirmed(批准/拒绝)与 confirmSource(ONCE / REMEMBER),拒绝时把用户填的原因一并留痕。
3.4 恢复:把「人的决定」翻译成框架能懂的消息
恢复不是「重新发一条提问」,而是构造一条带 ConfirmResult 元数据的用户消息回传给框架:
java
// 必须带回 content 与 ASKING 状态:框架恢复执行时按 ToolUseBlock.getContent() 校验入参,
// 缺失会报 argument "content" is null
ToolUseBlock block = new ToolUseBlock(call.toolCallId(), call.toolName(), call.input(),
call.content(), null, ToolCallState.ASKING);
List<PermissionRule> rules = decision.confirmed() && decision.remember()
? List.of(new PermissionRule(call.toolName(), null, PermissionBehavior.ALLOW,
AiPermissionDecisionLog.SOURCE_REMEMBER))
: null;
results.add(new ConfirmResult(decision.confirmed(), block, rules, decision.confirmed() ? null : reason));随消息还给模型一句自然语言提示:全部拒绝时是「用户拒绝了上述工具调用……请不要重复请求执行」;有确认时是「用户已确认执行上述工具调用,请继续」。
入口链路用用户会话槽位 (userId, sessionId) 恢复;专家链路必须用同一专家实例 + 同一 expertSessionId 才能续跑——这是两条链路最容易踩错的地方。
四、四个真正难写的工程细节
4.1 「记住该工具」必须按基线重建,不能叠加
装配实例是智能体级、跨用户共享的,所以用户级信任只能落在 (userId, sessionId) 槽位。更关键的是两个框架行为:
- 框架在每轮开始时都会从状态存储重载
AgentState并用其中的权限上下文重建权限引擎,因此恢复流里ConfirmResult附带的规则只对当轮有效; - 「撤销记住」(删信任行)后,必须让 ask 规则自动恢复——按管理端档位基线重建即可自然做到。
所以正确做法是:每次以「管理端档位」为基线重建槽位上下文,把已记住的工具从 ask 集合里剔除、改为 ALLOW;而不是在现有上下文上叠加。判定顺序为 deny > ask > 工具自检 > allow,留着 ask 会让「记住」失效。
4.2 DONT_ASK 对显式 ask 规则无效
无人值守链路(定时 Agent 任务、渠道接入)不能悬挂等待人工确认。直觉做法是给智能体设 PermissionMode.DONT_ASK,但实测它只降级「未命中即 ASK」的默认档,对显式 ask 规则无效——仍会触发确认事件,让任务「看似结束却没有回答」。
真正的做法是把该槽位的 ask 规则逐条改写为 deny(同时必须原样带过既有的 allow / deny 规则与工作目录,否则会丢掉管理端档位):
java
PermissionContextState.Builder builder = PermissionContextState.builder().mode(PermissionMode.DONT_ASK);
base.getWorkingDirectories().forEach(builder::addWorkingDirectory);
base.getAllowRules().forEach((tool, rules) -> rules.forEach(rule -> builder.addAllowRule(tool, rule)));
base.getDenyRules().forEach((tool, rules) -> rules.forEach(rule -> builder.addDenyRule(tool, rule)));
base.getAskRules().forEach((tool, rules) -> rules.forEach(rule -> builder.addDenyRule(tool, rule)));
agent.getDelegate().replacePermissionContext(userId, sessionId, builder.build());同一套改写被两条链路复用:无人值守链路,以及未开启「允许专家使用写工具」的专家执行(专家是纯分析型,ask 即拒绝、不悬挂)。
4.3 并发:一张卡片只能被恢复一次
用户重复点击确认、或在多个标签页同时打开恢复流,都可能导致重复执行。Redis 里用一个一次性占用键兜底:
bizbuddy:ai:confirm:claimed:{sessionId}:{messageId}claim() 用 setIfAbsent 原子占位,只有一路能进入恢复执行;本次恢复段结束即 release()——因为暂停后还要允许用户再次确认,不能长期占用。
4.4 别的装饰器不能破坏暂停语义
平台在工具结果交回框架前会过一层安全守卫(脱敏/内容审核)。但暂停结果不能被改写:
java
if (result == null || result.isSuspended() || result.getState() == ToolResultState.ERROR) {
return result; // 暂停结果原样放行,保留 agentscope_suspended 元数据
}改写暂停结果会破坏恢复段的语义,让 HITL 直接失效。
五、专家链路的「同一专家会话续跑」
当「允许专家使用写工具」打开后,专家侧也走 HITL:卡片里显示的是专家要执行的工具,用户处置后专家用 ConfirmResult 在同一专家会话继续执行,结论再交回入口智能体整合,全程落在同一条助手消息上。拒绝则专家收到 DENIED、如实说明未执行。
配套还有一个写工具短期去重装饰器:一次编排里(含确认等待、契约重试、恢复续跑),「同工具 + 同入参」的写调用在 TTL 内只真正执行一次,避免重复发布公告这类重复副作用。它只包在专家装配的写工具外层(入口是长期会话,不包,避免误伤「同一会话再执行一次同样操作」),且只登记成功结果——首次失败不登记,模型修正入参后仍可重试。
六、审计:每一次「点头」都能复盘
HITL 的价值一半在执行、一半在留痕。平台把下列记录全部落库:
| 表 | 内容 |
|---|---|
ai_permission_decision_log | 每次决策:ASK / ALLOW、匹配规则、入参、耗时;以及用户的 confirmed 与 confirmSource |
ai_tool_call_log | 工具调用的入参、出参、状态、耗时 |
ai_message | 会话消息(含暂停时落库的助手消息) |
ai_route_run / ai_trace | 编排运行与装配快照(这轮模型看到了哪些工具、用了哪个模型) |
出问题时可以精确回答:这一轮模型看到哪些工具?准备调用什么?用户确认了吗?是谁确认的?
七、已知边界(说清楚比藏起来重要)
- 跨专家暂停不续跑:一个任务内两位专家各自需要确认时,只续跑当前专家;
- 恢复段超时可能已部分执行:写操作已发出但恢复超时,平台只降级为「如实说明」,不自动回滚;
- 停不下来的幻觉:用户点「停止生成」或断开 SSE,暂停前已在跑的编排仍会跑完(与「指定专家」兜底路径同款局限)。
八、落地清单
- 禁止档不注册,可见面在装配期裁剪,而不是运行期拦截;
- 三档授权比布尔开关更贴近企业语义(允许 / 需确认 / 禁止);
- 确认是暂停点,用框架原生的暂停-恢复,而不是提示词叮嘱;
- 恢复消息必须完整(带上
content与ASKING状态),否则框架报错; - 用户级信任要按基线重建,且不能污染共享的装配实例;
- 无人值守链路把 ask 改写为 deny,别指望
DONT_ASK能兜住显式规则; - 恢复入口做一次性占用,防止重复执行;
- 写工具短期去重只登记成功结果,让失败可重试;
- 全链路留痕,否则排障无从下手。
相关仓库
- 代码仓库:https://gitee.com/zl3624/biz-buddy
- 项目:BizBuddy —— 全量开源的企业级智能体平台(MIT License)