为智能体工具调用设计分层权限判定
文章用 TypeScript 演示五层权限判定,按优先级匹配规则,返回放行、人工审批或拒绝。每次判定同时记录命中的规则,方便追溯决定。
AI 深度解读
给 AI Agent 接上发消息、发布和付款工具后,同一次调用可能既需要人工审批,又缺少执行权限。作者用一个 TypeScript 函数把五层规则排好顺序,第一层命中就返回,并带上触发判定的规则。这样,团队查日志时就能知道调用为什么停下。
这套设计容易落地,但示例也暴露了一个关键问题。如果「需要审批」排在「禁止执行」前面,系统就可能先给一笔本该拒绝的操作发审批单。读这篇最有用的地方,是把规则顺序和审批后的执行条件一起想清楚。
五层规则怎么决定一次工具调用
作者把每次工具调用压成三种结果。allow 表示继续,checkpoint 表示暂停并请求人工审批,deny 表示拒绝。每种结果都带一个 rule,发起审批和事后查日志时都能看到当时是哪条规则生效。
- 底线。 转移资金、公开发布、首次联系工作区外的人等动作固定需要人工介入。底线写在代码里,工作区可以加严,所有者也不能放宽。正文举了删除非 Agent 创建的记录作为例子,示例代码则拦下所有标为
destructive的调用。 - 明确拒绝。 缺少所需权限范围(scope)、目的地不在允许列表时拒绝。作者还举了超出允许时段的例子,代码里只实现了前两项。
- 单次委派限制。 交办人可以要求外发前先问,或者单次调用费用超过 2 美元时先问。代码比较的是
call.costUsd > ctx.askAboveUsd,刚好等于门槛时不会在这一层暂停。 - Agent 默认策略。 所有者或管理员按风险类别配置默认行为。例如,
read可以继续走后续检查,write可以要求审批。 - 预算。 把已花金额与本次费用相加,达到预算上限的 80% 时要求审批,达到上限时拒绝。两个条件都用
>=,所以刚好达到上限也会被拒绝。
下面的 decide 展示了检查顺序,以及每个分支如何返回判定和原因。
export function decide(call: Call, ctx: Context): Verdict {
// 1. The floor
const floor = FLOOR(call);
if (floor) return { result: "checkpoint", rule: floor };
// 2. Denies
if (call.scopes.some((s) => !ctx.grantedScopes.has(s)))
return { result: "deny", rule: "deny: scope not granted" };
if (call.destination && !ctx.allowedDestinations.has(call.destination))
return { result: "deny", rule: "deny: destination not on the allowlist" };
// 3. Delegation toggles
if (ctx.askBeforeSending && call.risk === "external_send")
return { result: "checkpoint", rule: "toggle: ask before anything leaves" };
if (ctx.askAboveUsd !== null && call.costUsd > ctx.askAboveUsd)
return { result: "checkpoint", rule: "toggle: step over the spend threshold" };
// 4. The agent's own policy
if (ctx.agentDefaults[call.risk] === "checkpoint")
return { result: "checkpoint", rule: `policy: ${call.risk} needs approval` };
// 5. Budget
const after = ctx.spentUsd + call.costUsd;
if (after >= ctx.capUsd) return { result: "deny", rule: "budget: hard stop" };
if (after >= ctx.capUsd * 0.8) return { result: "checkpoint", rule: "budget: 80 percent of the cap" };
return { result: "allow", rule: "default allow within granted scopes" };
}
看第一处 return。一旦 FLOOR(call) 命中,后面的 scope、目的地和预算检查都不会运行。这正是短路求值带来的行为。
审批、测试和日志各管什么
作者建议让新 Agent 的首次委派只产出草稿,所有写入先进入草稿流程,等人审完一整轮,再开放写权限。审批也要有自己的入口。邮件正文、网页和工具返回值都按数据处理,其中写着「已批准」也不能授予 scope。审批请求无人回应时,作者建议转交下一位审批人,随后暂停任务,初始有效期可以设为 7 天。
decide 是纯函数,可以用表驱动测试固定输入和预期判定。原文列了三行,分别检查 payments.refund 是否命中资金底线,http.get 访问 evil.test 是否因目的地被拒绝,以及费用为 9 美元的 notes.read 在给定预算上下文里是否命中 80% 检查点。作者还建议每次事故都补一条测试,并用只追加的表记录调用、判定和规则。Postgres 哈希链是后续文章的话题,这段代码没有实现。
我的判断
把判定收在纯函数里,再把命中规则随审批和日志保存,这两点很实用。策略评审可以直接拿冲突用例讨论,排查时也有当时的判定可查。原文给出了团队在做产品时采用的方案和测试样例,没有给出上线效果,也没有用对照数据证明这种顺序能减少多少争议。减少争议是作者的经验判断。
「最严格规则优先」在示例里实际是「最先命中的层优先」。比如一条首次对外发送的消息,其目的地同时不在允许列表,函数会先返回 checkpoint。同样,已经触发委派审批的调用可能跳过预算硬上限。原文没有说明审批通过后还会做哪些检查,因此仅凭这个函数,无法判断最终执行会不会越过这些限制。
全部规则一起评估、再按 deny、checkpoint、allow 的顺序取结果,可以同时保留冲突原因,代价是要定义多条规则如何展示和记录。想保留短路结构,也可以先处理必须拒绝的条件,再决定哪些调用要进审批。如果产品需要先记录底线命中,执行入口就要在真正发消息、发布或付款前,按当时的权限、目的地和预算重新校验。
能拿来做什么
- 在 Node 工具执行入口统一调用策略函数,把
result和rule一起交给审批界面和日志,让审批人看到触发原因。 - 给测试表加上冲突用例,例如首次外发遇到未获准的目的地、需要审批的调用恰好达到预算上限,并写明产品期望先返回哪个结果。
- 给负责发布或外发的 Agent 先开草稿流程。人工看过一整轮调用后,再授予对应的写权限,并验证审批等待期间权限发生变化时,执行入口会重新检查。