Skip to main content

LangGraph Deep Agents: What They Are and When to Use Them

· 8 min read
Vadim Nicolai
Vadim Nicolai
Senior Software Engineer

LangGraph Deep Agents is what you reach for when an agent has to keep working for a long time on a task nobody can fully script in advance. A model calling tools in a loop is easy to build. Keeping that loop on track at step 200 is harder: the plan drifts, the context window fills with tool output, and the work you could hand off sits in the same thread as everything else. Deep Agents takes the same tool loop and adds defaults aimed at those failures. In LangChain's own terms that makes it a harness, not a framework and not a runtime. This post explains what that difference means, how create_deep_agent compares with create_agent and a custom StateGraph, and what the harness gives you.

LangGraph Deep Agents, a 10-part series. Part 2 →

The thesis is simple. A harness is the tool loop plus the defaults that make long tasks reliable. Pick it over a raw StateGraph when the task is open-ended.

Series: 01 Harness (this post) · 02 Quickstart · 03 MCP tools · 04 Virtual filesystem · 05 Sandbox and permissions · 06 Skills and memory · 07 Context engineering · 08 Subagents · 09 Human-in-the-loop · 10 Production

What is LangGraph Deep Agents?​

The Deep Agents overview describes it as the agent harness for complex, multi-step work. It is built on LangChain and LangGraph and adds four things on top of them: planning, a virtual filesystem for context, subagent spawning, and long-term memory.

It ships as a standalone library, deepagents. You don't fork a template or copy a graph into your repo. You call one function and get back a compiled agent that runs on the LangGraph runtime, so checkpointing, streaming and interrupts work the same way they do for any other LangGraph graph.

Framework vs runtime vs harness: what is the difference?​

LangChain's frameworks, runtimes, and harnesses page splits its stack into three layers, and the split decides which one you should build on:

  • Framework (LangChain). Abstractions that get you started quickly: structured content blocks, the agent loop, middleware. It is built on LangGraph, but you don't need to know LangGraph to use it (products overview).
  • Runtime (LangGraph). What you need to run agents in production: durable execution, streaming, human-in-the-loop, persistence and low-level control. The docs call it "a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents."
  • Harness (Deep Agents). "Opinionated, batteries-included frameworks with built-in tools and capabilities". In practice that means planning, a filesystem, subagents and token management, all layered on LangGraph.

One way to remember it: the framework gives you the loop, the runtime keeps the loop alive, and the harness decides what the loop should have by default. Each layer sits on the one below it. A deep agent is still a LangGraph graph, and it still uses LangChain's model and tool abstractions.

create_agent vs create_deep_agent vs a custom StateGraph​

These are the three entry points you will actually choose between.

create_agent (LangChain) gives you the plain tool-calling loop: a model, some tools, middleware if you want it. The agents docs show the minimal form:

from langchain.agents import create_agent

agent = create_agent(model="anthropic:claude-sonnet-5", tools=tools)

Use it when the task is short and well-bounded: answer a question, call two APIs, return. Nothing extra goes into the context, and you can see everything the model sees.

create_deep_agent (Deep Agents) has the same calling shape, but the agent it returns already has a filesystem, delegation and context management built in. This is the quickstart from the overview:

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Your code barely changes (the system_prompt argument works the same way). What changes is what the agent can do once the task stops being a single weather lookup.

A custom StateGraph (LangGraph) is the escape hatch. You write the nodes and edges yourself. The products page recommends LangGraph when you need fine-grained control over orchestration, or a mix of deterministic and agentic steps. If you already know the order the work happens in (validate, enrich, score, write), a graph says that more clearly than any prompt, and a model can't skip a step.

The overview points the same way: for agents that don't need the built-in capabilities, use create_agent or a custom LangGraph workflow.

When should you use LangGraph Deep Agents over a custom graph?​

Use the harness when the task is open-ended: research across many sources, a coding change that touches an unknown number of files, an analysis where the next step depends on what the last one found. The products page recommends Deep Agents for agents that "run over long time periods" or "need to handle complex, multi-step tasks", and for when you want predefined tools, prompts and subagents.

Some signals that you need a harness:

  • The run outgrows its context window. Tool results pile up until the model forgets the goal. The harness offloads and summarizes them for you.
  • The work splits into independent pieces. Subagents run each piece in its own context and send back only the conclusion.
  • The agent needs scratch space. Notes, drafts and intermediate files go in a filesystem instead of the message history.

And some signals that you don't:

  • The control flow is fixed. Write it as a StateGraph.
  • The task finishes in a few tool calls. create_agent is smaller and easier to reason about.
  • Every step is audited. A deterministic graph is easier to defend than a planner.

Harness defaults aren't free. Each built-in tool is a description the model reads on every turn. Part 03 covers trimming that surface, and you should trim it rather than accept every default.

What capabilities does the Deep Agents harness include?​

The overview groups the harness into four areas. Each one gets a later part of this series.

All four come back to one problem: keeping the model's working context small and pointed at the goal over a long run. The filesystem moves bulk out of the message history. Subagents keep heavy work in a separate context. Skills load knowledge only when it's needed. Summarization compresses what is left. Planning gives the model a written goal it can check against. Interrupts let a person stop the run before an irreversible step.

Where Deep Agents runs​

A deep agent is a LangGraph graph, so you can deploy it the way you would deploy any other graph. You can also use Managed Deep Agents in LangSmith, which hosts it for you. LangChain also publishes a comparison with the Claude Agent SDK. Part 10 covers the managed-vs-SDK decision.

FAQ​

Is Deep Agents a replacement for LangGraph? No. Deep Agents is a harness that runs on LangGraph. It uses the LangGraph runtime for durable execution, streaming and human-in-the-loop, and it adds opinionated defaults on top.

What is the difference between create_agent and create_deep_agent? create_agent is LangChain's plain tool-calling loop. create_deep_agent takes the same kinds of arguments (model, tools, system prompt) and returns an agent that also has planning, a virtual filesystem, subagents and context management.

When should I build a custom StateGraph instead of using LangGraph Deep Agents? Build a custom graph when you already know the control flow, need deterministic steps, or need fine-grained control over orchestration. Use the harness when the task is open-ended and long-running.

Next: LangGraph Deep Agents Quickstart: create_deep_agent.