Deep Agents Backends：8 种虚拟文件系统后端全解析

摘要DeepAgents 上下文工程框架提供了 8 种虚拟文件系统后端用于管理 AI Agent 的工作空间与状态。本文逐一剖析 StateBackend、FilesystemBackend、StoreBackend、LocalShellBackend、CompositeBackend、ContextHubBackend、CustomBackend 和 Sandbox Backend 的工作原理、适用场景与关键限制并给出横向对比与选型建议 目录前言Backends1. StateBackend2. FilesystemBackend (local disk)3. StoreBackend (LangGraph store)4. LocalShellBackend5. CompositeBackend6. ContextHubBackend7. CustomBackend8. Sandbox Backend思考总结帮助开发者为不同场景选择最合适的后端方案。前言DeepAgents 是一个面向 AI Agent 的上下文工程框架其核心设计目标是为智能代理提供灵活、可扩展且安全的文件系统接口与状态管理能力。在构建复杂的多步骤 Agent 应用时如何管理 Agent 的「工作空间」——即它能够读取、写入和操作的文件与数据——是一个关键的设计决策。本文聚焦于 DeepAgents 后端系统的8 种虚拟文件系统类型逐一剖析其工作原理、适用场景与关键限制。无论你是正在搭建本地开发工具的独立开发者还是设计生产级分布式 Agent 系统的架构师理解这些后端的特性与选型策略都能帮助你做出更明智的技术决策。阅读指南如果你对 DeepAgents 后端体系尚不熟悉建议按顺序阅读从 StateBackend 到 Sandbox Backend 逐步深入。如果你已有明确的使用场景如本地开发、分布式部署、团队协作可直接跳转到对应的后端章节。文末的「总结与选型建议」章节提供了横向对比与决策参考可作为快速选型的起点。BackendsDeepAgents通过ls、read_file、write_file、edit_file、glob和grep等工具向代理暴露一个文件系统接口。这些工具通过可插拔后端进行操作。read_file工具在所有后端上原生支持图像文件.png、.jpg、.jpeg、.gif、.webp并将其作为多模态内容块返回。*Backend存在8种虚拟文件系统类型后端类型持久化级别适用场景关键限制/风险典型配置示例推荐使用场景StateBackend会话级session/thread_id 生命周期配合 checkpoint 可持久化单次会话内的临时文件操作无需跨会话持久化文件生命周期与 session 绑定会话结束后文件默认丢失backendStateBackend()快速原型验证、单次对话临时文件处理FilesystemBackend磁盘级真实文件落盘本地项目开发、CI 沙箱环境、挂载的持久卷virtual_modeTrue时路径被沙盒化真实落盘需注意磁盘空间管理backendFilesystemBackend(root_dir., virtual_modeTrue)本地开发环境、需要真实文件落盘的 CI/CD 流程StoreBackend取决于底层存储实现内存/Redis/Postgres长期记忆数据如用户偏好、跨对话知识库底层存储实现决定持久化级别生产环境建议使用 Redis 或 PostgresbackendStoreBackend(rt), storeInMemoryStore()跨对话知识库、用户偏好记忆、需要持久化的会话数据LocalShellBackend磁盘级继承 FilesystemBackend本地编码助手、开发工具、快速迭代 demo⚠️ 极度危险赋予 Agent 主机任意命令执行权限禁止用于生产环境或不可信输入backendLocalShellBackend(root_dir., virtual_modeTrue)本地开发工具、需要执行 shell 命令的编码助手CompositeBackend取决于路由到的具体后端混合存储策略如临时文件用 StateBackend、长期记忆用 StoreBackend路由规则基于路径前缀匹配需确保前缀设计不冲突不同后端特性差异影响整体表现backendCompositeBackend(defaultStateBackend(), routes{/memories/: StoreBackend(...)})复杂应用场景、需要按路径区分存储策略的多层架构ContextHubBackend云端级LangSmith Hub 远程仓库多进程/分布式 Agent、持久化长对话、团队协作开发、生产环境部署强依赖网络连接需 LangSmith 账号认证仓库有状态大小限制并发写入可能冲突频繁读写产生 API 调用成本backendContextHubBackend(my-team/my-agent)分布式 Agent 系统、团队协作开发、需要云端状态同步的生产环境CustomBackend自定义取决于实现需要集成第三方存储系统如 S3、数据库需要实现 BackendProtocol 接口开发复杂度较高实现 BackendProtocol 接口企业级定制存储、集成现有云存储或数据库系统Sandbox Backend沙盒级隔离环境安全敏感场景、不可信代码执行需要额外配置沙盒环境可能有性能开销参考 Deep Agents Sandbox 实践安全沙盒环境、执行不可信代码或处理敏感数据1. StateBackendStateBackend 是默认使用的 Backend。当未集成 LangSmith 平台时它提供一个虚拟文件系统创建的文件存在于运行时的 State 中即 session/thread_id 范围内的生命周期。若设置了 checkpoint会话中创建的文件会根据 checkpoint 策略进行相应的持久化。创建 StateBackend 代码fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend# 默认情况下create_deep_agent 自动使用 StateBackendagentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash)# 显式指定 StateBackend 的等价写法agent2create_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendStateBackend(),)适用场景单次会话内的临时文件操作无需跨会话持久化。注意点文件生命周期与 session 绑定会话结束后文件默认丢失如需持久化需配合 checkpoint 机制。2. FilesystemBackend (local disk)FilesystemBackend 在可配置的根目录下读写实际文件可真实在指定的root_dir下创建文件但不具备命令执行功能。创建 FilesystemBackend 代码fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportFilesystemBackend agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendFilesystemBackend(root_dir.,virtual_modeTrue),)工作原理在可配置的根目录下读写真实文件。可将virtual_mode设为True对root_dir下的路径进行沙盒处理和标准化。采用安全路径解析防止不安全的符号链接遍历可使用 ripgrep 实现快速 grep。适用场景本地项目开发CI 沙箱环境挂载的持久卷注意点virtual_modeTrue时路径会被沙盒化避免越界访问文件真实落盘需注意磁盘空间管理。3. StoreBackend (LangGraph store)工作原理StoreBackend 将文件存储在运行时提供的 LangGraph BaseStore支持 Redis、Postgres、内存等实现中从而实现跨线程持久存储。适用场景存储需要长期记忆的数据例如用户偏好、跨对话知识库。StoreBackend 代码实现# 案例配置一个具有持久化记忆的 Agentfromdeepagents.backendsimportStoreBackendfromdeepagentsimportcreate_deep_agentfromlanggraph.store.memoryimportInMemoryStore agentcreate_deep_agent(modelgpt-4o,backendlambdart:StoreBackend(rt),storeInMemoryStore()# 使用内存存储进程重启后丢失。生产环境可用 RedisStore 等。)# Agent 写入 /memories/ 下的文件在后续的新对话中仍可读取。注意点底层存储实现InMemoryStore/RedisStore/PostgresStore决定了数据的持久化级别生产环境建议使用 Redis 或 Postgres 等持久化存储。4. LocalShellBackend工作原理在 FilesystemBackend 的基础上额外提供了一个execute工具允许 Agent 在主机上执行任意的 Shell 命令。⚠️ 极度危险警告此后端赋予 Agent 在您的主机上执行任意命令的最高权限。仅限在您完全信任 Agent 代码的本地开发环境中使用。禁止用于生产环境或处理不可信输入。适用场景本地编码助手、开发工具开发过程中的快速迭代 demo。LocalShellBackend 代码实现fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportLocalShellBackend agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendLocalShellBackend(root_dir.,virtual_modeTrue,env{PATH:/usr/bin:/bin}),)注意点务必在受控的沙盒环境中使用限制环境变量如 PATH可降低风险禁止在生产环境或处理不可信输入时使用。5. CompositeBackend工作原理作为后端路由器1) 根据文件路径的前缀将操作定向到不同的底层后端2) 在列表和搜索结果中保留原始路径前缀。适用场景实现混合存储策略。例如临时工作文件用 StateBackend长期记忆用 StoreBackend特定目录映射到本地磁盘。CompositeBackend 代码实现fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportCompositeBackend,StateBackend,StoreBackendfromlanggraph.store.memoryimportInMemoryStore agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendCompositeBackend(defaultStateBackend(),routes{/memories/:StoreBackend(namespacelambda_rt:(memories,)),},),storeInMemoryStore(),# Store 传给 create_deep_agent而非 backend)注意点路由规则基于路径前缀匹配需确保前缀设计不冲突不同后端的特性差异如读写性能、持久化能力会直接影响整体表现。6. ContextHubBackendContextHubBackend 将 Agent 的上下文状态包括对话历史、中间步骤、工具调用记录等持久化存储在LangSmith Hub的远程仓库中。它利用 LangSmith 的仓库机制为 Agent 状态提供云端存储、版本管理和团队协作能力适合需要跨进程、跨机器共享 Agent 状态的场景。工作原理ContextHubBackend 的核心机制是将 Agent 的完整上下文序列化为可存储的结构化数据并通过 LangSmith Hub 的仓库 API 进行读写仓库标识每个 Agent 实例对应一个 LangSmith Hub 仓库使用owner/name或name格式的仓库标识符来定位。例如my-team/my-agent或my-agent。状态序列化Agent 运行过程中的上下文消息列表、工具调用结果、Agent 内部状态会被序列化为 LangSmith 兼容的格式并写入仓库。远程同步每次上下文更新时Backend 自动将最新状态同步到 LangSmith HubAgent 重启或跨进程恢复时从仓库拉取最新状态。版本追踪LangSmith Hub 天然支持仓库的版本历史因此 ContextHubBackend 间接获得了状态版本管理能力可回溯到之前的 Agent 状态。适用场景多进程/分布式 Agent多个 Worker 进程需要共享同一个 Agent 的上下文状态例如在微服务架构中不同服务节点轮流处理同一用户的对话。持久化长对话对话可能持续数小时甚至数天Agent 状态需要跨会话持久保存避免因服务重启导致上下文丢失。团队协作开发团队成员需要共享和调试同一个 Agent 的上下文状态LangSmith Hub 的仓库机制提供了天然的共享和权限控制。生产环境部署需要将 Agent 状态与业务数据分离存储利用 LangSmith Hub 的可靠性保障数据不丢失。使用注意事项网络依赖ContextHubBackend 强依赖网络连接每次状态读写都需要与 LangSmith Hub 通信。在网络不稳定或离线环境下Agent 可能无法正常工作。建议在关键路径上添加重试和超时机制。LangSmith 账号与认证使用前需要配置 LangSmith API Key 和项目信息。通常通过环境变量LANGSMITH_API_KEY和LANGSMITH_PROJECT设置或直接在代码中传入认证参数。仓库命名规范仓库名称应遵循 LangSmith Hub 的命名规则避免使用特殊字符。建议使用团队名/Agent名的格式便于管理和权限隔离。状态大小限制LangSmith Hub 仓库对单次写入的数据量有一定限制通常为几 MB。如果 Agent 上下文非常庞大例如包含大量长文档或图片可能需要考虑分片存储或使用其他 Backend。并发写入冲突多个进程同时写入同一个仓库时可能出现状态覆盖。生产环境中建议实现乐观锁或使用 CompositeBackend 将 ContextHubBackend 与本地缓存结合减少并发冲突概率。成本考量频繁的状态读写会产生 LangSmith Hub API 调用可能带来额外的使用成本。建议根据实际需求调整同步频率避免不必要的写入。ContextHubBackend 代码实现fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportContextHubBackend# 使用 owner/name 格式指定仓库agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendContextHubBackend(my-team/my-agent),)# 也可以只传 name使用默认 owneragent_simplecreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendContextHubBackend(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…)。对于外部后端如S3files_update应为 None。4. edit(file_path: str, old_string: str, new_string: str, replace_all: bool False) - EditResult•功能替换文件中的文本。当 replace_allFalse时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 BackendDeep 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正是让这份未来变得可存储、可共享、可进化的关键基础设施。