后端 - Docs by LangChain中文

Deep Agents 通过 ls、read_file、write_file、edit_file、delete、glob 和 grep 等工具向代理暴露文件系统接口。这些工具通过一个可插拔的后端运行。read_file 工具原生支持图像文件（.png、.jpg、.jpeg、.gif、.webp），并在所有后端中将其作为多模态内容块返回。沙盒和 LocalShellBackend 还提供了一个 execute 工具。本页将解释如何：

选择一个后端
将不同的路径路由到不同的后端
实现自定义后端
为文件系统访问设置权限
遵循后端协议

当您在 LangSmith 部署上部署时，系统会自动配置一个存储。使用 LangSmith 追踪来调试文件路径、权限拒绝和跨线程存储问题。请按照可观测性快速入门指南进行设置。我们建议您同时设置 LangSmith 引擎，它可以监控您的追踪、检测问题并提出修复建议。

快速入门

这里有一些预构建的文件系统后端，您可以快速地将其与您的深度代理一起使用：

内置后端	描述
默认	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash")` 线程作用域。代理的默认文件系统后端存储在 `langgraph` 状态中。文件在线程内跨轮次持久化（通过您的检查点器），并且不跨线程共享。
本地文件系统持久化	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash", backend=FilesystemBackend(root_dir="/Users/nh/Desktop/"))` 这使得深度代理可以访问您本地机器的文件系统。您可以指定代理可以访问的根目录。请注意，任何提供的 `root_dir` 必须是绝对路径。通常，将其包装在 CompositeBackend 中，以将代理内部数据（卸载的工具结果、对话历史记录）与您的项目文件分开。
持久存储（LangGraph 存储）	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash", backend=StoreBackend())` 这使得代理可以访问_跨线程持久化_的长期存储。这非常适合存储适用于代理多次执行的长期记忆或指令。
上下文中心	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash", backend=ContextHubBackend("my-agent"))` 将文件持久存储在 LangSmith 中心仓库中，无需配置单独的 LangGraph 存储。
沙盒	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash", backend=sandbox)` 在隔离环境中执行代码。沙盒提供文件系统工具以及用于运行 Shell 命令的 `execute` 工具。可从 LangSmith、AgentCore、Daytona、Deno、E2B、Modal、Runloop 或本地 VFS 中选择。
本地 Shell	`agent = create_deep_agent(model="google_genai:gemini-3.6-flash", backend=LocalShellBackend(root_dir=".", env={"PATH": "/usr/bin:/bin"}))` 直接在宿主机上进行文件系统和 Shell 执行操作。无隔离——仅在受控的开发环境中使用。请参阅下面的安全注意事项。
组合	默认为线程作用域，`/memories/` 跨线程持久化。组合后端具有最大的灵活性。您可以指定文件系统中的不同路径指向不同的后端。有关可直接粘贴的示例，请参阅下面的组合路由。

内置后端

StateBackend

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.6-flash")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="openai:gpt-5.5")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="openrouter:z-ai/glm-5.2")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="fireworks:accounts/fireworks/models/glm-5p2")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="baseten:zai-org/GLM-5.2")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，我们提供一个 StateBackend
agent = create_deep_agent(model="ollama:north-mini-code-1.0")

# 实际上，其底层实现类似如下
agent2 = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

工作原理：

通过 StateBackend 将文件存储在当前线程的 LangGraph 代理状态中。
通过检查点在同一线程的多个代理轮次中持久化。文件不跨线程共享。

设计为在图内使用。在图运行之外调用后端方法（例如 state_backend.upload_files(...)）将不会生效，直到图执行为止。

最适合：

用于代理写入中间结果的草稿本。
自动淘汰大型工具输出，代理随后可以分块读回。

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

FilesystemBackend（本地磁盘）

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

此授权代理具有直接的文件系统读/写访问权限。请谨慎使用，并仅在适当的环境中使用。适用用例：

本地开发 CLI（编码助手、开发工具）
CI/CD 管道（请参阅下面的安全注意事项）

不适用用例：

Web 服务器或 HTTP API - 请改用 StateBackend、StoreBackend 或沙盒后端

安全风险：

代理可以读取任何可访问的文件，包括密钥（API 密钥、凭据、.env 文件）
结合网络工具，密钥可能通过 SSRF 攻击被泄露
文件修改是永久且不可逆的

推荐的保护措施：

启用人机协作 (HITL) 中间件以审查敏感操作。
将密钥排除在可访问的文件系统路径之外（尤其是在 CI/CD 中）。
对于需要文件系统交互的生产环境，请使用沙盒后端。
务必在设置 root_dir 时使用 virtual_mode=True，以启用基于路径的访问限制（阻止 ..、~ 以及根目录外的绝对路径）。请注意，默认值（virtual_mode=False）即使设置了 root_dir 也不提供安全性。

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

工作原理：

在可配置的 root_dir 下读写真实文件。
您可以选择性地设置 virtual_mode=True 以在 root_dir 下沙盒化和规范化路径。
使用安全的路径解析，尽可能防止不安全的符号链接遍历，可以使用 ripgrep 进行快速 grep。

最适合：

您机器上的本地项目
CI 沙盒
挂载的持久卷

对于大多数用例，请将 FilesystemBackend 包装在 CompositeBackend 中。Deep Agents 会自动将内部数据写入后端，包括卸载的大型工具结果（位于 /large_tool_results/ 下）和对话历史记录（位于 /conversation_history/ 下）。当您单独使用 FilesystemBackend 时，这些内部文件将写入 root_dir 下的真实磁盘，将代理工件与您的项目文件混合。使用 CompositeBackend 将您的项目目录路由到 FilesystemBackend，同时将内部路径保留在临时的 StateBackend 存储中：

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

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/workspace/": FilesystemBackend(root_dir="/path/to/project", virtual_mode=True),
        },
    )
)

通过这种方式，代理在 /workspace/ 下的读写操作会指向真实磁盘，而卸载的工具结果和其他内部数据则保留在临时状态中。有关更多路由模式，请参阅路由到不同的后端。

LocalShellBackend（本地 Shell）

此授权代理具有直接的文件系统读/写访问权限以及在您的宿主机上不受限制的 Shell 执行能力。请极其谨慎使用，并仅在适当的环境中使用。适用用例：

本地开发 CLI（编码助手、开发工具）
您信任代理代码的个人开发环境
具有适当密钥管理的 CI/CD 管道

不适用用例：

生产环境（如 Web 服务器、API、多租户系统）
处理不受信任的用户输入或执行不受信任的代码

安全风险：

代理可以使用您的用户权限执行任意 Shell 命令
代理可以读取任何可访问的文件，包括密钥（API 密钥、凭据、.env 文件）
密钥可能暴露
文件修改和命令执行是永久且不可逆的
命令直接在您的宿主系统上运行
命令可以消耗无限的 CPU、内存、磁盘资源

推荐的保护措施：

启用人机协作 (HITL) 中间件在执行前审查并批准操作。这是强烈推荐的。
仅在专用开发环境中运行。切勿在共享或生产系统上使用。
对于需要 Shell 执行的生产环境，请使用沙盒后端。

注意： 当启用 Shell 访问时，virtual_mode=True 不提供安全性，因为命令可以访问系统上的任何路径。

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

工作原理：

扩展 FilesystemBackend，增加了用于在宿主机上运行 Shell 命令的 execute 工具。
使用 subprocess.run(shell=True) 直接在您的机器上运行命令，没有沙盒化。
支持 timeout（默认 120 秒）、max_output_bytes（默认 100,000）、env 和 inherit_env 用于环境变量。
Shell 命令使用 root_dir 作为工作目录，但可以访问系统上的任何路径。

最适合：

本地编码助手和开发工具
当您信任代理时，在开发过程中快速迭代

StoreBackend（LangGraph 存储）

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 适用于本地开发；在LangSmith部署中可省略
)

部署到 LangSmith 部署时，请省略 store 参数。平台会自动为您的代理配置一个存储。

namespace 参数控制数据隔离。对于多用户部署，始终设置一个命名空间工厂以按用户或租户隔离数据。

工作原理：

StoreBackend 将文件存储在运行时提供的 LangGraph BaseStore 中，从而实现跨线程的持久存储。

最适合：

当您已经在使用配置好的 LangGraph 存储运行时（例如，Redis、Postgres 或 BaseStore 背后的云实现）。
当您通过 LangSmith 部署部署代理时（系统会自动为您的代理配置一个存储）。

命名空间工厂

命名空间工厂控制 StoreBackend 读写数据的位置。它接收一个 LangGraph Runtime 并返回一个用作存储命名空间的字符串元组。使用命名空间工厂可以在用户、租户或助手之间隔离数据。在构造 StoreBackend 时，将命名空间工厂传递给 namespace 参数：

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

Runtime 提供：

rt.context — 用户通过 LangGraph 的上下文模式传递的上下文（例如，user_id）
rt.server_info — 在 LangGraph Server 上运行时的服务器特定元数据（助手 ID、图 ID、认证用户）
rt.execution_info — 执行标识信息（线程 ID、运行 ID、检查点 ID）

Runtime 参数在 deepagents>=0.5.2 中可用。早期的 0.5.x 版本传递的是 BackendContext — 请参阅下面的从 BackendContext 迁移。rt.server_info 和 rt.execution_info 需要 deepagents>=0.5.0。

常见的命名空间模式：

from deepagents.backends import StoreBackend

# 按用户：每个用户获得自己隔离的存储
backend = StoreBackend(
    namespace=lambda rt: (rt.server_info.user.identity,),
)

# 按助手：同一助手的所有用户共享存储
backend = StoreBackend(
    namespace=lambda rt: (
        rt.server_info.assistant_id,
    ),
)

# 按线程：存储作用域限于单个对话
backend = StoreBackend(
    namespace=lambda rt: (
        rt.execution_info.thread_id,
    ),
)

您可以组合多个组件来创建更具体的范围 — 例如，(user_id, thread_id) 用于按用户按对话隔离，或者添加后缀如 "filesystem" 以在同一范围使用多个存储命名空间时进行区分。命名空间组件必须仅包含字母数字字符、连字符、下划线、点、@、+、冒号和波浪号。为防止 glob 注入，拒绝使用通配符（*、?）。

namespace 参数在 v0.5.0 中将是必需的。对于新代码，请始终显式设置它。

当未提供命名空间工厂时，旧的默认行为使用来自 LangGraph 配置元数据的 assistant_id。这意味着同一助手的所有用户共享相同的存储。对于多用户准备生产环境，始终提供一个命名空间工厂。

ContextHubBackend

开始之前： ContextHubBackend 需要在 LangSmith 中设置一个上下文中心仓库。如果您不熟悉代理仓库和技能仓库，请先阅读上下文中心概念页面。

ContextHubBackend 将您的代理文件系统存储在 LangSmith 上下文中心仓库中。它可以使用独立仓库或链接到技能仓库的代理仓库。 仓库结构： 在上下文中心，一个_代理仓库_保存代理的顶层指令和配置（例如，AGENTS.md、tools.json）。它可以链接到一个或多个_技能仓库_，每个技能仓库打包为一个可重用的能力（例如，包含电子邮件格式化或代码审查指令的 SKILL.md）。当您传递 ContextHubBackend("my-agent") 时，后端将代理仓库挂载到文件系统根目录；链接的技能仓库显示为 /skills/ 下的子目录。这意味着您代理的上下文故意分布在多个仓库中：每个代理一个仓库，每个技能单独的仓库。这种分离使得技能可以独立于多个代理进行版本控制、共享和重用。如果这感觉过于分散，请参阅链接仓库了解其原理。

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    backend=ContextHubBackend("my-agent"),
)

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    backend=ContextHubBackend("my-agent"),
)

使用 owner/name 或 name 格式的仓库标识符构造它。

使用 ContextHubBackend 前请设置 LANGSMITH_API_KEY。

工作原理：

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

行为和限制：

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

最适合：

LangSmith 原生的持久文件系统持久化，无需单独连接 LangGraph BaseStore。
受益于中心提交历史记录的文件系统更改的工作流。

CompositeBackend（路由器）

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.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
    
agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # 传递给 create_deep_agent 的 store，而非 backend
)

工作原理：

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

最适合：

当您希望为代理同时提供线程作用域和跨线程存储时，CompositeBackend 允许您同时提供 StateBackend 和 StoreBackend
当您有多个信息源想要作为单个文件系统的一部分提供给代理时。
- 例如，您将长期记忆存储在一个存储中的 /memories/ 下，并且您还有一个自定义后端，其中包含可通过 /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.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": FilesystemBackend(root_dir="/deepagents/myagent", virtual_mode=True),
        },
    )
)

行为：

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

注意：

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

自定义后端

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

实现后端协议

子类化 BackendProtocol 并实现以下方法：

方法	签名	功能
`ls`	`(path: str) -> LsResult`	列出给定路径下的文件和目录。
`read`	`(file_path: str, offset: int, limit: int) -> ReadResult`	返回文件内容，可选择分页。
`write`	`(file_path: str, content: str) -> WriteResult`	创建或覆盖一个文件。
`edit`	`(file_path: str, old_string: str, new_string: str, replace_all: bool) -> EditResult`	在现有文件中查找和替换。
`glob`	`(pattern: str, path: str	None) -> GlobResult`	返回匹配 glob 模式的路径。
`grep`	`(pattern: str, path: str	None, glob: str	None) -> GrepResult`	在文件内容中搜索字面字符串。
`delete`	`(file_path: str) -> DeleteResult`	可选。删除文件或递归删除目录。如果后端不支持删除，该工具将在请求时自动对模型隐藏。

要同时支持 execute 工具（运行 Shell 命令），请实现 SandboxBackendProtocol，它用 execute 方法扩展了 BackendProtocol。始终返回带有 error 字段的结构化结果类型用于失败情况。不要引发异常。

示例：S3 风格后端骨架

此骨架将文件系统路径映射到对象键。用您的存储客户端的列表、读取、搜索、上传和读-修改-写操作填充每个方法。

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.6-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",
        ),
    ],
)

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

添加策略钩子

对于基于路径的允许/拒绝规则之外的自定义验证逻辑（速率限制、审计日志、内容检查），通过子类化或包装后端来强制执行企业规则。阻止对选定前缀下的写入/编辑（子类化）：

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)

从后端工厂迁移

后端工厂模式自 deepagents 0.5.0 起已弃用。请直接传递预构造的后端实例，而不是工厂函数。

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

发生了什么变化

之前（已弃用）	之后
`backend=lambda rt: StateBackend(rt)`	`backend=StateBackend()`
`backend=lambda rt: StoreBackend(rt)`	`backend=StoreBackend()`
`backend=lambda rt: CompositeBackend(default=StateBackend(rt), ...)`	`backend=CompositeBackend(default=StateBackend(), ...)`
`backend: (config) => new StateBackend(config)`	`backend: new StateBackend()`
`backend: (config) => new StoreBackend(config)`	`backend: new StoreBackend()`

已弃用的 API

已弃用	替代方案
在 `create_deep_agent` 中向 `backend=` 传递可调用对象	直接传递后端实例
`StateBackend(runtime)` 上的 `runtime` 构造函数参数	`StateBackend()`（无需参数）
`StoreBackend(runtime)` 上的 `runtime` 构造函数参数	`StoreBackend()` 或 `StoreBackend(namespace=..., store=...)`
`WriteResult` 和 `EditResult` 上的 `files_update` 字段	状态写入现在由后端内部处理
中间件写入/编辑工具中的 `Command` 包装	工具返回纯字符串；不需要 `Command(update=...)`

工厂模式在运行时仍然有效，并会发出弃用警告。在下一个主要版本之前更新您的代码以使用直接实例。

迁移示例

# 之前（已弃用）
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

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

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

从 `BackendContext` 迁移

在 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 没有直接替代。命名空间信息在运行期间应是只读且稳定的，而状态是可变的且逐步变化的 — 从状态派生命名空间有风险，导致数据最终位于不一致的键下。如果您有一个需要读取代理状态的用例，请提交问题。

# 之前（已弃用，v0.7 中移除）
StoreBackend(
    namespace=lambda ctx: (ctx.runtime.context.user_id,),
)

# 之后
StoreBackend(
    namespace=lambda rt: (rt.server_info.user.identity,),
)

协议参考

后端必须实现 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
- 除非 replace_all=True，否则强制 old_string 唯一。如果未找到，返回错误。成功时包括 occurrences。

支持类型：

LsResult(error, entries) — entries 成功时为 list[FileInfo]，失败时为 None。
ReadResult(error, file_data) — file_data 成功时为 FileData 字典，失败时为 None。
GrepResult(error, matches) — matches 成功时为 list[GrepMatch]，失败时为 None。
GlobResult(error, matches) — matches 成功时为 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" 或 "base64"), created_at, modified_at。 :::

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

后端

快速入门

内置后端

StateBackend

FilesystemBackend（本地磁盘）

LocalShellBackend（本地 Shell）

StoreBackend（LangGraph 存储）

命名空间工厂

ContextHubBackend

CompositeBackend（路由器）

指定一个后端

路由到不同的后端

自定义后端

实现后端协议

权限

添加策略钩子

从后端工厂迁移

发生了什么变化

已弃用的 API

迁移示例

从 `BackendContext` 迁移

协议参考

​快速入门

​内置后端

​StateBackend

​FilesystemBackend（本地磁盘）

​LocalShellBackend（本地 Shell）

​StoreBackend（LangGraph 存储）

​命名空间工厂

​ContextHubBackend

​CompositeBackend（路由器）

​指定一个后端

​路由到不同的后端

​自定义后端

​实现后端协议

​权限

​添加策略钩子

​从后端工厂迁移

​发生了什么变化

​已弃用的 API

​迁移示例

​从 BackendContext 迁移

​协议参考

快速入门

内置后端

StateBackend

FilesystemBackend（本地磁盘）

LocalShellBackend（本地 Shell）

StoreBackend（LangGraph 存储）

命名空间工厂

ContextHubBackend

CompositeBackend（路由器）

指定一个后端

路由到不同的后端

自定义后端

实现后端协议

权限

添加策略钩子

从后端工厂迁移

发生了什么变化

已弃用的 API

迁移示例

从 `BackendContext` 迁移

协议参考