all of us do naturally and frequently. In our private lives, we regularly hold to-do lists to organise holidays, errands, and all the pieces in between.
At work, we depend on process trackers and venture plans to maintain groups aligned. For builders, it’s also frequent 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 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 frequently) 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 allows 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 record capabilities, analyze the underlying elements of the planning course of, and exhibit its implementation with LangChain.
Contents
(1) Instance Situation for Planning Agent
(2) Key Elements of To-Do Capabilities
(3) Placing it collectively 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 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 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 look at the to-do record ensuing from the agent’s planning:
Using structured note-taking through to-do lists allows brokers to keep up 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 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 watch, alter, or prolong its habits.
It provides 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 gives to-do record 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 record administration capabilities boil down to those 4 key elements:
- To-do process merchandise
- Listing of to-do gadgets
- A software that writes and updates the to-do record
- To-do system immediate replace
The TodoListMiddleware brings these parts collectively to allow an agent’s to-do record capabilities.
Let’s take a better have a look at every part 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 record, 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 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": "Examine flight choices from Singapore to Tokyo",
"standing": "accomplished"
},(2.2) Listing of to-do gadgets
Now that we’ve outlined the construction of a Todo merchandise, we discover how a set of to-do gadgets 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 gadgets, which might be up to date as duties are carried out:
The todos discipline is non-obligatory (NotRequired), which 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 offered immediately as consumer enter.
State is the agent’s short-term reminiscence, capturing current conversations and key data so it could actually 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) Software to put in writing 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 solution 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 vital extra immediate, guiding it on the right way to use it appropriately and what inputs to offer.
Right here is LangChain’s (fairly prolonged) expression of the software description:
We will see that the outline is extremely structured and exact, defining when and the right way to use the software, process states, and administration guidelines.
It additionally gives clear pointers 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 right here
(2.4) System immediate replace
The ultimate aspect of organising the to-do functionality is updating the agent’s system immediate.
It’s finished by injecting WRITE_TODOS_SYSTEM_PROMPT into the principle 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, gives context for complicated, multi-step duties, and descriptions greatest 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 known 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 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 means of 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
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 way of LangChain’s middleware implementation, we additionally acquire deeper perception into how deliberate duties could be structured, tracked, and executed by brokers.
Try this GitHub repo for the code implementation.
