> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 权限

> 使用声明式权限规则控制 Deep Agents 的文件系统访问

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

<Note>
  权限功能需要 `deepagents>=0.5.2`。
</Note>

权限仅适用于内置文件系统工具（`ls`、`read_file`、`glob`、`grep`、`write_file`、`edit_file`）。访问文件系统的自定义工具和 MCP 工具不在其覆盖范围内。权限也不适用于[沙箱后端](/oss/python/deepagents/sandboxes)，这些后端支持通过 `execute` 工具执行任意命令。

<Tip>
  当你需要对内置文件系统工具进行**基于路径的允许/拒绝规则**时，请使用 `permissions`。当你需要自定义验证逻辑（速率限制、审计日志、内容检查）或需要控制自定义工具时，请使用[后端策略钩子](/oss/python/deepagents/backends#add-policy-hooks)。
</Tip>

## 基本用法

将 [`FilesystemPermission`](https://reference.langchain.com/python/deepagents/middleware/permissions/FilesystemPermission) 规则列表传递给 [`create_deep_agent`](https://reference.langchain.com/python/deepagents/graph/create_deep_agent)。规则按声明顺序进行评估。第一个匹配的规则生效。如果没有规则匹配，则允许该操作。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import create_deep_agent, FilesystemPermission

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

## 规则结构

每个 `FilesystemPermission` 有三个字段：

| 字段           | 类型                        | 描述                                                                                         |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `operations` | `list["read" \| "write"]` | 此规则适用的操作。`"read"` 涵盖 `ls`、`read_file`、`glob`、`grep`。`"write"` 涵盖 `write_file`、`edit_file`。 |
| `paths`      | `list[str]`               | 用于匹配文件路径的 Glob 模式（例如 `["/workspace/**"]`）。支持 `**` 进行递归匹配和 `{a,b}` 进行交替匹配。                  |
| `mode`       | `"allow" \| "deny"`       | 是允许还是拒绝匹配的操作。默认为 `"allow"`。                                                                |

规则使用首次匹配生效的评估方式：第一个其 `operations` 和 `paths` 与当前调用匹配的规则决定结果。如果没有规则匹配，则**允许**该调用（宽容默认值）。

## 示例

### 隔离到工作区目录

仅允许在 `/workspace/` 下进行读写，拒绝其他所有操作：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

### 保护特定文件

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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",
        ),
    ],
)
```

### 只读记忆

允许代理读取记忆文件，但阻止其修改它们。这对于组织范围的策略或应仅由应用程序代码更新的共享知识库很有用。有关更多上下文，请参阅[只读与可写记忆](/oss/python/deepagents/memory#read-only-vs-writable-memory)。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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",
        ),
    ],
)
```

### 拒绝所有访问

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

### 规则顺序

由于采用首次匹配生效机制，规则顺序很重要。将更具体的规则放在更宽泛的规则之前：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 正确：拒绝 .env，允许 workspace，拒绝其他所有内容
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",
    ),
]
```

## 子代理权限

[子代理](/oss/python/deepagents/subagents)默认继承父代理的权限。要为子代理赋予不同的权限，请在其规范中设置 `permissions` 字段。这将**完全替换**父代理的规则。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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`](https://reference.langchain.com/python/deepagents/backends/composite/CompositeBackend) 时，每个权限路径都必须限定在已知的路由前缀下。沙箱支持任意命令执行，因此仅基于路径的限制无法防止通过 shell 命令访问文件系统。将权限限定在特定路由的[后端](/oss/python/deepagents/backends)下可以避免此冲突。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 引发 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",
        ),
    ],
)
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/permissions.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>