Skip to main content
使用声明式权限规则控制代理可以读取或写入哪些文件和目录。将规则列表传递给 permissions=，代理的内置文件系统工具将遵守这些规则。 权限仅适用于内置文件系统工具（ls、read_file、glob、grep、write_file、edit_file）。访问文件系统的自定义工具和 MCP 工具不受覆盖。权限也不适用于 沙箱后端，后者支持通过 execute 工具执行任意命令。
当您需要对内置文件系统工具使用基于路径的允许/拒绝规则时，请使用 permissions。当您需要自定义验证逻辑（速率限制、审计日志、内容检查）或需要控制自定义工具时，请使用 后端策略钩子。

​
基本用法

将 FilesystemPermission 规则列表传递给 create_deep_agent。规则按声明顺序进行评估。第一个匹配的规则胜出。如果没有规则匹配，则允许该操作。 
from deepagents import create_deep_agent, FilesystemPermission

# 只读代理：拒绝所有写入
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)

​
规则结构

每个 FilesystemPermission 都有三个字段：
字段类型描述
operationslist["read" | "write"]此规则适用的操作。"read" 涵盖 ls、read_file、glob、grep。"write" 涵盖 write_file、edit_file。
pathslist[str]用于匹配文件路径的 Glob 模式（例如 ["/workspace/**"]）。支持 ** 用于递归匹配，支持 {a,b} 用于交替匹配。
mode"allow" | "deny"允许还是拒绝匹配的操作。默认为 "allow"。
规则使用首次匹配胜出评估：operations 和 paths 与当前调用匹配的第一个规则决定结果。如果没有规则匹配，则调用被允许（默认允许）。

​
示例

​
隔离到工作区目录

仅允许在 /workspace/ 下读取和写入，并拒绝其他所有内容： 
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)

​
保护特定文件

agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/.env", "/workspace/examples/**"],
            mode="deny",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)

​
只读记忆

允许代理读取记忆文件，但防止其修改它们。这对于组织范围的策略或应仅由应用代码更新的共享知识库很有用。有关更多上下文，请参阅 只读与可写记忆。 
agent = create_deep_agent(
    model=model,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.server_info.user.identity,),
            ),
            "/policies/": StoreBackend(
                namespace=lambda rt: (rt.context.org_id,),
            ),
        },
    ),
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/memories/**", "/policies/**"],
            mode="deny",
        ),
    ],
)

​
拒绝所有访问

阻止所有读取和写入。这是一个限制性基线，您可以在其上分层更具体的允许规则： 
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)

​
规则顺序

由于首次匹配胜出，规则顺序很重要。将更具体的规则放在更广泛的规则之前： 
# 正确：拒绝 .env，允许工作区，拒绝其他所有内容
permissions=[
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

# 错误：/workspace/** 首先匹配 .env，因此拒绝永远不会触发
permissions=[
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",  # 永远不会到达
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

​
子代理权限

子代理 默认继承父代理的权限。要为子代理提供不同的权限，请在其 spec 中设置 permissions 字段。这将完全替换父级的规则。 
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
    subagents=[
        {
            "name": "auditor",
            "description": "只读代码审查员",
            "system_prompt": "审查代码以查找问题。",
            "permissions": [
                FilesystemPermission(
                    operations=["write"],
                    paths=["/**"],
                    mode="deny",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/workspace/**"],
                    mode="allow",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/**"],
                    mode="deny",
                ),
            ],
        }
    ],
)

​
复合后端

当使用带有沙箱默认值的 CompositeBackend 时，每个权限路径必须限定在已知的路由前缀下。沙箱支持任意命令执行，因此仅基于路径的限制无法防止通过 shell 命令访问文件系统。将权限限定为特定路由的 后端 可以避免此冲突。 
from deepagents.backends import CompositeBackend

composite = CompositeBackend(
    default=sandbox,
    routes={"/memories/": memories_backend},
)

# 有效：权限限定在 /memories/ 路由
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/memories/**"],
            mode="deny",
        ),
    ],
)
包含任何路由之外路径的权限会引发 NotImplementedError： 
# 引发 NotImplementedError：/workspace/** 命中沙箱默认值
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/workspace/**"],
            mode="deny",
        ),
    ],
)

# 也会引发：/** 涵盖路由和默认值
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["read"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
在 GitHub 上编辑此页面 或 提交问题。
连接这些文档 到 Claude、VSCode 等，通过 MCP 获取实时答案。