知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 人机协同(Human-in-the-Loop)设计方案 > 导读:本文从"Agent 自动删了生产库、还给客户发了邮件,事后才被发现"这个典型事故出发,把风险分级决策矩阵、三类高危动作、同步/异步/预审批三种模式、审批 UX 的认知负荷控制、中断与越权、超时升级链、渐进式自主、以及与 Checkpoint 的状态集成逐项讲透,最后给出工程实践与踩坑。适合正在做 Agent 安全网关、或准备 Agent 系统设计面试的同学。 ## 一、先建立全局认知 ### Q:Human-in-the-Loop 到底要解决什么问题? A:结论先行——HITL(Human-in-the-Loop,人机协同/人在环中)的核心目标是在**保障安全的前提下最大化 Agent 自主性**:在人需要参与的关键节点让人高效介入,在人不需要参与时完全静默运行。 先纠正一个常见误解:HITL **不是"人盯机器"**,而是**精确把人的判断力嵌入 Agent 的最薄弱环节**——不确定、高风险、不可逆的时刻。 这个定义直接推导出两条设计约束: 1. 如果 HITL 变成"每个操作都要人点一下",那 Agent 的价值就被抹平了,人会变成瓶颈; 2. 如果 HITL 变成"事后审计",那第一次事故就已经造成损失了。 所以 HITL 的本质是**一套贯穿 Agent 生命周期的控制体系**,而不是一个审批弹窗功能。 ### Q:面对一个 Agent 即将执行的动作,怎么判断"要不要人介入"? A:结论先行——问三个问题:**出错后果多严重(影响面 × 不可逆程度)、Agent 对这个动作把握有多大(置信度)、是否在合规/政策红线内**;三个维度交叉形成介入决策矩阵。  *图:人工介入强度的决策矩阵:风险等级 × 置信度* ```text 风险等级 低 中 高 致命 ┌─────────┬─────────┬─────────┬─────────┐ 置信度 高 │ 自动执行 │ 自动执行 │ 建议审批 │ 强制审批 │ ├─────────┼─────────┼─────────┼─────────┤ 置信度 中 │ 自动执行 │ 建议审批 │ 强制审批 │ 强制审批 │ ├─────────┼─────────┼─────────┼─────────┤ 置信度 低 │ 自动执行 │ 强制审批 │ 强制审批 │ 直接拒绝 │ ├─────────┼─────────┼─────────┼─────────┤ 不确定 │ 建议审批 │ 强制审批 │ 直接拒绝 │ 直接拒绝 │ └─────────┴─────────┴─────────┴─────────┘ ``` 这里有一个非常关键、也最容易被忽略的设计决策:**"拒绝执行"也是一等公民**。不是所有不确定的动作都应该拿去问人——对于"低置信度 + 高风险"的组合,系统应该**直接拒绝并解释原因**,而不是把决策负担甩给人。把"要不要赌一把"这种问题丢给人类,既降低效率又转移了责任。  *图:Agent 人机协同风险与置信度决策矩阵* ### Q:具体哪些动作需要人类审批? A:结论先行——分三类:**A 破坏性操作(Destructive)、B 高价值交易(High-Value)、C 合规敏感(Compliance-Sensitive)**。 ```text A 类:破坏性操作(一旦执行无法或极难撤销) A1 数据删除:删除用户数据/数据库记录、DROP TABLE、删文件、清空缓存队列 A2 数据修改:UPDATE/INSERT 生产库、改配置中心关键配置、覆盖已有文件 A3 资源销毁:销毁云资源(K8s 集群/虚拟机/DB 实例)、删 DNS 记录、注销 SSL 证书 B 类:高价值交易(涉及资金、资源分配、对外承诺) B1 资金操作:支付/退款/转账、修改定价与折扣、签署合同 B2 资源分配:超过阈值的资源申请、长期预留资源、生产扩容 B3 对外通信:给真实客户发邮件/SMS、发布到社交媒体、公开渠道声明 C 类:合规敏感(涉及法律、隐私、安全边界) C1 数据访问:访问 PII/PHI、跨租户访问、导出用户数据 C2 权限变更:改 RBAC 角色权限、增删团队成员、开放端口/防火墙规则 C3 模型与算法:新模型版本上生产、改推理参数(温度/top_p)、变更推荐排序策略 ``` 分类的价值在于它是**声明式的**:工具在注册时就把自己归到某类,风险引擎不需要去猜。 ## 二、审批触发:风险分级与声明式工具画像 ### Q:风险等级怎么定义才能落到代码里? A:结论先行——用**四个等级 + 一组规则函数**:LOW(可逆、影响面小)、MEDIUM(可逆但有成本)、HIGH(不可逆或影响面大或涉及资金)、CRITICAL(不可逆 + 影响面极大 + 合规红线)。 ```python from enum import Enum from dataclasses import dataclass from typing import Optional class RiskLevel(Enum): LOW = "low" # 可逆,影响面小,可自主执行 MEDIUM = "medium" # 可逆但有成本,或影响面中等 HIGH = "high" # 不可逆,或影响面大,或资金相关 CRITICAL = "critical" # 不可逆 + 影响面极大 + 合规红线 class ActionCategory(Enum): DESTRUCTIVE = "destructive" HIGH_VALUE = "high_value" COMPLIANCE = "compliance" READONLY = "readonly" INTERNAL = "internal" @dataclass class RiskAssessment: action_name: str action_category: ActionCategory is_reversible: bool # 是否可撤销 impact_scope: str # single_record|multi_record|system_wide|external financial_value: Optional[float] = None involves_pii: bool = False involves_auth_change: bool = False agent_confidence: float = 1.0 # 0.0~1.0 similar_action_success_rate: float = 1.0 risk_level: RiskLevel = RiskLevel.LOW requires_approval: bool = False approval_type: str = "" # none | recommended | mandatory def __post_init__(self): self.risk_level, self.requires_approval, self.approval_type = self._compute_risk() def _compute_risk(self): # 规则 1:合规红线 → 直接最高级 if self.involves_pii or self.involves_auth_change: return RiskLevel.CRITICAL, True, "mandatory" # 规则 2:不可逆 + 资金超阈值 → CRITICAL if not self.is_reversible and self.financial_value and self.financial_value > 1000: return RiskLevel.CRITICAL, True, "mandatory" # 规则 3:不可逆 → 至少 HIGH if not self.is_reversible: if self.agent_confidence < 0.9: return RiskLevel.HIGH, True, "mandatory" return RiskLevel.HIGH, True, "recommended" # 规则 4:涉及资金 → 至少 HIGH if self.financial_value and self.financial_value > 0: if self.agent_confidence < 0.85: return RiskLevel.HIGH, True, "mandatory" return RiskLevel.HIGH, True, "recommended" # 规则 5:Agent 不确定 → 升级审批 if self.agent_confidence < 0.6: return RiskLevel.MEDIUM, True, "recommended" if self.agent_confidence < 0.8: return RiskLevel.LOW, False, "none" # 规则 6:默认放行 return RiskLevel.LOW, False, "none" ``` 关键点解读:注意这里的规则顺序——**红线类规则(PII、权限变更)排在最前面且不可被后续规则放宽**。设计上的取舍是"宁可多审,不可漏审":这类操作一旦出事,检查成本远低于事故成本。另外"置信度 < 0.8 → 不审批"这条容易被质疑,它的前提是"风险为 LOW",本质是"低风险场景不要用低置信度当成审批理由",否则 Agent 稍一犹豫就打扰人。 ### Q:工具的风险属性应该在什么时候声明? A:结论先行——**在工具注册时声明**,用声明式(而非命令式)画像描述风险,让 HITL 引擎拿到元数据就能决策。 ```python from dataclasses import dataclass @dataclass class ToolRiskProfile: # 基础分类 is_destructive: bool = False is_financial: bool = False is_compliance_sensitive: bool = False # 影响范围 max_affected_records: str = "single" # single | batch | all affects_production: bool = False affects_external_users: bool = False # 可逆性 is_reversible: bool = True rollback_instruction: str = "" # 给审批者看的"怎么回滚" # 历史表现 historical_success_rate: float = 1.0 # 审批策略覆盖 force_approval: bool = False # 某些工具永远不能自动执行 confidence_threshold_for_approval: float = 0.85 DELETE_DATABASE_TOOL_RISK = ToolRiskProfile( is_destructive=True, is_compliance_sensitive=True, max_affected_records="all", affects_production=True, is_reversible=False, rollback_instruction="无自动回滚:需从备份手动恢复,预计耗时 2~6 小时", historical_success_rate=0.998, force_approval=True, # 无论置信度多高都必须审批 confidence_threshold_for_approval=1.0, ) SEARCH_KNOWLEDGE_BASE_TOOL_RISK = ToolRiskProfile( is_destructive=False, is_compliance_sensitive=False, max_affected_records="single", affects_production=False, is_reversible=True, historical_success_rate=0.999, # 不设置 force_approval,走默认规则 ) ``` 关键点解读:`rollback_instruction` 是最有工程品味的一个字段——它把"不可回滚"这个抽象风险翻译成审批者能理解的具体代价("需从备份手动恢复,预计 2~6 小时"),直接决定了人工决策的质量。 ### Q:把所有这些规则整合起来,最终怎么得到一个"要不要审批"的答案? A:结论先行——用**四层规则引擎**:硬性规则(不可覆盖)→ 动态规则 → 渐进式自主覆盖 → 默认放行。  *图:执行前判定:什么情况自动放行,什么情况必须审批* ```text Agent 即将执行操作 │ ├─ 只读查询 ─────────────────────────────▶ ✅ 自动执行 │ └─ 写操作 ├─ 可逆?否 ─▶ 影响范围系统级 ─────▶ 🔴 强制审批 │ 影响范围批量/单条 ──▶ 看置信度 ├─ 涉及资金 > 阈值 ─────────────────▶ 🔴 强制审批 ├─ 置信度 < 0.7 ───────────────────▶ 🔴 强制审批 ├─ 置信度 0.7~0.9 且高风险领域 ─────▶ 🟠 建议审批 ├─ 涉及合规/PII ───────────────────▶ 🔴 强制审批 ├─ 历史成功率 > 99% ───────────────▶ ✅ 自动执行 ├─ 历史成功率 95%~99% ─────────────▶ 🟠 建议审批 └─ 历史成功率 < 95% ───────────────▶ 🔴 强制审批 ``` ```python class ApprovalDecisionEngine: def decide(self, tool_profile, agent_confidence, risk_assessment, domain_profile=None): """返回:(requires_approval, approval_type, reason)""" # === 规则层 1:硬性规则(不可覆盖)=== if tool_profile.force_approval: return True, "mandatory", "此工具配置为始终需要审批" if risk_assessment.risk_level == RiskLevel.CRITICAL: return True, "mandatory", "致命风险等级:必须审批" if risk_assessment.involves_pii or risk_assessment.involves_auth_change: return True, "mandatory", "涉及隐私数据或权限变更" # === 规则层 2:动态规则 === if not tool_profile.is_reversible: if agent_confidence < 0.9: return True, "mandatory", f"不可逆+低置信度({agent_confidence:.0%})" return True, "recommended", "不可逆操作,建议审批" if tool_profile.is_financial: if agent_confidence < 0.85: return True, "mandatory", f"涉及资金+低置信度({agent_confidence:.0%})" return True, "recommended", "涉及资金,建议审批" # === 规则层 3:渐进式自主覆盖 === if domain_profile and domain_profile.autonomy_level >= 4: return False, "none", f"L{domain_profile.autonomy_level}:自动放行" if domain_profile and domain_profile.autonomy_level >= 3: return False, "none", "L3:条件自主,自动放行" # === 规则层 4:默认 === if tool_profile.affects_production and tool_profile.affects_external_users: return True, "recommended", "影响生产环境和外部用户" return False, "none", "低风险,自动放行" ``` 关键点解读:注意"规则层 1 不可覆盖"这个设计——**再高的自主等级也不能推翻 CRITICAL 与红线规则**。这是分层的意义:自主等级只影响"动态规则"的松紧,不影响安全底线。 ## 三、三种审批模式 ### Q:同步、异步、预审批,怎么选? A:结论先行——**按"是否需要立即决策"和"Agent 能否并行做别的事"来选**:单个关键操作要立即决策用同步;多步骤中某一步需要审批、且其它步骤可并行用异步;Plan-and-Execute 型 Agent 用预审批。 | 维度 | 同步审批(Sync) | 异步审批(Async) | 预审批(Pre-Approval) | |---|---|---|---| | Agent 行为 | 阻塞等待,不干别的事 | 继续执行其他可并行任务 | 先出计划,人批计划再执行 | | 人的响应 | 必须实时响应 | 可以延迟响应 | 计划阶段一次性审批 | | 适用场景 | 单个关键操作、需立即决策 | 多步骤中某一步需审批 | Plan-and-Execute 类型 Agent | | 延迟容忍 | 秒级 | 分钟~小时级 | 不敏感 | | 实现复杂度 | 低 | 中 | 中 |  *图:三种审批模式* ### Q:同步审批的实现要点是什么? A:结论先行——流程是"**构建请求 → 持久化 → 写 PENDING_APPROVAL Checkpoint → 通知 → 阻塞等待(带超时)→ 落库结果 → 回主循环**",其中"先持久化再通知"的顺序不能反。 ```python async def request_sync_approval(self, agent_run_id, step, tool_name, tool_arguments, tool_description, risk_assessment, agent_thought, task_context, previous_actions, timeout_seconds=300): approval_req = ApprovalRequest( agent_run_id=agent_run_id, step=step, tool_name=tool_name, tool_arguments=tool_arguments, tool_description=tool_description, risk_level=risk_assessment.risk_level.value, risk_reason=self._build_risk_reason(risk_assessment), task_context=task_context, thought=agent_thought, previous_actions_summary=self._summarize_actions(previous_actions), created_at=datetime.now().isoformat(), timeout_at=(datetime.now().timestamp() + timeout_seconds), ) # 1. 先持久化审批请求(防止进程崩溃丢失) self._approval_store.save_request(approval_req) # 2. 写 checkpoint:标记 Agent 正在等待审批 self._checkpoint_store.save_pending_approval( agent_run_id=agent_run_id, approval_request_id=approval_req.request_id, current_step=step, pending_tool_call={"tool_name": tool_name, "arguments": tool_arguments, "status": "waiting_approval"}, ) # 3. 通知人类审批者 self._notification.send(approval_req) # 4. 阻塞等待(带超时) try: response = await self._wait_for_decision(approval_req.request_id, timeout_seconds) except asyncio.TimeoutError: response = self._handle_approval_timeout(approval_req) # 走超时策略 # 5. 记录审批结果 self._approval_store.save_response(response) return response ``` 三类审批决定:`APPROVED`(批准)、`REJECTED`(拒绝,Agent 跳过该工具并重新规划或上报用户)、`MODIFIED`(参数被人类修改后批准,用修改后的参数重新发起 tool_call)。 关键点解读:`_wait_for_decision` 示例里是"每秒轮询一次",生产环境应改为 **Redis pub/sub 或 WebSocket 推送**,否则大量并发的审批等待会打爆存储。这一点在面试里经常被追问,因为有经验的面试官会立刻意识到轮询的 QPS 问题。 ### Q:异步审批为什么重要? A:结论先行——因为**在"等人"这件事上让 Agent 干等是巨大的浪费**;异步模式让 Agent 在等待期间继续执行不依赖该审批结果的并行任务,审批结果回来后合并。  *图:T3 挂起待批,T4~T6 继续执行不阻塞* ```text Agent 任务 T3 需要审批 ├─ HITLEngine 记录 T3 = PENDING_APPROVAL,异步发送请求(不阻塞) ├─ Agent 继续执行不依赖 T3 的任务: │ T4 查询知识库 ✅ │ T5 格式化已有数据 ✅ │ T6 生成部分报告 ✅ └─ 人类几小时后批准 T3 └─ 通知 Agent:T3 结果已就绪 → 融合结果 → 继续后续步骤 ``` ```python @dataclass class AsyncApprovalHandle: """异步审批句柄——Agent 持有此句柄,后续可查询状态""" request_id: str tool_name: str state: AsyncApprovalState = AsyncApprovalState.PENDING # PENDING/APPROVED/REJECTED/TIMED_OUT response: Optional[ApprovalResponse] = None dependent_task_ids: set = field(default_factory=set) # 依赖此结果的后续任务 ``` 异步引擎的关键方法有三个:`request_async_approval`(发出后**立即返回句柄,不阻塞**)、`check_approval_status`(Agent 主动查询,非阻塞)、`wait_for_any_approval` / `wait_for_all_approvals`(等最先回来 / 等全部回来)。异步模式的超时可以显著更长(示例取 3600 秒,同步只有 300 秒),因为这个取舍是"延迟容忍度换并发度"。 ### Q:预审批适合什么场景?要注意什么? A:结论先行——适合 **Plan-and-Execute 型 Agent**:Agent 先生成完整计划,人类一次批准整份计划,之后执行途中不再中断;代价是"批准的是计划而不是实际参数",所以高风险步骤仍需保留单独审批。 ```python @dataclass class ExecutionStep: step_id: str step_description: str # 人类可读的步骤描述 tool_name: str tool_arguments: dict expected_outcome: str depends_on: list = field(default_factory=list) risk_level: str = "low" requires_separate_approval: bool = False # 即使计划批准,此步仍需单独审批 @dataclass class ExecutionPlan: plan_id: str agent_run_id: str task_summary: str steps: list overall_confidence: float approval_status: str = "pending" # pending|approved|rejected|modified ``` 审批视图要突出三类信息:整体风险等级、Agent 信心(如 `f"{confidence:.0%}"`)、以及**需要特别关注的步骤**(risk_level 为 high/critical 的步骤单独列出)。另外注意一个边界情况:计划批准后如果存在 `requires_separate_approval=True` 的步骤,状态应标记为 `approved_with_conditions`,执行到那一步时再触发同步/异步审批——**"批计划"不能等于"批了一切"**。 ## 四、审批 UX:让人类高效决策 ### Q:HITL 的最大瓶颈是什么? A:结论先行——不是技术,而是**人的认知负荷**。如果每次审批都要花 5 分钟理解上下文,HITL 就会变成瓶颈;目标是**让人类在 10 秒内做出正确决策**。 实现手段是把审批信息按优先级分成三层:  *图:审批界面要展示的三层信息* ```text ┌───────────────────────────────────────────────┐ │ Layer 1: 核心决策信息(5 秒理解) │ │ • 要做什么? │ │ • 为什么 Agent 想做这个? │ │ • 风险等级 + 风险原因 │ ├───────────────────────────────────────────────┤ │ Layer 2: 辅助判断信息(10 秒) │ │ • Agent 前几步做了什么(上下文) │ │ • 历史同类操作的结果 │ │ • 可以回滚吗?怎么回滚? │ ├───────────────────────────────────────────────┤ │ Layer 3: 详细技术信息(按需展开,默认折叠) │ │ • 完整参数 JSON │ │ • 完整 Agent Thought 链 │ │ • 受影响数据范围、类似审批案例 │ └───────────────────────────────────────────────┘ ``` 三个具体设计原则: 1. **最重要的信息在最前面**(标题就用 emoji + 一句话说清"要做什么",如"🟠 Agent 请求执行:删除生产库表"); 2. **风险用视觉符号区分**(🔴 critical / 🟠 high / 🟡 medium / 🟢 low),不要纯文字; 3. **决策按钮语义清晰**:除"✅ 批准 / ❌ 拒绝"外,高风险额外提供"✏️ 修改后批准",低风险额外提供"⏭️ 信任 Agent,本次会话不再审批此类操作"。 另外要**截断长文本**(例如 Agent thought 只展示前 300 字符)并**只抽取 2~3 个关键参数**优先展示(ID 类、数量类、名称类优先),避免人类被参数海洋淹没。  *图:审批通知信息层级* ### Q:批量审批、决策疲劳这些现实问题怎么处理? A:结论先行——四个策略:**批量审批、学习用户偏好、上下文关联展示、决策疲劳管理**。  *图:降低审批负担的四个策略* ```text 策略 1:批量审批(Batch Approval) 同一 Agent Run 中产生的多个同类低风险审批 → 合并为一张审批单 示例: 🔵 Agent 请求批量修改 5 个配置项 ├── db.max_connections: 100 → 200 ├── db.timeout: 30 → 60 ├── cache.ttl: 300 → 600 ├── api.rate_limit: 1000 → 2000 └── log.level: INFO → DEBUG → 全部批准 / 全部拒绝 / 逐项选择 策略 2:学习用户偏好(Preference Learning) 记录用户在什么条件下批准了什么类型的操作,下次自动批准同类低风险操作 策略 3:上下文关联展示 把审批放进 Agent Run 的完整时间线里,而不是孤立展示: Step 1 ✅ 搜索财报 → 找到 3 条记录 Step 2 ✅ 计算毛利率 → 毛利率 45% Step 3 ⏳ 等待审批:重新定价(🟠 高风险) ← 当前关注点 Step 4 ⏸️ 生成报告(等待 Step 3 审批通过) 策略 4:决策疲劳管理 同一审批者连续处理超过 10 个审批后 → 提示休息 或自动把部分低风险审批降级为"建议审批"(降低强制性) ``` 关键点解读:策略 4 背后是一个真实规律——**同一个人在短时间内收到 N 个审批,从第 N/2 个开始决策质量就明显下降**。所以"审批太多"不是效率问题,而是安全问题:疲劳的人会开始无脑点"批准"。工程上必须给"每小时审批数"设监控。 ## 五、中断与越权控制 ### Q:HITL 除了"审批",还要提供哪些控制能力? A:结论先行——三种干预操作:**PAUSE(暂停)、REDIRECT(重定向)、TERMINATE(终止)**,另外还有一个 ROLLBACK(回滚到之前的 Checkpoint)。 | 干预操作 | 效果 | Agent 状态变化 | |---|---|---| | PAUSE | 立即挂起当前执行,保存状态,等待进一步指令 | RUNNING → PAUSED | | REDIRECT | 注入新的指令/上下文/约束,Agent 按新指令继续执行 | 保持不变(继续执行) | | TERMINATE | 立即停止执行,清理资源,记录终止原因和最后状态 | RUNNING → TERMINATED | ### Q:干预为什么不能"直接 kill"? A:结论先行——因为 Agent 可能正在执行一个**有副作用的工具调用**,粗暴 kill 会留下脏数据(扣了钱没记账、发了半封邮件);所以 PAUSE 要等当前工具调用做完再挂起,TERMINATE 要给收尾时间并释放租约。 ```python async def _pause_agent(self, agent, cmd): """优雅暂停: 1. 标记 PAUSING(不再发起新的工具调用) 2. 等待当前正在执行的工具调用完成(不中断,避免副作用) 3. 完成后不再进入下一轮思考 → 写 checkpoint → PAUSED """ agent.set_flag("pause_requested", True) self._checkpoint_store.save_emergency( agent_run_id=cmd.agent_run_id, break_reason=f"manual_pause_by_{cmd.issued_by}", pause_reason=cmd.reason, ) self._notification.send_status_update(cmd.agent_run_id, "PAUSED", "Agent 已暂停…") async def _terminate_agent(self, agent, cmd): agent.set_flag("terminate_requested", True) try: await asyncio.wait_for(agent.wait_for_current_operation(), timeout=5.0) except asyncio.TimeoutError: agent.force_kill_current_operation() # 超时后强制终止 self._checkpoint_store.save_emergency( agent_run_id=cmd.agent_run_id, break_reason=f"terminated_by_{cmd.issued_by}", termination_reason=cmd.reason, status="TERMINATED", ) agent.release_lease() # 释放租约,避免资源泄漏 self._notification.send_status_update(cmd.agent_run_id, "TERMINATED", "Agent 已终止…") ``` REDIRECT 的实现方式不同——它不需要暂停,而是把人类指令作为**高优先级系统消息**注入当前上下文: ```python agent.inject_system_message( role="system", content=(f"[人类干预 - {cmd.issued_by}] {cmd.reason}\n\n" f"新指令:{cmd.redirect_instructions}\n\n" f"请立即按上述新指令调整你的行为。" f"之前正在执行的任务可能需要根据新指令重新评估。"), priority="high", ) ``` ### Q:干预指令应该在哪些时机被检查? A:结论先行——在 Agent 主循环里嵌入**五个干预检查点**:每轮开始、思考后行动前、每个工具调用前、工具执行完后、每轮结束,其中最关键的检查点是"思考后、行动前"。 ```python async def run(self): while self.step < self.max_step and not self.done: # ===== 检查点 1:每轮循环开始 ===== await self._check_intervention() thought = await self.think() if not thought: break # ===== 检查点 2:思考后、行动前(重定向的最佳时机)===== await self._check_intervention(check_redirect=True) tool_calls = self._extract_tool_calls(thought) for tool_call in tool_calls: # ===== 检查点 3:每个工具调用前 ===== await self._check_intervention() risk = self._assess_risk(tool_call) if risk.requires_approval: response = await self._hitl.request_sync_approval(...) if response.decision == ApprovalDecision.REJECTED: continue # 跳过此工具,处理下一个 result = await self._execute_tool(tool_call) # ===== 检查点 4:工具执行完后 ===== await self._check_intervention() self._checkpoint() # ===== 检查点 5:每轮结束 ===== await self._check_intervention() ``` 关键点解读:"思考后、行动前"是重定向的黄金时机——此时 Agent 已经想好要做什么、还没执行,人类的一句新指令可以避免一次错误动作,而不需要"先执行错的再纠正"。 ## 六、超时与升级 ### Q:人类不响应怎么办?总不能无限等。 A:结论先行——四种策略:**安全拒绝、自动升级、自动批准(仅低风险)、继续等待并通知用户**。  *图:审批超时四策略:拒绝、升级、批准、等待* ```text 审批请求发出 ├─ 人类在 T 时间内响应? → 按人类决策执行 └─ 超时 ├─ 策略1 安全拒绝:自动拒绝,Agent 跳过或报告用户 ├─ 策略2 自动升级:升级到更高权限审批者 ├─ 策略3 自动批准:仅限低风险"建议审批"自动放行 └─ 策略4 继续等待:通知 Agent 等待中,Agent 告知用户延迟 ``` ### Q:升级链怎么设计? A:结论先行——**逐级升到更高权限的角色,每级设置独立超时,链条耗尽后走兜底策略**(默认拒绝)。  *图:四级审批链逐级超时:5、10、15 分钟* ```text Level 1: 直接审批者(agent_reviewer / team_member) 超时 5 分钟 │ 未响应 ▼ Level 2: 团队 Lead / 值班人员(team_lead / oncall_primary) 超时 10 分钟 │ 未响应 ▼ Level 3: 部门负责人 / On-Call Manager(manager / oncall_manager) 超时 15 分钟 │ 未响应 ▼ Level 4: 系统自动决策(按预设策略) CRITICAL / HIGH / MEDIUM → 自动拒绝 LOW → 自动批准 ``` ```python @dataclass class EscalationLevel: level: int reviewer_roles: list # 该级别的审批者角色(可多人) timeout_seconds: int auto_decision_on_timeout: Optional[str] # None = 继续升级 @dataclass class EscalationChain: chain_id: str levels: list fallback_decision: str = "reject" # 所有级别都超时 → 拒绝 ``` 实现上用 `wait_with_escalation` 做逐级等待/逐级通知/逐级超时:每级先 `send_to_roles` 通知对应角色,再等 `timeout_seconds`;若该级配置了 `auto_decision_on_timeout` 就直接返回自动决策,否则进入下一级;全部超时则用 `fallback_decision`。 设计取舍:**高风险链的兜底是"拒绝",低风险链的兜底可以是"批准"**(示例中低风险链只有一级、超时自动批准)。这是一个很实用的分级思路——兜底方向取决于"错误的代价":误拒只是效率损失,误批可能造成实际损害。 ### Q:超时对 Agent 和用户的体验分别是什么? A:结论先行——见行为矩阵,核心是**"Agent 状态"和"用户可见信息"必须一致且可解释**。  *图:审批超时与长时间等待时的 Agent 行为与用户可见提示* ```text 场景 Agent 行为 用户可见 ───────────────────────────────────────────────────────────────────── 审批超时 + 自动拒绝 跳过该工具调用 "操作已自动取消(审批超时), 报告拒绝原因 Agent 将尝试替代方案" 审批超时 + 自动批准 放行执行 静默(Agent 继续工作) (仅低风险建议审批) 审批超时 + 升级中 Agent 保持等待 "等待审批中,预计还需 X 分钟。 通知用户当前状态 如需加速,请前往审批面板" Agent 等待超过阈值(如 10 分钟) 主动告知用户当前进度 "抱歉,我在等待一项审批(X 分钟), 您可以查看详情或取消等待" ``` 关键点解读:最后一行是最容易被漏掉的体验细节——**Agent 等待超时不应该表现为"卡住了",而应该主动向用户解释"我在等人批"**。否则用户会以为系统挂了,重复提交任务,反而把系统压垮。 ## 七、渐进式自主 ### Q:HITL 的终局是"永远需要人"吗? A:结论先行——不是。理想状态是**从"人盯机器"逐步过渡到"人信机器"**:系统随 Agent 表现提升自动减少审批频率。用 L0~L5 六级模型描述: | Level | 描述 | |---|---| | L0 | 完全手动(Human-Only):Agent 只做建议,所有操作由人执行 | | L1 | 强制审批(Mandatory Approval):Agent 可提出操作,但每个都必须人批准 | | L2 | 风险驱动审批(Risk-Based Approval):低风险自动,高风险审批——**多数系统的起始级别** | | L3 | 条件自主(Conditional Autonomy):熟悉领域/高置信度自动执行,新领域仍需审批 | | L4 | 高度自主(High Autonomy):绝大多数操作自动执行,仅极端风险仍需审批 | | L5 | 完全自主(Full Autonomy):Agent 独立决策和执行,仅事后审计 |  *图:渐进式自主等级* ### Q:升级和降级的条件怎么定? A:结论先行——**升级看长期统计(足够样本 + 高成功率 + 零回滚),降级看短期异常(一次回滚就降)**;核心原则是"信任建立慢,摧毁快"。 ```python def evaluate_autonomy_upgrade(self) -> tuple[bool, str]: """评估是否可以升级自主等级""" # 条件 1:至少执行过 50 次此领域的任务 if self.total_runs < 50: return False, f"执行次数不足({self.total_runs}/50)" # 条件 2:无人工干预率 > 95% intervention_free_rate = self.zero_intervention_runs / self.total_runs if intervention_free_rate < 0.95: return False, f"无干预率不足({intervention_free_rate:.1%}/95%)" # 条件 3:每个工具的成功率 > 98% for tool_name, perf in self.tools.items(): if perf.success_rate < 0.98: return False, f"工具 {tool_name} 成功率不足({perf.success_rate:.1%}/98%)" # 条件 4:没有产生过需要回滚的严重后果 if sum(p.caused_rollback for p in self.tools.values()) > 0: return False, "存在回滚记录" return True, "所有条件满足,可以升级" def evaluate_autonomy_downgrade(self) -> tuple[bool, str]: """降级条件比升级条件更敏感——信任建立慢,摧毁快""" if any(p.caused_rollback > 0 for p in self.tools.values()): return True, "检测到回滚事件,自动降级" recent_runs_need_intervention = self.total_runs - self.zero_intervention_runs if recent_runs_need_intervention >= 2 and self.total_runs <= 20: return True, "近期多次需要人工干预" return False, "不需要降级" ``` `ToolPerformance` 统计的字段值得记住:总调用次数、成功次数(工具返回正常且后续无回滚)、被人类拒绝次数、参数被修改次数、导致回滚次数。由这些派生出 `success_rate` 与 `human_intervention_rate`(需要人类干预的比例,越低越好)。 ### Q:自主等级如何真正影响审批决策? A:结论先行——用 `should_require_approval` 覆盖默认策略:**L2 及以下走默认规则,L3 只审批"历史不擅长或高风险"的操作,L4 只审批 CRITICAL,L5 不审批**。 ```python if profile.autonomy_level >= 4: # L4:高度自主 if risk_assessment.risk_level == RiskLevel.CRITICAL: return True, f"[L{profile.autonomy_level}] 致命风险仍需审批" return False, f"[L{profile.autonomy_level}] 高度自主,自动放行" if profile.autonomy_level >= 3: # L3:条件自主 if tool_perf and tool_perf.human_intervention_rate > 0.1: return True, f"[L3] 此工具历史人工干预率 {tool_perf.human_intervention_rate:.0%},仍需审批" if risk_assessment.risk_level in (RiskLevel.HIGH, RiskLevel.CRITICAL): return True, "[L3] 高风险仍需审批" return False, "[L3] 条件自主,自动放行" return default_requires_approval, "" # L2 及以下:默认策略 ``` 关键点解读:**历史数据不足(`total_runs < 10`)时必须回退到默认策略**,不能用少量样本推断信任等级。这是一个常见的实现陷阱:刚上线时数据稀疏,如果直接按统计结论放行,等于在没数据支撑时就把安全开关打开了。另外每次升降级都要通知管理员(`_notify_autonomy_change`),因为"Agent 权限变大了"本身就是一个需要被审计的治理事件。 ## 八、状态管理与 Checkpoint 的集成 ### Q:审批可能持续数小时,状态怎么管? A:结论先行——**用状态机描述完整生命周期,并把审批状态写进 Checkpoint**,这样崩溃后能恢复、多 Worker 能接管。  *图:人机协同:Agent 状态机与人工介入点* ```text [*] → IDLE → RUNNING → RISK_CHECK ├─ 风险 LOW ────────▶ RUNNING(自动放行) └─ 风险 HIGH/CRITICAL → PENDING_APPROVAL ├─ 批准 ─────▶ APPROVED → RUNNING ├─ 拒绝 ─────▶ REJECTED → RUNNING(跳过该操作) ├─ 超时 ─────▶ TIMED_OUT → RUNNING(按超时策略) ├─ 人类暂停 ─▶ PAUSED └─ 人类终止 ─▶ TERMINATED RUNNING → PAUSED → RUNNING(人类恢复) RUNNING → WAITING_ASYNC → RUNNING(异步审批结果回来,合并) RUNNING → COMPLETED / FAILED / TERMINATED ``` ### Q:Checkpoint 要新增哪些审批相关字段? A:结论先行——新增**审批状态、当前请求、等待起止时间、异步审批池、审批历史、升级状态、干预状态**这几组字段,并显式定义"什么样的 Checkpoint 才能被 Resume"。 ```python @dataclass class HITLEnhancedCheckpoint: # ---- 继承自基础 Checkpoint ---- checkpoint_id: str agent_run_id: str step: int messages: list tool_call_history: list status: str schema_version: str = "v2-hitl" # ---- HITL 专用字段 ---- approval_state: str = "none" # none|pending|approved|rejected|timed_out current_approval_request: Optional[dict] = None approval_started_at: Optional[str] = None approval_timeout_at: Optional[str] = None async_approval_handles: list = field(default_factory=list) approval_history: list = field(default_factory=list) # 审计 + 渐进式自主 escalation: Optional[dict] = None # {"current_level":2, ...} intervention_state: str = "none" # none|paused|redirected|terminated intervention_by: Optional[str] = None intervention_reason: Optional[str] = None def is_stable_for_resume(self) -> bool: """PENDING_APPROVAL 状态的 checkpoint 不能直接 resume,必须先解析审批结果""" return (self.approval_state in ("none", "approved", "rejected", "timed_out") and self.intervention_state not in ("terminated",)) def is_waiting_for_human(self) -> bool: return (self.approval_state == "pending" or self.intervention_state == "paused") ``` 关键点解读:`is_stable_for_resume` 是 HITL 与 Checkpoint 集成的**核心契约**——`pending` 和 `paused` 都不是可恢复起点,因为它们代表"宿主的决策还没到"。如果允许从这种状态直接续跑,就会出现"审批还没批就已经执行了"的严重漏洞。 ### Q:Resume 时怎么处理"还没批完"的审批? A:结论先行——**恢复流程先判断是否在等人类,再决定"继续执行"还是"先解析审批"**;返回值用 `continue` / `resolve_first` / `completed` 三态表达。 ```python async def resume_with_hitl(self, agent_run_id: str): """返回: (Agent实例, 下一步行动提示)""" cp = self._checkpoint_store.load_latest_stable(agent_run_id) if cp.status in ("COMPLETED", "TERMINATED"): return None, "completed" agent = Agent.restore_from_checkpoint(cp) if cp.is_waiting_for_human(): return await self._resolve_pending_human_action(agent, cp) if cp.async_approval_handles: agent = await self._reconcile_async_approvals(agent, cp) return agent, "continue" async def _resolve_pending_human_action(self, agent, cp): # 情况 A:等待审批 if cp.approval_state == "pending": response = self._approval_store.get_response(cp.current_approval_request["request_id"]) if response: self._apply_approval_response(agent, cp, response) return agent, "continue" if datetime.now().timestamp() > cp.approval_timeout_at: # 检查是否超时 response = self._hitl_engine._handle_approval_timeout(cp.current_approval_request) self._apply_approval_response(agent, cp, response) return agent, "continue" return agent, "resolve_first" # 情况 B:等待恢复 if cp.intervention_state == "paused": resume_cmd = self._intervention_handler.check_resume_command(cp.agent_run_id) if resume_cmd: agent.status = "RUNNING" cp.intervention_state = "none" return agent, "continue" return agent, "resolve_first" ``` 审批结果应用时有一个很重要的细节:**被拒绝时要向 Agent 显式注入一条系统消息说明原因**,而不是静默跳过: ```python if response.decision == ApprovalDecision.REJECTED: cp.approval_state = "rejected" agent.inject_system_message( role="system", content=(f"你请求的操作 [{cp.current_approval_request.get('tool_name')}] 被拒绝。" f"原因:{response.reason}。请调整方案。"), ) elif response.decision == ApprovalDecision.MODIFIED: cp.approval_state = "approved" cp.current_approval_request["tool_arguments"] = response.modified_arguments ``` 关键点解读:**拒绝必须带原因回灌给模型**。否则 Agent 只知道"失败了",会原样重试同一个被拒操作,形成"拒绝—重试—再拒绝"的死循环。 ## 九、工程实践与踩坑 ### Q:落地时最容易踩哪些坑? A:结论先行——六个高频坑:审批请求没持久化、PENDING 状态被直接 Resume、PAUSE 硬中断工具调用、工具没有风险画像、"批准计划"被当成"批准一切"、以及每次评测通过就放宽自主等级。 1. **审批请求必须持久化后再通知。** 顺序反了(先通知后落库)会导致"人已经批了但系统找不到请求"。 2. **PENDING_APPROVAL 的 Checkpoint 不能直接 Resume。** 必须走 `resolve_first`,先解析审批结果。 3. **PAUSE 不要中断正在执行的工具调用。** 半截中断可能留下副作用脏数据;等它做完再挂起。 4. **所有工具注册时必须声明风险画像。** 不允许无 `ToolRiskProfile` 的工具上线,否则风险引擎只能瞎猜。 5. **预审批不等于预批一切。** 高风险步骤要用 `requires_separate_approval` 单独把关。 6. **自主等级不要用少量样本推断。** 历史数据不足时回退默认策略;降级要比升级敏感得多。 ### Q:生产级约束清单有哪些? A:结论先行——见下表,这是可以直接当"上线检查表"用的。 | # | 约束 | 说明 | |---|---|---| | 1 | 所有工具注册时必须声明 `ToolRiskProfile` | 不允许无风险画像的工具上线 | | 2 | CRITICAL 风险操作必须同步审批 | 不允许对致命风险使用异步审批 | | 3 | 审批请求必须持久化 | 进程崩溃后审批请求不能丢失 | | 4 | PENDING_APPROVAL 状态的 Checkpoint 不能直接 Resume | 必须先解析审批结果 | | 5 | 审批超时必须走升级链 | 每级设置合理超时,不能无限等待 | | 6 | PAUSE 不中断正在执行的工具调用 | 避免副作用操作被半截中断 | | 7 | TERMINATE 后必须释放租约和资源 | 避免资源泄漏 | | 8 | 渐进式自主:降级条件比升级条件更敏感 | 信任建立慢,摧毁快 | | 9 | 人类干预指令必须有审计日志 | 记录谁在什么时间做了什么干预 | | 10 | 审批通知遵循 Layer 1/2/3 信息层级 | 最重要的信息在前 5 秒可理解 | | 11 | 所有审批决策记录在 `approval_history` | 用于事后审计和渐进式自主计算 | | 12 | 同一 Run 的审批不重复发送给已拒绝的人 | 避免决策疲劳和骚扰 | | 13 | 不可逆工具的 `rollback_instruction` 必须有值 | 让审批者知道后果和补救方案 | ### Q:整体架构上,HITL 应该分成哪几个模块? A:结论先行——五块:**Agent 运行时(主循环 + 风险引擎 + 决策引擎)、HITL 核心(审批引擎 + 升级引擎 + 干预处理器)、渐进式自主(等级管理器 + 表现存储)、通知层(通知服务 + 审批存储)、持久化层(Checkpoint 存储 + 信任画像存储)**。  *图:人机协同架构——审批引擎、升级引擎与通知层* ```text ┌──────────────── Agent 运行时 ────────────────┐ │ Agent 主循环(含干预检查点) │ │ → 风险评估引擎 → 审批决策引擎 │ │ │需要审批 │自动放行 │ └─────────┼────────────────────┼───────────────┘ ▼ │ ┌──── HITL 核心 ────┐ │ │ HITL 引擎 │◀── 查询信任等级 ──┐ │ (同步/异步审批) │ │ │ 升级引擎(超时逐级)│ ┌── 渐进式自主 ──┐ │ 干预处理器(暂停/ │ │ 自主等级管理器 │ │ 重定向/终止) │ │ 表现数据存储 │ └────────┬───────────┘ │ 信任画像存储 │ ▼ └────────────────┘ ┌──── 通知层 ────┐ │ 通知服务 IM/邮件│ │ 审批存储 │ └────────────────┘ ▲ ┌──── 持久化层 ──────────────────────────────┐ │ Checkpoint 存储(含 HITL 状态字段) │ └────────────────────────────────────────────┘ ``` 一个最小的端到端流程:Agent 执行任务 → 遇到需审批操作 → 写 PENDING_APPROVAL 并推送审批 → Agent 挂起(或 Worker 崩溃,另一个 Worker 接管)→ 人类批 `APPROVED` 并写回 `approval_store` → `HITLAwareResumeEngine.resume_with_hitl` 拿到 `continue` → Agent 继续执行并输出结果。 ## 小结 - HITL 的目标是"**在需要时高效参与,在不需要时完全静默**",它是控制体系而不是一个弹窗功能; - 决策逻辑是 **风险等级 × Agent 置信度 × 历史表现**,并且"拒绝执行"是一等公民; - 三种审批模式按场景选:**关键操作同步、可并行任务异步、Plan-and-Execute 预审批**; - 人类体验是硬约束:**审批通知必须 10 秒可理解**,批量审批、上下文展示、疲劳管理缺一不可; - 干预要优雅:**PAUSE 等工具调用收尾、TERMINATE 释放资源与租约**; - 超时是常态不是异常,靠**升级链 + 兜底策略**自洽; - 信任动态演进:**L0→L5,升级慢、降级快**,且自主等级不能突破安全红线; - 一切依赖 Checkpoint:审批中/等待中/已暂停的状态必须可靠持久化,否则崩溃恢复与多 Worker 接管都无从谈起。 ## 思考题 1. 如果把高风险链的"超时兜底"也设成"自动批准",会有什么后果?请从"错误的代价不对称"角度论证为什么兜底方向必须按风险分级。 2. 渐进式自主的升级条件要求"50 次运行、无干预率 95%、工具成功率 98%",这些数字如果调松调紧分别会有什么风险?你会用什么线上指标来判断参数是否合理? 3. 同步审批的等待窗口(示例 300 秒)如果设得和异步一样长会怎样?如果设得特别短又会怎样?这个参数和"Agent 单步超时"是什么关系? 4. Agent 被拒绝后你注入了"拒绝原因"的系统消息,但如果人类给的原因是"就是不行"这种无信息量的内容,Agent 大概率还是会重试。你会怎么设计拒绝原因的结构化约束? 5. 批量审批把 5 个配置修改合并成一张单子,效率是高了,但如果其中第 4 项有问题,人类的"全部批准"会不会变成风险?你会怎么在设计上限制批量审批的适用面?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入