第 08 章 · 任务规划与 write_todos
v0.7 起任务规划是显式开启的：通过 TodoListMiddleware 提供 write_todos 工具，给多步任务一个可检查的结构化清单。
机制与设计选择
规划不是让模型写散文计划，而是让状态可检查：pending/in_progress/completed，UI 可以直接订阅。规划不是必须——简单任务跳过反而省 token；同一时刻只应有一个规划者。
示例
python
import os
from langchain_openai import ChatOpenAI
model = ChatOpenAI(
model=os.environ["MODEL_ID"],
api_key=os.environ["DEEPAGENT_API_KEY"],
base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)
from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware
agent = create_deep_agent(
model=model,
middleware=[TodoListMiddleware()],
system_prompt="Use write_todos for multi-step tasks.",
)
result = agent.invoke(
{"messages": [
{"role": "user", "content": "Plan and finish: 1) write_file a plan to /plan.txt, 2) verify with read_file, 3) report."},
]
}, config={"configurable": {"thread_id": "ch08"}})
print(result["messages"][-1].content)运行与验收
需要 API Key。验收：trace 中可见 write_todos 调用记录（步骤状态变化）与最终报告。
容易踩的坑
write_todos 不是唯一的规划机制：对确定性流程仍建议用图路由或代码编排，规划工具适合“模型主导且步骤多”的任务。并行调用 write_todos 被官方明确反对。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. v0.7 规划默认开启吗？
2. 规划状态包括哪些？
3. 简单任务要规划吗？
4. write_todos 可以并行调用吗？
动手实践
- 让规划工具跟踪 4 个步骤并验证状态依次变为 completed。
- 把规划结果输出到前端列表。
- 对简单任务去掉 TodoListMiddleware 并对比 token 消耗。
官方参考
核验日期：2026-09-17，运行环境：Deep Agents 0.7.15。