Kagent is a Kubernetes-native AI agent framework designed to build, deploy, and manage AI agents as native cluster resources. By utilizing Custom Resource Definitions (CRDs), it enables declarative AI agent management, allowing DevOps and SRE teams to automate complex K8s operations, perform AI-driven health diagnostics, and implement advanced AIOps workflows through natural language and integrated tooling.

When should I use kagent?

kagent is useful in the following scenarios: • Automated Cluster Health Analysis: Proactively analyze cluster health, identify resource bottlenecks, and generate comprehensive status reports using AI-powered diagnostics. • Infrastructure Resource Optimization: Automatically identify over-provisioned deployments or pods without resource limits and receive intelligent recommendations for cost-effective adjustments. • Security and Compliance Auditing: Scan clusters for security vulnerabilities, such as pods running with root privileges or services exposed without proper ingress, to ensure a hardened infrastructure. • Intelligent Troubleshooting and RCA: Rapidly diagnose the root cause of failing pods, OOMKilled events, or network connectivity issues by querying the cluster in natural language. • Declarative Agent Management: Deploy persistent AI agents as Kubernetes CRDs that can manage specific namespaces, execute kubectl commands, and maintain long-term operational workflows.

name	kagent
description	Kubernetes-native AI agent framework for building, deploying, and managing AI agents on Kubernetes. This skill should be used when deploying AI agents as Kubernetes resources, analyzing cluster health with AI, and automating complex K8s operations. Use this skill for Phase IV advanced AIOps and agent-based cluster management.

Kagent Skill

Overview

Kagent is a Kubernetes-native framework for building, deploying, and managing AI agents. It uses Custom Resource Definitions (CRDs) to define agents as Kubernetes resources, enabling declarative AI agent management with full K8s integration.

Key Concepts

What Kagent Provides

Kubernetes-Native Agents: Define AI agents as CRDs
Cluster Analysis: AI-powered health checks and optimization
Extensibility: Custom tools and integrations
Observability: Full visibility into agent operations

Architecture

┌─────────────────────────────────────────────────────┐
│                  Kubernetes Cluster                  │
│  ┌─────────────────┐    ┌─────────────────────────┐ │
│  │ Kagent          │    │ Custom Resources        │ │
│  │ Controller      │───▶│ - Agent                 │ │
│  │                 │    │ - Tool                  │ │
│  │                 │    │ - Model                 │ │
│  └─────────────────┘    └─────────────────────────┘ │
│           │                                          │
│           ▼                                          │
│  ┌─────────────────────────────────────────────────┐ │
│  │              AI Agent Pods                       │ │
│  │  - Execute kubectl commands                      │ │
│  │  - Analyze resources                             │ │
│  │  - Report findings                               │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Installation

Prerequisites

Kubernetes cluster (Minikube, kind, or cloud)
kubectl configured
Go 1.21+ (for building from source)

Install from Bundle

# Install CRDs and controller
kubectl apply -f https://raw.githubusercontent.com/kagent-dev/kagent/main/dist/install.yaml

Build from Source

# Clone repository
git clone https://github.com/kagent-dev/kagent.git
cd kagent/go

# Install CRDs
make install

# Deploy controller
make deploy

Build Installer Bundle

# Generate consolidated install.yaml
make build-installer

Usage

Basic Kubernetes Operations

Kagent agents can execute standard kubectl commands:

# Resource listing
kubectl get pods -n namespace
kubectl get deployments -n namespace
kubectl get services -n namespace

# Detailed listing
kubectl get pods -n namespace -o wide
kubectl get nodes -o wide

Resource Inspection

# Describe resources
kubectl describe pod podname -n namespace
kubectl describe deployment deployname -n namespace
kubectl describe service servicename -n namespace

# Get full YAML
kubectl get configmap configname -n namespace -o yaml
kubectl get secret secretname -n namespace -o yaml

Health and Status Queries

# Component health
kubectl get componentstatuses
kubectl get nodes -o wide

# Resource status
kubectl get deployments -n namespace -o wide
kubectl get pods -n namespace -o wide

Advanced Operations

# Node management
kubectl drain <node>
kubectl cordon/uncordon <node>

# Port forwarding
kubectl port-forward svc/my-service 8080:80

# Authorization checks
kubectl auth can-i create pods

# Debugging
kubectl debug pod/my-pod --image=busybox

Diagnostic Tools

Kagent agents have access to:

Tool	Purpose
`crictl`	Container runtime interface
`kubelet logs`	Node-level logs
`journalctl`	System logs
`tcpdump`	Network diagnostics
`netstat`	Connection status

Use Cases for TaskFlow

1. Cluster Health Analysis

Use kagent to analyze overall cluster health before deployment:

kagent "analyze the cluster health and report any issues"
kagent "check if there are sufficient resources for 5 new pods"

2. Resource Optimization

kagent "identify pods without resource limits"
kagent "find over-provisioned deployments"
kagent "recommend resource adjustments based on actual usage"

3. Security Audit

kagent "find pods running as root"
kagent "identify services exposed without ingress"
kagent "check for secrets mounted as environment variables"

4. Troubleshooting

kagent "why are pods in namespace X failing?"
kagent "analyze network connectivity between services"
kagent "find the root cause of OOMKilled pods"

Custom Resource Definitions

Agent CRD Example

apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
  name: cluster-analyzer
  namespace: kagent-system
spec:
  model:
    provider: openai
    name: gpt-4
  tools:
    - kubectl
    - helm
  systemPrompt: |
    You are a Kubernetes cluster analyzer.
    Focus on identifying resource issues and optimization opportunities.

Tool CRD Example

apiVersion: kagent.dev/v1alpha1
kind: Tool
metadata:
  name: kubectl-tool
spec:
  type: kubectl
  permissions:
    - get
    - list
    - describe
  namespaces:
    - default
    - production

Integration with kubectl-ai

Kagent complements kubectl-ai:

Tool	Best For
kubectl-ai	Ad-hoc commands, quick operations
kagent	Persistent agents, complex analysis, automation

Combined Workflow

# Use kubectl-ai for immediate operations
kubectl-ai "scale api to 3 replicas"

# Use kagent for analysis and recommendations
kagent "analyze if scaling to 3 replicas is sustainable given current cluster resources"

Best Practices

Start with read-only: Begin with agents that only read cluster state
Namespace scope: Limit agent permissions to specific namespaces
Audit trail: Enable logging for all agent operations
Resource limits: Set limits on agent pods themselves
Gradual automation: Start manual, then automate proven workflows

Resources

Refer to references/agent-patterns.md for common agent configurations.

When & Why to Use This Skill

Use Cases