This is The Powerful Pattern Behind Top AI Agents
Hey everyone!
Have you ever wondered how AI agents like Claude, Anthropic’s Computer Use agent, Gemini’s CLI tools, or LangChain agents handle complex tasks so effectively?
There’s a powerful design pattern that all these top agents share - and today, I’m going to break it down for you.
It’s called write_todos or Todo Tool, and once you understand it, you’ll never build AI agents the same way again.
Full walkthrough of the custom write_todo implementation in Customer Service Agent.
In many AI agents, write_todos is used to create and manage TODO lists that help the agent stay organized and focused during long or complex tasks.
For example, Claude Code uses a feature called plan mode to generate a structured list of steps before starting any work. This is done using a tool called TodoWrite, which is based on a special prompt.
Each TODO item includes:
A short, clear description of the task
A status: pending, in progress, or completed
As tasks grow in size—sometimes involving 50 or more tool calls—it becomes harder for the agent to remember everything. This can lead to context rot, where the agent forgets earlier goals or drifts off-topic.
To prevent this, agents like Manus regularly rewrite and update their TODO lists. This helps them stay on track by constantly reminding themselves of their goals, reducing the risk of losing focus or deviating from the task.
There are 2 parts
Phase 1: Planning The agent receives a complex task and uses an LLM to decompose it into smaller, actionable subtasks. Think of it like a project manager breaking down a big project.
[Show example: “Handle customer complaint about delayed order”] The agent might plan:
Todo 1: Search knowledge base for refund policy
Todo 2: Look up similar past tickets
Todo 3: Check shipping status
Todo 4: Draft response with options
Phase 2: Writing (The Critical Part) [Highlight this]
Here’s the key difference: The agent writes these todos down - typically to a file, database, or persistent storage.
Why use ‘write_todos’?
Reason #1: Transparency and Debuggability
When your agent writes its plan to a file, you as a developer - or even the user - can see exactly what it’s planning to do BEFORE it does it.
Reason #2: Fault Tolerance and Recovery
Here’s where it gets really powerful. If your agent crashes halfway through a task, what happens?
Without write-todos: Everything is lost. Start over. With write-todos: Read the file, see what’s completed, continue where you left off.
Reason #3: Human-in-the-Loop Workflows
Sometimes you want human approval before execution. With write-todos:
Agent creates plan and writes it
Human reviews and approves (or modifies)
Agent reads the (potentially modified) plan and executes
When to use ‘write_todos’?
Multi-step tasks (3+ steps)
If your task naturally breaks down into multiple sequential or parallel steps, write-todos will help.
Research and analysis
Customer support workflows
Data processing pipelines
Code generation and deployment
Content creation workflows
Long-running operations (minutes to hours)
Anything that takes significant time benefits from fault tolerance and observability.
High-stakes operations
Financial transactions, data deletion, production deployments - anything where you want a review before action.
Collaborative agent-human workflows
When humans need to be in the loop at any
❌ Don’t use write-todos when:
1. Simple, single-step tasks “What’s the weather?” - No need for todos.
2. Real-time, low-latency requirements File I/O adds overhead. If you need sub-second responses, keep it in memory.
3. Stateless, idempotent operations If the operation can be safely retried from scratch, the crash recovery benefit is less valuable.
The ToDo Methods in our Agent
Below is a simple implementation of the Todo tools for our Customer Service Agent.
The generated Todo file
{
“created_at”: “2025-11-11T01:26:18.171559”,
“todos”: [
{
“id”: 1,
“task”: “Search knowledge base for \”refund policy\” to understand the guidelines for processing refunds.”,
“status”: “completed”,
“result”: “No relevant article found in knowledge base.”
},
{
“id”: 2,
“task”: “Look up the customer’s order status in the system to determine if the product has shipped or if there are any delays.”,
“status”: “completed”,
“result”: “Found 2 similar past tickets:\n- Ticket TICKET-2024-089: Order delayed - carrier issue\n Customer reported order stuck in transit for 8 days. Root cause: Holiday shipping backlog. Resolution: Expedited replacement sent, original order refu...\n Resolved in: 2 days\n- Ticket TICKET-2024-112: Package not delivered after 10 days\n Order placed 10 days ago, tracking shows ‘in transit’ with no updates. Customer requested refund. Resolution: Refund processed, new order sent with ex...\n Resolved in: 1 day\n”
},
{
“id”: 3,
“task”: “Check recent similar tickets or issues to see if other customers are experiencing similar delays with the same product.”,
“status”: “completed”,
“result”: “Found 2 similar past tickets:\n- Ticket TICKET-2024-089: Order delayed - carrier issue\n Customer reported order stuck in transit for 8 days. Root cause: Holiday shipping backlog. Resolution: Expedited replacement sent, original order refu...\n Resolved in: 2 days\n- Ticket TICKET-2024-112: Package not delivered after 10 days\n Order placed 10 days ago, tracking shows ‘in transit’ with no updates. Customer requested refund. Resolution: Refund processed, new order sent with ex...\n Resolved in: 1 day\n”
},
{
“id”: 4,
“task”: “Review current refund processing times to inform the customer about how long it may take to receive their refund if approved.”,
“status”: “completed”,
“result”: “Completed: Review current refund processing times to inform the customer about how long it may take to receive their refund if approved.”
}
]
}
I strongly recommend you go through the video or the code to full understand this pattern.
So there you have it - the write-todos pattern that powers some of the most sophisticated AI agents in production today.
To recap:
What it is: Externalize the agent’s plan by writing it to persistent storage
Why use it: Transparency, fault tolerance, human-in-the-loop, better planning, and testability
When to use it: Multi-step tasks, long-running operations, high-stakes work, collaborative workflows
The complete code for this example is in the description below. I encourage you to:
Clone it and run it yourself
Modify it to handle different support scenarios
Try adding a “human approval” step before execution
Build your own agent using this pattern