企业官网建设流程全解析

DeepAgents : 后端（Backends）

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

1. 开箱即用的后端

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

2. 各后端详解

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

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

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend# 默认即为 StateBackendagent=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）限制访问范围。

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportFilesystemBackend 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 命令。

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportLocalShellBackend 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 持久化存储）

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

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStoreBackendfromlanggraph.store.memoryimportInMemoryStore agent=create_deep_agent(model="google_genai:gemini-3.5-flash",backend=StoreBackend(namespace=lambdart:(rt.server_info.user.identity,),),store=InMemoryStore(),# 本地开发用；部署至 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. ContextHubBackend（LangSmith Context Hub）

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

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportContextHubBackend 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（路由后端）

根据路径前缀将不同的文件操作路由到不同的后端，是最灵活的配置方式。

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportCompositeBackend,StateBackend,StoreBackendfromlanggraph.store.memoryimportInMemoryStore 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并实现以下方法：

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

实现 SandboxBackendProtocol

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

4. 指定后端

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

fromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend,FilesystemBackend,StoreBackend# StateBackend（默认）agent=create_deep_agent(model="openai:gpt-5.5")# FilesystemBackendagent=create_deep_agent(model="openai:gpt-5.5",backend=FilesystemBackend(root_dir=".",virtual_mode=True),)# StoreBackendagent=create_deep_agent(model="openai:gpt-5.5",backend=StoreBackend(namespace=lambdart:(rt.server_info.user.identity,)),store=InMemoryStore(),)

5. 总结