Related Pages

Related topics: Quickstart Guide, Agent Graph Architecture

Deep Agents Overview

Deep Agents is a production-ready agent framework built on LangGraph that provides an opinionated harness for building sophisticated AI agents with planning, filesystem access, context management, subagent delegation, and skill-based workflows. The framework is designed to be model-agnostic, supporting any LLM that implements tool calling, and integrates deeply with the LangChain ecosystem for tracing, evaluation, and deployment. Source: README.md:1-15

Architecture Overview

Deep Agents sits at the top of the LangChain stack, building upon LangGraph's graph runtime and LangChain's create_agent minimal harness. It provides a full-featured agent loop out of the box while remaining composable—any compiled LangGraph state graph can be passed as a subagent to a Deep Agent.

graph TD
    A[Deep Agents] --> B[create_agent Harness]
    B --> C[LangGraph CompiledStateGraph]
    C --> D[LangChain Chat Models]
    
    E[FilesystemBackend] -.-> A
    F[Memory Middleware] -.-> A
    G[Skills System] -.-> A
    H[Subagents] -.-> A
    
    I[LangSmith] --> |Tracing & Deployments| A

Relationship to LangChain Ecosystem

Source: README.md:45-60

Core Components

Agent Creation

The primary entry point for creating a Deep Agent is the create_deep_agent function. The following example demonstrates the basic pattern:

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20251101",
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})

Source: libs/deepagents/README.md:1-20

Memory System

Memory provides persistent context that the agent can reference across sessions. The memory system is configured through middleware and typically uses an AGENTS.md file that is loaded into the agent's system prompt.

agent = create_deep_agent(
    memory=["./AGENTS.md"],  # Middleware loads into system prompt
    # ... other config
)

Key Configuration Options:

Known Issues:

• In deepagents 0.6, add_cache_control=True may put incorrect cache_control markers on volatile memory blocks. See Issue #3639.

Source: examples/content-builder-agent/README.md:1-25

Skills System

Skills are specialized workflows that extend agent capabilities with domain-specific knowledge, procedures, and tool integrations. They use a progressive disclosure design to manage context efficiently:

graph LR
    A[Metadata<br/>100 words] --> B[SKILL.md Body<br/>&lt;5k words]
    B --> C[Bundled Resources<br/>Unlimited]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

#### Skill Loading Levels

Source: libs/cli/examples/skills/skill-creator/SKILL.md:1-50

#### Skill Directory Precedence

Skills are loaded from four directories with the following precedence (highest wins for conflicts):

Source: libs/cli/examples/skills/skill-creator/SKILL.md:50-80

Skills Structure

A skill directory contains:

skill-name/
├── SKILL.md           # Required: skill metadata and instructions
├── scripts/           # Executable scripts (not loaded into context)
├── references/        # Detailed reference docs (loaded on demand)
└── assets/            # Templates, images, boilerplate (used, not read)

Files to Avoid: README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md—these add clutter without helping the agent.

Source: libs/cli/examples/skills/skill-creator/SKILL.md:80-120

Subagents

Subagents are specialized agents that can be delegated specific tasks. They are particularly useful for parallel execution and complex workflows requiring different expertise.

agent = create_deep_agent(
    subagents=[
        {
            "name": "researcher",
            "description": "Research topics before writing...",
            "model": "anthropic:claude-haiku-4-5-20251001",
            "system_prompt": "You are a research assistant...",
            "tools": [web_search],
        }
    ],
)

Source: examples/content-builder-agent/README.md:25-50

Architecture Pattern:

graph TD
    A[Main Agent] -->|task tool| B[Researcher Subagent]
    A -->|task tool| C[Editor Subagent]
    B -->|saves research/| D[Filesystem]
    C -->|reviews content| E[blogs/]
    
    style A fill:#bbdefb
    style B fill:#c8e6c9
    style C fill:#ffe0b2

Known Issues:

• Subagents lack checkpoint persistence, and state queries truncate tool execution history. See Issue #573.

Source: examples/content-builder-agent/README.md:50-80

Filesystem Backend

The FilesystemBackend provides file operations and filesystem traversal capabilities. It supports features like pagination, glob patterns, and grep searches.

Key Capabilities:

• Read/write files with pagination support
• Glob-based file discovery
• Content search with ripgrep
• Directory traversal

Known Issues:

• read_file pagination may skip lines after wrapping due to double limit application. See Issue #2453.
• SandboxBackend.grep crashes with ValueError when container exec fails. See Issue #3441.

Source: examples/content-builder-agent/README.md:1-15

Built-in Tools

Deep Agents includes a comprehensive set of built-in tools. The following table summarizes key tools available:

Source: examples/text-to-sql-agent/README.md:1-50

Example Applications

Deep Research Agent

A research agent that uses Tavily for web search, parallel subagents for coverage, and strategic reflection via a think_tool.

agent = create_deep_agent(
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    tools=[tavily_search, think_tool],
)

Source: examples/deep_research/README.md:1-30

Content Builder Agent

Blog post, LinkedIn post, and tweet generation with memory, skills, subagents, and image generation.

agent = create_deep_agent(
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    tools=[generate_cover, generate_social_image],
    subagents=load_subagents("./subagents.yaml"),
    backend=FilesystemBackend(root_dir="./"),
)

Workflow:

1. Agent receives task → loads relevant skill (blog-post or social-media)
2. Delegates research to researcher subagent → saves to research/
3. Writes content following skill workflow → saves to blogs/ or linkedin/
4. Generates cover image with Gemini → saves alongside content

Source: examples/content-builder-agent/README.md:1-30

Text-to-SQL Agent

Natural language to SQL with planning and skill-based workflows on the Chinook demo database.

agent = create_deep_agent(
    memory=["./AGENTS.md"],
    skills=["./skills/query-writing/", "./skills/schema-exploration/"],
    backend=FilesystemBackend(root_dir="./db/"),
)

Planning Pattern:

Complex Query with Planning:
- Use `write_todos` to plan the approach
- Identify required tables
- Plan the JOIN structure
- Execute the query
- Format results with analysis

Source: examples/text-to-sql-agent/README.md:1-80

LLM Wiki Agent

Script-first example that builds a persistent wiki and syncs through LangSmith Hub commands.

# Ingest sources into wiki
uv run --project examples/llm-wiki \
  python examples/llm-wiki/runner.py \
  --mode ingest --repo "wiki-name" --source ./notes/

# Query the wiki
uv run --project examples/llm-wiki \
  python examples/llm-wiki/runner.py \
  --mode query --repo "wiki-name" --question "What is X?"

Source: examples/llm-wiki/README.md:1-60

Model Support

Deep Agents works with any model that supports tool calling:

Use any LangChain chat model by specifying the model identifier:

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20251101",
    # or
    model="openai:gpt-5.5",
)

Source: libs/deepagents/README.md:1-20

Production Deployment

Deep Agents is production-ready and designed for deployment with LangSmith. Key production features:

• LangGraph-based: Built on LangGraph for reliable agent execution
• LangSmith integration: Tracing, evaluation, and monitoring
• Checkpointing: State persistence for long-running tasks
• Sandbox execution: Safe execution environments for code agents

Deployment Options

Source: README.md:60-80

Deploy via SDK Example

from langgraph_sdk import get_client

client = get_client(url="https://<your-deployment-url>")
thread = await client.threads.create()

async for chunk in client.runs.stream(
    thread["thread_id"], "agent",
    input={"messages": [{"role": "user", "content": "Your question"}]},
    stream_mode="messages",
):
    print(chunk.data, end="", flush=True)

Source: examples/deploy-mcp-docs-agent/README.md:1-40

Security Model

Deep Agents follows a "trust the LLM" model. The agent can perform any action its tools allow. Security boundaries should be enforced at the tool or sandbox level, not by expecting the model to self-police.

# Configure backend with restricted scope
backend = FilesystemBackend(
    root_dir="./workspace",  # Restrict to specific directory
    # ... other security config
)

See the security policy for detailed security guidelines.

Source: README.md:85-95

Known Limitations and Issues

Active Bugs

Community Feature Requests

Source: Community Context

Installation and Setup

# Install via pip
pip install deepagents

# For CLI features
pip install deepagents-cli

# For interactive coding agent
pip install deepagents-code

Dependencies:

• ANTHROPIC_API_KEY or equivalent for your chosen model
• LANGSMITH_API_KEY for production deployments

Source: libs/cli/deepagents_cli/__init__.py:1-35

Quick Start

from deepagents import create_deep_agent

# Create a basic agent
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20251101",
)

# Run it
result = agent.invoke({"messages": [{"role": "user", "content": "Hello!"}]})

For a full quickstart and conceptual overview, see the official documentation.

Source: libs/deepagents/README.md:1-15

Resources

Related Pages

Related topics: Deep Agents Overview, Agent Graph Architecture, Skills System

Quickstart Guide

This guide provides a comprehensive introduction to deepagents, covering installation, core concepts, and practical workflows for building AI-powered agents.

Overview

deepagents is a framework for building deep research agents that combine memory, skills, subagents, and tools to accomplish complex tasks. The framework provides a Python API (create_deep_agent) for defining agents through three filesystem primitives: Memory (AGENTS.md), Skills (skills/*/SKILL.md), and Subagents (subagents.yaml). Source: examples/content-builder-agent/README.md

The agent architecture supports multiple deployment patterns:

• CLI-based interactive agents
• Programmatic agents via Python API
• Deployed services using LangSmith sandbox

Installation

Prerequisites

Using uv (Recommended)

uv run --project examples/content-builder-agent \
  python content_writer.py "Your task here"

Source: examples/content-builder-agent/README.md

Installation Methods

Core Concepts

Agent Architecture

deepagents uses a middleware-based architecture where agents are configured through files on disk rather than code. The agent is configured by files on disk, not code:

agent = create_deep_agent(
    memory=["./AGENTS.md"],                        # ← Middleware loads into system prompt
    skills=["./skills/"],                          # ← Middleware loads on demand
    tools=[generate_cover, generate_social_image], # ← Image generation tools
    subagents=load_subagents("./subagents.yaml"),  # ← See note below
    backend=FilesystemBackend(root_dir="./"),
)

Source: examples/content-builder-agent/README.md:68-76

Three Filesystem Primitives

Memory (AGENTS.md)

Memory files contain persistent context that the agent uses across interactions. These are loaded into the system prompt by MemoryMiddleware.

Example Memory Structure:

# Agent Configuration

## Brand Voice
- Professional but approachable
- Use active voice
- Include concrete examples

## Style Guidelines
- Keep paragraphs under 4 sentences
- Use bullet points for lists

Skills (SKILL.md)

Skills are loaded on demand when triggered by user requests. They use a progressive disclosure design with three levels:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed (scripts, references, assets)

Source: libs/cli/examples/skills/skill-creator/SKILL.md

Skill Directory Structure:

skill-name/
├── SKILL.md           # Main skill definition
├── scripts/           # Executable code (Python/Bash)
├── references/        # Documentation to load on demand
└── assets/            # Files for output (templates, fonts)

Subagents

Subagents are specialized agents spawned via the task tool for parallel or delegated work. Unlike memory and skills, subagents must be defined in code:

subagents=[
    {
        "name": "researcher",
        "description": "Research topics before writing...",
        "model": "anthropic:claude-haiku-4-5-20251001",
        "system_prompt": "You are a research assistant...",
        "tools": [web_search],
    }
]

Source: examples/content-builder-agent/README.md:78-87

Creating Your First Agent

Basic Agent Setup

from deepagents import create_deep_agent
from deepagents import FilesystemBackend

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="./"),
)

Custom Model Configuration

By default, deepagents uses "claude-sonnet-4-5-20250929". Customize using any LangChain model object:

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Using Claude
model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929", temperature=0.0)

# Using Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
model = ChatGoogleGenerativeAI(model="gemini-3-pro-preview")

agent = create_deep_agent(model=model)

Source: examples/deep_research/README.md

Agent with Memory and Skills

agent = create_deep_agent(
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    backend=FilesystemBackend(root_dir="./"),
)

Agent with Tools

from deepagents import create_deep_agent, FilesystemBackend

def generate_cover(topic: str) -> str:
    """Generate a cover image for the topic."""
    # Implementation here
    pass

agent = create_deep_agent(
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    tools=[generate_cover],
    backend=FilesystemBackend(root_dir="./"),
)

Source: examples/content-builder-agent/README.md:68-76

Example Workflows

Content Builder Agent

The Content Builder demonstrates combining all three filesystem primitives for blog posts, LinkedIn posts, and tweets with cover images:

# Set API keys
export ANTHROPIC_API_KEY="..."
export GOOGLE_API_KEY="..."
export TAVILY_API_KEY="..."

# Run
cd examples/content-builder-agent
uv run python content_writer.py "Write a blog post about prompt engineering"

Agent Flow:

1. Agent receives task → loads relevant skill (blog-post or social-media)
2. Delegates research to researcher subagent → saves to research/
3. Writes content following skill workflow → saves to blogs/ or linkedin/
4. Generates cover image with Gemini → saves alongside content

Source: examples/content-builder-agent/README.md

Deep Research Agent

Deep research agent uses custom instructions and web search for comprehensive research:

from examples.deep_research.agent import create_research_agent

agent = create_research_agent(
    model=model,
    tools=[web_search, tavily_search, ReflectTool()],
)

Custom instructions defined in research_agent/prompts.py complement the default middleware instructions:

Source: examples/deep_research/README.md

Script-First Wiki Workflow

The LLM Wiki example demonstrates script-first workflow for maintaining a persistent wiki:

# Ingest new content
uv run --project examples/llm-wiki \
  python examples/llm-wiki/runner.py \
  --mode ingest \
  --repo "ada-lovelace-wiki" \
  --source ./notes/ada.md

# Query the wiki
uv run --project examples/llm-wiki \
  python examples/llm-wiki/runner.py \
  --mode query \
  --repo "ada-lovelace-wiki" \
  --question "What did Ada contribute to computing?"

# Run maintenance
uv run --project examples/llm-wiki \
  python examples/llm-wiki/runner.py \
  --mode lint \
  --repo "ada-lovelace-wiki"

Source: examples/llm-wiki/README.md

Deployment

Deploy Command

Deploy agents using the CLI:

deepagents deploy

The deploy command uses deepagents.toml for configuration:

[sandbox]
type = "langsmith"
image = "python:3.12"

Source: examples/deploy-coding-agent/README.md

Query via SDK

from langgraph_sdk import get_client

client = get_client(url="https://<your-deployment-url>")
thread = await client.threads.create()

async for chunk in client.runs.stream(
    thread["thread_id"], "agent",
    input={"messages": [{"role": "user", "content": "Your task"}]},
    stream_mode="messages",
):
    print(chunk.data, end="", flush=True)

Source: examples/deploy-coding-agent/README.md

Example Catalog

Source: examples/README.md

CLI Commands

Source: libs/cli/examples/skills/skill-creator/SKILL.md

Skill Location Precedence

The deepagents CLI loads skills from four directories (highest precedence wins):

When two directories contain a skill with the same name, the higher-precedence version wins.

Source: libs/cli/examples/skills/skill-creator/SKILL.md

Next Steps

• Explore the Example Catalog for complete implementations
• Learn about Skills for task-specific workflows
• Understand Subagents for parallel processing
• Review deployment options in the Deploy Coding Agent example

Related Pages

Related topics: Middleware System, Filesystem and Sandbox Backend, Subagents System

Agent Graph Architecture

Deep Agents leverages LangGraph's stateful graph execution model as its core runtime. The agent graph architecture defines how the agent processes messages, manages state, invokes tools, delegates to subagents, and handles the middleware pipeline that provides filesystem access, memory, and skills.

Overview

Deep Agents is built as an opinionated harness on top of LangGraph's CompiledStateGraph. The architecture composes three distinct layers:

Source: libs/deepagents/README.md

Core Graph Structure

The agent graph is constructed via create_deep_agent(), which returns a compiled LangGraph graph. The graph defines nodes for agent reasoning, tool execution, and middleware processing.

graph TD
    Input[User Input] --> Messages[Messages State]
    Messages --> Agent[Agent Node]
    Agent --> Decision{Decision?}
    Decision -->|Action| Tools[Tool Execution]
    Tools --> Messages
    Decision -->|Delegate| Subagent[Subagent Node]
    Subagent --> Messages
    Decision -->|Response| Output[Final Response]
    
    subgraph Middleware
        FS[FilesystemMiddleware]
        Mem[MemoryMiddleware]
        Skills[SkillsMiddleware]
    end
    
    Tools --> FS
    Tools --> Mem
    Tools --> Skills

Graph State

The agent maintains state across turns using a structured state object. The primary state components include:

Source: libs/deepagents/deepagents/graph.py

Message Processing Pipeline

Messages flow through a reduction pipeline that normalizes, deduplicates, and summarizes the message history to stay within context window limits.

Messages Reducer

The _messages_reducer.py module handles message normalization and state updates. Key responsibilities include:

• Assigning stable UUIDs to ID-less messages for consistent thread resumption
• Merging message deltas during streaming updates
• Truncating or summarizing older messages when approaching token limits

graph LR
    NewMsg[New Message] --> Normalize[Normalize Message]
    Normalize --> Dedupe[Deduplicate]
    Dedupe --> Summary{Summary Needed?}
    Summary -->|Yes| Summarize[Summarize Old Messages]
    Summary -->|No| Append[Append to State]
    Summarize --> Append
    Append --> State[Updated State]

Source: libs/deepagents/deepagents/_messages_reducer.py

Known Issues

The message reducer has a known issue where read_file pagination can skip lines after wrapping due to double limit application. This affects file reading in long conversations. Source: GitHub Issue #2453

Subagent Architecture

Subagents enable delegation of tasks to specialized, independently-executed agent graphs. The _subagent_transformer.py module handles the transformation of subagent configurations into callable graph nodes.

Subagent Execution Flow

graph TD
    Main[Main Agent] --> Task[Task for Subagent]
    Task --> Transform[Transform to Subagent Graph]
    Transform --> Spawn[Spawn Subagent Thread]
    Spawn --> Execute[Execute with Own Tools]
    Execute --> Return[Return Results]
    Return --> Main
    
    subgraph Subagent State
        Checkpoint[Checkpoint Persistence]
        History[Tool Execution History]
    end
    
    Execute --> Checkpoint
    Execute --> History

Subagent State Management

Subagents run in isolated threads with their own checkpoint persistence. However, there is a known limitation:

Subagents in deepagents do not have checkpoint persistence enabled by default, and when querying state, the tool execution records from subagents are truncated.

Source: GitHub Issue #573

Subagent Configuration

Subagents can be defined in code or loaded from YAML configuration:

editor:
  description: Review and improve drafted content
  model: anthropic:claude-haiku-4-5-20251001
  system_prompt: |
    You are an editor. Review the content and suggest improvements...
  tools: []

Source: libs/cli/examples/skills/skill-creator/SKILL.md

Middleware Pipeline

Middleware components intercept tool calls and agent responses to provide additional capabilities. Deep Agents includes three core middleware types:

FilesystemMiddleware

Provides file system access including read, write, grep, and directory listing operations. This middleware can be configured with backend options:

The .deepagentsignore file can be used to exclude files from agent context, similar to .gitignore patterns used by comparable tools like Claude Code's .claudeignore. Source: GitHub Issue #2143

MemoryMiddleware

Manages persistent context loaded from files like AGENTS.md. In version 0.6+, the add_cache_control=True option was introduced as default, which writes cache control markers on memory blocks.

Known Issue: In deepagents 0.6, add_cache_control=True puts incorrect cache_control markers on volatile memory blocks. This has been reported in issues #3638 and #3639. Source: GitHub Issue #3638

SkillsMiddleware

Implements progressive disclosure for skill loading. Skills are defined as filesystem directories containing a SKILL.md file with YAML frontmatter:

Related Pages

Related topics: Agent Graph Architecture, Filesystem and Sandbox Backend, Memory Middleware, Skills System, Context Summarization

Middleware System

The middleware system in deepagents provides a composable, pluggable architecture for extending agent capabilities. Middleware components intercept and transform the interaction between the agent and its tools, enabling cross-cutting concerns like memory management, skill loading, filesystem access control, and context summarization without polluting core agent logic.

Architecture Overview

Middleware operates as a layered pipeline that processes requests before they reach tools and responses before they return to the agent. Each middleware can inspect, modify, or reject requests, and can attach metadata to responses for downstream middleware consumption.

graph TD
    A[User Input] --> B[Agent Core]
    B --> C[Middleware Pipeline]
    C --> D[FilesystemMiddleware]
    C --> E[MemoryMiddleware]
    C --> F[SkillsMiddleware]
    C --> G[SubagentsMiddleware]
    C --> H[SummarizationMiddleware]
    C --> I[PermissionsMiddleware]
    H --> J[Tools]
    J --> K[Responses]
    K --> H
    H --> L[Modified Response]

Core Middleware Components

FilesystemMiddleware

FilesystemMiddleware provides controlled file system access for agents. It implements read, write, and search operations with built-in support for glob patterns, line-based pagination, and recursive directory traversal.

Key Responsibilities:

• File reading with pagination support
• File writing and directory creation
• Glob-based file discovery
• Grep/search functionality with regex support

Configuration Parameters:

Pagination Behavior:

FilesystemMiddleware implements line-based pagination for large files. The read_file tool accepts line_start and line_end parameters to fetch specific ranges. The middleware handles wrapping when content exceeds display limits.

Known Issue: In deepagents versions prior to 0.6.4, read_file pagination could skip lines after wrapping due to double limit application. This was addressed in the 0.6.4 release. Source: Issue #2453

MemoryMiddleware

MemoryMiddleware manages persistent context across agent sessions by loading and managing memory blocks that provide background information to the agent.

Key Responsibilities:

• Load memory files (AGENTS.md, user preferences) into context
• Manage memory block lifecycle
• Cache control for memory refresh

Configuration Parameters:

Known Issue: In deepagents 0.6.x, add_cache_control=True (the default) places incorrect cache_control markers on volatile memory blocks. This causes memory content to be incorrectly cached when it should be refreshed per session. This was reported in Issues #3638 and #3639.

SkillsMiddleware

SkillsMiddleware enables on-demand loading of task-specific workflows defined in SKILL.md files. Skills support progressive disclosure, allowing detailed instructions to remain available without cluttering the context window until needed.

Key Responsibilities:

• Discover skills from configured directories
• Match user requests to appropriate skills
• Load skill content with progressive disclosure
• Manage skill resources (scripts, references, assets)

Skill Structure:

skill-name/
├── SKILL.md              # Primary skill definition
├── scripts/              # Executable code
├── references/           # Documentation for context loading
└── assets/               # Files for output (templates, fonts, etc.)

Progressive Disclosure Levels:

SubagentsMiddleware

SubagentsMiddleware enables task delegation to specialized sub-agents. Subagents inherit middleware configurations and can operate either synchronously (blocking) or asynchronously (non-blocking).

Key Responsibilities:

• Spawn subagent threads
• Manage subagent lifecycle
• Aggregate subagent results
• Handle async task coordination

Subagent Definition Example:

researcher:
  description: Research topics before writing
  model: anthropic:claude-haiku-4-5-20251001
  system_prompt: |
    You are a research assistant...
  tools: [web_search]

Known Issue: Subagents lack checkpoint persistence and state query truncates tool execution history. This is documented in Issue #573 and should be considered when debugging subagent behavior.

SummarizationMiddleware

SummarizationMiddleware automatically compresses conversation history and tool outputs to manage context window usage. It triggers summarization when token counts exceed configured thresholds.

Key Responsibilities:

• Monitor context window usage
• Trigger summarization when thresholds exceeded
• Preserve critical information in summaries
• Handle multi-modal content (text, images)

Known Issue: In deepagents 0.6.x, SummarizationMiddleware may lose image content during summarization. Images are dropped rather than preserved in summary outputs. See Issue #2873.

PermissionsMiddleware

PermissionsMiddleware enforces access control policies for agent actions. It validates operations against configured permission rules before execution.

Key Responsibilities:

• Define permission policies
• Validate operations against policies
• Block unauthorized actions
• Log permission decisions

Middleware Pipeline Configuration

Middleware components are composed using a pipeline pattern. The order of middleware in the pipeline determines processing precedence.

Pipeline Order

The recommended middleware order balances security, efficiency, and functionality:

graph LR
    A[Input] --> B[Permissions]
    B --> C[Filesystem]
    C --> D[Memory]
    D --> E[Skills]
    E --> F[Subagents]
    F --> G[Summarization]
    G --> H[Tools]

Creating Agents with Middleware

from deepagents import create_deep_agent
from deepagents.middleware import (
    FilesystemMiddleware,
    MemoryMiddleware,
    SkillsMiddleware,
    SubagentsMiddleware,
)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    subagents=load_subagents("./subagents.yaml"),
    backend=FilesystemBackend(root_dir="./"),
)

Source: examples/content-builder-agent/README.md

Middleware Lifecycle Hooks

Each middleware component implements lifecycle hooks that are called at specific points during agent execution:

Context Isolation

Middleware supports context isolation through assistant-scoped configurations. This enables multi-tenant deployments where each user or session maintains separate memory, skills, and state.

# deepagents.assistant-scope.toml
[middleware.memory]
memory = ["/memories/{user_id}/context.md"]

[middleware.filesystem]
root_dir = "/workspace/{user_id}"

Source: examples/deploy-coding-agent/README.md

Best Practices

1. Order middleware correctly: Place PermissionsMiddleware first to enforce security before any operations proceed.

1. Configure ignored patterns: Use .deepagentsignore (when available) or middleware-specific ignore configurations to prevent sensitive directories from being accessed.

1. Monitor summarization thresholds: Configure SummarizationMiddleware thresholds to balance context retention against token costs.

1. Handle async subagents carefully: Async subagents do not inherit checkpoint persistence. Plan for state recovery when using async delegation.

1. Review memory caching settings: When using MemoryMiddleware in multi-session contexts, consider setting add_cache_control=False to ensure fresh context loading.

Related Documentation

• Filesystem Tools
• Memory Management
• Skills System
• Subagents
• Deploy Configuration

Related Pages

Related topics: Middleware System, Memory Middleware

Filesystem and Sandbox Backend

Overview

The Filesystem and Sandbox Backend system in Deep Agents provides two distinct execution environments for agent operations: a local FilesystemBackend for development and a remote SandboxBackend for production deployments. These backends abstract file system operations, process execution, and secure sandboxing, enabling agents to read, write, search, and manipulate files regardless of the underlying execution environment.

The backend architecture follows a protocol-based design that defines a consistent interface for all backend implementations, allowing seamless switching between local and remote execution contexts. This design supports the Deep Agents philosophy of filesystem-primitives-first agent configuration, where agents define their behavior through memory files (AGENTS.md), skills, and tools rather than hard-coded logic.

Architecture

Backend Protocol Hierarchy

The backend system implements a protocol-based abstraction layer that defines the contract for all backend implementations. This allows for multiple backend types while maintaining a consistent API surface for the agent runtime.

graph TD
    A[Agent Runtime] --> B[Backend Protocol Interface]
    B --> C[FilesystemBackend]
    B --> D[SandboxBackend]
    B --> E[Custom Backend Implementations]
    C --> F[Local Filesystem]
    D --> G[Remote Sandbox Environments]
    D --> H[Daytona Partner Integration]
    D --> I[Modal Partner Integration]

Backend Selection by Use Case

Different deployment scenarios require different backend types, with selection based on security requirements, execution environment, and operational needs.

FilesystemBackend

Purpose and Scope

The FilesystemBackend provides direct access to the local filesystem for agent operations. It is designed for development, testing, and scenarios where local file access is required without the overhead of containerization. This backend implements the full backend protocol including file read/write operations, directory traversal, and pattern-based searching.

Core Capabilities

The FilesystemBackend exposes a comprehensive set of file operations that agents use to interact with their working directory. These operations are wrapped with appropriate error handling and permission checks to provide reliable filesystem access.

File reading operations support pagination to handle large files efficiently, with the backend managing line-based slicing and offset tracking. Writing operations preserve file metadata where possible and handle atomic writes to prevent data corruption during concurrent access scenarios.

Directory traversal capabilities include recursive listing, pattern matching with glob expressions, and exclusion logic that respects .gitignore patterns by default. The backend also supports symbolic link resolution and handles edge cases around permission-denied scenarios gracefully.

File Operations API

The filesystem backend implements the following primary operations through the backend protocol:

Configuration

The FilesystemBackend accepts a root_dir parameter that establishes the root directory for all file operations. This parameter constrains the backend to operate within a specific directory tree, preventing accidental access to unrelated filesystem regions.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(root_dir="./project")
agent = create_deep_agent(
    backend=backend,
    # ... other configuration
)

SandboxBackend

Purpose and Scope

The SandboxBackend provides isolated containerized execution for agent operations in production environments. Unlike the FilesystemBackend, the SandboxBackend executes all file operations within a remote container, providing security isolation and consistent execution environments across different host systems.

The sandbox architecture supports multiple provider implementations, including native LangSmith Sandboxes, Daytona partner integration, and Modal partner integration. This multi-provider approach allows deployment flexibility while maintaining a consistent interface for agent operations.

Container Execution Model

Sandbox operations execute within ephemeral containers that are provisioned on-demand and torn down after use. The container lifecycle is managed automatically by the backend, with agents receiving a consistent filesystem view regardless of the underlying container provider.

File operations are forwarded to the container via a command execution protocol, with results streamed back to the agent runtime. This approach allows the sandbox to maintain full isolation while still providing responsive file access for agent operations.

Known Issues

The SandboxBackend has known issues that users should be aware of when deploying agents:

• Issue #3441: SandboxBackend.grep crashes with ValueError when container exec fails. This occurs when the underlying container execution encounters errors during grep operations, particularly in edge cases involving file permission changes mid-operation.
• Issue #3592 (Fixed in 0.6.4): Grep crashing when files vanish mid-walk. This race condition occurred when files were deleted or modified during filesystem traversal operations.

Provider Integrations

#### LangSmith Sandbox

The native LangSmith Sandbox provider is the default sandbox backend for production deployments. It provisions containers using a predefined Python image and provides integrated logging and tracing through LangSmith.

Configuration for LangSmith Sandbox is specified in the deepagents.toml deploy configuration file:

[sandbox]
provider = "langsmith"
image = "python:3.12"

#### Daytona Integration

The Daytona partner integration provides additional sandbox customization options and alternative container management capabilities. Daytona sandboxes are configured through the partner library and expose the same backend protocol interface.

#### Modal Integration

The Modal partner integration offers GPU-accelerated sandbox execution for compute-intensive agent operations. Modal sandboxes can be configured with specific hardware requirements and support longer-running operations than standard container timeouts.

Grep Operations

Grep operations in the SandboxBackend use ripgrep under the hood for efficient pattern matching across large codebases. Recent fixes have addressed several edge cases:

• Glob anchoring: Search patterns are now properly anchored to the search root to prevent unintended matches outside the specified directory scope.
• File vanishing handling: The grep implementation now gracefully handles cases where files are deleted or become inaccessible during the search operation.

Backend Protocol

Protocol Definition

The backend protocol defines the interface that all backend implementations must satisfy. This protocol-based design allows the agent runtime to work with any backend that implements the required methods without knowledge of the specific implementation details.

Required Methods

All backend implementations must provide the following core methods:

Error Handling

Backends implement consistent error handling patterns that translate underlying errors into agent-friendly exceptions. Common error scenarios include file not found, permission denied, timeout exceeded, and container execution failures.

Configuration and Deployment

Deploy Configuration

The CLI bundler (libs/cli/deepagents_cli/deploy/bundler.py) handles backend configuration during deployment. The bundler reads the canonical project layout and prepares the appropriate backend configuration for the target deployment environment.

The deployment configuration file (deepagents.toml) specifies the sandbox settings:

[agent]
model = "anthropic:claude-sonnet-4-5-20250929"

[sandbox]
provider = "langsmith"
image = "python:3.12"
timeout = 3600

Backend Selection in Agents

Agents specify their backend through the backend parameter when creating the agent instance. This allows explicit backend selection for each agent based on its operational requirements.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend, SandboxBackend

# Development configuration
dev_agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="./workspace"),
    memory=["./AGENTS.md"],
)

# Production configuration  
prod_agent = create_deep_agent(
    backend=SandboxBackend(provider="langsmith"),
    memory=["./AGENTS.md"],
)

Ignored Files and Patterns

DeepAgentsIgnore Support

Similar to other coding agents (Claude Code with .claudeignore, Gemini CLI with .geminiignore), Deep Agents supports a .deepagentsignore file that lets users exclude files and directories from the agent's context. This feature addresses community request #2143 and applies to file reads, @ mentions, and filesystem traversal operations.

The .deepagentsignore file uses the same pattern syntax as .gitignore:

# Exclude build artifacts
__pycache__/
*.pyc
dist/

# Exclude dependency directories
node_modules/
venv/

# Exclude sensitive files
.env
*.key
credentials.json

Interaction with Backend Operations

The ignore patterns affect backend operations in the following ways:

Pagination and Line Wrapping

Read File Pagination

The read_file operation supports pagination through offset and limit parameters, allowing agents to read large files in manageable chunks. This is particularly important for agents working with extensive codebases or log files.

Known Bug: Double Limit Application

Issue #2453: read_file pagination skips lines after wrapping due to double limit application. This bug occurs when the pagination logic applies the limit twice, causing the second page of results to skip lines that should have been included.

The issue manifests when reading files that wrap long lines, with subsequent pages missing content that should have been captured in the pagination window. Users experiencing this issue should work around it by using smaller limit values until the fix is available.

Best Practices

Backend Selection Guidelines

• Use FilesystemBackend for local development, testing, and scenarios requiring direct filesystem access
• Use SandboxBackend for production deployments where security isolation is required
• Consider provider-specific features when selecting a sandbox provider (GPU acceleration, custom images, extended timeouts)

Security Considerations

• Always specify a root_dir when using FilesystemBackend to prevent directory traversal attacks
• Use sandbox backends for untrusted code execution
• Review .deepagentsignore patterns to ensure sensitive files are excluded from agent context
• Monitor sandbox logs for unexpected file access patterns

Performance Optimization

• Use pagination for large files to reduce memory consumption
• Configure appropriate timeout values for long-running operations
• Leverage glob patterns in list_files to reduce the number of filesystem calls
• Consider using grep with context lines instead of reading entire files for pattern matching

Summary

The Filesystem and Sandbox Backend system provides Deep Agents with flexible execution environments for file operations. The protocol-based architecture enables seamless switching between local FilesystemBackend and remote SandboxBackend implementations, while partner integrations extend capabilities through Daytona and Modal providers. Understanding backend configuration and aware

ness of known issues helps ensure reliable agent deployments across development and production environments.

Related Pages

Related topics: Middleware System, Quickstart Guide

Skills System

The Skills System extends Deep Agents with specialized knowledge, workflows, and tool integrations through modular, filesystem-based skill definitions. Skills enable agents to load domain-specific instructions and resources on demand, reducing context overhead while providing targeted capabilities for complex tasks.

Overview

Skills are self-contained directories containing a SKILL.md file along with optional bundled resources (scripts/, references/, assets/). Unlike hardcoded instructions, skills are loaded dynamically when triggered by the agent, following a progressive disclosure pattern that keeps the context lean while enabling deep expertise when needed.

Source: libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md

Skill Anatomy

A skill directory contains the following components:

SKILL.md Structure

Every skill requires a SKILL.md file with YAML frontmatter defining metadata:

Related Pages

Related topics: Agent Graph Architecture, Middleware System

Subagents System

Overview

The Subagents System enables Deep Agents to delegate tasks to specialized child agents, allowing for parallel execution, modular task decomposition, and coordinated multi-agent workflows. Subagents operate as independent agent instances with their own model, tools, and system prompts, coordinated by a parent agent.

Subagents are particularly useful for:

• Parallel research tasks: Spawn multiple research agents to investigate different aspects of a topic simultaneously
• Specialized workflows: Delegate to agents optimized for specific domains (e.g., code review, content writing, market research)
• Complex task decomposition: Break large tasks into manageable subtasks handled by dedicated agents
• Scalable architectures: Build multi-agent systems where subagents can run synchronously or asynchronously

Architecture

System Components

graph TD
    Parent[Parent Agent] -->|Coordinates| SubagentManager[Subagent Manager]
    SubagentManager -->|Sync Execution| SyncSubagent[Sync Subagent]
    SubagentManager -->|Async Execution| AsyncSubagent[Async Subagent]
    SubagentManager -->|HTTP/SSE| RemoteSubagent[Remote Subagent Server]
    
    SyncSubagent -->|Results| Parent
    AsyncSubagent -->|Results| Parent
    RemoteSubagent -->|Results| Parent
    
    SyncSubagent -->|Built-in Tools| BuiltInTools[Filesystem, Shell, Grep, etc.]
    SyncSubagent -->|Custom Tools| CustomTools[web_search, etc.]
    
    AsyncSubagent -->|MCP Tools| MCPTools[MCP Server Tools]
    RemoteSubagent -->|External Tools| ExternalTools[External Service]

Subagent Types

Deep Agents supports three types of subagents:

Sync Subagents

Sync subagents execute tasks in a blocking manner, where the parent agent waits for completion before continuing. They are ideal for straightforward task delegation scenarios.

Configuration

Sync subagents can be defined in two ways:

#### Inline Configuration

from deepagents import create_deep_agent

agent = create_deep_agent(
    model=model,
    subagents=[
        {
            "name": "researcher",
            "description": "Research topics before writing...",
            "model": "anthropic:claude-haiku-4-5-20251001",
            "system_prompt": "You are a research assistant. Use web_search to gather information.",
            "tools": [web_search],
        }
    ],
    backend=FilesystemBackend(root_dir="./"),
)

#### YAML Configuration

Create a subagents.yaml file:

researcher:
  description: Research topics before writing content
  model: anthropic:claude-haiku-4-5-20251001
  system_prompt: |
    You are a research assistant. Use web_search to gather information.
    After completing your research, use write_file to save findings.
  tools:
    - web_search

Load subagents from YAML:

from deepagents_cli.deploy.config import load_subagents

subagents = load_subagents("./subagents.yaml")

Built-in Subagent Tools

Sync subagents automatically have access to built-in tools:

Async Subagents

Async subagents execute tasks concurrently, enabling parallel processing of independent subtasks. They are exposed via the Agent Protocol standard.

Architecture

graph LR
    Parent[Parent Agent] -->|Spawns| AsyncSpawner[Async Subagent Spawner]
    AsyncSpawner -->|Concurrent Execution| AsyncAgent1[Async Agent 1]
    AsyncSpawner -->|Concurrent Execution| AsyncAgent2[Async Agent 2]
    AsyncSpawner -->|Concurrent Execution| AsyncAgent3[Async Agent 3]
    
    AsyncAgent1 -->|Status Updates| EventStream[Event Stream]
    AsyncAgent2 -->|Status Updates| EventStream
    AsyncAgent3 -->|Status Updates| EventStream
    
    EventStream -->|Results| Parent

Middleware Integration

from deepagents import create_deep_agent
from deepagents.middleware import AsyncSubagentMiddleware

agent = create_deep_agent(
    model=model,
    middleware=[AsyncSubagentMiddleware()],
    backend=FilesystemBackend(root_dir="./"),
)

Remote Async Subagent Server

Async subagents can be exposed as self-hosted Agent Protocol servers. This enables:

• Independent deployment and scaling
• External access via HTTP/SSE
• Integration with external systems

#### Server Implementation

# examples/async-subagent-server/server.py
from deepagents.middleware.async_subagents import create_async_subagent_app
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(root_dir="./"),
)

app = create_async_subagent_app(
    agent=agent,
    researcher=researcher_subagent,  # Optional predefined subagent
)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8123)

#### Configuration

Subagents can be configured via deepagents.toml for remote deployment:

# examples/deploy-gtm-agent/subagents/market-researcher/deepagents.toml
[agent]
model = "anthropic:claude-haiku-4-5-20251001"
system_prompt = "You are a market research specialist..."

[sandbox]
type = "ssh"
image = "python:3.12"

[tools]
enabled = ["web_search", "read_file"]

Subagent Transformer

The _subagent_transformer.py module handles the compilation and transformation of subagent configurations into executable agent instances.

Key Responsibilities

State Query Limitations

When querying subagent state, tool execution records may be truncated. This is a known limitation when subagents lack checkpoint persistence enabled. See Issue #573 for details.

Usage Patterns

Pattern 1: Parallel Research

graph TD
    User[User Request] --> Parent[Parent Agent]
    Parent -->|Spawn 3| Sub1[Research Topic A]
    Parent -->|Spawn 3| Sub2[Research Topic B]
    Parent -->|Spawn 3| Sub3[Research Topic C]
    
    Sub1 -->|Write findings| File1[findings_a.md]
    Sub2 -->|Write findings| File2[findings_b.md]
    Sub3 -->|Write findings| File3[findings_c.md]
    
    File1 -->|Read all| Parent
    File2 -->|Read all| Parent
    File3 -->|Read all| Parent
    
    Parent -->|Synthesize| FinalReport[Final Report]

Spawn up to 3 subagents in parallel for efficient research:

For each subtopic in your plan:

1. **Use the `task` tool** to spawn a research subagent with:
   - Clear, specific research question (no acronyms)
   - Instructions to write findings to a file
   - Budget: 3-5 web searches maximum

Pattern 2: Sequential Delegation

graph LR
    Task1[Task 1] -->|Delegate| Subagent1[Subagent]
    Subagent1 -->|Complete| Task2[Task 2]
    Task2 -->|Delegate| Subagent2[Subagent]
    Subagent2 -->|Complete| Task3[Task 3]

Pattern 3: Coordinated Workflow

# From examples/deploy-gtm-agent
agent = create_deep_agent(
    model=model,
    subagents=[
        {
            "name": "market-researcher",
            "description": "Research market trends and competitors",
            "model": "anthropic:claude-haiku-4-5-20251001",
            "system_prompt": "You are a market research specialist...",
            "tools": [web_search, read_file, write_file],
        },
        {
            "name": "content-writer",
            "description": "Write GTM content based on research",
            "model": "anthropic:claude-haiku-4-5-20251001",
            "system_prompt": "You are a GTM content writer...",
            "tools": [write_file],
        },
    ],
)

Configuration Reference

Subagent Definition Schema

Task Tool Parameters

Known Issues

Checkpoint Persistence (Issue #573)

Subagents currently lack checkpoint persistence enabled. When querying state, tool execution records from subagents may be truncated. This is inconsistent with the parent agent's behavior and may affect debugging and state inspection.

Workaround: Implement custom checkpointing within subagent tools if state inspection is critical.

Best Practices

Do

• Use clear, specific task descriptions: Avoid acronyms and ambiguous instructions
• Set resource budgets: Limit web searches or tool calls to prevent runaway subagents
• Write results to files: Have subagents save findings to files for reliable result aggregation
• Use parallel execution: Spawn 2-3 subagents concurrently for independent research tasks
• Define tool restrictions: Limit subagent tools to only those needed for their specific task

Don't

• Over-delegate: Avoid spawning too many subagents simultaneously (diminishing returns)
• Leave subagent scope vague: Always provide specific research questions or tasks
• Assume shared state: Subagents operate independently; pass necessary context explicitly
• Skip result aggregation: Always read and synthesize subagent outputs in the parent

Examples

Related Documentation

• Skills System - Workflow-based task execution
• Memory System - Persistent context management
• Middleware - Extensibility architecture
• Deploy - Deploying multi-agent systems

Related Pages

Related topics: Middleware System, Context Summarization

Memory Middleware

Memory Middleware is a core component of Deep Agents that manages persistent context across agent conversations. It enables agents to maintain awareness of long-running instructions, user preferences, and conversational state without repeatedly re-injecting this information.

Overview

Memory Middleware handles the loading and management of memory files that provide persistent context to the agent. This context includes system-level instructions defined in AGENTS.md, user-specific preferences, and conversation history that survives across sessions.

The middleware integrates with the agent's system prompt at initialization and can be configured to add cache control markers for content optimization.

Architecture

graph TD
    A[Agent Initialization] --> B[MemoryMiddleware]
    B --> C[Load Memory Files]
    C --> D[AGENTS.md - System Instructions]
    C --> E[User Memory - Per-user Preferences]
    C --> F[Skill Memory - Bundled Skills]
    
    B --> G[add_cache_control Option]
    G -->|True| H[Add Cache Control Markers]
    G -->|False| I[Standard Memory Loading]
    
    H --> J[Append to System Prompt]
    I --> J

Configuration

Basic Configuration

Memory is configured at agent creation using the memory parameter:

from deepagents import create_deep_agent

agent = create_deep_agent(
    memory=["./AGENTS.md"],  # Memory file paths
    tools=[...],
)

Advanced Configuration Options

Cache Control Behavior

Known Issue: In version 0.6, the add_cache_control=True default introduces a bug where incorrect cache control markers are written to volatile memory blocks. This affects the in-context AGENTS.md content. See Issue #3638 and Issue #3639 for details.

To disable cache control markers:

from deepagents.middleware.memory import MemoryMiddleware

middleware = MemoryMiddleware(
    add_cache_control=False  # Disable cache control markers
)

Memory Sources

System Memory (AGENTS.md)

The primary memory source is the AGENTS.md file located at the project root. This file contains:

• Agent identity and role definitions
• Behavioral guidelines and constraints
• Default tool behaviors
• Style and tone preferences

Source: examples/content-builder-agent/README.md

Per-User Memory

For multi-user deployments, each user can have isolated memory files. The middleware supports per-user memory scoping through authentication providers.

# Per-user memory structure
# /memories/user/
#   preferences.md  - User's preferences and settings
#   context.md      - User's static context (company, product, etc.)

Source: examples/deploy-content-writer/README.md

Per-User Memory with Supabase Auth

When deploying with Supabase authentication, memory files are automatically scoped by user identity:

# deepagents.toml
[auth]
provider = "supabase"

This configuration automatically generates a token validator that scopes memory to the authenticated user's identity without custom code.

Source: examples/deploy-content-writer/README.md

Project Structure

The memory middleware reads from the following canonical project layout:

<project>/
├── deepagents.toml     # Agent and sandbox configuration
├── AGENTS.md           # System prompt and seeded memory (required)
├── .env                # Environment variables (optional)
├── mcp.json            # MCP server configuration (optional)
├── skills/             # Auto-seeded skills (optional)
│   └── <skill>/
│       └── SKILL.md
└── user/               # Per-user writable memory (optional)
    └── AGENTS.md       # Seeded per-user memory

Source: libs/cli/deepagents_cli/deploy/bundler.py

Memory Lifecycle

sequenceDiagram
    participant User
    participant Agent
    participant MemoryMiddleware
    participant StoreBackend
    
    User->>Agent: Create agent with memory config
    Agent->>MemoryMiddleware: Initialize middleware
    MemoryMiddleware->>StoreBackend: Load memory files
    StoreBackend-->>MemoryMiddleware: Return memory content
    MemoryMiddleware->>MemoryMiddleware: Process with cache control
    MemoryMiddleware-->>Agent: Append to system prompt
    
    User->>Agent: Send message
    Agent->>MemoryMiddleware: Access memory context
    MemoryMiddleware-->>Agent: Include memory in context

Backend Integration

Memory Middleware uses the StoreBackend interface for persistence. The default backend is FilesystemBackend, which reads memory files from the local filesystem.

Custom Backend Configuration

from deepagents import create_deep_agent
from deepagents.backends.store import StoreBackend

class CustomMemoryBackend(StoreBackend):
    async def read(self, path: str) -> bytes:
        # Custom implementation
        pass

agent = create_deep_agent(
    memory_backend=CustomMemoryBackend(),
    memory=[...],
)

Source: libs/deepagents/deepagents/backends/store.py

Known Issues and Limitations

Cache Control Marker Bug (v0.6)

Issue: Issue #3638, Issue #3639

Deep Agents 0.6 introduced add_cache_control=True as the default when constructing MemoryMiddleware. This causes the middleware to write a cache_control marker on appended memory blocks, which can interfere with volatile memory blocks.

Workaround: Set add_cache_control=False when creating the middleware:

middleware = MemoryMiddleware(add_cache_control=False)

Memory File Size Limits

Large memory files can impact token usage and performance. Best practices include:

• Keep AGENTS.md files under 5,000 lines
• Use skill references for detailed documentation
• Split large documentation into separate files that are read on-demand

Source: libs/cli/examples/skills/skill-creator/SKILL.md

Best Practices

1. Modular Memory Organization: Separate static context from frequently changing preferences
2. Use Per-User Memory for Multi-Tenant Deployments: Isolate user data through authentication
3. Cache Control Management: Consider disabling add_cache_control when working with volatile memory
4. Skill-Based Documentation: Move detailed reference material to skill files rather than main memory
5. Context Efficiency: Load only essential memory at startup; defer detailed context to skills

Related Components

Version History

Related Pages

Related topics: Memory Middleware, Middleware System

Context Summarization

Context Summarization is a critical middleware system in Deep Agents that automatically manages the conversation context window by condensing, evicting, or clipping messages when they exceed configured thresholds. This system ensures that agents remain efficient and responsive even during long-running conversations or when processing large amounts of information.

Overview

Deep Agents uses a sophisticated context management strategy that operates through multiple middleware layers. When the conversation context grows too large, the system employs summarization techniques to preserve important information while reducing token usage. The context summarization system works in conjunction with memory management and overflow handling to maintain an optimal context state.

The architecture consists of three primary components that handle different aspects of context reduction:

1. Summarization - Condenses messages into concise summaries using an LLM
2. Message Eviction - Removes older, less relevant messages from context
3. Overflow Clipping - Truncates context when it exceeds hard limits

This layered approach ensures that context remains manageable without losing critical information, supporting long-running agent sessions and complex multi-step workflows.

Architecture

The context summarization system integrates with Deep Agents' middleware pipeline, allowing it to intercept and transform messages before they reach the agent's core reasoning engine.

graph TD
    A[User Messages] --> B[Middleware Pipeline]
    B --> C[MemoryMiddleware]
    C --> D[SummarizationMiddleware]
    D --> E[OverflowClipMiddleware]
    E --> F[MessageEvictionMiddleware]
    F --> G[Agent Core]
    G --> H[Response Generation]
    
    D -.->|Condense when threshold exceeded| I[Summarizer]
    F -.->|Remove old messages| J[Eviction Strategy]
    E -.->|Hard limit enforcement| K[Token Budget]

Middleware Integration

The summarization middleware sits within the broader middleware architecture, interacting with other context management components. It receives messages after initial processing by memory middleware and before overflow clipping occurs.

The middleware pipeline processes messages in a specific order, with each component handling a distinct responsibility. Summarization specifically focuses on reducing the verbosity of existing messages rather than removing them entirely.

Summarization Middleware

The SummarizationMiddleware class implements the core summarization logic, providing configurable thresholds and summarization prompts that control when and how messages are condensed.

Configuration Options

Summarization Flow

When the message count or token count exceeds the configured threshold, the middleware invokes the summarization process:

1. Identify messages eligible for summarization
2. Generate a condensed summary of selected messages
3. Replace original messages with the summary
4. Preserve critical metadata and tool results

sequenceDiagram
    participant U as User
    participant M as Middleware
    participant S as Summarizer
    participant A as Agent
    
    U->>M: Message Stream
    M->>M: Check Threshold
    alt Threshold Exceeded
        M->>S: Request Summary
        S->>S: Generate Condensed Summary
        S-->>M: Summary Content
        M->>M: Replace Messages with Summary
    end
    M->>A: Processed Messages
    A-->>U: Response

Message Eviction

The _message_eviction.py module implements strategies for removing messages from context based on relevance, recency, and importance scoring.

Eviction Strategies

Eviction Rules

Message eviction follows a set of protected rules that prevent critical messages from being removed:

• System messages are always preserved
• Tool execution results may be selectively preserved
• User messages with explicit flags are protected
• Summarized content is retained until further condensed

Overflow Clipping

The _overflow_clip.py module provides hard-limit enforcement for context size, ensuring that the total context never exceeds the model's maximum token limit.

Clip Behavior

When context exceeds the maximum allowed size:

1. The system calculates the excess token count
2. Messages are removed from oldest to newest
3. At least one user message and the system prompt are preserved
4. A truncation notice may be added to indicate incomplete context

# Pseudocode representation of overflow handling
if total_tokens > max_tokens:
    excess = total_tokens - max_tokens
    messages = prune_oldest(messages, excess)
    ensure_system_preserved(messages)
    ensure_user_intent_preserved(messages)

Known Limitations

As documented in community issue #2453, there is a known issue with read_file pagination where double limit application can cause lines to be skipped after wrapping. This affects file content that exceeds pagination boundaries.

Memory Integration

Context summarization integrates with MemoryMiddleware to provide persistent context management alongside dynamic summarization.

Cache Control

The memory middleware supports add_cache_control functionality (enabled by default in v0.6) that adds cache control markers to memory blocks. This helps the summarization system identify which content can be safely condensed versus which must be preserved.

Memory Block Handling

Memory blocks are treated with special priority in the summarization pipeline:

• Core agent instructions (AGENTS.md) are never summarized
• User-defined memory files may be summarized selectively
• Volatile memory blocks use different retention policies than durable memory

Summarizer Core

The core/summarizer.py module provides the underlying LLM-based summarization functionality used by the middleware components.

Summary Generation

The summarizer uses a dedicated LLM call to generate concise summaries of conversation history. The generated summaries maintain key information while significantly reducing token count.

Summary Quality

Key factors affecting summary quality:

Usage Examples

Basic Configuration

from deepagents import create_deep_agent
from deepagents.middleware import SummarizationMiddleware

agent = create_deep_agent(
    middleware=[
        SummarizationMiddleware(
            threshold=1500,
            max_messages=30
        )
    ]
)

Custom Summarization Prompt

from deepagents.middleware import SummarizationMiddleware

custom_middleware = SummarizationMiddleware(
    threshold=2000,
    prompt="Summarize the conversation, preserving: "
           "1. Key decisions made, "
           "2. Important facts established, "
           "3. Current task goals and progress"
)

Disabling Summarization

For applications requiring full context preservation:

agent = create_deep_agent(
    middleware=[
        SummarizationMiddleware(enabled=False)
    ]
)

Best Practices

Threshold Selection

Monitoring Context Health

Track these metrics to optimize summarization:

• Average messages per session
• Token usage trends over time
• Summary quality assessments
• Task completion rates with summarization enabled

Avoiding Common Issues

1. Image Loss in Summaries: Be aware that summarization may lose image content (see issue #2873)
2. Volatile Memory Markers: Verify correct cache_control markers on memory blocks (see issues #3638, #3639)
3. Double Limit Application: When using pagination, ensure limits are applied only once (see issue #2453)

Troubleshooting

Summarization Not Triggering

If messages are not being summarized when expected:

1. Verify enabled=True in middleware configuration
2. Check that token counting is accurate for your model
3. Ensure threshold is set below actual message size
4. Review logs for summarization errors

Poor Summary Quality

If summaries are losing important information:

1. Customize the summarization prompt
2. Increase the threshold to reduce compression
3. Add explicit markers to preserve critical content
4. Consider using importance-based eviction instead

Context Still Overflowing

If context exceeds limits despite summarization:

1. Reduce the threshold value
2. Enable additional eviction strategies
3. Check for messages bypassing middleware
4. Verify overflow clipping is properly configured

Related Components

Version History

See Also

• Memory Management - Persistent context configuration
• Middleware System - Pipeline architecture overview
• Context Management - Overall context strategy
• Tool Integration - How tools interact with context

MCP (Model Context Protocol) integration in Deep Agents enables agents to discover and use external tools provided by MCP servers. This allows agents to extend their capabilities beyond built-in tools by connecting to specialized services like documentation APIs, databases, and external tool providers.

Overview

MCP integration in Deep Agents provides a standardized way for agents to:

• Discover available MCP servers and their exposed tools
• Execute tools on MCP servers directly from agent workflows
• Manage MCP server connections and authentication
• Configure MCP servers via declarative mcp.json files

Source: libs/code/deepagents_code/mcp_providers/__init__.py

Architecture

graph TD
    A[Agent] --> B[MCP Middleware]
    B --> C[MCP Providers]
    C --> D[MCP Servers]
    D --> E[External Services]
    
    F[mcp.json] --> B
    G[MCP Auth] --> C
    
    H[CLI: /mcp command] --> B

The MCP integration consists of several interconnected components that work together to provide seamless external tool discovery and execution.

Source: libs/code/deepagents_code/mcp_tools.py

MCP Configuration

mcp.json Structure

The mcp.json file defines MCP server connections for an agent. It follows a declarative configuration format:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@server/package"],
      "env": {
        "API_KEY": "${API_KEY}"
      },
      "headers": {
        "Authorization": "Bearer ${AUTH_TOKEN}"
      }
    }
  }
}

Configuration supports environment variable expansion using ${VAR} syntax, allowing sensitive credentials to be injected at runtime.

Source: libs/cli/deepagents_cli/deploy/config.py

Configuration Parameters

Environment variables can reference ${VAR} patterns that are expanded at runtime from the host environment.

Source: libs/cli/deepagents_cli/deploy/bundler.py

MCP Providers

MCP providers manage the lifecycle of MCP server connections and tool discovery.

class MCPProvider:
    """Manages MCP server connections and tool discovery."""
    
    async def list_tools(self) -> list[MCPTool]:
        """Discover all tools available from connected MCP servers."""
        
    async def execute_tool(self, tool_name: str, arguments: dict) -> Any:
        """Execute a tool on the appropriate MCP server."""

Source: libs/code/deepagents_code/mcp_providers/__init__.py

Tool Discovery Flow

sequenceDiagram
    participant Agent
    participant Middleware
    participant Provider
    participant Server
    
    Agent->>Middleware: Request tools
    Middleware->>Provider: List available tools
    Provider->>Server: ListTools request
    Server-->>Provider: Tool definitions
    Provider-->>Middleware: Tool list
    Middleware-->>Agent: Available tools
    
    Agent->>Middleware: Execute tool
    Middleware->>Provider: Call tool
    Provider->>Server: Execute request
    Server-->>Provider: Result
    Provider-->>Middleware: Tool result
    Middleware-->>Agent: Response

Source: libs/code/deepagents_code/mcp_tools.py

MCP Authentication

The authentication system handles credential management for MCP servers that require authentication.

class MCPAuthService:
    """Handles authentication for MCP server connections."""
    
    def get_credentials(self, server_id: str) -> Credentials:
        """Retrieve credentials for a specific MCP server."""
        
    def refresh_credentials(self, server_id: str) -> Credentials:
        """Refresh expired credentials for a server."""

Source: libs/code/deepagents_code/mcp_auth.py

Login Service

The MCP login service provides OAuth and token-based authentication flows for MCP servers:

class MCPLoginService:
    """Manages user authentication for MCP servers."""
    
    async def authenticate(self, server_id: str, credentials: dict) -> bool:
        """Authenticate user and store credentials."""
        
    async def logout(self, server_id: str) -> None:
        """Remove stored credentials for a server."""

Source: libs/code/deepagents_code/mcp_login_service.py

CLI Commands

The Deep Agents CLI provides several commands for managing MCP integrations:

The /mcp command also surfaces deferred reconnect state, allowing users to monitor the health of MCP connections and identify servers that need attention.

Source: libs/code/deepagents_code/mcp_commands.py

Viewing MCP Status

/mcp

This command displays:

• Connected MCP servers
• Available tools from each server
• Connection health status
• Deferred reconnect states

Source: libs/code/deepagents_code/mcp_commands.py

Deployment Integration

When deploying an agent with MCP servers, the bundler packages the mcp.json configuration and handles subagent MCP configurations:

def _build_subagent_seed(subagent: SubAgentProject) -> dict:
    """Build the seed entry for a single sync subagent."""
    sa_root = subagent.root
    mcp_path = sa_root / MCP_FILENAME
    mcp = None
    if mcp_path.is_file():
        mcp = json.loads(mcp_path.read_text(encoding="utf-8"))
    return {"mcp": mcp, ...}

Source: libs/cli/deepagents_cli/deploy/bundler.py

Deploying with MCP

1. Create an mcp.json file in the agent directory
2. Define server configurations with appropriate authentication
3. Run deepagents deploy to package and deploy
4. The deployed agent automatically connects to configured MCP servers

Example: MCP Docs Agent

The repository includes a deployable MCP documentation agent that searches LangChain documentation:

{
  "mcpServers": {
    "langchain-docs": {
      "url": "https://docs.langchain.com/mcp"
    }
  }
}

This agent configuration uses the official LangChain MCP server to provide real-time documentation search capabilities.

Source: examples/deploy-mcp-docs-agent/README.md

Best Practices

Configuration Management

• Use environment variables for sensitive credentials
• Test MCP configurations locally before deployment
• Keep mcp.json in version control for reproducible deployments

Tool Selection

• Configure MCP servers with specific tool scopes rather than broad access
• Document which MCP servers and tools each agent uses
• Monitor MCP server health and connection status

Security

• Store credentials securely using environment variables or secrets management
• Review MCP server permissions before adding to agent configuration
• Use headers with minimal required authentication scopes

Troubleshooting

Common Issues

Debug Mode

Enable verbose logging to diagnose MCP connection issues:

import logging
logging.getLogger("deepagents.mcp").setLevel(logging.DEBUG)

Related Documentation

• Deep Agents Overview
• Deploy Documentation
• LangGraph SDK Docs

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_835108c2241d479e882292911a15ba40 | https://github.com/langchain-ai/deepagents/issues/3547

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_c1040f878b164a949793ba929d2d6463 | https://github.com/langchain-ai/deepagents/issues/3657

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_5caff99ca831421092eb3042c17156a0 | https://github.com/langchain-ai/deepagents/issues/1877

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using deepagents with real data or production workflows.

• Add RemoteBackend as a backend alternative - github / github_issue
• feat(sdk): add regex support to the grep tool - github / github_issue
• Filter by agent in /threads - github / github_issue
• FilesystemMiddleware's _handle_read_result ignores `read_result.file - github / github_issue
• .deepagentsignore - github / github_issue
• read_file pagination skips lines after wrapping due to double limit ap - github / github_issue
• Summarization middleware image loss - github / github_issue
• MemoryMiddleware: add_cache_control=True (0.6) puts incorrect cache_cont - github / github_issue
• Capability evidence risk requires verification - GitHub / issue