# kagent-dev/kagent architecture

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

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

## Overview

1. **Repository shape**
   - This is a multi-language monorepo for a Kubernetes-native AI agent platform.
   - The main deliverables are a Go control plane, a Next.js UI, several Python agent/runtime libraries and samples, Helm charts, and reusable MCP/tool server packages.

2. **Primary runtime boundary: Kubernetes**
   - The system is centered on Kubernetes custom resources, not a standalone app server.
   - Core resources include Agents, ModelConfigs, ToolServers, RemoteMCPServers, Memories, SandboxAgents, and AgentHarnesses.
   - Most user actions ultimately translate into CRD creation/update, which the controller turns into Kubernetes workloads and supporting objects.

3. **Control plane in Go**
   - The Go code under `go/core` is the operational center of the project.
   - It contains the Kubernetes controller, HTTP API server, A2A transport/compat layers, database layer, MCP handling, sandbox backend logic, and shared utilities.
   - The controller watches CRDs and reconciles them into Deployments, Services, Secrets, RBAC, routes, and status updates.

4. **API and persistence**
   - `go/core/internal/httpserver` exposes the backend API used by the UI and by other clients.
   - `go/core/internal/database` plus `go/core/pkg/migrations` manage persistent state such as sessions, tasks, feedback, memory, model/tool metadata, and shares.
   - This persistence layer is separate from Kubernetes state; it stores conversational and platform data that should survive pod restarts independently of CRD reconciliation.

5. **Agent execution boundary**
   - The actual agent runtime is split from the controller.
   - Go packages under `go/adk` and Python packages under `python/packages/kagent-adk`, `kagent-openai`, `kagent-crewai`, `kagent-langgraph`, and `kagent-core` implement agent execution adapters, event conversion, sessions, HITL/approval flows, model bindings, and tool invocation.
   - The runtime talks to external LLM providers and to tool services, while the controller remains responsible for declarative lifecycle management.

6. **Tooling and MCP integration**
   - Tool access is modeled around MCP servers and tool servers.
   - The repo includes reusable tool-server charts and templates in `contrib/tools` and `helm/tools`, plus controller logic for MCP-related CRDs and reconciliation.
   - Agents can consume local or remote MCP servers, and the platform supports tool sharing across agents.

7. **A2A and nested-agent communication**
   - There is a distinct agent-to-agent boundary implemented through A2A components in both Go and Python.
   - `go/core/internal/a2a` and related Python modules handle remote agent calls, passthroughs, task/result aggregation, and compatibility with A2A protocol versions.
   - This enables nested agents, remote tool/agent delegation, and sandboxed transport paths separate from normal tool calls.

8. **Sandbox and substrate layer**
   - The sandbox/substrate code is a major architectural subsystem.
   - `go/core/pkg/sandboxbackend` and `go/core/internal/controller/*substrate*` manage isolated execution environments and special agent harness flows.
   - This layer is used when agents need controlled network, credential, or gateway behavior, and it is distinct from ordinary Kubernetes workloads.

9. **UI as a management surface**
   - `ui/` is a Next.js front end that drives the platform.
   - It provides agent creation, model/provider setup, MCP management, prompts, sessions/chat, substrate status, and onboarding flows.
   - The UI mostly orchestrates backend actions through API routes and action modules rather than owning business logic itself.

10. **Authentication and access control**
   - The platform has explicit auth and proxy-auth support in the Go HTTP layer and corresponding UI auth context.
   - There are signals of OIDC/proxy integration, session sharing, and user identity propagation through the API and chat/session flows.
   - RBAC and service accounts are part of the deployed architecture, especially for controller actions and tool/server access.

11. **Deployment packaging**
   - Helm charts under `helm/` package the controller, UI, PostgreSQL, CRDs, and tool-server deployments.
   - `contrib/` contains additional add-ons, memory backend examples, and standalone tool-server manifests.
   - The repo also includes devcontainer, Dockerfiles, and scripts to support local development and production image builds.

12. **Validation, testing, and release flow**
   - The repo is heavily tested with Go unit/integration/e2e tests, Python unit/e2e tests, UI tests, and GitHub Actions workflows.
   - There are dedicated test fixtures for agent translation, CRD reconciliation, MCP tooling, auth, upgrades, and UI behavior.
   - Architecture-wise, this matters because many subsystems are validated independently: Kubernetes reconciliation, runtime adapters, UI actions, database migrations, and sample agent packages.

13. **Typical data flow**
   - A user uses the UI or CLI to define an agent, model provider, memory, or tool server.
   - The API/controller persists metadata and applies CRDs into Kubernetes.
   - Reconciliation materializes workloads and secrets/RBAC.
   - The runtime executes the agent, calls LLM providers and MCP tools, and emits events, traces, session updates, and feedback into the API/database.

14. **External dependencies that matter**
   - The platform depends on Kubernetes, PostgreSQL, OpenTelemetry, and one or more LLM providers such as OpenAI, Anthropic, Azure OpenAI, Bedrock, Ollama, Gemini/Vertex AI, or SAP AI Core.
   - It also integrates with MCP ecosystems and optional observability add-ons like Prometheus/Grafana.
   - These are not incidental libraries; they define the main operational boundaries of the system.

Main entry points: [`go/core/internal/controller`](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/controller) (Controller), [`ui/src/app`](https://github.com/kagent-dev/kagent/tree/main/ui/src/app) (Next.js UI), [`python/packages/kagent-adk/src/kagent/adk`](https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-adk/src/kagent/adk) (Python ADK), [`helm`](https://github.com/kagent-dev/kagent/tree/main/helm) (Helm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_go["Go"]
  node_controller["Controller<br/>reconciler"]
  node_translator["Translator<br/>manifest compiler"]
  node_httpserver["API Server<br/>http api"]
  node_database[("Database<br/>postgres persistence")]
  node_migrations["Migrations<br/>schema versioning"]
  node_a2a["A2A<br/>agent transport"]
  node_mcp["MCP<br/>tool protocol"]
  node_sandbox["Sandbox<br/>isolated backend"]
  node_adkgo["Go ADK<br/>agent runtime"]
  node_cli["CLI"]
end

subgraph group_python["Python"]
  node_pythonadk["Python ADK<br/>agent runtime"]
  node_pythoncore["Python Core<br/>shared runtime"]
  node_pythonadapters["Framework Adapters<br/>python plugins"]
  node_samples["Samples<br/>example agents"]
end

subgraph group_ui["UI"]
  node_uiapp["Next.js UI<br/>frontend"]
  node_uiruntime["UI Logic<br/>client state"]
end

subgraph group_platform["Platform"]
  node_crds["CRDs<br/>kubernetes api"]
  node_helm["Helm<br/>deployment charts"]
  node_tools["Tool Servers<br/>mcp packages"]
end

node_controller -->|"watches"| node_crds
node_translator -->|"feeds manifests"| node_controller
node_httpserver -->|"reads/writes"| node_database
node_httpserver -->|"mutates state"| node_controller
node_controller -->|"provisions"| node_sandbox
node_controller -->|"reconciles"| node_mcp
node_adkgo -->|"implements"| node_a2a
node_adkgo -->|"invokes tools"| node_mcp
node_adkgo -->|"stores sessions"| node_database
node_pythonadk -->|"builds on"| node_pythoncore
node_pythonadk -->|"calls tools"| node_mcp
node_pythonadk -->|"delegates"| node_a2a
node_pythonadapters -->|"extends"| node_pythonadk
node_uiapp -->|"uses"| node_uiruntime
node_uiapp -->|"calls API"| node_httpserver
node_uiapp -->|"manages"| node_crds
node_uiapp -->|"chat routes"| node_a2a
node_cli -->|"packages"| node_helm
node_cli -->|"targets"| node_controller
node_helm -->|"installs"| node_crds
node_helm -->|"deploys"| node_controller
node_helm -->|"deploys"| node_uiapp
node_tools -->|"templates"| node_mcp
node_samples -->|"demonstrates"| node_pythonadk

click node_crds "https://github.com/kagent-dev/kagent/tree/main/go/api/config/crd/bases"
click node_controller "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/controller"
click node_translator "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/controller/translator/agent"
click node_httpserver "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/httpserver"
click node_database "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/database"
click node_migrations "https://github.com/kagent-dev/kagent/tree/main/go/core/pkg/migrations"
click node_a2a "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/a2a"
click node_mcp "https://github.com/kagent-dev/kagent/tree/main/go/core/internal/mcp"
click node_sandbox "https://github.com/kagent-dev/kagent/tree/main/go/core/pkg/sandboxbackend"
click node_adkgo "https://github.com/kagent-dev/kagent/tree/main/go/adk/pkg"
click node_cli "https://github.com/kagent-dev/kagent/tree/main/go/core/cli"
click node_uiapp "https://github.com/kagent-dev/kagent/tree/main/ui/src/app"
click node_uiruntime "https://github.com/kagent-dev/kagent/tree/main/ui/src/lib"
click node_pythonadk "https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-adk/src/kagent/adk"
click node_pythoncore "https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-core/src/kagent/core"
click node_pythonadapters "https://github.com/kagent-dev/kagent/tree/main/python/packages"
click node_samples "https://github.com/kagent-dev/kagent/tree/main/python/samples"
click node_helm "https://github.com/kagent-dev/kagent/tree/main/helm"
click node_tools "https://github.com/kagent-dev/kagent/tree/main/contrib/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_translator,node_httpserver,node_database,node_migrations,node_a2a,node_mcp,node_sandbox,node_adkgo,node_cli toneBlue
class node_pythonadk,node_pythoncore,node_pythonadapters,node_samples toneAmber
class node_uiapp,node_uiruntime toneMint
class node_crds,node_helm,node_tools toneRose
```

## Components

### Go

Control plane, API, CLI, and shared runtime packages.

- [Controller](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/controller): reconciler · Watches CRDs and materializes workloads, services, RBAC, secrets, routes, and status. · `go/core/internal/controller`
- [Translator](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/controller/translator/agent): manifest compiler · Converts agent specs into deployable Kubernetes manifests and runtime config. · `go/core/internal/controller/translator/agent`
- [API Server](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/httpserver): http api · Backend API for the UI and clients, including auth and platform operations. · `go/core/internal/httpserver`
- [Database](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/database): postgres persistence · Persistent storage for sessions, tasks, feedback, memories, shares, and metadata. · `go/core/internal/database`
- [Migrations](https://github.com/kagent-dev/kagent/tree/main/go/core/pkg/migrations): schema versioning · Database migration set for core and vector-backed persistence. · `go/core/pkg/migrations`
- [A2A](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/a2a): agent transport · Agent-to-agent compatibility, passthroughs, and remote task/result handling. · `go/core/internal/a2a`
- [MCP](https://github.com/kagent-dev/kagent/tree/main/go/core/internal/mcp): tool protocol · MCP handling across controller, API, and runtime tool invocation paths. · `go/core/internal/mcp`
- [Sandbox](https://github.com/kagent-dev/kagent/tree/main/go/core/pkg/sandboxbackend): isolated backend · Substrate and sandbox lifecycle for controlled execution and gateway behavior. · `go/core/pkg/sandboxbackend`
- [Go ADK](https://github.com/kagent-dev/kagent/tree/main/go/adk/pkg): agent runtime · Go agent runtime support for sessions, models, tools, telemetry, and A2A. · `go/adk/pkg`
- [CLI](https://github.com/kagent-dev/kagent/tree/main/go/core/cli): developer cli · Command-line workflows for agent init, deploy, invoke, and MCP scaffolding. · `go/core/cli`

### Python

Agent runtimes, adapters, and samples.

- [Python ADK](https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-adk/src/kagent/adk): agent runtime · Python execution adapter for sessions, approvals, memory, MCP, A2A, and model bindings. · `python/packages/kagent-adk/src/kagent/adk`
- [Python Core](https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-core/src/kagent/core): shared runtime · Shared Python core for A2A config, HITL utilities, and tracing. · `python/packages/kagent-core/src/kagent/core`
- [Framework Adapters](https://github.com/kagent-dev/kagent/tree/main/python/packages): python plugins · Execution adapters for OpenAI, CrewAI, LangGraph, and related agent frameworks. · `python/packages`
- [Samples](https://github.com/kagent-dev/kagent/tree/main/python/samples): example agents · Reference agents and framework samples used for onboarding and validation. · `python/samples`

### UI

Next.js management surface.

- [Next.js UI](https://github.com/kagent-dev/kagent/tree/main/ui/src/app): frontend · Operator console for agents, models, MCP, prompts, sessions, auth, and substrate. · `ui/src/app`
- [UI Logic](https://github.com/kagent-dev/kagent/tree/main/ui/src/lib): client state · Action modules, contexts, hooks, and API bindings used by the UI. · `ui/src/lib`

### Platform

Kubernetes packaging, CRDs, and deployment assets.

- [CRDs](https://github.com/kagent-dev/kagent/tree/main/go/api/config/crd/bases): kubernetes api · Custom resources for agents, model configs, tool servers, memories, and harnesses. · `go/api/config/crd/bases`
- [Helm](https://github.com/kagent-dev/kagent/tree/main/helm): deployment charts · Charts for controller, UI, PostgreSQL, CRDs, agents, and tool servers. · `helm`
- [Tool Servers](https://github.com/kagent-dev/kagent/tree/main/contrib/tools): mcp packages · Reusable MCP/tool server charts, templates, and example deployments. · `contrib/tools`

## Connections

- Controller → CRDs: watches · Reconciles custom resources into Kubernetes objects.
- Translator → Controller: feeds manifests · Produces workload and runtime specifications consumed by reconciliation.
- API Server → Database: reads/writes · Persists conversational and platform state.
- API Server → Controller: mutates state · API actions create or update CRDs and related platform objects.
- Controller → Sandbox: provisions · Creates substrate and isolated execution environments when needed.
- Controller → MCP: reconciles · Manages MCP-related tool server resources and status.
- Go ADK → A2A: implements · Provides nested-agent and remote-call support in Go.
- Go ADK → MCP: invokes tools · Resolves tool registries and MCP-backed calls at runtime.
- Go ADK → Database: stores sessions · Uses persistent state for sessions, tasks, feedback, and memory.
- Python ADK → Python Core: builds on · Shares config, A2A, HITL, and tracing primitives.
- Python ADK → MCP: calls tools · Consumes local and remote MCP servers.
- Python ADK → A2A: delegates · Supports remote agent calls and task aggregation.
- Framework Adapters → Python ADK: extends · Framework-specific execution adapters plug into the shared runtime.
- Next.js UI → UI Logic: uses · Pages are driven by shared actions, contexts, hooks, and utilities.
- Next.js UI → API Server: calls API · Primary management surface for platform operations.
- Next.js UI → CRDs: manages · Creates and edits agents, models, tools, and harness resources.
- Next.js UI → A2A: chat routes · Handles A2A and sandbox chat flows in the interface.
- CLI → Helm: packages · CLI workflows align with deployable charts and manifests.
- CLI → Controller: targets · Drives local and cluster workflows for agent deployment.
- Helm → CRDs: installs · Ships the API types and custom resource definitions.
- Helm → Controller: deploys · Deploys controller, RBAC, and supporting services.
- Helm → Next.js UI: deploys · Packages the front end alongside the control plane.
- Tool Servers → MCP: templates · Reusable MCP server charts and manifests.
- Samples → Python ADK: demonstrates · Reference agent projects exercise the runtime adapters.
