配置工具审批流程
在智能体开发服务平台（AgentWorks）中，智能体模板中的 工具权限 用于决定工具调用是直接拒绝、自动批准，还是在执行前等待人工审批。规则在智能体运行时生效，统一管理沙箱、MCP 和其他可审批工具的调用。
工具权限只决定调用是否可以继续，不会增加工具本身的文件、网络或业务系统权限。对于必须禁止的操作，仍应使用只读凭证、工具服务授权、沙箱网络策略和最小权限账号形成第二道限制。
需要运行命令、代码或访问沙箱工作目录时，先配置沙箱模板和实例，再用本页规则约束智能体对沙箱工具的调用。
重要
新建模板时，如果不添加允许或拒绝规则、不选择默认行为，并且不启用审批描述，平台不会开启 HITL，工具调用不会因为空配置而等待人工审批。需要审批时，请至少添加一条规则、显式选择 审批 或开启 生成审批描述。
理解规则顺序和默认行为
每个工具调用按以下顺序判断：
- 先按列表顺序检查拒绝规则。第一条匹配规则生效，调用被拒绝且工具不会执行。
- 未命中拒绝规则时，按列表顺序检查允许规则。第一条匹配规则生效，调用自动通过。
- 两组规则都未命中时，使用 默认行为。
默认行为有三种选择：
| 默认行为 | 未命中规则时的结果 | 适用情况 |
|---|---|---|
| 审批 | 暂停工具执行，等待人工批准或拒绝 | 首次接入、有副作用或权限边界尚未验证的工具 |
| 拒绝 | 自动拒绝，不执行工具 | 只允许明确列入允许规则的调用 |
| 自动批准 | 直接执行工具 | 经过验证且工具本身已经限制权限的低风险范围 |
如果已有允许或拒绝规则，但没有显式选择默认行为，未命中的调用按 审批处理。只有没有规则、没有显式默认行为，并且未开启 生成审批描述 时，才不启用审批；单独开启生成审批描述也会启用 HITL。
注意
选择并保存默认行为后，无法恢复为空配置
默认行为可以保持未选择，但从下拉列表选择并保存后，无法通过页面恢复为“未选择”。需要保持空配置不启用 HITL 时，不要改动这个下拉列表；需要设置明确的策略时，先记录原值，再选择实际需要的 审批、拒绝或 自动批准，并用固定调用验证结果。
了解不会进入人工审批的内置工具
以下内置工具用于读取、运行维护或管理智能体自身状态，即使宽泛规则会匹配，也会自动通过：
- 异步子代理任务的开始、查询、更新、取消和列表工具。
- 待办列表写入工具
write_todos。 - 手动压缩工具
compact_conversation。 - Skill 重新加载工具
reload_skills。 - 文件系统功能提供的只读工具
read_file、ls、glob和grep。 - 记忆的增加、搜索、读取、更新和删除工具。
- 定时任务的创建、列表和删除工具
__infini_cron_create、__infini_cron_list、__infini_cron_delete。
不要使用一条 * 拒绝规则来承诺这些内置工具会被阻止。需要限制相关能力时，在智能体模板中关闭对应功能、移除关联能力，或者使用该能力本身的访问控制。
添加允许和拒绝规则
打开 智能体模板，创建或编辑目标模板。
找到 工具权限。
对必须阻止的调用选择 添加拒绝规则。
对可以直接执行的低风险调用选择 添加允许规则。
填写实际的 工具名称。需要限制参数值时，再填写 参数名和 匹配正则 (RE2 语法)。
选择未命中规则时的默认行为。
保存模板，然后创建测试实例；已有实例需要同步模板更新或重启后再验证。
自动批准固定的低风险调用
例如，只允许 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 规则已经得出“需要审批”后，接入方式决定由谁提交决定：
| 接入方式 | 处理方式 |
|---|---|
| 网页版对话 | 在当前等待确认区域逐项核对工具名称、待审批记录标识和参数，再从当前调用显示的操作中作出决定；同一轮有多个待审批调用时，所有调用都有决定后，智能体才会继续运行 |
| 飞书 | 由飞书审批卡片处理；还可以限制允许操作审批的用户。使用前必须先完成单项批准和拒绝验收，参见验证消息往返 |
| 当前不支持渠道内审批交互；工具进入 HITL 时会提示改用支持审批的渠道 | |
| 业务客户端 | 从 WebSocket 事件接收待处理中断，通过 HTTP 提交对应记录的审批决定；参见中断响应 |
在网页版对话中处理 HITL 审批
在待审批区域展开调用，核对工具名称、参数和可能产生的副作用，再选择 批准 或 拒绝。批准使用当前显示的参数执行工具；拒绝不会执行目标工具。无法确认参数或副作用时，应拒绝并让智能体重新准备符合要求的调用。
提交后等待界面更新，再检查工具结果。网页版对话不提供代答或修改参数后执行的按钮；不要把用户提问表单当成修改工具参数的入口。这里只处理当前会话自己的待审批调用。子代理的待审批调用在该子代理的运行里处理；飞书渠道仍按主智能体飞书会话中的审批卡片处理。
网页版对话中，任务失败或取消后，尚未完成的工具会显示为已终止，旧审批和提问卡片不能继续操作。飞书任务已结束时，也不要再回复旧卡片。需要重新尝试时，先确认外部操作是否已经发生，再发起新的任务。
注意
拒绝调用后，Trace 可能显示失败
这里的“失败”记录的是审批拒绝，不是工具执行出错，无需因此重试。
配置渠道用户的自动批准范围
使用飞书等渠道并在用户绑定中配置工具规则时，请阅读本节。仅使用网页版对话或业务客户端时，可以跳过本节。
渠道用户绑定中的工具规则只处理已经进入人工审批的调用，实际效果如下：
| 配置位置或匹配结果 | 实际处理 |
|---|---|
| 命中智能体模板拒绝规则 | 自动拒绝，不执行工具 |
| 命中渠道用户允许规则 | 自动批准原本需要人工处理的调用 |
| 命中渠道用户拒绝规则 | 不自动批准，保留人工审批 |
| 未命中渠道用户规则 | 保留人工审批 |
需要禁止某类调用时，请在智能体模板中添加拒绝规则。渠道用户拒绝规则不能代替模板拒绝规则。配置方法参见配置用户补充审批规则。
飞书渠道的人工审批人员另由渠道账号中的两份名单决定：审批人员 ID 可以处理其他人的任务，可自我审批人员 ID 只能处理自己发起的任务。两份名单都为空时，只有发起人可以操作；配置的人员全部无法识别时不会自动放行。配置和验证方法见手动创建飞书渠道账号。
区分审批与工具结果
用户工具包的 respond 中断与 HITL 审批不同。若用户工具调用先经过 HITL，批准后业务调用方仍需执行工具，再通过 HTTP 中断响应返回结果或失败。批准不能代替业务工具执行和鉴权。参见定义用户工具包。
按接入方式处理多个审批调用
网页版对话支持逐项 批准 或 拒绝，也支持 全部批准 和 全部拒绝。全部批准需要再次确认；全部拒绝直接提交，不再次确认。批量操作只处理尚未决定的记录。每项都有决定后，智能体才继续运行。
断线或刷新后，先恢复连接并选择原会话，检查待审批项和 Trace，再继续处理。出现未收到确认的提示时，不能直接认定操作失败；先核对工具结果和外部系统，避免重复执行有副作用的调用。
业务客户端按每项中断标识提交决定，并等待后续事件；具体字段和恢复边界参见中断响应。飞书使用审批卡片提供的操作；QQ 需要改用支持审批的渠道。不要用一个入口的验收结果替代另一个入口。
验证审批流程
以下步骤用于确认工具名称、参数、规则顺序和实例配置符合你的预期，不用于重新验证 AgentWorks 的拒绝实现。
按计划使用的入口分别验证：
- 使用非内置自动通过工具，确认空配置不会产生 HITL。
- 添加一条拒绝规则，发送明确匹配的请求，确认 Trace 显示调用命中拒绝规则。
- 添加一条范围较窄的允许规则，确认只有匹配工具和参数自动通过。
- 让调用不匹配任何规则，分别验证默认拒绝、审批和自动批准。
- 通过目标渠道验证人工审批和渠道用户自动批准规则；确认用户级拒绝或未匹配仍进入人工审批。
- 通过业务客户端分别验证批准和拒绝，确认后续事件及最终结果符合预期，并验证同一会话可以继续。未确认执行结果时，不要重复发送决定或原消息。
- 对用户工具包，继续验证批准后由调用方执行工具，再通过 HTTP 回传成功或失败结果。
- 在 Trace 或对应运行记录中核对工具名称、参数、审批和最终结果。
模板更新后，应同步或重启已有实例，再重新执行固定测试。生产验收方法参见通过预发布验收。