Deep Agents Day 1: 3 Key Differences for LangChain Users

Quick Take

If you only need single‑turn Q&A or simple RAG, LangChain is sufficient. For agents that require planning, file I/O, sub‑agent dispatch, and risk control, Deep Agents offers a ready‑made engineering scaffold.

1. Three Names, One Layered Stack

LangChain, LangGraph, and Deep Agents exist together but serve different layers:

LangChain : basic toolbox – model I/O, prompt templates, tool calls.

LangGraph : execution engine – state‑machine workflows, persistence, streaming, human‑in‑the‑loop.

Deep Agents : default agent implementation – wraps the above and adds out‑of‑the‑box long‑task capabilities.

LangChain gives you parts, LangGraph gives you the runtime, Deep Agents gives you a pre‑assembled agent.

2. Why Add Another Layer?

When building a LangChain agent, the hardest part is not tool calls but reliably completing a long task, such as a code‑refactoring assistant that must read directories, generate TODOs, edit files, spawn sub‑agents, execute commands, and pause for human confirmation.

Hand‑written LangChain agents typically require dozens of lines of glue code to manage todo data structures, virtual file systems, sub‑agent scheduling, and permission checks. Deep Agents bundles these concerns as default behavior, leaving you to focus on business tools, system prompts, and boundary control.

3. Built‑In Tools

Deep Agents ships with a set of common tools, for example: write_todos: task planning and decomposition ls: list virtual file system directories read_file: read file contents write_file: write file contents edit_file: edit existing files glob: pattern‑match files grep: search text in files execute: shell execution (requires a backend that supports it) task: spawn sub‑agents for subtasks

4. Middleware Chain

The main agent is a sequential middleware chain. With deepagents==0.5.3 the chain looks like:

TodoListMiddleware
 → SkillsMiddleware
 → FilesystemMiddleware
 → SubAgentMiddleware
 → SummarizationMiddleware
 → PatchToolCallsMiddleware
 → AsyncSubAgentMiddleware
 → (your middleware=[])
 → Provider extra middleware
 → AnthropicPromptCachingMiddleware
 → MemoryMiddleware
 → HumanInTheLoopMiddleware
 → _PermissionMiddleware

Each middleware is only installed when the corresponding argument (e.g., skills=, memory=, interrupt_on=) is provided. The permission middleware is always the last step, enforcing file‑system rules.

5. Key Parameters of create_deep_agent()

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="...",
    subagents=[...],
    skills=["/skills/project/"],
    memory=["/memory/AGENTS.md"],
    permissions=[...],
    interrupt_on={"write_file": True},
    checkpointer=InMemorySaver(),
    backend=None,
)

Important notes: model can be a provider string or a model instance. tools should contain only your business tools; built‑in tools are added automatically. system_prompt is appended to the base prompt, not replaced. skills expects a list of skill directory paths. memory is suitable for team rule files like AGENTS.md. permissions mainly constrain file‑system tools; they do not cover all shell risks. checkpointer should be an explicit saver instance (e.g., InMemorySaver()) for production.

6. Minimal Example

pip install -qU deepagents langchain-anthropic

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Fetch weather for a city"""
    return f"{city} today is sunny, 25°C"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="You are a weather assistant",
)

result = agent.invoke({"messages": [{"role": "user", "content": "Beijing today?"}]})
print(result["messages"][-1].content)

This runs without a checkpointer, but for multi‑turn stateful agents you should configure one.

7. When to Switch, When Not To

Suitable Scenarios

AI coding assistants – need file I/O, task decomposition, and verification.

Long‑process research – require planning, retrieval, summarization, and context compression.

Enterprise knowledge‑base maintenance – multi‑turn document processing and structured output.

Automated testing agents – execute commands, inspect results, and apply fixes.

Multi‑agent division of labor – a master agent schedules specialized sub‑agents.

Scenarios to Stay with LangChain

Single‑turn Q&A – LangChain or the model SDK is lighter.

Simple RAG – LangChain retrieval chains are more lightweight.

Only a few tools – adding the full Deep Agents stack adds unnecessary weight.

Highly custom workflows – writing a LangGraph state machine gives finer control.

Two hidden pitfalls:

Omitting skills= disables SkillsMiddleware; merely mentioning a skill in the system prompt does nothing.

The default base prompt is long; system_prompt is concatenated, not replaced. To fully control behavior, inspect BASE_AGENT_PROMPT in the source.

My Verdict

Deep Agents is not a replacement for LangChain but a higher‑level default implementation. It handles agent scaffolding, while cloud services, CI runners, key management, and monitoring still need to follow your team’s engineering standards.

Before deciding to adopt, evaluate model API cost, execution boundaries, and auditability of critical operations.