DeepAgents : 后端（Backends）

DeepAgents : 后端（Backends）

DeepAgents 提供多种后端实现，用于承载智能体运行逻辑、调度沙箱环境、持久化会话状态。开发者可根据部署场景灵活切换后端，实现原型调试、单机服务、分布式生产环境之间平滑迁移。

1. 开箱即用的后端

DeepAgents 提供了多种预置后端，可直接使用：

后端	说明
StateBackend（默认）	文件存储在 LangGraph 状态中，线程内持久化（通过 Checkpointer），不跨线程共享
FilesystemBackend	直接读写本地磁盘 真实文件，需指定 root_dir
StoreBackend	基于 LangGraph Store 的跨线程持久化存储，适合存放长期记忆或全局指令
ContextHubBackend	将文件存储在 LangSmith Context Hub 仓库中，无需额外配置 Store
SandboxBackend	在隔离环境 中执行代码，提供文件系统工具 + execute 命令执行工具
LocalShellBackend	直接在宿主机上执行文件操作和 Shell 命令------无隔离，仅限受控开发环境使用
CompositeBackend	路由后端，可根据路径前缀将不同目录路由到不同的存储后端

2. 各后端详解

1. StateBackend（默认，线程内存储）

文件存储在当前线程的 LangGraph 状态中，借助 Checkpointer 在同线程的多次对话轮次间持久化，但不跨线程共享。

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认即为 StateBackend
agent = create_deep_agent(model="openai:gpt-5.5")

# 显式指定效果相同
agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StateBackend(),
)

适用场景：

• 作为智能体的临时工作区（scratch pad），用于写入中间结果
• 大型工具输出的自动换出与分段读取

⚠️ 注意 ：在 Graph 运行之外调用 StateBackend 的方法（如 upload_files）不会生效。

2. FilesystemBackend（本地磁盘）

直接读写宿主机真实文件，可配置根目录（root_dir）限制访问范围。

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

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

安全警告 ⚠️：

• 智能体可读取任何可访问的文件，包括 .env、API 密钥等敏感信息
• 结合网络工具可能通过 SSRF 导致数据泄露
• 文件修改是永久且不可逆的

安全建议：

• 启用 virtual_mode=True 以启用路径访问限制（禁止 ..、~ 及根目录外的绝对路径）
• 对敏感操作启用 Human-in-the-Loop（HITL） 中间件进行人工审批
• 生产环境推荐使用 SandboxBackend
• 使用 CompositeBackend 将项目目录路由到 FilesystemBackend，同时将内部数据（工具输出、对话历史）保留在 StateBackend 中

3. LocalShellBackend（本地 Shell）

在 FilesystemBackend 的基础上额外提供了 execute 工具，可直接在宿主机执行任意 Shell 命令。

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

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

特性：

• 命令通过 subprocess.run(shell=True) 直接执行，无任何沙箱隔离
• 支持 timeout（默认 120 秒）、max_output_bytes（默认 100,000）、env 和 inherit_env 等参数
• root_dir 仅作为工作目录，命令可访问系统任意路径

安全警告 ⚠️：

• 智能体可以你的权限执行任意 Shell 命令
• 可读取任意文件（含 secrets）
• 文件修改和命令执行均永久且不可逆
• 命令可消耗无限的 CPU、内存和磁盘

适用场景（仅限可信环境）：

• 本地开发 CLI（编码助手、开发工具）
• 个人开发环境（信任智能体代码）
• CI/CD 管道（需妥善管理 secrets）

绝对禁止：

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

⚠️ 注意 ：启用 Shell 访问时，virtual_mode=True 不提供任何安全保护，因为命令可访问系统任意路径。

4. StoreBackend（LangGraph 持久化存储）

基于 LangGraph BaseStore 实现跨线程的持久化存储，适合存放长期记忆或跨会话共享的指令。

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.5-flash",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # 本地开发用；部署至 LangSmith 时可省略
)

命名空间（Namespace）工厂：

• 控制数据的隔离范围，接收 LangGraph Runtime 对象，返回元组作为存储命名空间
• 常见模式：
  • 按用户隔离：lambda rt: (rt.server_info.user.identity,)
  • 按助理隔离：lambda rt: (rt.server_info.assistant_id,)
  • 按线程隔离：lambda rt: (rt.execution_info.thread_id,)

适用场景：

• 已有 LangGraph Store 配置（Redis、Postgres 等）
• 通过 LangSmith Deployment 部署（Store 自动预置）

5. ContextHubBackend（LangSmith Context Hub）

将智能体的文件系统存储在 LangSmith Context Hub 仓库中。

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

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

工作原理：

• 首次使用时懒加载拉取仓库树，随后从内存缓存提供读取
• 写入和编辑以 Hub 提交（commit）形式持久化，并在成功提交后更新缓存
• 使用乐观父提交（parent_commit）策略
• 若仓库不存在，首次写入会自动创建
• 冲突时需重新拉取并重试

前置条件 ：使用前需设置 LANGSMITH_API_KEY。

适用场景：

• 原生 LangSmith 持久化文件系统，无需额外配置 LangGraph Store
• 需要 Hub 提交历史记录的工作流

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

路由规则：

• 匹配最长前缀 优先（例如 /memories/projects/ 可覆盖 /memories/）
• ls、glob、grep 会聚合所有后端的结果，并保留原始路径前缀
• DeepAgents 的内部数据（换出的工具结果、对话历史）写入 default 后端

典型用法 ：将 /memories/ 路由到 StoreBackend 实现跨线程持久化，其余路径保持 StateBackend 的线程内临时存储。

3. 自定义后端

如需连接数据库、对象存储或远程文件系统，可实现自定义后端。

实现 BackendProtocol

继承 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`
grep	`(pattern: str, path: str	None, glob: str
delete	(file_path: str) -> DeleteResult	删除文件或目录（可选；若不支持，工具会自动隐藏）

⚠️ 重要 ：始终返回带 error 字段的结构化结果类型，不要抛出异常。

实现 SandboxBackendProtocol

如需支持 execute 工具（执行 Shell 命令），应实现 SandboxBackendProtocol，它扩展了 BackendProtocol 并增加了 execute 方法。

4. 指定后端

在创建智能体时通过 backend 参数传入后端实例：

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

# StateBackend（默认）
agent = create_deep_agent(model="openai:gpt-5.5")

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

# StoreBackend
agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=StoreBackend(namespace=lambda rt: (rt.server_info.user.identity,)),
    store=InMemoryStore(),
)

5. 总结

需求	推荐后端
单次对话内的临时文件操作	StateBackend（默认）
读写本地磁盘真实文件	FilesystemBackend（注意安全）
跨线程的长期记忆/全局配置	StoreBackend 或 ContextHubBackend
隔离环境中执行代码	SandboxBackend
本地开发需执行 Shell 命令	LocalShellBackend（仅限可信环境）
不同路径使用不同存储策略	CompositeBackend
连接数据库/对象存储/远程文件系统	实现自定义 BackendProtocol