Generative AI and Agentic AILangChain 1.4 · LangGraph 1.2 · Python 3.12 or 3.13
Dashboard
0%

Deep agents

A deep agent is an agent built for long, multi-step tasks: besides the model and its tools it has a plan it can write and update, subagents it can hand work to, and a file system where it keeps notes and results.

Last updated: 08 Oct, 2026 · deepagents 0.7 · LangChain 1.4

A tool-using agent keeps everything in one message list. On a long task that list grows, early results get buried, and the agent has no written plan to come back to. The deepagents library from LangChain wraps an agent with the pieces a long task needs.

Shallow agents and their limits

Shallow agents and their limits · from the Complete Agentic AI Course video · 8:03:23 to 8:07:19

The video starts with what it calls a shallow agent: a model that either answers or calls a tool, takes the tool's output, and finishes. Its problems, as the clip lists them, are no explicit planning, trouble with a complex question that must be split into smaller ones, and little context carried along. It then draws the ReAct agent from ReAct agents, where the tool result goes back to the model and the loop can repeat, and calls that shallow too: there is still no planning, no state management and no persistent memory. In the first picture the tool result ends the run, while create_agent already feeds each result back to the model.

The four parts of a deep agent · from the Complete Agentic AI Course video · 8:11:44 to 8:17:17

The video describes the planning tool and a Claude-Code-style system prompt as built in. In deepagents 0.7.23, the version used here, they are not. The default tools are ls, read_file, write_file, edit_file, delete, glob, grep, execute and task, which hands work to a subagent. There is no default write_todos tool and no default system prompt: the planning tool is added as middleware, and the prompt is whatever you pass in.

Planning, subagents, a system prompt and files

The clip names four parts, using Claude Code as the model of a deep agent:

  • A planning tool. Before acting, the agent writes a to-do list for the task. A holiday booking becomes a list of days and things to book, and the list tells it what is done and what is left.
  • Subagents. The to-do items are carried out by other agents, each suited to its item: one that searches the internet, one that reads research papers, one that writes, one that checks.
  • A system prompt. Instructions that set the agent's tone and way of working.
  • A file system. A shared place where every subagent can save results, which works as memory that lasts through the task.
A deep agent has a main model connected to a plan (write_todos, added as middleware), subagents reached with the task tool, files through write_file and read_file, and the tools you pass in.

Installing deepagents

pip install "deepagents==0.7.23"

Creating a deep agent with create_deep_agent

create_deep_agent takes the same kind of arguments as create_agent and a few more. Syntax: create_deep_agent(model=..., tools=[...], system_prompt="...", subagents=[...], middleware=[...]). The video passes a Qwen model on Groq, which Groq has retired; the code here passes groq:openai/gpt-oss-20b with max_retries=8, because a deep agent sends long prompts and Groq's free tier limits tokens per minute; the client waits and retries instead of stopping at the first rate-limit reply. Always pass a model: leaving it out falls back to a default that is deprecated.

The video's agent has a search tool and the system prompt "Act as a researcher", and it prints the built agent to compare with create_agent. A quick way to see what a deep agent carries is to list the tools its tool node holds. The second agent adds the planning middleware:

Example
from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware
from langchain.chat_models import init_chat_model

model = init_chat_model("groq:openai/gpt-oss-20b", max_retries=8)

plain = create_deep_agent(model=model, tools=[])
planned = create_deep_agent(model=model, tools=[], middleware=[TodoListMiddleware()])

for name, agent in [("default", plain), ("with TodoListMiddleware", planned)]:
    print(name, "->", sorted(agent.nodes["tools"].bound.tools_by_name))
  • The default agent has nine tools: the file tools ls, read_file, write_file, edit_file, delete, glob and grep, then execute, and task, which hands work to a subagent. write_todos is not among them.
  • With TodoListMiddleware the same nine tools are there, plus write_todos.

Adding a plan with TodoListMiddleware

TodoListMiddleware is the same middleware create_agent accepts. It gives the agent a write_todos tool and keeps the list in the agent's state under todos, where a person or a later step can read it. Pass it in middleware=[...], as in the second agent above.

Handing work to a subagent

A subagent is a dictionary: a name, a description that tells the main agent when to use it, a system_prompt, and its own tools. The main agent reaches it through the built-in task tool, which sends the subagent a description of the job and returns its final message. The subagent works in its own message list, so its searches do not fill the main agent's list. This one looks facts up on Wikipedia, with the wiki_search tool from Multi-agent systems:

python
import json
import time
import urllib.error
import urllib.parse
import urllib.request

from langchain.tools import tool

@tool
def wiki_search(query: str) -> str:
    """Search Wikipedia. Returns the page title, its link and the first sentences of the page."""
    params = {"action": "query", "format": "json", "generator": "search", "gsrsearch": query, "gsrlimit": 1,
              "prop": "extracts", "exintro": 1, "explaintext": 1, "exsentences": 3}
    request = urllib.request.Request("https://en.wikipedia.org/w/api.php?" + urllib.parse.urlencode(params),
                                     headers={"User-Agent": "agent-course-demo/1.0 (learning project)"})
    for attempt in range(3):
        try:
            with urllib.request.urlopen(request, timeout=20) as response:
                pages = json.load(response).get("query", {}).get("pages", {})
            break
        except urllib.error.HTTPError as error:
            if error.code != 429:
                return f"Search failed with HTTP {error.code}."
            time.sleep(2 * (attempt + 1))
    else:
        return "Search is busy, try again later."
    if not pages:
        return "No page found."
    page = next(iter(pages.values()))
    title = page["title"]
    return f"{title} (https://en.wikipedia.org/wiki/{title.replace(' ', '_')}): {page['extract']}"
python
subagents = [{
    "name": "researcher",
    "description": "Looks facts up on Wikipedia. Give it one question at a time.",
    "system_prompt": "Search Wikipedia and answer in two sentences.",
    "tools": [wiki_search],
}]

Giving the agent files

The file tools work on a virtual file system kept in the agent's state, so nothing is written to disk. write_file creates a file, read_file and edit_file change it, and the files come back in the result under files. Large tool results are also moved into files, so the message list stays short. In the video's run, result["files"] held a large tool result saved by the agent itself.

Running the deep agent

The agent below has a system prompt that lists the steps in order, the planning middleware, and the researcher subagent. The task needs all three: plan, look something up through the subagent, and save the result. A deep agent decides for itself which of its tools to use, so the prompt spells the steps out.

python
agent = create_deep_agent(
    model=model,
    system_prompt=(
        "Follow these steps in order. 1: call write_todos with your plan. "
        "2: get facts only by calling the task tool with the researcher subagent. "
        "3: save the result with write_file. 4: call write_todos again to mark the steps completed."
    ),
    middleware=[TodoListMiddleware()],
    subagents=subagents,
)
ExampleAPI keyRun on Groq
task = "Find out when the Eiffel Tower was built and for which event, then save a one-line note to /note.md."
result = agent.invoke({"messages": [{"role": "user", "content": task}]})

for message in result["messages"]:
    calls = [call["name"] for call in message.tool_calls] if message.type == "ai" else []
    if calls:
        print("calls:", calls)

print("files:", list(result["files"]))
print(result["files"].get("/note.md", {}).get("content"))
print("todos:", result.get("todos"))
  • The calls. They follow the prompt: write_todos to plan, task to give the lookup to the researcher subagent, write_file to save the note, and write_todos again to mark the step completed. Only the tool names are printed. A looser prompt leaves these choices to the model, which may skip the plan and the subagent and answer from memory.
  • The file. result["files"] holds /note.md with the one-line note the agent wrote from what the subagent returned. The file lives in the agent's state, not on disk.
  • The plan. result.get("todos") holds the to-do list as it ended, here one item with the status completed. It is None when the agent never called write_todos.
  • One subagent at a time. Subagents can run in parallel when the model asks for several task calls in one reply. On Groq, gpt-oss asks for one tool call per reply, so they run one after another.

create_agent vs create_deep_agent

create_agentcreate_deep_agent
Built-in toolsOnly the tools you passFile tools and the task tool for subagents, plus the tools you pass
PlanningNone unless you add middlewareAdd TodoListMiddleware
DelegationYou write it, for example agents as toolsSubagents through the subagents list
Context growthEvery result stays in the message listLarge results move to files, subagents keep their own lists
FitsA few tool callsLong tasks with research and written results

Where you use deep agents

  • Deep research. A plan of questions, a researcher subagent per question, and a written report saved to a file.
  • Coding and analysis assistants. Read files, edit them, run checks, and keep notes between steps.
  • Long writing tasks. A plan, a drafting subagent and a reviewing subagent, with the draft kept in a file.
Watch out. A deep agent makes many model calls, and the file and subagent tools add long descriptions to every one of them. On a free key the run can take minutes and may hit rate limits. Start with a small task, and read the message list to see which tools the agent used: nothing forces it to plan or to delegate. The smaller gpt-oss-20b model also sometimes writes a tool call that is not valid JSON, and Groq then answers with a 400 tool_use_failed error. Run the cell again, or switch the model line to groq:openai/gpt-oss-120b.
Try it yourself
  • Remove middleware=[TodoListMiddleware()] and run the task again. Check that write_todos is gone from the calls and todos is missing from the result.
  • Ask for a second note at /second.md and print list(result["files"]).
  • Change the researcher's system prompt to answer in one sentence and read how the saved note changes.

This is what real progress feels like.