Deep Agents

Generative AI application development has evolved rapidly. Initially, developers relied on single LLM calls, then progressed to autonomous shallow agents interacting with external tools, and later to multi-agent collaboration frameworks. Today, the industry is shifting toward Deep Agents—autonomous, long-running agent architectures capable of handling complex, multi-step tasks like deep research, software engineering, and multi-domain analysis.

In this comprehensive tutorial, you will learn the theoretical foundations and practical implementation of Deep Agents using LangChain and LangGraph. We will break down how deep agents differ from shallow and ReAct agents, explore context engineering, implement swappable storage backends, set up on-demand skills with progressive disclosure, and delegate work to specialized sub-agents.

What Is a Deep Agent? #

Simple Explanation #

Imagine you want to plan a complex 4-day trip to Paris on a specific budget. A basic AI assistant might try to answer everything in one short response or run a single search. A Deep Agent, however, acts like a senior trip consultant: it breaks down your goal into a structured to-do list, hires specialized helpers (e.g., a flight researcher, a hotel analyst, a sightseeing guide), keeps notes in a shared workspace file, and synthesizes everything into a polished plan.

Technical Definition #

A Deep Agent is a stateful multi-agent system—typically built on graph frameworks like LangGraph—that handles complex multi-step tasks through four core properties: autonomous planning, specialized sub-agent delegation, system prompt behavior, and persistent virtual file system backends.

Build agents that can plan, use subagents, and leverage file systems for complex tasks

Deepagents is a standalone library for building agents that can tackle complex, multi-step tasks. Built on LangGraph and inspired by applications like Claude Code, Deep Research, and Manus, deep agents come with planning capabilities, file systems for context management, and the ability to spawn subagents.

When to use deep agents

Use deep agents when you need agents that can:

• Handle complex, multi-step tasks that require planning and decomposition
• Manage large amounts of context through file system tools
• Delegate work to specialized subagents for context isolation
• Persist memory across conversations and threads

Real-World Analogy #

Think of a Deep Agent as a Lead Software Architect overseeing a complex software release.

• The Lead Architect (Main Supervisor Agent) receives the client request, writes a project plan (to-do list), and refers to company coding standards (agent.md memory).
• The Architect delegates tasks to Specialized Engineers (Sub-Agents)—such as a backend specialist or a security reviewer—so each engineer focuses strictly on their own domain without clogging the lead’s memory.
• Everyone reads from and writes to a Shared File Server (Virtual File System) to persist progress across days.

Why Are Deep Agents Important? (Solving Shallow & ReAct Agent Limits) #

To understand why Deep Agents matter, we must examine the limitations of traditional agent architectures:

1. Shallow Agents (Single-Loop Tool Callers) #

A shallow agent connects an LLM directly to one or more external tools (e.g., weather or search APIs). When a user asks a simple question like “What is the current temperature in Paris?”, the LLM invokes the API tool and returns the response.

• The Problem: There is no explicit planning, no multi-step reasoning, and very limited context retention. If given a complex query like “Analyze current AI news and evaluate its impact on physics research and global economic trends”, shallow agents fail because they cannot decompose the problem into sub-tasks.

2. ReAct Agents (Reason + Act Loops) #

A ReAct agent improves upon shallow agents by introducing an iterative thought-action-observation loop. The LLM can invoke tools multiple times based on intermediate observations.

• The Problem: Despite being more capable, ReAct agents remain fundamentally shallow. They lack structured planning tools, deep multi-step reasoning, persistent state management, cross-thread memory, and context isolation. As the conversation grows longer, prompt context degrades, costs rise, and the model loses track of earlier goals.

Feature Matrix: Shallow vs. ReAct vs. Deep Agents #

The Four Core Components of a Deep Agent #

Deep agents rely on four fundamental building blocks:

1. Planning Tool (Automated To-Do List): When assigned a task, the agent automatically creates and updates a to-do list to track multi-step execution progress.
2. Specialized Sub-Agents: The main supervisor delegates sub-tasks to isolated child agents, preserving context hygiene and token efficiency.
3. System Prompt & Operating Context: Sets system behavior, constraints, and operational guidelines.
4. Virtual File System & Backends: A persistent storage abstraction allowing agents to read, write, edit, and search files during execution.

Detailed Concepts: Context Engineering, Memory, Skills, and Backends #

1. Context Engineering #

Context Engineering is the practice of providing the agent with the right information, tools, and constraints in the right format at the right time. Deep agents handle context through four strategies:

• Input Context: Information supplied at agent startup (System Prompt, agent.md memory, and skill references).
• Runtime Context: Dynamic inputs injected during task execution.
• Context Compression: Automated summarization middleware that condenses long conversation histories.
• Context Isolation: Delegating complex sub-tasks to sub-agents so intermediate outputs do not pollute the main prompt.

2. Memory (agent.md) vs. Skills (Progressive Disclosure) #

A key architectural distinction in deep agent design is how global project guidelines differ from specialized capabilities:

• Memory (agent.md): A project’s “README for agents”. It stores durable context—such as tech stack requirements, coding conventions, or corporate rules—and is loaded into the system prompt on every execution turn.
• Skills: Specialized capability modules (e.g., AWS deployment expert, Python coding guide, Report Writer). Skills use progressive disclosure: they are loaded only when relevant to the current user query and released after execution to maintain prompt hygiene.

3. Swappable Backends #

The virtual file system abstraction allows deep agents to manipulate files. The backend specifies where those files physically reside:

1. StateBackend (Default): Saves files in the LangGraph execution state (RAM) for the current thread session.
2. FileSystemBackend: Writes physical files directly to disk under a designated root directory, enabling persistence across restarts.
3. StoreBackend: Stores files in a LangGraph Store (key-value or vector storage) under specific namespaces, allowing cross-thread file sharing.

Practical Implementation Walkthrough #

Let’s build a Deep Agent step by step using Python, LangChain, and deepagents.

Step 1: Environment & Dependency Setup #

Initialize your project workspace using uv and install the required dependencies:

# Initialize workspace and virtual environment
uv init
uv venv
source .venv/bin/activate

# Install required libraries
uv add deepagents langchain langchain-openai langchain-groq tavily-python python-dotenv ipykernel

Step 2: Define External Tools (Tavily Web Search) #

Create a web search tool utilizing TavilyClient to retrieve real-time data:

import os
from typing import Literal
from dotenv import load_dotenv
from tavily import TavilyClient

load_dotenv()
tavily_client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

def web_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance", "sports news"] = "general",
    include_raw_content: bool = False
) -> dict:
    """Executes a real-time web search using the Tavily API."""
    return tavily_client.search(
        query=query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic
    )

Step 3: Create a Basic Deep Agent #

Initialize a basic Deep Agent using create_deep_agent. Note that create_deep_agent automatically attaches middleware hooks for tool-call parsing, summarization, and automated to-do planning:

from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

# Initialize LLM
model = init_chat_model("gpt-4o", model_provider="openai")

# Create Deep Agent
deep_agent = create_deep_agent(
    model=model,
    tools=[web_search],
    system_prompt="You are an expert AI research assistant. Always cite sources and use clear structure."
)

# Invoke Agent
response = deep_agent.invoke({
    "messages": [{"role": "user", "content": "What are LLM Gateways?"}]
})

print(response["messages"][-1].content)

Deep Agents, backends #

In Deep Agents, backends serve as the storage execution layer behind the agent’s Virtual File System.

While the deep agent uses standard file tools (write_file, read_file, edit_file, search_file) to manipulate workspace context, the backend dictates where those files physically live, how long they persist, and how they are shared across threads.

Key Role of Backends #

• Abstraction Layer: Tools operate on abstract file paths (e.g., todo.txt), while the backend translates these calls to physical storage resources like RAM, local disk, or object stores.
• Context Preservation & Offloading: Deep agents offload large search results, intermediate research notes, and code drafts into files rather than stuffing them into the immediate LLM prompt context.

Core Types of Backends #

1. StateBackend (Default)

• How it works: Files are stored directly inside the LangGraph state held in RAM.
• Scope & Lifetime: Scoped to a single thread/session. Files persist across multiple message turns within the same thread ID.
• Persistence: Once the session or agent execution closes, the state is cleared and files are deleted. No physical files are created on disk.
• When to use: Fast, ephemeral execution where temporary scratch files do not need to survive process restarts.

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# StateBackend is used by default if no backend is specified
agent = create_deep_agent(
    model=model,
    tools=[web_search],
    backend=StateBackend()
)

2. FileSystemBackend

• How it works: Reads and writes actual physical files directly onto the host disk / hard drive under a designated root_dir.
• Scope & Lifetime: Persists permanently on the disk across application restarts and across independent execution threads.
• Persistence: Full local disk persistence. Existing project files (like an agent.md file) on disk are directly readable by the agent.
• When to use: Local developer environments, coding assistants, or workflows where generated files (e.g., code, reports) must be saved to the real file system.

from deepagents import create_deep_agent
from deepagents.backends import FileSystemBackend

disk_backend = FileSystemBackend(root_dir="./project_files", virtual_mode=True)

agent = create_deep_agent(
    model=model,
    tools=[web_search],
    backend=disk_backend
)

3. StoreBackend

• How it works: Backed by a LangGraph Store (such as an InMemoryStore or persistent key-value / vector store). Files are stored as entries under specific namespaces (e.g., ("user_id", "workspace")).
• Scope & Lifetime: Enables cross-thread sharing. Different chat threads or user sessions can read and write files within the same shared namespace.
• Persistence: Does not write to local disk. Persistence depends on whether the underlying store is saved to a persistent database or held in memory.
• When to use: Multi-tenant systems or long-running user workspaces where state and project notes must be accessed across separate chat threads.

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
store_backend = StoreBackend(store=store, namespace=("user_workspace", "files"))

agent = create_deep_agent(
    model=model,
    tools=[web_search],
    backend=store_backend
)

Backend Comparison Summary #

Step 5: Implement On-Demand Skills & Operating Memory #

Context engineering in Deep Agents distinguishes between Durable Operating Memory (agent.md) and On-Demand Skills .

Skills are reusable agent capabilities that provide specialized workflows and domain knowledge.

You can use Agent Skills to provide your deep agent with new capabilities and expertise. For ready-to-use skills that improve your agent’s performance on LangChain ecosystem tasks, see the LangChain Skills repository.

Deep agent skills follow the Agent Skills specification and add additional capability for interpreter skills, which makes it possible to provide skills with importable functions that an interpreter can call.

1. Operating Memory (agent.md)

• What it is: Think of agent.md as a “README for AI agents”. It holds durable, high-level project rules—such as tech stack constraints, backend framework preferences, or organizational standards.
• How it works: Memory is always loaded into the system prompt on every execution turn (it does not use progressive disclosure).
• Best Practice: Keep agent.md small and minimal to save context tokens and prevent model confusion

Example: agent.md

# Agent Operating Guidelines
- Architecture: FastAPI, LangChain, LangGraph, Quadrant Vector DB.
- Coding Standard: Write typed, clean, runnable Python code with docstrings.
- Planning Rule: Always plan multi-step tasks using explicit to-do lists before invoking heavy tools.

2. On-Demand Skills Directory Layout

Unlike memory, skills are specialized capability modules. They use progressive disclosure: the agent reads only skill titles/descriptions first, loads the full skill instructions only when relevant to a specific query, and releases them post-execution to keep context clean

Code Example

from pathlib import Path
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import MemorySaver
from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# 1. Initialize Model & Checkpointer
model = init_chat_model("gpt-4o", model_provider="openai")
checkpointer = MemorySaver()

# 2. Read Operating Memory (agent.md)
memory_path = Path("projects/agent.md")
agent_memory = memory_path.read_text(encoding="utf-8") if memory_path.exists() else ""

# 3. Create Deep Agent with Skills Directory & Memory
agent = create_deep_agent(
    model=model,
    system_prompt=f"You are an AI assistant. Follow these project conventions:\n\n{agent_memory}",
    skills_dir="./skills",             # Automatically registers skills from directory
    backend=StateBackend(),
    checkpointer=checkpointer
)

# 4. Invoke Agent — Request triggers 'python_expert' skill on-demand
response = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "Write a Python function for binary search using recursion."}
        ]
    },
    config={"configurable": {"thread_id": "thread_1"}}
)

Step 6: Create Sub-Agents with Structured Pydantic Output #

When an agent needs to perform deep research or multi-step analysis, dumping all intermediate search logs into the main conversation pollutes prompt context.

Sub-agents provide context isolation (quarantine). The child sub-agent performs tool loops inside its own isolated context and returns a validated, structured Pydantic data object back to the supervisor agen

Delegate research tasks to a specialized sub-agent that returns structured Pydantic data (summary, confidence, sources):

import os
from typing import Literal
from pydantic import BaseModel, Field
from dotenv import load_dotenv
from tavily import TavilyClient
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

load_dotenv()
tavily_client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

# 1. Define Web Search Tool
def web_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False
) -> dict:
    """Performs real-time web search via Tavily API."""
    return tavily_client.search(
        query=query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic
    )

# 2. Define Pydantic Schema for Structured Output
class ResearchFindings(BaseModel):
    summary: str = Field(description="Executive summary of key findings")
    confidence: float = Field(description="Confidence score between 0.0 and 1.0")
    sources: list[str] = Field(description="List of verified reference URLs")

# 3. Define Sub-Agent Specification with response_format
research_subagent = {
    "name": "research_specialist",
    "description": "Performs deep internet research and returns structured findings.",
    "system_prompt": "You are a research specialist. Gather verified facts and format results as structured data.",
    "tools": [web_search],
    "response_format": ResearchFindings  # Enforces Pydantic structured contract
}

# 4. Initialize Main Supervisor Agent with Sub-Agents
main_agent = create_deep_agent(
    model=init_chat_model("gpt-4o", model_provider="openai"),
    subagents=[research_subagent],
    skills_dir="./skills"
)

# 5. Invoke Main Agent
result = main_agent.invoke({
    "messages": [
        {"role": "user", "content": "Research recent advances in quantum computing LLM accelerators."}
    ]
})

# Accessing the supervisor's final output
print(result["messages"][-1].content)

Architecture & Execution Workflow #

The complete end-to-end execution workflow of a Deep Agent combines all four core pillars into a unified graph:

Key Takeaways #

1. Deep Agents exceed Shallow/ReAct limits: By adding explicit planning, persistent memory, swappable backends, and sub-agent delegation, Deep Agents reliably execute complex multi-step tasks.
2. Context Hygiene is Critical: Use agent.md for global rules, dynamic skills for task-specific capabilities, and sub-agents for context isolation.
3. Storage Flexibility: Choose StateBackend for fast session-based tasks, FileSystemBackend for local disk persistence, or StoreBackend for cross-thread data sharing.

Here is a set of senior-level, situation-based technical interview questions and detailed architectural answers focusing on Deep Agents, LangChain, and LangGraph. These scenarios test deep reasoning, system design trade-offs, context management, and production reliability

Question 1 (System Design & Context Isolation)

Scenario: You are building an enterprise research assistant tasked with analyzing global financial trends, market news, and regulatory updates to output a multi-page report. Initially, your team implemented a single ReAct agent equipped with 15 different tools. However, after 5–10 interaction turns, the LLM starts hallucinating tool parameters, missing earlier instructions, and hitting context window limits due to massive raw tool search outputs.

Interview Question: How would you re-architect this monolithic ReAct agent into a Deep Agent using LangGraph to eliminate context degradation and prevent token budget explosion?

Answer:

The degradation happens because ReAct agents operate in a single, un-isolated loop where every raw tool response, intermediate observation, and scratchpad note is appended into the main conversation prompt. As conversation history grows, context inflation degrades model adherence.

To solve this, re-architect the application into a Deep Agent using three core principles:

1. Automated Planning Middleware (To-Do List): Introduce a supervisor planning tool that decomposes the complex prompt into an explicit to-do list. Rather than holding all tasks in active prompt memory, the agent tracks state explicitly across turns.
2. Context Quarantine via Sub-Agent Delegation: Split the monolithic agent into specialized sub-agents (e.g., a Financial Data Analyst, a News Researcher, a Regulatory Analyst). When the supervisor delegates a research topic to a sub-agent, the sub-agent executes its tools in an isolated context window.
3. Context Compression & Offloading: The sub-agent synthesizes its raw web search tool outputs into a concise summary or writes heavy results directly to a virtual file system. Only the final structured summary is returned to the main supervisor. This keeps the supervisor’s context clean and prevents prompt bloat.

Question 2 (Infrastructure & Storage Backends)

Scenario: Your company is deploying a Deep Agent to a stateless, auto-scaling Kubernetes cluster. The agent requires a virtual file system so sub-agents can write intermediate drafts and code files. However, because pods can restart or scale down at any moment, relying on the local container disk is risky. At the same time, users expect their custom workspace notes to persist across different login sessions and threads.

Interview Question: How would you design the storage layer using StateBackend, FileSystemBackend, and StoreBackend in LangGraph to balance execution speed, pod statelessness, and cross-thread persistence?

Answer:

Deep Agents rely on virtual file system backends to abstract where files physically reside. The storage layer should be tiered based on durability requirements:

1. StateBackend (Session-Level / Transient Data): Use StateBackend for intermediate scratch files created during a single workflow run. Files live directly inside the LangGraph state (in-memory) tied to a specific thread ID. If a container restarts, thread state can be rehydrated from a database checkpointer (e.g., PostgreSQL / Redis).
2. FileSystemBackend (Avoid in Stateless Containers unless mounted): FileSystemBackend writes files directly to disk under a root directory. In a stateless Kubernetes pod, local disk writes are ephemeral. Unless mounted to a persistent volume (EFS / NFS), FileSystemBackend should be avoided for cross-session storage in cloud-native deployments.
3. StoreBackend (Cross-Thread & Long-Term Memory): For data that must persist across different user sessions and threads (such as user preferences or project workspace notes), configure StoreBackend backed by an InMemoryStore or persistent Key-Value / Vector database store. By mapping files under specific user namespaces (e.g., ("user_id", "workspace")), any thread can access shared files across independent chat sessions.

Question 3 (Prompt Optimization & Context Engineering)

Scenario: An engineering team built an AI coding assistant. To make it versatile, they dumped 100 pages of guidelines—including Python best practices, AWS deployment rules, SQL conventions, and React design systems—into the main system prompt. Token costs have skyrocketed, and the agent frequently applies React rules to backend Python tasks.

Interview Question: How would you restructure this system using Memory (agent.md) and On-Demand Skills (Progressive Disclosure) to optimize performance and reduce token usage?

Answer:

The team is violating the core rule of Context Engineering: providing the right context in the right format at the right time without polluting prompt memory.

The solution is to separate static global rules from specialized task guidelines:

1. Durable Operating Memory (agent.md): Keep the always-loaded system memory minimal. Store only high-level global architecture conventions, tech stack definitions, and baseline behavioral rules in an agent.md file. This is combined with the system prompt on every execution turn.
2. On-Demand Skills with Progressive Disclosure: Move domain-specific instructions (AWS setup, React conventions, SQL rules) into separate skill modules under a /skills directory (e.g., /skills/python, /skills/aws).
3. Dynamic Loading & Unloading: Skills operate under progressive disclosure:
   • When a user asks “Write a Python script to query PostgreSQL”, the agent inspects available skill metadata and dynamically loads only the Python and SQL skills into context.
   • Once the coding task completes, the skill context is released, keeping the agent’s memory clean for subsequent turns.

Question 4 (Fault Tolerance & Reliability)

Scenario: You have a long-running multi-step Deep Agent performing a 12-step data pipeline. At Step 7, an external search API returns a 503 Service Unavailable error or rate-limit exception. In a standard script, the pipeline fails and restarts from Step 1, wasting LLM tokens and execution time.

Interview Question: How do LangGraph checkpointers and automated planning tools ensure state recovery and fault tolerance in Deep Agents?

Answer:

Fault tolerance in Deep Agents is achieved through Graph Checkpointing and Dynamic To-Do Tracking:

1. State Persistence via Checkpointers: By attaching a checkpointer (e.g., MemorySaver or PostgresSaver) to the agent, LangGraph saves a state snapshot at every node transition. If a tool call fails at Step 7, the thread state remains saved up to Step 6.
2. Automated To-Do Replanning: Deep Agents use an automated planning middleware that maintains an active task queue (to-do list). When a tool call raises an error, the agent catches the exception, updates the status of the specific task in its to-do list to failed or pending, and can either retry the tool with exponential backoff or re-route execution to an alternative sub-agent.
3. Resumption without Retries: Upon recovering from the API outage, the agent re-hydrates its state from the last checkpoint using its unique thread_id. It skips steps 1–6 (which are already saved in the state or virtual file system) and resumes directly from Step 7.

Question 5 (Structured Sub-Agent Interoperability)

Scenario: You are designing a multi-agent system where a Lead Agent coordinates a Data Extraction Sub-Agent and a Report Writer Sub-Agent. If the Data Extraction Sub-Agent returns raw unstructured text, the Report Writer Sub-Agent frequently misinterprets numbers or fails to extract source URLs.

Interview Question: How do you enforce strict input/output contracts between supervisor agents and sub-agents using Pydantic schema validation in LangChain/LangGraph?

Answer:

To guarantee deterministic interaction between sub-agents, define strict schema boundaries using Pydantic structured outputs (response_format):

1. Define Schema Specifications: Create a explicit Pydantic model representing the exact payload required by downstream agents:

from pydantic import BaseModel, Field

class ExtractionFindings(BaseModel):
    summary: str = Field(description="Executive summary of facts")
    metrics: dict[str, float] = Field(description="Key metric key-value pairs")
    confidence: float = Field(description="Score between 0.0 and 1.0")
    sources: list[str] = Field(description="List of verified source URLs")

1. Bind Schema to Sub-Agent Definition: Pass the schema into the sub-agent’s specification under the response_format parameter:

extraction_subagent = {
    "name": "data_extractor",
    "description": "Extracts structured financial metrics from documents.",
    "system_prompt": "Extract precise metrics and return validated findings.",
    "tools": [document_search_tool],
    "response_format": ExtractionFindings
}

1. Downstream Consumption: When the main supervisor invokes the data_extractor sub-agent, the framework enforces tool-call output validation via the model’s structured output mechanism. The supervisor receives a validated ExtractionFindings object rather than unstructured text, guaranteeing clean inputs for the Report Writer Sub-Agent.

Reference

• https://github.com/krishnaik06/Deep-agents-With-Langchain
• https://docs.langchain.com/oss/python/deepagents/overview

Deep Agents Quiz #