配置工具审批流程

智能体模板中的 工具权限 用于决定工具调用是直接拒绝、自动批准，还是在执行前等待人工审批。规则在智能体运行时生效，不再依赖沙箱模板或沙箱实例中的审批开关。

工具权限只决定调用是否可以继续，不会增加工具本身的文件、网络或业务系统权限。对于必须禁止的操作，仍应使用只读凭证、工具服务授权、沙箱网络策略和最小权限账号形成第二道限制。

需要运行命令、代码或访问沙箱工作目录时，先配置沙箱模板和实例，再用本页规则约束智能体对沙箱工具的调用。

重要

新建模板时，如果不添加允许或拒绝规则、不选择默认行为，并且不启用审批描述，平台不会开启 HITL，工具调用不会因为空配置而等待人工审批。需要审批时，请至少添加一条规则、显式选择 审批 或开启 生成审批描述。

理解规则顺序和默认行为

每个工具调用按以下顺序判断：

1. 先按列表顺序检查拒绝规则。第一条匹配规则生效，调用被拒绝且工具不会执行。
2. 未命中拒绝规则时，按列表顺序检查允许规则。第一条匹配规则生效，调用自动通过。
3. 两组规则都未命中时，使用 默认行为。

默认行为有三种选择：

默认行为	未命中规则时的结果	适用情况
审批	暂停工具执行，等待人工批准或拒绝	首次接入、有副作用或权限边界尚未验证的工具
拒绝	自动拒绝，不执行工具	只允许明确列入允许规则的调用
自动批准	直接执行工具	经过验证且工具本身已经限制权限的低风险范围

如果已有允许或拒绝规则，但没有显式选择默认行为，未命中的调用按 审批处理。如果没有规则，也没有显式默认行为，则不启用审批。

注意

修改旧模板前记录默认行为

旧模板可能仍处于“未选择默认行为”的空配置。第一次从下拉列表选择并保存后，页面不再提供恢复为“未选择”的选项。需要继续保持空配置不启用 HITL 时，不要改动这个下拉列表；需要改成显式策略时，先记录原值，再选择实际需要的 审批、拒绝或 自动批准，并用固定调用验证结果。

图表预览

了解不会进入人工审批的内置工具

以下内置工具用于读取、运行维护或管理智能体自身状态，即使宽泛规则会匹配，也会自动通过：

• 异步子代理任务的开始、查询、更新、取消和列表工具。
• 待办列表写入工具 write_todos。
• 手动压缩工具 compact_conversation。
• Skill 重新加载工具 reload_skills。
• 文件系统功能提供的只读工具 read_file、ls、glob 和 grep。
• 记忆的增加、搜索、读取、更新和删除工具。

不要使用一条 * 拒绝规则来承诺这些内置工具会被阻止。需要限制相关能力时，在智能体模板中关闭对应功能、移除关联能力，或者使用该能力本身的访问控制。

添加允许和拒绝规则

1. 打开 智能体模板，创建或编辑目标模板。
2. 找到 工具权限。
3. 对必须阻止的调用选择 添加拒绝规则。
4. 对可以直接执行的低风险调用选择 添加允许规则。
5. 填写实际的 工具名称。需要限制参数值时，再填写 参数名和 匹配正则 (RE2 语法)。
6. 选择未命中规则时的默认行为。
7. 保存模板，然后创建测试实例；已有实例需要同步模板更新或重启后再验证。

自动批准固定的低风险调用

例如，只允许 exec 自动执行 ls 或 pwd：

• 规则类型：允许
• 工具名称：exec
• 参数名：command
• 匹配正则：^(ls|pwd)( |$)

把默认行为设为 审批后，cat、rm 或其他未匹配命令仍会等待人工决定。不要使用 * 和空参数条件把尚未验证的调用全部放行。

自动拒绝高风险调用

例如，拒绝以 rm 开头的命令：

• 规则类型：拒绝
• 工具名称：exec
• 参数名：command
• 匹配正则：^rm( |$)

测试时应确认工具没有执行，也没有删除文件或产生其他外部副作用。如果拒绝规则和允许规则同时匹配，拒绝规则生效。

找到工具名称和参数名

• 工具名称是模型实际调用的名称，不是插件、模板、实例或工具包的显示名称。
• 参数名来自输入 schema 的顶层 properties，名称区分大小写。
• 匹配正则 (RE2 语法)由你根据允许或限制的参数值编写。

工具来源	查找工具名称和参数的方法
MCP	在 MCP 实例的工具列表中复制工具名称，并展开输入 schema 查看顶层参数
沙箱	在沙箱实例详情中加载工具列表；参数不明确时先保留人工审批，再用低风险测试和 Trace 核对
平台工具包	根据工具说明或 Trace 核对实际可调用名称；工具包显示名称不一定等于工具名称
用户工具包	使用定义中的 name 和 inputSchema.properties；审批通过后，调用方仍需执行工具并返回结果

以下定义表示工具名称为 exec，顶层参数名为 command：

{
  "name": "exec",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": { "type": "string" }
    }
  }
}

填写匹配条件

字段	填写方法	留空或特殊值的含义
工具名称	使用区分大小写的可调用名称，例如 exec	* 匹配所有非内置自动通过工具
参数名	使用输入 schema 顶层字段，例如 command	留空表示不按参数过滤
匹配正则 (RE2 语法)	编写与参数值匹配的 RE2 表达式	留空表示工具名称匹配后无条件生效

只有同时填写参数名和匹配正则时，规则才会按参数值缩小范围。需要判断嵌套对象或数组时，不要猜测点号路径；应保留人工审批，或把需要判断的值设计为工具输入的顶层参数。

生成审批描述

开启 生成审批描述后，平台会在需要人工审批时尝试生成一句操作意图说明。描述生成失败或超时不会改变审批规则，也不会自动批准调用。

生成内容只用于帮助审批人理解，不是权限判断结果。审批人仍需核对工具名称、参数、当前用户和可能的副作用。开启该选项本身会启用 HITL；如果没有规则和显式默认行为，未命中调用按 审批处理。

根据接入方式处理人工审批

Agent 规则已经得出“需要审批”后，接入方式决定由谁提交决定：

接入方式	处理方式
Playground	在当前等待确认区域逐项核对工具名称、待审批记录标识和参数，再从当前调用显示的操作中作出决定；同一轮有多个待审批调用时，所有调用都有决定后，智能体才会继续运行
飞书	由飞书审批卡片处理；还可以限制允许操作审批的用户。使用前必须先完成单项批准和拒绝验收，参见验证消息往返
QQ	当前不支持渠道内审批交互；工具进入 HITL 时会提示改用支持审批的渠道
WebSocket	客户端接收 hitl 中断，并提交 APPROVE 或 REJECT
Direct Invoke	调用方读取 pending_interrupt.type=hitl，使用同一个 session_id 和中断 ID 提交 APPROVE 或 REJECT

在 Playground 中处理 HITL 审批

打开待审批调用后，先核对工具名称、调用参数和可能产生的副作用。Meta 信息用于标识和排查本次调用，通常不需要审批人处理。

操作	结果
拒绝	不执行目标工具；可以在消息框中填写拒绝原因
代答	不执行目标工具；将消息框中的内容作为工具结果返回给智能体
修改执行	使用编辑后的 JSON 调用参数执行目标工具；选择前重新核对完整参数
允许	使用当前显示的原始参数执行目标工具

弹窗只显示当前调用支持的操作，因此不一定同时出现四个按钮。上述操作仅说明 Playground 中的 HITL 审批；Direct Invoke、WebSocket 和渠道接入仍应使用本节表格中各自支持的审批操作。

注意

先确认结果或参数

代答会让智能体把人工填写的内容当作工具结果继续处理；修改执行会真正使用修改后的参数调用工具。无法确认内容、参数或副作用时，应选择 拒绝。

配置渠道用户的自动批准范围

使用飞书等渠道并在用户绑定中配置工具规则时，请阅读本节。仅使用 Playground、WebSocket 或 Direct Invoke 时，可以跳过本节。

渠道用户绑定中的工具规则只处理已经进入人工审批的调用，实际效果如下：

配置位置或匹配结果	实际处理
命中智能体模板拒绝规则	自动拒绝，不执行工具
命中渠道用户允许规则	自动批准原本需要人工处理的调用
命中渠道用户拒绝规则	不自动批准，保留人工审批
未命中渠道用户规则	保留人工审批

需要禁止某类调用时，请在智能体模板中添加拒绝规则。渠道用户拒绝规则不能代替模板拒绝规则。配置方法参见配置用户补充审批规则。

理解 Playground 中的拒绝结果

如果使用 Playground 处理人工审批，请按下面的方式解读拒绝结果。

选择拒绝后，智能体开发服务平台（AgentWorks）不会调用目标工具。运行时会把拒绝决定作为 error 状态的工具结果交给智能体，因此界面或 Trace 可能将该工具显示为失败。这里的失败记录的是拒绝结果，不表示工具已经执行后发生错误。智能体仍可能根据对话中的已有信息继续回答，收到回复也不表示工具已经执行。

区分审批与工具结果

用户工具包的 respond 中断与 HITL 审批不同。若用户工具调用先经过 HITL，批准后业务调用方仍需执行工具，并用 RESPOND 返回结果或用 ERROR 返回失败。批准不能代替业务工具执行和鉴权。参见定义用户工具包。

按接入方式处理多个审批调用

在 Playground 中，如果同一轮显示多个待审批工具调用，请逐项核对工具名称、待审批记录标识和参数，再分别选择每项显示的可用操作。例如，可以全部批准、全部拒绝，也可以批准其中一项并拒绝另一项。Playground 会保留尚未决定的调用，并在每一项都有决定后继续运行。

Playground 短暂断线或浏览器刷新后，等待连接恢复，重新打开 Playground 并选择原会话。确认原有待审批项仍然显示后再继续决定；不要重新发送原提示词。

各入口按以下方式处理多项审批：Playground 逐项提交决定；飞书使用审批卡片提供的批量动作；QQ 改用支持审批的渠道。Direct Invoke 或 WebSocket 返回多项待审批调用时，当前接口无法保证每项决定都被保留，也未规定断线或重复提交后的处理方式，请按下面的步骤暂停处理。

如果 Direct Invoke 或 WebSocket 的中断数据出现多个 tool_calls：

1. 暂不批准、拒绝或重新提交有副作用的调用。
2. 保存原始负载、会话或消息上下文和任务状态。
3. 停止处理并联系平台支持。
4. 调整提示词或工具设计，让需要审批的调用按顺序发生。

公共 API 只支持 APPROVE、REJECT、RESPOND 和 ERROR。不要发送或依赖 EDIT。

验证审批流程

以下步骤用于确认工具名称、参数、规则顺序和实例配置符合你的预期，不用于重新验证 AgentWorks 的拒绝实现。

按计划使用的入口分别验证：

1. 使用非内置自动通过工具，确认空配置不会产生 HITL。
2. 添加一条拒绝规则，发送明确匹配的请求，确认 Trace 显示调用命中拒绝规则。
3. 添加一条范围较窄的允许规则，确认只有匹配工具和参数自动通过。
4. 让调用不匹配任何规则，分别验证默认拒绝、审批和自动批准。
5. 通过目标渠道验证人工审批和渠道用户自动批准规则；确认用户级拒绝或未匹配仍进入人工审批。
6. 使用 Direct Invoke 时，分别验证 APPROVE 和 REJECT，并确认同一会话可以继续。使用 WebSocket 时，在两个无副作用的单项调用中分别验证这两个决定；两次运行都返回 done: true 后，才通过审批验收。未收到终止帧时，不要重复发送决定或原消息，按 WebSocket 中断恢复步骤停止处理。
7. 对用户工具包，继续验证批准后的 RESPOND 或 ERROR 回传。
8. 在 Trace 或对应运行记录中核对工具名称、参数、审批和最终结果。

模板更新后，应同步或重启已有实例，再重新执行固定测试。生产验收方法参见验证智能体实例。