# https://github.com/langchain-ai/deepagents Project Manual
Generated at: 2026-05-31 04:30:53 UTC
## Table of Contents
- [Deep Agents Overview](#overview)
- [Quickstart Guide](#quickstart)
- [Agent Graph Architecture](#agent-graph)
- [Middleware System](#middleware)
- [Filesystem and Sandbox Backend](#filesystem-backend)
- [Skills System](#skills-system)
- [Subagents System](#subagents)
- [Memory Middleware](#memory-middleware)
- [Context Summarization](#summarization)
- [MCP (Model Context Protocol) Integration](#mcp-integration)
## Deep Agents Overview
### Related Pages
Related topics: [Quickstart Guide](#quickstart), [Agent Graph Architecture](#agent-graph)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/langchain-ai/deepagents/blob/main/README.md)
- [examples/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/README.md)
- [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md)
- [examples/text-to-sql-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/text-to-sql-agent/README.md)
- [examples/deploy-coding-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/README.md)
- [examples/deep_research/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deep_research/README.md)
- [examples/llm-wiki/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/llm-wiki/README.md)
- [examples/deploy-mcp-docs-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-mcp-docs-agent/README.md)
- [libs/deepagents/README.md](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/README.md)
- [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
- [libs/cli/examples/skills/web-research/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/web-research/SKILL.md)
- [libs/cli/deepagents_cli/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/__init__.py)
# 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.
```mermaid
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
| Layer | Description | Use When |
|-------|-------------|----------|
| **LangGraph** | Graph runtime for custom orchestration | The agent loop itself isn't the right shape |
| **LangChain `create_agent`** | Minimal agent harness | You want a lighter harness without bundled middleware |
| **Deep Agents** | Full harness with context management | You want planning, filesystem, subagents, and skills out of the box |
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:
```python
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.
```python
agent = create_deep_agent(
memory=["./AGENTS.md"], # Middleware loads into system prompt
# ... other config
)
```
**Key Configuration Options:**
| Parameter | Description | Default |
|-----------|-------------|---------|
| `memory` | List of memory sources (files, configs) | `[]` |
| `add_cache_control` | Enable cache control markers on memory blocks | `True` (v0.6+) |
**Known Issues:**
- In deepagents 0.6, `add_cache_control=True` may put incorrect `cache_control` markers on volatile memory blocks. See [Issue #3639](https://github.com/langchain-ai/deepagents/issues/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:
```mermaid
graph LR
A[Metadata
100 words] --> B[SKILL.md Body
<5k words]
B --> C[Bundled Resources
Unlimited]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
```
#### Skill Loading Levels
| Level | Content | Context Cost | Trigger |
|-------|---------|--------------|----------|
| 1 | Name + description | ~100 words | Always in context |
| 2 | SKILL.md body | <5k words | When skill triggers |
| 3 | Bundled resources (scripts, references, assets) | 0 (executed, not read) | As needed |
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):
| Priority | Directory | Scope |
|----------|-----------|-------|
| 1 | `~/.deepagents//skills/` | User (agent-specific) |
| 2 | `~/.agents/skills/` | User (shared) |
| 3 | `.deepagents/skills/` | Project |
| 4 | `.agents/skills/` | Project (shared) |
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.
```python
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:**
```mermaid
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](https://github.com/langchain-ai/deepagents/issues/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](https://github.com/langchain-ai/deepagents/issues/2453).
- `SandboxBackend.grep` crashes with `ValueError` when container exec fails. See [Issue #3441](https://github.com/langchain-ai/deepagents/issues/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:
| Tool | Purpose |
|------|---------|
| `read_file` | Read file contents with pagination |
| `write_file` | Create or update files |
| `grep` | Search file contents using ripgrep patterns |
| `glob` | Find files matching glob patterns |
| `bash` / `shell` | Execute shell commands |
| `task` | Spawn subagent tasks |
| `write_todos` | Planning and task tracking |
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`.
```python
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.
```python
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.
```python
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.
```bash
# 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:
| Category | Examples |
|----------|----------|
| **Frontier APIs** | OpenAI (GPT-4, GPT-5), Anthropic (Claude), Google (Gemini) |
| **Open-weight** | Models hosted on Baseten, Fireworks |
| **Self-hosted** | Ollama, vLLM, llama.cpp |
Use any [LangChain chat model](https://docs.langchain.com/oss/python/langchain/models) by specifying the model identifier:
```python
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
| Method | Description |
|--------|-------------|
| `deepagents deploy` | CLI deployment to LangSmith |
| LangGraph SDK | Programmatic deployment via `langgraph_sdk` |
| Custom | Embed in any Python application |
Source: [README.md:60-80]()
### Deploy via SDK Example
```python
from langgraph_sdk import get_client
client = get_client(url="https://")
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.
```python
# Configure backend with restricted scope
backend = FilesystemBackend(
root_dir="./workspace", # Restrict to specific directory
# ... other security config
)
```
See the [security policy](https://github.com/langchain-ai/deepagents?tab=security-ov-file) for detailed security guidelines.
Source: [README.md:85-95]()
## Known Limitations and Issues
### Active Bugs
| Issue | Description | Severity |
|-------|-------------|----------|
| [#2453](https://github.com/langchain-ai/deepagents/issues/2453) | `read_file` pagination skips lines due to double limit application | Medium |
| [#3639](https://github.com/langchain-ai/deepagents/issues/3639) | `add_cache_control=True` puts incorrect cache_control markers | Medium |
| [#3441](https://github.com/langchain-ai/deepagents/issues/3441) | `SandboxBackend.grep` crashes with `ValueError` on container exec failure | Medium |
| [#573](https://github.com/langchain-ai/deepagents/issues/573) | Subagents lack checkpoint persistence and state query truncates tool execution history | High |
### Community Feature Requests
| Issue | Description | Interest |
|-------|-------------|----------|
| [#506](https://github.com/langchain-ai/deepagents/issues/506) | Use skills in custom agent (non-CLI version) | 4 comments |
| [#180](https://github.com/langchain-ai/deepagents/issues/180) | Support agent skills natively | 5 comments |
| [#297](https://github.com/langchain-ai/deepagents/issues/297) | AG-UI integration/demo | 5 comments |
| [#2630](https://github.com/langchain-ai/deepagents/issues/2630) | Provider-native file uploads in `FilesystemMiddleware` | 0 comments |
Source: [Community Context](https://github.com/langchain-ai/deepagents/issues)
## Installation and Setup
```bash
# 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
```python
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](https://docs.langchain.com/oss/python/deepagents/overview).
Source: [libs/deepagents/README.md:1-15]()
## Resources
| Resource | URL |
|----------|-----|
| Documentation | https://docs.langchain.com/oss/python/deepagents/overview |
| API Reference | https://reference.langchain.com/python/deepagents/ |
| Community Forum | https://forum.langchain.com/c/oss-product-help-lc-and-lg/deep-agents/18 |
| Contributing Guide | https://docs.langchain.com/oss/python/contributing/overview |
| Examples | https://github.com/langchain-ai/deepagents/tree/main/examples |
---
## Quickstart Guide
### Related Pages
Related topics: [Deep Agents Overview](#overview), [Agent Graph Architecture](#agent-graph), [Skills System](#skills-system)
Related Source Files
The following source files were used to generate this page:
- [examples/deep_research/agent.py](https://github.com/langchain-ai/deepagents/blob/main/examples/deep_research/agent.py)
- [examples/content-builder-agent/content_writer.py](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/content_writer.py)
- [examples/deep_research/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deep_research/README.md)
- [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md)
- [examples/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/README.md)
- [examples/deploy-coding-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/README.md)
- [examples/llm-wiki/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/llm-wiki/README.md)
- [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
# 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](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
| Requirement | Description |
|-------------|-------------|
| Python | 3.11+ |
| API Key | `ANTHROPIC_API_KEY` for Claude models |
| Optional | `LANGSMITH_API_KEY` for deployment and sandbox features |
### Using uv (Recommended)
```bash
uv run --project examples/content-builder-agent \
python content_writer.py "Your task here"
```
Source: [examples/content-builder-agent/README.md](examples/content-builder-agent/README.md)
### Installation Methods
| Method | Command |
|--------|---------|
| Package install | `pip install deepagents` |
| CLI install | `pip install deepagents-cli` |
| Development | Clone repo and install from source |
## 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:
```python
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](examples/content-builder-agent/README.md)
### Three Filesystem Primitives
| Primitive | Location | Purpose | Loading |
|-----------|----------|---------|---------|
| **Memory** | `AGENTS.md` | Persistent context like brand voice and style guidelines | Always in system prompt |
| **Skills** | `skills/*/SKILL.md` | Workflows for specific tasks | Loaded on demand |
| **Subagents** | `subagents.yaml` | Specialized agents for delegated tasks | Spawned via `task` tool |
### 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:**
```markdown
# 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](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:
```python
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](examples/content-builder-agent/README.md)
## Creating Your First Agent
### Basic Agent Setup
```python
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:
```python
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](examples/deep_research/README.md)
### Agent with Memory and Skills
```python
agent = create_deep_agent(
memory=["./AGENTS.md"],
skills=["./skills/"],
backend=FilesystemBackend(root_dir="./"),
)
```
### Agent with Tools
```python
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](examples/content-builder-agent/README.md)
## Example Workflows
### Content Builder Agent
The Content Builder demonstrates combining all three filesystem primitives for blog posts, LinkedIn posts, and tweets with cover images:
```bash
# 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](examples/content-builder-agent/README.md)
### Deep Research Agent
Deep research agent uses custom instructions and web search for comprehensive research:
```python
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:
| Instruction Set | Purpose |
|-----------------|---------|
| Custom prompts | Domain-specific guidance |
| Middleware instructions | Default tool usage patterns |
| SKILL.md files | Task-specific workflows |
Source: [examples/deep_research/README.md](examples/deep_research/README.md)
### Script-First Wiki Workflow
The LLM Wiki example demonstrates script-first workflow for maintaining a persistent wiki:
```bash
# 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](examples/llm-wiki/README.md)
## Deployment
### Deploy Command
Deploy agents using the CLI:
```bash
deepagents deploy
```
The deploy command uses `deepagents.toml` for configuration:
```toml
[sandbox]
type = "langsmith"
image = "python:3.12"
```
Source: [examples/deploy-coding-agent/README.md](examples/deploy-coding-agent/README.md)
### Query via SDK
```python
from langgraph_sdk import get_client
client = get_client(url="https://")
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](examples/deploy-coding-agent/README.md)
## Example Catalog
| Category | Example | Description |
|----------|---------|-------------|
| Research | [deep_research](examples/deep_research/) | Web research with Tavily, parallel sub-agents, and strategic reflection |
| Research | [deploy-mcp-docs-agent](examples/deploy-mcp-docs-agent/) | Docs research agent using MCP tools |
| Coding | [deploy-coding-agent](examples/deploy-coding-agent/) | Autonomous coding agent in LangSmith sandbox |
| Content | [content-builder-agent](examples/content-builder-agent/) | Blog posts with memory, skills, and subagents |
| Content | [text-to-sql-agent](examples/text-to-sql-agent/) | Natural language to SQL with planning |
| Deployable | [deploy-content-writer](examples/deploy-content-writer/) | Content writer with per-user memory |
| Deployable | [deploy-gtm-agent](examples/deploy-gtm-agent/) | GTM strategy with sync/async subagents |
Source: [examples/README.md](examples/README.md)
## CLI Commands
| Command | Description |
|---------|-------------|
| `deepagents deploy` | Deploy agent to LangSmith |
| `deepagents skills create` | Create a new skill |
| `deepagents skills create --project` | Create skill in project directory |
| `deepagents mcp config` | Configure MCP servers |
Source: [libs/cli/examples/skills/skill-creator/SKILL.md](libs/cli/examples/skills/skill-creator/SKILL.md)
## Skill Location Precedence
The deepagents CLI loads skills from four directories (highest precedence wins):
| Priority | Directory | Scope |
|----------|-----------|-------|
| 1 | `~/.deepagents//skills/` | User (deepagents alias) |
| 2 | `~/.agents/skills/` | User |
| 3 | `.deepagents/skills/` | Project (deepagents alias) |
| 4 | `.agents/skills/` | Project |
When two directories contain a skill with the same name, the higher-precedence version wins.
Source: [libs/cli/examples/skills/skill-creator/SKILL.md](libs/cli/examples/skills/skill-creator/SKILL.md)
## Next Steps
- Explore the [Example Catalog](#example-catalog) for complete implementations
- Learn about [Skills](#skills-skillmd) for task-specific workflows
- Understand [Subagents](#subagents) for parallel processing
- Review deployment options in the [Deploy Coding Agent](examples/deploy-coding-agent/) example
---
## Agent Graph Architecture
### Related Pages
Related topics: [Middleware System](#middleware), [Filesystem and Sandbox Backend](#filesystem-backend), [Subagents System](#subagents)
Related Source Files
The following source files were used to generate this page:
- [libs/deepagents/deepagents/graph.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py)
- [libs/deepagents/deepagents/_messages_reducer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_messages_reducer.py)
- [libs/deepagents/deepagents/_subagent_transformer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_subagent_transformer.py)
- [libs/deepagents/deepagents/backends/state.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/state.py)
- [libs/deepagents/README.md](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/README.md)
- [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
# 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:
| Layer | Description |
|-------|-------------|
| **LangGraph** | Graph runtime for stateful, checkpointed execution |
| **LangChain Agent** | Minimal agent harness providing tool calling and message handling |
| **Deep Agents Middleware** | Filesystem, memory, skills, and context management bundled together |
Source: [libs/deepagents/README.md](https://github.com/langchain-ai/deepagents/blob/main/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.
```mermaid
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:
| State Field | Type | Description |
|-------------|------|-------------|
| `messages` | `list[BaseMessage]` | Conversation history including tool calls and results |
| `memory` | `dict` | Loaded memory blocks from AGENTS.md or memory files |
| `skills` | `dict` | Active skill context loaded on demand |
| `context` | `dict` | Middleware-provided context (file listings, search results) |
Source: [libs/deepagents/deepagents/graph.py](https://github.com/langchain-ai/deepagents/blob/main/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
```mermaid
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](https://github.com/langchain-ai/deepagents/blob/main/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](https://github.com/langchain-ai/deepagents/issues/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
```mermaid
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](https://github.com/langchain-ai/deepagents/issues/573)
### Subagent Configuration
Subagents can be defined in code or loaded from YAML configuration:
```yaml
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](https://github.com/langchain-ai/deepagents/blob/main/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:
| Option | Description |
|--------|-------------|
| `root_dir` | Root directory for relative file operations |
| `backend` | Backend type (local or sandbox) |
| `ignore_patterns` | Patterns to exclude from file operations |
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](https://github.com/langchain-ai/deepagents/issues/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](https://github.com/langchain-ai/deepagents/issues/3638)
### SkillsMiddleware
Implements progressive disclosure for skill loading. Skills are defined as filesystem directories containing a `SKILL.md` file with YAML frontmatter:
```yaml
---
name: newsletter
description: Use this skill when writing email newsletters
---
# Newsletter Skill
...
```
Skills follow a three-level loading system:
| Level | Content | Context Impact |
|-------|---------|----------------|
| Metadata | name + description | Always loaded (~100 words) |
| Body | SKILL.md contents | When skill triggers (<5k words) |
| Resources | Bundled files | Unlimited, loaded on demand |
Source: [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
## Backend Architecture
The `backends/state.py` module provides state management backends that handle persistence and retrieval of agent state.
### State Backend Options
| Backend | Description |
|---------|-------------|
| `MemoryBackend` | In-memory state, ephemeral |
| `FilesystemBackend` | Local filesystem persistence |
| `SandboxBackend` | Remote sandbox with additional isolation |
| `HubBackend` | LangSmith Hub integration for shared state |
Source: [libs/deepagents/deepagents/backends/state.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/state.py)
### Sandbox Backend
The `SandboxBackend` provides isolated execution environments. When using `grep`, the backend may encounter issues if container exec fails, resulting in a `ValueError`. This has been addressed in recent releases. Source: [GitHub Issue #3441](https://github.com/langchain-ai/deepagents/issues/3441)
## Tool Execution
Tools are defined using LangChain's `@tool` decorator and passed to the agent at construction time. The graph handles tool calling through the standard LangChain agent loop:
1. Agent receives current state
2. Agent decides on next action (reason, tool call, or respond)
3. If tool call, execute with appropriate backend
4. Append result to message history
5. Check for truncation/summarization needs
6. Loop until terminal action
```mermaid
graph TD
A[Agent Decision] --> B{Action Type}
B -->|reason| C[Internal Reasoning]
B -->|tool| D[Execute Tool]
B -->|respond| E[Return to User]
C --> A
D --> F[Append Result]
F --> A
```
## Configuration
The agent graph is configured through `deepagents.toml` for deployments or directly in code when using `create_deep_agent()`:
```python
agent = create_deep_agent(
model=model,
memory=["./AGENTS.md"],
skills=["./skills/"],
tools=[generate_cover, generate_social_image],
subagents=load_subagents("./subagents.yaml"),
backend=FilesystemBackend(root_dir="./"),
)
```
Source: [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
## Deployment Architecture
When deploying with `deepagents deploy`, the graph is bundled into a deployable format with:
- Graph template rendered into `deploy_graph.py`
- Auth handler for the specified provider
- `langgraph.json` configuration
- Optional MCP server integration via `mcp.json`
The deployment graph adds user memory handling, assistant scope configuration, and sandbox provisioning. Source: [libs/cli/deepagents_cli/deploy/bundler.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/bundler.py)
## Layer Composition
The three layers compose naturally:
```mermaid
graph TD
subgraph LangGraph
G1[CompiledStateGraph]
end
subgraph LangChain Agent
L1[create_agent harness]
end
subgraph Deep Agents
D1[create_deep_agent]
D2[FilesystemMiddleware]
D3[MemoryMiddleware]
D4[SkillsMiddleware]
end
D1 --> L1
L1 --> G1
D2 --> D1
D3 --> D1
D4 --> D1
```
Any LangGraph `CompiledStateGraph` can be passed as a sub-agent, enabling custom orchestration alongside the harness defaults. Source: [libs/deepagents/README.md](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/README.md)
---
## Middleware System
### Related Pages
Related topics: [Agent Graph Architecture](#agent-graph), [Filesystem and Sandbox Backend](#filesystem-backend), [Memory Middleware](#memory-middleware), [Skills System](#skills-system), [Context Summarization](#summarization)
Related Source Files
The following source files were used to generate this page:
- [libs/deepagents/deepagents/middleware/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/__init__.py)
- [libs/deepagents/deepagents/middleware/filesystem.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py)
- [libs/deepagents/deepagents/middleware/memory.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py)
- [libs/deepagents/deepagents/middleware/skills.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py)
- [libs/deepagents/deepagents/middleware/subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py)
- [libs/deepagents/deepagents/middleware/summarization.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/summarization.py)
- [libs/deepagents/deepagents/middleware/permissions.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/permissions.py)
# 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.
```mermaid
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:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `root_dir` | `str` | `"."` | Root directory for all file operations |
| `allowed_dirs` | `List[str]` | `None` | Explicitly allowed directories |
| `ignored_patterns` | `List[str]` | `[]` | Glob patterns to exclude |
| `max_file_size` | `int` | `10MB` | Maximum file size for reading |
**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](https://github.com/langchain-ai/deepagents/issues/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:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `memory` | `List[str]` | `[]` | List of memory file paths to load |
| `add_cache_control` | `bool` | `True` | Enable cache control markers on memory blocks |
> **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](https://github.com/langchain-ai/deepagents/issues/3638) and [#3639](https://github.com/langchain-ai/deepagents/issues/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:**
| Level | Content | Context Cost |
|-------|---------|--------------|
| Metadata | name, description | ~100 words |
| Body | SKILL.md content | <5k words |
| Resources | scripts/references/assets | As needed |
### 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:**
```yaml
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](https://github.com/langchain-ai/deepagents/issues/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](https://github.com/langchain-ai/deepagents/issues/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:
```mermaid
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
```python
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:
| Hook | Timing | Use Case |
|------|--------|----------|
| `before_tool` | Before tool execution | Permission checks, argument validation |
| `after_tool` | After tool execution | Response transformation, logging |
| `on_error` | On exception | Error recovery, fallback behavior |
| `on_completion` | After agent turn | Cleanup, state persistence |
## 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.
```toml
# 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.
2. **Configure ignored patterns:** Use `.deepagentsignore` (when available) or middleware-specific ignore configurations to prevent sensitive directories from being accessed.
3. **Monitor summarization thresholds:** Configure SummarizationMiddleware thresholds to balance context retention against token costs.
4. **Handle async subagents carefully:** Async subagents do not inherit checkpoint persistence. Plan for state recovery when using async delegation.
5. **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](https://docs.langchain.com/deepagents/filesystem)
- [Memory Management](https://docs.langchain.com/deepagents/memory)
- [Skills System](https://docs.langchain.com/deepagents/skills)
- [Subagents](https://docs.langchain.com/deepagents/subagents)
- [Deploy Configuration](https://docs.langchain.com/deepagents/deploy)
---
## Filesystem and Sandbox Backend
### Related Pages
Related topics: [Middleware System](#middleware), [Memory Middleware](#memory-middleware)
Related Source Files
The following source files were used to generate this page:
- [libs/deepagents/deepagents/backends/filesystem.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/filesystem.py)
- [libs/deepagents/deepagents/backends/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/sandbox.py)
- [libs/deepagents/deepagents/backends/protocol.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/protocol.py)
- [libs/partners/daytona/langchain_daytona/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/partners/daytona/langchain_daytona/sandbox.py)
- [libs/partners/modal/langchain_modal/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/partners/modal/langchain_modal/sandbox.py)
- [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md)
- [examples/deploy-coding-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/README.md)
- [libs/cli/deepagents_cli/deploy/bundler.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/bundler.py)
# 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.
```mermaid
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.
| Use Case | Backend Type | Environment | Security Level |
|----------|--------------|--------------|----------------|
| Local Development | `FilesystemBackend` | Local machine | Standard filesystem permissions |
| Production Coding Agent | `SandboxBackend` | LangSmith Sandbox | Isolated container |
| Documentation Agent | `SandboxBackend` | LangSmith Sandbox | Isolated container |
| Custom Deployment | `SandboxBackend` | Partner provider | Provider-dependent |
## 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:
| Operation | Purpose | Parameters |
|-----------|---------|------------|
| `read_file` | Read file contents with optional pagination | `path`, `offset`, `limit` |
| `write_file` | Write or overwrite file contents | `path`, `content` |
| `list_files` | List directory contents recursively | `path`, `pattern`, `exclude` |
| `grep` | Search file contents using patterns | `pattern`, `path`, `glob`, `context` |
| `execute` | Run shell commands | `command`, `timeout`, `cwd` |
### 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.
```python
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:
```toml
[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:
| Method | Return Type | Description |
|--------|-------------|-------------|
| `read_file` | `str` | Read and return file contents |
| `write_file` | `None` | Write content to file |
| `list_files` | `list[str]` | List files in directory |
| `grep` | `list[dict]` | Search files for pattern |
| `execute` | `dict` | Execute shell command |
| `get_path` | `str` | Get absolute path |
### 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:
```toml
[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.
```python
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:
| Operation | Ignored Pattern Effect |
|-----------|----------------------|
| `read_file` | Skips ignored files in directory reads |
| `list_files` | Filters out matching paths from results |
| `grep` | Does not search ignored file paths |
| `@` mentions | Ignored files not suggested for auto-complete |
## 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.
---
## Skills System
### Related Pages
Related topics: [Middleware System](#middleware), [Quickstart Guide](#quickstart)
Related Source Files
The following source files were used to generate this page:
- [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
- [libs/cli/examples/skills/skill-creator/scripts/init_skill.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/scripts/init_skill.py)
- [libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md)
- [libs/cli/examples/skills/web-research/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/web-research/SKILL.md)
- [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md)
- [examples/deploy-coding-agent/skills/planning/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/skills/planning/SKILL.md)
# 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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
## Skill Anatomy
A skill directory contains the following components:
| Component | Type | Purpose |
|-----------|------|---------|
| `SKILL.md` | File | Primary skill definition with YAML frontmatter metadata and workflow instructions |
| `scripts/` | Directory | Executable code (Python/Bash) for automation and operations |
| `references/` | Directory | Detailed documentation, API references, and guides loaded on demand |
| `assets/` | Directory | Templates, images, fonts, and boilerplate not loaded into context |
### SKILL.md Structure
Every skill requires a `SKILL.md` file with YAML frontmatter defining metadata:
```yaml
---
name: skill-name
description: "Use this skill when user asks to... Trigger on phrases like..."
---
# Skill Title
## Workflow Section
...
```
Source: [libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md)
### Skill Resource Directories
Skills can include three types of bundled resources:
#### scripts/
Executable code (Python/Bash) that can be run directly to perform specific operations. Scripts may be executed without loading into context, enabling automation without consuming context window space.
Appropriate for: Python scripts, shell scripts, data processing, specific operations.
#### references/
Documentation and reference material intended to be loaded into context when the agent needs detailed information. References keep `SKILL.md` lean while providing deep-dive content.
Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, company policies.
Best practice: For files exceeding 10k words, include search patterns in `SKILL.md` to help the agent locate relevant sections.
Source: [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
#### assets/
Files not intended for context loading, but used within the agent's output. These are copied or modified by the agent as needed.
Appropriate for: Templates (.pptx, .docx), images, icons, boilerplate directories, fonts, sample documents.
## Skill Loading Architecture
Deep Agents discovers and loads skills through a layered directory system with explicit precedence rules.
### Skill Discovery Directories
Skills are loaded from four directories, listed from lowest to highest precedence:
```mermaid
graph TD
A["~/.deepagents/<agent>/skills/"] --> B["~/.agents/skills/"]
B --> C[".deepagents/skills/"]
C --> D[".agents/skills/"]
E["Higher precedence wins"] --> F["Same-name skill resolution"]
```
| Priority | Directory | Scope | Notes |
|----------|-----------|-------|-------|
| 1 | `~/.deepagents//skills/` | User | Default for `deepagents skills create` |
| 2 | `~/.agents/skills/` | User | Shared across agent tools |
| 3 | `.deepagents/skills/` | Project | Default for `deepagents skills create --project` |
| 4 | `.agents/skills/` | Project | Shared across agent tools |
`` is the agent configuration name (default: `agent`). When two directories contain a skill with the same name, the higher-precedence version takes effect.
Source: [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
## Progressive Disclosure Design
Skills use a three-level loading system to manage context efficiently:
```mermaid
graph LR
A["Metadata
~100 words"] --> B["SKILL.md body
<5k words"]
B --> C["Bundled resources
Unlimited"]
D["Always loaded"] --> A
E["When skill triggers"] --> B
F["As needed"] --> C
```
| Level | Content | Loading | Context Impact |
|-------|---------|---------|----------------|
| 1 | Metadata (name + description) | Always | ~100 words |
| 2 | SKILL.md body | When skill triggers | <5k words |
| 3 | Bundled resources (scripts/, references/, assets/) | As needed | Unlimited |
This pattern allows skills to provide comprehensive functionality without bloating the context window. Scripts can be executed directly without reading into context, and references are loaded only when the agent determines they are needed.
### SKILL.md Size Guidelines
- Keep `SKILL.md` body to the essentials and under 500 lines to minimize context bloat
- `SKILL.md` files exceeding 10 MB are silently skipped by the agent runtime
- Split content into separate files when approaching the line limit
- Reference files from `SKILL.md` and describe clearly when to read them
Source: [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
## Skill Invocation Flow
When an agent encounters a task that matches a skill's trigger criteria, the following flow occurs:
```mermaid
sequenceDiagram
participant User
participant Agent
participant SkillsMiddleware
participant SkillDirectory
User->>Agent: Task request
Agent->>SkillsMiddleware: Check for matching skill
SkillsMiddleware->>SkillDirectory: Load SKILL.md + metadata
SkillDirectory-->>SkillsMiddleware: Skill content
SkillsMiddleware-->>Agent: Skill instructions
Agent->>Agent: Execute with skill context
alt Needs detailed reference
Agent->>SkillDirectory: Load references/
SkillDirectory-->>Agent: Reference documentation
end
alt Needs executable script
Agent->>SkillDirectory: Execute scripts/
SkillDirectory-->>Agent: Script results
end
```
## Skill Triggering
Skills are triggered when the agent determines that a user's request matches the skill's description. The description should include:
1. **Use cases**: Clear scenarios when the skill applies
2. **Trigger phrases**: Common user expressions that activate the skill
3. **Intent patterns**: Keywords and phrases indicating skill relevance
Example skill description:
```yaml
description: "Use this skill when the user asks to: (1) create a new skill,
(2) make a skill, (3) build a skill, (4) set up a skill, (5) initialize a skill,
(6) scaffold a skill, (7) update or modify an existing skill, (8) validate a skill,
(9) learn about skill structure, (10) understand how skills work, or (11) get
guidance on skill design patterns. Trigger on phrases like 'create a skill',
'new skill', 'make a skill', 'skill for X', 'how do I create a skill', or
'help me build a skill'."
```
Source: [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
## Built-in Skills
Deep Agents ships with several built-in skills:
### skill-creator
Guides the creation of new skills with reusable components. Includes scripts for skill initialization (`init_skill.py`) and validation (`quick_validate.py`).
| Resource | Type | Purpose |
|----------|------|---------|
| `scripts/init_skill.py` | Script | Scaffold new skill directories |
| `references/workflows.md` | Reference | Sequential workflows and conditional logic patterns |
| `references/output-patterns.md` | Reference | Template and example patterns |
### web-research
Performs web research using Tavily search, delegated subagents, and strategic synthesis. Demonstrates complex multi-step workflows with file organization.
Source: [libs/cli/examples/skills/web-research/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/web-research/SKILL.md)
### planning
Task planning skill that helps agents break down complex tasks into manageable steps. Includes templates for structured planning.
Source: [examples/deploy-coding-agent/skills/planning/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/skills/planning/SKILL.md)
### blog-post
Writing skill for long-form blog posts with SEO optimization and clear structure guidance.
Source: [libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md)
## Creating Custom Skills
### Skill Creation Process
| Step | Phase | Description |
|------|-------|-------------|
| 1 | Understand | Identify concrete usage examples for the skill |
| 2 | Plan | Determine reusable resources (scripts, references, assets) |
| 3 | Initialize | Run `init_skill.py` to scaffold the directory |
| 4 | Edit | Implement resources and write SKILL.md |
| 5 | Validate | Run `quick_validate.py` to verify structure |
| 6 | Iterate | Refine based on real usage |
### Skill Initialization
Use the built-in skill-creator to scaffold a new skill:
```bash
deepagents skills create --name my-new-skill
```
Or with project scope:
```bash
deepagents skills create --name my-new-skill --project
```
### Structuring SKILL.md Content
Four main patterns for organizing skill content:
| Pattern | Best For | Structure |
|---------|----------|-----------|
| **Task-Based** | Tool collections | ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2... |
| **Reference/Guidelines** | Standards or specifications | ## Overview → ## Guidelines → ## Specifications → ## Usage... |
| **Capabilities-Based** | Integrated systems | ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature... |
| **Workflow** | Sequential processes | ## Overview → ## Prerequisites → ## Steps → ## Examples... |
Patterns can be mixed and matched. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
Source: [libs/cli/examples/skills/skill-creator/scripts/init_skill.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/scripts/init_skill.py)
### Reference File Organization
Reference files should:
- Be linked directly from `SKILL.md` (one level deep maximum)
- Include a table of contents at the top for files longer than 100 lines
- Live in either `SKILL.md` or `references/` — not both
- Prefer `references/` for detailed information to keep `SKILL.md` lean
### What to Include vs. Exclude
A skill should only contain essential files that directly support its functionality. Do NOT create:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- Other auxiliary documentation
The skill should contain only information needed for an AI agent to execute the task at hand.
Source: [libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/built_in_skills/skill-creator/SKILL.md)
## Using Skills in Custom Agents
Skills can be integrated into custom agents created with `create_deep_agent`:
```python
from deepagents import create_deep_agent
agent = create_deep_agent(
skills=["./skills/"], # Directory containing skill directories
# ... other configuration
)
```
The skills directory is scanned and skills are loaded based on the directory path provided. The agent automatically handles skill discovery and triggering based on task context.
Source: [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md)
## Best Practices
### Skill Design
1. **Start with concrete examples**: Understand real usage patterns before building
2. **Minimize context usage**: Use progressive disclosure to keep context lean
3. **Separate concerns**: Use `references/` for detailed docs, `SKILL.md` for workflows
4. **Test bundled scripts**: Run scripts to ensure they work correctly before shipping
### Context Management
| Strategy | When to Use |
|----------|-------------|
| Keep SKILL.md under 500 lines | Most skills |
| Use references/ for deep content | Files exceeding 10k words |
| Execute scripts without reading | Automation and data processing |
| Include search patterns | Large reference files |
### Skill Independence
- Skills should be self-contained and portable
- Avoid hardcoded paths outside the skill directory
- Use relative references within the skill structure
- Test skills in isolation before integrating
## Community Considerations
The community has expressed interest in expanding skills capabilities:
- **Issue #506**: Request for using skills in custom agent (non-CLI version)
- **Issue #180**: Discussion on native skill support in the deep agent
These discussions highlight the importance of skills as a core extensibility mechanism for the Deep Agents framework.
---
## Subagents System
### Related Pages
Related topics: [Agent Graph Architecture](#agent-graph), [Middleware System](#middleware)
Related Source Files
The following source files were used to generate this page:
- [libs/deepagents/deepagents/middleware/subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py)
- [libs/deepagents/deepagents/middleware/async_subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/async_subagents.py)
- [libs/deepagents/deepagents/_subagent_transformer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_subagent_transformer.py)
- [examples/async-subagent-server/server.py](https://github.com/langchain-ai/deepagents/blob/main/examples/async-subagent-server/server.py)
- [examples/deploy-gtm-agent/subagents/market-researcher/deepagents.toml](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-gtm-agent/subagents/market-researcher/deepagents.toml)
- [examples/content-builder-agent/subagents.yaml](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/subagents.yaml)
- [libs/cli/examples/skills/web-research/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/web-research/SKILL.md)
# 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
```mermaid
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:
| Type | Execution Model | Use Case | Configuration |
|------|-----------------|----------|---------------|
| **Sync Subagent** | Blocking, sequential | Task delegation within a single workflow | Inline definition or `subagents.yaml` |
| **Async Subagent** | Non-blocking, concurrent | Parallel research, parallel tool execution | `AsyncSubagentMiddleware` |
| **Remote Subagent** | HTTP/SSE communication | Self-hosted Agent Protocol servers | `mcp.json` + server endpoint |
## 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
```python
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:
```yaml
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:
```python
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:
| Tool | Description |
|------|-------------|
| `read_file` | Read file contents with pagination support |
| `list_files` | List directory contents |
| `write_file` | Write content to files |
| `grep` | Search file contents using ripgrep |
| `shell` | Execute shell commands |
| `task` | Spawn nested subagents |
## Async Subagents
Async subagents execute tasks concurrently, enabling parallel processing of independent subtasks. They are exposed via the Agent Protocol standard.
### Architecture
```mermaid
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
```python
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
```python
# 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:
```toml
# 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
| Responsibility | Description |
|---------------|-------------|
| Configuration parsing | Validates and normalizes subagent definitions |
| Tool injection | Adds necessary tools (task, read_file, write_file) |
| State management | Manages checkpointing and state persistence |
| Result aggregation | Collects and formats subagent outputs |
### 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](https://github.com/langchain-ai/deepagents/issues/573) for details.
## Usage Patterns
### Pattern 1: Parallel Research
```mermaid
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:
```markdown
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
```mermaid
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
```python
# 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
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the subagent |
| `description` | string | Yes | Description for model context (when to use) |
| `model` | string | Yes | Model identifier (e.g., `anthropic:claude-haiku-4-5-20251001`) |
| `system_prompt` | string | No | Custom instructions for the subagent |
| `tools` | list | No | Tool definitions for the subagent |
### Task Tool Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `task_name` | string | Name of the subagent to invoke |
| `input` | string | Task description/question |
| `model` | string | Override model (optional) |
| `system_prompt` | string | Override system prompt (optional) |
## 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
| Example | Path | Description |
|---------|------|-------------|
| Content Builder | `examples/content-builder-agent/` | Uses subagents for research delegation |
| GTM Strategist | `examples/deploy-gtm-agent/` | Coordinates sync and async subagents |
| Async Subagent Server | `examples/async-subagent-server/` | Self-hosted Agent Protocol server |
| Web Research Skill | `libs/cli/examples/skills/web-research/` | Parallel research with task tool |
## Related Documentation
- [Skills System](skills-system) - Workflow-based task execution
- [Memory System](memory-system) - Persistent context management
- [Middleware](middleware) - Extensibility architecture
- [Deploy](deploy) - Deploying multi-agent systems
---
## Memory Middleware
### Related Pages
Related topics: [Middleware System](#middleware), [Context Summarization](#summarization)
Related Source Files
The following source files were referenced to generate this page:
- [libs/deepagents/deepagents/middleware/memory.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py) - Memory middleware implementation
- [libs/deepagents/deepagents/backends/store.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/store.py) - Backend storage interface
- [libs/cli/deepagents_cli/deploy/bundler.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/bundler.py) - Project bundling for deployment
- [examples/deploy-content-writer/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-content-writer/README.md) - Per-user memory implementation
- [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) - Agent configuration with memory
- [examples/deploy-coding-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-coding-agent/README.md) - Deploy configuration
- [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md) - Skill creation guidelines
# 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
```mermaid
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:
```python
from deepagents import create_deep_agent
agent = create_deep_agent(
memory=["./AGENTS.md"], # Memory file paths
tools=[...],
)
```
### Advanced Configuration Options
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `memory` | `List[str]` | `None` | List of file paths to load as memory |
| `add_cache_control` | `bool` | `True` (v0.6+) | Adds cache control markers to memory blocks |
| `memory_backend` | `StoreBackend` | `FilesystemBackend` | Backend for memory persistence |
### 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](https://github.com/langchain-ai/deepagents/issues/3638) and [Issue #3639](https://github.com/langchain-ai/deepagents/issues/3639) for details.
To disable cache control markers:
```python
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](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.
```python
# 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](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:
```toml
# 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](examples/deploy-content-writer/README.md)
## Project Structure
The memory middleware reads from the following canonical project layout:
```
/
├── 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.md
└── user/ # Per-user writable memory (optional)
└── AGENTS.md # Seeded per-user memory
```
Source: [libs/cli/deepagents_cli/deploy/bundler.py](libs/cli/deepagents_cli/deploy/bundler.py)
## Memory Lifecycle
```mermaid
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
```python
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](libs/deepagents/deepagents/backends/store.py)
## Known Issues and Limitations
### Cache Control Marker Bug (v0.6)
**Issue**: [Issue #3638](https://github.com/langchain-ai/deepagents/issues/3638), [Issue #3639](https://github.com/langchain-ai/deepagents/issues/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:
```python
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](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
| Component | Relationship |
|-----------|--------------|
| Skills | Bundled alongside memory in skills namespace |
| Subagents | Can have isolated memory contexts |
| Sandbox Backend | Reads memory files during agent execution |
| Deploy Bundler | Packages memory files for deployment |
## Version History
| Version | Change |
|---------|--------|
| 0.6+ | `add_cache_control=True` becomes default (includes bug) |
| 0.6.7 | Improved memory block handling |
| 0.5 and earlier | Cache control not applied to memory |
---
## Context Summarization
### Related Pages
Related topics: [Memory Middleware](#memory-middleware), [Middleware System](#middleware)
Related Source Files
The following source files were used to generate this page:
- [libs/deepagents/deepagents/middleware/summarization.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/summarization.py)
- [libs/deepagents/deepagents/middleware/_message_eviction.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/_message_eviction.py)
- [libs/deepagents/deepagents/middleware/_overflow_clip.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/_overflow_clip.py)
- [libs/deepagents/deepagents/middleware/base.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/base.py)
- [libs/deepagents/deepagents/middleware/memory.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py)
- [libs/deepagents/deepagents/core/summarizer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/core/summarizer.py)
# 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.
```mermaid
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
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `enabled` | `bool` | `True` | Enable or disable summarization |
| `threshold` | `int` | `2000` | Token count threshold before summarization triggers |
| `max_messages` | `int` | `50` | Maximum messages to retain before eviction |
| `prompt` | `str` | `None` | Custom prompt for summarization LLM |
| `model` | `str` | `None` | Specific model to use for summarization |
### 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
```mermaid
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
| Strategy | Description | Use Case |
|----------|-------------|----------|
| `fifo` | First-in, First-out removal | Simple context management |
| `lru` | Least Recently Used eviction | Preserve recent context |
| `importance` | Score-based removal | Keep critical messages |
| `hybrid` | Combined approach | Balanced context management |
### 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
```python
# 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:
| Factor | Impact |
|--------|--------|
| Prompt Design | Determines what information is preserved |
| Model Selection | Affects coherence and accuracy |
| Threshold Tuning | Balances detail vs. compression |
| Iterative Summarization | Maintains quality over long sessions |
## Usage Examples
### Basic Configuration
```python
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
```python
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:
```python
agent = create_deep_agent(
middleware=[
SummarizationMiddleware(enabled=False)
]
)
```
## Best Practices
### Threshold Selection
| Conversation Type | Recommended Threshold | Rationale |
|------------------|---------------------|-----------|
| Short tasks | 3000-5000 | Minimal summarization needed |
| Long research | 1000-2000 | Balance detail with efficiency |
| Multi-agent | 500-1500 | Preserve delegation context |
| Code-heavy | 2000-3000 | Preserve technical details |
### 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
| Component | Purpose | Integration |
|-----------|---------|-------------|
| `FilesystemMiddleware` | File reading and management | May use summarization for large files |
| `MemoryMiddleware` | Persistent context management | Provides cache_control markers |
| `OverflowClipMiddleware` | Hard limit enforcement | Final safety net for context size |
| `MessageEvictionMiddleware` | Selective message removal | Alternative to summarization |
## Version History
| Version | Change |
|---------|--------|
| 0.6+ | Added `add_cache_control` feature to memory integration |
| 0.6.3 | Fixed ripgrep glob anchoring in context operations |
| 0.6.4 | Stable HumanMessage IDs across resumed threads |
| 0.6.7 | Improved goto and graph propagation in Commands |
## See Also
- [Memory Management](memory.md) - Persistent context configuration
- [Middleware System](middleware.md) - Pipeline architecture overview
- [Context Management](context.md) - Overall context strategy
- [Tool Integration](tools.md) - How tools interact with context
---
## MCP (Model Context Protocol) Integration
Related Source Files
The following source files were used to generate this page:
- [libs/code/deepagents_code/mcp_tools.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_tools.py)
- [libs/code/deepagents_code/mcp_providers/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_providers/__init__.py)
- [libs/code/deepagents_code/mcp_commands.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_commands.py)
- [libs/code/deepagents_code/mcp_auth.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_auth.py)
- [libs/code/deepagents_code/mcp_login_service.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_login_service.py)
- [libs/cli/deepagents_cli/deploy/bundler.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/bundler.py)
# MCP (Model Context Protocol) Integration
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_providers/__init__.py)
## Architecture
```mermaid
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](https://github.com/langchain-ai/deepagents/blob/main/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:
```json
{
"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](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/config.py)
### Configuration Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `command` | string | Executable command to start the MCP server |
| `args` | array | Command-line arguments passed to the server |
| `env` | object | Environment variables for the server process |
| `headers` | object | HTTP headers for server-to-server communication |
Environment variables can reference `${VAR}` patterns that are expanded at runtime from the host environment.
Source: [libs/cli/deepagents_cli/deploy/bundler.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/deploy/bundler.py)
## MCP Providers
MCP providers manage the lifecycle of MCP server connections and tool discovery.
```python
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_providers/__init__.py)
### Tool Discovery Flow
```mermaid
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_tools.py)
## MCP Authentication
The authentication system handles credential management for MCP servers that require authentication.
```python
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_auth.py)
### Login Service
The MCP login service provides OAuth and token-based authentication flows for MCP servers:
```python
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_login_service.py)
## CLI Commands
The Deep Agents CLI provides several commands for managing MCP integrations:
| Command | Description |
|---------|-------------|
| `/mcp` | Show MCP connection status and available servers |
| `/mcp add ` | Add a new MCP server configuration |
| `/mcp remove ` | Remove an MCP server configuration |
| `/mcp config` | Edit MCP configuration |
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](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_commands.py)
### Viewing MCP Status
```bash
/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](https://github.com/langchain-ai/deepagents/blob/main/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:
```python
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](https://github.com/langchain-ai/deepagents/blob/main/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:
```json
{
"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](https://github.com/langchain-ai/deepagents/blob/main/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
| Issue | Cause | Solution |
|-------|-------|----------|
| MCP server not connecting | Invalid configuration | Verify `mcp.json` syntax and server availability |
| Tool not found | Server disconnected | Run `/mcp` to check connection status |
| Auth failures | Expired credentials | Refresh credentials with server-specific auth flow |
### Debug Mode
Enable verbose logging to diagnose MCP connection issues:
```python
import logging
logging.getLogger("deepagents.mcp").setLevel(logging.DEBUG)
```
## Related Documentation
- [Deep Agents Overview](https://docs.langchain.com/oss/python/deepagents/overview)
- [Deploy Documentation](https://docs.langchain.com/deepagents/deploy)
- [LangGraph SDK Docs](https://langchain-ai.github.io/langgraph/concepts/sdk/)
---
---
## Pitfall Log
Project: langchain-ai/deepagents
Summary: 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested 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