# langchain-ai/deep-agents-from-scratch architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/deep-agents-from-scratch
- Repository: https://github.com/langchain-ai/deep-agents-from-scratch

## Overview

##### Project type and purpose
- This is a Python-based tutorial library plus Jupyter notebooks for incrementally building “deep” AI agents using LangGraph.
- It’s not a web or frontend/backend full-stack app but an SDK (src/deep_agents_from_scratch) combined with five interactive notebooks that demonstrate how to assemble agent components (ReAct loop, TODO planner, file system, sub-agents) and hook them up to external APIs (Anthropic, Tavily, Langsmith).

##### File structure
- Top-level:
- notebooks/ – five sequential Jupyter notebooks + assets + a utils helper.
- src/deep_agents_from_scratch/ – Python package modules:
– file_tools.py  (virtual FS operations)
– prompts.py     (prompt templates for ReAct, tasks)
– research_tools.py (search, summarization)
– state.py       (agent state container)
– task_tool.py   (create_agent core, ReAct loop)
– todo_tools.py  (TODO list planner)
- example.env, pyproject.toml, uv.lock – environment and dependency management.

##### README
- Describes progressive agent patterns: Task Planning, File System, Sub-agents, culminating in a Full Agent.
- Lists external dependencies: Python 3.11+, LangGraph via uv, APIs for Anthropic (LLM), Tavily (search), Langsmith (logging/tracing).

a. Main components
- User Interface Layer: Jupyter Notebooks (“0_create_agent” → “4_full_agent”)
- Core Agent Engine: task_tool.py (ReAct loop & create_agent API)
- Tool Modules:
- TODO Planner (todo_tools.py)
- Virtual File System (file_tools.py + state.py)
- Research Tools (research_tools.py)
- Prompt Templates: prompts.py
- State Management: state.py (holds memory, files, todo lists)
- Sub-Agent Manager: sub-agent registry & delegation within task_tool.py + research_tools.py
- External Services:
- LLM API (Anthropic)
- Web Search API (Tavily)
- Tracing/Logging (Langsmith)

b. Relationships & data flow
1. Notebook invokes create_agent(...) from task_tool.py.
2. Agent Engine initializes State, registers Tools, loads Prompt templates.
3. ReAct Loop:
– Agent constructs prompt via prompts.py → sends to LLM API → receives response → Decide: call tool or return final answer.
– Tool invocation: e.g., file_tools calls State to read/write; research_tools calls external search or summarization; todo_tools updates State.todo_list.
– Sub-agent branch: delegate a new create_agent instance with restricted tool set.
4. State persists across turns, held in-memory in state.py.
5. If LANGSMITH_TRACING enabled, every call and state transition is sent to Langsmith.

c. Architectural patterns & principles
- Modular Tool-based Agent: clear separation of core engine vs. individual tools.
- ReAct Loop Pattern: chain of thought + action calls.
- Context Offloading: virtual file system as memory to reduce token use.
- Delegation & Isolation: spawn sub-agents with limited scope.
- Progressive Composition: notebooks build incrementally on prior components.

d. Key technologies & frameworks
- Python 3.11+, LangGraph SDK (via uv package manager)
- Jupyter Notebooks for interactive demos
- Anthropic API for LLM calls
- Tavily API for external research search
- Langsmith for tracing & evaluation

##### Elements
- Rectangles (or containers) for each module: Task Engine, TODO, File Tools, Research Tools, State, Prompts.
- Notebooks → Agent Engine.create_agent()
- Agent Engine ↔ LLM API (prompt → response)
- Agent Engine → Tool Modules → State or External API → back to Engine
- Core engine (blue), Tools (green), State & Prompts (orange), External (purple), UI (gray).

##### Detailed call-out items
- Sub-agent invocation: “Engine spawns Sub-agent with restricted tool set.”
- State store as the single source of truth for memory, files, and todo lists.
- Optional tracing channel to Langsmith for telemetry.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        Folder["Notebooks/"]:::ui
        UI0["0_create_agent.ipynb"]:::ui
        UI1["1_todo.ipynb"]:::ui
        UI2["2_files.ipynb"]:::ui
        UI3["3_subagents.ipynb"]:::ui
        UI4["4_full_agent.ipynb"]:::ui
        Utils["utils.py"]:::ui
    end

    %% Core Engine
    subgraph "Core Agent Engine"
        Engine["TaskEngine\n(ReAct Loop & create_agent)"]:::core
    end

    %% Tool Modules
    subgraph "Tool Modules"
        TODO["TODO Planner"]:::tool
        FS["Virtual File System"]:::tool
        Research["Research Tools"]:::tool
    end

    %% State & Prompts
    subgraph "State & Prompts"
        State["State Management"]:::data
        Prompts["Prompt Templates"]:::data
    end

    %% External Services
    subgraph "External Services"
        LLM["Anthropic LLM API"]:::external
        Search["Tavily Search API"]:::external
        Tracing["Langsmith Tracing"]:::external
    end

    %% Connections
    Folder --> UI0
    Folder --> UI1
    Folder --> UI2
    Folder --> UI3
    Folder --> UI4
    Folder --> Utils

    UI0 -->|"invoke create_agent()"| Engine
    UI1 -->|"invoke create_agent()"| Engine
    UI2 -->|"invoke create_agent()"| Engine
    UI3 -->|"invoke create_agent()"| Engine
    UI4 -->|"invoke create_agent()"| Engine

    Engine -->|"loads prompts"| Prompts
    Engine -->|"init state"| State
    Engine -->|"ReAct: prompt→LLM"| LLM
    LLM -->|"response"| Engine

    Engine -->|"calls tool"| TODO
    Engine -->|"calls tool"| FS
    Engine -->|"calls tool"| Research

    TODO -->|"update todo list"| State
    FS -->|"read/write files"| State
    Research -->|"search/summarize"| Search
    Research -->|"store results"| State
    Search -->|"results"| Research

    Engine -.->|"spawns sub-agent"| Engine

    Engine -->|optional tracing| Tracing
    State -->|telemetry| Tracing

    %% Click Events
    click Folder "https://github.com/langchain-ai/deep-agents-from-scratch/tree/main/notebooks/"
    click UI0 "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/0_create_agent.ipynb"
    click UI1 "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/1_todo.ipynb"
    click UI2 "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/2_files.ipynb"
    click UI3 "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/3_subagents.ipynb"
    click UI4 "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/4_full_agent.ipynb"
    click Utils "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/notebooks/utils.py"
    click Engine "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/task_tool.py"
    click TODO "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/todo_tools.py"
    click FS "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/file_tools.py"
    click Research "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/research_tools.py"
    click Prompts "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/prompts.py"
    click State "https://github.com/langchain-ai/deep-agents-from-scratch/blob/main/src/deep_agents_from_scratch/state.py"

    %% Styles
    classDef ui fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef core fill:#afdfff,stroke:#333,stroke-width:1px
    classDef tool fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef data fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#d1c4e9,stroke:#333,stroke-width:1px
```
