all of us do naturally and often. In our private lives, we frequently preserve to-do lists to organise holidays, errands, and all the things in between.
At work, we depend on process trackers and mission plans to maintain groups aligned. For builders, it’s also widespread to go away TODO feedback within the code as reminders for future modifications.
Unsurprisingly, LLM brokers additionally profit from clear to-do lists to information their planning.
To-do lists assist brokers plan and observe advanced duties extra successfully, making them particularly helpful for multi-tool coordination and long-running operations the place progress must be seen.
Coding brokers like OpenAI Codex, Cline, and Claude Code (which I exploit often) are prime examples of this idea.
They break advanced requests into an preliminary set of steps, set up them as a to-do checklist with dependencies, and replace the plan in actual time as duties are accomplished or new data arises.
This readability permits brokers to deal with lengthy sequences of actions, coordinate throughout totally different instruments, and observe progress in an comprehensible method.
On this article, we dive into how brokers make the most of to-do checklist capabilities, analyze the underlying parts of the planning course of, and display its implementation with LangChain.
Contents
(1) Example Scenario for Planning Agent
(2) Key Components of To-Do Capabilities
(3) Putting it together in a Middleware
The accompanying code is out there in this GitHub repo.
(1) Instance Situation for Planning Agent
Let’s have a look at the instance state of affairs to anchor our walkthrough.
We are going to arrange a single agent to plan a journey itinerary and execute the reserving duties. The agent has entry to :
On this instance, these instruments are mocked and don’t carry out actual bookings; they’re included for instance the agent’s planning logic and the way it makes use of to-do lists.
Right here is the code to implement our planning agent in LangChain:
We enter a consumer question and consider the to-do checklist ensuing from the agent’s planning:
Using structured note-taking by way of to-do lists permits brokers to take care of persistent reminiscence outdoors the context window. This technique improves an agent’s capability to handle and retain related context over time.
The code setup is simple: create_agent creates the LLM agent occasion, we cross within the system immediate, choose the mannequin (GPT-5.1), and hyperlink the instruments.
What’s noteworthy is the TodoListMiddleware() object that’s handed into the middleware parameter.
Firstly, what’s LangChain’s middleware?
Because the title suggests, it’s a center layer that allows you to run customized code earlier than and after LLM calls.
Consider middleware as a programmable layer that enables us to inject code to observe, regulate, or prolong its conduct.
It provides us management and visibility over brokers’ behaviors with out altering their core logic. It may be used to remodel prompts and outputs, handle retries or early exits, and apply safeguards (e.g., guardrails, PII checks).
TodoListMiddleware is a built-in middleware that particularly gives to-do checklist administration capabilities to brokers. Subsequent, we discover how the TodoListMiddleware works below the hood.
(2) Key Elements of To-Do Capabilities
A planning agent’s to-do checklist administration capabilities boil down to those 4 key parts:
- To-do process merchandise
- Listing of to-do objects
- A instrument that writes and updates the to-do checklist
- To-do system immediate replace
The TodoListMiddleware brings these parts collectively to allow an agent’s to-do checklist capabilities.
Let’s take a better have a look at every element and the way it’s carried out within the to-do middleware code.
(2.1) To-do process merchandise
A to-do merchandise is the smallest unit in a to-do checklist, representing a single process. It’s represented by two fields: process description and present standing.
In LangChain, that is modeled as a Todo sort, outlined utilizing TypedDict:
The content material area represents the outline of the duty that the agent must do subsequent, whereas the standing tracks whether or not the duty has not been began (pending), being labored on (in_progress), or completed (accomplished).
Right here is an instance of a to-do merchandise:
{
"content material": "Examine flight choices from Singapore to Tokyo",
"standing": "accomplished"
},(2.2) Listing of to-do objects
Now that we’ve outlined the construction of a Todo merchandise, we discover how a set of to-do objects is saved and tracked as a part of the general plan.
We outline a State object (PlanningState) to seize the plan as a checklist of to-do objects, which can be up to date as duties are carried out:
The todos area is elective (NotRequired), which means it could be absent when first initialized (i.e., the agent might not but have any duties in its plan).
OmitFromInput signifies that todos is managed internally by the middleware and shouldn’t be offered straight as consumer enter.
State is the agent’s short-term reminiscence, capturing current conversations and key data so it could act appropriately primarily based on prior context and data.
On this case, the to-do checklist stays throughout the state for the agent to reference and replace duties persistently all through the session.
Right here is an instance of a to-do checklist:
todos: checklist[Todo] = [
{
"content": "Research visa requirements for Singapore passport holders visiting Japan",
"status": "completed"
},
{
"content": "Compare flight options from Singapore to Tokyo",
"status": "in_progress"
},
{
"content": "Book flights and hotels once itinerary is finalized",
"status": "pending"
}
](2.3) Software to jot down and replace to-dos
With the essential construction of the to-do checklist established, we now want a instrument for the LLM agent to handle and replace it as duties get executed.
Right here is the usual strategy to outline our instrument (write_todos):
The write_todos instrument returns a Command that instructs the agent to replace its to-do checklist and append a message recording the change.
Whereas the write_todos construction is simple, the magic lies within the description (WRITE_TODOS_TOOL_DESCRIPTION) of the instrument.
When the agent calls the instrument, the instrument description serves because the vital extra immediate, guiding it on find out how to use it appropriately and what inputs to offer.
Right here is LangChain’s (fairly prolonged) expression of the instrument description:
We are able to see that the outline is extremely structured and exact, defining when and find out how to use the instrument, process states, and administration guidelines.
It additionally gives clear pointers for monitoring advanced duties, breaking them into clear steps, and updating them systematically.
Be happy to take a look at Deepagents’ extra succinct interpretation of a to-do instrument description here
(2.4) System immediate replace
The ultimate ingredient of establishing the to-do functionality is updating the agent’s system immediate.
It’s executed by injecting WRITE_TODOS_SYSTEM_PROMPT into the primary immediate, explicitly informing the agent that the write_todos instrument exists.
It guides the agent on when and why to make use of the instrument, gives context for advanced, multi-step duties, and descriptions finest practices for sustaining and updating the to-do checklist:
(3) Placing it collectively in a Middleware
Lastly, all 4 key parts come collectively in a single class known as TodoListMiddleware, which packages the to-do capabilities right into a cohesive circulation for the agent:
- Outline
PlanningStateto trace duties as a part of a to-do checklist - Dynamically create
write_todosinstrument for updating the checklist and making it accessible to the LLM - Inject
WRITE_TODOS_SYSTEM_PROMPTto information the agent’s planning and reasoning
The WRITE_TODOS_SYSTEM_PROMPT is injected by means of the middleware’s wrap_model_call (and awrap_model_call) technique, which appends it to the agent’s system message for each mannequin name, as proven under:
Wrapping it up
Similar to people, brokers use to-do lists to interrupt down advanced issues, keep organized, and adapt in actual time, enabling them to unravel issues extra successfully and precisely.
By LangChain’s middleware implementation, we additionally acquire deeper perception into how deliberate duties may be structured, tracked, and executed by brokers.
Take a look at this GitHub repo for the code implementation.
