Deep Agents 文件系统后端完全指南

在构建强大的 AI Agent 时，一个关键能力是让它们能够与文件系统交互。无论是读取项目文件、写入日志、还是保存长期记忆，文件系统都是 Agent 工作流中不可或缺的一部分。

Deep Agents 框架通过一套精巧的"后端（Backends）"系统，为我们提供了极大的灵活性。你可以选择简单的临时存储，也可以连接到本地磁盘、数据库，甚至自定义虚拟文件系统。本文将带你全面了解这些选项，并提供可直接运行的代码示例。

1. 核心概念：Agent 的文件系统工具

Deep Agents 默认为你的 Agent 提供了一套文件系统工具，包括：

• ls: 列出目录内容
• read_file: 读取文件
• write_file: 写入文件
• edit_file: 编辑文件
• glob: 路径匹配
• grep: 文本搜索

这些工具背后都由一个"后端（Backend）"驱动。你可以通过 create_deep_agent 函数的 backend 参数来指定使用哪个后端。

2. 内置后端详解与代码示例

(1) StateBackend (默认的临时存储)

这是最简单、最安全的后端。所有文件都存储在 LangGraph 的状态（state）中，仅在单个对话线程（thread）内有效。对话结束后，数据会自动消失。

适用场景：作为 Agent 的"草稿纸"，用于存放中间计算结果。

from deepagents import create_deep_agent

# 方法一：使用默认后端（即 StateBackend）
agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview")

# 方法二：显式声明
from deepagents.backends import StateBackend
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StateBackend()
)

(2) FilesystemBackend (访问本地磁盘)

这个后端允许 Agent 直接读写你机器上的真实文件。请务必注意安全风险！

重要安全提示：

• 切勿在 Web 服务器或处理不受信任输入的环境中使用。
• 务必设置 virtual_mode=True 来限制 Agent 只能访问你指定的根目录。

适用场景：本地开发助手、CI/CD 流水线中的自动化脚本。

from deepagents.backends import FilesystemBackend

# 让 Agent 访问当前目录下的文件，并启用安全沙箱模式
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
)

(3) LocalShellBackend (本地 Shell 执行)

这是功能最强大但也最危险的后端。它不仅提供了 FilesystemBackend 的所有功能，还额外增加了一个 execute 工具，允许 Agent 在你的主机上直接执行任意 Shell 命令。

极端警告：

• 仅限在完全受控的本地开发环境中使用。
• Agent 将拥有你当前用户的全部权限，可以做任何事情！

适用场景：完全信任的本地编码助手，用于快速迭代开发。

from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=LocalShellBackend(
        root_dir=".",
        env={"PATH": "/usr/bin:/bin"} # 设置环境变量
    )
)

(4) StoreBackend (跨线程的持久化存储)

当你需要 Agent 的记忆能够跨越多个对话时，StoreBackend 是最佳选择。它利用 LangGraph 的 BaseStore（如 Redis, Postgres）来持久化数据。

关键点：命名空间（Namespace）

为了隔离不同用户或不同 Agent 的数据，你必须提供一个 namespace 工厂函数。

适用场景：部署在 LangSmith 上的生产级 Agent，需要长期记忆。

from langgraph.store.memory import InMemoryStore # 本地开发用内存存储
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StoreBackend(
        # 为每个用户创建独立的存储空间
        namespace=lambda rt: (rt.server_info.user.identity,)
    ),
    store=InMemoryStore() # 在 LangSmith 部署时，此参数会被忽略
)

(5) CompositeBackend (复合路由)

这是最灵活的后端，允许你将不同的路径路由到不同的后端。例如，你可以让 /memories/ 目录使用持久化存储，而其他所有路径使用临时存储。

适用场景：需要同时具备临时工作区和持久化记忆的复杂 Agent。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=CompositeBackend(
        default=StateBackend(), # 默认后端，处理所有未指定的路径
        routes={
            "/memories/": StoreBackend( # 将 /memories/ 下的所有操作路由到 StoreBackend
                namespace=lambda rt: (rt.server_info.user.identity,)
            ),
        }
    ),
    store=InMemoryStore()
)

3. 进阶用法：自定义与安全控制

实现你自己的虚拟文件系统

你可以通过实现 BackendProtocol 接口，将任何数据源（如 S3、PostgreSQL）映射为 Agent 的文件系统。

from deepagents.backends.protocol import BackendProtocol, ReadResult, LsResult

class S3Backend(BackendProtocol):
    def __init__(self, bucket: str):
        self.bucket = bucket

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult:
        # 在这里实现从 S3 读取文件的逻辑
        try:
            # ... 你的 S3 读取代码 ...
            content = "..."
            return ReadResult(file_data={"content": content, "encoding": "utf-8"})
        except Exception as e:
            return ReadResult(error=f"Failed to read {file_path}: {str(e)}")
    
    # 你需要实现 ls, write, edit, grep, glob 等所有方法
    def ls(self, path: str) -> LsResult:
        # 实现列出 S3 对象的逻辑
        ...

添加权限和策略钩子

除了后端本身，你还可以通过 permissions 参数或包装后端类来添加精细的访问控制。

使用权限规则：

from deepagents import FilesystemPermission

agent = create_deep_agent(
    model="...",
    backend=...,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/policies/**"], # 禁止写入 /policies/ 目录
            mode="deny",
        ),
    ],
)

通过子类添加策略：

from deepagents.backends.filesystem import FilesystemBackend
from deepagents.backends.protocol import WriteResult

class GuardedBackend(FilesystemBackend):
    def __init__(self, *, deny_prefixes: list[str], **kwargs):
        super().__init__(**kwargs)
        self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in deny_prefixes]

    def write(self, file_path: str, content: str) -> WriteResult:
        if any(file_path.startswith(p) for p in self.deny_prefixes):
            return WriteResult(error=f"Writes are not allowed under {file_path}")
        return super().write(file_path, content)

总结

Deep Agents 的后端系统为你提供了从简单到复杂的全方位文件系统解决方案。记住以下几点：

1. 安全第一 ：对于 FilesystemBackend 和 LocalShellBackend，永远不要在不安全的环境中使用，并始终开启 virtual_mode。
2. 按需选择 ：临时任务用 StateBackend，本地开发用 FilesystemBackend，生产部署用 StoreBackend 或 Sandboxes。
3. 组合使用 ：CompositeBackend 是构建复杂 Agent 的利器，可以轻松分离临时工作区和持久化记忆。
4. 扩展无限 ：通过实现 BackendProtocol，你可以将 Agent 的能力延伸到任何你能想到的数据源。

现在，你已经掌握了 Deep Agents 文件系统的核心！快去构建你的下一个强大 Agent 吧！

参考文献

https://docs.langchain.com/oss/python/deepagents/backends