Skip to content

6.3. Platform Agents

What does the BYO Agent declare?

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: agentops-agent
  namespace: agentops
spec:
  type: BYO
  byo:
    deployment:
      image: agentops-agent:dev
      replicas: 1
      serviceAccountName: agentops-agent

Skaffold rewrites the logical image name to the configured registry and commit tag. kagent creates the A2A workload/service from this resource.

Which environment variables preserve the data plane?

- name: AGENT_MODEL_PROVIDER
  value: openai-compatible
- name: AGENT_MCP_URL
  value: http://agentgateway:3000/mcp
- name: OPENAI_BASE_URL
  value: http://agentgateway:4000/v1
- name: OPENAI_API_KEY
  value: agentgateway
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: http://otel-collector:4318
- name: AGENT_STATE_DIR
  value: /app/state

The application stays on its OpenAI-compatible provider in both overlays. The local overlay uses qwen3:4b; the optional GKE overlay uses gemini-3.5-flash behind agentgateway. No upstream provider credential enters the agent pod.

How is the pod hardened?

  • UID/GID/fsGroup 10001 and runAsNonRoot.
  • RuntimeDefault seccomp.
  • no privilege escalation and all capabilities dropped.
  • read-only root filesystem plus a 128 MiB /tmp limit.
  • CPU/memory requests and limits.
  • one replica with a 1 Gi RWO state PVC.
  • service-account token automount disabled for every course workload that does not call the Kubernetes API.

The optional GKE gateway and MLflow identities obtain ambient cloud credentials through the metadata server, so Workload Identity Federation does not require an automounted Kubernetes API token.

What is the ModelConfig for?

ModelConfig/agentgateway declares an OpenAI-compatible endpoint at http://agentgateway:4000/v1 for kagent-managed consumers. The API key Secret contains the non-secret SDK marker. The BYO agent uses its own environment variables, so the ModelConfig documents and enables the platform contract rather than injecting the BYO model.

The local overlay patches both the Agent and ModelConfig model names to qwen3:4b; the optional GKE overlay leaves the explicit Gemini model name while preserving the same OpenAI-compatible gateway endpoint.

How does Kubernetes know the processes are actually ready?

The agent image exposes two application-level endpoints on both network servers:

  • /livez proves the event loop can answer a trivial request.
  • On MCP, /healthz opens the agent-published runtime database read-only and runs a bounded SQLite integrity/schema probe.
  • On A2A, application startup owns first-boot initialization. /healthz then runs the same read-only database probe, verifies the writable state directory, and checks the persistent session/task store.

Health polling never creates state. On a fresh volume the A2A startup publishes the database atomically; MCP readiness remains false until that valid database appears on the shared claim. The static MCP Deployment wires the endpoints directly as startupProbe, readinessProbe, and livenessProbe; scripts/check-infra.sh asserts those exact rendered paths and that the 15-second pod grace period exceeds AGENT_DRAIN_TIMEOUT_S=10. Both MCP HTTP transports and A2A run under Uvicorn with that bounded graceful-shutdown timeout, so SIGTERM stops new work and gives in-flight requests time to finish before Kubernetes may send SIGKILL.

The pinned kagent v1alpha2 BYO deployment schema does not expose container probe or pod termination-grace fields. The course therefore does not pretend the controller-created A2A pod has probes it cannot declare. The endpoints still support a direct checkpoint:

kubectl -n agentops port-forward svc/agentops-agent 8080:8080
curl -fsS http://localhost:8080/livez
curl -fsS http://localhost:8080/healthz

When kagent adds those BYO fields, wire the same endpoints through the Agent resource and remove this limitation. Do not patch the generated Deployment behind the controller: reconciliation can overwrite that drift.

How do you verify the resource?

After the local Skaffold deploy:

kubectl -n agentops get agents.kagent.dev
kubectl -n agentops get pods,pvc,svc
kubectl -n agentops describe agent.kagent.dev/agentops-agent

Expected: one ready agent pod, bound agentops-agent-state, and ClusterIP agentops-agent on 8080.

What is the agent checkpoint?

Delete only the agent pod and watch kagent recreate it. Confirm the replacement mounts the same PVC and the agent card is available through gateway port 3001. This tests pod replacement, not zone/PV disaster recovery.