深度代理通过工具向代理暴露文件系统界面，例如 ls, read_file, write_file, edit_file, glob和 grep。这些工具通过可插拔后端运行。 read_file 工具原生支持图像文件（.png, .jpg, .jpeg, .gif, .webp）跨所有后端，返回它们为多模态内容块。

沙箱和LocalShellBackend也提供了一个 execute tool. 本页说明如何：

• - 选择后端
• - 将不同路径路由到不同后端
• - 实现自定义后端
• - 设置权限 对文件系统访问
• - 符合后端协议

快速入门

以下是几个预构建的文件系统后端，您可以使用它们与深度代理快速配合：

graph TB
    Tools[Filesystem Tools] --> Backend[Backend]

    Backend --> State[State]
    Backend --> Disk[Filesystem]
    Backend --> Store[Store]
    Backend --> ContextHub[Context Hub]
    Backend --> Sandbox[Sandbox]
    Backend --> LocalShell[Local Shell]
    Backend --> Composite[Composite]
    Backend --> Custom[Custom]

    Composite --> Router{Routes}
    Router --> State
    Router --> Disk
    Router --> Store
    Router --> ContextHub

    Sandbox --> Execute["#43; execute tool"]
    LocalShell --> Execute["#43; execute tool"]

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class Tools trigger
    class Backend,State,Disk,Store,ContextHub,Sandbox,LocalShell,Composite,Custom process
    class Router decision
    class Execute output

内置后端

状态后端

工作原理： - 通过 @[ 将文件存储在当前线程的 LangGraph 代理状态中StateBackend]. - 通过检查点跨同一线程的多个代理轮次持久化。文件不在线程之间共享。

最适合： - 供代理写入中间结果的草稿板。 - 自动清除大型工具输出，然后代理可以逐块读回。

请注意，此后端在主管代理和子代理之间共享，子代理写入的任何文件都将保留在 LangGraph 代理状态中 即使该子代理的执行完成。这些文件将继续对主管代理和其他子代理可用。

文件系统后端（本地磁盘）

FilesystemBackend 在可配置的根目录下读取和写入真实文件。

工作原理： - Reads/writes real files under a configurable root_dir. - 您可以选择设置 virtual_mode=True 来沙箱化并规范化 root_dir. - 使用安全路径解析，尽可能防止不安全的符号链接遍历，可使用 ripgrep 进行快速 grep.

最适合： - 本地项目 - CI 沙箱 - 挂载的持久卷

LocalShellBackend（本地 shell）

工作原理： - 扩展 FilesystemBackend 并配合 execute 工具在主机上运行 shell 命令。 - 命令使用 subprocess.run(shell=True) 直接在你的机器上运行，无沙盒隔离。 - 支持 timeout （默认 120 秒）， max_output_bytes （默认 100,000）， env和 inherit_env 用于环境变量。 - Shell 命令使用 root_dir 作为工作目录，但可以访问系统上的任何路径。

最佳用途： - 本地编码助手和开发工具 - 在开发过程中需要快速迭代且信任代理时

StoreBackend (LangGraph 存储)

工作原理： - StoreBackend 将文件存储在运行时提供的 LangGraph BaseStore 中，实现跨线程持久化存储。

最佳用途： - 当你已经使用配置的 LangGraph 存储运行时（例如 Redis、Postgres 或 BaseStore). - 当你通过 LangSmith 部署 部署你的代理时（系统会自动为你的代理配置存储）。

命名空间工厂

命名空间工厂控制 StoreBackend 读取和写入数据的位置。它接收一个 LangGraph Runtime 并返回一个字符串元组，用作存储命名空间。使用命名空间工厂来隔离用户、租户或助手之间的数据。

在构造 namespace 时将命名空间工厂传递给 StoreBackend:

NamespaceFactory = Callable[[Runtime], tuple[str, ...]]

Runtime provides: - rt.context — 通过 LangGraph 的 上下文 schema 传递的用户提供上下文（例如， user_id) - rt.server_info — 在 LangGraph Server 上运行时的服务器特定元数据（助手 ID、图 ID、已认证用户） - rt.execution_info — 执行身份信息（线程 ID、运行 ID、检查点 ID）

常见的命名空间模式：

from deepagents.backends import StoreBackend

# Per-user: each user gets their own isolated storage
backend = StoreBackend(
    namespace=lambda rt: (rt.server_info.user.identity,),  # [!code highlight]
)

# Per-assistant: all users of the same assistant share storage
backend = StoreBackend(
    namespace=lambda rt: (
        rt.server_info.assistant_id,  # [!code highlight]
    ),
)

# Per-thread: storage scoped to a single conversation
backend = StoreBackend(
    namespace=lambda rt: (
        rt.execution_info.thread_id,  # [!code highlight]
    ),
)

您可以组合多个组件来创建更具体的作用域 — 例如， (user_id, thread_id) 用于每个用户每个会话的隔离，或者附加后缀如 "filesystem" 用于在相同作用域使用多个存储命名空间时进行区分。

命名空间组件只能包含字母数字字符、连字符、下划线、点、 @, +、冒号和波浪号。通配符（*, ?）会被拒绝以防止 glob 注入。

，请始终提供命名空间工厂。

ContextHubBackend 页面，如果您不熟悉 agent 代码库和 skill 代码库的话。

将您的 agent 的文件系统存储在 LangSmith Context Hub 代码库中。它可以使用独立的代码库或链接到 skill 代码库的 agent 代码库。 代码库结构： _在 Context Hub 中，_ agent 代码库 AGENTS.md, tools.json保存 agent 的顶级指令和配置（例如， _）。它可以链接到一个或多个_skill 代码库 SKILL.md ，每个代码库都打包为可重用的功能（例如， ContextHubBackend("my-agent")，后端将 agent 仓库挂载到文件系统根目录；链接的技能仓库显示为以下子目录 /skills/.

这意味着您的 agent 上下文有意分散在多个仓库中：每个 agent 一个仓库，每个技能一个独立仓库。这种分离允许技能独立地进行版本控制、共享和跨多个 agent 重用。如果这感觉分散，请参阅 链接的仓库 以了解原理。

使用仓库标识符构造它， owner/name or name format.

工作原理： - 在首次使用时延迟拉取 Hub 仓库树，然后从内存缓存中提供读取服务。 - 将写入和编辑持久化为 Hub 提交，并在成功提交后更新缓存。 - 使用乐观的父提交写入（parent_commit）：每次推送都针对最新已知的提交哈希。

行为和限制： - 如果仓库不存在，首次拉取被视为空；首次成功写入可以创建仓库。 - 如果另一个写入者先推进了仓库，您的过时父提交写入可能会失败。发生冲突时重新拉取并重试。 - upload_files() 接受 UTF-8 文本。非 UTF-8 文件按路径被拒绝，并显示 invalid_path.

最适用于： - LangSmith 原生的持久文件系统存储，无需单独连接 LangGraph BaseStore. - 从文件系统变更的 Hub 提交历史中受益的工作流。

CompositeBackend（路由器）

工作原理： - @[CompositeBackend根据路径前缀将文件操作路由到不同的后端。 - 保留列表和搜索结果中的原始路径前缀。

最适用于： - 当你想要为你的代理提供线程作用域和跨线程存储时，可以使用 CompositeBackend 允许你同时提供 StateBackend 和 StoreBackend - 当你有多个想要作为单一文件系统提供给代理的信息源时。 - 例如，你有长期记忆存储在 /memories/ in one Store and you also have a custom backend that has documentation accessible at /docs/.

指定后端

• - 将后端实例传递给 create_deep_agent(model=..., backend=...)。文件系统中间件将其用于所有工具。
• - 后端必须实现 BackendProtocol （例如， StateBackend(), FilesystemBackend(root_dir="."), StoreBackend(), ContextHubBackend("my-agent")).
• - 如果省略，默认值是 StateBackend().

路由至不同的后端

将命名空间的不同部分路由到不同的后端。常用于持久化 /memories/* 跨线程使用，同时让其他内容保持线程作用域。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, FilesystemBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": FilesystemBackend(root_dir="/deepagents/myagent", virtual_mode=True),
        },
    )
)

Behavior: - /workspace/plan.md → StateBackend （线程作用域） - /memories/agent.md → FilesystemBackend 在...下 /deepagents/myagent - ls, glob, grep 聚合结果并显示原始路径前缀。

Notes: - 更长的前缀优先（例如，路由 "/memories/projects/" 可以覆盖 "/memories/"). - 对于 StoreBackend 路由，请确保通过 create_deep_agent(model=..., store=...) 或由平台提供存储。 - Deep Agents 将内部数据（卸载的工具结果、对话历史）写入默认后端。使用 StateBackend 作为默认值，以保持这些产物为临时性的，避免将它们写入磁盘或持久化存储。请参阅 FilesystemBackend 技巧 获取完整示例。

自定义后端

实现自定义后端，将 Deep Agents 连接到数据库、对象存储和远程文件系统等存储系统。请参阅 社区构建的后端 获取示例。

实现后端协议

子类 BackendProtocol 并实现以下方法：

要同时支持 execute 工具（运行 shell 命令），实现 SandboxBackendProtocol 而不是，它扩展了 BackendProtocol 具有 execute method.

始终返回带有 error 字段的结构化结果类型用于失败情况。不要抛出异常。

from deepagents.backends.protocol import (
    BackendProtocol,
    EditResult,
    GlobResult,
    GrepResult,
    LsResult,
    ReadResult,
    WriteResult,
)

class S3Backend(BackendProtocol):
    def __init__(self, bucket: str, prefix: str = ""):
        self.bucket = bucket
        self.prefix = prefix.rstrip("/")

    def _key(self, path: str) -> str:
        return f"{self.prefix}{path}"

    def ls(self, path: str) -> LsResult:
        ...

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult:
        ...

    def grep(self, pattern: str, path: str | None = None, glob: str | None = None) -> GrepResult:
        ...

    def glob(self, pattern: str, path: str | None = None) -> GlobResult:
        ...

    def write(self, file_path: str, content: str) -> WriteResult:
        ...

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        ...

权限

使用 权限 以声明方式控制代理可以读取或写入的文件和目录。权限适用于内置文件系统工具，并在调用后端之前进行评估。

from deepagents import create_deep_agent, FilesystemPermission

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    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=["/policies/**"],
            mode="deny",
        ),
    ],
)

有关完整的选项集（包括规则排序、子代理权限和复合后端交互），请参阅 权限指南.

添加策略钩子

For custom validation logic beyond path-based allow/deny rules (rate limiting, audit logging, content inspection), enforce enterprise rules by subclassing or wrapping a backend.

Block writes/edits under selected prefixes (subclass):

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

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)

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        if any(file_path.startswith(p) for p in self.deny_prefixes):
            return EditResult(error=f"Edits are not allowed under {file_path}")
        return super().edit(file_path, old_string, new_string, replace_all)

通用包装器（适用于任何后端）：

from deepagents.backends.protocol import (
    BackendProtocol, WriteResult, EditResult, LsResult, ReadResult, GrepResult, GlobResult,
)

class PolicyWrapper(BackendProtocol):
    def __init__(self, inner: BackendProtocol, deny_prefixes: list[str] | None = None):
        self.inner = inner
        self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in (deny_prefixes or [])]

    def _deny(self, path: str) -> bool:
        return any(path.startswith(p) for p in self.deny_prefixes)

    def ls(self, path: str) -> LsResult:
        return self.inner.ls(path)

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult:
        return self.inner.read(file_path, offset=offset, limit=limit)
    def grep(self, pattern: str, path: str | None = None, glob: str | None = None) -> GrepResult:
        return self.inner.grep(pattern, path, glob)
    def glob(self, pattern: str, path: str | None = None) -> GlobResult:
        return self.inner.glob(pattern, path)
    def write(self, file_path: str, content: str) -> WriteResult:
        if self._deny(file_path):
            return WriteResult(error=f"Writes are not allowed under {file_path}")
        return self.inner.write(file_path, content)
    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        if self._deny(file_path):
            return EditResult(error=f"Edits are not allowed under {file_path}")
        return self.inner.edit(file_path, old_string, new_string, replace_all)

从后端工厂迁移

以前，像 StateBackend 和 StoreBackend 这样的后端需要一个接收运行时对象的工厂函数，因为它们需要运行时上下文（状态、存储）才能操作。后端现在通过 LangGraph 的 get_config(), get_store()和 get_runtime() 辅助函数来内部解析此上下文，因此您可以直接传递实例。

发生了什么变化

已弃用的 API

迁移示例

# Before (deprecated)
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=lambda rt: CompositeBackend(
        default=StateBackend(rt),
        routes={"/memories/": StoreBackend(rt, namespace=lambda rt: (rt.server_info.user.identity,))},
    ),
)

# After
agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={"/memories/": StoreBackend(namespace=lambda rt: (rt.server_info.user.identity,))},
    ),
)

从迁移 BackendContext

In deepagents>=0.5.2 （Python）和 deepagents>=1.9.1 （TypeScript），命名空间工厂直接接收 LangGraph Runtime 而不是 BackendContext 包装器。旧的 BackendContext 形式仍然通过向后兼容 .runtime 和 .state 访问器来工作，但这些访问器会发出弃用警告，将在 deepagents>=0.7.

发生了什么变化：

• - 工厂参数现在是一个 Runtime，而不是 BackendContext.
• - 删除 .runtime 访问器——例如， ctx.runtime.context.user_id 变为 rt.server_info.user.identity.
• - 没有直接替代 ctx.state的方案。命名空间信息应该是只读的，在运行期间保持稳定，而状态是可变的且每步都会变化——从中派生命名空间可能导致数据最终出现在不一致的键下。如果您有需要读取代理状态的使用场景，请 提交问题.

# Before (deprecated, removed in v0.7)
StoreBackend(
    namespace=lambda ctx: (ctx.runtime.context.user_id,),  # [!code --]
)

# After
StoreBackend(
    namespace=lambda rt: (rt.server_info.user.identity,),  # [!code ++]
)

协议参考

后端必须实现 BackendProtocol.

必需方法： - ls(path: str) -> LsResult - 返回条目，至少包含 path。如有则包含 is_dir, size, modified_at 。按 path 排序以确保确定性输出。 - read(file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult - 成功时返回文件数据。文件缺失时，返回 ReadResult(error="Error: File '/x' not found"). - grep(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> GrepResult - 返回结构化匹配项。出错时，返回 GrepResult(error="...") （不要抛出异常）。 - glob(pattern: str, path: Optional[str] = None) -> GlobResult - 将匹配的文件作为 FileInfo 条目返回（无匹配则为空列表）。 - write(file_path: str, content: str) -> WriteResult - 仅用于创建。冲突时，返回 WriteResult(error=...)。成功时，设置 path ，对于状态后端还需设置 files_update={...}；外部后端应使用 files_update=None. - edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult - 强制 old_string 的唯一性，除非 replace_all=True。如未找到，返回错误。成功时包含 occurrences 。

支持的类型： - LsResult(error, entries) — entries is a list[FileInfo] 成功时， None 失败时。 - ReadResult(error, file_data) — file_data is a FileData 成功时返回字典， None 失败时。 - GrepResult(error, matches) — matches is a list[GrepMatch] 成功时， None 失败时。 - GlobResult(error, matches) — matches is a list[FileInfo] 成功时， None 失败时。 - WriteResult(error, path, files_update) - EditResult(error, path, files_update, occurrences) - FileInfo 字段： path （必填），可选 is_dir, size, modified_at. - GrepMatch 字段： path, line, text. - FileData 字段： content (str)， encoding ("utf-8" or "base64"), created_at, modified_at. :::