权限规则

PermissionRule 把某个工具与具体的调用模式映射到三种行为之一：ALLOW、DENY、ASK。规则在每种权限模式下都以最高优先级评估：拒绝与询问规则最先，允许规则排在工具内置检查之后。每条规则由下述字段组成。当权限引擎评估一条规则时，它会用 rule_content 与实际调用入参调用该工具的 match_rule() 方法，判断规则是否命中。

str

必填

规则适用的工具名："Bash"、"Read"、"Write"、"Edit"，或任意自定义工具名。

str | None

必填

匹配模式，语义随 tool_name 变化：

Bash：通配前缀模式（npm run:* 命中 npm run build、npm run test）
Read / Write / Edit：glob 模式（src/**/*.py 命中 src/ 下任意 .py）
其他工具：对 JSON 序列化后的参数做精确匹配

PermissionBehavior

必填

ALLOW、DENY 或 ASK

str

必填

规则来源："userSettings"、"projectSettings"、"session" 等。

匹配模式示例

rule_content 由各工具的 match_rule() 方法消费，并由 ToolBase.generate_suggestions() 自动生成。由于这两个方法都属于工具接口的一部分，每个工具可以独立定义自己的模式语法与匹配逻辑。 AgentScope 内置工具的模式约定如下：

Bash
文件类工具（Read / Write / Edit）

针对 command 参数做匹配。模式格式为 COMMAND_PREFIX:*：前缀是命令的首段 token，* 匹配后续任意参数。

模式	匹配	不匹配
`npm run:*`	`npm run build`、`npm run test`	`npm install`
`git commit:*`	`git commit -m "fix"`	`git push`
`rm:*`	`rm file.txt`、`rm -rf /tmp/x`	`ls`

PermissionRule(
    tool_name="Bash",
    rule_content="npm run:*",
    behavior=PermissionBehavior.ALLOW,
    source="userSettings",
)

针对 file_path 参数，通过 fnmatch 做 glob 匹配。

模式	匹配
`src/**`	`src/` 下任意文件
`src/*/.py`	`src/` 下的 Python 文件
`config.json`	精确匹配该文件

PermissionRule(
    tool_name="Write",
    rule_content="src/**",
    behavior=PermissionBehavior.ALLOW,
    source="userSettings",
)

配置规则

规则通过两种途径进入引擎：初始化时静态配置，或运行时由用户接受建议规则动态加入。 初始化时：在创建智能体时把规则传入 PermissionContext：

from agentscope.agent import Agent
from agentscope.state import AgentState
from agentscope.permission import (
    PermissionContext, PermissionMode, PermissionRule, PermissionBehavior
)

agent = Agent(
    name="my_agent",
    system_prompt="...",
    model=model,
    state=AgentState(
        permission_context=PermissionContext(
            mode=PermissionMode.DEFAULT,
            allow_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="npm run:*",
                                        behavior=PermissionBehavior.ALLOW, source="userSettings")],
                "Write": [PermissionRule(tool_name="Write", rule_content="src/**",
                                         behavior=PermissionBehavior.ALLOW, source="userSettings")],
            },
            deny_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="rm:*",
                                        behavior=PermissionBehavior.DENY, source="userSettings")],
            },
        )
    ),
)

运行时通过建议规则：当权限系统返回 ASK 时，会基于本次调用自动生成建议规则。把已接受的规则附在 UserConfirmResultEvent.rules 中回传，智能体会自动写入引擎：

from agentscope.event import UserConfirmResultEvent

# ASK 决策中包含基于本次调用生成的 suggested_rules。
# 接受建议时，把它放入结果事件即可：
result = UserConfirmResultEvent(
    confirmed=True,
    rules=[suggested_rule],  # 已接受的规则会被持久化进引擎
)

允许规则无法覆盖工具发出的安全 ASK（bypass_immune=True），例如写入 ~/.ssh/ 的操作。详见安全检查契约。

快速开始

核心模块

智能体即服务

其他

匹配模式示例

配置规则

​匹配模式示例

​配置规则

匹配模式示例

配置规则