---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - langchain
  - deep-agents
  - python
  - agent-harness
sources:
  - "https://docs.langchain.com/oss/python/deepagents"
  - "https://docs.langchain.com/oss/python/deepagents/overview"
  - "https://docs.langchain.com/oss/python/deepagents/harness"
  - "https://docs.langchain.com/oss/python/deepagents/quickstart"
  - "https://docs.langchain.com/oss/python/deepagents/customization"
  - "https://docs.langchain.com/oss/python/deepagents/models"
  - "https://docs.langchain.com/oss/python/deepagents/profiles"
  - "https://docs.langchain.com/oss/python/deepagents/comparison"
  - "https://docs.langchain.com/oss/python/deepagents/changelog-py"
  - "https://docs.langchain.com/oss/python/deepagents/code-link"
last_verified: 2026-08-11
---

# Deep Agents Python：概览与定制

> 路由边界：`/oss/python/deepagents` 与 `/harness` 都规范跳转到本页 overview；`/code-link` 则跳到 Deep Agents Code overview。三条可点击入口均已核对，后者的完整 CLI 知识记录在 `02-Deep-Agents-Code`。

## 一句话定位

Deep Agents 是构建在 LangChain Agent 原语之上的“代理执行框架（agent harness）”，底层使用 LangGraph 负责持久化执行、流式输出、中断恢复与人机协作。它没有创造另一套模型调用循环，而是把复杂任务常用的文件系统、上下文压缩、子代理、记忆、技能、权限和执行环境预装成一套可组合能力。

选择边界：

- 只需少量工具调用、流程短：优先 LangChain create_agent。
- 需要明确的状态机、确定性分支或精细编排：直接使用 LangGraph。
- 需要长任务、文件工作区、上下文隔离、子代理和生产级执行外壳：使用 Deep Agents。

## 四个能力面

| 能力面 | 解决的问题 | 核心机制 |
| --- | --- | --- |
| 执行环境 | Agent 在哪里读写、运行与调用外部系统 | 自定义工具、MCP、虚拟文件系统、沙箱、解释器 |
| 上下文管理 | 长任务如何不撑爆上下文 | 技能渐进加载、AGENTS.md 记忆、结果卸载、自动摘要、提示缓存 |
| 委派 | 如何拆解并隔离重工作 | 默认 general-purpose 子代理、自定义同步/异步子代理、可选待办计划 |
| 驾驶与治理 | 人如何介入高风险动作 | interrupt_on、文件权限、检查点和恢复 |

Deep Agents 的关键价值不是“让模型想得更多”，而是把信息放到正确的层：稳定规则进记忆，按需流程进技能，大结果进文件，重型调查进子代理，高风险动作进审批。

## 最小启动路径

1. 安装 deepagents，并配置一个支持 tool calling 的 LangChain 聊天模型。
2. 定义少量、职责清楚的领域工具；搜索可用模型提供商内置搜索或第三方搜索。
3. 用 create_deep_agent 传入 model、tools 和 system_prompt。
4. 通过 messages 调用；同一会话需要稳定 thread_id 和 checkpointer。
5. 开启 LangSmith tracing，观察模型调用、工具调用、子代理委派和上下文压缩。

最小可行配置只需要模型。即便如此，默认仍有文件系统、中间结果压缩、摘要和 general-purpose 子代理。结构化任务计划从 0.7 起是显式选择：需要 write_todos 时加入 TodoListMiddleware，不应假定它默认存在。

## create_deep_agent 的配置地图

| 参数 | 职责 | 重要边界 |
| --- | --- | --- |
| model | 模型字符串或已初始化模型 | 字符串格式为 provider:model；模型必须支持工具调用 |
| tools | 领域动作 | 与框架内置文件/委派工具并存 |
| system_prompt | 业务角色与约束 | 会和框架基础提示、技能、记忆、工具说明共同组装 |
| memory | 启动时总是加载的 AGENTS.md | 只放每次都相关的短规则 |
| skills | 按需加载的 SKILL.md 目录 | 适合详细流程、模板和脚本 |
| backend | 文件系统与执行环境 | 默认 StateBackend，仅在线程内持久 |
| permissions | 内置文件工具的路径级规则 | 不覆盖 MCP、自定义工具或沙箱 shell |
| subagents | 专职同步、异步子代理 | 自定义子代理的提示与技能通常需显式配置 |
| middleware | 横切能力 | 同名默认中间件会被“整体替换”，不是字段合并 |
| interrupt_on | 工具审批策略 | 必须配 checkpointer，并用同一 thread_id 恢复 |
| response_format | 主代理结构化输出 | 结果进入 structured_response |
| state_schema | 可变且需检查点持久化的状态 | 必须继承 DeepAgentState |
| context_schema | 单次运行的不可变上下文 | user_id、角色、连接、短期凭证等 |

## 默认中间件栈

### 裸栈

只有 model 时，主代理通常依次包含：

1. FilesystemMiddleware
2. SubAgentMiddleware（默认 general-purpose 存在时）
3. SummarizationMiddleware
4. PatchToolCallsMiddleware
5. 提示缓存中间件
6. 模型 profile 附加项与工具过滤

### 完整组装顺序

传入所有可选能力后，顺序可概括为：

1. SkillsMiddleware
2. FilesystemMiddleware（含 permissions）
3. SubAgentMiddleware
4. SummarizationMiddleware
5. PatchToolCallsMiddleware
6. AsyncSubAgentMiddleware
7. 调用方 middleware
8. Harness profile 附加 middleware
9. excluded_tools 过滤
10. Anthropic / Bedrock 提示缓存
11. MemoryMiddleware
12. HumanInTheLoopMiddleware

顺序有实际语义：PatchToolCalls 在恢复中断时修复悬空工具调用；缓存位于提示最终成形之后；Memory 放在缓存尾部，减少记忆变化导致缓存前缀失效。

### 覆盖规则

- 调用方传入的 middleware 若 name 与默认项一致，会原位替换默认实例。
- 替换不是合并。替换 FilesystemMiddleware 时，backend、permissions 和工具白名单都要重新提供。
- 默认 general-purpose 子代理会继承主代理对默认 middleware 的覆盖；声明式自定义子代理不会，需要在子代理内单独配置。
- 不应通过 excluded_middleware 删除 FilesystemMiddleware、SubAgentMiddleware 或内部权限脚手架；要收窄能力，应过滤工具或按官方方式关闭默认子代理。
- 自定义中间件不要把线程状态写在实例属性里。并行工具、子代理和多线程调用会共享实例，易产生竞态；应写入图状态。

## 模型与 Profile

### 模型选择

任意支持工具调用的 LangChain chat model 都可用。字符串模型由 init_chat_model 解析；需要 timeout、max_retries、reasoning 参数或供应商特性时，传入预配置模型实例更清晰。

官方 eval 只覆盖文件操作、检索、工具、记忆、对话和摘要等基础行为。它能证明“具备基本代理能力”，不能证明复杂长任务质量。模型排名和版本变化快，应以自己的任务集、成本、延迟和失败恢复做回归测试。

### 两类 Profile

| 类型 | 控制什么 | 何时使用 |
| --- | --- | --- |
| HarnessProfile | 基础/后缀提示、工具描述、排除工具或中间件、额外中间件、默认子代理 | 行为应随模型或供应商变化 |
| ProviderProfile | init_chat_model 初始化参数、凭证检查、动态 kwargs | 模型构造默认值应随供应商变化 |

注册键可以是 provider 或 provider:model。模型级设置覆盖供应商级设置；集合字段做并集，映射按键合并，extra_middleware 按 name 替换或追加。重复注册是叠加，不是清空重建。没有全局通配符；真正全局的调整应放在 create_deep_agent 调用处。

运行时让用户选择模型时，使用 runtime context 加 wrap_model_call 动态替换，而不是为每次选择重建整个 Agent。预配置模型实例不会应用 ProviderProfile，但仍会尝试解析对应 HarnessProfile。

## 与 Claude Agent SDK 的取舍

两者都是 Agent harness，主要差异不在推理循环，而在执行环境与生产平台：

- Deep Agents 可独立选择模型、后端和部署目标；支持本地/虚拟文件系统/远程沙箱/自定义后端。
- Claude Agent SDK 更紧密绑定 Claude 与“Agent 运行在沙箱内”的模式。
- Deep Agents 同时支持 Agent 在沙箱内和“沙箱作为远程工具”两种模式。
- LangSmith Agent Server 提供线程、流式接口、历史、认证和多租户基础设施；选择 Claude SDK 时这些通常需要自行建设。
- Deep Agents 可托管或自托管；代价是需要自行验证不同模型和后端组合，而不能默认获得单一供应商的端到端调优。

## 设计建议

1. 先用裸栈加最少领域工具完成任务，再按证据加入 Todo、技能、专职子代理和 rubric。
2. 模型、执行后端、持久化范围和权限范围分别决策，不把它们绑定成一个不可替换组件。
3. 把业务约束放在 system_prompt / memory，把低层动作放在工具，把长流程放在技能。
4. 用 profile 做“随模型变化”的修正；不要把全局业务逻辑藏在 profile。
5. 任何本地文件或 shell 能力都先当作高风险面，生产默认转向隔离后端。
6. 模型 eval 表是时点快照；上线门槛应由自己的回归集、失败预算与成本上限定义。

## 官方索引异常

官方 llms.txt 当前还列出 deepagents/changelog-py.md，但该地址返回的是全局 Python Changelog 的 HTML 页面，canonical 指向 /oss/python/releases/changelog，并非可逐页读取的 Deep Agents Markdown。它只作为覆盖清单保留，不从该重定向页面提炼 Deep Agents 专题结论。

## 延伸阅读

- [[02-工具-后端-权限-沙箱与协议]]
- [[03-上下文-记忆-检索与子代理]]
- [[04-流式前端-HITL与状态协议]]
- [[05-生产-容错与应用模式]]