Deep agents and deep research agents

Meera had an idea she could not stop thinking about. Millets were everywhere: on government posters, in office canteens, in her own kitchen. For Makar Sankranti in January she wanted to launch a millet range: ragi cookies, jowar crackers, bajra-jaggery ladoos.

“Before I spend money on this,” she told Arjun on Monday, “I want a proper brief. Who in Pune already sells millet bakery products, at what prices, what customers say about them, and roughly what millet flour costs wholesale. Five pages. With sources, so I can check. By Friday?”

Arjun said yes immediately. He had an agent from Module 13 that could search the web. How hard could it be?

Arjun’s first attempt: one agent, one long loop

He pointed his ReAct-style agent (the think, act, observe loop from Module 13) at Meera’s request, gave it a web search tool and a 50-step limit, and went for lunch.

When he came back, it had finished. The log told the story:

• Steps 1 to 10 were good. It searched for millet bakeries in Pune, found four, and read their pages.
• Steps 11 to 25 started to wobble. Each search result, often 2,000 to 4,000 tokens of web page, was appended to the conversation. By step 20 the context held about 90,000 tokens. The agent searched “ragi cookies price Pune” three times with slightly different wording, apparently not noticing it already had the answer.
• Steps 26 to 34 drifted. It spent nine steps on a tangent about millet health benefits that nobody had asked for.
• Step 34, with about 180,000 tokens in context, it wrote the final answer: 400 words, two sources, no supplier costs at all. One “source” was a URL that did not exist.

It had taken 11 minutes. And because every step re-sends the whole growing conversation, the agent had read roughly 3 million input tokens in total. At the $3permillionwehavebeenassuming(checkcurrentpricing),thatisabout$9, or roughly ₹800, for a brief Meera could not use.

“It forgot half your question,” Arjun admitted.

“It didn’t forget,” said Priya. “It buried it. Your original request is at the very top of a 180,000-token pile. Remember Lesson 1? Having something in the context window is not the same as the model paying attention to it.”

Priya’s analogy: the investigations desk

Priya drew a newsroom on the whiteboard.

“A newspaper wants a big investigative story. Do they give it to one reporter and say ‘go, come back when it’s done’?”

“No. There’s an editor.”

“What does the editor do first?”

Arjun thought. “Makes a plan. What are the questions, who covers what.”

“Writes it on the whiteboard, so everyone can see it and tick things off. Then?”

“Sends reporters out. One on competitors, one on prices, one on suppliers.”

“Does each reporter need to know everything the others found?”

“No. Just their assignment. And they come back with notes.”

“Where do the notes go? Into the editor’s head?”

“Into a shared folder. The editor reads the folder when it’s time to write.”

“And before it prints?”

“A fact-checker checks every claim against a source.”

Priya underlined four things: the whiteboard plan, reporters with focused assignments, the shared folder, and the editor’s standing instructions (the house style, the rules). “That’s a deep agent. Your agent was a single reporter with no plan, no folder, writing everything on the back of their hand.”

The four ingredients of a deep agent

The phrase deep agent became popular in 2025 for agents like Claude Code and the “deep research” features in ChatGPT, Gemini and Claude, which can work for many minutes on one task. When people looked at what made them work, the same four ingredients kept appearing.

1. An explicit plan. Before acting, the agent writes a to-do list, and it updates the list as it goes: done, in progress, next. This sounds trivial, and in a way it is: the plan does not make the model smarter. It makes the goal visible. Each time the agent rereads the plan, the original question is back at the front of its attention instead of buried at token 3,000 of 180,000.

2. Subagents. A subagent is a separate agent run, started by the main agent with a focused task and a fresh, empty context. It does its work, then returns a short result. The main agent (often called the lead or orchestrator) never sees the subagent’s messy intermediate steps. You met subagents in Module 13’s multi-agent lessons; here their job is specifically to protect the lead’s context.

3. A file system as a scratchpad. A scratchpad is somewhere the agent can write notes for later. In a deep agent it is usually a folder of files: plan.md, notes/competitors.md, draft.md. Files live outside the context window, so they cost nothing until read. They survive crashes. Subagents can share them. And a human can open them and see exactly what the agent knows.

4. Detailed instructions. Deep agents run on long, specific system prompts: how to plan, when to delegate, how to cite sources, when to stop. Claude Code’s system prompt is famously long. Short prompts give short-horizon behaviour.

Put together, this is what makes long-horizon tasks (tasks that take many steps and a long time, where early decisions affect late ones) possible.

Following Meera’s brief through a deep agent

Arjun rebuilt the agent with those four ingredients and ran it again. Here is the whole run, traced.

Stage 1: clarify. Instead of diving in, the lead asked Meera three questions through Arjun: Which millets matter most? (Ragi, jowar and bajra.) Bakeries only, or also packaged brands sold in Pune? (Both.) Wholesale prices per kg, or per quintal? (Per kg, she thinks in kg.) Two minutes of questions saved an hour of wrong research.

Stage 2: plan. The lead wrote plan.md:

# Millet brief for Sankranti launch
- [ ] 1. Pune competitors: bakeries and packaged brands selling ragi/jowar/bajra bakery items
- [ ] 2. Retail prices for comparable products (per 100 g)
- [ ] 3. What customers say: reviews, common praise and complaints
- [ ] 4. Wholesale millet flour prices per kg, Pune region
- [ ] 5. Synthesise into a 5-page brief with sources
- [ ] 6. Verify every claim against its source

Stage 3: delegate. The lead sent tasks 1 to 4 to four subagents, each with a precise brief. Here is the one for task 2:

“Find retail prices for millet-based cookies, crackers and ladoos sold in Pune, from at least five sellers. Normalise every price to rupees per 100 g. Record the source URL and the date for each price. Write your findings to notes/prices.md as a table. Reply with a 100-word summary and nothing else.”

That brief has four parts every good delegation needs: the goal, the output format, where to put it, and what to send back. Vague briefs (“research prices”) produce overlapping, inconsistent work.

Stage 4: one subagent at work. The prices subagent ran 9 searches, read 7 pages, and wrote a 600-word table to notes/prices.md. Its context peaked around 30,000 tokens, all of it relevant to prices. It replied to the lead with 100 words: “Found 11 products from 6 sellers. Ragi cookies range ₹55 to ₹90 per 100 g, median ₹68…” The lead never saw the 7 web pages.

Stage 5: synthesise. When all four subagents had reported, the lead ticked off tasks 1 to 4 in plan.md, read the four notes files (about 3,500 words, or 4,700 tokens), and wrote draft.md.

Stage 6: verify. A final subagent got one job: for every factual claim in the draft, find the supporting line in the notes files and its source URL; list any claim without one. It flagged two: a market-growth percentage the lead had half-remembered from a page that did not actually say it, and a price that came from 2023. The lead removed one and re-dated the other.

Here is how the lead’s context window compared with the first attempt:

Moment	Single-loop agent	Deep agent (lead only)
After 10 steps	about 45,000 tokens	about 6,000 tokens
Peak	about 180,000 tokens	about 24,000 tokens
Total input tokens, all agents	about 3,000,000	about 900,000
Approx. cost at $3 per million input	₹800	₹240
Time	11 min	14 min (subagents ran in parallel)
Usable brief?	No	Yes, 5 pages, 23 sources

The deep agent was cheaper here only because the single loop had bloated so badly. Be careful with that conclusion. Compared with answering a simple question in one call, a deep research run costs tens or hundreds of times more. Anthropic has written that its multi-agent research system uses many times the tokens of a normal chat. Deep agents are worth it for work worth an analyst’s afternoon, not for “what time does the Baner store open?”.

Opening the hood: the shape of a deep agent

flowchart TD
  U["Meera's request"] --> L["Lead agent"]
  L --> P[("plan.md")]
  L --> S1["Subagent: competitors"]
  L --> S2["Subagent: prices"]
  L --> S3["Subagent: reviews"]
  L --> S4["Subagent: suppliers"]
  S1 --> F[("notes/ folder")]
  S2 --> F
  S3 --> F
  S4 --> F
  F --> L
  L --> V["Subagent: verifier"]
  V --> D["Final brief"]

Two ideas from earlier in this module are hiding in that picture.

The file system is long-term memory for a task. Lesson 1 split memory into a desk (the context window) and a filing cabinet (external storage). Deep agents apply exactly that to a single long job. plan.md is procedural memory for this task (what we are doing and how). The notes/ folder is a store of facts the agent has gathered. MemGPT, a 2023 research system, described the same idea as treating the context window like a computer’s RAM and external storage like its disk, paging things in and out as needed.

Delegation is a form of context engineering: deliberately deciding what goes into each model call’s context and what stays out. A lot of an agent’s quality depends less on the model and more on keeping each context small, relevant and well-organised.

You do not have to build all this from scratch. LangChain’s open-source deepagents package bundles a planning tool, a virtual file system and a subagent tool on top of LangGraph. Anthropic’s Claude Agent SDK (which you will meet in Module 18) gives you the agent loop behind Claude Code, including real file tools and subagents. But building a small one yourself, once, makes every one of those frameworks easy to understand.

The real code: a mini deep agent

You will build a lead agent with file tools and a delegate tool that spins up subagents. It uses Claude’s tool runner, which runs the tool-calling loop for you: it calls the model, runs any tools the model asks for, sends back results, and repeats until the model is done. Install with uv add anthropic python-dotenv.

Step 1: a workspace the agent cannot escape

from pathlib import Path

import anthropic
from anthropic import beta_tool
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()
MODEL = "claude-opus-5-5"

WORKSPACE = Path("workspace").resolve()
WORKSPACE.mkdir(exist_ok=True)


def safe_path(relative: str) -> Path:
    """Turn a model-supplied path into a real path, refusing anything outside the workspace."""
    full = (WORKSPACE / relative).resolve()
    if not full.is_relative_to(WORKSPACE):
        raise ValueError(f"{relative} is outside the workspace")
    return full

This matters more than it looks. The model chooses file paths. Without safe_path, a confused or manipulated agent could write to ../../.env or read your SSH keys. When a tool raises an error, the tool runner sends the error message back to the model as a failed tool result, so the agent learns it was refused and can try again.

Step 2: file tools, the scratchpad

@beta_tool
def write_file(path: str, content: str) -> str:
    """Save text to a file in the workspace, replacing it if it exists.

    Args:
        path: Relative path, like "plan.md" or "notes/prices.md".
        content: The full text to write.
    """
    target = safe_path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content)
    return f"Saved {path} ({len(content.split())} words)."


@beta_tool
def read_file(path: str) -> str:
    """Read a file from the workspace.

    Args:
        path: Relative path, like "notes/prices.md".
    """
    return safe_path(path).read_text()


@beta_tool
def list_files() -> str:
    """List every file in the workspace."""
    files = [str(p.relative_to(WORKSPACE)) for p in WORKSPACE.rglob("*") if p.is_file()]
    return "\n".join(sorted(files)) or "(empty)"

The docstrings are not decoration. beta_tool turns them into the tool descriptions and parameter descriptions the model reads, exactly as in Module 06.

Step 3: a search tool for the subagents

@beta_tool
def search_web(query: str) -> str:
    """Search the web and return the top results with titles, URLs and snippets.

    Args:
        query: What to search for.
    """
    # Plug in the search tool you built in Module 13 (Tavily, Brave, SerpAPI...).
    # This stub lets you run the whole agent without a search API key.
    return (
        "1. Ragi Cookies 200 g, Rs 140 - examplemilletco.in/ragi-cookies\n"
        "2. Jowar Crackers 150 g, Rs 120 - puneorganics.example/jowar\n"
        "3. Millet flour wholesale, ragi Rs 48/kg - agrimandi.example/ragi"
    )

Step 4: the delegate tool, where subagents are born

SUBAGENT_RULES = (
    "You are a focused research assistant. Do only the task you are given. "
    "Use search_web, then save your findings with write_file to the file you were told. "
    "Every fact needs a source URL. Finish with a summary of at most 100 words."
)


@beta_tool
def delegate(task: str, output_file: str) -> str:
    """Give one focused research task to a fresh subagent and get back its short summary.

    Args:
        task: A precise brief: the goal, the format and what to include.
        output_file: Where the subagent must save its notes, like "notes/prices.md".
    """
    runner = client.beta.messages.tool_runner(
        model=MODEL,
        max_tokens=4000,
        system=SUBAGENT_RULES,
        tools=[search_web, write_file],     # no delegate: subagents cannot spawn subagents
        messages=[{"role": "user", "content": f"{task}\n\nSave your notes to {output_file}."}],
    )
    final = runner.until_done()             # run the subagent's whole loop
    summary = next(b.text for b in final.content if b.type == "text")
    print(f"  [subagent done] {output_file}")
    return summary

This is the heart of it. Each call to delegate starts a brand-new conversation, with an empty context apart from the brief. When it finishes, only summary (100 words) comes back to the lead. Everything the subagent read is gone, except what it chose to save in its notes file.

Notice the deliberate limit: subagents get search_web and write_file, but not delegate. Without that rule, a subagent can spawn subagents that spawn subagents, and your bill grows like a chain letter.

Step 5: the lead agent

LEAD_RULES = """You are the lead researcher for Crumb & Co., a bakery chain in Pune.
How to work:
1. First write plan.md: a numbered checklist of research tasks, then synthesis, then verification.
2. Delegate each research task with a precise brief and its own notes file.
3. After each task, update plan.md, ticking off what is done.
4. When research is done, read the notes files and write draft.md with sources.
5. Delegate a final check: every claim in draft.md must have a source in notes/.
6. Fix anything flagged, write brief.md, and reply with a two-line summary."""

runner = client.beta.messages.tool_runner(
    model=MODEL,
    max_tokens=8000,
    system=LEAD_RULES,
    tools=[write_file, read_file, list_files, delegate],
    messages=[{"role": "user", "content": (
        "Brief on millet bakery products in Pune for a Sankranti launch: competitors, "
        "retail prices per 100 g, customer opinions, and wholesale ragi/jowar/bajra flour per kg."
    )}],
)

for message in runner:                      # one iteration per model turn
    for block in message.content:
        if block.type == "tool_use":
            print(f"lead -> {block.name}({list(block.input)})")

print(list_files())

When you run it, you should see the lead write plan.md, call delegate four or five times, read notes and write drafts, ending with a file list like:

brief.md
draft.md
notes/competitors.md
notes/prices.md
notes/reviews.md
notes/suppliers.md
plan.md

Open plan.md while it runs and you can watch the boxes being ticked. That visibility is a feature in its own right: a human can see where a long-running agent is and stop it if it has gone wrong.

Library APIs change quickly. If a name has moved, check the docs linked below.

Where it breaks

Delegations run one at a time here. In this simple, synchronous version each delegate call blocks until its subagent finishes, so this version is slower than the 14 minutes in the worked example. Production systems run subagents in parallel, with asyncio or a framework like LangGraph. Start sequential; it is far easier to debug.

The telephone game. Each summary loses detail. If the lead writes the final brief from 100-word summaries, nuance disappears. That is why the lead reads the notes files before synthesising. Summaries are for steering; files are for writing.

Overlapping or contradictory work. Two subagents with vague briefs will research the same thing and disagree on the numbers. Precise briefs, with explicit boundaries (“prices only; do not research suppliers”), fix most of this.

Crashes at minute 40. Long runs fail: a network blip, a rate limit, a bug in a tool. Because the plan and notes are files, you can restart the lead with “Resume: read plan.md and continue from the first unticked item.” For anything that matters, add proper checkpointing, as you did with LangGraph in Module 14, so the run itself can be resumed, not just its notes.

Budgets. Set a maximum number of delegations, a maximum number of tool calls per subagent, and a spending alarm. Some teams also add human checkpoints: the agent shows its plan, and a person approves it before any research starts. Two minutes of review can save a ₹2,000 run in the wrong direction.

Try it yourself

Run the mini deep agent on a smaller question: “Which three Pune neighbourhoods have the most bakeries, and which of them is Crumb missing a store in?” (Use the stub search, or plug in a real one.)

Then, without rerunning, answer these from the files alone:

1. How many tasks were in the plan, and were they all ticked off?
2. Which claim in brief.md has the weakest source?

Show the answer

There is no single correct output, because it depends on your search results. What matters is that you could answer both questions by opening plan.md and the notes/ folder, without reading a single log line or rerunning anything. That is the practical payoff of a file-system scratchpad: the agent’s working memory is visible, inspectable and durable. If you could not answer question 2, your subagent brief did not demand sources clearly enough. Tighten it and rerun.

Common mistakes

• Using a deep agent for a shallow task. If one or two tool calls would do, a plan and subagents only add cost and delay.
• Vague delegation. “Research prices” produces vague research. State the goal, the format, the output file and what to send back.
• Letting subagents delegate. Limit the depth to one level unless you have a strong reason and a budget.
• Writing from summaries. Read the notes before synthesising.
• No sandbox. Every file path the model provides must be checked against the workspace.
• No verification step. Long research produces confident, unsupported claims. Check them against the sources before a human relies on them.

Recap

• Single long agent loops fail on big tasks because the context fills with raw material and the original goal gets buried.
• Deep agents use four ingredients: an explicit plan, subagents with clean contexts, a file-system scratchpad, and detailed instructions.
• Subagents protect the lead’s context: the lead sees 100-word summaries, not 30,000-token web pages.
• Files are task-level long-term memory: cheap until read, crash-proof, shareable and inspectable by humans.
• Deep research costs far more than a chat. Use it for work worth an analyst’s afternoon, with budgets, sandboxes and a verification step.

On Thursday afternoon, a day early, Arjun sent Meera brief.md. Five pages, 23 sources, a price table and a recommendation to price ragi cookies at ₹65 per 100 g.

“How did it do this?” she asked. Arjun explained it the newsroom way. “It’s an editor with a whiteboard. It wrote a plan, sent four reporters out with one question each, made them file notes in a folder, then wrote the story from the folder. Then it sent a fact-checker through the draft. The checker caught two claims that weren’t backed up.”

“And what did it cost?”

“About ₹240 in model calls. Less than the first attempt, which was useless.” Meera nodded slowly, then asked something that made Arjun pause. “Next month, after the Diwali recall, I’ll need to know which customers bought which products containing which ingredients. Can your memory answer that?” He thought about his vector store, full of separate sentences, and realised it could not join them. That is where Module 16 begins: graph memory.

Go deeper

• Building effective agents by Anthropic, on when to use workflows, orchestrators and subagents. Anthropic’s engineering blog also has a write-up on how it built its multi-agent research system.
• LangChain deepagents on GitHub, an open-source deep agent harness built on LangGraph.
• MemGPT: Towards LLMs as Operating Systems, the context-as-RAM, storage-as-disk idea.
• ReAct, the single-loop pattern this lesson builds on.
• Anthropic documentation, for the tool runner and the Claude Agent SDK.