Deep Agents SDK: The Agent Harness
Deep Agents is LangChain's batteries-included agent harness — planning, virtual filesystem, subagent spawning, and context management on top of LangGraph. The decision to reach for it over create_agent is the most important one you will make before writing a single line.
Quick Reference
- →Three-tier model: LangChain (framework) → LangGraph (runtime) → Deep Agents (harness)
- →create_agent for conversational tasks; create_deep_agent for multi-step autonomous work
- →Built-in tools: write_todos, read/write/edit/ls/glob/grep files, task, compact_conversation, ask_user
- →Pluggable backends: StateBackend (dev) → StoreBackend (production) → Sandbox (code execution)
- →Context management: large outputs go to files; conversation summarizes before window overflow
- →v0.5+: async subagents run in background — supervisor keeps working while they execute remotely
- →Any provider supported by LangChain's init_chat_model works: OpenAI, Anthropic, Google, and more
When NOT to Use Deep Agents
Before choosing create_deep_agent, ask: does this task actually need planning, file-based working memory, and subagent delegation? Most tasks don't. The planning tool (write_todos) and the filesystem backend add token overhead every turn. On a 2-turn Q&A workflow, that overhead exceeds the value. The framework launched March 15, 2026 and is still maturing — there is a real cost to being an early adopter.
The package reached v0.5.3 in April 2026. The API stabilized but expect churn in advanced features. Pin your version in production and read the changelog before upgrading.
| Scenario | Right tool | Why |
|---|---|---|
| Conversational Q&A or RAG | create_agent | No planning needed; filesystem overhead hurts latency |
| Single tool call with < 3 turns | create_agent | Simpler, faster, cheaper |
| API wrapper or structured extraction | Anthropic/OpenAI client SDK directly | create_agent is already overkill |
| Multi-step research, code, or writing task | create_deep_agent | Planning + file memory + subagents pay off here |
| Task that runs autonomously for 10+ turns | create_deep_agent | Context management prevents window overflow |
| Parallel sub-tasks with independent context | create_deep_agent | Async subagent isolation is the point |
If you can describe the task as a single prompt and expect an answer in < 3 turns, use create_agent. If you need to describe the task as a project — with stages, intermediate artifacts, and decisions along the way — use create_deep_agent.