For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Create and communicate with your first agent by using the kagent project.

This guide walks you through creating an agent, from applying a Harness and an AgentTemplate to holding a conversation with the AgentInstance that they produce. You apply the Harness and the AgentTemplate as Kubernetes resources, and you create and talk to the AgentInstance with the kagent CLI. For definitions of each of these components, review the core concepts. For an overview of how each component fits together in kagent, review the architecture. For the complete schema of every field that this guide sets, see the API reference.

Before you begin

1. Install kagent with a WorkerPool provisioned.

2. Download the kagent CLI.

   curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash

3. Install jq, to read the AgentInstance ID out of the CLI’s JSON output.

Create a Harness and an AgentTemplate

1. Apply a Harness that uses kagent’s native runtime. Its substrate section names the WorkerPool that this Harness’s Actors run on, and the object storage location for their snapshots.

   apiVersion: kagent.dev/v1alpha3
   kind: Harness
   metadata:
     name: my-first-harness
     namespace: kagent
   spec:
     kagent: {}
     workload:
       # kagent's native runtime image, pinned by digest
       image: ghcr.io/kagent-dev/kagent/golang-adk@sha256:c8ab012e9774d50e20ffa8cd035ddebff69486a2843b3af281f5f6ebc67ab512
     substrate:
       workerPoolRef:
         name: kagent-default
       snapshotPolicy:
         # The object storage location your cluster's Substrate installation uses for Actor snapshots
         location: gs://<your-bucket>/kagent/
     allowedAgentTemplates:
       selector:
         matchLabels:
           # Selector to match the AgentTemplate label
           kagent.dev/harness: my-first-harness

   Note

   An AgentTemplate has no field naming this Harness. The kagent.dev/harness: my-first-harness selector is a convention that this guide uses to match the kagent.dev/harness label in the next step. However, you can choose any label key and value, as long as the Harness selector and the AgentTemplate’s labels match.

2. Apply an AgentTemplate that is labeled to match the Harness’s allowedAgentTemplates selector. The modelConfig field references the default-model-config ModelConfigModelConfigA Kubernetes custom resource naming one model at one provider, along with the credentials to reach it. An AgentTemplate references one by name, and every agent compiled from that template calls the model that it names.Learn more that was automatically created for the model provider API key that you provided during kagent installation.

   apiVersion: kagent.dev/v1alpha3
   kind: AgentTemplate
   metadata:
     name: my-first-agent
     namespace: kagent
     labels:
       # Label matching the Harness selector
       kagent.dev/harness: my-first-harness
   spec:
     description: My first kagent agent
     modelConfig:
       # Default config created by the kagent install guide
       name: default-model-config
     systemPrompt: You are a concise, helpful assistant.

3. Confirm that the pair is ready. The HARNESS column lists each Harness that admitted this AgentTemplate, and READY reports whether kagent compiled a runtime revisionRevisionThe compiled, immutable output of one Harness and AgentTemplate pairing, identified by a content digest. An AgentInstance runs the revision it was created from for its whole life, so editing either resource affects only instances created afterward. for that pairing.

   kagent get agent-template my-first-agent

   Example output:

   +----------------+------------------+-------+----------------------+
   | NAME           | HARNESS          | READY | CREATED              |
   +----------------+------------------+-------+----------------------+
   | my-first-agent | my-first-harness | TRUE  | 2026-08-31T15:01:44Z |
   +----------------+------------------+-------+----------------------+
   

   An empty HARNESS column with a READY value of UNKNOWN means that the kagent controller has not yet reconciled the pair. Wait a few seconds, then check again. If READY stays FALSE, inspect the individual conditions to find which stage failed.

   kagent get agent-template my-first-agent -o json

   Each entry in status.harnesses reports four conditions, ending in Ready. The Accepted condition covers the label selector match, ResolvedRefs covers the ModelConfig and tool references, Compatible covers whether the resolved configuration suits the Harness runtime, and Ready covers the compiled revision itself.

Create the AgentInstance

An AgentInstance is one running conversation. Creating it starts an Actor on the WorkerPool from the revision that kagent compiled for the Harness and AgentTemplate pair.

1. Create an AgentInstance from the Harness and AgentTemplate pair.

   kagent create agent-instance --harness my-first-harness --agent-template my-first-agent

   The command returns output only after the AgentInstance reaches the READY state. Example output:

   +--------------------------------------+----------------+------------------+-------+----------------------+
   | ID                                   | AGENT TEMPLATE | HARNESS          | STATE | CREATED              |
   +--------------------------------------+----------------+------------------+-------+----------------------+
   | 0198c3d7-4f2a-7b61-9c3e-5d8f7a2b4e10 | my-first-agent | my-first-harness | READY | 2026-08-31T15:02:10Z |
   +--------------------------------------+----------------+------------------+-------+----------------------+
   

   An error reporting that the AgentTemplate and Harness have no ready prepared revision means that the pair is not READY yet. Return to step 3 of the previous section to check the conditions.

2. Save the AgentInstance’s ID to an environment variable.

   export INSTANCE_ID=$(kagent get agent-instance -o json \
     | jq -r '[.agentInstances[] | select(.agentTemplate.name == "my-first-agent")] | sort_by(.createdAt) | last | .id')
   echo $INSTANCE_ID

Talk to your agent

1. Send a message to the AgentInstance. The CLI holds the conversation over the A2AA2AThe Agent-to-Agent protocol, which callers and other agents use to talk to an AgentInstance. The conversation's context identifier is the AgentInstance ID, so a second message on the same ID continues the same conversation.Learn more (Agent-to-Agent) protocol.

   kagent invoke --agent-instance $INSTANCE_ID --task "What is 2+2?"

   The agent’s reply prints as text.

   4
   

2. Send a follow-up message to the same AgentInstance. An AgentInstance holds the transcriptTranscriptThe record of an AgentInstance's conversation, held server-side and append-only. It survives the Actor suspending between turns, and a resumed runtime cannot shrink it. of its conversation, so the agent answers with the earlier turns in context.

   kagent invoke --agent-instance $INSTANCE_ID --task "What did I just ask you?"

   You asked what 2+2 is.
   

The invoke command takes a few more options that are useful beyond a first conversation.

Clean up

To remove the resources, follow these steps.

1. Delete every AgentInstance that was created from the AgentTemplate. Later guides create their own instances from the same pair, so delete them all rather than only the one that you saved. Deleting the Harness and the AgentTemplate does not delete the AgentInstances that you created from them, so delete the instances first.

   kagent get agent-instance -o json \
     | jq -r '.agentInstances[] | select(.agentTemplate.name == "my-first-agent") | .id' \
     | xargs -n1 kagent delete agent-instance

2. Delete the AgentTemplate and the Harness.

   kubectl delete agenttemplate my-first-agent -n kagent
   kubectl delete harness my-first-harness -n kagent

Next steps