┌─────────────────────────────────────────┐
│ Deep Agents │ ← highest level: batteries included
│ (planning, memory, skills, files) │
├─────────────────────────────────────────┤
│ LangGraph │ ← orchestration: graphs, loops, state
│ (nodes, edges, state, persistence) │
├─────────────────────────────────────────┤
│ LangChain │ ← foundation: models, tools, chains
│ (models, tools, prompts, RAG) │
└─────────────────────────────────────────┘
Picking a higher layer does not cut you off from lower layers — you can use LangGraph graphs inside Deep Agents, and LangChain primitives inside both.
This skill should be loaded at the top of any project before selecting other skills or writing agent code. The framework you choose dictates which other skills to invoke next.
Decision Guide
Answer these questions in order:
| Question |
Yes → |
No → |
| Does the task require breaking work into sub-tasks, managing files across a long session, persistent memory, or loading on-demand skills? |
Deep Agents |
↓ |
| Does the task require complex control flow — loops, dynamic branching, parallel workers, human-in-the-loop, or custom state? |
LangGraph |
↓ |
| Is this a single-purpose agent that takes input, runs tools, and returns a result? |
LangChain (create_agent) |
↓ |
| Is this a pure model call, chain, or retrieval pipeline with no agent loop? |
LangChain (LCEL / chain) |
— |
Framework Profiles
LangChain — Use when the task is focused and self-contained
Best for:
- Single-purpose agents that use a fixed set of tools
- RAG pipelines and document Q&A
- Model calls, prompt templates, output parsing
- Quick prototypes where agent logic is simple
Not ideal when:
- The agent needs to plan across many steps
- State needs to persist across multiple sessions
- Control flow is conditional or iterative
Skills to invoke next: langchain-models, langchain-rag, langchain-middleware
LangGraph — Use when you need to own the control flow
Best for:
- Agents with branching logic or loops (e.g. retry-until-correct, reflection)
- Multi-step workflows where different paths depend on intermediate results
- Human-in-the-loop approval at specific steps
- Parallel fan-out / fan-in (map-reduce patterns)
- Persistent state across invocations within a session
Not ideal when:
- You want planning, file management, and subagent delegation handled for you (use Deep Agents instead)
- The workflow is straightforward enough for a simple agent
Skills to invoke next: langgraph-fundamentals, langgraph-execution, langgraph-persistence
Deep Agents — Use when the task is open-ended and multi-dimensional
Best for:
- Long-running tasks that require breaking work into a todo list
- Agents that need to read, write, and manage files across a session
- Delegating subtasks to specialized subagents
- Loading domain-specific skills on demand
- Persistent memory that survives across multiple sessions
Not ideal when:
- The task is simple enough for a single-purpose agent
- You need precise, hand-crafted control over every graph edge (use LangGraph directly)
Middleware — built-in and extensible:
Deep Agents ships with a built-in middleware layer out of the box — you configure it, you don't implement it. The following come pre-wired; you can also add your own on top:
| Middleware |
What it provides |
Always on? |
TodoListMiddleware |
write_todos tool — agent plans and tracks multi-step tasks |
✓ |
FilesystemMiddleware |
ls, read_file, write_file, edit_file, glob, grep tools |
✓ |
SubAgentMiddleware |
task tool — delegate work to named subagents |
✓ |
SkillsMiddleware |
Load SKILL.md files on demand from a skills directory |
Opt-in |
MemoryMiddleware |
Long-term memory across sessions via a Store instance |
Opt-in |
HumanInTheLoopMiddleware |
Interrupt and request human approval before sensitive tool calls |
Opt-in |
Skills to invoke next: deep-agents-core, deep-agents-memory, deep-agents-orchestration
Mixing Layers
When to mix
| Scenario |
Recommended pattern |
| Main agent needs planning + memory, but one subtask requires precise graph control |
Deep Agents orchestrator → LangGraph subagent |
| Specialized pipeline (e.g. RAG, reflection loop) is called by a broader agent |
LangGraph graph wrapped as a tool or subagent |
| High-level coordination but low-level graph for a specific domain |
Deep Agents + LangGraph compiled graph as a subagent |
How it works in practice
A LangGraph compiled graph can be registered as a subagent inside Deep Agents. This means you can build a tightly-controlled LangGraph workflow (e.g. a retrieval-and-verify loop) and hand it off to the Deep Agents task tool as a named subagent — the Deep Agents orchestrator delegates to it without caring about its internal graph structure.
LangChain tools, chains, and retrievers can be used freely inside both LangGraph nodes and Deep Agents tools — they are the shared building blocks at every level.
Quick Reference
|
LangChain |
LangGraph |
Deep Agents |
| Control flow |
Fixed (tool loop) |
Custom (graph) |
Managed (middleware) |
| Middleware layer |
Callbacks only |
✗ None |
✓ Explicit, configurable |
| Planning |
✗ |
Manual |
✓ TodoListMiddleware |
| File management |
✗ |
Manual |
✓ FilesystemMiddleware |
| Persistent memory |
✗ |
With checkpointer |
✓ MemoryMiddleware |
| Subagent delegation |
✗ |
Manual |
✓ SubAgentMiddleware |
| On-demand skills |
✗ |
✗ |
✓ SkillsMiddleware |
| Human-in-the-loop |
✗ |
Manual interrupt |
✓ HumanInTheLoopMiddleware |
| Custom graph edges |
✗ |
✓ Full control |
Limited |
| Setup complexity |
Low |
Medium |
Low |
| Flexibility |
Medium |
High |
Medium |
Middleware is a concept specific to LangChain (callbacks) and Deep Agents (explicit middleware layer). LangGraph has no middleware — you wire behavior directly into nodes and edges.
1---2name: framework-selection3description: INVOKE THIS SKILL at the START of any LangChain/LangGraph/Deep Agents project, before writing any agent code. Determines which framework layer is right for the task: LangChain, LangGraph, Deep Agents, or a combination. Must be consulted before other agent skills.4---5
6<overview>
7LangChain, LangGraph, and Deep Agents are **layered**, not competing choices. Each builds on the one below it:
8
9```
10┌─────────────────────────────────────────┐
11│ Deep Agents │ ← highest level: batteries included
12│ (planning, memory, skills, files) │
13├─────────────────────────────────────────┤
14│ LangGraph │ ← orchestration: graphs, loops, state
15│ (nodes, edges, state, persistence) │
16├─────────────────────────────────────────┤
17│ LangChain │ ← foundation: models, tools, chains
18│ (models, tools, prompts, RAG) │
19└─────────────────────────────────────────┘
20```
21
22Picking a higher layer does not cut you off from lower layers — you can use LangGraph graphs inside Deep Agents, and LangChain primitives inside both.
23
24> **This skill should be loaded at the top of any project before selecting other skills or writing agent code.** The framework you choose dictates which other skills to invoke next.
25</overview>
26
27---
28
29## Decision Guide
30
31<decision-table>
32
33Answer these questions in order:
34
35| Question | Yes → | No → |
36|----------|-------|-------|
37| Does the task require breaking work into sub-tasks, managing files across a long session, persistent memory, or loading on-demand skills? | **Deep Agents** | ↓ |
38| Does the task require complex control flow — loops, dynamic branching, parallel workers, human-in-the-loop, or custom state? | **LangGraph** | ↓ |
39| Is this a single-purpose agent that takes input, runs tools, and returns a result? | **LangChain** (`create_agent`) | ↓ |
40| Is this a pure model call, chain, or retrieval pipeline with no agent loop? | **LangChain** (LCEL / chain) | — |
41
42</decision-table>
43
44---
45
46## Framework Profiles
47
48<langchain-profile>
49
50### LangChain — Use when the task is focused and self-contained
51
52**Best for:**
53- Single-purpose agents that use a fixed set of tools
54- RAG pipelines and document Q&A
55- Model calls, prompt templates, output parsing
56- Quick prototypes where agent logic is simple
57
58**Not ideal when:**
59- The agent needs to plan across many steps
60- State needs to persist across multiple sessions
61- Control flow is conditional or iterative
62
63**Skills to invoke next:** `langchain-models`, `langchain-rag`, `langchain-middleware`
64
65</langchain-profile>
66
67<langgraph-profile>
68
69### LangGraph — Use when you need to own the control flow
70
71**Best for:**
72- Agents with branching logic or loops (e.g. retry-until-correct, reflection)
73- Multi-step workflows where different paths depend on intermediate results
74- Human-in-the-loop approval at specific steps
75- Parallel fan-out / fan-in (map-reduce patterns)
76- Persistent state across invocations within a session
77
78**Not ideal when:**
79- You want planning, file management, and subagent delegation handled for you (use Deep Agents instead)
80- The workflow is straightforward enough for a simple agent
81
82**Skills to invoke next:** `langgraph-fundamentals`, `langgraph-execution`, `langgraph-persistence`
83
84</langgraph-profile>
85
86<deep-agents-profile>
87
88### Deep Agents — Use when the task is open-ended and multi-dimensional
89
90**Best for:**
91- Long-running tasks that require breaking work into a todo list
92- Agents that need to read, write, and manage files across a session
93- Delegating subtasks to specialized subagents
94- Loading domain-specific skills on demand
95- Persistent memory that survives across multiple sessions
96
97**Not ideal when:**
98- The task is simple enough for a single-purpose agent
99- You need precise, hand-crafted control over every graph edge (use LangGraph directly)
100
101**Middleware — built-in and extensible:**
102
103Deep Agents ships with a built-in middleware layer out of the box — you configure it, you don't implement it. The following come pre-wired; you can also add your own on top:
104
105| Middleware | What it provides | Always on? |
106|------------|-----------------|------------|
107| `TodoListMiddleware` | `write_todos` tool — agent plans and tracks multi-step tasks | ✓ |
108| `FilesystemMiddleware` | `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` tools | ✓ |
109| `SubAgentMiddleware` | `task` tool — delegate work to named subagents | ✓ |
110| `SkillsMiddleware` | Load SKILL.md files on demand from a skills directory | Opt-in |
111| `MemoryMiddleware` | Long-term memory across sessions via a `Store` instance | Opt-in |
112| `HumanInTheLoopMiddleware` | Interrupt and request human approval before sensitive tool calls | Opt-in |
113
114**Skills to invoke next:** `deep-agents-core`, `deep-agents-memory`, `deep-agents-orchestration`
115
116</deep-agents-profile>
117
118---
119
120## Mixing Layers
121
122<mixing-layers>
123Because the frameworks are layered, they can be combined in the same project. The most common pattern is using Deep Agents as the top-level orchestrator while dropping down to LangGraph for specialized subagents.
124
125### When to mix
126
127| Scenario | Recommended pattern |
128|----------|---------------------|
129| Main agent needs planning + memory, but one subtask requires precise graph control | Deep Agents orchestrator → LangGraph subagent |
130| Specialized pipeline (e.g. RAG, reflection loop) is called by a broader agent | LangGraph graph wrapped as a tool or subagent |
131| High-level coordination but low-level graph for a specific domain | Deep Agents + LangGraph compiled graph as a subagent |
132
133### How it works in practice
134
135A LangGraph compiled graph can be registered as a subagent inside Deep Agents. This means you can build a tightly-controlled LangGraph workflow (e.g. a retrieval-and-verify loop) and hand it off to the Deep Agents `task` tool as a named subagent — the Deep Agents orchestrator delegates to it without caring about its internal graph structure.
136
137LangChain tools, chains, and retrievers can be used freely inside both LangGraph nodes and Deep Agents tools — they are the shared building blocks at every level.
138
139</mixing-layers>
140
141---
142
143## Quick Reference
144
145<quick-reference>
146
147| | LangChain | LangGraph | Deep Agents |
148|---|-----------|-----------|-------------|
149| **Control flow** | Fixed (tool loop) | Custom (graph) | Managed (middleware) |
150| **Middleware layer** | Callbacks only | ✗ None | ✓ Explicit, configurable |
151| **Planning** | ✗ | Manual | ✓ TodoListMiddleware |
152| **File management** | ✗ | Manual | ✓ FilesystemMiddleware |
153| **Persistent memory** | ✗ | With checkpointer | ✓ MemoryMiddleware |
154| **Subagent delegation** | ✗ | Manual | ✓ SubAgentMiddleware |
155| **On-demand skills** | ✗ | ✗ | ✓ SkillsMiddleware |
156| **Human-in-the-loop** | ✗ | Manual interrupt | ✓ HumanInTheLoopMiddleware |
157| **Custom graph edges** | ✗ | ✓ Full control | Limited |
158| **Setup complexity** | Low | Medium | Low |
159| **Flexibility** | Medium | High | Medium |
160
161> **Middleware is a concept specific to LangChain (callbacks) and Deep Agents (explicit middleware layer). LangGraph has no middleware — you wire behavior directly into nodes and edges.**
162
163</quick-reference>
jackjin1997