Appearance
Agent Harness 架构与规划
Deep Agents 的“深”并不来自更多隐藏推理，而来自一个明确的工程结构：让模型在 LangChain Agent 循环中使用规划、文件和委派工具，同时由 LangGraph 管理状态与可恢复执行。
Harness 如何组装
create_deep_agent/createDeepAgent 负责配置这套组合，真正的 Agent loop 由 LangChain create_agent 建立，执行状态继续由 LangGraph Runtime 管理。
前端类比
可以把 middleware 链类比为服务端框架的中间件管线：TodoList 记录工作计划，Filesystem 提供 工作区，SubAgent 类似任务队列入口，Summarization 类似缓存压缩层，LangGraph 则像保存请求状态 并支持重放的运行时。
Deep Agents 原生语义：这些不是固定按顺序执行一次的 HTTP middleware。它们可以向 Agent state、system prompt 和工具集合注入能力，并在模型循环的不同时点运行。最终下一步仍由模型产生 tool call 或结束消息，LangGraph 负责推进和持久化执行。
默认 middleware 与按需能力
| 能力 | 默认状态 | 主要结果 |
|---|---|---|
| TodoList | 开启 | 提供 write_todos，让模型维护任务列表 |
| Filesystem | 开启 | 提供虚拟文件工具，默认连接 StateBackend |
| SubAgent | 开启 | 提供 task 委派入口 |
| Summarization | 开启 | 接近上下文限制时压缩对话历史 |
| PatchToolCalls | 开启 | 修补部分 provider 的工具调用兼容问题 |
| Skills | 传入 skills 后开启 | 按需发现和加载技能说明与资源 |
| Memory | 传入 memory 后开启 | 把指定记忆源加入上下文 |
| HITL | 配置 interrupt_on 后开启 | 在选定工具执行前暂停审批 |
自定义 middleware 会和内置 Harness 共同交给 create_agent。编写依赖 hook 顺序的 middleware 时，应以当前版本源码与 API Reference 为准，不要从表格推断具体 before/after hook 次序。
Planning 的真实作用
TodoList middleware 向模型提供 write_todos。它帮助模型把长任务显式拆成小步骤，并把当前状态 保存在 Agent state 中。典型 Todo 状态包括 pending、in progress 与 completed，但计划本身不会 自动执行。
text
用户目标
→ 模型调用 write_todos 建立步骤
→ 模型选择工具、文件或 subagent 完成当前步骤
→ 模型更新 Todo 状态
→ 重复直到形成最终结果规划特别适合：
- 研究、迁移、编码等无法一次完成的任务。
- 有明确验收条件，需要在结束前逐项核对的任务。
- 可以把独立问题交给 subagent 的任务。
规划不等于确定性工作流。模型可以漏掉步骤、错误标记完成或改变计划。涉及付款、权限升级等业务 不变量时，应由 LangGraph 节点、应用代码和基础设施强制执行，而不是只靠 Todo。
为规划提供正确的 system prompt
Python 主线可以用 system prompt 规定何时规划、何时写文件，以及结束前必须检查什么：
python
import os
from deepagents import create_deep_agent
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
system_prompt="""
面对超过一个步骤的任务时，先用 write_todos 建立可验证计划。
大段中间材料写入文件，只把结论留在消息上下文。
结束前重新检查用户给出的验收条件；不要把 Todo 状态当作验收证据。
""",
)TypeScript 使用相同概念，通过 createDeepAgent({ systemPrompt: '...' }) 配置。两个 SDK 的参数 命名风格不同，但都由同一个 Harness 思路驱动。
State、Checkpoint 与 Store
这三个概念解决不同生命周期：
- State：一次 thread 当前执行所需的数据，包括 messages、todos 与默认虚拟文件。
- Checkpoint：在执行步骤之间保存 state，使 interrupt/resume 和故障恢复成为可能。
- Store：跨 thread 访问的数据空间，可用于长期 memory 或共享资源。
默认 StateBackend 把文件放入 state。它不自动创建生产级 checkpointer，也不自动把文件放进 跨用户 store。持久化边界需要应用显式设计。
何时下探到 LangGraph
以下需求不应只通过 prompt 和 Todo 表达：
- 必须按固定顺序经过审批、写入和通知节点。
- 需要确定性并发、汇聚、重试和补偿。
- 需要对某个状态转换做强类型和业务校验。
- 需要在 Agent 前后运行不可绕过的安全节点。
此时可以把 Deep Agents 编译出的 Agent 图作为 LangGraph 中的一个节点，或直接为任务构建自定义图。