跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

使用声明式权限规则来控制智能体可以读取或写入哪些文件和目录。将规则列表传递给 permissions=，智能体的内置文件系统工具将遵循这些规则。
权限功能需要 deepagents>=0.5.2。
权限仅适用于内置文件系统工具（ls、read_file、glob、grep、write_file、edit_file）。不涵盖访问文件系统的自定义工具和 MCP 工具。权限也不适用于 沙盒后端，因为它们通过 execute 工具支持任意命令执行。
当您需要针对内置文件系统工具进行基于路径的允许/拒绝规则时，请使用 permissions。当您需要自定义验证逻辑（速率限制、审计日志、内容检查）或需要控制自定义工具时，请使用 后端策略钩子。

​
基本用法

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

# Read-only agent: deny all writes
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/ 下读取和写入，拒绝所有其他路径 
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",
        ),
    ],
)

​
规则排序

由于采用首次匹配胜出原则，规则顺序非常重要。请将更具体的规则放在更广泛的规则之前。 
# Correct: deny .env, allow workspace, deny everything else
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",
    ),
]

# Bug: /workspace/** matches .env first, so the deny never triggers
permissions=[
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",  # never reached
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

​
子智能体权限

子智能体默认继承父智能体的权限。要为子智能体提供不同的权限，请在其规范中设置 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": "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 命令进行的文件系统访问。将权限限定在特定路由的 后端 可以避免这种冲突。 
from deepagents.backends import CompositeBackend

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

# Works: permissions are scoped to the /memories/ route
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/memories/**"],
            mode="deny",
        ),
    ],
)
包含任何路由之外路径的权限会引发 NotImplementedError。 
# Raises NotImplementedError: /workspace/** hits the sandbox default
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/workspace/**"],
            mode="deny",
        ),
    ],
)

# Also raises: /** covers both routes and the default
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["read"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.