使用声明式权限规则控制代理可以读取或写入的文件和目录。将规则列表传递给 permissions= ，代理的内置文件系统工具会遵守这些规则。

权限仅适用于内置文件系统工具（ls, read_file, glob, grep, write_file, edit_file）。自定义工具和访问文件系统的 MCP 工具不受覆盖。权限也不适用于 沙盒后端，它支持通过以下方式执行任意命令 execute tool.

基本用法

将 FilesystemPermission 规则列表传递给 create_deep_agent。规则按声明顺序评估。第一个匹配的规则生效。如果没有规则匹配，则允许操作。

规则结构

每个 FilesystemPermission 有三个字段：

规则使用首次匹配优先评估：第一个 operations 和 paths 与当前调用匹配的规则决定结果。如果没有规则匹配，则调用被 **允许** （默认允许）。

暂停等待人工审批

设置为 mode="interrupt" 以在匹配操作时暂停等待人工审批，而不是直接允许或拒绝。当代理对匹配中断模式规则的路径调用内置写入工具（write_file, edit_file）时， create_deep_agent 会触发人工介入中断，而不是运行该工具，审核者可以批准、编辑或拒绝该调用。

from deepagents import FilesystemPermission, create_deep_agent
from langgraph.checkpoint.memory import InMemorySaver


agent = create_deep_agent(
    model=model,
    permissions=[
        # Pause for approval before writing anything under /secrets.
        FilesystemPermission(
            operations=["write"],
            paths=["/secrets/**"],
            mode="interrupt",
        ),
    ],
    # Interrupt mode requires a checkpointer to pause and resume.
    checkpointer=InMemorySaver(),
)

中断模式规则自动连接到代理的人工介入中间件，并与您传入的任何 interrupt_on 合并，因此您可以像处理工具调用中断一样的方式处理和恢复它们。参见 Human-in-the-loop 了解恢复流程。

示例

隔离到工作区目录

仅允许在以下位置进行读写 /workspace/ 并拒绝其他一切操作：

保护特定文件

只读内存

允许智能体读取内存文件但阻止其修改它们。这对于组织范围的策略或仅应由应用程序代码更新的共享知识库很有用。请参阅 只读内存与可写内存 获取更多上下文。

拒绝所有访问

阻止所有读写操作。这是一个限制性的基线，您可以在其上叠加更具体的允许规则：

规则排序

由于采用首个匹配优先原则，规则顺序很重要。请将更具体的规则放在更宽泛的规则之前：

子代理权限

子代理 默认继承父代理的权限。若要为子代理设置不同的权限，请在 permissions 字段中设置。这将 **替换** 父代理的规则。

复合后端

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

包含在任何路由外部路径的权限会引发 NotImplementedError: