# kryvokhyzha/langgraph-agent-toolkit architecture

> Architecture diagram of the GitHub repository kryvokhyzha/langgraph-agent-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kryvokhyzha/langgraph-agent-toolkit
- Repository: https://github.com/kryvokhyzha/langgraph-agent-toolkit

## Overview

##### Project type and purpose
- This is a full-stack Python toolkit + reference application for building, deploying, and interacting with AI agents.
- It comprises three “faces”:
– A FastAPI-based backend service (`langgraph_agent_toolkit/service`)
– A Streamlit frontend UI (`langgraph_agent_toolkit/streamlit_app.py`)
– A Python client library (`langgraph_agent_toolkit/client`)
- Core domain: LangGraph agent orchestration, LLM abstraction (LiteLLM), memory management, observability.

##### File structure
- Top level:
– `configs/` + `docker/` + `docker-compose.yaml` → deployment & env configurations
– `langgraph_agent_toolkit/` → toolkit source, subdivided into agents, core, client, schema, service
– `tests/` → comprehensive test suite (unit + integration + e2e)
- Patterns & modules:
– `agents/blueprints/` → pre-built agent definitions (chatbot, bg tasks, supervisor, etc.)
– `core/` → memory (Postgres/SQLite), LLM factory (OpenAI, fake), observability (Langfuse, Langsmith), prompt/templates
– `service/` → FastAPI app, routes, middleware, error handlers, streaming vs non-streaming endpoints
– `client/` → AgentClient abstraction to call service API programmatically
– `streamlit_app.py` → standalone UI, calls the local/remote service via the client

##### README for architectural clues
- Stack: LangGraph (graph-based agent flows) + FastAPI + Streamlit + Pydantic + LiteLLM + PostgreSQL/SQLite + Langfuse/Langsmith

a. Main components:
– Frontend: Streamlit UI (calls Client)
– Client: `AgentClient` (HTTP/gRPC)
– Backend Service: FastAPI App
– Core Toolkit Modules:
- Agent Executor (orchestrates LangGraph flows)
- LLM Adapter Layer (LiteLLM proxy)
- Memory Store (Postgres/SQLite)
- Observability (Langfuse, Langsmith)
- Prompt Manager (templates, variables)
– External Services / Infrastructure:
- PostgreSQL (persistence)
- Redis (caching, if configured)
- ClickHouse (analytics, optional)
- MinIO (artifact store, optional)
- Langfuse / Langsmith (observability backend)
b. Relationships / data-flows:
1. User interacts with Streamlit UI → issues “run agent” requests
2. UI calls AgentClient → issues HTTP request to FastAPI service
3. FastAPI service authenticates, routes request to AgentExecutor
4. AgentExecutor loads agent blueprint → enters LangGraph flow
5. At each step, LLM Adapter requests tokens from one of the configured LLM providers (via LiteLLM proxy)
6. Memory Store is read/written for context/history
7. Observability hooks log events/traces to Langfuse/Langsmith
8. Final response streams back (via FastAPI) → AgentClient → UI
c. Architectural patterns / principles:
– Layered modularity: clear separation between service, core, agents, client, UI
– Dependency injection via Pydantic settings & factory methods
– Asynchronous, event-driven flows (async/await streaming)
– Pluggable abstractions for LLM, memory, observability
d. Key technologies / libs:
– FastAPI (API + streaming)
– Streamlit (UI)
– Pydantic (settings, schemas)
– LangGraph (flow orchestration)
– LiteLLM (multi-provider LLM proxy)
– Postgres/SQLite (memory)
– Langfuse/Langsmith (observability)
– Docker + docker-compose (deployment)

##### Elements
– Blue: user-facing (UI, Client)
– Green: service/API layer
– Yellow: core business logic modules
– Gray: external infrastructure/datastores
– Purple: observability & analytics

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend Layer
    User("User"):::external
    subgraph "Frontend Layer"
        StreamlitUI["Streamlit UI"]:::frontend
    end

    %% Client Layer
    subgraph "Client Library"
        AgentClient["AgentClient"]:::frontend
    end

    %% Service Layer
    subgraph "Backend Service (FastAPI)" 
        EntryPoint["run_service.py"]:::service
        Factory["factory.py"]:::service
        Routes["routes.py"]:::service
        Handlers["handler.py"]:::service
        Middleware["middleware.py"]:::service
        Exceptions["exception_handlers.py"]:::service
        Types["types.py"]:::service
        UtilsService["utils.py"]:::service
    end

    %% Core Modules
    subgraph "Core Toolkit Modules"
        Executor["AgentExecutor"]:::core
        Blueprints["AgentBlueprints"]:::core
        subgraph "Memory Store"
            MemFactory["factory.py"]:::core
            MemBase["base.py"]:::core
            PostgresAdapter["postgres.py"]:::core
            SQLiteAdapter["sqlite.py"]:::core
        end
        subgraph "LLM Adapter (LiteLLM Proxy)"
            ModelFactory["factory.py"]:::core
            OpenAIModel["chat_openai.py"]:::core
            FakeModel["fake.py"]:::core
        end
        subgraph "Observability"
            ObsFactory["factory.py"]:::observ
            LangfuseObs["langfuse.py"]:::observ
            LangsmithObs["langsmith.py"]:::observ
            ObsBase["base.py"]:::observ
            ObsEmpty["empty.py"]:::observ
        end
        PromptManager["chat_prompt_template.py"]:::core
        Settings["settings.py"]:::core
    end

    %% Helper and Schema
    subgraph "Utilities & Schema"
        HelperUtils["utils.py"]:::core
        Logging["logging.py"]:::core
        Constants["constants.py"]:::core
        SchemaDefs["schema.py & models"]:::core
    end

    %% External Infrastructure
    subgraph "External Services & Datastores"
        PostgresDB["PostgreSQL"]:::external
        RedisCache["Redis (optional)"]:::external
        ClickHouse["ClickHouse (optional)"]:::external
        MinIO["MinIO (optional)"]:::external
        LangfuseExt["Langfuse"]:::observ
        LangsmithExt["Langsmith"]:::observ
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        Configs["configs/"]:::config
        DockerCompose["docker-compose.yaml"]:::config
        DockerSvc["docker/service/Dockerfile"]:::config
        DockerApp["docker/app/Dockerfile"]:::config
    end

    %% Flow Connections
    User -->|"interacts"| StreamlitUI
    StreamlitUI -->|"calls"| AgentClient
    AgentClient -->|"HTTP POST"| EntryPoint
    EntryPoint --> Factory
    Factory --> Routes
    Routes --> Handlers
    Handlers -->|"invoke"| Executor
    Executor --> Blueprints
    Executor --> ModelFactory
    ModelFactory --> OpenAIModel
    ModelFactory --> FakeModel
    Executor --> MemFactory
    MemFactory --> PostgresAdapter
    MemFactory --> SQLiteAdapter
    Executor --> ObsFactory
    ObsFactory --> LangfuseObs
    ObsFactory --> LangsmithObs
    Executor --> PromptManager
    Handlers --> UtilsService
    Executor --> Settings
    Handlers --> Types
    Handlers --> UtilsService
    Executor -->|"logs"| LangfuseExt
    Executor -->|"traces"| LangsmithExt
    PostgresAdapter -->|"SQL read/write"| PostgresDB
    RedisCache --- Executor
    ClickHouse --- Executor
    MinIO --- Executor
    Configs --> EntryPoint
    Configs --> Settings
    DockerCompose --> EntryPoint
    DockerSvc --> EntryPoint
    DockerApp --> StreamlitUI

    %% Click Events
    click StreamlitUI "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/streamlit_app.py"
    click AgentClient "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/client/client.py"
    click EntryPoint "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/run_service.py"
    click Factory "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/factory.py"
    click Routes "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/routes.py"
    click Handlers "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/handler.py"
    click Middleware "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/middleware.py"
    click Exceptions "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/exception_handlers.py"
    click Types "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/types.py"
    click UtilsService "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/service/utils.py"
    click Executor "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/agents/agent_executor.py"
    click Blueprints "https://github.com/kryvokhyzha/langgraph-agent-toolkit/tree/main/langgraph_agent_toolkit/agents/blueprints/"
    click MemFactory "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/memory/factory.py"
    click MemBase "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/memory/base.py"
    click PostgresAdapter "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/memory/postgres.py"
    click SQLiteAdapter "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/memory/sqlite.py"
    click ModelFactory "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/models/factory.py"
    click OpenAIModel "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/models/chat_openai.py"
    click FakeModel "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/models/fake.py"
    click ObsFactory "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/observability/factory.py"
    click LangfuseObs "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/observability/langfuse.py"
    click LangsmithObs "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/observability/langsmith.py"
    click ObsBase "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/observability/base.py"
    click ObsEmpty "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/observability/empty.py"
    click PromptManager "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/prompts/chat_prompt_template.py"
    click Settings "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/langgraph_agent_toolkit/core/settings.py"
    click Configs "https://github.com/kryvokhyzha/langgraph-agent-toolkit/tree/main/configs/"
    click DockerCompose "https://github.com/kryvokhyzha/langgraph-agent-toolkit/blob/main/docker-compose.yaml"
    click DockerSvc "https://github.com/kryvokhyzha/langgraph-agent-toolkit/tree/main/docker/service/Dockerfile"
    click DockerApp "https://github.com/kryvokhyzha/langgraph-agent-toolkit/tree/main/docker/app/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef core fill:#FFF5B1,stroke:#DAA520,color:#DAA520;
    classDef external fill:#EEEEEE,stroke:#A9A9A9,color:#333333;
    classDef observ fill:#F3E5FF,stroke:#800080,color:#800080;
    classDef config fill:#F0F0F0,stroke:#808080,color:#333333;
```
