# rupeshksingh/deepagents architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source Python library/package (“deepagents”) that provides a framework for building “deep” LLM-based agents.
- It wraps LangGraph and LangChain, offers built-in planning, file-system simulation, subagent orchestration, and human-in-the-loop tooling.
- It also includes an optional REST API layer (in the `api/` folder), CLI scripts (`main.py`, `react_agent.py`), example usage, and unit tests.

##### Top-Level Components
- Library Core (`src/deepagents/`):
– graph.py: constructs the LangGraph graph for the agent.
– middleware.py: registers planning, filesystem, subagent middleware.
– model.py: creates or configures the LangChain model.
– prompts.py: defines the default detailed system prompt.
– state.py & types.py: state schema and type definitions for the graph.
– tools.py: built-in tools (todos, virtual FS operations).
– logging/ & logging_utils.py: instrumentation and debug logging.

- API Layer (`api/`):
– router.py: FastAPI endpoints to invoke agents via HTTP.
– models.py: Pydantic schemas for requests/responses.
– store.py: in-memory or persistent storage of agent sessions.
– utils.py: common helpers.

- Entry Points:
– main.py & react_agent.py: sample scripts demonstrating how to instantiate and invoke agents.
– tool_utils.py & tools.py at top level: helper wrappers and example external tools.

- Examples (`examples/`):
– research_agent.py: a full “deep research” agent using the library + TavilyClient.
– requirements, sample LangGraph JSON.

- Tests (`test_agent/`):
– unit tests for agent invocation, streaming, memory, tool usage.

##### External Dependencies and Services
- LangGraph: orchestrates the agent as a graph of actions and state transitions.
- LangChain: provides chat models and tool abstractions.
- TavilyClient (example): an external search API for demos.
- FastAPI (in api/): serves HTTP endpoints.
- InMemorySaver (for human-in-the-loop checkpoints).

##### Relationships and Interactions
1) User Code / Scripts (main.py, examples) call create_deep_agent(...)
2) `create_deep_agent` (in deepagents/model.py) → builds a LangGraph graph:
- System prompt node (from prompts.py)
- Planning tool middleware (middleware.py)
- Virtual FS middleware (middleware.py → state.py)
- Subagent middleware (middleware.py)
- Tool invocation nodes (tools.py)
3) Graph executes in a loop:
- Each iteration: send context to LLM (LangChain Chat model) → receives action or text
- If it’s a tool call → use internal virtual FS or external tool function
- Update the LangGraph State (state.py) accordingly
4) API layer (api/router.py) exposes HTTP endpoints that:
- Accept JSON payloads (messages, optional files)
- Look up or create an agent session in `store.py`
- Invoke the agent graph, stream responses back
- Optionally enforce human-in-the-loop via Checkpointer

##### Architectural Patterns and Principles
- Graph-based orchestration (LangGraph) for modular, composable agent behavior.
- Middleware pattern to inject planning, FS, subagent capabilities.
- Dependency injection: user-supplied tools and subagents are passed into the graph builder.
- Virtual file system: isolate agent file operations in JSON state for safety.
- Human-in-the-loop hook points via tool configurations and checkpoints.
- Clear separation: Core library vs. API vs. examples vs. tests.

##### Key Technologies & Libraries
- Python 3.10+
- LangGraph (agent graph)
- LangChain (models, tools)
- FastAPI (optional REST API)
- TavilyClient (example external search)
- Pydantic (API models)
- pytest (unit tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        EP1["main.py"]:::entry
        EP2["react_agent.py"]:::entry
        EP3["tool_utils.py"]:::entry
        EP4["tools.py"]:::entry
    end

    %% Core Library
    subgraph "Core Library"
        GM["graph.py\n(Graph Builder)"]:::core
        MW["middleware.py\n(Middleware)"]:::core
        MC["model.py\n(create_deep_agent)"]:::core
        PR["prompts.py"]:::core
        ST["state.py\n(State Schema)"]:::core
        TP["types.py\n(Type Defs)"]:::core
        TL["tools.py\n(Built-in Tools)"]:::core
        LI["logging.py"]:::core
        LU["logging_utils.py"]:::core
        SR["Subagent Runtime"]:::core
    end

    %% API Layer
    subgraph "API Layer"
        AR["router.py\n(FastAPI Router)"]:::api
        AM["models.py\n(Pydantic Models)"]:::api
        AS["store.py\n(Session Store)"]:::datastore
        AU["utils.py\n(Helpers)"]:::api
    end

    %% Examples
    subgraph "Examples"
        EX1["research_agent.py"]:::examples
        EX2["langgraph.json"]:::examples
        EX3["requirements.txt"]:::examples
    end

    %% Tests
    subgraph "Tests"
        T1["test_agent.py"]:::tests
        T2["test_chat.py"]:::tests
        T3["test_memory.py"]:::tests
        T4["test_streaming.py"]:::tests
    end

    %% External Dependencies
    subgraph "External Dependencies"
        LG["LangGraph Engine"]:::external
        LC["LangChain Model"]:::external
        TC["TavilyClient"]:::external
        HIT["Checkpointer\n(Human-in-loop)"]:::external
    end

    %% Connections
    EP1 -->|invoke| MC
    EP2 -->|invoke| MC
    EP3 -->|provides tools| MC
    EP4 -->|external tools| MC
    EX1 -->|demo usage| MC

    MC -->|builds graph| GM
    MC -->|uses prompt| PR
    MC -->|registers middleware| MW

    MW -->|manages FS & state| ST
    MW -->|injects subagents| SR

    GM -->|updates state| ST
    GM -->|calls tools| TL
    GM -->|orchestrates| LG
    GM -->|streams| LC
    GM -->|spawn| SR
    GM -->|checkpoint| HIT
    SR -->|calls model| LC
    SR -->|calls tools| TL
    TL -->|external API| TC

    AR -->|HTTP invoke| MC
    AR -->|manages sessions| AS
    AR -->|uses schemas| AM
    AR -->|helpers| AU

    T1 -->|tests| MC
    T2 -->|tests| LC
    T3 -->|tests| ST
    T4 -->|tests| GM

    %% Click Events
    click GM "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/graph.py"
    click MW "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/middleware.py"
    click MC "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/model.py"
    click PR "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/prompts.py"
    click ST "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/state.py"
    click TP "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/types.py"
    click TL "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/tools.py"
    click LI "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/logging.py"
    click LU "https://github.com/rupeshksingh/deepagents/blob/master/src/deepagents/logging_utils.py"
    click AR "https://github.com/rupeshksingh/deepagents/blob/master/api/router.py"
    click AM "https://github.com/rupeshksingh/deepagents/blob/master/api/models.py"
    click AS "https://github.com/rupeshksingh/deepagents/blob/master/api/store.py"
    click AU "https://github.com/rupeshksingh/deepagents/blob/master/api/utils.py"
    click EP1 "https://github.com/rupeshksingh/deepagents/blob/master/main.py"
    click EP2 "https://github.com/rupeshksingh/deepagents/blob/master/react_agent.py"
    click EP3 "https://github.com/rupeshksingh/deepagents/blob/master/tool_utils.py"
    click EP4 "https://github.com/rupeshksingh/deepagents/blob/master/tools.py"
    click EX1 "https://github.com/rupeshksingh/deepagents/blob/master/examples/research/research_agent.py"
    click EX2 "https://github.com/rupeshksingh/deepagents/blob/master/examples/research/langgraph.json"
    click EX3 "https://github.com/rupeshksingh/deepagents/blob/master/examples/research/requirements.txt"
    click T1 "https://github.com/rupeshksingh/deepagents/blob/master/test_agent/test_agent.py"
    click T2 "https://github.com/rupeshksingh/deepagents/blob/master/test_agent/test_chat.py"
    click T3 "https://github.com/rupeshksingh/deepagents/blob/master/test_agent/test_memory.py"
    click T4 "https://github.com/rupeshksingh/deepagents/blob/master/test_agent/test_streaming.py"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef api fill:#DFFFE0,stroke:#000,stroke-width:1px
    classDef entry fill:#FFE0B3,stroke:#000,stroke-width:1px
    classDef examples fill:#E5D0FF,stroke:#000,stroke-width:1px
    classDef tests fill:#FFD0D0,stroke:#000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFEFEF,stroke:#000,stroke-width:1px
    class AS datastore
```
