DeepAgents : 权限（Permissions）

DeepAgents : 权限（Permissions）

权限功能允许你以声明式规则控制智能体（Agent）可以读取或写入哪些文件和目录。将规则列表传入 permissions 参数，智能体的内置文件系统工具便会遵循这些规则。

1. 基本用法

将 FilesystemPermission 规则列表传入 create_deep_agent。

from deepagents import FilesystemPermission, create_deep_agent

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

适用范围 ：权限仅 适用于内置文件系统工具（ls、read_file、glob、grep、write_file、edit_file、delete）。

不适用范围：

• 自定义工具和访问文件系统的 MCP 工具不在涵盖范围内
• 权限不适用于 沙盒后端（Sandbox Backend），后者通过 execute 工具支持任意命令执行

使用建议：

需求场景	推荐方案
对内置文件系统工具进行基于路径的允许/拒绝控制	使用 permissions
需要自定义验证逻辑（速率限制、审计日志、内容检查）或控制自定义工具	使用后端策略钩子（Backend Policy Hooks）

2. 规则结构

每个 FilesystemPermission 包含三个字段：

字段	类型	说明
operations	`list["read"	"write"]`
paths	list[str]	匹配文件路径的 Glob 模式（如 ["/workspace/**"]）。 支持 **（递归匹配）、*（单段内匹配）、{a,b}（花括号展开）
mode	`"allow"	"deny"

路径规范：

• 所有路径必须是绝对 Glob 模式 （以 / 开头）
• 不得包含 .. 或 ~

匹配逻辑 ：按声明顺序评估，第一个同时匹配 operations 和 paths 的规则决定结果。若无规则匹配，则操作允许（默认宽松策略）。

3. 人工审批（Interrupt）

设置 mode="interrupt" 可暂停匹配的操作，等待人工审批，而非直接允许或拒绝。

当智能体调用内置写入工具（write_file、edit_file、delete）且目标路径匹配 interrupt 模式的规则时，create_deep_agent 会触发人机协同中断（Human-in-the-Loop Interrupt），审查人员可以批准、编辑或拒绝该调用。

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

agent = create_deep_agent(
    model=model,
    permissions=[
        # 写入 /secrets/ 下的任何文件前，暂停等待人工审批
        FilesystemPermission(
            operations=["write"],
            paths=["/secrets/**"],
            mode="interrupt",
        ),
    ],
    # interrupt 模式需要 checkpointer 来暂停和恢复
    checkpointer=InMemorySaver(),
)

注意事项：

• interrupt 模式的规则会自动接入智能体的人机协同中间件，与你手动传入的 interrupt_on 配置合并
• 中断的处理和恢复方式与工具调用中断相同
• 必须配置 checkpointer 才能实现暂停与恢复

4. 子智能体（SubAgent）权限

子智能体可以独立配置权限规则：

配置方式	行为
省略 permissions	继承父智能体的权限规则
显式指定 permissions	完全替换父智能体的规则（不继承）

# 子智能体独立配置权限
subagent = {
    "name": "researcher",
    "description": "Research assistant",
    "system_prompt": "...",
    "permissions": [
        FilesystemPermission(
            operations=["read"],
            paths=["/data/**"],
            mode="allow",
        ),
    ],
}

5. 复合后端（CompositeBackend）与可执行后端

可执行后端 （isSandboxBackend 返回 true，如 SandboxBackend、LocalShellBackend）配合权限使用时，需特别注意：

场景	行为
可执行后端 + 权限 + execute 工具启用	抛出 ConfigurationError（因为 Shell 命令可绕过基于路径的权限规则）
可执行后端 + 权限 + execute 工具禁用	正常工作
CompositeBackend + 权限路径限定到路由前缀	正常工作

⚠️ 重要 ：execute 工具不受权限规则约束------Shell 命令可以访问任何路径，无论基于路径的权限规则如何配置。

6. 权限 vs. 后端策略钩子

对比维度	permissions	后端策略钩子（Backend Policy Hooks）
适用范围	仅内置文件系统工具	所有文件系统操作（含自定义工具）
控制粒度	基于路径的允许/拒绝	自定义验证逻辑（速率限制、审计日志、内容检查等）
配置方式	声明式规则列表	编程式钩子函数

7. 示例

7.1 隔离至工作区目录

仅允许在 /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",
        ),
    ],
)

7.2 保护特定文件

拒绝访问 .env 等敏感文件，同时允许工作区其他路径的读写。

agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        # 拒绝访问 .env 和 examples 目录
        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",
        ),
    ],
)

7.3 只读记忆（Read-only Memory）

允许智能体读取记忆文件，但禁止修改。适用于组织级策略或共享知识库------这些内容应由应用代码单独更新，而非由智能体改动。

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

7.4 全部拒绝（Deny All）

拒绝所有读写操作。这是一种严格的基线策略，你可以在其之上叠加更具体的允许规则。

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

7.5 规则顺序

权限规则按首次匹配优先 （first-match-wins）的顺序评估，因此规则的声明顺序至关重要------更具体的规则必须放在更宽泛的规则之前。

# ✅ 正确：先拒绝 .env，再允许 workspace，最后兜底拒绝
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，导致 deny 规则永远无法触发
incorrect_permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",          # 这条规则会先匹配 .env
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",           # 永远无法到达
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

8. 总结

需求	推荐方案
限制智能体读写特定目录	permissions + allow/deny 规则
敏感操作需人工审批	permissions + mode="interrupt"
子智能体独立权限策略	在 SubAgent 中单独配置 permissions
速率限制、审计日志等高级控制	后端策略钩子（Backend Policy Hooks）
沙盒/Shell 后端的命令执行控制	禁用 execute 或使用 CompositeBackend 限定路由