🎯 What is DeepAgents?
LangChain's premier framework for creating "deep agents" - sophisticated agents that do complex, open-ended tasks over longer time horizons.
Planning Tools
Break down complex tasks with write_todos
Filesystem Access
read_file, write_file, ls, edit_file, grep_search
Subagent Spawning
Delegate specialized tasks to focused subagents
Pluggable Backends
State, Store, Filesystem, Composite backends
Auto-Optimization
Large result eviction, conversation summarization
Error Recovery
Automatic tool call repair
Perfect for: Complex research, code generation, chatbots, multi-step workflows, and production systems.
Read more: LangChain Blog - Doubling Down on DeepAgents →🗄️ Pluggable Backends
Choose where agent files are stored - transforms DeepAgents into a production-ready agent harness
StateBackend
Persistence: Thread only
Use Case: Scratch space (default)
StoreBackend
Persistence: Forever
Use Case: Long-term memory, chatbots
FilesystemBackend
Persistence: Forever
Use Case: Real project files, code analysis
CompositeBackend
Persistence: Mixed
Use Case: Hybrid strategies (best of all)
📦 Installation
# Install SuperOptiX with DeepAgents support uv tool install superoptix --with "superoptix[frameworks-deepagents]" # REQUIRED: Install Gemini integration (or your preferred LLM provider) uv pip install langchain-google-genai # For Gemini (FREE!) # uv pip install langchain-anthropic # For Claude # uv pip install langchain-openai # For GPT-4
Includes:
- • deepagents 0.7.x with pluggable backends
- • SuperOptiX core with GEPA
- • LangChain, LangGraph integration
Requirements:
- • Python 3.11+
- • Git (for DSPy dependency)
- • API keys for function-calling models
Note: Ollama models are NOT supported by DeepAgents (LangChain limitation). Use Gemini (FREE!), Claude, or GPT-4. For Ollama, use DSPy framework instead.
🚀 Quick Start with Gemini (FREE!)
Get started with DeepAgents using FREE Gemini API
Get FREE API Key
# Get FREE API key from https://aistudio.google.com/app/apikey export GOOGLE_API_KEY="your-gemini-api-key"
Pull Demo Agent
super agent pull research_agent_deepagents
Run the Full Workflow
super agent compile research_agent_deepagents --framework deepagents super agent run research_agent_deepagents --goal "What is LangGraph?" super agent evaluate research_agent_deepagents super agent compile research_agent_deepagents --framework deepagents --optimize super agent optimize research_agent_deepagents --auto light --framework deepagents --reflection-lm ollama:llama3.1:8b # Done! Agent optimized with local Ollama
📚 Demo Agents with Backends
SuperOptiX includes demo agents showcasing different backends
research_agent_deepagents
Basic research (ephemeral)
super agent pull research_agent_deepagents
chatbot_persistent
Persistent chatbot with memory
super agent pull chatbot_persistent
code_reviewer
Real file access for code review
super agent pull code_reviewer
researcher_hybrid
Hybrid storage for complex agents
super agent pull researcher_hybrid
🎯 GEPA Optimization Details
What Gets Optimized
system_prompt
The main instruction to the agent - GEPA automatically analyzes performance, generates variations, tests each, and selects the best.
Key Innovation: GEPA optimizes DeepAgents agents even though they're not DSPy!
Optimization Example
Before:
"You are an expert researcher."After GEPA:
"You are an expert researcher. When answering questions:
1. Use write_todos to plan your research steps
2. Save findings to research_notes.md
3. Synthesize information before responding..."DeepAgents vs DSPy
| Feature | DeepAgents | DSPy |
|---|---|---|
| Framework | LangGraph | DSPy |
| Strength | Complex multi-step tasks | Prompt optimization |
| Planning | Built-in write_todos | Manual implementation |
| Filesystem | Built-in tools | Manual implementation |
| Subagents | Native support | Manual composition |
| Ollama Support | ⚠️ Blocked (LangChain issue) | Full support |
| GEPA Optimization | system_prompt | All signatures (10+) |
When to use DeepAgents:
- Complex research tasks
- Multi-step workflows requiring planning
- Need filesystem for context management
- Want subagent delegation
When to use DSPy:
- Need Ollama/local model support
- Focus on prompt optimization
- Simpler task structures
- Want maximum optimization flexibility
💡 Tips & Best Practices
Use Detailed System Prompts
DeepAgents shine with detailed instructions for role, goal, and backstory
Leverage Planning
Always include write_todos in tools for complex tasks
Use Filesystem for Context
For long outputs, instruct agent to save to files
Start Simple, Then Optimize
Get baseline working, then run GEPA to improve performance