📚 AI 工程与智能体教程站

简体中文

English

简体中文

English

第 03 章 · 文件系统权限与路径边界 ​

本章演示如何把智能体的文件操作限制在 /workspace/ 目录，并保护 /.env 不被修改。

机制与设计选择 ​

permissions 是声明式规则，按声明顺序 first-match-wins，未命中默认允许。规则作用于内置文件工具；FilesystemBackend(virtual_mode=True) 会把路径规范化到 root_dir 下，并阻断 ..、~ 与根外绝对路径。两层要一起理解：权限管“工具层放行”，虚拟文件系统管“路径解析”。

示例 ​

python
import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FilesystemPermission

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(root_dir="/tmp/deepagents-sandbox", virtual_mode=True),
    permissions=[
        FilesystemPermission(operations=["write"], paths=["/.env"], mode="deny"),
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
    ],
    system_prompt="You work inside /workspace. Never touch /.env.",
)
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Write a note to /workspace/notes.txt, then try to modify /.env."}]},
    {"configurable": {"thread_id": "ch03"}},
)
print(result["messages"][-1].content)

运行与验收 ​

需要 API Key。验收看两条：/workspace/notes.txt 写入成功；对 /.env 的写操作被权限层拒绝，模型收到的反馈包含 deny 语义。

容易踩的坑 ​

permissions 只控制内置文件工具；它不限制模型通过其他自定义工具造成的影响。sandbox backend 的 execute 工具不受声明式权限约束，需要靠隔离与网络策略兜底。permissions= 接收 FilesystemPermission 对象（0.7.15 实测不自动转换 dict 字面量，直接传 dict 会报 AttributeError: 'dict' object has no attribute 'mode'）。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 权限规则如何命中？

2. 未命中默认什么？

3. virtual_mode 管什么？

4. execute 受 permissions 约束吗？

动手实践 ​

  1. 让模型尝试写 /outside.txt，观察虚拟模式的拦截信息。
  2. 调整规则顺序，观察 first-match-wins 变化。
  3. 为子智能体配置比父更窄的权限。

官方参考 ​

核验日期：2026-09-17，运行环境：Deep Agents 0.7.15。