学习笔记 · Obsidian
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 的关键价值不是“让模型想得更多”，而是把信息放到正确的层：稳定规则进记忆，按需流程进技能，大结果进文件，重型调查进子代理，高风险动作进审批。
最小启动路径
- 安装 deepagents，并配置一个支持 tool calling 的 LangChain 聊天模型。
- 定义少量、职责清楚的领域工具；搜索可用模型提供商内置搜索或第三方搜索。
- 用 create_deep_agent 传入 model、tools 和 system_prompt。
- 通过 messages 调用；同一会话需要稳定 thread_id 和 checkpointer。
- 开启 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 时，主代理通常依次包含：
- FilesystemMiddleware
- SubAgentMiddleware（默认 general-purpose 存在时）
- SummarizationMiddleware
- PatchToolCallsMiddleware
- 提示缓存中间件
- 模型 profile 附加项与工具过滤
完整组装顺序
传入所有可选能力后，顺序可概括为：
- SkillsMiddleware
- FilesystemMiddleware（含 permissions）
- SubAgentMiddleware
- SummarizationMiddleware
- PatchToolCallsMiddleware
- AsyncSubAgentMiddleware
- 调用方 middleware
- Harness profile 附加 middleware
- excluded_tools 过滤
- Anthropic / Bedrock 提示缓存
- MemoryMiddleware
- 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 可托管或自托管；代价是需要自行验证不同模型和后端组合，而不能默认获得单一供应商的端到端调优。
设计建议
- 先用裸栈加最少领域工具完成任务，再按证据加入 Todo、技能、专职子代理和 rubric。
- 模型、执行后端、持久化范围和权限范围分别决策，不把它们绑定成一个不可替换组件。
- 把业务约束放在 system_prompt / memory，把低层动作放在工具，把长流程放在技能。
- 用 profile 做“随模型变化”的修正；不要把全局业务逻辑藏在 profile。
- 任何本地文件或 shell 能力都先当作高风险面，生产默认转向隔离后端。
- 模型 eval 表是时点快照；上线门槛应由自己的回归集、失败预算与成本上限定义。
官方索引异常
官方 llms.txt 当前还列出 deepagents/changelog-py.md，但该地址返回的是全局 Python Changelog 的 HTML 页面，canonical 指向 /oss/python/releases/changelog，并非可逐页读取的 Deep Agents Markdown。它只作为覆盖清单保留，不从该重定向页面提炼 Deep Agents 专题结论。