# hwchase17/deepagents architecture

> Architecture diagram of the GitHub repository hwchase17/deepagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hwchase17/deepagents
- Repository: https://github.com/hwchase17/deepagents

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client / Examples"
        direction TB
        ClientCode["Client Code<br/>(examples/research/research_agent.py)"]:::client
        ExampleGraph["Example Graph Definition<br/>(langgraph.json)"]:::client
        ExampleReq["Example Dependencies<br/>(requirements.txt)"]:::client
    end

    ClientCode -->|"invokes create_deep_agent()"| AgentFactory

    %% Library Layer
    subgraph "DeepAgents Library"
        direction TB
        AgentFactory["create_deep_agent()"]:::internal
        GraphModule["Graph Construction<br/>(graph.py)"]:::internal
        ModelModule["Model Initialization<br/>(model.py)"]:::internal
        PromptsModule["Prompt Templates<br/>(prompts.py)"]:::internal
        ToolsModule["Built-in Tools<br/>(tools.py)"]:::internal
        StateModule["State Store<br/>(state.py)"]:::state
        SubAgentModule["Sub-Agent Manager<br/>(sub_agent.py)"]:::internal
    end

    AgentFactory -->|"builds pipeline"| GraphModule
    AgentFactory -->|"uses prompts"| PromptsModule
    AgentFactory -->|"wires tools"| ToolsModule
    AgentFactory -->|"configures model"| ModelModule
    AgentFactory -->|"manages state"| StateModule
    AgentFactory -->|"handles sub-agents"| SubAgentModule

    %% Execution Pipeline inside Graph
    subgraph "Execution Pipeline (LangGraph)"
        direction TB
        SP["System Prompt Node"]:::internal
        PT["Planning Tool Node"]:::internal
        FS["File System Tools Nodes"]:::internal
        SA["Sub-Agent Dispatcher Node"]:::internal
        LM["LLM Model Node"]:::internal
        SP --> PT --> FS --> SA --> LM
        SA --> FS
        LM --> StateModule
        PT --> StateModule
        FS --> StateModule
    end

    GraphModule -->|"nodes"| SP

    %% State Store
    StateModule ---|"persists plan/files/history"| StateStorage[(Virtual File Store)]:::state

    %% External Services
    subgraph "External Services & APIs"
        direction TB
        LLMCloud["LLM Providers Cloud"]:::external
        InternetSearch["Internet Search (TavilyClient)"]:::external
        MCP["MCP Tools API"]:::external
    end

    LM -->|"LLM call"| LLMCloud
    PT -->|"tool call"| InternetSearch
    ToolsModule -->|"MCP tool call"| MCP

    %% Output back to Client
    StateModule -->|"output messages + files"| ClientCode

    %% Click Events
    click ClientCode "https://github.com/hwchase17/deepagents/blob/master/examples/research/research_agent.py"
    click ExampleGraph "https://github.com/hwchase17/deepagents/blob/master/examples/research/langgraph.json"
    click ExampleReq "https://github.com/hwchase17/deepagents/blob/master/examples/research/requirements.txt"
    click AgentFactory "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/__init__.py"
    click GraphModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/graph.py"
    click ModelModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/model.py"
    click PromptsModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/prompts.py"
    click ToolsModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/tools.py"
    click StateModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/state.py"
    click SubAgentModule "https://github.com/hwchase17/deepagents/blob/master/src/deepagents/sub_agent.py"

    %% Styles
    classDef client fill:#dddddd,stroke:#333,stroke-width:1px
    classDef internal fill:#a8d0e6,stroke:#333,stroke-width:1px
    classDef state fill:#b8e994,stroke:#333,stroke-width:1px
    classDef external fill:#f6bd60,stroke:#333,stroke-width:1px
```
