all of us do naturally and frequently. In our private lives, we frequently hold to-do lists to organise holidays, errands, and every thing in between.
At work, we depend on activity trackers and challenge plans to maintain groups aligned. For builders, it is usually 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 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 take advantage of frequently) are prime examples of this idea.
They break complicated requests into an preliminary set of steps, arrange them as a to-do checklist with dependencies, and replace the plan in actual time as duties are accomplished or new info arises.
This readability allows brokers to deal with lengthy sequences of actions, coordinate throughout completely different instruments, and monitor 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) Instance Situation for Planning Agent
(2) Key Parts of To-Do Capabilities
(3) Placing it collectively in a Middleware
The accompanying code is accessible in this GitHub repo.
(1) Instance Situation for Planning Agent
Let’s take a look at the instance situation to anchor our walkthrough.
We’ll 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 person question and look at the to-do checklist ensuing from the agent’s planning:
Using structured note-taking by way of to-do lists allows 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 easy: 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 enables us to inject code to watch, alter, or lengthen 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 offers to-do checklist administration capabilities to brokers. Subsequent, we discover how the TodoListMiddleware works underneath the hood.
(2) Key Parts of To-Do Capabilities
A planning agent’s to-do checklist administration capabilities boil down to those 4 key parts:
- To-do activity merchandise
- Checklist of to-do objects
- A instrument that writes and updates the to-do checklist
- To-do system immediate replace
The TodoListMiddleware brings these components collectively to allow an agent’s to-do checklist capabilities.
Let’s take a more in-depth take a look at every element and the way it’s applied within the to-do middleware code.
(2.1) To-do activity merchandise
A to-do merchandise is the smallest unit in a to-do checklist, representing a single activity. It’s represented by two fields: activity 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": "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 checklist of to-do objects, which might be up to date as duties are carried out:
The todos discipline 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 implies that todos is managed internally by the middleware and shouldn’t be supplied instantly as person enter.
State is the agent’s short-term reminiscence, capturing current conversations and key info so it may act appropriately primarily based on prior context and knowledge.
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) Device to write down and replace to-dos
With the fundamental 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 approach 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 easy, 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 essential further immediate, guiding it on use it accurately 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 use the instrument, activity states, and administration guidelines.
It additionally offers 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 instrument description right here
(2.4) System immediate replace
The ultimate component of organising the to-do functionality is updating the agent’s system immediate.
It’s performed by injecting WRITE_TODOS_SYSTEM_PROMPT into the principle 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, offers context for complicated, 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 stream 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 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 resolve issues extra successfully and precisely.
By LangChain’s middleware implementation, we additionally achieve deeper perception into how deliberate duties could be structured, tracked, and executed by brokers.
Try this GitHub repo for the code implementation.
