This page provides a high-level introduction to the kagent system, its architectural components, and core concepts. It serves as an entry point for understanding how kagent enables Kubernetes-native AI agent deployment and management.
For detailed architectural information, see System Architecture. For installation procedures, see Installation and Deployment. For custom resource specifications, see Custom Resources Reference.
kagent is a Kubernetes-native framework for building, deploying, and managing AI agents. It extends Kubernetes with custom resources that represent agents, model configurations, and tool servers, enabling declarative infrastructure-as-code practices for AI workloads. The framework orchestrates agent lifecycle through a Go-based controller, executes agent logic using a Python runtime engine built on Google's ADK (Agent Development Kit), and provides management interfaces via both a web UI and CLI.
Key capabilities:
Sources: README.md33-98 go/pkg/app/app.go1-502
kagent consists of four primary components that work together to provide the complete agent management lifecycle:
Sources: go/pkg/app/app.go76-502 go/internal/controller/reconciler/reconciler.go44-77 go/internal/a2a/a2a_registrar.go26-61
The controller is a Kubernetes operator written in Go that manages the lifecycle of kagent custom resources. It implements the reconciliation pattern to ensure the desired state (defined in CRDs) matches the actual state in the cluster.
Key code entities:
app.Start() in go/pkg/app/app.go203-502controller.AgentController in go/internal/controller/agent_translator.AdkApiTranslator in go/internal/controller/translator/agent/reconciler.KagentReconciler interface in go/internal/controller/reconciler/reconciler.go44-51Responsibilities:
Default bind addresses:
:8083 (configurable via --http-server-address):8443 or :8080 (configurable via --metrics-bind-address):8082 (configurable via --health-probe-bind-address)Sources: go/pkg/app/app.go95-167 go/internal/controller/reconciler/reconciler.go44-77
The engine is a Python-based runtime that executes agent logic using Google's ADK (Agent Development Kit). Each agent runs in its own pod with the engine as the main process.
Key characteristics:
The engine translates AgentConfig objects (stored in the database by the controller) into executable Agent instances that can process tasks and maintain conversation history.
Sources: README.md93-98 go/internal/controller/translator/agent/
The UI is a Next.js-based web dashboard that provides visual management of agents, models, and tools. It communicates with the controller's HTTP API.
Key features:
Default address: :8080 (exposed as kagent-ui service)
Sources: README.md96 contrib/cncf/technical-review.md66-71
The kagent CLI provides command-line access to agent management, deployment, and invocation capabilities. It interacts with both the Kubernetes API (for CRD management) and the controller's HTTP API (for operations).
Common commands:
kagent agent deploy - Deploy agents to clusterkagent agent invoke - Invoke an agent with a messagekagent mcp - Manage MCP serversSources: README.md98 contrib/cncf/technical-review.md72-77
kagent extends Kubernetes with several custom resource definitions (CRDs) that represent core concepts in the system:
| Resource | API Group | Version | Purpose |
|---|---|---|---|
Agent | kagent.dev | v1alpha2 | Defines an AI agent with tools, model configuration, and deployment specification |
ModelConfig | kagent.dev | v1alpha2 | Configures LLM provider credentials and parameters |
RemoteMCPServer | kagent.dev | v1alpha2 | Registers external MCP tool servers |
MCPServer | kmcp | v1alpha1 | Defines in-cluster MCP servers (via KMCP dependency) |
Memory | kagent.dev | v1alpha1 | Configures vector storage for agent memory |
Agent Types:
The Agent CRD supports two primary types:
type: Declarative): Framework-managed agents where kagent handles the runtime. Specify system message, tools, and model configuration.type: BYO): Bring-your-own container agents where users provide a custom container image implementing the A2A protocol.Sources: go/api/v1alpha2/ go/internal/controller/reconciler/reconciler.go79-96 contrib/cncf/technical-review.md286-294
The following diagram shows how a user request flows through the system, from CRD creation to agent execution:
Sources: go/internal/controller/reconciler/reconciler.go79-500 go/internal/a2a/a2a_registrar.go67-152 go/internal/controller/translator/agent/
| Layer | Technologies | Purpose |
|---|---|---|
| Controller | Go 1.23+, controller-runtime, Kubernetes client-go | Kubernetes operator implementation |
| Engine | Python 3.12+, Google ADK, MCP client libraries | Agent runtime execution |
| UI | Next.js 14, React, TypeScript, Tailwind CSS | Web dashboard |
| CLI | Go, Cobra framework | Command-line interface |
| Database | SQLite (dev), PostgreSQL (prod) | Session and agent state persistence |
| Protocols | A2A (agent-to-agent), MCP (tool integration), HTTP/SSE | Communication standards |
| Observability | OpenTelemetry, Prometheus metrics | Distributed tracing and monitoring |
| Build | Docker Buildx, Make, Helm | Multi-arch container builds and deployment |
Sources: go/pkg/app/app.go19-74 README.md72-98 contrib/cncf/security-self-assessment.md51
The controller maintains a database (via database.Client) that stores runtime state independent of Kubernetes:
| Table | Key Fields | Purpose |
|---|---|---|
agents | id (identifier), type, config (JSON) | Agent configurations for runtime loading |
tool_servers | name, group_kind, description | Registered MCP server metadata |
tools | id, server_name, server_group_kind, description | Discovered tools from MCP servers |
sessions | Session tracking for multi-turn conversations | |
tasks | Task execution records |
Key operations:
dbClient.StoreAgent() in go/internal/controller/reconciler/reconciler.go634dbClient.StoreToolServer() in go/internal/controller/reconciler/reconciler.go646dbClient.RefreshToolsForServer() in go/internal/controller/reconciler/reconciler.go660Database type is configurable:
./kagent.db (default)--postgres-database-url flagSources: go/pkg/app/app.go120-124 go/pkg/app/app.go338-357 go/internal/controller/reconciler/reconciler.go622-665
kagent configuration follows a hierarchical precedence:
Config.SetFlags() in go/pkg/app/app.go127-166)METRICS_BIND_ADDRESS)Critical configuration:
--default-model-config-name and --default-model-config-namespace: References the default ModelConfig resource--http-server-address: Controller HTTP API bind address (default :8083)--a2a-base-url: Base URL advertised to A2A clients (default http://127.0.0.1:8083)--database-type: sqlite or postgres (default sqlite)--image-registry, --image-tag: Container image configuration for agent podsSources: go/pkg/app/app.go95-184 go/pkg/app/app.go210-220
kagent integrates with multiple LLM providers through the ModelConfig CRD. The controller validates credentials and manages API key secrets:
Provider configuration includes:
gpt-4.1-mini, claude-3-5-sonnet)Sources: README.md72 go/internal/controller/reconciler/reconciler.go215-267
MCP provides the extensible tool system. The controller:
client.ListTools() in go/internal/controller/reconciler/reconciler.go681-704dbClient.RefreshToolsForServer() in go/internal/controller/reconciler/reconciler.go660RemoteMCPServer and MCPServer CRDsTransport protocols supported:
Sources: go/internal/controller/reconciler/reconciler.go641-679 README.md73
The A2A protocol enables agents to invoke other agents as tools. The A2ARegistrar component:
Agent CRDs via cache informer in go/internal/a2a/a2a_registrar.go70-73A2AClient instances for each agent in go/internal/a2a/a2a_registrar.go127-141A2AHttpMux for request routingAgent cards (server.AgentCard) advertise capabilities:
Sources: go/internal/a2a/a2a_registrar.go26-152 go/internal/controller/translator/agent/utils.go14-35
Each agent gets its own Kubernetes resources:
Per-agent resources created by controller:
Deployment: Runs agent pods with Python ADK engineService: ClusterIP service exposing port 8080 for A2A protocolServiceAccount: With configurable RBAC permissionsSecret: Contains resolved model configuration and credentials (if needed)Resource naming convention:
{agent.name} in namespace {agent.namespace}{agent.name}.{agent.namespace}http://{agent.name}.{agent.namespace}:8080Default resource limits (configurable):
Sources: go/internal/controller/translator/agent/ contrib/cncf/technical-review.md242-262
Refresh this wiki