DeepAgents Masterclass

Build production-grade, autonomous agents using the DeepAgents harness. This framework is 100% compatible with LangChain structures, allowing you to seamlessly integrate any LangChain retriever, tool, or guardrail into a robust autonomous loop.

Core Architecture

DeepAgents operates on a 3-layer architecture designed for durability and context hygiene.

1. The Harness (Cognitive Loop)

The harness create_deep_agent is not just a loop; it is a rigid cognitive architecture that enforces specific behaviors:

• Planning First: The agent is driven by a Todo list (write_todos). It cannot effectively operate without a plan.
• Context-on-Disk: To prevent context window pollution (and hallucinations), the harness prioritizes filesystem operations (grep, read_file) over loading everything into memory.
• Eviction: Large tool outputs are legally evicted from the context window and replaced with file pointers.

2. Middleware (Capabilities)

Middleware extends the agent without cluttering the core graph.

• SubAgentMiddleware: Spawns isolated agents. This is CRITICAL for complex tasks.
• FilesystemMiddleware: Manages valid paths and virtual environments.

See references/middleware_and_structures.md for the Middleware API specification and lifecycle hooks.

3. Memory (Storage Backend)

DeepAgents splits memory into two domains:

• Transient (StateBackend): /workspace/ or root. Dies with the thread.
• Persistent (StoreBackend/S3): /memories/ or /cloud/. Lives forever in a Database (Postgres) or Cloud (S3).

Capabilities & Patterns

1. Sub-Agent Delegation (Context Isolation)

Don’t ask one agent to do everything. Use SubAgentMiddleware to delegate.

Why?

• Context Hygiene: A sub-agent has a fresh context window. It reads 10 files, synthesizes the answer, and returns only the answer to the parent. The parent’s context remains clean.
• Specialization: You can swap models per sub-agent (e.g., o1-preview for planning, haiku for summarization).

# See references/deep_agents_patterns.md for full code
sub_middleware = SubAgentMiddleware(
    subagents=[{"name": "researcher", "tools": [web_search], ...}]
)

2. Advanced Prompt Engineering (Reasoning Loops)

Agents must think before they act. You must enforce a generic “Chain of Thought” (CoT) system prompt.

Rule: Never let an agent call a tool blindly. Pattern:

1. Analyze the request.
2. Plan the step.
3. Verify the context (do I have the file?).
4. Act (call tool).

See references/deep_agents_patterns.md for the specific “Cognitive Process” system prompt.

3. Long-Term Memory (The “Memories” Folder)

Use the /memories/ path convention to store knowledge that needs to persist.

• User Preferences: /memories/user_prefs.txt
• Project Context: /memories/architecture_decisions.md

The agent should be instructed to check these files at the start of a session.

4. Skills (Knowledge Injection)

Use the skills directory to inject read-only knowledge (like coding standards or API docs) without bloating the system prompt. The agent “consults” these skills as needed.

5. Middleware & Guardrails

Middleware intercepts agent actions to enforce business logic that the LLM cannot override.

• Planning Guardrails: Use TodoListMiddleware to enforce “Human-in-the-Loop” approval for high-stakes plans.
• Filesystem Guardrails: Use FilesystemMiddleware to sandbox operations (e.g., read-only access to /production).

See references/deep_agents_patterns.md for Middleware configuration examples.

6. Advanced Prompting

DeepAgents relies on structured reasoning. Implement the Chain-of-Thought with Verification pattern (see prompt-engineering-patterns skill) to minimize hallucinations.

See references/deep_agents_patterns.md for the DeepAgent System Prompt template.

7. Observability & Debugging

Autonomous agents can be unpredictable. Use LangSmith and Debug Middleware to track every thought and action. See references/observability_and_testing.md for tracing and evaluation patterns.

8. MCP (Model Context Protocol)

Decouple your tool logic from your agent. Host tools on independent servers and connect via the standard MCP interface. See references/mcp_and_tooling.md for implementation details.

9. RAG & Advanced Retrieval

Build intelligent RAG agents that evaluate their own context before answering. Supports Multi-Query and Contextual Compression. See references/advanced_retrieval_and_rag.md for RAG patterns.

11. Context Engineering

Managing the context window is as important as the model selection. Use techniques like pruning, compression, and structured formatting to maximize reasoning accuracy. See the context-engineering skill for deep-dive patterns.

Quick Start (Production Setup)

from deepagents import create_deep_agent
from deepagents.middleware.subagents import SubAgentMiddleware
from deepagents.backends import FilesystemBackend, StoreBackend, CompositeBackend

# 1. Define specific Sub-Agents for isolation
coder_agent = {
    "name": "senior_coder",
    "description": "Writes and refactors code. Has access to all code tools.",
    "model": "gpt-4o",
    "tools": [lint_code, run_tests]
}

# 2. Configure Dual-Memory Backend
backend = CompositeBackend(routes={
    "/memories/": StoreBackend(...), # Long-term
    "/": FilesystemBackend(...)      # Short-term
})

# 3. Initialize Harness with Reasoning Prompt
agent = create_deep_agent(
    model="gpt-4o",
    middleware=[SubAgentMiddleware(subagents=[coder_agent])],
    storage=backend,
    skills_path="./skills",
    system_prompt="""
    You are a Senior Deep Agent.
    Strict Rules:
    1. ALWAYS <plan> before acting.
    2. Delegate complex coding tasks to 'senior_coder'.
    3. Save critical findings to /memories/.
    """
)

Common Pitfalls & Solutions

Resources

• Middleware & Structures (Hooks): references/middleware_and_structures.md
• Patterns Code: references/deep_agents_patterns.md
• Advanced RAG: references/advanced_retrieval_and_rag.md
• MCP & Tooling: references/mcp_and_tooling.md
• Guardrails: references/guardrails_and_validation.md
• Context Engineering Skill: (See context-engineering folder)
• Observability: references/observability_and_testing.md
• Official Docs: DeepAgents Documentation