为什么Agent工具权限设计决定生死？agents-best-practices风险分级与审批门禁实战

为什么Agent工具权限设计决定生死？agents-best-practices风险分级与审批门禁实战

【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practices

AI Agent 能不能"活"下来，往往不取决于模型多聪明，而取决于Agent 工具权限设计是否到位。本文基于开源项目agents-best-practices（一个面向 Codex、Claude Code 等运行时、供应商中立的 Agent 架构技能包），用尽量少的代码，讲清楚风险分级（Risk Taxonomy）与审批门禁（Approval Gate）的实战方法，帮助新手搭建一个"敢放手、但收得住"的 AI Agent。

一、权限设计是 Agent 的生死线 🚨

agents-best-practices 的核心哲学只有一句话：

模型提议动作，Harness（运行时外壳）负责校验、授权、执行、记录和返回观测结果。

这意味着：模型永远不直接"动手"。它提出工具调用，是应用代码在背后做权限判定。风险就藏在这里——如果你把execute_anything、send_message、write_database这类宽泛工具直接暴露给模型，等于把方向盘交给了一个会"被网页内容影响"的司机。一次提示注入、一段恶意检索结果，就可能变成真实的外部操作。

项目把这件事称为harness discipline（外壳纪律）：循环保持简单，运行时保持严格。

二、风险分级：给每个工具贴"标签" 🏷️

1. 工具即契约

在 references/tools-and-permissions.md 中，每个工具被定义为模型与 Harness 之间的契约，至少应声明：用途、输入/输出结构、风险等级（risk class）、副作用类别、资源范围、权限策略、超时、结果大小上限与审计策略。

原则是：避免宽泛工具，优先窄而带领域语义的工具。

2. 十四级风险分类表

风险分级章节（Risk taxonomy） 给出了 14 个风险等级，建议为每一个工具指定其中一档：

工具注册表要把这些风险元数据暴露给权限引擎——这是后面一切门禁的基础。

3. 权限决策不是"允许/拒绝"二选一

权限决策对象（Permission decision object） 定义了 7 种决策结果，比简单的 allow/deny 精细得多：

allow（放行）｜deny（拒绝）｜ask_user（问用户）｜approval_required（走审批）｜require_stronger_auth（要求更强认证）｜run_in_sandbox（沙箱内执行）｜run_as_draft_only（降级为草稿）

并且每次决策都要留痕：工具名、参数哈希、风险等级、资源范围、决策、命中的策略规则、审批人、时间戳。可审计，才能谈得上安全。

三、审批门禁：草稿与提交必须分离 🔒

1. 一个核心模式：Draft → Commit

草稿与提交分离（Draft versus commit） 是整个权限设计里最值得抄作业的机制——把高危动作拆成两个独立工具：

• draft_email→send_email
• prepare_refund→issue_refund
• recommend_trade→place_trade

草稿工具可以自动跑（无副作用）；提交工具必须走审批，除非它本身是低风险且被显式加白名单。

2. 审批请求要"说人话"

references/security-observability.md 给出了审批记录的标准格式：审批类型、目标动作、目标对象、风险等级、预览引用（让人先看草稿原文）、预期结果、回滚说明、作用域。审批结果则包含：审批人、时间戳、作用域、过期时间。

两条铁律：

• ⚠️永远不要让模型批准它自己的动作。
• ⚠️审批是有作用域、有过期时间的——"同意这一次"不等于"同意以后所有"。

3. 结果状态也要设限

一个容易被忽略的细节（结果状态限制章节）：业务限额要约束最终状态，而不仅是单次请求。比如"最多 4 件"的限制，要能拦住"两次各加 3 件"的连招；提交时必须原子地复核授权、审批有效性、实时目标状态，冲突时不做部分写入。

四、权限矩阵速查：一张表配好默认策略 ⚡

默认权限策略（Permission matrix） 是一份可以直接套用的速查表：

配合 references/checklists.md 中的权限检查清单（外部发送需审批、审批记录持久化、模型不能自批、并发的重复写入要保护最终状态限制等十几条 pass/fail 项），就能把这套矩阵变成可执行的验收标准。

五、落地实战：把权限写进 MVP 蓝图 🛠️

1. 先选自治级别，再谈能力

references/mvp-agent-blueprint.md 把 Agent 的自治分成 5 级，原则是选"仍能有价值"的最低级别：

• Level 0 只回答：只读+总结，不动手
• Level 1 只出草稿：人负责所有提交
• Level 2 审批门禁：提出动作、暂停等审批 ——多数业务 Agent 的默认起点 ✅
• Level 3 策略内自治：低风险动作可自动执行，需要强日志+评测+回滚
• Level 4 长时自治目标：基础框架被证明可靠后再上

2. 上线前的安全门禁（Launch Gates）

references/security-observability.md 的发布门禁清单是"生死线"的第二道闸：窄工具注册表、本地 schema 校验、权限矩阵在代码中强制生效、高危动作有审批 UI、提示注入测试通过、追踪日志开启、成本预算强制、回滚与事故路径有文档。

3. 配套能力别漏掉

• 📦沙箱：命令执行、浏览器自动化、生成代码、外部数据处理，一律沙箱 + 文件系统/网络白名单 + 密钥隔离
• 🔐密钥：永不进入模型上下文，工具内部用短期作用域令牌，结果返回脱敏摘要
• 👁可观测性：追踪"模型输出 → 工具调用 → 权限决策 → 结果"全链路，能回答"它做了什么、谁批准的、为什么停、能否审计重放"

六、新手避坑清单 🧯

来自 SKILL.md 的反模式总结，条条是事故现场：

1. 别靠提示词保安全—— 必须被代码强制的防护，写在 prompt 里等于没写。
2. 别把检索内容当指令—— 网页、邮件、工单、PDF 里的文字是"数据"，不是命令，不能让外部内容直接选工具。
3. 别把宽泛工具丢给模型——execute_anything/send_message/write_database没有严格包装和审批策略前，一律不暴露。
4. 每次工具调用必须有结果—— 拒绝、超时、参数错误、中止，都是观测结果，不能让调用"悬空"。
5. 压缩上下文时别丢审批状态—— 进行中的计划、已加载规则、审批进度必须跨压缩保留。
6. 别急着上多 Agent—— 单 Agent 循环在评测上没跑稳之前，多 Agent 只会放大权限漏洞面。

写在最后

Agent 工具权限设计的本质，不是限制 Agent，而是让"放手"变得可预期、可审计、可回滚。风险分级让你知道每个动作有多危险，审批门禁让你在人机之间划出清晰的责任边界。

想动手实践？可以安装该技能包后，直接让 Agent 为你的业务场景生成一份含工具注册表、权限矩阵与审批策略的 MVP 蓝图：

• 技能入口：SKILL.md
• 权限核心参考：references/tools-and-permissions.md
• 安全与可观测性：references/security-observability.md
• MVP 蓝图模板：references/mvp-agent-blueprint.md
• 验收清单：references/checklists.md

记住项目的那句话：Keep the loop simple, and make the runtime rigorous.（循环保持简单，运行时保持严格。）

【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practices