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

Build an agent from a system prompt, tools, skills, and plugins, and let the kagent harness run the agentic loop.

A declarative agent is an agent that you describe rather than build. In an AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once an Agent pairs it with a Harness.Learn more resource, you write a system prompt, name a model, and bind the tools, skills, and plugins that the agent can use. The kagent HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: which harness executes the agent, its workload image, and its WorkerPool and snapshot storage. An Agent pairs it with the AgentTemplate that it runs.Learn more then runs kagent’s built-in Go engine, which reads the AgentTemplate configuration and runs the agentic loop from it. To change what the agent does, you edit the AgentTemplate.

Declarative agents and BYO agents

kagent runs an agent in one of two ways depending on who owns the agentic loop. A declarative agent hands the loop to kagent. A BYO agent keeps the loop inside a container image that you build and maintain, and kagent runs the image instead.

Both routes receive the same resolved agent configuration, run in the same sandbox, follow the same snapshot policy, and route through the same gateway. For how a BYO image reads that configuration, and what its agent card leaves out, see Compare BYO and declarative agents.

The codex and claude harnesses provide a third route, in which a coding agent owns the loop and takes its configuration from the AgentTemplate. To compare all options side by side, see Choose a harness.

Configure the kagent harness

Define settings that belong to the engine rather than to the agent in the spec.kagent section of the Harness resource. The section takes memory settings, which persist facts across conversations, and compaction settings, which keep a single conversation’s prompt within a limit as the conversation grows.

spec:
  kagent:
    memory:
      modelConfigRef:
        name: embedding-model-config
      ttlDays: 30
    compaction:
      tokenThreshold: 120000
      eventRetentionSize: 20

Compaction offers two strategies. Tail retention summarizes the older history once the prompt passes a token count, while a sliding window summarizes each group of completed invocations as the conversation goes. Setting compaction requires at least one of these two strategies, and setting both is valid. For the rules that the API server enforces, see Context management.

For the fields that every Harness shares, such as the workload image and the Agent Substrate placement, see Configure a Harness.

Apply a complete declarative agent

The following example applies a declarative agent end to end, from the ModelConfig to the Agent that runs it. The ModelConfig reads its API key from the kagent-openai Secret that the OpenAI guide creates. spec.kagent is an empty object because memory and compaction are both optional.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: ModelConfig
metadata:
  name: kagent-model-config
  namespace: kagent
spec:
  apiKeySecret: kagent-openai
  apiKeySecretKey: OPENAI_API_KEY
  model: gpt-4o-mini
  provider: OpenAI
  openAI: {}
---
apiVersion: api.kagent.dev/v1alpha3
kind: Harness
metadata:
  name: kagent-harness
  namespace: kagent
spec:
  kagent: {}
  workload:
    image: ghcr.io/kagent-dev/kagent/golang-adk@sha256:ae01c3a6d7e0ed2e044253a26abbfb1a9426f3176363842ca9a954762c274d36
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: s3://ate-snapshots/kagent/
---
apiVersion: api.kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
  name: kagent-template
  namespace: kagent
spec:
  modelConfig:
    name: kagent-model-config
  systemPrompt: You are a concise, helpful assistant.
---
apiVersion: api.kagent.dev/v1alpha3
kind: Agent
metadata:
  name: my-agent
  namespace: kagent
spec:
  template:
    ref:
      name: kagent-template
  harnessRef:
    name: kagent-harness
EOF

To confirm that the Agent is ready, run the following command. In the output, READY reports whether kagent built and prepared a 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-agent

A READY value of False immediately after you apply the Agent is expected, because kagent builds a snapshot of the agent before it reports the Agent ready. If READY stays False, read the conditions on the Agent to find the stage that failed, asdescribed in Your first agent. To start a conversation with the agent, see Create a Session.

Next steps