This document provides a high-level overview of the kagent system architecture, its core components, and fundamental concepts. It introduces the Kubernetes-native framework for building, deploying, and managing AI agents, explains how the major subsystems interact, and outlines the key resources and protocols that enable agent orchestration.
For detailed installation instructions, see Getting Started. For in-depth component documentation, see Controller Component, Agent Runtime and SDK, and User Interface. For API specifications of Kubernetes resources, see Custom Resources Reference.
kagent is a Kubernetes-native platform for building and running AI agents. It extends Kubernetes with custom resource definitions (CRDs) that declaratively define agents, their LLM configurations, and tool integrations. The system orchestrates agent deployments, manages their lifecycle, and provides observability into agent operations.
The framework supports multiple AI agent development paradigms through a unified platform:
Sources: README.md33-99 python/uv.lock11-25
The kagent platform consists of four primary layers deployed in a Kubernetes cluster:
Sources: README.md86-98 Makefile34-53 go/Dockerfile1-52 ui/Dockerfile1-111 python/Dockerfile1-159
The controller is a Kubernetes operator written in Go that reconciles kagent custom resources. It watches for changes to Agent, ModelConfig, and RemoteMCPServer resources and manages the corresponding Kubernetes deployments, services, and configurations.
KagentReconciler manages reconciliation loops/api/sessions, /api/tasks, /api/memoriesThe controller translates Agent CRDs into ADK-compatible configurations using the AdkApiTranslator in go/core/internal/controller/translator
Sources: Makefile48 go/Dockerfile10-33 go/Makefile64-67 .github/workflows/ci.yaml217-221
The web UI provides a visual interface for managing agents, models, and tool servers. Built with Next.js and served by Nginx.
AgentsProvider context in ui/src/components/AgentsProvider.tsx/agents, chat interface at /agents/:namespace/:name/chat/api/* to controller, /a2a/* to agent podsSources: ui/Dockerfile1-111 Makefile49 ui/src/app/agents/[namespace]/[name]/chat/layout.tsx:1-89
Agent pods execute the actual AI agent logic. Each agent runs as a FastAPI application built from the kagent-adk package.
uv package manager python/Dockerfile23-159kagent-adk run CLI command python/packages/kagent-adk/pyproject.toml50AgentExecutor in python/packages/kagent-adk/src/kagent/adk/_agent_executor.py - orchestrates agent executionKAgentSessionService - manages session state and historyto_agent() method converts AgentConfig to ADK Agent instancesSources: python/Dockerfile114-159 python/packages/kagent-adk/pyproject.toml1-71 README.md97
A Go-based CLI for interacting with kagent from the terminal.
kagent dashboard for local developmentSources: go/Makefile64-67 Makefile406-413
kagent extends Kubernetes with three primary CRDs that define the agent ecosystem:
Defines an AI agent with two types:
systemMessage, tools, modelConfig, and memory fieldsimage, command, args for frameworks like OpenAI Agents SDK, CrewAI, LangGraphThe controller creates a Deployment and Service for each Agent resource.
Sources: README.md71
Defines LLM provider configurations supporting 8 providers:
| Provider | Configuration Fields |
|---|---|
openAI | model, apiKeySecret, baseUrl |
anthropic | model, apiKeySecret, baseUrl |
azureOpenAI | model, apiKeySecret, endpoint, deployment |
gemini | model, apiKeySecret |
ollama | model, baseUrl (no auth required) |
geminiVertexAI | model, project, location |
anthropicVertexAI | model, project, location |
bedrock | model, region, credentials |
Supports apiKeyPassthrough for per-request authentication.
Sources: README.md72
Defines external tool servers using the Model Context Protocol (MCP). The spec.url points to an SSE endpoint, and discovered tools are populated in status.tools.
Sources: README.md73
The A2A protocol enables synchronous and asynchronous communication between agents and between UI/CLI clients and agents.
POST /a2a/task with TaskRequest containing app_name, message, model_overrideTaskStatusUpdate messagesa2a-sdk Python package python/uv.lock41-61a2a_sdk.http_server provides FastAPI route handlersAgents can call other agents as tools by referencing them in the spec.tools.remoteAgents field.
Sources: python/uv.lock41-61 python/packages/kagent-adk/pyproject.toml33
MCP defines how agents discover and invoke external tools. Tool servers expose:
mcp>=1.25.0 SDK python/packages/kagent-adk/pyproject.toml21kagent includes built-in MCP servers for Kubernetes, Istio, Helm, Prometheus, Grafana, and other infrastructure components.
Sources: python/packages/kagent-adk/pyproject.toml21 README.md73
The monorepo uses a unified build system:
api, core, adkuv managing 8 packagesBuild targets in Makefile220-287:
make build-controller # Go controller image
make build-ui # Next.js UI image
make build-app # Python agent runtime base image
make build-kagent-adk # Python ADK with dependencies
make build-golang-adk # Go ADK runtime
Sources: Makefile1-468 python/pyproject.toml1-54 go/Makefile1-176
The make targets provide a complete local development environment:
Environment variables for API keys:
OPENAI_API_KEY for OpenAIANTHROPIC_API_KEY for AnthropicGOOGLE_API_KEY for GeminiAZUREOPENAI_API_KEY for Azure OpenAISources: Makefile184-198 Makefile342-390 Makefile415-418
The following diagram illustrates how data flows through kagent during agent execution:
Sources: README.md86-98 python/packages/kagent-adk/pyproject.toml18 .github/workflows/ci.yaml87-138
kagent includes comprehensive testing across all layers:
| Test Type | Implementation | Run Command |
|---|---|---|
| Go unit tests | All modules: api, core, adk | go test -race ./... .github/workflows/ci.yaml154-156 |
| Python unit tests | pytest for all packages | make test python/Makefile20-22 |
| Helm unit tests | helm-unittest plugin | helm unittest helm/kagent .github/workflows/ci.yaml175-182 |
| E2E tests | Go tests with Kind cluster | go test .../test/e2e .github/workflows/ci.yaml112-127 |
| UI tests | Next.js test suite | npm run test .github/workflows/ci.yaml206-208 |
E2E tests deploy real agents (kebab, poem-flow) and verify end-to-end workflows including database persistence (both SQLite and PostgreSQL).
Sources: .github/workflows/ci.yaml34-364 python/Makefile20-22 go/Makefile109-115
kagent integrates OpenTelemetry for distributed tracing across all components:
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAMEmake otel-local runs Jaeger at localhost:16686 Makefile439-443All Python agents inherit OpenTelemetry context through the ADK framework.
Sources: README.md74 Makefile439-443
Key configuration files and their purposes:
| File | Purpose |
|---|---|
| helm/kagent/values.yaml | Helm chart configuration: replicas, resources, providers |
| go/core/internal/database/config.go | Database connection settings (SQLite/PostgreSQL) |
| python/packages/kagent-adk/pyproject.toml | Python package dependencies and versions |
| ui/conf/nginx.conf | Reverse proxy routing rules |
For complete configuration options, see Configuration Reference.
Sources: Makefile342-375
Refresh this wiki