Deep Agents: planning, sub-agents, and a filesystem for long tasks

At the top of the LangChain ladder is the harness layer: you supply intent, and the framework supplies the machinery for long, open-ended tasks. That's what deepagents is — a package (built on LangGraph, inspired by agents like Claude Code and deep-research systems) that turns a plain agent into one that can plan and stay coherent over many steps.

What makes an agent 'deep'

A bare agent loop stalls on long tasks — it loses the plot, floods its context, and repeats itself (the failure modes from the agent-loops post). Deep agents add four things that fix that:

• Planning — a todo/plan tool the agent uses to lay out and track the steps, so it stays on course.
• Sub-agents — it spawns focused agents for sub-tasks, keeping each one's context clean instead of one bloated window (context isolation).
• A virtual filesystem — scratch space and memory that lives outside the context window, so long work isn't limited by token budget.
• A detailed system prompt — the harness ships strong instructions for how to plan, delegate, and use the filesystem.

create_deep_agent

You create one much like create_agent — tools plus instructions — and the harness does the rest.

from deepagents import create_deep_agent

agent = create_deep_agent(
    tools=[web_search],
    instructions='You are an expert researcher. Plan first, then execute.',
)
# built on LangGraph — comes with planning, sub-agents, and a virtual filesystem
agent.invoke({'messages': [{'role': 'user', 'content': 'Research X and write a brief.'}]})

The backend: where the virtual filesystem lives

That virtual filesystem needs somewhere to store its files, and the backend parameter decides where. By default the files live in the agent's LangGraph state — simple, and gone when the run ends. Pass a filesystem-backed backend instead and the agent's files are written to real disk, so they persist across runs and can be inspected like any other files (other backends store them in a LangGraph Store, or compose several). Choose the backend by how long the work needs to outlive a single run.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    tools=[web_search],
    instructions='Research and write to files as you go.',
    backend=FilesystemBackend(root_dir='./agent_workspace'),   # real files on disk
)
# default (no backend) keeps the virtual files in state — gone after the run

A filesystem backend does one more useful thing: the agent can load Agent Skills (SKILL.md folders) straight from that directory, picking up new capabilities from disk (see the Agent Skills post). So the backend isn't just where scratch files go — it's how a deep agent gains persistent memory and reusable skills at once.

When to reach for it

Deep agents are the top of the least-agency ladder: use them for genuinely long-horizon, open-ended tasks — multi-step research, large coding jobs — where planning and sub-agents earn their cost. For a simple Q&A or a single-tool task, a create_agent or a plain loop is the right, cheaper call.

A deep agent is what you build when the task is too long for one loop to hold — planning, sub-agents, and a filesystem are how it keeps its head across many steps.