Deep Agents 权限控制：打造安全可靠的智能体文件系统访问

在构建基于 Deep Agents 的智能体应用时，确保其对文件系统的访问安全至关重要。Deep Agents 提供了一套声明式的权限控制系统，让你可以精确地控制智能体能读取或写入哪些文件和目录。本文将深入浅出地介绍这一功能，并提供大量可直接运行的代码示例。

什么是 Deep Agents 权限控制？

Deep Agents 的权限控制允许你通过声明式规则来限制智能体对文件系统的访问。这些规则会自动应用于 Deep Agents 内置的文件系统工具（如 ls、read_file、glob、grep、write_file、edit_file）。

重要提示 ：权限控制需要 deepagents>=0.5.2 版本，并且仅适用于内置的文件系统工具。自定义工具、MCP 工具以及沙箱后端的 execute 工具不受此权限系统约束。

基础用法

最简单的用法是创建一个只读智能体，禁止所有写操作：

python 复制代码

from deepagents import FilesystemPermission, create_deep_agent

# 创建只读智能体：拒绝所有写操作
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)

权限规则结构

每个 FilesystemPermission 规则包含三个关键字段：

字段	类型	描述
`operations`	`list["read"	"write"]`
`paths`	`list[str]`	文件路径的 glob 模式（如 `["/workspace/"]`）。支持 `` 递归匹配和 `{a,b}` 交替匹配
`mode`	`"allow"	"deny"`

规则评估机制 ：采用"首次匹配获胜"原则，即按声明顺序评估规则，第一个匹配的规则决定结果。如果没有规则匹配，则允许操作（宽松默认策略）。

实用示例

1. 工作区隔离

只允许在 /workspace/ 目录下进行读写操作，拒绝其他所有访问：

python 复制代码

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

2. 保护特定文件

保护敏感文件（如 .env）和示例目录，同时允许工作区的其他文件访问：

python 复制代码

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",
        ),
    ],
)

3. 只读内存

对于组织级策略或共享知识库，允许智能体读取但不能修改内存文件：

python 复制代码

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

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",
        ),
    ],
)

4. 完全拒绝访问

创建一个完全隔离的基线，可以在此基础上添加更具体的允许规则：

python 复制代码

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

规则顺序的重要性

由于采用"首次匹配获胜"机制，规则顺序至关重要。更具体的规则应该放在更通用的规则之前：

python 复制代码

# 正确：先拒绝 .env，再允许工作区，最后拒绝其他所有
correct_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，导致拒绝规则永远不会触发
incorrect_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",
    ),
]

子智能体权限

子智能体默认继承父智能体的权限，但你可以为子智能体指定不同的权限规则，这会完全替换父智能体的规则：

python 复制代码

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": "Read-only code reviewer",
            "system_prompt": "Review the code for issues.",
            "permissions": [
                FilesystemPermission(
                    operations=["write"],
                    paths=["/**"],
                    mode="deny",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/workspace/**"],
                    mode="allow",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/**"],
                    mode="deny",
                ),
            ],
        }
    ],
)

复合后端的权限限制

当使用 CompositeBackend 且默认后端是沙箱时，权限路径必须限定在已知的路由前缀下。这是因为沙箱支持任意命令执行，仅靠路径限制无法防止通过 shell 命令访问文件系统。

python 复制代码

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，因为 /workspace/** 会命中沙箱默认后端
try:
    create_deep_agent(
        model=model,
        backend=composite,
        permissions=[
            FilesystemPermission(
                operations=["write"],
                paths=["/workspace/**"],
                mode="deny",
            ),
        ],
    )
except NotImplementedError:
    pass

何时使用权限控制 vs 后端策略钩子

使用 permissions：当你需要基于路径的允许/拒绝规则来控制内置文件系统工具时
使用后端策略钩子：当你需要自定义验证逻辑（如速率限制、审计日志、内容检查）或需要控制自定义工具时

总结

Deep Agents 的权限控制系统为你提供了强大的文件系统访问控制能力。通过合理配置权限规则，你可以：

隔离工作环境：限制智能体只能访问特定目录
保护敏感数据：防止智能体读取或修改敏感文件
实现只读策略：为共享资源设置只读访问
精细化控制：为不同子智能体设置不同的权限

记住关键原则：规则顺序很重要 ，更具体的规则放前面 ，没有匹配规则时默认允许。这样你就能构建出既功能强大又安全可靠的 Deep Agents 应用。