Unlock Complex AI Agents with DeepAgents: A Hands‑On Guide

Introduction

LangChain 1.0 and LangGraph 1.0 constitute a mature, general‑purpose agent framework. DeepAgents is an open‑source library that sits on top of these layers and provides a concise create_deep_agent API together with a set of ready‑made middlewares, enabling developers to build complex, multi‑step, long‑running agents with minimal boilerplate.

Framework positioning

LangGraph : persistent, observable runtime for low‑level workflows and agents.

LangChain : high‑level wrapper over LangGraph that offers the create_agent helper and a middleware extension point.

DeepAgents : builds on LangChain’s high‑level API and LangGraph’s runtime; its create_deep_agent function automatically injects a suite of middlewares (task planning, virtual file system, sub‑agent delegation).

Core capabilities

Task planning (TodoListMiddleware)

DeepAgents adds a built‑in tool write_todos that generates a step‑by‑step plan before execution and updates the plan after each step. The tool is invoked automatically when the requested task is identified as multi‑step or when the user explicitly asks for planning.

Virtual file system (FilesystemMiddleware)

Agents can read and write files through a virtual file system. Four backend implementations are provided:

StateBackend : stores files in the agent’s in‑memory state; data exists only for the current thread.

FileSystemBackend : maps the virtual file system to a local directory, persisting files across runs.

StoreBackend : uses LangGraph’s Store (e.g., Redis, Postgres) to achieve cross‑thread, cross‑session persistence and optional vector‑search capabilities.

CompositeBackend : combines the above, routing specific paths (e.g., /memories/) to a StoreBackend while using the local filesystem for everything else.

Custom backends can be created by implementing the BackendProtocol interface, allowing integration with object storage, databases, or vector stores.

Sub‑agents (SubAgentMiddleware)

DeepAgents supports hierarchical delegation: a main agent can spawn specialized sub‑agents, each with its own system prompt, tool set, and model. This isolates context, separates expertise, and reduces token bloat for complex workflows.

Step‑by‑step example – Stock‑analysis agent

The demo builds a ReAct‑style agent that uses create_deep_agent instead of create_agent. The system prompt defines the role as a “stock analysis assistant” and registers a generic search tool.

SYSTEM_PROMPT = """你是一个股票分析助手。你的任务是帮助用户分析股票，使用 search 工具搜索相关信息。"""
main_tools = [search]
agent = create_deep_agent(
    model=f"openai:{OPENAI_MODEL}",
    tools=main_tools,
    system_prompt=SYSTEM_PROMPT,
    debug=True,
).with_config({"recursion_limit": RECURSION_LIMIT})

Run the agent with the LangGraph CLI: langgraph dev When the user asks for analysis of a specific stock, the agent follows the normal ReAct loop for simple queries. For multi‑step requests the write_todos tool is called first, storing a todo list in the agent’s state. Subsequent steps use write_file to persist intermediate results.

Switching the backend to FileSystemBackend writes the final markdown report to a real file on disk. Routing /memories/ to a StoreBackend stores the list of analyzed stocks in a persistent store, demonstrating cross‑session memory.

Sub‑agent configuration

Three sub‑agents are defined for fundamental, technical, and news analysis. Each sub‑agent is described by a name, a description, a system prompt, a tool list, and a model. They are collected into a subagents list and passed to create_deep_agent. During execution the main agent dispatches tasks to the appropriate sub‑agent via a special task tool.

subagents = [fundamental_analyst, technical_analyst, news_analyst]
agent = create_deep_agent(
    model=f"openai:{OPENAI_MODEL}",
    tools=main_tools,
    system_prompt=SYSTEM_PROMPT,
    subagents=subagents,
    debug=True,
)

Middleware architecture

TodoListMiddleware : inserts the planning step.

FilesystemMiddleware : provides write_file, read_file and path routing.

SubAgentMiddleware : enables hierarchical delegation.

Each middleware focuses on a single concern and can be swapped or customized without touching the core agent loop.

Future outlook

DeepAgents is at version 0.2. Planned enhancements include fully customizable system prompts, more flexible multi‑agent collaboration patterns, advanced memory retrieval and forgetting mechanisms, deeper integration with retrieval‑augmented generation (RAG) pipelines, and an expanding ecosystem of third‑party middlewares.

Reference

Source code for the demo:

https://github.com/pingcy/deepagents-demo