all of us do naturally and repeatedly. In our private lives, we regularly hold to-do lists to organise holidays, errands, and every little thing in between.
At work, we depend on job trackers and venture plans to maintain groups aligned. For builders, it’s also widespread to depart 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 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 take advantage of repeatedly) are prime examples of this idea.
They break complicated requests into an preliminary set of steps, manage them as a to-do record 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 completely different instruments, and observe progress in an comprehensible method.
On this article, we dive into how brokers make the most of to-do record capabilities, analyze the underlying elements of the planning course of, and reveal its implementation with LangChain.
Contents
(1) Instance State of affairs for Planning Agent
(2) Key Parts of To-Do Capabilities
(3) Placing it collectively in a Middleware
The accompanying code is obtainable in this GitHub repo.
(1) Instance State of affairs for Planning Agent
Let’s take 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 example 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 record ensuing from the agent’s planning:
The usage of structured note-taking by way of to-do lists permits brokers to take care of persistent reminiscence exterior 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 go 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 permits 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, alter, or prolong its conduct.
It offers us management and visibility over brokers’ behaviors with out altering their core logic. It may be used to rework prompts and outputs, handle retries or early exits, and apply safeguards (e.g., guardrails, PII checks).
TodoListMiddleware is a built-in middleware that particularly supplies to-do record administration capabilities to brokers. Subsequent, we discover how the TodoListMiddleware works beneath the hood.
(2) Key Parts of To-Do Capabilities
A planning agent’s to-do record administration capabilities boil down to those 4 key elements:
- To-do job merchandise
- Checklist of to-do objects
- A software that writes and updates the to-do record
- To-do system immediate replace
The TodoListMiddleware brings these components collectively to allow an agent’s to-do record capabilities.
Let’s take a more in-depth take a look at every part and the way it’s carried out within the to-do middleware code.
(2.1) To-do job merchandise
A to-do merchandise is the smallest unit in a to-do record, 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 discipline 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": "Evaluate flight choices from Singapore to Tokyo",
"standing": "accomplished"
},(2.2) Checklist 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 record of to-do objects, which can be up to date as duties are carried out:
The todos discipline is non-obligatory (NotRequired), that means it might be absent when first initialized (i.e., the agent could not but have any duties in its plan).
OmitFromInput signifies that todos is managed internally by the middleware and shouldn’t be supplied immediately as consumer enter.
State is the agent’s short-term reminiscence, capturing current conversations and key data so it might act appropriately primarily based on prior context and knowledge.
On this case, the to-do record 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 record:
todos: record[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 write down and replace to-dos
With the fundamental construction of the to-do record established, we now want a software for the LLM agent to handle and replace it as duties get executed.
Right here is the usual technique to outline our software (write_todos):
The write_todos software returns a Command that instructs the agent to replace its to-do record 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 crucial extra immediate, guiding it on methods to use it accurately and what inputs to supply.
Right here is LangChain’s (fairly prolonged) expression of the software description:
We are able to see that the outline is extremely structured and exact, defining when and methods to use the software, job states, and administration guidelines.
It additionally supplies clear pointers for monitoring complicated duties, breaking them into clear steps, and updating them systematically.
Be at liberty to take a look at Deepagents’ extra succinct interpretation of a to-do software description right here
(2.4) System immediate replace
The ultimate factor of organising the to-do functionality is updating the agent’s system immediate.
It’s accomplished 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, supplies context for complicated, multi-step duties, and descriptions finest practices for sustaining and updating the to-do record:
(3) Placing it collectively in a Middleware
Lastly, all 4 key elements come collectively in a single class referred to 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 record - Dynamically create
write_todossoftware for updating the record 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 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 beneath:
Wrapping it up
Similar 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 LangChain’s middleware implementation, we additionally acquire deeper perception into how deliberate duties may be structured, tracked, and executed by brokers.
Try this GitHub repo for the code implementation.
