Skip to content
/
Tier A A10 Memory engine

deepagents (LangChain)

deepagents-langchain · langchain-ai/deepagents · ★ 23k · last commit 2026-05-26

Primitive shape
No installable primitives
00

Summary

deepagents (LangChain) — Summary

Deep Agents is LangChain's "batteries-included" Python agent harness, describing itself as opinionated middleware layered on top of LangGraph's create_agent. It bundles filesystem access, sub-agent delegation, context summarization, todo-list planning, memory, skills, and human-in-the-loop approval into a single create_deep_agent() call. The framework is explicitly model-agnostic — any LangChain chat model that supports tool calling works, from frontier APIs to local Ollama/vLLM instances. Its middleware architecture lets users override or remove individual layers (filesystem, subagents, memory, summarization) without forking the library. A companion deepagents-cli package (binary: deepagents) handles project scaffolding (init), local dev server (dev), and deployment to LangSmith. The interactive coding REPL (deepagents-code, binary dcode) is a separate package installed via a one-liner curl script.

Compared to seeds, deepagents most closely resembles claude-flow in being an MCP-adjacent, LangGraph-backed harness with sub-agents and checkpointing, but differs fundamentally: it is a Python pip package with no MCP server of its own, uses LangGraph's native checkpointer/store rather than SQLite+HNSW, and targets any LLM rather than being Claude-Code-specific. Unlike superpowers (skills-only, zero code) or BMAD-METHOD (persona-based markdown), deepagents is code-first — the full harness is imported Python classes.

01

Overview

deepagents (LangChain) — Overview

Origin

Developed by LangChain, Inc. as an opinionated harness on top of their existing langchain.agents.create_agent and LangGraph runtime. The project was publicly introduced with the tagline "The batteries-included agent harness." It is explicitly positioned as what you use when you want the full harness out-of-the-box, rather than assembling LangGraph nodes by hand.

The README states: "Inspired by Claude Code: an attempt to identify what makes it general-purpose, and push that further."

Philosophy

From the README:

"Deep Agents is an open source agent harness — an opinionated agent that runs out of the box. Extend, override, or replace any piece."

Principles listed verbatim:

  • Opinionated — defaults tuned for long-horizon, multi-step work
  • Extensible — override or replace any piece without forking
  • Model-agnostic — works with any LLM that supports tool calling: frontier, open-weight, or local
  • Production-ready — built on LangGraph (streaming, persistence, checkpointing) with first-class tracing, evaluation, and deployment via LangSmith

Security Model

The README is explicit: "Deep Agents follows a 'trust the LLM' model. The agent can do anything its tools allow. Enforce boundaries at the tool/sandbox level, not by expecting the model to self-police."

Stack Relationship

All three are layers in the same stack:

  • LangGraph — the graph runtime
  • LangChain create_agent — a minimal harness on top of LangGraph
  • Deep Agents — a more opinionated harness on top of create_agent with filesystem, sub-agents, context management, and skills bundled in

Acknowledgements

README: "Inspired by Claude Code: an attempt to identify what makes it general-purpose, and push that further."

02

Architecture

deepagents (LangChain) — Architecture

Distribution

  • Type: pip package (deepagents on PyPI)
  • Version analyzed: 0.6.3
  • Install: uv add deepagents or pip install deepagents
  • Required runtime: Python >=3.11, <4.0
Package Binary Purpose
deepagents (library, no binary) Core harness library
deepagents-cli deepagents Project scaffolding + deployment (init, dev, deploy)
deepagents-code (dcode) dcode Interactive coding REPL (like Claude Code but model-agnostic)

CLI install: uv tool install deepagents-cli Code agent install: curl -LsSf https://langch.in/dcode | bash

Repository Layout (monorepo under libs/)

libs/
├── deepagents/          # Core Python library (pip: deepagents)
│   └── deepagents/
│       ├── __init__.py  # Public API: create_deep_agent + middleware classes
│       ├── graph.py     # create_deep_agent() — main entry point
│       ├── middleware/  # Pluggable middleware layers
│       │   ├── filesystem.py
│       │   ├── subagents.py
│       │   ├── async_subagents.py
│       │   ├── memory.py
│       │   ├── skills.py
│       │   ├── summarization.py
│       │   ├── patch_tool_calls.py
│       │   └── permissions.py
│       ├── backends/    # Pluggable state + filesystem backends
│       ├── profiles/    # Harness profiles + provider profiles
│       └── _models.py   # Model resolution
├── cli/                 # deepagents-cli package
│   └── deepagents_cli/  # init, dev, deploy subcommands
├── acp/                 # Agent Communication Protocol support
├── code/                # deepagents-code REPL
├── evals/               # Evaluation harness
└── partners/            # Partner integrations

Key Dependencies

  • langchain>=1.3.0 — base agent framework
  • langchain-core>=1.4.0 — core primitives
  • langgraph>=X (via langchain) — graph runtime + checkpointing
  • langsmith>=0.8.3 — tracing + evaluation
  • langchain-anthropic, langchain-google-genai — bundled providers

Target AI Tools

Model-agnostic: any LangChain BaseChatModel with tool calling (OpenAI, Anthropic, Google, Ollama, vLLM, llama.cpp via Baseten/Fireworks).

Config Files

  • pyproject.toml — standard Python packaging
  • LangSmith env vars for tracing (LANGCHAIN_API_KEY, LANGCHAIN_TRACING_V2)
  • Provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
03

Components

deepagents (LangChain) — Components

Primary Entry Point

Name Purpose
create_deep_agent() Factory function in graph.py; assembles all middleware into a LangGraph CompiledStateGraph

Middleware Layer (pluggable, applied in order)

Middleware Class Purpose
FilesystemMiddleware Read/write/edit/search files; pluggable LocalShellBackend, SandboxBackend, RemoteBackend
SubAgentMiddleware Synchronous sub-agent delegation; each sub-agent gets isolated context window
AsyncSubAgentMiddleware Async sub-agent delegation for concurrent work
MemoryMiddleware Persistent cross-session memory via LangGraph store backend
SkillsMiddleware Loadable reusable behaviors the agent can activate on demand
TodoListMiddleware Planning tool: write_todos for task breakdown and progress tracking (from langchain.agents.middleware)
HumanInTheLoopMiddleware Approve/edit/reject tool calls before execution
AnthropicPromptCachingMiddleware Prompt caching for Anthropic models (from langchain_anthropic.middleware)
PatchToolCallsMiddleware Repairs malformed tool calls in conversation history
create_summarization_middleware() Context compaction via LLM summarization

Profile System

Profile Type Purpose
HarnessProfile Base class for per-model behavior overrides
GeneralPurposeSubagentProfile Default sub-agent behavior profile
ProviderProfile Provider-specific defaults (e.g., Anthropic-specific caching)
register_harness_profile() Register custom profiles
register_provider_profile() Register provider-level profiles

Sub-Agent Types

Type Purpose
SubAgent Synchronous delegate agent; defined as CompiledStateGraph or identifier
CompiledSubAgent Pre-compiled LangGraph graph used as a sub-agent
AsyncSubAgent Async variant for concurrent delegation
GENERAL_PURPOSE_SUBAGENT Default sentinel value spawning a recursive deep agent

Backend Abstractions

Backend Purpose
StateBackend Pluggable conversation state + file persistence
BackendProtocol Protocol interface for custom backends
BackendFactory Factory callable for lazy backend creation

CLI Commands (deepagents-cli)

Subcommand Purpose
deepagents init <name> Scaffold a new Deep Agents project folder
deepagents dev Run a local LangGraph dev server against the project
deepagents deploy Bundle and deploy to LangSmith Deployment

No Hooks, No Slash Commands

Deep Agents ships no Claude Code hooks and no slash-command markdown files. It is purely a Python library. Integration with AI coding tools is done by importing the library, not by installing files into .claude/.

05

Prompts

deepagents (LangChain) — Prompts

Excerpt 1: BASE_AGENT_PROMPT (from graph.py)

The verbatim base system prompt baked into every deep agent:

You are a deep agent, an AI assistant that helps users accomplish tasks using tools. You respond with text and tool calls. The user can see your responses and tool outputs in real time.

## Core Behavior

- Be concise and direct. Don't over-explain unless asked.
- NEVER add unnecessary preamble ("Sure!", "Great question!", "I'll now...").
- Don't say "I'll now do X" — just do it.
- If the request is underspecified, ask only the minimum followup needed to take the next useful action.
- If asked how to approach something, explain first, then act.

## Professional Objectivity

- Prioritize accuracy over validating the user's beliefs
- Disagree respectfully when the user is incorrect
- Avoid unnecessary superlatives, praise, or emotional validation

## Doing Tasks

When the user asks you to do something:

1. **Understand first** — read relevant files, check existing patterns. Quick but thorough — gather enough evidence to start, then iterate.
2. **Act** — implement the solution. Work quickly but accurately.
3. **Verify** — check your work against what was asked, not against your own output. Your first attempt is rarely correct — iterate.

Keep working until the task is fully complete. Don't stop partway and explain what you would do — just do it. Only yield back to the user when the task is done or you're genuinely blocked.

**When things go wrong:**

- If something fails repeatedly, stop and analyze *why* — don't keep retrying the same approach.
- If you're blocked, tell the user what's wrong and ask for guidance.

Prompting technique: Instruction-tuned behavioral guide with explicit anti-patterns ("NEVER add unnecessary preamble"). Uses imperative direct style, numbered process steps, and bold callouts. Matches Claude Code's documented style preferences — explicitly derived from studying Claude Code's behavior.

Excerpt 2: AGENTS.md (monorepo contributor prompt)

From the repo root AGENTS.md:

The batteries-included agent harness.

This is the root AGENTS.md; it serves as a one-line context injection for AI agents working in the monorepo. The actual behavior specification lives in graph.py's BASE_AGENT_PROMPT.

Prompting Architecture

  • The base prompt is defined in Python code (BASE_AGENT_PROMPT string in graph.py)
  • Per-model profile overrides can prepend or append to the base prompt via HarnessProfile._apply_profile_prompt()
  • The system_prompt parameter to create_deep_agent() appends user-defined instructions after the base prompt
  • Skills add dynamic behavior injections at runtime
  • No static .md prompt files are shipped; all prompting is code-defined
09

Uniqueness

deepagents (LangChain) — Uniqueness

Differs from Seeds

Deepagents is most architecturally similar to claude-flow among the 11 seeds: both are code-first multi-agent harnesses with sub-agent spawning, persistent memory, context compaction, and production deployment targets. The critical delta is ecosystem: claude-flow is an npm package anchored to Claude Code with 305 MCP tools and a SQLite+HNSW vector store; deepagents is a pip package anchored to LangGraph with pluggable store backends and LangSmith tracing. Deepagents is fully model-agnostic (any LangChain BaseChatModel), while claude-flow is effectively Anthropic-model-first. Unlike superpowers (prompt-only skill files, no code), BMAD-METHOD (persona markdown), or taskmaster-ai (MCP-anchored task management), deepagents lives entirely in Python code with no markdown-convention files.

Distinctive Position

The only harness in the batch that:

  1. Is an official LangChain product (not community-built)
  2. Bundles LangSmith tracing as a required dependency
  3. Uses LangGraph CompiledStateGraph as its runtime primitive
  4. Exposes a complete middleware stack that users can override component by component
  5. Explicitly acknowledges Claude Code as its inspiration

Explicit Anti-Patterns

  • "Don't expect the model to self-police" (from security model)
  • "Don't stop partway and explain what you would do — just do it" (from BASE_AGENT_PROMPT)
  • "NEVER add unnecessary preamble" (from BASE_AGENT_PROMPT)

Observable Failure Modes

  • Heavy dependency on LangSmith infrastructure for production observability — teams avoiding hosted telemetry face friction
  • LangGraph's learning curve: users must understand graph concepts (thread_id, checkpointers, stores) to configure persistence
  • The middleware exclusion pattern requires knowing middleware names as strings — refactoring risk
  • No built-in git automation or per-feature isolation; filesystem writes happen in-place by default
  • deepagents-code and deepagents-cli are separate packages that must be installed independently — confusing for new users

Inspired By

  • Claude Code (explicit acknowledgement in README)
  • LangChain's own create_agent (builds on top of it)
04

Workflow

deepagents (LangChain) — Workflow

Execution Flow

Deep Agents does not impose a fixed workflow. The agent loop is continuous until the task is complete or the model yields. The user provides a message; the agent reasons, uses tools, and loops.

Phases (implicit)

Phase Description Artifact
Instantiation create_deep_agent(model, tools, system_prompt, ...) builds a CompiledStateGraph In-memory graph object
Invocation agent.invoke({"messages": ...}) or agent.stream(...) starts the agent loop Streamed events / final state
Planning (optional) Agent uses write_todos to decompose work In-context todo list
Execution Agent reads/writes files, runs shell commands, calls custom tools File changes, outputs
Delegation Agent spawns sub-agents via task tool for isolated subtasks Sub-agent result messages
Summarization create_summarization_middleware compacts long message threads Summarized conversation state
Checkpointing LangGraph checkpointer persists state after each step Checkpoint in configured store

Approval Gates

  • HumanInTheLoopMiddleware: intercepts tool calls before execution. The user can approve, edit, or reject each tool call. This is opt-in; not enabled by default.
  • InterruptOnConfig: LangGraph interrupt mechanism for conditional human approval.

Configuration Entry Points

agent = create_deep_agent(
    model="openai:gpt-5.5",           # any LangChain chat model
    tools=[my_tool],                   # additional custom tools
    system_prompt="...",               # override base prompt
    subagents=[SubAgent(...)],         # delegate agents
    excluded_middleware=["memory"],    # disable specific middleware
    backend=StateBackend(...),         # custom state backend
)

Excluded Middleware Pattern

Users can disable any built-in middleware layer by name, allowing fine-grained control over which batteries are included in a particular instantiation.

06

Memory Context

deepagents (LangChain) — Memory and Context

Memory Architecture

Deep Agents uses LangGraph's pluggable backend system for both short-term state and long-term memory.

Short-term (in-session) state

  • Stored in LangGraph's CompiledStateGraph state via _DeepAgentState (inherits AgentState)
  • messages field uses a DeltaChannel with custom reducer to keep checkpoint growth O(N) instead of O(N²)
  • Every tool call and response is a message in the LangGraph message list
  • snapshot_frequency=50 controls how often a full snapshot is written vs. delta

Long-term (cross-session) memory

  • MemoryMiddleware provides persistent memory via LangGraph's BaseStore interface
  • Pluggable backends: in-memory, file-based, or external store
  • The store parameter to create_deep_agent() passes a langgraph.store.base.BaseStore
  • checkpointer parameter accepts a LangGraph Checkpointer for conversation replay

Context Compaction

  • create_summarization_middleware() builds a middleware that periodically summarizes long conversation threads
  • Summarization is LLM-powered: older message history is replaced with a summary message
  • Configurable trigger: by message count, token count, or custom condition
  • File-based context offloading: large tool outputs are written to disk and replaced with a file reference in the message thread

Persistence

  • Conversation state: LangGraph checkpointer (in-memory by default; SQLite, PostgreSQL, Redis via LangGraph integrations)
  • Cross-session memory: LangGraph store backend
  • File outputs: StateBackend controls where the agent's filesystem lives (local, sandboxed, remote)

Handoff Pattern

Because deepagents returns a LangGraph CompiledStateGraph, any LangGraph-compatible checkpointer can persist and resume sessions. The thread_id concept from LangGraph provides conversation scoping. Sub-agents run in their own isolated context windows and return results as messages to the parent.

07

Orchestration

deepagents (LangChain) — Orchestration

Multi-Agent Pattern

Deep Agents supports hierarchical sub-agent delegation:

  • The main agent has a task tool that spawns a sub-agent with an isolated context window
  • Sub-agents can themselves spawn sub-agents (recursive delegation)
  • Each sub-agent is a CompiledSubAgent — typically another create_deep_agent() call, or any CompiledStateGraph
  • AsyncSubAgentMiddleware enables concurrent sub-agent execution

Pattern: hierarchical — a parent agent delegates subtasks to named child agents, which report results back to the parent. No peer-to-peer coordination.

Sub-Agent Definition Format

code-class — sub-agents are defined as Python objects (SubAgent, CompiledSubAgent) passed to create_deep_agent(). There are no markdown persona files. The GENERAL_PURPOSE_SUBAGENT constant spawns a recursive deep agent with the same default middleware stack.

Isolation Mechanism

  • Default: LocalShellBackend in virtual mode — writes to the same filesystem as the caller unless virtual_mode=True isolates to a temp dir
  • Sandbox: pluggable SandboxBackend (LangSmith sandbox, Daytona, E2B, Morph, etc.)
  • Remote: RemoteBackend for cloud filesystem targets
  • No git worktrees: no built-in per-feature worktree isolation

Multi-Model

Supported via model parameter per agent instantiation. Each create_deep_agent() call takes an independent model argument. There is no config-file-level role-to-model mapping, but users can create sub-agents with different models:

critic_agent = create_deep_agent(model="anthropic:claude-opus-4-7", ...)
fast_agent = create_deep_agent(model="openai:gpt-5.5", ...)

Execution Mode

interactive-loop for the CLI REPL (dcode). one-shot or programmatic when using the library directly (agent.invoke() returns when done). LangGraph streaming enables event-driven consumption of intermediate outputs.

Crash Recovery

LangGraph checkpointing: if the agent loop is interrupted, it can be resumed from the last checkpoint using the same thread_id. The DeltaChannel on messages ensures checkpoints are compact.

Context Compaction

create_summarization_middleware() handles compaction. Also supports offloading large tool outputs to disk, replacing them with file references in the message thread.

08

Ui Cli Surface

deepagents (LangChain) — UI/CLI Surface

CLI Binary: deepagents (from deepagents-cli)

  • Binary name: deepagents
  • Install: uv tool install deepagents-cli
  • Subcommands:
    • deepagents init <name> — scaffold a new project folder
    • deepagents dev — run local LangGraph dev server
    • deepagents deploy — bundle and deploy to LangSmith Deployment
  • Is thin wrapper: No — it is its own runtime that launches a LangGraph dev server

CLI Binary: dcode (from deepagents-code)

  • Binary name: dcode
  • Install: curl -LsSf https://langch.in/dcode | bash
  • Purpose: Interactive coding agent REPL, analogous to Claude Code but model-agnostic
  • Subcommands: unknown (separate package, limited documentation in this repo)

Local UI

  • LangGraph Studio can connect to a deepagents dev local server — this is a web UI for agent visualization and debugging provided by LangSmith infrastructure, not bundled in the deepagents package itself
  • No dedicated web dashboard is bundled in the deepagents pip package

Observability

  • LangSmith tracing: first-class; langsmith>=0.8.3 is a required dependency
  • Tracing enabled via LANGCHAIN_TRACING_V2=true env var
  • All LangGraph steps, tool calls, and sub-agent invocations appear in the LangSmith trace tree
  • Public trace example provided in the README for demonstration

IDE Integration

None bundled. No .claude/ files, no Cursor config, no VS Code extension. The library is used via Python imports.

Cross-Tool Portability

high — works with any LLM provider via LangChain chat models. No dependency on any specific AI coding tool. The deepagents-code REPL is model-agnostic by design.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k
A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…

Claude-Supermemory ★ 2.6k
A10 Memory engine

Gives Claude Code team-level persistent memory via a cloud API, sharing project knowledge across developers and sessions without…