TodoListMiddleware(
self,
*,
system_prompt: str = WRITE_TODOS_SYSTEM_PROMPT,
tool_description: str = Logic to run before the agent execution starts.
Async logic to run before the agent execution starts.
Logic to run before the model is called.
Async logic to run before the model is called.
Logic to run after the agent execution completes.
Async logic to run after the agent execution completes.
Intercept tool execution for retries, monitoring, or modification.
Intercept and control async tool execution via handler callback.
Middleware that provides todo list management capabilities to agents.
This middleware adds a write_todos tool that allows agents to create and manage
structured task lists for complex multi-step operations. It's designed to help
agents track progress, organize complex tasks, and provide users with visibility
into task completion status.
The middleware automatically injects system prompts that guide the agent on when
and how to use the todo functionality effectively. It also enforces that the
write_todos tool is called at most once per model turn, since the tool replaces
the entire todo list and parallel calls would create ambiguity about precedence.
Example:
from langchain.agents.middleware import TodoListMiddleware
from langchain.agents import create_agent
agent = create_agent("openai:gpt-5.5", middleware=[TodoListMiddleware()])
# Agent now has access to write_todos tool and todo state tracking
result = await agent.invoke({"messages": [HumanMessage("Help me refactor my codebase")]})
print(result["todos"]) # Array of todo items with status tracking