DeepAgents : 后端BackendsDeepAgents 提供多种后端实现用于承载智能体运行逻辑、调度沙箱环境、持久化会话状态。开发者可根据部署场景灵活切换后端实现原型调试、单机服务、分布式生产环境之间平滑迁移。1. 开箱即用的后端DeepAgents 提供了多种预置后端可直接使用后端说明StateBackend默认文件存储在 LangGraph 状态中线程内持久化通过 Checkpointer不跨线程共享FilesystemBackend直接读写本地磁盘真实文件需指定root_dirStoreBackend基于 LangGraph Store 的跨线程持久化存储适合存放长期记忆或全局指令ContextHubBackend将文件存储在 LangSmith Context Hub 仓库中无需额外配置 StoreSandboxBackend在隔离环境中执行代码提供文件系统工具 execute命令执行工具LocalShellBackend直接在宿主机上执行文件操作和 Shell 命令——无隔离仅限受控开发环境使用CompositeBackend路由后端可根据路径前缀将不同目录路由到不同的存储后端2. 各后端详解1. StateBackend默认线程内存储文件存储在当前线程的 LangGraph 状态中借助 Checkpointer 在同线程的多次对话轮次间持久化但不跨线程共享。fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend# 默认即为 StateBackendagentcreate_deep_agent(modelopenai:gpt-5.5)# 显式指定效果相同agentcreate_deep_agent(modelopenai:gpt-5.5,backendStateBackend(),)适用场景作为智能体的临时工作区scratch pad用于写入中间结果大型工具输出的自动换出与分段读取⚠️注意在 Graph 运行之外调用StateBackend的方法如upload_files不会生效。2. FilesystemBackend本地磁盘直接读写宿主机真实文件可配置根目录root_dir限制访问范围。fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportFilesystemBackend agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendFilesystemBackend(root_dir.,virtual_modeTrue),)安全警告⚠️智能体可读取任何可访问的文件包括.env、API 密钥等敏感信息结合网络工具可能通过 SSRF 导致数据泄露文件修改是永久且不可逆的安全建议启用virtual_modeTrue以启用路径访问限制禁止..、~及根目录外的绝对路径对敏感操作启用Human-in-the-LoopHITL中间件进行人工审批生产环境推荐使用SandboxBackend使用CompositeBackend将项目目录路由到 FilesystemBackend同时将内部数据工具输出、对话历史保留在 StateBackend 中3. LocalShellBackend本地 Shell在 FilesystemBackend 的基础上额外提供了execute工具可直接在宿主机执行任意 Shell 命令。fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportLocalShellBackend agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendLocalShellBackend(root_dir.,virtual_modeTrue,env{PATH:/usr/bin:/bin}),)特性命令通过subprocess.run(shellTrue)直接执行无任何沙箱隔离支持timeout默认 120 秒、max_output_bytes默认 100,000、env和inherit_env等参数root_dir仅作为工作目录命令可访问系统任意路径安全警告⚠️智能体可以你的权限执行任意 Shell 命令可读取任意文件含 secrets文件修改和命令执行均永久且不可逆命令可消耗无限的 CPU、内存和磁盘适用场景仅限可信环境本地开发 CLI编码助手、开发工具个人开发环境信任智能体代码CI/CD 管道需妥善管理 secrets绝对禁止生产环境Web 服务器、API、多租户系统处理不可信用户输入或执行不可信代码⚠️注意启用 Shell 访问时virtual_modeTrue不提供任何安全保护因为命令可访问系统任意路径。4. StoreBackendLangGraph 持久化存储基于 LangGraphBaseStore实现跨线程的持久化存储适合存放长期记忆或跨会话共享的指令。fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStoreBackendfromlanggraph.store.memoryimportInMemoryStore agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendStoreBackend(namespacelambdart:(rt.server_info.user.identity,),),storeInMemoryStore(),# 本地开发用部署至 LangSmith 时可省略)命名空间Namespace工厂控制数据的隔离范围接收 LangGraphRuntime对象返回元组作为存储命名空间常见模式按用户隔离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. ContextHubBackendLangSmith Context Hub将智能体的文件系统存储在 LangSmith Context Hub 仓库中。fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportContextHubBackend agentcreate_deep_agent(modelgoogle_genai:gemini-3.5-flash,backendContextHubBackend(my-agent),)工作原理首次使用时懒加载拉取仓库树随后从内存缓存提供读取写入和编辑以 Hub 提交commit形式持久化并在成功提交后更新缓存使用乐观父提交parent_commit策略若仓库不存在首次写入会自动创建冲突时需重新拉取并重试前置条件使用前需设置LANGSMITH_API_KEY。适用场景原生 LangSmith 持久化文件系统无需额外配置 LangGraph Store需要 Hub 提交历史记录的工作流6. 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)路由规则匹配最长前缀优先例如/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返回匹配 glob 模式的路径grep(pattern: str, path: str | None, glob: str | None) - GrepResult在文件内容中搜索字符串delete(file_path: str) - DeleteResult删除文件或目录可选若不支持工具会自动隐藏⚠️重要始终返回带error字段的结构化结果类型不要抛出异常。实现 SandboxBackendProtocol如需支持execute工具执行 Shell 命令应实现SandboxBackendProtocol它扩展了BackendProtocol并增加了execute方法。4. 指定后端在创建智能体时通过backend参数传入后端实例fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend,FilesystemBackend,StoreBackend# StateBackend默认agentcreate_deep_agent(modelopenai:gpt-5.5)# FilesystemBackendagentcreate_deep_agent(modelopenai:gpt-5.5,backendFilesystemBackend(root_dir.,virtual_modeTrue),)# StoreBackendagentcreate_deep_agent(modelopenai:gpt-5.5,backendStoreBackend(namespacelambdart:(rt.server_info.user.identity,)),storeInMemoryStore(),)5. 总结需求推荐后端单次对话内的临时文件操作StateBackend默认读写本地磁盘真实文件FilesystemBackend注意安全跨线程的长期记忆/全局配置StoreBackend或ContextHubBackend隔离环境中执行代码SandboxBackend本地开发需执行 Shell 命令LocalShellBackend仅限可信环境不同路径使用不同存储策略CompositeBackend连接数据库/对象存储/远程文件系统实现自定义 BackendProtocol