Using Kagent Substrate
Agent
This lab creates a Harness, an AgentTemplate, and an Agent with the kagent api.kagent.dev/v1alpha3 API, then talks to the Agent. Each conversation runs as a Substrate Actor.
Prerequisites
- kagent
1.0.0-alpha14and Substrate0.5.0-alpha2, installed withkagent installas shown in Install kagent and Agent Substrate. - WorkerPool
kagent/kagent-defaultand ModelConfigkagent/default-model-config. Both are created by that install.
The Helm-only 0.10.x install path in the installation lab uses the older
kagent.dev/v1alpha2API (SandboxAgent,AgentHarness). The manifests below don’t apply to it.
Two things are needed to create an Agent:
- A snapshot location for the Actors
- A Harness (the runtime that runs the Agent)
You don’t need your own Agent image anymore. The kagent Harness uses the built-in runtime image that ships with the kagent release, pinned by digest.
Storage Location
By default, the snapshot location is gs://ate-snapshots/kagent/. ate-snapshots is the in-cluster RustFS bucket that the Substrate chart creates. Substrate only uses the bucket and path from this URL. The storage backend comes from Substrate’s atelet.storageBackend setting (s3, backed by RustFS, by default), so the gs:// prefix still lands in RustFS. kagent’s own end-to-end tests use this same location.
The default lives inside the cluster. It’s good for demo and testing purposes, but not production.
If you want to create your own storage location, see the next section.
Your own bucket (GCS example)
Below is an example of creating a Google Cloud Storage (GCS) bucket for your snapshots. Actors (where your Agents run) save and restore their state from this location.
export PROJECT_ID=$(gcloud config get-value project)
export REGION=$(gcloud config get-value compute/region)
export BUCKET_NAME="ate-snapshots-${PROJECT_ID}"
gcloud storage buckets create "gs://${BUCKET_NAME}" \
--project="${PROJECT_ID}" \
--location="${REGION}" \
--uniform-bucket-level-accessCreating the bucket isn’t enough on its own. Substrate also has to be set up to use it:
- Install the
substratechart withrustfs.enabled=false. - Change
atelet.storageBackendfroms3. In the upstream Substrate code, any value other thans3selects GCS. - Give atelet and ate-api-server access to the bucket, for example with GKE Workload Identity.
Pass those values with install.substrate.valuesFiles in the kagent CLI config. Then set the Harness’s snapshotPolicy.location to gs://${BUCKET_NAME}/kagent/.
Harness Implementation
kagent supports the following harnesses:
kagentcodexclaudebyo
All four can be used with Agent Substrate, so each Harness runs in an isolated sandbox.
You set the harness in the Harness object. The example below uses the kagent harness.
kagent,codex, andclaudeuse the built-in image for that harness, so you can leave outworkload.image.byomust setworkload.image.- To run your own image, or a mirrored copy such as an Artifact Registry copy of
golang-adk, setspec.workload.image. The image must be pinned with@sha256:, or the controller rejects it withHarness image must be pinned by sha256 digest.
There are three objects below:
Harness: which Agent harness to use, the WorkerPool it runs on, and the snapshot locationAgentTemplate: the template (configs) the Agent will use: model, prompt, tools, and skills (think of it like a golden image, but “image” is a heavy word)Agent: the actual running Agent, which pairs one AgentTemplate with one Harness
kagent does not create Harnesses for you.
kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: Harness
metadata:
name: kagent
namespace: kagent
spec:
kagent: {}
substrate:
workerPoolRef:
name: kagent-default
snapshotPolicy:
location: gs://ate-snapshots/kagent/
---
apiVersion: api.kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
name: assistant
namespace: kagent
spec:
modelConfig:
name: default-model-config
description: A substrate-backed assistant.
systemPrompt: You are a helpful assistant running on kagent.
---
apiVersion: api.kagent.dev/v1alpha3
kind: Agent
metadata:
name: assistant
namespace: kagent
spec:
template:
ref:
name: assistant
harnessRef:
name: kagent
EOFWait for everything to become ready:
kubectl wait --for=condition=Ready harness/kagent -n kagent --timeout=5m
kubectl wait --for=condition=Ready agent/assistant -n kagent --timeout=5m
kubectl get agents,agenttemplates,harnesses -n kagentWhen the Agent is Ready, the controller has:
- compiled a revision of the Agent,
- registered it with the Substrate API as an ActorTemplate,
- built the golden snapshot that every Actor of this Agent starts from.
The ActorTemplate still exists: kagent creates one for every Agent revision. It lives in Substrate’s API (backed by PostgreSQL), not as a Kubernetes CRD, so kubectl get actortemplates won’t find it. Substrate’s kubectl ate get actor-templates -A will.
How the objects fit together:
AgentTemplate (behavior: model, prompt, tools, skills)
+ Harness (execution: runtime, WorkerPool, snapshot location)
= Agent
↓ kagent compiler
immutable revision → ActorTemplate → golden snapshot
↓ per conversation
Session → Substrate ActorTest the Agent
No Actor exists until a conversation starts. Each conversation is a Session. A Session lives in PostgreSQL, not in Kubernetes. Each Session gets its own Substrate Actor, which is restored from the golden snapshot and suspended again when it goes idle.
From the UI:
kagent dashboardOr port-forward the UI and open http://localhost:8080:
kubectl -n kagent port-forward service/kagent-ui 8080:8080Select the assistant Agent and send a message. The first message creates the Session and its Actor.
From the CLI (the CLI opens its own port-forward to kagent-controller:8083):
kagent agent session create --agent assistantCopy the Session ID from the output, then send a message:
export SESSION_ID=<session-id>
kagent agent invoke --session "${SESSION_ID}" --task "Say hello"Clean up
kubectl delete agent assistant -n kagent
kubectl delete agenttemplate assistant -n kagent
kubectl delete harness kagent -n kagentWhat changed from the earlier version of this lab
Earlier (1.0.0-alpha7) | Now (1.0.0-alpha14) |
|---|---|
spec.templateRef.name on the Agent | spec.template.ref.name (or an inline spec.template) |
workload.image: ghcr.io/kagent-dev/kagent/golang-adk@sha256:... set on the kagent Harness | Optional. When it’s left out, the release’s built-in, digest-pinned image is used |
snapshotPolicy.location: s3://ate-snapshots/kagent/ | gs://ate-snapshots/kagent/, the same RustFS bucket, matching kagent’s e2e tests |
You can see more configurations and options here.