# langchain-ai/langgraph-supervisor-py architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/langgraph-supervisor-py
- Repository: https://github.com/langchain-ai/langgraph-supervisor-py

## Overview

##### Project Type & Purpose
- This is an **open-source Python library** that builds on top of LangGraph to create **hierarchical multi-agent systems**.
- It provides core modules for defining a **supervisor agent**, **specialized sub-agents**, and a **tool-based handoff mechanism**.

##### High-Level Components
From your code and README, identify these main blocks:
A. **User Application (Top Layer)**
– Code that imports `langgraph_supervisor` and `langgraph` APIs.
– Constructs specialized agents (React or Functional API) and a supervisor workflow.
– Calls `.compile()` and invokes the resulting application.

B. **langgraph_supervisor Library (Core Layer)**
– **supervisor.py**: `create_supervisor()` function, orchestrates a `StateGraph` with sub-graphs for each agent.
– **handoff.py**: Default and custom handoff tool definitions (`create_handoff_tool`) for message‐based delegation.
– **agent_name.py**: Utilities to manage/resolve agent names in the graph.

C. **LangGraph & LangChain Integration (Framework Layer)**
– Underlying graph engine (`StateGraph`, `Command`, `InjectedState`).
– Prebuilt React‐style agents from LangGraph (`create_react_agent`).
– Functional API decorators (`@task`, `@entrypoint`).

D. **External Services & Data Stores**
– **LLM Provider**: e.g. OpenAI API (via `ChatOpenAI`).
– **Tool Endpoints**: Web search function or any custom Python tool.
– **Memory/Checkpoint Store** (optional): In-memory or persistent store for histories.

##### Relationships & Data Flow
1. **User Application** ➔ calls **create_react_agent**/**@entrypoint** ➔ defines **Agent Sub-graphs**.
2. **User Application** ➔ calls **create_supervisor(agents, …)** ➔ builds a **Supervisor Graph**.
3. **Supervisor Graph**
– Maintains global `state["messages"]` and `state["active_agent"]`.
– Exposes **handoff tools** that the LLM can “call” to switch context to sub-agents.
4. **Agent Sub-graphs**
– Receive messages, call the **LLM provider** or custom tools.
– Return responses to the supervisor graph via `Command`.
5. **Compile & Invoke**
– `.compile()` wires everything into a runnable app object.
– `.invoke({"messages": [...]})` kicks off the supervisor entrypoint.
6. **Optional Memory**
– During compile, user can inject a **checkpointer** or **store** which the graph uses to persist state.

##### Architectural Patterns & Principles
- **Hierarchical Multi-Agent**: A tree of graphs (supervisor ➔ sub-agents ➔ optional sub-supervisors).
- **Tool-Based Delegation**: Supervisor uses first-class tool calls to hand off tasks.
- **Functional vs Graph API**: Your library supports both declarative graph definitions and decorator-based tasks.
- **Separation of Concerns**:
– **Supervisor logic** vs **Agent logic** vs **Tool implementations**.
– **State management** abstracted in LangGraph’s `StateGraph`.

##### Final Checklist
– Clear component names matching module/file names.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application" 
        direction TB
        UA1["Create React Agent"]:::user
        UA2["Define Functional Agent"]:::user
        UA3["Call create_supervisor(agents, ...)"]:::user
        UA4[".compile()"]:::user
        UA5[".invoke({messages})"]:::user
    end

    %% Library Core Layer
    subgraph "LangGraph Supervisor Library"
        direction TB
        LM1["supervisor.py"]:::lib
        LM2["handoff.py"]:::lib
        LM3["agent_name.py"]:::lib
        LM4["__init__.py"]:::lib
        LM5["py.typed"]:::lib
        Config["pyproject.toml"]:::lib
        Readme["README.md"]:::lib
        Tests1["tests/test_supervisor.py"]:::lib
        Tests2["tests/test_supervisor_functional_api.py"]:::lib
        Tests3["tests/test_agent_name.py"]:::lib
    end

    %% LangGraph & LangChain Integration
    subgraph "Framework Layer"
        direction TB
        FG1["StateGraph"]:::framework
        FG2["create_react_agent"]:::framework
        FG3["@task/@entrypoint"]:::framework
    end

    %% Supervisor Graph
    subgraph "Supervisor Graph" 
        direction TB
        GS["Global State (messages, active_agent)"]:::state
        HT["Handoff Tools"]:::state
        subgraph "Agent Sub-graph A"
            direction TB
            LLM_A["LLM Call"]:::external
            Tool_A["Optional Tool Call"]:::external
        end
        subgraph "Agent Sub-graph B"
            direction TB
            LLM_B["LLM Call"]:::external
            Tool_B["Optional Tool Call"]:::external
        end
        GS --> HT
        HT -->|"delegate task"| AgentA
        HT -->|"delegate task"| AgentB
    end

    %% External Services & Data Stores
    OpenAI["OpenAI API"]:::external
    WebSearch["Web Search Service"]:::external
    Memory["Memory Store"]:::store

    %% Application Runner
    Runner["Application Runner"]:::user

    %% Connections
    UA1 -->|uses| FG2
    UA2 -->|uses| FG3
    UA3 -->|imports & calls| LM1
    UA3 -->|imports & calls| LM2
    UA3 -->|imports & calls| LM3
    LM1 -->|orchestrates| FG1
    LM1 -->|uses tool defs| LM2
    LM1 -->|uses name utils| LM3
    FG2 -->|builds sub-graph| AgentA
    FG3 -->|builds sub-graph| AgentB
    AgentA -->|calls| LLM_A
    AgentA -->|calls| Tool_A
    AgentB -->|calls| LLM_B
    AgentB -->|calls| Tool_B
    LLM_A -->|LLM API call| OpenAI
    LLM_B -->|LLM API call| OpenAI
    Tool_A -->|tool endpoint call| WebSearch
    Tool_B -->|tool endpoint call| WebSearch
    GS -->|persist/restore| Memory
    UA4 -->|wires into| Runner
    UA5 -->|invokes entrypoint| GS
    Runner -->|runs graph| GS
    GS -->|returns| UA5

    %% Click Events
    click LM1 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/langgraph_supervisor/supervisor.py"
    click LM2 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/langgraph_supervisor/handoff.py"
    click LM3 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/langgraph_supervisor/agent_name.py"
    click LM4 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/langgraph_supervisor/__init__.py"
    click LM5 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/langgraph_supervisor/py.typed"
    click Config "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/pyproject.toml"
    click Readme "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/README.md"
    click Tests1 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/tests/test_supervisor.py"
    click Tests2 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/tests/test_supervisor_functional_api.py"
    click Tests3 "https://github.com/langchain-ai/langgraph-supervisor-py/blob/main/tests/test_agent_name.py"

    %% Styles
    classDef user fill:#E8F0FE,stroke:#3182BD,color:#0B3C5D;
    classDef lib fill:#FDE2E4,stroke:#D81159,color:#7F1734;
    classDef framework fill:#FFF4E1,stroke:#F08A5D,color:#663F2C;
    classDef state fill:#E1F4E1,stroke:#2F855A,color:#1A472A;
    classDef external fill:#F0F0F0,stroke:#4A5568,color:#2D3748;
    classDef store fill:#E1F4E1,stroke:#2F855A,color:#1A472A;
```
