How hwchase17/deepagents works
Project Type and Purpose
• This is a general-purpose Python package (deepagents) for orchestrating multi-step LLM agents (“deep agents”)
• Core goal: combine planning, sub-agents, a virtual file system, and rich prompts around a Language Model
Top-Level Components
• Client code / Examples
– e.g. examples/research/research_agent.py which imports create_deep_agent
– External service clients (e.g. TavilyClient, MCPClient)
• Library package (src/deepagents/)
– graph.py: wraps LangGraph graph construction
– model.py: handles model initialization or override
– prompts.py: built-in system prompt templates
– tools.py: built-in planning tool + file system polymocks
– state.py: LangGraph State wrapper (holds “virtual” files, plan, messages)
– sub_agent.py: logic for spawning and isolating sub-agents
• External Dependencies
– LangGraph (graph execution & State management)
– LangChain (tools, models, MCP adapters)
– LLM providers (Anthropic Claude, OpenAI, Ollama, etc.)
– Optional: Third-party tool APIs (e.g. TavilyClient for internet_search)
Core Architectural Patterns
• Modular “Graph” of nodes (LangGraph) → orchestration pipeline
• Plugin-style tools interface (user functions or @tool objects)
• Context isolation via sub-agents and virtual file system
• Prompt layering: system prompt + user instructions + tool descriptions
a. User / Client Layer
– “Client Code” block (examples or user app)
– Injects: tools list, instructions, optional sub-agents, optional custom model
– Invokes create_deep_agent()
b. Agent Factory (create_deep_agent)
– Builds a LangGraph Graph:
• System Prompt Node (prompts.py)
• Planning Tool Node (tools.py)
• File System Tools Nodes (ls, read_file, etc.)
• Sub-Agent Dispatcher Node (sub_agent.py)
• LLM Model Node (model.py + LangChain wrapper)
– Wires nodes together into pipeline
c. Execution Pipeline
– Input: messages + optional files → Graph
– Graph processes:
1. Combine system prompt + instructions + history
2. (Optional) call planning tool → produce plan stored in State
3. (Optional) spawn sub-agent nodes (context quarantine)
4. Dispatch tool calls to external APIs (e.g. internet_search)
5. Call LLM with augmented prompt → receives next action or answer
6. Update State (files, plan, history)
– Output: messages + updated files (State)
d. External Tools & Services
– Internet search, file mock store, MCP tools, custom LangChain tools
Final Advice
• Be exhaustive in representing all six built-in tools (planning + 4 FS + sub-agent)
• Two kinds of prompts (built-in system + user instructions) feeding into the LLM node
• Optional custom-model path (override LangChain model)
• Don’t overcomplicate: break into main blocks and expand only when needed (e.g., show a sub-agent sub-graph in detail if illustrating sub-agents)