Simple LLM agents that loop through tool calls are “shallow”—they fail at complex planning, context management, and multi-step workflows. DeepAgents, LangChain’s open-source agent harness (14,000 GitHub stars, trending #4 today), solves this by providing batteries-included defaults for planning, file operations, sub-agents, and context management. Think of it as Claude Code’s architecture made model-agnostic and production-ready. If you’re building AI agents into your product, DeepAgents eliminates the friction of manually assembling prompts, tools, and orchestration logic—you get a working agent immediately.
What Makes DeepAgents “Deep”
Harrison Chase, LangChain’s founder, created DeepAgents to democratize sophisticated agent patterns he observed in Claude Code, OpenAI’s Deep Research, and Manus. The core insight: “Simple LLM-based agents that loop through tool calls tend to be ‘shallow’—they struggle with complex planning and extended task execution.”
Shallow agents hit walls fast. They can’t decompose tasks into manageable steps, overflow their context windows with information, or coordinate specialized subtasks. Try building a research assistant with standard LangChain—you’ll manually wire prompts, implement memory management, design task decomposition logic, and orchestrate tool calls. It works for demos but breaks in production.
DeepAgents provides five superpowers that transform shallow agents into deep ones: explicit planning with visible task lists, filesystem operations for offloading context, sandboxed shell execution, sub-agent spawning for task delegation, and automatic context management. Applications like Claude Code, Deep Research, and Manus all implement this pattern. DeepAgents extracted the harness and made it pip-installable.
Your First DeepAgent in 5 Minutes
Install DeepAgents with a single command. No complex setup, no manual configuration—just pip and you’re ready.
pip install -qU deepagentsHere’s the simplest possible DeepAgent—a weather assistant that demonstrates the core API:
from deepagents import create_deep_agent
def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's always sunny in {city}!"
agent = create_deep_agent(
tools=[get_weather],
system_prompt="You are a helpful assistant",
)
agent.invoke(
{"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)What’s happening under the hood? You defined one tool (a simple function with a docstring), created an agent with that tool and a system prompt, then invoked it with a message. DeepAgents automatically equipped your agent with planning capabilities, file operations, shell execution, sub-agent spawning, and context management. You didn’t request these features—they’re built-in. The agent can now handle complex multi-step tasks, not just weather queries.
Compare this to standard LangChain, where you’d use create_agent and manually add planning tools, implement file operations, design sub-agent coordination, and configure context management yourself. DeepAgents is opinionated—it gives you production-ready defaults immediately.
Five Core Capabilities
DeepAgents provides five capabilities that make agents production-ready. Each solves a specific problem that breaks shallow agents.
Planning with write_todos: The agent can break tasks into discrete steps, track progress visibly in the context window, and adapt plans as new information emerges. This isn’t a side feature—it’s how DeepAgents maintains coherence over long time horizons. The write_todos tool forces explicit task decomposition. Ask the agent to “research Python async patterns and write a blog post,” and it creates a visible task list: research patterns, outline post, write draft, test code examples, revise. Progress tracking prevents the agent from losing track mid-workflow.
Filesystem operations: Six built-in tools (ls, read_file, write_file, edit_file, glob, grep) let agents offload large context to files instead of jamming everything into the LLM’s context window. Research a topic? Write findings to research.md. Generate code? Save to app.py. The filesystem acts as shared workspace where agents and sub-agents collaborate. This solves the context overflow problem that kills shallow agents after a few turns.
Shell execution with execute: Agents can run commands in sandboxed environments. Install packages, run tests, execute scripts—all as part of the agent workflow. Pluggable backends (Modal, Daytona, Deno) provide isolation and security. Want a coding agent that writes tests and runs them? Shell execution makes it possible without manual intervention.
Sub-agent spawning with task: The main agent can delegate specialized subtasks to independent sub-agents with isolated context windows. Architecture: orchestrator plans the research project, spawns a web search sub-agent to gather sources, spawns a data analysis sub-agent to process findings, then synthesizes the results from both. Each sub-agent runs its own loop and returns only the final output. The main agent’s context stays clean while sub-agents go deep on focused tasks.
Context management: DeepAgents automatically summarizes conversations when they get long, integrating with LangGraph’s Memory Store for persistent information retrieval across threads. Your agent won’t forget critical information halfway through a task because the context window filled up. Memory persists across sessions.
Together, these five capabilities enable agents to handle complex workflows that shallow agents can’t touch: research assistants that plan investigations, coding assistants that write and test code iteratively, and data pipeline builders that design, implement, and validate multi-stage processing.
DeepAgents vs Alternatives
Where does DeepAgents fit in the agent framework landscape?
Standard LangChain gives you building blocks (tools, prompts, chains) but requires manual assembly. Full control, more work. Use it for custom workflows and simple agents where you want maximum flexibility. DeepAgents sits on top of LangChain—same foundation, batteries included.
Claude Code provides the best terminal experience for personal coding assistance. It’s proprietary, Claude-only, and deeply integrated into Anthropic’s product. DeepAgents extracted Claude Code’s agent harness architecture and made it model-agnostic and open-source (MIT licensed). The underlying pattern is identical: planning tools, filesystem access, sub-agents, detailed prompts. Community consensus: “If you want the best terminal experience for yourself, Claude Code still wins. If you’re building agents into your product, DeepAgents is the move.”
Manus is a hosted service, not a framework—non-technical users describe tasks and Manus executes them via web browsing and automation. It’s an end-user product. DeepAgents is a developer framework for building custom agent features into your own products.
DeepAgents occupies a unique position: more opinionated than raw LangChain/LangGraph, more flexible than Claude Code (works with any LLM), more developer-focused than Manus, and more production-ready than experimental agent projects like early AutoGPT.
When to Use DeepAgents
Use DeepAgents for multi-step complex workflows: research assistants (plan research → search sources → synthesize findings → write report), coding assistants (design architecture → write code → run tests → debug failures → refactor), and data pipeline builders (design stages → implement transforms → validate output → deploy).
Skip it for simple single-shot queries, non-agentic workflows where standard LLM calls suffice, and quick prototypes where the harness overhead outweighs benefits. One developer summarized: “The investment in the workflow pays for itself many times over in the quality and reliability of the final product for non-trivial features.” Translation: DeepAgents is overkill for trivial tasks but essential for production agent features.
The framework’s growth signals strong developer demand. Released July 27, 2025, it hit 14,000 stars in 8 months and gained 1,418 today (trending #4 on GitHub). LangChain provides an official Academy course, and over 10 tutorials appeared across DataCamp, Medium, and DEV Community in 2026. This isn’t experimental—it’s production-ready infrastructure backed by official support.
Key Takeaways
- Shallow agents loop through tool calls but fail at complex planning, context management, and multi-step workflows—DeepAgents solves this with batteries-included planning, file ops, sub-agents, and context management
- Install with
pip install deepagentsand create agents withcreate_deep_agent—planning, filesystem, shell execution, sub-agents, and memory come built-in automatically - Five core capabilities transform agents:
write_todosfor explicit planning, file tools for context offloading,executefor sandboxed commands,taskfor sub-agent delegation, and automatic context summarization - DeepAgents is Claude Code’s architecture made model-agnostic and open-source (MIT)—use it for product integration, choose Claude Code for personal terminal use
- Use DeepAgents for complex workflows (research, coding, data pipelines) requiring task decomposition and context management—skip it for simple queries where overhead exceeds value
DeepAgents democratizes the agent harness pattern that powers Claude Code, Deep Research, and Manus. It’s model-agnostic (works with OpenAI, Anthropic, any LLM), open-source (MIT licensed), and production-ready from day one. If you’re building AI agents into your product, this is your starting point.
