DeepAgents: LangChain Open-Sourced the Architecture Behind Claude Code

By Prahlad Menon 1 min read

Updated April 2026: DeepAgents has hit v0.5.0, the CLI now has a Skills system and auto-updates, and the project has crossed 20K GitHub stars. Jump to what’s changed →

LangChain’s README for DeepAgents opens with a clear diagnosis:

“Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are ‘shallow’ and fail to plan and act over longer, more complex tasks. Applications like Deep Research, Manus, and Claude Code have gotten around this limitation by implementing a combination of four things: a planning tool, sub agents, access to a file system, and a detailed prompt.”

Then they built it, open-sourced it, and put it on PyPI.

The Four-Component Architecture

This is the insight worth understanding before touching any code. The gap between a toy LLM agent (call a tool, get a result, done) and a real coding agent (Claude Code completing a multi-file refactor) comes down to four things working together:

1. Planning — Before acting, the agent writes a structured task list. DeepAgents uses a write_todos tool that lets the agent decompose work and track progress. This is why Claude Code can work on a 30-step task without losing the thread — it has an explicit plan, not just a conversation history.

2. Filesystem access — read_file, write_file, edit_file, ls, glob, grep. The agent can navigate a codebase, read context, make targeted edits, and verify results. Without this, everything has to be pasted into the prompt.

3. Shell execution — execute with sandboxing. The agent can run tests, install packages, call CLIs, and verify that code actually works. Not just generate it.

4. Sub-agents — A task tool that spawns child agents with isolated context windows. Complex tasks get delegated in parallel. Each sub-agent has its own context, so you’re not burning the parent’s window on implementation details.

These four together are what makes something a deep agent vs a shallow one. DeepAgents gives you all four, pre-wired.

Running It in Five Lines

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "Research LangGraph and write a summary"}]
})

That’s it. The agent plans, reads and writes files, manages its own context window, and can spawn sub-agents as needed — all with defaults already set.

Install:

pip install deepagents
# or
uv add deepagents

Swapping Models

Model-agnostic means you pick the LLM:

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),   # or anthropic:claude-sonnet-4-5, etc.
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)

Same architecture, different brain. This matters if you want to benchmark models on real agentic tasks, run locally with Ollama, or avoid vendor lock-in entirely.

MCP Support

DeepAgents supports MCP (Model Context Protocol) via langchain-mcp-adapters. That means it can plug into any MCP server — the same protocol that Claude uses to connect to external tools, databases, and file systems.

If you’ve been building MCP servers, DeepAgents gives you an open agent harness to connect them to. No proprietary runtime required.

The CLI

There’s also a CLI for running it without writing any Python:

curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

Terminal-native, same architecture underneath. Web search, remote sandboxes, persistent memory, and human-in-the-loop approval are listed as upcoming features.

Why This Matters

Claude Code costs $200/month (or burns fast on API credits). DeepAgents costs nothing and runs on any model you already have access to.

More importantly: it’s inspectable. When Claude Code does something unexpected, you can’t see why. With DeepAgents, every planning step, every tool call, every sub-agent spawn is visible and modifiable. It’s the reference implementation — the thing you read to understand how these systems actually work.

For anyone building on top of LangGraph or trying to understand why Claude Code handles complex tasks so much better than simple agents, this repo is exactly what you want to study.

What’s Changed Since Launch: v0.5 and the CLI

We originally covered DeepAgents when it was fresh off the main branch — v0.4.x, a clean architecture, and a CLI that was basically a launcher. Three weeks later, the project has moved fast. Here’s what’s different.

v0.5.0: The First Major Version Bump

Released April 7, v0.5.0 is a real milestone. The 0.4.x series we wrote about was the foundation — working four-component architecture, model-agnostic design, MCP support. v0.5.0 builds on that with enough changes that upgrading is worth it immediately:

pip install --upgrade deepagents

The repo has crossed ~20K stars and 2.7K forks, which puts it in rare company for a framework that’s barely a month old. For context, LangChain itself took months to hit those numbers.

The CLI Got Serious

The CLI (v0.0.35) went from “convenient launcher” to “actual development environment.” Three things stand out:

Skills system. You can now define reusable capabilities and invoke them by name:

# At startup
deepagents --skill code-review

# Or mid-session
/skill:code-review

This is the same pattern that makes Claude Code’s / commands useful — predefined workflows you can trigger without re-explaining context every time. Write a skill once, use it across projects.

Auto-updates. /update pulls the latest version, /auto-update keeps the CLI current without thinking about it. Small thing, but it means the tool stays fresh as the framework evolves rapidly.

Global dotenv. ~/.deepagents/.env gives you a single place for API keys, model preferences, and configuration. No more per-project .env juggling for common settings. Themes and color overrides are also configurable now — purely cosmetic, but the terminal experience matters when you’re living in it.

ACP: Agents Talking to Agents

The deepagents-acp package adds Agent Communication Protocol support — a structured way for agents to communicate with each other across processes. This is different from the existing sub-agent task tool (which spawns children within a single session). ACP is for inter-agent communication: your DeepAgents instance talking to another agent, or receiving delegated work from an orchestrator.

Worth noting: the ACP implementation includes dangerous shell pattern blocking, which means the protocol is designed with the assumption that connected agents might try to do harmful things. Defense-in-depth, not trust-by-default. Good instinct.

Web Search via Tavily

DeepAgents can now ground responses in live information using Tavily web search integration. This was listed as “upcoming” in the original CLI roadmap — now it’s shipped. For research-heavy tasks, this is the difference between an agent that can only work with what’s in its context and one that can verify facts, find documentation, and pull in current data.

Artifacts Root

CompositeBackend now supports an artifacts_root parameter for organized file output. Instead of agents dumping files wherever, you define a root directory and the backend organizes outputs under it. This sounds minor until you’ve debugged an agent run that scattered 47 files across your working directory.

Eval Framework

CI now has LLM-powered failure analysis, eval tagging, and an auto-regenerated eval catalog. Translation: when a test fails, an LLM analyzes why and categorizes the failure. The eval catalog regenerates automatically, so you can track regressions across the framework’s own test suite.

If you’re building on top of DeepAgents, this eval infrastructure is worth studying — it’s a pattern for testing agentic systems that goes beyond “did the output match the expected string.”

Async Sub-Agents Actually Work Now

The original sub-agent system spawned children but had rough edges with async execution. v0.5.0 fixes callback propagation and interrupt inheritance — meaning parent agents properly receive results from async children, and when you cancel a parent, children actually stop. These are the kinds of bugs that make agentic systems unreliable in production, and they’re now fixed.

REPL Module

A new minimal REPL (feat(repl)) for testing agent configurations without writing a full script. Handy for prototyping prompts, testing tool integrations, or just poking at the framework interactively.

Bottom line: Three weeks ago, DeepAgents was a clean reference implementation. Now it’s becoming a real tool. The Skills system, ACP, and web search move it from “study this to understand coding agents” to “actually use this to build coding agents.” The velocity is impressive — and the architecture is holding up.

How It Fits the Stack

LayerTool
Execution harness (planning, filesystem, shell, sub-agents)DeepAgents
Codebase intelligence (semantic search, AST-aware chunking)SocratiCode
API knowledge (current docs, no hallucination)Context Hub
Persistent memory across sessionssoul.py
Agent isolation and sandboxingNanoClaw

DeepAgents is the engine. The rest of the stack is what makes it reliable and safe to run on real codebases.

GitHub: langchain-ai/deepagents · Related: GitClaw: Git-Native AI Agent Framework · SocratiCode: MCP Codebase Intelligence