For a values-driven install with more customization options, see the Helm deployment guide.

Choose an Overlay

The repository provides pre-configured overlays for different scenarios:

Overlay	Description	Best For	Source
`python-demo`	Control plane + Python demo agent	Quick evaluation (recommended)	View
`local-demo`	Control plane + Go demo agent	Testing Go SDK (requires custom image)	View
`postgres-demo`	PostgreSQL + Go demo agent	Production-like storage testing	View

The python-demo overlay is the easiest to get started with — it installs the Python SDK from PyPI at startup, so no custom image build is required.

Quick Start

Create Namespace

kubectl create namespace agentfield --dry-run=client -o yaml | kubectl apply -f -
kubectl config set-context --current --namespace=agentfield

Apply the Overlay

kubectl apply -k deployments/kubernetes/overlays/python-demo

Wait for pods to be ready (first run installs Python dependencies):

kubectl -n agentfield wait --for=condition=Ready pod -l app.kubernetes.io/component=control-plane --timeout=300s
kubectl -n agentfield wait --for=condition=Ready pod -l app.kubernetes.io/component=demo-python-agent --timeout=600s

Port-Forward the UI/API

kubectl port-forward svc/agentfield-control-plane 8080:8080

Open the UI at http://localhost:8080/ui/

Verify health:

curl -s http://localhost:8080/api/v1/health

Execute an Agent

curl -X POST http://localhost:8080/api/v1/execute/demo-python-agent.hello \
  -H "Content-Type: application/json" \
  -d '{"input":{"name":"World"}}'

Other Overlays

Go Demo Agent (requires custom image)

Build and load the image first (see Dockerfile.demo-go-agent):

docker build -t agentfield-demo-go-agent:local -f deployments/docker/Dockerfile.demo-go-agent .
minikube image load agentfield-demo-go-agent:local

docker build -t agentfield-demo-go-agent:local -f deployments/docker/Dockerfile.demo-go-agent .
kind load docker-image agentfield-demo-go-agent:local --name <cluster-name>

Then apply:

kubectl apply -k deployments/kubernetes/overlays/local-demo

PostgreSQL + Go Demo Agent

For production-like storage with PostgreSQL:

kubectl apply -k deployments/kubernetes/overlays/postgres-demo

Architecture

┌─────────────────────────────────────────────────────┐
│                    Kubernetes Cluster               │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ agentfield-control-plane (Deployment)         │  │
│  │ • HTTP API on port 8080                       │  │
│  │ • gRPC on port 8180                           │  │
│  │ • Embedded Web UI                             │  │
│  │ • Health endpoint: /api/v1/health             │  │
│  └───────────────────────┬───────────────────────┘  │
│                          │                          │
│            Internal DNS (Service discovery)         │
│                          │                          │
│  ┌───────────────────────▼───────────────────────┐  │
│  │ demo-python-agent (Deployment)                │  │
│  │ • Registers with control plane on startup     │  │
│  │ • Callback URL: http://service-name:8001      │  │
│  │ • Exposes actions for execution               │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Key points:

Control plane is stateless (scales horizontally)
Agents register via their Kubernetes Service DNS names
All state stored locally (SQLite/BoltDB) or in PostgreSQL

Connecting Your Own Agents

To connect your own agent to the control plane running in Kubernetes:

From inside the cluster: Set AGENTFIELD_URL=http://agentfield-control-plane:8080
From outside the cluster: Use port-forward or Ingress, then set AGENTFIELD_URL=http://localhost:8080

Always use a Kubernetes Service DNS name for AGENT_CALLBACK_URL (e.g., http://my-agent-service:8001), not localhost. The control plane must be able to reach your agent.

Useful Commands

# Check pod status
kubectl get pods

# View control plane logs
kubectl logs -l app.kubernetes.io/component=control-plane

# View agent logs
kubectl logs -l app.kubernetes.io/component=demo-python-agent

# Describe pod for debugging
kubectl describe pod -l app.kubernetes.io/component=control-plane

# Shell into control plane
kubectl exec -it deployment/agentfield-control-plane -- sh

Cleanup

# Delete all resources
kubectl delete -k deployments/kubernetes/overlays/python-demo

# Delete namespace
kubectl delete namespace agentfield

Notes

The Python demo agent installs the SDK at startup — your cluster needs outbound network access
For agent nodes, always use a Service DNS name for callback URLs, not localhost

Source files:

Base manifests — Control plane deployment, service, and PVC
Overlays — Pre-configured Kustomize overlays

Helm Deployment — Values-driven install with more customization
Docker Deployment — Local development with Docker Compose
Monitoring — Prometheus metrics and observability

Kubernetes (Kustomize)