What Are LangGraph Deep Agents? The Harness Explained

A single tool-calling loop is fine for a task that finishes in four steps. It falls apart on work that runs for an hour. The model loses the thread of what it was doing, the conversation history outgrows the context window, and one large tool result poisons everything downstream.

What separates a demo from a working agent is the harness: planning so the agent can decompose and track its own work, a place to put intermediate state that isn't the message history, delegation so subtasks get clean context, and compaction so long runs don't fall off a cliff. LangGraph Deep Agents is LangChain's packaged answer to all four.

What Are Deep Agents?

Deep Agents is an open-source, MIT-licensed agent harness from the LangChain team, distributed as the deepagents package in Python and deepagents on npm for JavaScript and TypeScript. It has picked up roughly 15,000 GitHub stars since release.

The entry point is a single function:‍


from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search, fetch_page, run_query],
)

agent.invoke({"messages": "Research LangGraph and write a summary"})

That call returns a compiled LangGraph graph, ready to invoke or deploy. Behind it, the harness has already attached a planning tool, filesystem access, subagent capability, summarization and a built-in system prompt that tells the model how to use all of them. You supply the model and your domain tools; the harness supplies the scaffolding.

The JavaScript package publishes environment-specific entrypoints (deepagents for Node, deepagents/browser for browser-safe usage) and declares the LangChain runtime packages as peer dependencies, so your application controls their versions and everything resolves to one shared copy.

What the Harness Actually Adds?

Deep Agents is assembled from middleware. Each piece attaches tools and prompt instructions to the agent, and you can override or remove any of them. Understanding the default set is the fastest way to understand what you're getting.

Todo List Middleware

Adds a write_todos planning tool. The agent breaks an objective into tasks, records them, and updates progress as it goes. This sounds trivial and isn't: an explicit, writable plan is what lets a model recover its place after twenty tool calls instead of drifting.

File system Middleware

Adds ls, read_file, write_file, edit_file, glob, grep and delete, plus an optional execute tool when the backend supports it. The filesystem is the agent's working memory. Instead of carrying a 40,000-token scrape in the message history, the agent writes it to a file and greps the part it needs later.

SubAgent Middleware

Adds a task tool for delegating work to subagents, each running with an isolated context window. The parent agent gets back a result rather than the entire exploration that produced it, which is the single most effective form of context control available.

There is also async subagent support over the Agent Protocol, where subagents return immediately with a task ID and the main agent keeps working while they execute. Those task IDs are persisted in agent state under async_tasks, so they survive context compaction and offloading. It works against LangGraph Platform or any self-hosted server implementing the Agent Protocol spec.

Summarization Middleware

Condenses message history when a conversation grows past the context limit. This is the piece most teams write badly by hand, usually by truncating from the front and silently losing the original instructions.

Anthropic Prompt Caching Middleware

Cuts redundant token processing on Anthropic models automatically. On a long agent run where the system prompt and tool definitions are resent on every step, this is a direct line item on the bill.

Patch Tool Calls Middleware

Repairs message history when tool calls are interrupted or cancelled before returning results. An unglamorous fix for a failure mode that otherwise throws provider-side validation errors halfway through a run.

Two more attach when you use the relevant features: MemoryMiddleware persists context across sessions, loading agent memory from AGENTS.md files, and SkillsMiddleware enables custom skills.

The Virtual Filesystem and Its Backends

The filesystem deserves its own section because so much else depends on it. Skills, memory, code execution and context management all read and write through the same virtual filesystem, and so can your own custom tools and middleware.

It is pluggable. Backends include in-memory state, local disk, the LangGraph store, composite routing across several backends, and sandbox backends for isolated execution. Swapping backends changes where files physically live without changing the agent code, which is what makes the same agent runnable in a notebook, in CI and in production.

The harness also supports declarative permission rules controlling which files and directories the agent can read or write. Rules are passed as a list at agent creation, evaluated in declaration order with first-match-wins semantics, and they apply to the built-in filesystem tools. Worth noting for anyone designing least-privilege agents: declarative subagents don't inherit the parent's filesystem restrictions. You have to give a subagent its own FilesystemMiddleware instance to constrain it independently.

Deep Agents Is Built on LangGraph, Not an Alternative to It

This is where most coverage of the topic goes wrong, so it's worth stating plainly. Searching for "deep agents vs langgraph" implies a choice between two options. There isn't one. create_deep_agent() returns a LangGraph graph. Deep Agents is LangGraph with a harness pre-assembled on top.

LangChain describes three layers of the same stack:

• Deep Agents when you want the full harness with planning, context management and delegation already wired up
• create_agent when you want a lighter harness without the bundled middleware
• LangGraph when the agent loop itself isn't the right shape and you need a custom graph

The layers compose rather than compete. Any LangGraph CompiledStateGraph can be passed in as a subagent to a deep agent, so custom orchestration slots in alongside the harness defaults. You can start with create_deep_agent(), hit a workflow the standard loop handles badly, build that one piece as a LangGraph graph, and hand it to the harness as a subagent. Nothing gets thrown away.

If you're still working out where LangGraph itself sits relative to the wider LangChain ecosystem, our LangChain vs LangGraph breakdown covers that layer.

Deep Agents vs create_agent vs LangGraph

The decision is less about capability than about how much of the harness you want to own. Every default you accept is a thing you don't have to build, and a thing you can't change without going one layer down.

When to Use Each Layer

Use Deep Agents when the work is long-horizon and open-ended: research that spans dozens of sources, multi-file code changes, document generation where the agent needs somewhere to keep drafts. Also use it when you want a credible agent running this week rather than next month.

Use create_agent when you know exactly which tools you need and the task completes in a handful of steps. Loading a planning tool and a virtual file system onto a three-step classification agent adds prompt overhead and latency for nothing.

Use LangGraph directly when the control flow is the actual problem: explicit branching, deterministic routing, human approval gates at specific nodes, cycles that aren't a tool-calling loop. If you find yourself fighting the harness to express your flow, you've outgrown it. For the multi-agent patterns that sit above a single agent, our guide to multi-agent orchestration covers the territory.

A Better Alternative for Production: TrueForge Agent Harness

LangChain Deep Agents solves much of the hard work inside an individual agent, including planning, subagents, filesystem tools, skills, memory, and long-running execution. But once you're running agents across multiple teams, the problem shifts from building the agent to operating the fleet.

TrueForge is TrueFoundry's open-source, vendor-neutral agent harness for that runtime layer. It runs the agent loop around the model, including planning, tool calls, context management, approvals, and session state, while letting you bring your own models, MCP servers, and sandbox providers.

You can run it locally with npx @truefoundry/trueforge, or deploy the same harness for a team using Docker Compose or Helm. See the TrueForge documentation.

Optimizing the Agent Runtime

TrueForge also provides several mechanisms for controlling the amount of context and tool data that reaches the model.

Deferred tool loading means MCP tool schemas load on demand instead of filling the window upfront. Code Mode lets the agent chain several tool calls inside one sandbox script, so only the printed summary enters context rather than every intermediate result. Oversized tool responses get offloaded to a sandbox file and replaced with a path and a preview. Compaction fires at 80% of the model's context length and swaps old history for a structured summary, which is the direct answer to replay. Subagents run with their own clean context and hand back only the result.

The sandbox model is the other lever. Most harnesses wrap the entire session in a container. TrueForge treats the sandbox as a tool and spins one up only when the agent actually needs to execute code, so one server runs many agents at once and turns that never touch code stay cheap.

More Than a Python Library

TrueForge is also structured as a runtime rather than only a library interface.

The core server runs the agent loop and provides streaming, approval gates, subagent delegation, compaction, and persistent sessions. An HTTP API and TypeScript SDK (@truefoundry/trueforge-sdk) expose the same capabilities programmatically. A separate chat UI and UI SDK (@truefoundry/trueforge-ui) can be used directly, themed, or embedded into another product.

This gives teams a deployment surface beyond the Python agent definition itself: the same runtime can power an application, API, or embedded agent experience.

Models, MCP servers and sandbox providers are all bring-your-own. When a cheaper model ships you point at it instead of rewriting the agent, which is how the same benchmark run on GLM-5.2 solved the same ~11 of 14 tasks for $2.90 per run.

Deep Agents vs TrueForge Benchmark

The difference between an agent framework and an agent runtime becomes clearer when you compare them on the same workloads. TrueFoundry benchmarked TrueForge and Deep Agents on DevRev's Enterprise-Bench, which consists of 14 cross-system enterprise tasks. Each task requires the agent to plan, call MCP tools across a CRM, project tracker, and document store, combine the results, and return an answer that meets the evaluation rubric. Both harnesses ran the same tasks with the same MCP servers, and answers were scored by a blind LLM judge.

With Opus 4.8 held constant, the two harnesses produced similar task accuracy, but their execution costs were different:

The benchmark shows a relatively small difference in task accuracy, but a much larger difference in execution cost. TrueForge used less than a quarter of the tokens used by Deep Agents and was roughly 2.5x cheaper per run on the same model.

The Runtime Layer for Production AI Agents

Run production agents with an open-source runtime for your models, MCP tools, sandboxing, approvals, and observability.

Explore TrueForge

View on GitHub

The difference comes largely from how the two runtimes handle orchestration and context. Deep Agents provides capabilities such as planning, a virtual filesystem, and subagents, but these can also add more orchestration and context to each turn. TrueForge takes a leaner approach, using targeted tool calls and context compaction to avoid repeatedly sending large histories and tool responses back to the model. This matters because the cost of an agent is not determined by the model price alone. Two agent systems running the same model can have very different token consumption depending on how they implement planning, tool use, context management, and subagents.

Connecting the Agent Runtime to the Platform Layer

TrueForge can also connect to TrueFoundry's AI Gateway and MCP Gateway to provide the controls that become important once agents are no longer isolated projects, including centralized model access, MCP credentials, RBAC, budgets, guardrails, credential rotation, and unified traces. This moves those concerns out of individual agent definitions and into a shared platform layer.

For teams evaluating Deep Agents for production, the benchmark is a useful reminder that the framework is only one part of the stack. The runtime architecture around the agent can have a significant impact on token usage, latency, and cost. TrueForge is designed to provide that runtime layer while keeping the model and infrastructure choices open.

Conclusion

Deep Agents, create_agent, and LangGraph sit at different levels of abstraction in the LangChain agent stack. create_agent gives you a lightweight agent loop, while LangGraph provides the underlying graph primitives for developers who need to define the execution flow themselves. Deep Agents builds on top of LangGraph to provide a more complete agent harness with planning, subagents, context management, and filesystem capabilities.

The choice therefore comes down to how much of the agent runtime you want to control. If a standard agent loop and built-in capabilities are enough, Deep Agents reduces the amount of infrastructure you need to build. If you need a lightweight loop, create_agent provides a simpler starting point. When the execution flow itself is the core requirement, LangGraph gives you the primitives to design it explicitly.

For teams looking beyond the LangChain ecosystem, TrueForge takes another approach: an open-source, model-neutral agent harness that provides the runtime layer while keeping the model and underlying infrastructure under your control.

FAQ

Q: What are LangGraph Deep Agents?

‍A: Deep Agents is LangChain's open-source, MIT-licensed agent harness built on LangGraph. Calling create_deep_agent() returns a compiled LangGraph graph with planning, a virtual filesystem, subagent delegation, summarization and prompt caching already attached as middleware. It exists so teams don't have to hand-build the scaffolding that long-running agents need.

Q: Is Deep Agents a replacement for LangGraph?

‍A: No. Deep Agents is built on top of LangGraph and returns a LangGraph graph. They are layers of the same stack, not competing options. Use Deep Agents when the default agent shape fits your task, and drop down to LangGraph when you need a custom control flow. Any LangGraph graph can be passed back into a deep agent as a subagent.

Q: What middleware does a deep agent include by default?

‍A: Six pieces: TodoListMiddleware for planning, FilesystemMiddleware for file operations, SubAgentMiddleware for delegation with isolated context, SummarizationMiddleware for context compaction, AnthropicPromptCachingMiddleware for token savings on Anthropic models, and PatchToolCallsMiddleware for repairing interrupted tool calls. MemoryMiddleware and SkillsMiddleware attach when you use memory or skills.

Q: Does TrueFoundry support MCP and AI agents?

‍A: Yes. TrueFoundry includes an MCP Gateway, Agent Gateway and an MCP & Agents Registry with tool-level access control. Agents built on Deep Agents, LangGraph, CrewAI, AutoGen or custom frameworks can all be deployed and governed centrally.

Q: Can I deploy TrueFoundry in my own VPC or on-prem?

‍A: Yes. TrueFoundry runs in your VPC, on-prem, air-gapped, hybrid or across multiple clouds, and no data leaves your domain. This is the main reason regulated enterprises choose it over SaaS-only gateways.

Q: Does it integrate with my existing observability stack?

‍A: Yes. The gateway is OpenTelemetry-compliant and plugs into Grafana, Datadog, Prometheus or whatever you already run, tracing every request from prompt through to tool and model execution.

Related reading

• CrewAI vs LangGraph — how LangGraph compares to the other main multi-agent framework
• AutoGen vs LangGraph — the same comparison against Microsoft's framework
• LangGraph Pricing — what LangGraph and LangGraph Platform actually cost
• LLM Agents: architecture and patterns — the primer behind this post
• TrueForge: an open-source agent harness — our take on the same problem