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.
TodoListMiddleware(
self,
*,
system_prompt: str = WRITE_TODOS_SYSTEM_PROMPT,
tool_description: str = WRITE_TODOS_TOOL_DESCRIPTION
)Example:
from langchain.agents.middleware.todo import TodoListMiddleware
from langchain.agents import create_agent
agent = create_agent("openai:gpt-4o", 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 trackingUpdate the system message to include the todo system prompt.
Update the system message to include the todo system prompt.
Check for parallel write_todos tool calls and return errors if detected.
The todo list is designed to be updated at most once per model turn. Since
the write_todos tool replaces the entire todo list with each call, making
multiple parallel calls would create ambiguity about which update should take
precedence. This method prevents such conflicts by rejecting any response that
contains multiple write_todos tool calls.
Check for parallel write_todos tool calls and return errors if detected.
Async version of after_model. The todo list is designed to be updated at
most once per model turn. Since the write_todos tool replaces the entire
todo list with each call, making multiple parallel calls would create ambiguity
about which update should take precedence. This method prevents such conflicts
by rejecting any response that contains multiple write_todos tool calls.
Start the shell session and run startup commands.
Async start the shell session and run startup commands.
Check model call limits before making a model call.
Async check model call limits before making a model call.
Run shutdown commands and release resources when an agent completes.
Async run shutdown commands and release resources when an agent completes.
Intercept tool execution for retries, monitoring, or modification.
Intercept and control async tool execution via handler callback.