Deep Agents

Deep Agents is an open source AI agent framework created by LangChain Inc. in 2025 to solve a clear engineering bottleneck: the complexity of building and stabilizing long-running, multi-step agent loops. While raw execution graph engines provide the base primitives for step-by-step execution, developers traditionally spend weeks manually implementing file systems, token-budget management, thread summarization, context eviction, and subagent delegation. The Deep Agents framework delivers these capabilities in an opinionated, batteries-included harness running directly on top of the LangGraph execution engine.

Occupying the agent runtime and orchestration space, Deep Agents bridges the gap between low-level graph orchestration and rigid agent frameworks. Rather than inventing another bespoke runtime, LangChain Inc. packaged Deep Agents as a specialized application harness over their existing infrastructure. It serves engineers who need a production-grade execution harness for complex workflows without having to hand-wire checkpoints, streaming protocols, or isolated subagent contexts from scratch. With an MIT license and nearly 30,000 GitHub stars, it has quickly become a notable contender among teams building autonomous systems.

The core philosophy of this Python agent framework is composability over lock-in. Deep Agents provides opinionated defaults optimized for deep work: task planning, pluggable filesystems, isolated subagent environments, and human approval gates. At the same time, it preserves the ability to swap, extend, or override any underlying component. If an engineering team wants to build agents with Deep Agents, they can start with the defaults on day one and progressively tailor the middleware, model providers, and backend stores as requirements scale.

The Deep Agents architecture relies on a clear, three-tier separation of concerns:

1. Deep Agents Harness Layer: The top layer exposes high-level abstractions, including middleware, sandboxed environments, model profiles, planning routines, and subagent routing.
2. LangChain Abstraction Layer: The middle tier manages standard interfaces for model invocation, schema validation, tool execution, and prompt normalization.
3. LangGraph Runtime Layer: The foundation handles the low-level execution graph, persistent state checkpoints, streaming updates, and asynchronous interrupts for human intervention.

1Deep Agents  -> Opinionated harness: planning, filesystem, profiles, subagents
2LangChain    -> Agent abstraction: models, tools, schemas, middleware
3LangGraph    -> Execution runtime: state graphs, checkpoints, streaming, interrupts

Developers interact with the framework through a code-first, imperative Python API centered on the create_deep_agent() factory function. Rather than declaring agents via rigid YAML or configuration files, developers assemble agents programmatically by passing LLM instances, tool lists, environment backends, and subagent graphs directly into the constructor.

When invoked, create_deep_agent() normalizes system prompts, mounts virtual filesystems, registers task delegation tools, and compiles the agent into an executable LangGraph instance. Control flow inside the loop follows a dynamic tool-calling pattern. If a tool call produces an exceptionally large output (such as raw database dumps, large code files, or web scrapes), the harness diverts that data to disk or a virtual backend instead of bloating the model context window. Subagents operate as isolated child graphs: they receive a delegated subtask, execute in their own ephemeral context, and return only the synthesized outcome back to the parent agent.

Deep Agents provides a concrete set of tools specifically designed to prevent context exhaustion and state degradation across long-horizon workloads.

• Pluggable Virtual Filesystem: Agents can read, write, edit, and grep files across local directories, isolated Docker sandboxes, or remote object storage. When tool responses exceed safe token budgets, the framework offloads the raw data to disk and supplies the LLM with file pointers, keeping token consumption low.
• Deep Agents Multi-Agent Delegation: The harness natively supports hierarchical execution. A primary supervisor agent can dynamically route subtasks to general or specialized subagents. Because each subagent runs inside its own isolated context window, parallel exploration does not contaminate the primary agent state. Teams can also mount any pre-existing compiled LangGraph graph directly as a subagent.
• Model-Agnostic Tool Calling: The framework works with any foundation model that supports structured tool use. Developers can run frontier commercial APIs (OpenAI, Anthropic, Google) or point the harness at self-hosted open-weight models via Ollama or vLLM without changing agent logic.
• Reusable Skills and Long-Term Memory: Deep Agents features a skill loader that retrieves domain-specific instructions and procedures on demand. State backends persist long-term facts, entity memory, and user preferences across distinct sessions using pluggable database stores.
• Streaming, Checkpoints, and Human in the Loop: Because the runtime is LangGraph, state persistence and streaming token output work without extra setup. Workflows can be paused at designated human-in-the-loop checkpoints, enabling operators to inspect, modify, or reject sensitive tool calls before execution resumes.
• Observability and Evaluations: Deep Agents integrates natively with LangSmith for distributed trace inspection, latency tracking, cost monitoring, and systematic regression evaluations.

The architectural design of Deep Agents targets scenarios that require sustained, multi-turn reasoning and environment interaction.

Teams use Deep Agents to build automated research analysts that decompose open-ended queries into structured research plans. The primary agent assigns specific questions to subagents, which query search engines, parse dense technical PDFs, and write intermediate notes to the virtual filesystem. The parent agent then inspects the accumulated files to draft comprehensive, cited reports without losing context midway through the run.

Because Deep Agents provides shell access and filesystem manipulation on remote or containerized backends, it serves as an effective harness for coding assistants. Developers deploy it within CI/CD pipelines or local terminal wrappers where the agent inspects repositories, applies multi-file code diffs, runs test suites, interprets tracebacks, and iterates until builds pass. Using local models via Ollama or vLLM makes it possible to run these coding agents entirely on-premise.

For multi-step document verification, regulatory filings, or reconciliation workflows, Deep Agents manages processes that exceed the capacity of a single context window. The agent can ingest batches of contracts, store structured extracts in persistent storage, and pause execution at critical decision gates to await human approval before committing updates to an external database.

Deep Agents is over-engineered for basic, single-turn interactions. If your application only requires a simple RAG query, a classification pipeline, or a low-latency chat interface with sub-second response requirements, the middleware and tool surface introduce unnecessary prompt overhead and token latency.

To install the Deep Agents Python agent framework, install the package from PyPI:

1pip install deepagents langchain-openai

The following Deep Agents tutorial snippet demonstrates how to configure an agent with a custom tool, planning capabilities, and the built-in virtual filesystem:

1import os
2from deepagents import create_deep_agent
3from langchain_openai import ChatOpenAI
4
5# 1. Initialize the tool-calling model
6model = ChatOpenAI(model="gpt-4o", temperature=0)
7
8# 2. Define custom domain tools
9def query_database(query: str) -> str:
10    """Execute a read-only query against the analytics database."""
11    return f"Result for: {query} -> 42 active enterprise accounts."
12
13# 3. Create the deep agent harness
14agent = create_deep_agent(
15    model=model,
16    tools=[query_database],
17    system_prompt="You are a data operations agent. Use the filesystem to organize complex tasks."
18)
19
20# 4. Execute the agent graph
21inputs = {"messages": [("user", "Analyze enterprise account growth and write a summary to report.txt")]}
22for chunk in agent.stream(inputs, stream_mode="values"):
23    latest_message = chunk["messages"][-1]
24    latest_message.pretty_print()

To take this implementation to production, you will need:

• An API key for your chosen LLM provider (or a locally deployed vLLM/Ollama server).
• A persistent checkpointer (such as Postgres) for session durability and interrupt support.
• A sandbox environment (such as Docker or a microVM provider) if enabling arbitrary shell execution.
• A LangSmith API key for end-to-end tracing, monitoring, and debugging.

Full API references and integration guides are maintained in the official LangChain documentation and the public langchain-ai/deepagents GitHub repository.

Selecting the right framework depends on whether you need a fully autonomous out-of-the-box system or granular graph control.

A frequent question is Deep Agents vs LangChain. LangChain is an foundational SDK containing broad model connectors, retrievers, and prompt abstractions. Deep Agents is an opinionated application harness built on top of LangChain. LangChain gives you the raw components, while Deep Agents wires those components into a pre-configured architecture with filesystems, planning, and subagent delegation already operational.

When evaluating Deep Agents vs CrewAI, the main difference lies in orchestration strategy. CrewAI organizes agents around role-playing personas, assigned tasks, and collaborative workflows. Deep Agents takes a systems-first approach rooted in LangGraph: subagents are isolated context instances rather than conversational role-players, and state management relies on explicit checkpoints and filesystems. Teams with complex, multi-step engineering tasks often prefer Deep Agents for its deterministic control, while CrewAI remains popular for rapid role-based ideation.

Is Deep Agents production ready? The underlying runtime (LangGraph) is widely deployed in enterprise production, providing mature checkpointing, streaming, and observability through LangSmith. However, the Deep Agents harness itself is still iterating rapidly in its pre-1.0 lifecycle on PyPI. While the architectural foundation is exceptionally strong, practitioners evaluating Deep Agents alternatives should expect occasional API refinements as the harness matures into the best agent orchestration framework for complex, long-running agent workloads.