Running a Declarative Kubernetes Agent Builder on a Local Cluster

kagent now supports a declarative Kubernetes agent builder that can turn a natural‑language description into a new kagent Agent resource and deploy it on a local kind cluster. Practitioners can prototype the full create‑apply‑verify loop on a laptop without paying for API tokens, while also seeing the concrete security and operational boundaries of running AI agents as Kubernetes custom resources.

How the Kubernetes Agent Builder Works

In kagent, an agent is defined as a Agent custom resource (CR). The controller watches these CRs, creates a pod that runs the LLM, and exposes a simple A2A (agent‑to‑agent) interface. By describing the builder as an Agent with a system prompt and a list of tools, the same controller can generate other agents. The builder uses three built‑in tools:

• k8s_get_resources – list existing agents in the kagent namespace.
• k8s_apply_manifest – apply a single YAML manifest that matches the Agent schema.
• k8s_get_resource_yaml – retrieve the newly created resource to inspect its Accepted and Ready conditions.

The system message instructs the model to produce exactly one manifest, avoid follow‑up questions, and pick a unique name. Because the builder itself is just another Agent, the entire workflow is version‑controlled and repeatable.

Implementation Steps on a Laptop

All required tools are open source: Docker, kind, kubectl, Helm, jq, and Ollama (or an API key for a hosted model). The example uses the local model qwen3-coder:30b-a3b-q4_K_M, pulled with:

ollama pull qwen3-coder:30b-a3b-q4_K_M

After creating a kind cluster (kind create cluster --name kagent-builder), the Helm chart is installed with a custom values file that limits the tool server to read‑only Kubernetes access plus a single write rule for agents.kagent.dev. The chart disables the default sample agents so the UI only shows resources you create.

helm upgrade --install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --kube-context kind-kagent-builder \
  --version 0.10.2 --namespace kagent --create-namespace
helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --kube-context kind-kagent-builder \
  --version 0.10.2 --namespace kagent --values kagent-values.yaml

With the controller running, the builder agent is created as a simple YAML file:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: agent-builder
  namespace: kagent
spec:
  description: Builds new kagent agents from a plain‑language description and deploys them.
  type: Declarative
  declarative:
    modelConfig: default-model-config
    stream: false
    systemMessage: |
      You build kagent agents. The user describes, in plain language, an agent they want. You turn that into ONE Kubernetes manifest and apply it.

Applying this manifest makes the builder available in the UI; a user can then type a description, and the builder will generate and apply a new Agent resource automatically.

Operational and Security Considerations

The default deployment runs in an “unsecure auth mode” where every request is treated as the same user. The UI and API are exposed only via kubectl port-forward on 127.0.0.1, which is acceptable for a personal laptop but unsuitable for a shared or production cluster. The tool server’s ServiceAccount is granted read‑only access to most Kubernetes resources and a single write permission for agents.kagent.dev. This limited RBAC mitigates accidental changes but does not replace a full authentication and authorization strategy.

Using a local LLM avoids token costs but requires ~18 GB of disk space and a host address that Docker Desktop resolves automatically (host.docker.internal:11434). On Linux the address must be adjusted for the kind node to reach the Ollama service.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

• Try the builder on a laptop to validate the declarative agent workflow before committing to a shared environment.
• Plan to replace the insecure auth mode with a proper identity provider and tighten RBAC if you move beyond a personal dev setup.
• Monitor resource consumption of the large local model; consider hosted providers for production scaling.
• Use the same Agent CRD pattern to version‑control other AI‑driven automation pipelines.