# chamodshehanka/kagent architecture

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

- Interactive diagram: https://gitdiagram.com/chamodshehanka/kagent
- Repository: https://github.com/chamodshehanka/kagent

## Overview

##### Project type and core purpose
- kagent is a full-stack, Kubernetes-native AI-agent framework.
- It comprises:
–  A **Kubernetes Operator** (the Controller) for CRD reconciliation
–  A **Python Engine** (Autogen-based) for running agents
–  A **Go CLI** for local cluster/CRD management and agent invocation
–  A **Next.js UI** for web-based management

##### File structure and map to high-level components
Top-level directories:
- go/cli → the `kagent` CLI binary (uses `go/autogen/client`)
- go/controller → the Kubernetes Controller (custom-resource watchers + HTTP server)
- python/ → the Engine service (Autogen-based; REST API + session/memory/db managers)
- ui/ → the Next.js React UI (static + dynamic routes)
- helm/ → Helm charts and CRD manifests for cluster installation

##### README architecture summary
The README calls out four core components:
- **Controller** – Kubernetes operator
- **UI** – Next.js app
- **Engine** – Python Autogen service
- **CLI** – Go command-line tool

##### Main components & their responsibilities
A.  User Interfaces
–  **CLI (Go)**
- Command-line tool (`go/cli/cmd/kagent`)
- Uses `go/autogen/client` to call the Engine’s HTTP API
- Orchestration commands: create/list/delete agents, tools, sessions
–  **UI (Next.js)**
- React app under `ui/src`
- Fetches from the Engine’s REST endpoints (via Next.js rewrites)

B.  Engine (Python)
–  Exposes REST API (FastAPI-like in `python/src/autogenstudio/web/app.py`)
–  Sub-modules:
- **SessionManager** – tracks runs & chat sessions
- **DatabaseManager / SchemaManager** – local storage (SQLite/SQLAlchemy)
- **ToolServerManager** – starts external tool server processes
- **TeamManager / ToolManager** – CRUD for teams and tool definitions
- **Eval / Orchestrator / Runners** – Autogen LLM orchestration
- **Gallery** – sample tool gallery
–  Auth & middleware under `python/src/autogenstudio/web/auth`
–  Validation & component testing services

C.  Controller (Go Kubernetes Operator)
–  Watches CRDs: Agents, Memories, ModelConfigs, Teams, ToolServers
–  Reconcilers under `go/controller/internal/controller/*_controller.go`
–  A built-in HTTP server (`go/controller/internal/httpserver`) for “invoke” and status APIs
–  Generates Kubernetes resources (Deployments, ConfigMaps, Services, RBAC) via client-go
–  Packaged via Helm under `helm/kagent`

D.  Kubernetes Cluster & CRDs
–  **API Server** hosts CRDs
–  **Custom Resources**:
- Agent
- Memory
- ModelConfig
- Team
- ToolServer
–  Operator creates underlying Pods/Services/ConfigMaps for agents and tool servers
–  Helm charts under `helm/kagent-*` (CRDs + Operator + Agents + Agents frameworks)

E.  External Dependencies
–  LLM providers (OpenAI, Anthropic, Ollama…)
–  Pinecone or other Vector DB (memory)
–  Kubernetes API
–  Optional observability (OpenTelemetry, Prometheus)

##### Relationships & Data Flows
1.  **User** → CLI or UI
2.  CLI/UI → **Engine HTTP API** (requests: create session, invoke agent, manage teams/tools)
3.  Engine → **Local DB** (session & metadata), → **LLM Providers** (chat completions), → **Tool servers** (gRPC or HTTP)
4.  For cluster mode, CLI/UI → **kubectl/Helm** → **Kubernetes API Server**
5.  **Controller** watches CRDs in the API Server
6.  Controller reconciler → **Kubernetes resources** (agent Pods, toolserver Pods, RBAC, ConfigMaps)
7.  Agent Pods load the **Engine container image** and register back with Controller HTTP server or Engine API as needed

##### Architectural patterns & design principles
–  **Microservices**: CLI, UI, Engine, Controller as separate deployables
–  **Operator Pattern**: CRD reconciliation loops in Controller
–  **Hexagonal (Ports & Adapters)** in Engine: clear separation between orchestrator, storage, tool adapters, LLM providers
–  **Declarative config** via YAML/Helm; **Extensibility** via CRDs and plugin-style tools
–  **Separation of concerns**: UI only talks to Engine, Controller only talks to K8s API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Clients"
        CLI_binary["kagent CLI"]:::goService
        UI_app["UI (Next.js)"]:::jsService
    end

    %% CLI Components
    subgraph "CLI (Go)"
        CLI_binary
        CLI_internal["Internal Modules"]:::goService
    end
    click CLI_binary "https://github.com/chamodshehanka/kagent/blob/main/go/cli/cmd/kagent/main.go"
    click CLI_internal "https://github.com/chamodshehanka/kagent/tree/main/go/cli"

    %% UI Components
    subgraph "UI (Next.js)"
        Pages["Pages & Routes"]:::jsService
        Actions["API Action Hooks"]:::jsService
        Components["Shared Components"]:::jsService
        Config["Config & Build"]:::jsService
    end
    click Pages "https://github.com/chamodshehanka/kagent/tree/main/ui/src/app"
    click Actions "https://github.com/chamodshehanka/kagent/tree/main/ui/src/app/actions"
    click Components "https://github.com/chamodshehanka/kagent/tree/main/ui/src/components"
    click Config "https://github.com/chamodshehanka/kagent/blob/main/ui/next.config.ts"

    %% Engine Service
    subgraph "Engine (Python)"
        App["app.py"]:::pythonService
        Routes["REST Routes & Auth"]:::pythonService
        SessionMgr["SessionManager"]:::pythonService
        DBmgr["DB & Schema Manager"]:::pythonService
        ToolSrvMgr["ToolServer Manager"]:::pythonService
        TeamTool["Team & Tool Managers"]:::pythonService
        Orch["Orchestrator & Runners"]:::pythonService
        Gallery["Gallery"]:::pythonService
        Validation["Validation"]:::pythonService
        DB["SQLite DB"]:::database
        Pinecone["Vector DB (Pinecone)"]:::external
        LLM["LLM Providers"]:::external
    end
    click App "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/web/app.py"
    click Routes "https://github.com/chamodshehanka/kagent/tree/main/python/src/autogenstudio/web/routes"
    click SessionMgr "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/sessionmanager/sessionmanager.py"
    click DBmgr "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/database/db_manager.py"
    click ToolSrvMgr "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/toolservermanager/toolserver_manager.py"
    click TeamTool "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/teammanager/teammanager.py"
    click TeamTool "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/toolmanager/toolmanager.py"
    click Orch "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/eval/orchestrator.py"
    click Gallery "https://github.com/chamodshehanka/kagent/blob/main/python/src/autogenstudio/gallery/builder.py"
    click Validation "https://github.com/chamodshehanka/kagent/tree/main/python/src/autogenstudio/validation"

    %% Controller Service
    subgraph "Controller (Go Operator)"
        API_types["API Types (CRDs)"]:::goService
        Reconcilers["Reconcilers"]:::goService
        HTTPserver["HTTP Invoke & Status Server"]:::goService
        Utils["Utilities & Translators"]:::goService
    end
    click API_types "https://github.com/chamodshehanka/kagent/tree/main/go/controller/api/v1alpha1"
    click Reconcilers "https://github.com/chamodshehanka/kagent/tree/main/go/controller/internal/controller"
    click HTTPserver "https://github.com/chamodshehanka/kagent/blob/main/go/controller/internal/httpserver/server.go"
    click Utils "https://github.com/chamodshehanka/kagent/tree/main/go/controller/internal/autogen"

    %% Helm Charts & CRDs
    subgraph "Helm Charts"
        KagentChart["kagent Chart"]:::external
        CRDsChart["CRDs Chart"]:::external
        AgentsChart["Agent Framework Charts"]:::external
    end
    click KagentChart "https://github.com/chamodshehanka/kagent/tree/main/helm/kagent"
    click CRDsChart "https://github.com/chamodshehanka/kagent/tree/main/helm/kagent-crds"
    click AgentsChart "https://github.com/chamodshehanka/kagent/tree/main/helm/agents"

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        API["API Server"]:::external
        CRDs["Custom Resources"]:::external
        K8sResources["Pods/Services/ConfigMaps/RBAC"]:::external
    end

    %% Data Flows
    CLI_binary -->|"calls HTTP API"| App
    UI_app -->|"calls HTTP API"| App

    App -->|manages sessions| SessionMgr
    App -->|CRUD teams/tools| TeamTool
    App -->|start tool servers| ToolSrvMgr
    App -->|orchestrates LLM runs| Orch
    App -->|serves gallery| Gallery
    App -->|validates inputs| Validation

    SessionMgr --> DBmgr
    DBmgr --> DB
    Orch --> LLM
    SessionMgr --> Pinecone
    ToolSrvMgr --> K8sResources

    CLI_binary -->|"kubectl/helm"| KagentChart
    UI_app -->|"kubectl/helm"| KagentChart

    KagentChart --> CRDs
    CRDsChart --> CRDs

    Controller -->|watches| CRDs
    Controller -->|reconciles| K8sResources

    Reconcilers --> K8sResources
    HTTPserver -->|invoke/status| App

    %% Styles
    classDef goService fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef pythonService fill:#98FB98,stroke:#000,stroke-width:1px
    classDef jsService fill:#FFD700,stroke:#000,stroke-width:1px
    classDef database fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
