Understanding Middleware in Deep Agents (With Runnable Examples) Deep Agents, an open-source framework, provides a middleware stack that handles context windows, interrupted tool calls, task tracking, sub-agents, and file management automatically. The middleware runs in a specific order, with components like TodoListMiddleware and PatchToolCallsMiddleware, allowing developers to add custom logic without modifying the core agent loop. If you've built even a simple AI agent, you've probably noticed that the "agent loop" itself is deceptively simple: the model gets a message, decides whether to call a tool, gets the result back, and repeats until it has an answer. But real-world agents need a lot more than that bare loop to actually work well. What happens when a conversation gets so long it blows past the model's context window? What if a tool call gets interrupted halfway through and leaves your message history in a broken state? What if you want the agent to keep a running todo list of what it's working on, or delegate parts of a task to a specialized sub-agent, or read and write files as part of its job? You could bolt all of this onto your agent manually. Or, if you're using Deep Agents, you get most of it for free through something called middleware . This post walks through what middleware actually is, why Deep Agents ships with a default stack of it, and how each piece behaves, with runnable code for each one so you can see it working instead of just reading about it. If you've done any web development, the term "middleware" probably already rings a bell. It's the same idea here. Middleware is code that sits around the core agent loop and gets a chance to run before or after certain things happen, like before a tool call executes, after the model responds, or right before messages are sent to the model. Instead of writing all of this logic directly inside your agent, you attach separate, independent pieces of middleware that each handle one specific concern. This matters for two reasons: Think of it like a pipeline. A request comes in, passes through a stack of middleware each one doing its own small job , reaches the model, and the response passes back out through that same stack on the way out. When you call create deep agent , you're not getting a bare-bones agent loop. You're getting an agent that already knows how to track tasks, manage files, spin up sub-agents, keep conversations within context limits, and recover gracefully from interrupted tool calls, all because of a default middleware stack that's assembled for you automatically. Here's the order that stack runs in, from first to last: skills injects skill metadata before file tools runAfter that, there's room for your own custom middleware, followed by a "tail" of provider-specific extras: things like prompt caching for Anthropic or Bedrock models, memory injection, excluded-tool filtering, and human-in-the-loop approval steps. The important thing to understand up front is that order matters . Each middleware runs at a specific point for a reason, for example, PatchToolCallsMiddleware needs to run before prompt caching so the cached message prefix actually matches what gets sent to the model. We'll come back to details like this as we go through each piece. Rather than explain all of this in the abstract, the rest of this post goes through each middleware one at a time with a runnable example, so you can actually see: By the end, you should have a clear mental model of what's happening under the hood every time you call create deep agent , and enough understanding to start adding your own custom middleware or overriding the defaults when you need something different. Let's start with the first one in the stack: TodoListMiddleware . python """ Example: TodoListMiddleware """ import os import sys sys.stdout.reconfigure encoding="utf-8" sys.stderr.reconfigure encoding="utf-8" from dotenv import load dotenv load dotenv from langchain.tools import tool from langchain nvidia ai endpoints import ChatNVIDIA from deepagents import create deep agent @tool def get weather city: str - str: """Get the current weather in a city.""" return f"The weather in {city} is sunny, 24C." @tool def get time city: str - str: """Get the current time in a city.""" return f"The current time in {city} is 12:00 PM." @tool def get population city: str - str: """Get the approximate population of a city.""" return f"The population of {city} is approximately 14 million." Build the model directly so we can control the timeout model = ChatNVIDIA model="nvidia/nemotron-3-super-120b-a12b", api key=os.environ "NVIDIA API KEY" , agent = create deep agent model=model, tools= get weather, get time, get population , system prompt="You are a helpful assistant. For multi-step requests, " "plan your steps using the todo list before executing them.", result = agent.invoke { "messages": "user", "I need a full briefing on Tokyo: check the weather, the " "current time, and the population. Plan this out first, " "then give me a summary.", }, config={"configurable": {"thread id": "todo-example-1"}}, for m in result "messages" : if m.type == "ai": if m.tool calls: for call in m.tool calls: print f" Tool Call {call 'name' } - {call 'args' }" if m.content: print f"AI: {m.content}" elif m.type == "tool": print f" Tool Result - {m.name} : {m.content}" if "todos" in result: print "\nFinal todo list state:" for todo in result "todos" : print f" - {todo}" """ Example: SkillsMiddleware The SkillsMiddleware is added to the default stack automatically when you pass skills= to create deep agent . It loads each skill's name and description from the YAML frontmatter of SKILL.md into the system prompt at startup, and gives the agent a read file tool so it can pull the full instructions in progressive disclosure when a task matches a skill. This example uses FilesystemBackend so skills are loaded from disk relative to a project root. Two sample skills live under middleware-examples/skills/ : - code-review: reviews code for bugs, security, performance, and style. - git-commit: writes conventional commit messages from a diff or summary. Run from the project root with: uv run middleware-examples/02 skills middleware.py """ import os import sys from pathlib import Path sys.stdout.reconfigure encoding="utf-8" sys.stderr.reconfigure encoding="utf-8" from dotenv import load dotenv load dotenv from langchain nvidia ai endpoints import ChatNVIDIA from deepagents import create deep agent from deepagents.backends.filesystem import FilesystemBackend ROOT = Path file .resolve .parent.parent SKILLS DIR = ROOT / "middleware-examples" / "skills" backend = FilesystemBackend root dir=str ROOT llm = ChatNVIDIA model="nvidia/nemotron-3-super-120b-a12b", timeout=120, agent = create deep agent model=llm, backend=backend, skills= str SKILLS DIR , system prompt= "You are a helpful assistant. When a user request matches one of your " "available skills, read the skill's SKILL.md and follow its instructions." , result = agent.invoke { "messages": "user", "Please turn this diff into a commit message:\n" "+ added 5 req/sec rate limiting to /login\n" "+ added unit tests for the limiter\n" "- removed the in-memory counter fallback", , "user", "review the below code:\n" "def add a, b :\n" " return a.tO string + b", , }, config={"configurable": {"thread id": "skills-example-1"}}, print "\n=== Skill state ===" for m in result "messages" : if m.type == "ai" and m.content: print f"\nAI: {m.content}" """ Example: FilesystemMiddleware The FilesystemMiddleware handles file system operations such as reading, writing, and navigating directories. When you pass permissions, filesystem permissions enforcement is included. This example shows basic filesystem operations without custom permissions. Run with: python middleware-examples/03 filesystem middleware.py """ import os import sys from pathlib import Path sys.stdout.reconfigure encoding="utf-8" sys.stderr.reconfigure encoding="utf-8" from dotenv import load dotenv load dotenv from langchain nvidia ai endpoints import ChatNVIDIA from deepagents import create deep agent from deepagents.backends.filesystem import FilesystemBackend FIX: this was .parent.parent , which resolves to one directory above your project this file lives at