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 Agent that pairs them. You apply the Harness, the AgentTemplate, and the Agent as Kubernetes resources. Then, you create and talk to a Session 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. The --version flag matches the CLI to the release that these docs cover.

   curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v1.0.0-alpha7

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

Create a Harness, an AgentTemplate, and an Agent

Three resources define a runnable agent: a Harness holds the runtime, an AgentTemplate holds the behavior, and an Agent pairs one of each.

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: api.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:215417b5401310bb496ae1687bb8622f93fd19991a218c6a218987836e71da84
     substrate:
       workerPoolRef:
         name: kagent-default
       snapshotPolicy:
         # The bucket that the Agent Substrate chart creates in its bundled object store.
         # If your Substrate installation uses your own object storage, use that location instead.
         location: s3://ate-snapshots/kagent/

2. Apply an AgentTemplate. 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: api.kagent.dev/v1alpha3
   kind: AgentTemplate
   metadata:
     name: my-first-template
     namespace: kagent
   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. Apply an Agent that pairs a Harness and an AgentTemplate.

   apiVersion: api.kagent.dev/v1alpha3
   kind: Agent
   metadata:
     name: my-first-agent
     namespace: kagent
   spec:
     templateRef:
       name: my-first-template
     harnessRef:
       name: my-first-harness

   Note

   Each side of the pairing takes either a reference, as shown here, or a complete spec written inline under spec.template or spec.harness. The two choices are independent, so an Agent can reference one side and inline the other. An inline spec is a complete value rather than an override, and kagent creates no Kubernetes object to back it.

4. Confirm that the Agent is ready. READY reports whether kagent compiled and prepared a runtime revisionRevisionThe compiled, immutable output of one Agent, identified by a content digest. A Session runs the revision it was created from for its whole life, so editing the Agent affects only sessions created afterward. for the pair.

   kagent agent get my-first-agent

   Example output:

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

   A READY value of UNKNOWN means that the kagent controller has not yet reconciled the Agent. Wait a few seconds, then check again. A READY value of False right after you apply the Agent is also expected, because kagent builds a snapshot of the agent’s runtime before it reports the Agent ready. This step can take a minute. If READY stays False, inspect the individual conditions to find which stage failed.

   kubectl get agent my-first-agent -n kagent -o jsonpath='{.status.conditions}' | jq

   An Agent reports four conditions, ending in Ready. The Accepted condition covers the shape of the spec, and ResolvedRefs covers the AgentTemplate, Harness, ModelConfig, and tool references. Compatible covers whether the resolved configuration suits the Harness runtime, and Ready covers the compiled revision itself. status.warnings lists non-blocking compatibility decisions that the compiler made.

Create a Session

A Session is one running conversation with an Agent. Creating it starts an Actor on the WorkerPool from the Agent’s latest successful revision.

1. Create a Session against the Agent, and save its ID to an environment variable.

   export SESSION_ID=$(kagent agent session create --agent my-first-agent -o json | jq -r '.session.id')
   echo $SESSION_ID

   The command returns only after the Session reaches the READY state. Run it without -o json to see the table instead:

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

   An error reporting that the Agent has no ready prepared revision means that the Agent is not Ready yet. Return to step 4 of the previous section to check the conditions.

Talk to your agent

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

   kagent agent invoke --session $SESSION_ID --task "What is 2+2?"

   The agent’s reply prints as text.

   4
   

2. Send a follow-up message to the same Session. A Session holds the transcriptTranscriptThe record of a Session'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 agent invoke --session $SESSION_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 Session that was created against the Agent. Later guides create their own sessions against the same Agent, so delete them all rather than only the one that you saved. Deleting the Agent does not delete the Sessions that were created against it, so delete the sessions first.

   kagent agent session list -o json \
     | jq -r '.sessions[] | select(.agent.name == "my-first-agent") | .id' \
     | xargs -n1 kagent agent session delete

2. Delete the Agent, the AgentTemplate, and the Harness.

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

Next steps