Deep Agents Python：生产、容错与应用模式

从原型到生产的变化

本地原型只需模型、工具和 invoke；生产必须把以下问题明确建模：

• 谁在调用：认证身份与授权。
• 对话属于谁：thread 所有权。
• 数据共享给谁：user、assistant、organization scope。
• Agent 在哪里执行：文件后端或沙箱。
• 失败后从哪里恢复：checkpointer、run 和 thread。
• 动作如何限额：调用上限、限流、超时、重试与回退。
• 人何时介入：HITL 与 OAuth/缺失输入。
• 用户如何看见长期进展：流式、重连和异步任务。

Managed Deep Agents 是官方推荐的托管路径，但截至核对日仍为 private preview。需要自定义代码、路由或高级认证时，可直接使用 LangSmith Deployment；也可用 langgraph build 生成镜像自托管。

三个生产作用域

Organization 是更高层共享域，通常用于只读策略。

thread_id 与 context 独立：

• thread_id 决定会话历史和 checkpoint 连续性。
• context 提供当前运行工具/中间件需要的 user_id、角色、连接、feature flag 等。
• 改变 context 不会自动切换 thread；改变 thread 也不会自动切换身份。

生产每次调用通常两者都传。thread_id 必须经过服务端授权，不能把“客户端知道 ID”当作所有权证明。

多租户

身份与资源授权

认证建立身份，授权处理器负责：

• 创建资源时写 owner metadata。
• 查询时附加过滤条件，只返回本人资源。
• 越权直接 403。

团队 RBAC（谁能部署、配置、看 trace）与终端用户授权（谁能访问哪个 thread/store）是两套问题，不能混为一谈。

凭证

不要把原始用户 token 放进消息、memory、state 或沙箱文件。短期凭证也不应出现在模型上下文；应由工具/runtime 或代理边界持有。

异步与耐久执行

Agent 工作以网络 I/O 为主：

• 工具尽量原生 async，减少线程池开销。
• 自定义 middleware 实现 async hook。
• 沙箱创建、MCP 连接等资源生命周期必须 await。
• 按运行信息创建后端时使用 async graph factory。

LangGraph 在每一步 checkpoint。进程故障、超时或人工中断后，从最近状态恢复，不重做已完成步骤。它还支持：

• 中断停留数小时/数天后恢复。
• time travel 回到早期 checkpoint 重放。
• 对不可逆动作保留发生前后的状态证据。

部署平台自动提供持久 checkpointer；自托管必须自行配置。Checkpoint 是恢复机制，不自动保证外部副作用幂等：支付、发信、写第三方系统仍需业务 idempotency key 和执行结果记录。

记忆与执行环境的生产作用域

记忆

• User scope 是推荐默认。
• Assistant scope 会让使用同一 Agent 的所有用户共享，必须审视写权限。
• Organization scope 适合只读政策。
• CompositeBackend 常用 StateBackend 作为默认临时区，把 /memories/ 路由到 StoreBackend。

共享可写记忆是跨用户提示注入通道；默认只读，只有可信应用/管理员可改。namespace 必须来自认证 runtime，不来自聊天参数。

文件系统

• StateBackend：thread 临时区，避免大文件长期堆进 checkpoint。
• StoreBackend：跨 thread 文件，必须有 namespace。
• CompositeBackend：生产常用混合。
• ContextHubBackend：需要 Hub commit 历史时使用。
• FilesystemBackend / LocalShellBackend：直接宿主访问，不用于部署的 Web Agent。

沙箱生命周期

graph factory 在每次 run 从 config 中取 thread_id / assistant_id，查找或创建命名沙箱，并返回绑定该 backend 的 Agent graph。命名查找需能处理重复并发创建。

沙箱文件通过 upload_files / download_files 穿越边界；技能脚本、输入数据先上传，报告/图表/更新后记忆再下载。同步动作可放 before_agent / after_agent middleware，但必须考虑失败重试和并发覆盖。

容错策略矩阵

“捕获所有异常继续跑”会把真实 bug 伪装成模型问题。只处理可明确恢复的异常，其余失败让 run 进入可观察终态。

限流、调用上限、重试与回退

Provider rate limiting

模型初始化时配置 rate_limiter，控制单位时间请求率和 burst。它解决供应商配额，不限制单个 Agent 无限循环。

Call limits

ModelCallLimitMiddleware 与 ToolCallLimitMiddleware 同时使用：

• run_limit：单次 invoke 上限，每轮重置。
• thread_limit：整个会话上限，需要 checkpointer。

对昂贵/有副作用工具设置更严格的独立上限，并在触顶时给用户可理解的终止原因。

Retry

• ModelRetryMiddleware 只处理瞬时模型失败。
• ToolRetryMiddleware 应按工具白名单配置；网络搜索超时可能值得重试，本地文件不存在通常不值得。
• 采用指数退避与有限次数，避免重试风暴。
• 非幂等工具重试前必须有 idempotency key 或先查询执行状态。

Fallback

ModelFallbackMiddleware 在供应商不可用时切换模型。备用模型必须用相同工具 schema、结构化输出和关键行为做回归；“能回复”不代表与主模型等价。

Tool error

ToolErrorMiddleware（langchain 1.3.14+）把选定异常转成错误 ToolMessage，让模型调整参数或换方案。只拦截预期业务错误；认证失败、数据损坏等不应被无限交给模型猜测。

数据隐私与审计

PIIMiddleware 可对 email、信用卡等执行：

• redact：替换标签。
• mask：部分掩码。
• hash：稳定散列。
• block：拒绝处理。

还可定义领域 detector。隐私控制要发生在进入模型和日志前；trace、tool result、memory、sandbox artifact 都是可能泄露的载体。

最低可观测字段：

• thread_id、run_id、assistant_id、已认证 user/tenant ID（不记录秘密）。
• lc_agent_name、工具名、耗时、重试数、错误分类。
• 模型/工具调用计数与成本。
• sandbox_id、创建/复用/回收事件。
• interrupt 请求、决定类型和恢复时间。
• memory/文件写路径及授权结果。

前端与重连

生产 useStream 指向部署地址，而不是本地 2024。必须提供稳定 thread_id，并启用重连/恢复，避免浏览器断线导致用户误以为 run 丢失。

长任务 UI 分层展示：

1. 协调者最终对话。
2. subagent 生命周期和可折叠细节。
3. todos/自定义状态作为进度。
4. interrupt 审批。
5. 沙箱文件与 diff。

UI 的“已完成”必须来自服务端 run/subagent 终态，不只看最后一条文本。

四类官方应用模式

数据分析 Agent

组合：sandbox backend + TodoListMiddleware + 自定义发布工具 + checkpointer。

流程：

1. 应用上传 CSV。
2. Agent 建立分析待办。
3. 在隔离环境执行 Python、生成图表与报告。
4. 沙箱外工具下载产物并发布到 Slack 等系统。

凭证留在发布工具外部，不放沙箱。生产强烈建议沙箱；LocalShell 只用于受控开发。

Deep Research Agent

组合：搜索工具 + 规划 + 同步子代理 + 引用综合。

主 Agent 分解问题；研究子代理在隔离上下文执行搜索和全文读取；主 Agent 评估缺口、追加调查并生成带来源报告。并行数量和委派轮数必须设上限，搜索结果需保存来源 URL 与抓取时间。

Content Builder Agent

组合：AGENTS.md 品牌记忆 + Blog/Social Skills + Researcher 子代理 + 图片生成工具 + FilesystemBackend。

设计价值在于职责分层：品牌声音每轮都相关，放 memory；内容类型流程按需相关，放 skills；网络调查进专职子代理；图像生成是窄工具；成品写入目录。

文档示例是教程而非生产模板：示例存在 TODO 文案、版本 pin 与输出路径表述不一致等迹象。落地时以当前 API、真实 backend root 和集成测试为准，且本地文件后端只放在专用工作目录。

Deep Agents RAG

官方端到端例子采用“检索、卸载、委派”：

1. 文档 load、split、embed，写入向量库。
2. 查询时相似度检索。
3. 搜索工具把 chunks 写进 Agent backend，只返回文件路径。
4. chunk-analyst 子代理逐文件分析。
5. 主 Agent 只接收摘要并带引用综合。

可扩展为：

• Skills-guided retrieval：技能定义索引、查询改写和引用规范。
• Rubric-checked grounding：grader 检查每个结论是否有证据。
• Todo-driven investigation：复杂问题拆成多轮检索。

生产索引应持久化并按数据变化刷新，不应每个进程启动都全量重建。检索内容可能包含间接提示注入；“只当数据”提示不是安全边界，需要允许来源、引用核验和输出验证。

生产就绪清单

正确性

• 自有任务集覆盖模型、工具 schema、结构化输出和 fallback。
• 外部副作用有幂等键；重试不会重复支付、发信或写数据。
• 自动摘要后仍能恢复目标、产物路径和待办。
• thread_id、context 和 namespace 作用域测试通过。

稳定性

• 模型/工具 timeout、有限退避、run/thread 调用上限齐全。
• checkpointer 和 store 为持久实现；故障恢复演练通过。
• 异步 worker 容量覆盖 supervisor + 并行子代理。
• sandbox TTL、快照、磁盘/CPU/内存限制和回收告警齐全。

安全

• 终端用户认证与 thread/store 授权均在服务端。
• 共享 memory/skills 只读，用户数据按 namespace 隔离。
• 不用宿主 Filesystem/LocalShell 承载生产 Web Agent。
• 沙箱不含秘密；网络默认关闭或白名单，优先 auth proxy。
• MCP、自定义工具、PTC、eval、文件 API 分别做权限控制。
• HITL 覆盖高风险/不可逆动作。

可观测性

• LangSmith trace 能按 run、thread、lc_agent_name 关联。
• 能区分模型失败、工具业务错误、授权拒绝、预算触顶、人工拒绝。
• 记录重试、fallback、摘要、sandbox 生命周期和 memory 写入。
• 设定成本、延迟、错误率和循环次数告警。

运维

• langgraph.json 的 graph、依赖和 env 路径可重复构建。
• 密钥由 workspace secret 或部署平台管理，不进入源码/日志。
• 数据保留、删除、导出和审计策略覆盖 checkpoint、store、trace 与沙箱产物。
• Managed Deep Agents 为 preview；若采用，需准备能力限制和退出/迁移方案。

延伸阅读

• 01-概览与定制
• 02-工具-后端-权限-沙箱与协议
• 03-上下文-记忆-检索与子代理
• 04-流式前端-HITL与状态协议