摘要：DeepAgents 上下文工程框架提供了 8 种虚拟文件系统后端，用于管理 AI Agent 的工作空间与状态。本文逐一剖析 StateBackend、FilesystemBackend、StoreBackend、LocalShellBackend、CompositeBackend、ContextHubBackend、CustomBackend 和 Sandbox Backend 的工作原理、适用场景与关键限制，并给出横向对比与选型建议，

📖 目录

• 前言
• Backends
  • 1. StateBackend
  • 2. FilesystemBackend (local disk)
  • 3. StoreBackend (LangGraph store)
  • 4. LocalShellBackend
  • 5. CompositeBackend
  • 6. ContextHubBackend
  • 7. CustomBackend
  • 8. Sandbox Backend
• 思考&总结

帮助开发者为不同场景选择最合适的后端方案。

前言

DeepAgents 是一个面向 AI Agent 的上下文工程框架，其核心设计目标是为智能代理提供灵活、可扩展且安全的文件系统接口与状态管理能力。在构建复杂的多步骤 Agent 应用时，如何管理 Agent 的「工作空间」——即它能够读取、写入和操作的文件与数据——是一个关键的设计决策。

本文聚焦于 DeepAgents 后端系统的 8 种虚拟文件系统类型，逐一剖析其工作原理、适用场景与关键限制。无论你是正在搭建本地开发工具的独立开发者，还是设计生产级分布式 Agent 系统的架构师，理解这些后端的特性与选型策略，都能帮助你做出更明智的技术决策。

阅读指南：

• 如果你对 DeepAgents 后端体系尚不熟悉，建议按顺序阅读，从 StateBackend 到 Sandbox Backend 逐步深入。
• 如果你已有明确的使用场景（如本地开发、分布式部署、团队协作），可直接跳转到对应的后端章节。
• 文末的「总结与选型建议」章节提供了横向对比与决策参考，可作为快速选型的起点。

Backends

DeepAgents通过ls、read_file、write_file、edit_file、glob和grep等工具向代理暴露一个文件系统接口。这些工具通过可插拔后端进行操作。read_file工具在所有后端上原生支持图像文件（.png、.jpg、.jpeg、.gif、.webp），并将其作为多模态内容块返回。

*Backend存在8种虚拟文件系统类型：

后端类型	持久化级别	适用场景	关键限制/风险	典型配置示例	推荐使用场景
StateBackend	会话级（session/thread_id 生命周期），配合 checkpoint 可持久化	单次会话内的临时文件操作，无需跨会话持久化	文件生命周期与 session 绑定，会话结束后文件默认丢失	backend=StateBackend()	快速原型验证、单次对话临时文件处理
FilesystemBackend	磁盘级（真实文件落盘）	本地项目开发、CI 沙箱环境、挂载的持久卷	virtual_mode=True 时路径被沙盒化；真实落盘需注意磁盘空间管理	backend=FilesystemBackend(root_dir=".", virtual_mode=True)	本地开发环境、需要真实文件落盘的 CI/CD 流程
StoreBackend	取决于底层存储实现（内存/Redis/Postgres）	长期记忆数据，如用户偏好、跨对话知识库	底层存储实现决定持久化级别；生产环境建议使用 Redis 或 Postgres	backend=StoreBackend(rt), store=InMemoryStore()	跨对话知识库、用户偏好记忆、需要持久化的会话数据
LocalShellBackend	磁盘级（继承 FilesystemBackend）	本地编码助手、开发工具、快速迭代 demo	⚠️ 极度危险：赋予 Agent 主机任意命令执行权限；禁止用于生产环境或不可信输入	backend=LocalShellBackend(root_dir=".", virtual_mode=True)	本地开发工具、需要执行 shell 命令的编码助手
CompositeBackend	取决于路由到的具体后端	混合存储策略，如临时文件用 StateBackend、长期记忆用 StoreBackend	路由规则基于路径前缀匹配，需确保前缀设计不冲突；不同后端特性差异影响整体表现	backend=CompositeBackend(default=StateBackend(), routes={"/memories/": StoreBackend(...)})	复杂应用场景、需要按路径区分存储策略的多层架构
ContextHubBackend	云端级（LangSmith Hub 远程仓库）	多进程/分布式 Agent、持久化长对话、团队协作开发、生产环境部署	强依赖网络连接；需 LangSmith 账号认证；仓库有状态大小限制；并发写入可能冲突；频繁读写产生 API 调用成本	backend=ContextHubBackend("my-team/my-agent")	分布式 Agent 系统、团队协作开发、需要云端状态同步的生产环境
CustomBackend	自定义（取决于实现）	需要集成第三方存储系统（如 S3、数据库）	需要实现 BackendProtocol 接口，开发复杂度较高	实现 BackendProtocol 接口	企业级定制存储、集成现有云存储或数据库系统
Sandbox Backend	沙盒级（隔离环境）	安全敏感场景、不可信代码执行	需要额外配置沙盒环境，可能有性能开销	参考 Deep Agents Sandbox 实践	安全沙盒环境、执行不可信代码或处理敏感数据

1. StateBackend

StateBackend 是默认使用的 Backend。当未集成 LangSmith 平台时，它提供一个虚拟文件系统，创建的文件存在于运行时的 State 中，即 session/thread_id 范围内的生命周期。若设置了 checkpoint，会话中创建的文件会根据 checkpoint 策略进行相应的持久化。

创建 StateBackend 代码：

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 默认情况下，create_deep_agent 自动使用 StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.5-flash")

# 显式指定 StateBackend 的等价写法
agent2 = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=StateBackend(),
)

适用场景： 单次会话内的临时文件操作，无需跨会话持久化。
注意点： 文件生命周期与 session 绑定，会话结束后文件默认丢失；如需持久化需配合 checkpoint 机制。

2. FilesystemBackend (local disk)

FilesystemBackend 在可配置的根目录下读写实际文件，可真实在指定的 root_dir 下创建文件，但不具备命令执行功能。

创建 FilesystemBackend 代码：

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),
)

工作原理：

1. 在可配置的根目录下读写真实文件。
2. 可将 virtual_mode 设为 True，对 root_dir 下的路径进行沙盒处理和标准化。
3. 采用安全路径解析，防止不安全的符号链接遍历；可使用 ripgrep 实现快速 grep。

适用场景：

1. 本地项目开发
2. CI 沙箱环境
3. 挂载的持久卷

注意点： virtual_mode=True 时路径会被沙盒化，避免越界访问；文件真实落盘，需注意磁盘空间管理。

3. StoreBackend (LangGraph store)

• 工作原理： StoreBackend 将文件存储在运行时提供的 LangGraph BaseStore（支持 Redis、Postgres、内存等实现）中，从而实现跨线程持久存储。
• 适用场景： 存储需要长期记忆的数据，例如用户偏好、跨对话知识库。

StoreBackend 代码实现：

# 案例：配置一个具有持久化记忆的 Agent
from deepagents.backends import StoreBackend
from deepagents import create_deep_agent
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="gpt-4o",
    backend=lambda rt: StoreBackend(rt),
    store=InMemoryStore()  # 使用内存存储，进程重启后丢失。生产环境可用 RedisStore 等。
)
# Agent 写入 /memories/ 下的文件，在后续的新对话中仍可读取。

注意点： 底层存储实现（InMemoryStore/RedisStore/PostgresStore）决定了数据的持久化级别；生产环境建议使用 Redis 或 Postgres 等持久化存储。

4. LocalShellBackend

• 工作原理： 在 FilesystemBackend 的基础上，额外提供了一个 execute 工具，允许 Agent 在主机上执行任意的 Shell 命令。
• ⚠️ 极度危险警告： 此后端赋予 Agent 在您的主机上执行任意命令的最高权限。仅限在您完全信任 Agent 代码的本地开发环境中使用。禁止用于生产环境或处理不可信输入。
• 适用场景： 本地编码助手、开发工具；开发过程中的快速迭代 demo。

LocalShellBackend 代码实现：

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"}),
)

注意点： 务必在受控的沙盒环境中使用；限制环境变量（如 PATH）可降低风险；禁止在生产环境或处理不可信输入时使用。

5. CompositeBackend

• 工作原理： 作为后端路由器，1) 根据文件路径的前缀，将操作定向到不同的底层后端；2) 在列表和搜索结果中保留原始路径前缀。
• 适用场景： 实现混合存储策略。例如，临时工作文件用 StateBackend，长期记忆用 StoreBackend，特定目录映射到本地磁盘。

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
)

注意点： 路由规则基于路径前缀匹配，需确保前缀设计不冲突；不同后端的特性差异（如读写性能、持久化能力）会直接影响整体表现。

6. ContextHubBackend

ContextHubBackend 将 Agent 的上下文状态（包括对话历史、中间步骤、工具调用记录等）持久化存储在 LangSmith Hub 的远程仓库中。它利用 LangSmith 的仓库机制，为 Agent 状态提供云端存储、版本管理和团队协作能力，适合需要跨进程、跨机器共享 Agent 状态的场景。

工作原理

ContextHubBackend 的核心机制是将 Agent 的完整上下文序列化为可存储的结构化数据，并通过 LangSmith Hub 的仓库 API 进行读写：

1. 仓库标识：每个 Agent 实例对应一个 LangSmith Hub 仓库，使用 owner/name 或 name 格式的仓库标识符来定位。例如 "my-team/my-agent" 或 "my-agent"。
2. 状态序列化：Agent 运行过程中的上下文（消息列表、工具调用结果、Agent 内部状态）会被序列化为 LangSmith 兼容的格式，并写入仓库。
3. 远程同步：每次上下文更新时，Backend 自动将最新状态同步到 LangSmith Hub；Agent 重启或跨进程恢复时，从仓库拉取最新状态。
4. 版本追踪：LangSmith Hub 天然支持仓库的版本历史，因此 ContextHubBackend 间接获得了状态版本管理能力，可回溯到之前的 Agent 状态。

适用场景

• 多进程/分布式 Agent：多个 Worker 进程需要共享同一个 Agent 的上下文状态，例如在微服务架构中，不同服务节点轮流处理同一用户的对话。
• 持久化长对话：对话可能持续数小时甚至数天，Agent 状态需要跨会话持久保存，避免因服务重启导致上下文丢失。
• 团队协作开发：团队成员需要共享和调试同一个 Agent 的上下文状态，LangSmith Hub 的仓库机制提供了天然的共享和权限控制。
• 生产环境部署：需要将 Agent 状态与业务数据分离存储，利用 LangSmith Hub 的可靠性保障数据不丢失。

使用注意事项

1. 网络依赖：ContextHubBackend 强依赖网络连接，每次状态读写都需要与 LangSmith Hub 通信。在网络不稳定或离线环境下，Agent 可能无法正常工作。建议在关键路径上添加重试和超时机制。
2. LangSmith 账号与认证：使用前需要配置 LangSmith API Key 和项目信息。通常通过环境变量 LANGSMITH_API_KEY 和 LANGSMITH_PROJECT 设置，或直接在代码中传入认证参数。
3. 仓库命名规范：仓库名称应遵循 LangSmith Hub 的命名规则，避免使用特殊字符。建议使用 团队名/Agent名 的格式，便于管理和权限隔离。
4. 状态大小限制：LangSmith Hub 仓库对单次写入的数据量有一定限制（通常为几 MB）。如果 Agent 上下文非常庞大（例如包含大量长文档或图片），可能需要考虑分片存储或使用其他 Backend。
5. 并发写入冲突：多个进程同时写入同一个仓库时可能出现状态覆盖。生产环境中建议实现乐观锁或使用 CompositeBackend 将 ContextHubBackend 与本地缓存结合，减少并发冲突概率。
6. 成本考量：频繁的状态读写会产生 LangSmith Hub API 调用，可能带来额外的使用成本。建议根据实际需求调整同步频率，避免不必要的写入。

ContextHubBackend 代码实现：

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

# 使用 owner/name 格式指定仓库
agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=ContextHubBackend("my-team/my-agent"),
)

# 也可以只传 name，使用默认 owner
agent_simple = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=ContextHubBackend("my-agent"),
)

7. CustomBackend

需要实现 BackendProtocol接口，将任何存储系统（如云存储S3、数据库）暴露给Agent。
需要重写的核心方法的简要说明：
1. ls_info(path: str) -> list[FileInfo]
•功能：列出指定路径下的文件和目录。
•要求：返回的 FileInfo列表必须至少包含 path字段。应对结果按 path排序以保证输出确定性。

2. read(file_path: str, offset: int = 0, limit: int = 2000) -> str
•功能：读取文件内容，支持从某行开始（offset）并限制行数（limit）。
•要求：返回的字符串必须包含行号（如 “1: first line\n2: second line”）。文件不存在时返回错误字符串。

3. write(file_path: str, content: str) -> WriteResult
•功能：创建新文件。默认应是“仅创建”（Create-only），即文件已存在时应返回错误。
•要求：操作成功返回 WriteResult(path=…, files_update=…)。对于外部后端（如S3），files_update应为 None。

4. edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult
•功能：替换文件中的文本。当 replace_all=False时，old_string必须在文件中精确出现一次，否则返回错误。这是为了防止意外替换。

5. grep_raw(pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str
•功能：在文件中搜索正则表达式 pattern。可以限制在特定 path（目录）下，或使用 glob模式过滤文件。
•要求：正则表达式无效时，返回错误字符串而非抛出异常。

6. glob_info(pattern: str, path: str = “/”) -> list[FileInfo]
•功能：使用 glob 模式（如 *.txt）在指定路径下搜索文件。

8. Sandbox Backend

Deep Agents Sandbox：从主流方案到企业级自定义实践技术全解析

思考&总结：DeepAgents Backends 的架构智慧与工程实践

DeepAgents 的后端架构远不止是简单的"存储抽象层"——它代表了一种对智能体系统本质的深刻理解：智能体的"记忆"与"环境"是其认知能力的物理基础。这8种后端设计，从StateBackend到Sandbox Backend，构成了一个从瞬时到持久、从孤立到协同、从模拟到现实的完整技术谱系。

一、架构设计的核心智慧

1. 存储即状态，状态即智能

• 认知科学视角：传统AI模型将智能视为纯计算过程，而DeepAgents通过Backends将"状态持久化"提升为一级公民。这暗合了认知科学中的"延展心智"理论——智能体的认知能力不仅存在于其算法内部，更延伸至其可操作的外部存储介质中。
• 系统设计启示：FilesystemBackend与StoreBackend的分离，本质上是"工作记忆"与"长期记忆"的工程化映射。前者处理当前任务的临时数据，后者存储需要跨会话保留的结构化知识。

2. 安全与能力的辩证统一

• 安全哲学：从LocalShellBackend的"信任但验证"到Sandbox Backend的"零信任隔离"，DeepAgents呈现了安全设计的渐进式策略。这反映了现代系统安全的核心矛盾：能力越强，攻击面越广。
• 工程实践：CompositeBackend的"路由规则"机制，本质上是安全策略的声明式配置。开发者不是在代码中硬编码安全检查，而是通过后端组合策略实现"最小权限原则"的自动化实施。

3. 分布式协同的拓扑学思考

• ContextHubBackend基于LangSmith Hub的设计，揭示了多智能体系统的核心挑战：状态同步的CAP定理困境。在一致性、可用性、分区容错性之间，DeepAgents选择了"最终一致性+冲突检测"的实用主义路径，这比强一致性更适合AI工作流的异步特性。

二、AI工程化的选型策略

1. 企业级部署的"三阶段"模型

• 阶段一（探索期）：StateBackend + FilesystemBackend组合，快速验证业务假设，零成本启动
• 阶段二（增长期）：引入StoreBackend + ContextHubBackend，建立跨团队知识共享，支持多智能体协作
• 阶段三（成熟期）：定制CustomBackend + Sandbox Backend，形成技术护城河，满足合规与安全要求

2. 成本效益的"存储经济学"

• 冷热数据分层：将高频访问的"热数据"放在内存后端，低频"冷数据"放在对象存储，平衡性能与成本
• 计算存储权衡：某些场景下，重新计算比存储更经济（如生成式AI的中间结果），需根据实际负载评估
• 合规性成本：医疗、金融等受监管行业，Sandbox Backend的审计日志功能可能成为法律必需品而非技术选配

3. 开发者体验的"认知负荷"优化

• 渐进式复杂度：从零配置的StateBackend起步，按需引入更复杂的后端，避免过度设计
• 可视化调试：未来IDE插件可能实时显示后端间的数据流图，帮助开发者理解数据流转路径
• 智能推荐：系统根据代码模式自动推荐最优后端组合策略，降低选型决策成本

三、选型决策要点速查

场景	推荐后端组合	核心考量
单智能体原型开发	StateBackend	零配置、快速迭代
本地文件处理	FilesystemBackend	持久化、可审计
跨会话知识管理	StoreBackend	结构化存储、语义检索
安全命令执行	LocalShellBackend	白名单控制、沙箱隔离
多后端组合路由	CompositeBackend	灵活路由、策略解耦
多智能体协作	ContextHubBackend	状态同步、版本管理
企业定制需求	CustomBackend	完全控制、专属优化
高风险隔离执行	Sandbox Backend	零信任、完整审计

四、未来演进方向

1. 存储层与AI模型的深度融合

• 后端系统将更深度集成向量数据库，支持语义级检索而非仅路径匹配
• 智能体可基于历史状态自动优化存储策略，实现"自适应存储层级"

2. 多智能体协作的标准化

• ContextHubBackend的模式可能演化为行业标准协议，类似HTTP之于Web
• 跨组织、跨平台的后端互操作将成为AI Agent生态的关键基础设施

3. 可观测性与调试能力增强

• 后端操作的全链路追踪将成为标配，帮助开发者定位状态异常
• 可视化数据流图、状态变更历史回放等工具将大幅降低调试复杂度

结语：从工具到生态的范式跃迁

DeepAgents Backends的价值不仅在于解决了"智能体在哪里存储数据"的技术问题，更在于它提出了一个根本性的设问：当AI系统拥有持久化、可共享、可审计的记忆时，我们如何重新定义人机协作的边界？

这8种后端如同8种不同的"记忆器官"，赋予智能体从金鱼般的瞬时记忆到人类般的传记记忆，再到集体智慧般的文化记忆。选择何种后端，本质上是为智能体选择何种"存在方式"——是昙花一现的工具，还是持续进化的伙伴，抑或是分布式大脑的神经元节点？

技术的前沿永远在工程实践中迭代。DeepAgents Backends的当前实现，只是这场宏大探索的起点。真正的挑战不在于编写更多后端类型，而在于构建一个让开发者高效构建、安全部署、持续迭代AI Agent的存储基础设施。

未来已来，只是分布不均——而DeepAgents Backends，正是让这份未来变得可存储、可共享、可进化的关键基础设施。