# fareedkhan-dev/multi-agent-ai-system architecture

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

- Interactive diagram: https://gitdiagram.com/fareedkhan-dev/multi-agent-ai-system
- Repository: https://github.com/fareedkhan-dev/multi-agent-ai-system

## Overview

##### Project type and purpose
- This is a Python‐based, notebook‐driven proof-of-concept for a multi-agent AI system. It combines small “ReAct” sub-agents into a supervisor-controlled workflow to answer customer support queries (music catalog lookups, invoice inquiries), while managing short- and long-term memory and human-in-the-loop verification.

##### File structure
- .env: holds API keys for OpenAI, LangSmith, etc.
- requirements.txt: lists Python dependencies (LangChain, LangGraph, LangSmith, SQLite driver, SQLAlchemy).
- multi_agent.ipynb: the main Jupyter notebook that assembles the workflow, defines tools, nodes, graphs, tests, and evaluation.
- utils.py: helper functions (e.g., show_graph) for visualizing the LangGraph StateGraph.

##### Key insights from README
- Two core sub-agents:
1. catalog_information_subagent – handles music catalog queries via SQL tools against an in-memory SQLite (Chinook) database
2. invoice_information_subagent – handles invoice lookup queries, also via SQL tools
- A supervisor agent routes user queries to the correct sub-agent(s) and merges results.
- Human-in-the-loop verification layer ensures the customer ID is validated before exposing sensitive data.
- Short-term memory via MemorySaver (conversation state) and long-term memory via InMemoryStore (user profiles).
- Final “create_memory” step updates user profiles with newly discovered preferences.
- Evaluation harness using LangSmith and LLM-as-judge patterns.

##### Detail without overcomplexity
- Every major component and data store.
- Core ReAct loop abstractly (Assistant Node ↔ Tool Node) rather than each individual tool query.
- Memory load/save steps are visible in the main flow.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface"
        User["User"]:::userIO
        Notebook["Jupyter Notebook"]:::external
    end
    click Notebook "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/multi_agent.ipynb"

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        LangSmith["LangSmith Tracing"]:::external
        LangGraph["LangGraph Runtime"]:::external
    end
    click OpenAI "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/.env"
    click LangSmith "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/.env"

    %% Verification Layer
    subgraph "Verification Layer"
        Verify["Verify Info"]:::human
        HumanInput["Human Input"]:::human
    end

    %% Memory Layer
    subgraph "Memory Layer"
        ShortMem["MemorySaver (Short-term)"]:::memory
        LongMem["InMemoryStore (Long-term)"]:::memory
    end

    %% Multi-Agent Core
    subgraph "Multi-Agent Core"
        Supervisor["Supervisor Agent"]:::agent
        subgraph "Sub-agents"
            MusicAgent["Music Catalog Sub-agent"]:::agent
            InvoiceAgent["Invoice Info Sub-agent"]:::agent
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["SQLite (Chinook) DB"]:::data
    end

    %% Evaluation Layer
    subgraph "Evaluation"
        Dataset["Example Dataset"]:::external
        EvalHarness["Evaluation Harness"]:::external
        Dashboard["LangSmith Dashboard"]:::external
    end

    %% Project Files
    subgraph "Project Files"
        Env[".env"]:::external
        Req["requirements.txt"]:::external
        Utils["utils.py"]:::external
        Images["images/"]:::external
        Readme["README.md"]:::external
        License["LICENSE"]:::external
    end
    click Env "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/.env"
    click Req "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/requirements.txt"
    click Utils "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/utils.py"
    click Images "https://github.com/fareedkhan-dev/multi-agent-ai-system/tree/main/images/"
    click Readme "https://github.com/fareedkhan-dev/multi-agent-ai-system/blob/main/README.md"
    click License "https://github.com/fareedkhan-dev/multi-agent-ai-system/tree/main/LICENSE"

    %% Connections
    User --> Notebook
    Notebook --> Verify
    Verify -->|"if customer_id missing"| HumanInput
    HumanInput --> Verify
    Verify -->|"customer_id"| Supervisor
    Notebook -->|"load_memory"| LongMem
    LongMem --> Supervisor
    Supervisor --> MusicAgent
    Supervisor --> InvoiceAgent
    MusicAgent -->|"invoke tool"| DB
    InvoiceAgent -->|"invoke tool"| DB
    MusicAgent <--> ShortMem
    InvoiceAgent <--> ShortMem
    Supervisor -->|"create_memory"| LongMem
    Supervisor --> Notebook
    Supervisor -->|"trace"| LangSmith
    Supervisor --> LangGraph
    OpenAI --> MusicAgent
    OpenAI --> InvoiceAgent
    Notebook -->|"run_graph"| EvalHarness
    EvalHarness --> Dataset
    EvalHarness --> Dashboard

    %% Styles
    classDef agent fill:#bbdefb,stroke:#1e88e5,color:#0d47a1,stroke-width:2px
    classDef memory fill:#c8e6c9,stroke:#43a047,color:#1b5e20,stroke-width:2px
    classDef data fill:#ffe0b2,stroke:#fb8c00,color:#e65100,stroke-width:2px
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#424242,stroke-width:2px
    classDef human fill:#fff9c4,stroke:#fbc02d,color:#f57f17,stroke-width:2px
    classDef userIO fill:#d1c4e9,stroke:#7e57c2,color:#311b92,stroke-width:2px
```
