Agent 调工具怎么做权限控制：白名单、审批、沙箱和日志

Agent 真正有用，往往从“能回答”变成“能操作”开始。它可以查数据库、发请求、读文件、调用内部系统、生成工单、修改配置。但工具调用一旦接上真实系统，就不能只靠一句“请谨慎操作”。正确做法是先定义工具边界，再定义参数校验、审批规则、沙箱环境、失败回滚和日志追踪。

本文是待复核草稿，正式发布前要按具体 SDK 和业务系统复核。Agent 上线流程可以看 Agent 生产部署清单，工具调用基础可以看 Agent Tool Calling 新手指南。

适合谁

适合正在做客服 Agent、运维 Agent、数据分析 Agent、销售助理、内部办公助手和自动化工作流的人。只要 Agent 能调用工具，就需要权限控制。

也适合接企业 AI 项目的开发者。客户可能更关心“能不能自动处理任务”，但你需要先解释哪些动作可以自动执行，哪些动作必须人工确认。

不适合谁

不适合让 Agent 拥有管理员权限后直接上线的人。管理员权限看起来省事，但一旦提示词理解错误、工具参数错误或用户输入诱导，就可能影响真实系统。

也不适合把所有工具暴露给同一个 Agent。查询、写入、删除、付款、通知、发布、修改权限等动作风险不同，应该拆分授权。

工具白名单

先列出 Agent 可以调用的工具，而不是让它自由发现所有能力。每个工具都要写清楚名称、用途、输入参数、输出格式、调用限制和禁止场景。

建议把工具分为只读、低影响写入、高影响写入和不可自动执行四类。只读工具可以放宽一点，删除、付款、公开发布、权限变更、批量通知等操作应默认需要人工确认。

参数校验

工具调用前要校验参数。比如查询订单时，订单号格式是否正确；发送邮件时，收件人是否在允许范围内；修改配置时，字段是否属于白名单；执行脚本时，路径是否在工作区内。

不要把参数校验完全交给模型。模型负责提出调用意图，程序负责执行边界。工具层应拒绝不合法参数，并把拒绝原因返回给 Agent。

人工审批

高影响动作应该加入审批。审批不是为了拖慢系统，而是为了把关键责任点放回人类手里。比如发送客户通知、修改生产数据、提交采购申请、删除文件、发布内容，都适合在执行前生成确认摘要。

确认摘要要写清动作、对象、影响范围、参数和回滚方式。用户点确认后再执行，而不是让 Agent 自己决定。

沙箱和最小权限

如果 Agent 需要执行代码或操作文件，优先使用沙箱环境。沙箱里只放当前任务需要的文件和命令，不给全盘文件访问，不给真实密钥，不给生产数据库写权限。

API 密钥也要最小权限。能只读就不要写入，能项目级就不要组织级，能短期令牌就不要长期密钥。工具调用日志里不要直接打印密钥。

日志和追踪

每次工具调用都应该记录：谁触发、哪个 Agent、哪个工具、输入参数摘要、输出摘要、是否审批、是否成功、耗时和错误信息。OpenAI Agents SDK 等框架提供 tracing 思路，但业务侧仍然需要自己的审计字段。

没有日志时，Agent 出错很难复盘。尤其是多步 Agent，一次失败可能来自模型、工具、权限、网络、数据或用户输入，追踪链路能减少排查时间。

常见错误

第一个错误是把工具描述写得太宽。比如“管理用户”，不如拆成“查询用户信息”“更新用户标签”“冻结用户账号”，每个工具有不同权限。

第二个错误是只在提示词里写禁止事项。提示词是软约束，工具层校验和权限系统才是硬边界。

第三个错误是没有失败策略。工具失败后 Agent 是重试、换工具、询问用户，还是停止任务，都要提前设计。

风险提醒

Agent 调工具会把模型输出变成真实动作。越接近生产系统，越需要最小权限、人工审批、审计日志和回滚方案。不要让模型直接掌握不可逆操作。

涉及客户数据、财务、权限、生产配置、公开发布和批量通知时，要提高审批等级，并保留操作记录。

具体步骤

第一步，列出所有工具并分级。第二步，给每个工具写参数 schema 和校验规则。第三步，设置只读、低影响、高影响操作的审批策略。第四步，把执行环境限制在沙箱或最小权限 API。第五步，记录工具调用日志和 trace。第六步，用测试任务验证越权和失败处理。需要权限控制模板，可以从 工具导航 下载或联系人工协助整理。

免责声明

本文只用于 Agent 工具权限设计学习，不构成安全审计或合规意见。正式上线前，应结合具体系统、权限模型和业务风险进行人工复核。