Development

To understand how to develop for kagent, It's important to understand the architecture of the project. Please refer to the README.md file for an overview of the project.

When making changes to kagent, the most important thing is to figure out which piece of the project is affected by the change, and then make the change in the appropriate folder. Each piece of the project has its own README with more information about how to setup the development environment and run that piece of the project.

• python: Contains the code for the ADK engine.
• go: Contains the code for the kubernetes controller, and the CLI.
• ui: Contains the code for the web UI.

Dependencies

Before you can run kagent in Kubernetes, you need to have the following tools installed:

Required Dependencies

• Kind (v0.27.0+)
• kubectl (v1.33.4+)
• Helm
• Go (v1.26.1+)
• Docker
• Docker Buildx (v0.23.0+)
• Make

Installation Verification

You can verify your installation by running:

# Check core dependencies
kind version
kubectl version
helm version
go version
docker version
docker buildx version
make --version

How to run everything in Kubernetes

1. Create a cluster:

make create-kind-cluster

1. Configure the cluster and set the default namespace kagent:

make use-kind-cluster

1. Set your model provider:

export KAGENT_DEFAULT_MODEL_PROVIDER=openAI
#or
export KAGENT_DEFAULT_MODEL_PROVIDER=anthropic

1. Set your providers API_KEY:

export OPENAI_API_KEY=your-openai-api-key
#or
export ANTHROPIC_API_KEY=your-anthropic-api-key

Alternatively, create a .env file at the repo root (gitignored). This file is loaded by the Makefile (via -include .env) to inject environment variables when you run make targets:

# Set your provider (supported: openAI, anthropic, azureOpenAI, gemini, ollama)
KAGENT_DEFAULT_MODEL_PROVIDER=openAI

# Set the corresponding API key for your provider
OPENAI_API_KEY=your-openai-api-key
# ANTHROPIC_API_KEY=your-anthropic-api-key
# GOOGLE_API_KEY=your-google-api-key

1. Build images, load them into kind cluster and deploy everything using Helm:

make helm-install

To apply personal Helm overrides without committing them, create helm/kagent/values.local.yaml (gitignored) and set KAGENT_HELM_EXTRA_ARGS in your .env file (which is read by the Makefile when you run make):

# .env
KAGENT_HELM_EXTRA_ARGS=-f helm/kagent/values.local.yaml

To access the UI, port-forward to the UI port on the kagent-ui service:

kubectl port-forward svc/kagent-ui 8001:8080

Then open your browser and go to http://localhost:8001.

Addons

Optional addons are available to enhance your development environment with observability and infrastructure components.

Prerequisites: Complete steps 1-3 above (cluster creation and environment variables).

To install all addons:

make kagent-addon-install

This installs the following components into your cluster:

Addon	Description	Namespace
Istio	Service mesh (demo profile)	istio-system
Grafana	Dashboards and visualization	kagent
Prometheus	Metrics collection	kagent
Metrics Server	Kubernetes resource metrics	kube-system

PostgreSQL is deployed automatically as part of make helm-install via the bundled Helm chart. The optional addons above provide observability components.

pgvector: The default bundled PostgreSQL image (postgres:18) does not include the pgvector extension. If you need vector features (e.g. long-term memory), either use an external PostgreSQL instance with pgvector installed, or override the bundled image to pgvector/pgvector:pg18-trixie and set database.postgres.vectorEnabled=true. The make helm-install target does this automatically for local development.

Verify the database connection by checking the controller logs:

kubectl logs -n kagent deployment/kagent-controller | grep -i postgres

Troubleshooting

buildx localhost access

The make helm-install command might time out with an error similar to the following:

ERROR: failed to solve: DeadlineExceeded: failed to push localhost:5001/kagent-dev/kagent/controller

As part of the build process, the buildx container tries to build and push the kagent images to the local Docker registry. The buildx command requires access to your host machine's Docker daemon.

Recreate the buildx builder with host networking, such as with the following example commands. Update the version and platform accordingly.

docker buildx rm kagent-builder-v0.23.0

docker buildx create --name kagent-builder-v0.23.0 --platform linux/amd64,linux/arm64 --driver docker-container --use --driver-opt network=host

Then run the make helm-install command again.

Run kagent and an agent locally

create a minimal cluster with kind. scale kagent to 0 replicas, as we will run it locally.

make create-kind-cluster helm-install-provider helm-tools push-test-agent push-test-skill
kubectl scale -n kagent deployment kagent-controller --replicas 0

Run kagent with KAGENT_A2A_DEBUG_ADDR=localhost:8080 environment variable set, and when it connect to agents it will go to "localhost:8080" instead of the Kubernetes service.

Run the agent locally as well, with --net=host option, so it can connect to the kagent service on localhost. For example:

docker run --rm \
  -e KAGENT_URL=http://localhost:8083 \
  -e KAGENT_NAME=kebab-agent \
  -e KAGENT_NAMESPACE=kagent \
  --net=host \
  localhost:5001/kebab:latest