Agent 也能「过安检」:AgentScope 权限系统设计拆解

0 阅读7分钟

当 Agent 能执行 Bash、读写文件、调用 MCP 时,「能不能干」比「会不会干」更重要。本文基于开源框架 AgentScope 的权限子系统,拆解一套面向工具调用的权限模型:规则怎么存、怎么匹配、怎么和 HITL(人在环)续跑咬合。


一、为什么 Agent 需要独立的权限层

传统后端权限多半挂在「用户 → API → 资源」上。Agent 场景不一样:

  1. 调用方是模型,不是人。模型可能连续发出 rm -rf、改配置文件、跑任意 shell。
  2. 危险粒度在「工具入参」。同样是 Bash,ls 和 rm -rf / 风险完全不同;同样是 Write,写 src/ 和写 ~/.bashrc 也不同。
  3. 决策常常要人确认,但不能阻塞整条异步链路。权限系统必须能输出「ASK」,让 Agent 停车,等 UI 确认后再续跑。

因此 AgentScope 把权限做成 工具执行前的独立引擎:Agent 循环只管 ReAct,权限引擎只管 ALLOW / DENY / ASK。


二、整体架构:三层结构

可以用一张关系图概括:

Agent._execute_tool_call
        │
        ▼
PermissionEngine.check_permission(tool, tool_input)
        │
        ├─ 读 PermissionContext(mode + 规则表 + 工作目录)
        ├─ 按 PermissionMode 走不同策略
        ├─ 用 tool.match_rule(rule_content, input) 做细粒度匹配
        └─ 必要时调用 tool.check_permissions(...)(工具自检 / Safety ASK)
        │
        ▼
PermissionDecision
  ALLOW  → 真正执行
  DENY   → 写回拒绝结果,继续/结束循环
  ASK    → RequireUserConfirmEvent,HITL 停车

核心类型都在 agentscope.permission:

类型职责
PermissionContext会话级权限状态(可随 AgentState 持久化)
PermissionRule一条细粒度规则
PermissionMode粗粒度总策略
PermissionBehavior单次决策结果:allow / deny / ask / passthrough
PermissionEngine评估器
PermissionDecision评估输出(含建议规则、是否 safety ASK)

Agent 初始化时会挂上:

self._engine = PermissionEngine(self.state.permission_context)

多轮会话共用同一份 permission_context:你确认「记住这条规则」之后,后面几轮仍然生效。


三、数据结构:规则到底长什么样

1. PermissionRule:一条规则

class PermissionRule(BaseModel):
    tool_name: str                 # 管哪个工具
    rule_content: str | None       # 管这个工具的哪类入参
    behavior: PermissionBehavior   # allow / deny / ask
    source: str                    # 溯源标签,不参与匹配

要点:

  • 索引维度是 tool_name,不是用户角色、不是 API path。
  • rule_content 不是全局统一语法,由各工具的 match_rule 解释。
  • source 是自由字符串(如 suggested、userSettings),只做展示/溯源,引擎匹配时不读。

2. PermissionContext:规则仓库

class PermissionContext(BaseModel):
    mode: PermissionMode = PermissionMode.DEFAULT
    working_directories: dict[str, AdditionalWorkingDirectory]
    allow_rules: dict[str, list[PermissionRule]]  # key = tool_name
    deny_rules: dict[str, list[PermissionRule]]
    ask_rules: dict[str, list[PermissionRule]]

内存里大概是这样:

PermissionContext(
    mode=PermissionMode.DEFAULT,
    allow_rules={
        "Bash": [
            PermissionRule(
                tool_name="Bash",
                rule_content="git status",
                behavior=PermissionBehavior.ALLOW,
                source="userSettings",
            ),
        ],
        "Read": [
            PermissionRule(
                tool_name="Read",
                rule_content="src/**",
                behavior=PermissionBehavior.ALLOW,
                source="suggested",
            ),
        ],
    },
    deny_rules={
        "Bash": [
            PermissionRule(
                tool_name="Bash",
                rule_content="rm -rf",
                behavior=PermissionBehavior.DENY,
                source="projectSettings",
            ),
        ],
    },
    ask_rules={},
)

设计上很克制:先按工具名分桶,再在桶内用入参模式匹配。这比「全局 ACL 表达式」更贴合 Agent 工具调用的形态。


四、rule_content 怎么匹配:不是全等

很多人第一反应是「规则内容要完全等于命令」。AgentScope 不是这样。

匹配委托给工具自己的 match_rule:

工具匹配方式
Bash(无通配符)子串包含:"npm install" in command
Bash(git:*)前缀:git 或 git ...
Bash(带 *)通配 / 正则 fullmatch
Read / Write / Editglob:fnmatch(path, "src/**")
rule_content is None该工具所有调用都命中
普通 FunctionTool(未覆写)只有 None 才能匹配;有内容则不匹配

举例:

规则: Bash + "npm install" + ALLOW
调用: Bash("npm install express")
结果: 命中(子串),直接放行
规则: Read + "src/**" + ALLOW
调用: Read("src/main.py")
结果: 命中(glob),放行
调用: Read("/etc/passwd")
结果: 不命中,继续走后续策略(多半 ASK)

复合 Bash(cmd1 && cmd2)还会先被拆成子命令再评估:deny/ask 是「任一命中」,allow 往往要求「全部覆盖」——这点对安全很重要。


五、PermissionMode:粗策略怎么和细规则叠加

PermissionMode 是会话级总开关,每种 mode 有独立的 _check_<mode> 方法,避免「一个巨型 if-else」。

Mode直觉
DEFAULT最安全:没规则就问;读操作也未必自动过
ACCEPT_EDITS人在旁边快速迭代:工作目录内的读写更宽松
EXPLORE只读探索:改文件 / 危险命令直接拒
BYPASS基本信任沙箱:少问,主要靠 deny/ask 规则兜底
DONT_ASK无人值守:所有 ASK 转 DENY,偏安全

以最常见的 DEFAULT 为例,评估顺序大致是:

1. deny_rules 命中? → DENY
2. ask_rules 命中?  → ASK(附带建议规则)
3. 只读快路径?      → ALLOW(部分场景)
4. tool.check_permissions(...)
     - ALLOW / DENY → 直接返回
     - Safety ASK(bypass_immune=True)→ 必须问人,allow 规则盖不住
     - 普通 ASK / PASSTHROUGH → 继续
5. allow_rules 命中? → ALLOW
6. 默认 → ASK

这里有个很关键的细节:Safety ASK(bypass_immune=True)。
例如疑似 rm -rf /、写入危险路径、命令注入模式——即使你以前点过「允许类似操作」,也不能用 allow 规则把这次危险调用「静默放行」。BYPASS 模式会刻意弱化这类提示(契约就是少问),真正硬护栏应靠 deny 规则。


六、和 Agent 循环如何咬合(HITL)

权限不是「同步 input() 卡住进程」,而是事件驱动:

Acting 执行工具
  → 引擎返回 ASK
  → tool_call.state = ASKING
  → yield RequireUserConfirmEvent
  → 本次 reply 以「未完成」方式结束(没有 ReplyEnd 的完成语义)

用户在 UI 确认 / 拒绝
  → 再次 reply(UserConfirmResultEvent)

续跑:
  确认 → state=ALLOWED,可 add_rule,再真正执行
  拒绝 → 写入 DENIED 工具结果,模型下一轮会看到拒绝原因

这和 AgentScope 的 ReAct 状态机一致:_next_action 发现还有 awaiting 的 tool call,就会「停车等外部事件」,而不是阻塞事件循环。

用户点「允许并记住」时,UI 通常会把 suggested_rules 一并带回;Agent 侧:

for rule in confirmation.rules:
    self._engine.add_rule(rule)

建议规则一般由工具的 generate_suggestions 生成,例如:

  • Bash:npm run → 建议 npm run:*
  • 读文件:src/a.py → 建议 src/**
  • source 常标成 "suggested"

七、一次完整走读

假设当前 context:

mode = DEFAULT
allow: Bash + "git status"
deny:  Bash + "rm -rf"
模型发起的调用引擎结果后续
Bash("git status")ALLOW直接执行
Bash("rm -rf /tmp/x")DENY工具结果写回拒绝文案
Bash("npm install")ASK弹确认;若记住 npm install,写入 allow_rules
Write("~/.bashrc")可能 Safety ASK即使有宽泛 allow,也可能仍要当面确认

对业务开发者而言,你很少手写规则表;更常见是:

  1. 启动时设好 mode 和工作目录;
  2. 让 HITL 在运行中积累 allow/deny;
  3. 项目级危险模式用 deny 规则预置。

八、设计取舍:值得抄的几点

1. 工具名分桶 + 入参模式,而不是通用策略语言

Agent 的「资源」本质上是工具调用。按 tool_name 索引、把匹配语义下沉到工具,比引入一套复杂 DSL 更贴业务,也方便第三方工具自定义 match_rule。

2. mode 与 rule 正交

mode 管「默认姿态」,rule 管「例外清单」。EXPLORE / DONT_ASK / BYPASS 改变的是评估流程,而不是把所有规则重写一遍。

3. ASK 是一等公民,且可带建议规则

权限系统不仅说「不行」,还说「如果你想以后少问,建议加这条规则」。这比冷冰冰的拒绝更适合 Agent 产品体验。

4. Safety ASK 防止「记住一次就永久危险」

bypass_immune 把「方便」和「危险」拆开:普通操作可以记住,高危操作必须当场确认(在非 BYPASS 场景下)。

5. 状态可持久化

规则住在 AgentState.permission_context,和对话 context 一起存。会话恢复后,权限习惯还在。


九、上手最小示例

from agentscope.permission import (
    PermissionContext,
    PermissionEngine,
    PermissionMode,
    PermissionRule,
    PermissionBehavior,
)

ctx = PermissionContext(mode=PermissionMode.DEFAULT)
engine = PermissionEngine(ctx)

engine.add_rule(
    PermissionRule(
        tool_name="Bash",
        rule_content="git:*",
        behavior=PermissionBehavior.ALLOW,
        source="userSettings",
    )
)

engine.add_rule(
    PermissionRule(
        tool_name="Bash",
        rule_content="rm -rf",
        behavior=PermissionBehavior.DENY,
        source="projectSettings",
    )
)

# Agent 里通常不必手动 check;执行工具前框架会调用:
# decision = await engine.check_permission(tool, tool_input)

挂到 Agent 上时,只要构造时带上(或事后改)state.permission_context 即可;引擎在 Agent.__init__ 里已经接好。


十、小结

AgentScope 的权限设计可以压成一句话:

按工具名归档规则,按入参模式匹配;用 Mode 定默认姿态,用 ASK + HITL 做人机协同,用 Safety ASK 兜住真正危险的操作。

如果你也在做「能动手的 Agent」,不妨优先想清楚这三件事:

  1. 权限客体是「工具调用」还是「HTTP 资源」?
  2. ASK 是阻塞式对话框,还是可续跑的事件?
  3. 「记住规则」会不会把高危操作永久放行?

想清楚这三点,你的 Agent 安检台就有了骨架;其余都是产品和体验上的填充。


参考(源码入口)

  • agentscope/permission/_rule.py — 规则模型
  • agentscope/permission/_context.py — 上下文与规则表
  • agentscope/permission/_types.py — Mode / Behavior
  • agentscope/permission/_engine.py — 评估引擎
  • agentscope/permission/_decision.py — 决策与 Safety ASK
  • agentscope/agent/_agent.py — _execute_tool_call / HITL 续跑
  • agentscope/tool/_builtin/_bash.py 等 — match_rule / generate_suggestions

(文中示例基于 AgentScope 当前实现梳理,细节以仓库源码为准。)