What Is a Deep Agent?

Most AI agents are shallow: they take a request, make a couple of tool calls, and answer — all inside one context window. That breaks down on big tasks: research a topic across 20 sources, refactor a codebase, write a long report. A deep agent is designed for exactly those long, multi-step jobs. It's the pattern behind Claude Code, Deep Research and Manus, and LangChain formalised it in the deepagents library (research preview, Jan 2026).

The four pillars

• Planning — a todo list the agent writes and updates, so the goal and next steps stay in its attention across a long run.
• Virtual filesystem — the agent saves large results and notes to files, keeping the prompt window from overflowing.
• Subagents — it delegates focused subtasks to specialists with their own, isolated context.
• A detailed system prompt — clear, specific instructions are what make it reliable on hard tasks.

When to reach for one

Use a deep agent when the task has many steps (10+), needs long-term planning, produces intermediate artifacts, or spans multiple documents/tools. For a single lookup or a one-shot answer, a plain LLM call or a simple agent is cheaper and simpler.

The simplest possible deep agent

# pip install deepagents
from deepagents import create_deep_agent

def internet_search(query: str) -> str:
    """Search the web for a query."""
    return f"results for {query}"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[internet_search],
    system_prompt="You are a research assistant. Plan first, then act.",
)

result = agent.invoke({"messages": "Research deep agents and summarize them."})
print(result["messages"][-1].content)

The rest of this tutorial takes each pillar in turn and builds up to a complete agent. Want to see the structure first? The Deep Agent Scaffold Generator turns a design into this exact code plus a diagram.