# vikaskapur/agent-service-toolkit architecture

> Architecture diagram of the GitHub repository vikaskapur/agent-service-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/vikaskapur/agent-service-toolkit
- Repository: https://github.com/vikaskapur/agent-service-toolkit

## Overview

##### Project type and purpose
- This is a full-stack AI agent toolkit. It provides:
- A LangGraph-based agent core (in Python).
- A FastAPI service exposing REST endpoints (streaming & non-streaming).
- A standalone Python client library to call the service.
- A Streamlit frontend that uses the client to provide a chat UI.
- Optional “long-term memory” via PostgreSQL, MongoDB, or SQLite.
- RAG capabilities via ChromaDB plus content moderation via LlamaGuard.

##### File structure
- Top-level:
- docker/ & compose.yaml → Dockerfiles and multi-container setup.
- src/agents/ → all agent definitions and workflows.
- src/service/ → FastAPI app (service.py).
- src/client/ → AgentClient implementation.
- src/streamlit_app.py → Streamlit UI.
- src/core/ → LLM wrapper & settings.
- src/memory/ → pluggable memory backends (postgres, mongodb, sqlite).
- src/schema/ → Pydantic models and request/response schemas.
- run_*.py scripts → entry points for service, client, or standalone agent.
- Tests span unit and integration, including Docker end-to-end.

##### README
- Confirms tech stack: LangGraph (v0.3), FastAPI, Pydantic, Streamlit.
- Mentions three Docker services: postgres, agent_service, streamlit_app.

##### Main components & interactions
a. Agent Core (LangGraph)
- src/agents/ defines multiple agent classes.
- Exposes a uniform “invoke” or “stream” API.
b. FastAPI Service
- src/service/service.py
- Loads agent instances, mounts endpoints: POST /{agent_name}/invoke and /{agent_name}/stream.
- Talks to memory backends and LLM wrapper.
c. Memory Layer
- Pluggable backends under src/memory/.
d. LLM Providers & Moderation
- src/core/llm.py wraps actual LLM calls (OpenAI, VertexAI, Ollama).
- LlamaGuard sits in front for content moderation (Groq API).
e. Client Library
- src/client/client.py → AgentClient.
- Connects to FastAPI endpoints, supports sync/async and streaming.
f. Streamlit App
- src/streamlit_app.py → chat UI.
- Uses AgentClient under the hood.
g. External Services
- OpenAI/VertexAI/Ollama APIs.
- LangSmith for tracing & feedback.
- ChromaDB for vector store in RAG.
h. Docker Compose
- Compose file orchestrates three containers: postgres DB, agent_service, streamlit_app.

##### Relationships & data flow
- User → Streamlit UI → AgentClient → FastAPI Service → Agent Core → LLM & Memory → back to UI.
- External LLM APIs and vector stores are called by Agent Core.
- FastAPI also exposes OpenAPI docs /info for agent discovery.
- UI → Client → Service (HTTP).
- Service → Memory DB (SQL or Mongo).
- Service → LLM Provider (HTTPS).
- Service → Vector Store (ChromaDB) for RAG.
- Feedback loop: user stars → LangSmith.

##### Architectural patterns & principles
- Layered architecture: UI / Client / Service / Core / Data.
- Pluggable interfaces: memory backends, LLM providers.
- Async design: service endpoints use async/await.
- Micro-frontend pattern: separate Streamlit UI container from service container.
- Single-repository monorepo with multi-container deployment.

##### Essential elements
- Clear labels: “Streamlit UI”, “AgentClient”, “FastAPI Service”, “Agent Core”, “Memory Store”, “LLM Provider”.

##### Final advice
- Every component in the repo at a high level—don’t omit memory adapters or the client.
- Docker Compose setup by drawing each container boundary.
- Viewers immediately see the data flow from UI to core agent logic to external services.
- This level of detail will give any engineer a clear blueprint of how to deploy, extend, or debug the system.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% User and UI
    User["User"]:::external
    subgraph "Streamlit Container"
        Streamlit["Streamlit UI"]:::internal
    end

    %% Client Library
    subgraph "Client Container"
        Client["AgentClient"]:::internal
    end

    %% Service Container
    subgraph "Agent Service Container"
        FastAPI["FastAPI Service"]:::internal
        Schema["Schemas (Pydantic)"]:::internal
        Settings["Core Settings"]:::internal
        subgraph "Memory Layer"
            Pg["Postgres Adapter"]:::db
            Mongo["MongoDB Adapter"]:::db
            SQLite["SQLite Adapter"]:::db
        end
        subgraph "Core Components"
            AgentsCore["Agent Core\n(LangGraph)"]:::internal
            LlamaGuard["LlamaGuard"]:::internal
            CoreLLM["LLM Provider"]:::internal
        end
    end

    %% External Services
    subgraph "External Services/APIs"
        OpenAI["OpenAI API"]:::external
        VertexAI["VertexAI API"]:::external
        Ollama["Ollama API"]:::external
        ChromaDB["ChromaDB"]:::external
        LangSmith["LangSmith"]:::external
    end

    %% Data Flow
    User -->|"interacts"| Streamlit
    Streamlit -->|"HTTP/HTTPS"| Client
    Client -->|"HTTP/HTTPS POST /{agent}/invoke"| FastAPI
    FastAPI -->|"uses"| Schema
    FastAPI -->|"loads settings"| Settings
    FastAPI -->|"invokes"| AgentsCore
    AgentsCore -->|"moderate"| LlamaGuard
    LlamaGuard -->|"calls"| CoreLLM
    CoreLLM -.->|"HTTPS"| OpenAI
    CoreLLM -.->|"HTTPS"| VertexAI
    CoreLLM -.->|"HTTPS"| Ollama
    FastAPI -->|"async RAG"| ChromaDB
    FastAPI -.->|"TCP"| Pg
    FastAPI -.->|"TCP"| Mongo
    FastAPI -.->|"TCP"| SQLite
    Streamlit -.->|"feedback stars"| LangSmith

    %% Click Events
    click Streamlit "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/streamlit_app.py"
    click Client "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/client/client.py"
    click FastAPI "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/service/service.py"
    click Schema "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/schema/models.py"
    click Settings "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/core/settings.py"
    click Pg "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/memory/postgres.py"
    click Mongo "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/memory/mongodb.py"
    click SQLite "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/memory/sqlite.py"
    click AgentsCore "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/agents/agents.py"
    click LlamaGuard "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/agents/llama_guard.py"
    click CoreLLM "https://github.com/vikaskapur/agent-service-toolkit/blob/main/src/core/llm.py"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef external fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef db fill:#FFE0B2,stroke:#E65100,color:#E65100
```
