Deep Agents Demystified: The Architecture of Complex AI
A practical deep dive into planning, subagents, context engineering, memory, tools, and autonomous execution.
Introduction
Ask a typical AI chatbot a quick question, like "What's the capital of Portugal?" or "Summarise this email", and it does a fine job. Now ask it for something bigger: "Go through last month's 12,000 customer complaints, work out why they suddenly jumped, check whether our delivery data backs that up, see what people are saying on social media, and tell me what we should do about it."
Most AI assistants struggle with this. They forget what they were doing halfway through, drown in information, or hand back a shallow answer that sounds confident but skips half the work.
Deep agents are the industry's answer to this problem. They power some of the most capable AI products in use today: coding assistants like Claude Code, the "Deep Research" features offered by the major AI labs, and general-purpose assistants like Manus. In this post we'll cover what a deep agent is, why the design works, where it fits and where it doesn't, and then walk through a complete real-world example. You don't need a computer science degree to follow along.
Part 1: The building blocks
What is an "AI Agent"?
Before we get to deep agents, we need the plain version.
A large language model (LLM) is the "brain" behind tools like ChatGPT, Claude and Gemini. On its own, an LLM can only read text and write text. It can't look anything up, open a spreadsheet or send an email.
An AI agent is an LLM that has been given tools and permission to use them. A tool can be almost anything a computer can do:
Search the web
Read or write a file
Query a company database
Run a calculation or a small program
Send a message or create a calendar invite
The agent works in a simple loop:
Think: "Given what I know so far, what should I do next?"
Act: use one of its tools.
Observe: read the result.
Repeat until it decides the job is done.
This loop is surprisingly powerful. Ask an agent "What's the cheapest flight from Delhi to Mumbai tomorrow?" and it can search a flights site, compare a few options and answer, all without a human clicking anything.
The problem with "shallow" agents
LangChain, the company that popularised the term "deep agents", calls this basic loop a shallow agent. The AI inside it isn't unintelligent. The problem is that it has no support system for long, messy jobs. Three things tend to go wrong.
No plan. The agent reacts one step at a time without a big picture. On a 30-step task it wanders off course, repeats itself, or declares victory too early.
Memory overload. Every web page, spreadsheet and document it reads gets stuffed into its short-term memory, called the context window. That memory is large but not infinite, and as it fills with clutter the AI starts missing important details. Practitioners call this "context rot".
One person doing everything. A single agent has to be researcher, data analyst and writer at once, with no way to hand pieces of work to someone else.
Picture a brilliant new hire handed a week-long investigation with no notebook, no to-do list and no colleagues. They're sharp, but by Wednesday they've forgotten what Monday's interviews said, and the final report shows it.
Part 2: So what exactly is a Deep Agent?
A deep agent is an AI agent built to plan and carry out complex, multi-step tasks over a long stretch of time: minutes to hours rather than seconds, dozens of steps rather than a handful.
The most important thing to understand is this: a deep agent runs the same basic loop as a shallow one. The difference isn't a smarter brain. It's the environment built around that brain.
When engineers studied what made products like Claude Code and Deep Research so effective, they found the same four ingredients again and again. LangChain wrote these up in 2025 and released an open-source toolkit, deepagents, so anyone could build agents on the same pattern.
Pillar 1: Detailed instructions (the employee handbook)
Every agent starts with a system prompt, a set of standing instructions it reads before doing anything. For a shallow agent this might be one line: "You are a helpful assistant."
A deep agent gets something closer to a full onboarding manual, often thousands of words long, covering:
How to approach work: break big problems into smaller ones, plan before acting, check your work.
How to use each tool: when to search, when to write a file, when to hand off to a helper.
What good output looks like: format, tone, level of detail, how to cite sources.
Worked examples of doing the job well.
This sounds mundane, but it is one of the biggest drivers of quality. Clear expectations produce consistent work, for AI just as for people. A skilled consultant with a clear brief does better work than one who has to guess what the client wants.
Pillar 2: A planning tool (the living to-do list)
Before diving in, a deep agent writes itself a to-do list. As it works it ticks items off, adds new ones when it discovers something, and rewrites the plan when the original approach isn't working.
The surprising part is that, technically, this tool often does nothing. It doesn't connect to any outside system or fetch any data. It just gives the AI a place to write its plan down. Yet LangChain found that planning, "even if done via a no-op tool call", is a big part of why deep agents succeed.
Why would writing a list help? For the same reason pilots and surgeons use checklists.
Writing the plan down:
Keeps the goal visible, so the agent doesn't lose the thread after its 20th tool call.
Forces it to think ahead, which catches missing steps before they cause problems.
Makes progress trackable, both for the agent and for any human watching.
Pillar 3: Sub-agents (the specialist team)
When a task is big, the main agent acts like a project manager. Instead of doing everything itself, it creates sub-agents: temporary helpers, each given one focused job such as "analyse these 12,000 support tickets" or "check the delivery database for late orders."
The real benefit lies in what each sub-agent doesn't carry. Every sub-agent:
Starts with a fresh, empty memory, holding only its own instructions and assignment.
Does the messy work: reading dozens of documents, running queries, trying and discarding ideas.
Returns one short final report to the manager.
The manager never sees the mess, only the conclusions.
Think of how a newspaper editor works. The editor doesn't sit in on every interview. Reporters go out, gather hundreds of pages of notes, and file a tight 800-word story. The editor's desk stays clear enough to see the whole front page.
This brings three benefits:
Cleaner thinking: the main agent's memory stays uncluttered, so it reasons better about the big picture.
Specialisation: each helper can have its own instructions, its own tools, and even a different AI model (a cheaper, faster one for simple jobs, say).
Speed: several sub-agents can work at the same time instead of one after another.
Pillar 4: A file system (the shared notebook)
Finally, deep agents get a place to save notes and files, like a shared drive. Instead of holding a 50-page data dump in its head, the agent writes it to a file such as ticket_themes.md and reads back only the parts it needs, when it needs them.
The file system does several jobs at once:
Long-term memory that doesn't overflow. Files can hold far more than the context window.
A meeting point for the team. Sub-agents write their findings; the manager reads them. Nobody has to repeat work.
Resilience. If a long task is interrupted, the agent can open its notes and pick up where it left off.
A trail for humans. You can open the files afterwards and see exactly what the agent found and how it reached its conclusions.
Manus leans heavily on its file system as "memory" during long tasks, and coding agents like Claude Code read and write real project files as a core part of how they work.
Part 3: How the pieces work together
Individually, each pillar is simple. Together, they turn a chatbot into something closer to a dependable colleague.
Challenge | Shallow agent | Deep agent |
Long, multi-step task | Loses the thread | Follows and updates a written plan |
Huge amounts of information | Memory overflows | Offloads to files, reads selectively |
Many different sub-tasks | Does it all alone | Delegates to specialists |
Consistency | Varies from run to run | Guided by detailed instructions |
Risky actions | Acts immediately | Can pause for human approval |
Auditing the work | Hard to see why it decided | Plan and notes are saved as files |
The extras that make deep agents production-ready
Modern deep-agent toolkits add several features on top of the four pillars. These matter most once you move from a demo to real business use.
Human-in-the-loop approvals. You can mark certain actions, such as sending emails, issuing refunds or deleting data, as "ask first". The agent pauses, shows a human what it wants to do, and waits for a yes or no.
Permissions. Rules that control what the agent may touch, for example "you may read the finance folder but never write to it."
Automatic summarisation. When the agent's memory gets close to full, older conversation is condensed into a summary so the agent can keep going.
Persistent memory. A standing file (often called AGENTS.md) that carries preferences and lessons from one session to the next, so you don't have to re-explain your company's conventions every time.
Skills. Reusable packages of instructions for specialised jobs, such as "how we format board reports", that the agent loads only when it needs them.
Sandboxes. A safe, walled-off computer where the agent can run code without any risk to your real systems.
A useful way to think about it: context engineering
AI practitioners increasingly use the phrase context engineering for the discipline behind deep agents. The idea is simple: the quality of an AI's work depends heavily on what's in front of it when it makes each decision.
Each pillar is really a context-engineering technique:
Instructions put the right guidance in front of the AI.
Planning keeps the goal in front of it.
Sub-agents keep irrelevant detail away from it.
Files let it fetch exactly the information it needs, at the moment it needs it.
A deep agent, in other words, is an agent whose "desk" is organised deliberately.
Part 4: A worked example: investigating a spike in customer complaints
Let's make this concrete with a scenario from e-commerce that almost any business will recognise.
The situation: "ShopKart" (a fictional online retailer) sees customer complaints jump 40% in a single month. Leadership wants to know why, and what to do, by Monday. The request to the deep agent: "Investigate why customer complaints rose last month. Use our support tickets, order and delivery data, and public social media posts. Find the root cause, estimate how many customers were affected, recommend fixes, and draft an apology email for affected customers."
A human analyst might spend three or four days on this: exporting tickets, reading samples, pulling database reports, scrolling social media and stitching it all into a slide deck. Here's how a deep agent handles it.
Step 1: Plan
The agent first writes its to-do list:
Group last month's support tickets into themes and count each one
Check order and delivery data for anything unusual
Scan social media for complaints and trending topics
Connect the findings and identify the root cause
Estimate the number of affected customers
Write a report with recommended fixes
Draft an apology email and get approval before sending
Step 2: Delegate to specialists
The manager agent creates three sub-agents that work in parallel, each with its own tools:
Ticket analyst (tool: the support-ticket system). It reads 12,000 tickets and groups them into themes. Finding: 62% of the extra complaints are about orders marked "delivered" that never arrived.
Logistics analyst (tool: the orders and delivery database). It looks for patterns in late or failed deliveries. Finding: failed deliveries tripled in Pune, Jaipur and Lucknow, all starting the week the company switched to a new courier partner in those cities.
Social listener (tool: a social media search). It scans public posts and review sites. Finding: a cluster of angry posts about "fake delivered" notifications, several with photos of empty doorsteps, mostly from the same three cities.
Step 3: Take notes in the shared notebook
Each specialist saves its detailed findings to the file system:
ticket_themes.md: themes, counts and example tickets
late_deliveries.csv: every affected order, with city, courier and dates
social_signals.md: key posts, volumes and sentiment over time
Each sends the manager only a short summary. The manager's memory stays clean; the evidence stays on file.
Step 4: Connect the dots
Now the main agent does the part that needs judgment. Reading across the three summaries, and opening the files to check specifics, it notices something none of the specialists could have spotted alone. All three signals point to the same cause. The new courier partner is marking parcels "delivered" when they're actually left at a local hub, and ShopKart's notification wording ("Your order has been delivered!") makes customers think their parcel was stolen.
It updates its plan, adding "check whether the courier's hub-drop policy is in the contract", and asks the Logistics analyst a follow-up question. It then writes report.md containing:
Root cause: courier hub-drops being reported as doorstep deliveries in three cities
Impact: about 8,000 customers affected, with a rise in refund requests
Recommended fixes: raise the issue with the courier under the contract's service terms; change notification wording to "Arrived at your local pickup point" where relevant; proactively credit affected customers
A draft apology email for the affected customers
Step 5: Human approval
Emailing 8,000 customers is a sensitive action, so the agent is configured to stop and ask before sending anything. The customer-experience head reviews the report, tweaks the email's tone and approves it. The human stays in control; the agent did days of legwork in under an hour.
Why a shallow agent would have struggled
It's worth spelling out what would likely have happened without the deep-agent design:
Reading 12,000 tickets would have flooded its memory long before it reached the delivery data.
Without a plan, it might have stopped after the first finding ("customers are unhappy about deliveries") without ever finding the courier link.
With no notes on file, there would be no evidence trail for leadership to check.
The crucial insight came from combining three separate investigations, which is exactly what a manager with clean, summarised inputs is good at.
What this looks like for a developer
For the technically curious, here's roughly how this could be set up with LangChain's open-source deepagents library in Python. The planning tool, file system and sub-agent tool come built in; you mainly describe the team and hand them the right tools.
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
# --- Your own business tools (simplified placeholders) ---
def search_support_tickets(month: str, query: str = "") -> str:
"""Fetch support tickets for a given month."""
...
def query_delivery_data(sql: str) -> str:
"""Run a read-only query on the orders & delivery database."""
...
def search_social_media(query: str, days: int = 30) -> str:
"""Search public posts and review sites."""
...
def send_customer_email(segment: str, subject: str, body: str) -> str:
"""Email a segment of customers."""
...
# --- The specialist team ---
subagents = [
{
"name": "ticket-analyst",
"description": "Groups support tickets into themes and counts them.",
"system_prompt": "Cluster tickets into clear themes with counts and "
"examples. Save details to ticket_themes.md and "
"return a short summary.",
"tools": [search_support_tickets],
},
{
"name": "logistics-analyst",
"description": "Finds patterns in late or failed deliveries.",
"system_prompt": "Look for spikes by city, courier and date. Save "
"affected orders to late_deliveries.csv.",
"tools": [query_delivery_data],
},
{
"name": "social-listener",
"description": "Monitors public posts and reviews about the brand.",
"system_prompt": "Identify trending complaints and where they come "
"from. Save findings to social_signals.md.",
"tools": [search_social_media],
},
]
# --- The manager agent ---
agent = create_deep_agent(
model="anthropic:claude-sonnet-5",
tools=[send_customer_email],
subagents=subagents,
system_prompt=(
"You are a customer-experience investigator. Always start with a "
"to-do list. Delegate data-heavy work to sub-agents, keep raw data "
"in files, look for a root cause that explains ALL the evidence, "
"and write your findings to report.md."
),
interrupt_on={"send_customer_email": True}, # pause for human approval
checkpointer=MemorySaver(), # needed so it can pause and resume
)
result = agent.invoke(
{"messages": [{"role": "user",
"content": "Investigate why complaints rose last month."}]},
config={"configurable": {"thread_id": "complaints-investigation"}},
)Notice what's not in this code: you don't build a planner, a memory system or a delegation engine. That is the point of a deep-agent harness: the four pillars come ready-made, and you focus on your business tools and instructions.
Part 5: When should you use a deep agent, and when not?
Deep agents get a lot of attention, but they are one option among several. Picking the wrong one is one of the most common and most expensive mistakes teams make. Build a deep agent for a simple job and you pay for speed and money you didn't need to spend. Use a simple chatbot for a complex investigation and you get a confident, shallow answer.
Anthropic's widely cited guide Building Effective Agents makes a useful distinction here:
Workflows are systems where the AI and its tools follow predefined steps written by a person.
Agents are systems where the AI decides for itself which steps to take and which tools to use.
Its main advice is to start with the simplest thing that works and add complexity only when simpler approaches fall short. With that in mind, here are the five main types you'll come across, from simplest to most capable.
1. The chatbot (a plain LLM)
What it is: An AI model answering from what it already knows, plus whatever you paste in. No tools, no actions.
Use it when:
You're drafting, rewriting, translating or summarising text you already have
You're brainstorming or asking a general-knowledge question
The answer doesn't depend on live or private company data
Example: "Turn these meeting notes into a polite follow-up email."
Skip it when the job needs current information, company data, or any action in another system.
2. The workflow (a fixed pipeline)
What it is: A sequence of steps designed by a person, with AI doing some of those steps.
The AI doesn't choose the path; the path is decided in advance. Common variations include:
Chaining: step A's output feeds step B (extract details from an invoice, then check them against the purchase order).
Routing: the AI sorts incoming items into categories, and each category follows its own fixed path (billing questions go one way, delivery questions another).
Parallel checks: several AI calls look at the same item at once, for example one checking tone and another checking facts.
Use it when:
The task is the same every time and you can write the steps down
You need predictable results, easy testing and tight cost control
You're running at high volume, such as thousands of documents a day
Example: Every night, read new supplier invoices, pull out amount, date and vendor, and flag any that don't match a purchase order.
Skip it when you can't predict the steps, because each case needs a different investigation.
3. The tool-calling agent (the "shallow" agent)
What it is: The think–act–observe loop from Part 1. The AI chooses which tools to use and in what order, but the job is short.
Use it when:
The path varies from case to case, but only a few steps are needed (roughly under ten)
It needs a handful of tools
Answers are needed quickly, in seconds rather than minutes
Example: A support assistant that looks up a customer's order, checks its delivery status and answers "Where is my parcel?"
Skip it when the task runs long, involves lots of reading, or needs separate lines of investigation. That's where it starts losing the thread.
4. The multi-agent system (a team of independent agents)
What it is: Several agents, each with a lasting role, working together as peers or under a coordinator. Unlike a deep agent's temporary sub-agents, these agents are often built and owned separately, perhaps by different teams, and can keep running on their own.
Use it when:
Different departments or systems each own their own agent (a finance agent, an HR agent, an IT agent) and they need to work together
Roles are long-lived and independent, such as one agent that writes and another that reviews, around the clock
You need agents built by different vendors or on different platforms to cooperate
Example: An employee-onboarding process where the HR agent sets up payroll, hands off to the IT agent to create accounts, and the Facilities agent books a desk, each managed by its own team.
Skip it when one team owns the whole task. A single deep agent with sub-agents is usually simpler to build, run and debug.
5. The deep agent
What it is: Everything described in this post: one agent in charge, with a plan, a file system, temporary specialist sub-agents and detailed instructions.
Use it when:
The task is long and open-ended: dozens of steps, minutes to hours
It involves a lot of information, such as many documents, large datasets or many web pages
It splits naturally into separate lines of investigation that must be brought together
You want a written trail (plan, notes, report) that people can review
Example: The ShopKart complaints investigation from Part 4.
Skip it when a simpler type does the job. More on that below.
Side by side
Chatbot | Workflow | Tool-calling agent | Multi-agent system | Deep agent | |
Who decides the steps? | Nobody (one answer) | A person, in advance | The AI | Several AIs | The AI, with a written plan |
Typical length | Seconds | Seconds to minutes | Seconds to minutes | Varies, often ongoing | Minutes to hours |
Uses tools / live data | No | Yes | Yes | Yes | Yes |
Predictability | High | Very high | Medium | Lower | Medium |
Cost per task | Lowest | Low | Low to medium | High | Medium to high |
Best for | Writing and Q&A | Repeatable processes | Quick, varied lookups | Cross-team collaboration | Deep research and investigation |
A simple decision guide
If you're unsure, work through these questions in order and stop at the first match:
Does it need to look things up or take actions? If not, use a chatbot.
Are the steps known in advance and the same every time? If so, build a workflow.
Can it be done in a few steps with a handful of tools? If so, use a tool-calling agent.
Do separate teams or long-lived roles each need their own agent? If so, consider a multi-agent system.
Otherwise, and especially if the job is long, information-heavy and open-ended, use a deep agent.
Another way to picture it is to plot the job by how many steps it takes and how unpredictable the path is.
Mixing types is normal
Real systems often combine these. A few common patterns:
A workflow that calls a deep agent. A nightly pipeline collects the day's complaints, and only if they spike does it start a deep agent to investigate.
A router in front of several agents. Simple questions go to a quick tool-calling agent; complex cases go to a deep agent.
A deep agent whose sub-agent is itself a workflow. The "ticket analyst" might run a fixed, well-tested categorisation pipeline instead of improvising.
The guiding principle stays the same: use the simplest type that reliably gets the job done, and step up only when you hit its limits.
Part 6: Deep agents in particular: good fits, limits and myths
Once you've decided the job really does call for a deep agent, here's what to expect.
Good fits for a deep agent:
Research and analysis across many sources: market research, competitor analysis, due diligence, literature reviews.
Investigations: "why did X happen?" questions where you don't know in advance where the answer lies.
Software engineering: changes that touch many files, bug hunts, writing and running tests.
Report and document creation that needs gathering, reasoning and writing.
Any job a person would break into sub-tasks and track on a checklist.
Probably overkill:
Simple questions or one-step lookups. A regular chatbot is faster and cheaper.
Fixed, repeatable processes ("every night, copy sales figures into the dashboard"). A traditional automated workflow is more reliable and predictable.
Real-time responses. Deep agents trade speed for thoroughness; a customer waiting on a live chat won't want to wait ten minutes.
Honest limitations and risks
It's worth going in with clear eyes:
Cost. A single deep-agent run may make dozens or hundreds of AI calls. That's usually cheap compared with days of human effort, but it adds up at scale.
Time. A thorough run can take minutes or more.
Mistakes can compound. If a sub-agent misreads data early on, the manager may build on that error. Good instructions ("double-check surprising numbers") and human review help.
Security and access. An agent that can read your databases and send emails needs the same care you'd give a new employee: least-privilege access, approvals for sensitive actions, and logs of what it did.
It still needs a good brief. A vague request gets a vague result. Deep agents amplify good direction; they don't replace it.
Common myths
"Deep agents are a new kind of AI model." They're not. They're a design pattern, a way of organising how an existing model works.
"More sub-agents is always better." No. Each one adds cost and coordination overhead. Use them where work is genuinely separable or data-heavy.
"Deep agents replace people." In practice they replace the tedious gathering and first-draft work, and people keep the judgment calls, as the approval step in our example shows.
Part 7: Getting started
If you're considering deep agents for your team, here's a practical path:
Pick one painful, multi-step task that people currently do by hand, ideally one involving lots of reading and summarising.
Write the handbook. Describe how your best person does the task today, step by step. That becomes the agent's system prompt.
List the tools it needs: which systems it must read from and which actions it may take.
Decide what needs approval. Anything touching customers, money or production systems should pause for a human.
Start small and review the files. The saved plans and notes let you see exactly where the agent did well and where its instructions need tightening.
Iterate. Most improvement comes from refining instructions and tools, not from switching AI models.
The big takeaway
The most important idea behind deep agents is this: the leap in capability didn't come from a smarter AI brain alone. It came from giving that brain a better way to work. A plan to follow, a notebook to write in, a team to delegate to, and a clear handbook to guide it.
That's exactly what we give talented people when we want them to take on big projects. It turns out AI benefits from the same things.
As organisations move from "AI that answers questions" to "AI that completes projects", deep agents are quickly becoming the blueprint. Understanding these four pillars is one of the best ways to see where AI at work is heading next.
Comments