Skip to main content

Kagent - Kubernetes AI Agent Management

24 min read
AI documentation guide

In a multi-model ecosystem, AI agents must call multiple LLMs/SLMs, connect to tools and other agents via MCP/A2A protocols, and dynamically scale based on traffic. Kubernetes' Operator pattern is the most natural approach for declaratively defining such agents as CRDs and automatically managing their lifecycles. Kagent is a reference architecture that applies this pattern to AI agents.

1. Overview​

Kagent declaratively defines agents, tools, and workflows through Custom Resource Definitions (CRDs), with an Operator automatically deploying and managing them. Instead of manually writing Deployments, Services, and ConfigMaps, a single Agent CRD integrates model connections, tool bindings, and scaling policies.

Kagent Project Status and Scope of This Document

Kagent is a CNCF Sandbox open-source project created by Solo.io. As of 2026-10-15 the latest release is v1.0.0-alpha13 (Apache-2.0). The project is public but still at the alpha stage, so its API and installation method can change between releases. In this document, the Agent/Tool/Memory specs in §3 follow the official kagent.dev/v1alpha2 API, whereas the Operator architecture diagram in §2 and the multi-agent orchestration patterns in §4 are design proposals not defined by the official API and require a separate controller and CRDs to implement. For production environments, also evaluate alternatives such as Bedrock AgentCore, KubeAI, or LangGraph Platform.

For installation and deployment guides and the current API, see the Kagent official documentation and the GitHub repository.

Alternative Solutions Comparison​

🔍 Kagent Alternative Solutions Comparison
SolutionFeaturesSuitable Use Cases
Kagent (Reference)
AI agent-specific CRD, workflow orchestrationMulti-agent systems, complex workflows
KubeAI
Lightweight LLM serving, OpenAI-compatible APISimple model serving, rapid prototyping
Bedrock AgentCore
AWS managed Agent runtime, MCP/A2A native, auto-scalingAWS-native Agent deployment, managed infrastructure preferred
LangGraph Platform
Write stateful workflows with the open-source LangGraph framework, deploy and manage on the LangGraph Platform (formerly LangGraph Cloud) runtime, trace with LangSmithComplex multi-step agents, stateful workflows
hermes-agent (NousResearch, OSS)
Self-improving agent runtime, MCP·40+ tools·subagents, model-agnostic (OpenRouter etc.), MITOSS self-improving agent, multi-backend (Docker/Modal) execution

Another open-source self-improving agent runtime is hermes-agent (NousResearch, MIT). It supports MCP, 40+ tools, and subagent spawning, and is model-agnostic — it can use OpenRouter and other LLM API Gateways (Tier 2 ②) as model providers, forming the Layer 4 (agent runtime) → Layer 5 (gateway) flow directly. Consider Kagent when you need Kubernetes-native declarative management, and hermes-agent when you need a standalone self-improving agent.

Key Features​

  • Declarative agent management: YAML-based agent definition and deployment
  • Tool registry: Central management of tools available to agents via CRDs
  • Auto-scaling integration: Dynamic scaling by attaching a separately installed HPA or KEDA ScaledObject to the controller-created Deployment (see §5)
  • Multi-agent orchestration: Inter-agent collaboration for complex workflows (design proposal)
  • Observability integration: Native integration with Langfuse/LangSmith, OpenTelemetry
Target Audience

This document is intended for Kubernetes administrators, platform engineers, and MLOps engineers. Understanding of basic Kubernetes concepts (Pod, Deployment, CRD) is required.

re:Invent 2025 Related Session

CNS421: Streamline Amazon EKS Operations with Agentic AI — A code talk session covering automated EKS cluster management, real-time issue diagnosis, and automatic recovery using AI agents like Kagent.

Key Topics:

  • Model Context Protocol (MCP): Standard protocol for AI agent integration with AWS services
  • Automated Incident Response: Automatic diagnosis and recovery for Pod failures, resource shortages, network issues
  • AWS Service Integration: Native integration with CloudWatch, Systems Manager, EKS API

Watch the session

2. Kagent Architecture​

Kagent follows the Kubernetes Operator pattern, consisting of Controller, CRDs, and Webhooks.

Figure 1. Kagent Operator architecture (control plane, CRDs, managed resources, runtime)

Expand the diagram to read labels and follow connections.
Diagram

Agent, ModelConfig, and RemoteMCPServer/MCPServer are CRDs defined by the official kagent.dev/v1alpha2 API. Tools and memory are not separate CRDs; they are embedded in the Agent spec, so they are not drawn as independent CRDs. The asterisk on Workflow* indicates that multi-agent orchestration is a design proposal not part of the official API and requires a separate CRD and controller to implement (see §4).

Component Description​

ComponentRoleDescription
Kagent ControllerReconciliation loopDetect CRD changes and reconcile resources to desired state
Admission WebhookValidation/MutationValidate and set defaults on CRD creation/modification
Metrics ServerMetrics collectionExpose agent state and performance metrics
Agent CRDAgent definitionSpec, model, and tool configuration for AI agents
ModelConfig CRDModel definitionModel provider, model name, and API key reference that an Agent references via modelConfig
RemoteMCPServer / MCPServer CRDTool server definitionMCP server that an Agent binds as type: McpServer tools (in the v1alpha2 API, tools and memory are not separate CRDs and live in the Agent spec; the chart still ships v1alpha1-only Memory/ToolServer CRDs)
Workflow CRD (design proposal)Workflow definitionDefine multi-agent collaboration workflows. Not in the official kagent.dev/v1alpha2 API; a design proposal that needs its own CRD and controller (§4)

Component Interaction​

Figure 2. Component interaction from Agent CRD creation to Pod scheduling

Expand the diagram to read labels and follow connections.
Diagram

Prerequisites​

  • Kubernetes cluster (a maintained version, v1.34+ recommended — v1.33 reached end of life on 2026-06-28)
  • kubectl CLI tool
  • Helm v3 (for Helm installation)
  • cert-manager (Webhook TLS certificate management)

3. CRD Structure​

Agent CRD​

The Agent CRD declaratively defines the settings for an AI agent. Below is the core spec of the kagent v1alpha2 Declarative Agent. The model is not written inline; it references a separate ModelConfig resource via modelConfig, and tools are bound from an MCP server with type: McpServer:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: customer-support-agent
  namespace: kagent
spec:
  description: "AI agent that responds to customer inquiries and creates tickets"
  type: Declarative
  declarative:
    # The model references a separate ModelConfig resource (not inline)
    modelConfig: default-model-config

    # System prompt
    systemMessage: |
      You are a friendly and professional customer support agent.

    # Tool list (binds tools from an MCP server)
    tools:
      - type: McpServer
        mcpServer:
          name: kagent-tool-server
          kind: RemoteMCPServer
          apiGroup: kagent.dev
          toolNames:
            - search-knowledge-base
            - create-ticket
          # Destructive tools pause for user approval before running
          requireApproval:
            - create-ticket

    # Memory (built on the Google ADK implementation, stored in pgvector)
    memory:
      modelConfig: default-model-config   # References the embedding ModelConfig
      ttlDays: 30                         # Default is 15 days

The referenced ModelConfig resource defines the model provider and model ID. For example, to use an Amazon Bedrock Titan embedding model:

apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: default-model-config
  namespace: kagent
spec:
  provider: Bedrock
  model: amazon.titan-embed-text-v2:0
  bedrock:
    region: us-east-1

Tool (nested type in the Agent spec)​

A Tool is not an independent CRD; it is defined in the Agent spec's tools: []Tool array. The tool type is one of McpServer or Agent (kagent v1alpha2 API).

Table 1. Key Tool fields by type with examples

FieldDescriptionExample
typeTool typeMcpServer, Agent
mcpServerMCP server reference (when type is McpServer)RemoteMCPServer or MCPServer name
agentReference to another Agent (when type is Agent)Agent name

Memory (field in the Agent spec)​

In v1alpha2, Memory is no longer an independent CRD; it is consolidated into the Agent spec's memory: MemorySpec field.

Table 2. Key features of Memory (field in the Agent spec)

FeatureDescription
Embedding model referenceReferences a ModelConfig resource via the modelConfig field
TTL settingSets the memory retention period via the ttlDays field
StorageBuilt-in implementation based on Google ADK, stored in pgvector (redis/in-memory not selectable)

Workflow CRD​

Define multi-agent workflows using the Workflow CRD.

Table 3. Core Workflow CRD spec fields

FieldDescription
spec.inputWorkflow input parameter definition
spec.stepsPer-step agent execution definition (sequential/parallel)
spec.steps[].dependsOnDependency step specification (DAG construction)
spec.steps[].parallelParallel execution flag
spec.outputWorkflow final output mapping
spec.errorHandlingBehavior on step/workflow failure
spec.timeoutOverall workflow timeout
spec.concurrencyConcurrent execution limit (queue/reject/replace)

4. Multi-Agent Orchestration​

Define workflows where multiple agents collaborate to handle complex tasks.

Inter-Agent Communication Patterns​

Figure 3. Inter-agent communication across orchestrator, worker, and communication layers

Expand the diagram to read labels and follow connections.
Diagram

Orchestration Patterns​

Table 4. Multi-agent orchestration patterns and suitable use cases

PatternDescriptionSuitable For
Sequential PipelineStep-by-step sequential execution, previous step output feeds next inputData processing, ETL
Parallel Fan-outSame input sent to multiple agents in parallelMulti-angle analysis, A/B comparison
DAG WorkflowDependency-based directed acyclic graph executionComplex research, report generation
LoopRepeated execution until condition is metReview-revision cycles, quality verification
RoutingBranch to different agents based on input contentInquiry classification, domain distribution

Workflow Example: Research Report​

Figure 4. Agent stages in the research report generation workflow

Expand the diagram to read labels and follow connections.
Diagram

Workflow execution status is tracked via WorkflowRun CRD:

Table 5. WorkflowRun execution states and meaning

StatusDescription
PendingWaiting for execution
RunningOne or more steps are running
SucceededAll steps completed successfully
FailedOne or more steps failed (retries exhausted)

5. Agent Lifecycle Management​

Operator-Managed Resources​

When an Agent CRD is created, the Controller creates/manages the following resources:

Agent CRD Creation
  ├── Deployment (agent Pod management)
  ├── Service (network access)
  ├── ConfigMap (agent configuration)
  └── Secret reference (API keys, credentials)

The kagent controller does not automatically create autoscaling resources (an HPA or a KEDA ScaledObject). A HorizontalPodAutoscaler requires metrics-server, and a KEDA ScaledObject requires the KEDA operator; each must be installed separately and then authored directly against the Deployment the controller created. The scaling-strategy table below is a design target to apply to such a separately configured autoscaler, not a set of fields provided by the kagent API.

Update Strategies​

Table 6. Agent update strategies and recommended scenarios

StrategyDescriptionRecommended Scenario
Rolling UpdateDefault strategy. Progressively replace PodsGeneral config changes
Canary DeploymentTest new version with separate Agent CRDModel changes, major prompt revisions
Blue-GreenRun two versions simultaneously, switch trafficZero-downtime migration

Scaling Strategies​

Table 7. Scaling metrics and threshold examples

MetricDescriptionThreshold Example
CPU utilizationBasic resource-based scaling70%
Memory utilizationScale out on memory pressure80%
Active session countKEDA + Prometheus custom metric50 sessions/Pod
Request throughputRequests per second based100 RPS/Pod

6. Observability Integration​

Agent execution traces are sent to Langfuse, LangSmith, or CloudWatch Generative AI Observability. For a comparison of each tool, see LLMOps Observability Comparison.

Deployment guides:

Key Alert Rules​

Table 8. Agent key alert rules with conditions and severity

AlertConditionSeverity
Agent error rate increaseError rate > 5% (5 min sustained)Critical
Agent response delayP99 > 30s (5 min sustained)Warning
Pod availability degradationReady Pods < 50% (5 min sustained)Critical

7. Conclusion​

Using Kagent enables declarative management of AI agents in Kubernetes environments. Key benefits include:

  • Declarative management: YAML-based agent definitions support GitOps workflows
  • Automated operations: Automatic recovery and scaling through the Operator pattern
  • Standardization: Agent definition standardization through CRDs
  • Scalability: Leveraging Kubernetes-native scaling mechanisms
  • Observability: Integrated monitoring and tracing support
Next Steps

References​

Official Documentation​