# kagent: Kubernetes Native Agents Built on Custom Resources

> kagent turns AI agents into Kubernetes custom resources managed with kubectl. It is a good fit for platform teams already running clusters, and a poor fit for anyone who does not want a cluster in the loop.

**kagent-dev/kagent** — Cloud Native Agentic AI | Discord: https://bit.ly/kagentdiscord

- Repository: https://github.com/kagent-dev/kagent
- Website: https://kagent.dev
- Stars: 3,907 · Forks: 802
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/kagent-dev-kagent

## The problem kagent solves for platform teams

Running an AI agent in production means solving a set of problems that have nothing to do with the model: where does the process run, how does it get credentials, how do you roll out a new system prompt, how do you see what it did last Tuesday. Teams that already run Kubernetes have answers to all of those questions, and kagent's bet is that agents should be expressed in the vocabulary those teams already use. An agent becomes a custom resource called Agent. A set of tools becomes a ToolServer. A model endpoint and its credentials become a ModelConfig. The audience is the platform or infrastructure engineer who is comfortable writing YAML and running kubectl, not the data scientist who wants a notebook. The README states the framework is designed to be easy to understand and use, and the core principles it lists are Kubernetes native, extensible, flexible, observable, declarative and testable. Those are the properties you get for free by living inside the cluster's control plane, and they are the reason to accept the operational weight.

## Four components and how an agent actually runs

The repository documents four core components. The controller watches the kagent custom resources and creates the resources needed to run the agents. The engine runs the agents using ADK, Google's Agent Development Kit. The UI is a web interface for managing agents and tools. The CLI manages agents and tools from a terminal. That split matters: the controller is the reconciliation loop, so the desired state of an agent lives in etcd and the engine is the thing that executes it. Tools come from MCP servers, and kagent ships an MCP server with tools for Kubernetes, Istio, Helm, Argo, Prometheus, Grafana and Cilium. Each is exposed as a ToolServer custom resource, and the README notes the same ToolServer can be used by multiple agents, which is the main reason to model tools separately rather than inline in an agent definition. Model access is a ModelConfig, and the supported providers listed are OpenAI, Azure OpenAI, Anthropic, Google Vertex AI and Ollama, plus any custom provider or model reachable through an AI gateway. Observability is OpenTelemetry tracing, which the README links to a dedicated tracing page. One design consequence worth naming: because an agent is a system prompt plus a set of tools and agents plus an LLM configuration, an agent can reference other agents. The README does not spell out the depth limits or cycle handling for that composition, so treat nested agents as something to test before you rely on it.

## Installing kagent and running a first agent

The README does not inline installation commands. It points to a Quick Start and an Installation guide on kagent.dev, so the authoritative steps live there and you should follow them rather than any command copied from a blog post. What the repository does show is the packaging: there is a helm/ directory at the top level, and the Makefile defines HELM_REPO ?= oci://ghcr.io/kagent-dev, which tells you the charts are published to an OCI registry rather than a classic chart repository. The Makefile also shows the local development loop expects a registry on localhost:5001 (DOCKER_REGISTRY ?= localhost:5001), which is the conventional port for a kind or k3d registry. If you are installing for real, take the chart from the installation guide; if you are hacking on kagent itself, the Makefile and DEVELOPMENT.md are the entry points. Once the controller and engine are running, an agent is a resource you apply. The README describes the shape but does not print a manifest, so the examples/ directory is where you should look for a working one, and examples/modelconfig-with-tls.yaml is the concrete case for a TLS-protected model endpoint. Managing the result is meant to be ordinary kubectl work, which is the whole point of the design.

## Where kagent is the wrong tool

The cost of the Kubernetes native design is Kubernetes. A single developer who wants an agent on a laptop now has to run a cluster, a controller, an engine, and a UI before the first prompt is answered. There is a devcontainer and a Codespaces badge in the README, which softens that for contributors, but it does not remove the dependency. The second limitation is maturity of the surface area. The README says kagent is currently in active development and points to a Kanban board for the roadmap. The release history shows the project is still moving quickly: v0.10.1 landed on 2026-09-08, four days after v0.10.0 on 2026-09-04, which followed v0.10.0-rc6 on 2026-09-01. A project that ships release candidates for a minor version is not promising that custom resource fields are frozen. If you write your own Agent and ToolServer manifests, budget for edits on upgrade. Third, the README does not document rollback, migration between versions, or what happens to running agents when the controller is upgraded. Those are real gaps for a platform team that has to promise an upgrade window, and the honest answer is that the documentation is silent on them.

## kagent compared with a plain agent framework

The natural alternative is a general-purpose agent framework such as ADK itself, or any of the Python-first agent libraries that run as a normal process. The difference is not capability, it is where state lives. A plain framework keeps agent definitions in code, secrets in environment variables or a vault, and deployment in whatever CI system you already have. kagent moves all of that into the cluster's API server: the agent definition is a custom resource, the model configuration is a custom resource, the tool server is a custom resource, and the controller reconciles them. You gain a single audit trail, kubectl-based debugging, and the ability to reuse one ToolServer across many agents. You give up the ability to run the agent without a cluster, and you inherit the API server as a dependency for anything the agent needs at startup. Note also that kagent is not a replacement for ADK: the README states the engine runs agents using ADK, so ADK is underneath, not beside. If your team already has a Kubernetes platform and a review process for cluster changes, kagent fits that process. If your team ships agents as application code, a plain framework will be less ceremony for the same result.

## Licence, maintenance and upgrade cost

kagent is licensed under Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It does not impose copyleft obligations on your own code. That is the permissive end of the spectrum and it is the same licence used by Kubernetes itself, so it will not be a blocker in most corporate reviews. This is not legal advice; check with your own counsel if you are redistributing the project or bundling it into a product. On maintenance, the repository is not archived and the last push was on 2026-09-10, with v0.10.1 released on 2026-09-08. The README describes a roadmap on a Kanban board and lists CNCF Slack, Discord and community meetings as the places where work is coordinated, and the topics list includes cncf. The upgrade cost is the part to plan for. A fast release cadence on a project whose extension points are custom resources means your manifests are the thing most likely to need attention. Pin the chart version, keep your Agent and ToolServer definitions in version control next to the rest of your cluster manifests, and read the release notes before moving between minor versions.

## Conclusion

Adopt kagent if you already run Kubernetes, want agents declared in YAML, and need the bundled Kubernetes, Istio, Helm, Argo, Prometheus, Grafana and Cilium tool servers. Do not adopt it if you have no cluster or you need a stable API surface: the README points to a roadmap board and calls the project active, and the CRD shapes can still move between releases. Verify first that your target cluster version matches the installation guide, that your chosen provider is one of the documented ones (OpenAI, Azure OpenAI, Anthropic, Google Vertex AI, Ollama, or a custom provider through an AI gateway), and that the ModelConfig resource in examples/modelconfig-with-tls.yaml matches how your endpoint authenticates.

## FAQ

### What is kagent?

kagent is a Kubernetes native framework for building AI agents. Agents, tools and model configurations are represented as Kubernetes custom resources, and the project ships a controller, a UI, an engine that runs agents with ADK, and a CLI.

### Is kagent a CNCF project?

The repository topics include cncf, and the README directs contributors to the CNCF #kagent Slack channel. The README does not state a CNCF project maturity level, so treat the CNCF relationship as a community channel rather than a formal graduation claim.

### How do I install kagent?

The README points to a Quick Start and an Installation guide on kagent.dev rather than inlining commands. The repository shows the charts are published to an OCI registry (HELM_REPO ?= oci://ghcr.io/kagent-dev in the Makefile), so follow the installation guide for the current chart reference.

### What are the four types of agents?

The README does not describe four types of agents. It documents four core components: the controller, the UI, the engine and the CLI, and it describes agents as a system prompt, a set of tools and agents, and an LLM configuration.

### Is kagent open source?

Yes. The repository is licensed under Apache-2.0, the same permissive licence Kubernetes uses, and the source is public on GitHub.

## Sources

- [kagent-dev/kagent on GitHub](https://github.com/kagent-dev/kagent)
- [License: Apache-2.0](https://github.com/kagent-dev/kagent/blob/main/LICENSE)
- [Project website](https://kagent.dev)
- [README](https://github.com/kagent-dev/kagent/blob/main/README.md)
- [Releases](https://github.com/kagent-dev/kagent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kagent-dev-kagent