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

Configure a Harness, the resource that defines which runtime executes an agent and what infrastructure it runs on.

Review configuration guidelines and reference for the Harness resource: every field it takes, the four runtimes it can select, and what each runtime supports. To understand a Harness and why an Agent, rather than the Harness itself, names the AgentTemplate that runs on it, see the core concepts.

Configure a Harness

The following configuration is for a complete Harness resource. Only workload, substrate, and one runtime block are required.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: Harness
metadata:
  name: my-harness
  namespace: kagent
spec:
  # Exactly one runtime block: kagent, codex, claude, or byo.
  kagent: {}
  workload:
    image: ghcr.io/kagent-dev/kagent/golang-adk@sha256:215417b5401310bb496ae1687bb8622f93fd19991a218c6a218987836e71da84
  env:
    - name: KAGENT_LOG_LEVEL
      value: info
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: s3://ate-snapshots/kagent/
EOF

Review the following table to understand this configuration. For more information, see the API reference.

A Harness names no AgentTemplate. An AgentAgentA Kubernetes custom resource that pairs one AgentTemplate with one Harness. Each side takes either an inline spec or a reference to an existing resource, and the controller compiles the pair into a revision.Learn more pairs the two through either spec.harnessRef or an inline spec.harness, so whoever writes the Agent decides which template runs on which Harness. For more information about the pairing, see Core concepts.

A command or argument override belongs to the revision that kagent prepares. Changing one prepares a new revision rather than altering a running agent. A SessionSessionA running conversation with one Agent. Unlike the resources it is built from, a Session is not a Kubernetes resource: kagent's gRPC API creates it and its PostgreSQL database tracks it.Learn more pinned to an earlier revision keeps the command it was prepared with until it moves to the new one.

Choose a runtime

A Harness names exactly one of the following four runtimes, and that choice decides what executes an agent and how much of kagent’s feature set the agent can use.

The kagent and byo runtimes compile through the same path, so they accept the same model providers and the same AgentTemplate features, except structured output, which only the kagent runtime supports. The codex and claude runtimes are purpose-built adapters, and each accepts a narrower slice.

Runtime-specific settings

spec.kagent is the only runtime block that takes settings of its own. The rest are empty.

spec:
  kagent:
    memory:
      modelConfigRef:
        name: embedding-model-config
      ttlDays: 30

Setting memory gives every agent on this Harness memory that persists across conversations. For how agents store and retrieve it, see Agent memory.

Setting compaction summarizes older session events so an agent’s prompt stays bounded as a conversation grows. For the two strategies and the rules the API server enforces, see Context management.

Model provider support

The runtime that a Harness selects decides which ModelConfig an Agent that runs on it can use. This table covers every value that the ModelConfig provider field accepts, including the four that kagent 1.0 rejects on every runtime.

kagent rejects AnthropicVertexAI, GeminiVertexAI, and SAPAICore on every runtime, because each authenticates with a credential that the egress gateway cannot place in an HTTP header. The ModelConfig never compiles, so no agent can use these providers. For the alternatives, see About model providers.

kagent rejects Mistral for a different reason. The controller does not resolve the provider at all, so a Mistral ModelConfig reports unsupported model provider: Mistral and compiles no revision.

Some supported combinations still carry restrictions.

Tool and skill support

The coding-agent runtimes also constrain what an AgentTemplate can ask for.

The kagent and byo runtimes take the full set. For more information about what an AgentTemplate can bind, see About tools.

Telemetry content settings

Tracing carries the prompts and replies that an agent exchanges with a model, and so does log export on the claude runtime. Two settings in the kagent Helm chart decide whether that content leaves the runtime, and each one reaches a different set of runtimes. Both default to false, and both take effect only where tracing or log export is already enabled.

otel:
  captureSensitiveContent: false
  logging:
    captureRawApiBodies: false

The controller sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT in every compiled runtime from otel.captureSensitiveContent, so setting that variable in the Harness spec.env field has no effect.

The controller sends the byo runtime no telemetry configuration, so neither setting reaches it. A byo image that implements OpenTelemetry itself reads whatever the Harness spec.env field holds. For more information, see Tracing.

Check that a Harness is ready

The READY column reports whether a Harness’s dependencies resolved.

kubectl get harness -n kagent

A Harness that is not Ready most often names a WorkerPool that does not exist yet. For the specific reason, read its conditions with kubectl describe harness <harness-name> -n kagent.

Ready covers the Harness’s own dependencies, not whether a given agent runs on it. Whether a template compiles against this Harness is reported on the Agent that pairs the two, because an AgentTemplate carries no status of its own. For that check and the conditions it reports, see Your first agent.

Next steps