---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - langchain
  - deep-agents
  - python
  - production
  - reliability
sources:
  - "https://docs.langchain.com/oss/python/deepagents/going-to-production"
  - "https://docs.langchain.com/oss/python/deepagents/fault-tolerance"
  - "https://docs.langchain.com/oss/python/deepagents/data-analysis"
  - "https://docs.langchain.com/oss/python/deepagents/deep-research"
  - "https://docs.langchain.com/oss/python/deepagents/content-builder"
  - "https://docs.langchain.com/oss/python/deepagents/rag"
last_verified: 2026-08-11
---

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

## 从原型到生产的变化

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

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

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

## 三个生产作用域

| 原语 | 含义 | 默认承载 |
| --- | --- | --- |
| Thread | 一次连续会话 | 消息历史、checkpoint、临时文件 |
| User | 已认证最终用户 | 私有记忆、个人技能、资源所有权 |
| Assistant | 一个 Agent 配置实例 | 共享配置、可选共享环境 |

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）是两套问题，不能混为一谈。

### 凭证

| 场景 | 推荐 |
| --- | --- |
| 用户代表自己访问 GitHub/Slack 等 | Agent Auth 管理 OAuth、暂停授权并恢复 |
| 沙箱代码调用外部 API | Auth proxy 在网络边界注入 header |
| 全工作区共享模型/搜索 key | Workspace secrets，供 Agent Server 使用 |

不要把原始用户 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。

### 沙箱生命周期

| Scope | 行为 | 适用 | 运维要求 |
| --- | --- | --- | --- |
| Thread | 新会话新环境，同 thread 重用 | 数据分析、一次性构建 | TTL、结束回收、重新进入恢复 |
| Assistant | 多 thread 共用 | 长期仓库、昂贵依赖 | 快照、清理、容量上限、跨用户隔离审查 |

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

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

## 容错策略矩阵

| 错误 | 处理者 | 策略 |
| --- | --- | --- |
| 网络抖动、429、暂时超时 | 系统 | 指数退避重试 |
| 可由模型修正的工具/解析错误 | LLM | 转成 error ToolMessage |
| 缺少账号、歧义、需要确认 | 人 | interrupt |
| 模型供应商整体故障 | 系统 | fallback model |
| Agent 循环失控 | 系统 | model/tool call limit |
| 未知程序错误 | 开发者 | 向上抛出并告警 |

“捕获所有异常继续跑”会把真实 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与状态协议]]