How chamodshehanka/kagent works
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