all of us do naturally and recurrently. In our private lives, we regularly preserve to-do lists to organise holidays, errands, and all the things in between.
At work, we depend on job trackers and mission plans to maintain groups aligned. For builders, additionally it is widespread to go away TODO feedback within the code as reminders for future adjustments.
Unsurprisingly, LLM brokers additionally profit from clear to-do lists to information their planning.
To-do lists assist brokers plan and monitor complicated 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 recurrently) are prime examples of this idea.
They break complicated requests into an preliminary set of steps, set up them as a to-do listing with dependencies, and replace the plan in actual time as duties are accomplished or new info arises.
This readability permits brokers to deal with lengthy sequences of actions, coordinate throughout totally different instruments, and monitor progress in an comprehensible method.
On this article, we dive into how brokers make the most of to-do listing capabilities, analyze the underlying parts of the planning course of, and reveal 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 on the market in this GitHub repo.
(1) Instance Situation for Planning Agent
Let’s have a look at the instance situation 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 person question and think about the to-do listing ensuing from the agent’s planning:
The usage of structured note-taking by way of to-do lists permits brokers to keep up persistent reminiscence exterior the context window. This technique improves an agent’s potential to handle and retain related context over time.
The code setup is simple: create_agent creates the LLM agent occasion, we move 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 identify 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 permits us to inject code to watch, alter, or lengthen its conduct.
It offers 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 offers to-do listing 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 listing administration capabilities boil down to those 4 key parts:
- To-do job merchandise
- Record of to-do objects
- A software that writes and updates the to-do listing
- To-do system immediate replace
The TodoListMiddleware brings these parts collectively to allow an agent’s to-do listing capabilities.
Let’s take a better have a look at every element and the way it’s applied within the to-do middleware code.
(2.1) To-do job merchandise
A to-do merchandise is the smallest unit in a to-do listing, representing a single job. It’s represented by two fields: job description and present standing.
In LangChain, that is modeled as a Todo kind, 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) Record 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 listing of to-do objects, which shall be up to date as duties are carried out:
The todos area is optionally available (NotRequired), which means it could be absent when first initialized (i.e., the agent could not but have any duties in its plan).
OmitFromInput implies that todos is managed internally by the middleware and shouldn’t be offered straight as person enter.
State is the agent’s short-term reminiscence, capturing current conversations and key info so it could actually act appropriately based mostly on prior context and knowledge.
On this case, the to-do listing stays inside the state for the agent to reference and replace duties persistently all through the session.
Right here is an instance of a to-do listing:
todos: listing[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) Instrument to put in writing and replace to-dos
With the fundamental construction of the to-do listing established, we now want a software for the LLM agent to handle and replace it as duties get executed.
Right here is the usual method to outline our software (write_todos):
The write_todos software returns a Command that instructs the agent to replace its to-do listing 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 software.
When the agent calls the software, the software description serves because the important extra immediate, guiding it on tips on how to use it accurately and what inputs to offer.
Right here is LangChain’s (fairly prolonged) expression of the software description:
We are able to see that the outline is very structured and exact, defining when and tips on how to use the software, job states, and administration guidelines.
It additionally offers clear tips for monitoring complicated 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 software 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 carried out by injecting WRITE_TODOS_SYSTEM_PROMPT into the primary immediate, explicitly informing the agent that the write_todos software exists.
It guides the agent on when and why to make use of the software, offers context for complicated, multi-step duties, and descriptions finest practices for sustaining and updating the to-do listing:
(3) Placing it collectively in a Middleware
Lastly, all 4 key parts come collectively in a single class referred to as TodoListMiddleware, which packages the to-do capabilities right into a cohesive move for the agent:
- Outline
PlanningStateto trace duties as a part of a to-do listing - Dynamically create
write_todossoftware for updating the listing 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 via the middleware’s wrap_model_call (and awrap_model_call) methodology, which appends it to the agent’s system message for each mannequin name, as proven under:
Wrapping it up
Identical to people, brokers use to-do lists to interrupt down complicated issues, keep organized, and adapt in actual time, enabling them to unravel issues extra successfully and precisely.
By means of LangChain’s middleware implementation, we additionally acquire deeper perception into how deliberate duties might be structured, tracked, and executed by brokers.
Try this GitHub repo for the code implementation.
