Chapter 08 · Task planning and write_todos

Since v0.7, task planning is opt-in: TodoListMiddleware supplies the write_todos tool, giving multi-step tasks an inspectable structured checklist.

Mechanics and design choices

Planning is not free-form prose; it is inspectable state: pending/in_progress/completed, which UIs can subscribe to. Planning is not mandatory — simple tasks skip it to save tokens; only one planner should act at a time.

Example

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)

Run and verify

API key required. Acceptance: the trace shows write_todos calls (state changes) and a final report.

Pitfalls

write_todos is not the only planning mechanism: for deterministic flows prefer graph routing or code orchestration; planning tools fit model-led, many-step tasks. Parallel write_todos calls are explicitly discouraged.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Is planning on by default in v0.7?

2. What planning states exist?

3. Should simple tasks plan?

4. Can write_todos run in parallel?

Hands-on exercises

1. Track 4 steps and verify each becomes completed in turn.
2. Render planning results into a frontend list.
3. Remove TodoListMiddleware for a simple task and compare token usage.

Official references

• overview
• customization

Verified on 2026-09-17 with Deep Agents 0.7.15.