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

Learn the Harness, AgentTemplate, Agent, Session, and Actor model that kagent 1.0 is built on.

kagent 1.0

kagent 1.0 replaces 0.x’s Deployment-based Agent custom resource with a new model built around Harness, AgentTemplate, Agent, and Session, running on Agent Substrate instead of the plain Kubernetes Deployments that the 0.x model uses. The 1.0 Agent kind shares the 0.x name but not its meaning: it pairs an AgentTemplate with a Harness rather than describing a Deployment. This page defines the vocabulary that the rest of the 1.0 model docs use. If you already have a 0.x installation, see Upgrade from 0.x, which maps each 0.x resource onto its 1.0 replacement.

The new model separates what an agent can do from how it is allowed to run, and then names the pairing explicitly:

• A Harness defines how an agent is allowed to run. It picks a runtime and the infrastructure policy around it.
• An AgentTemplate defines what an agent can do: its model, prompt, and tools.
• An Agent pairs one AgentTemplate with one Harness. The Agent is what callers address and what the controller compiles.
• A Session is a running conversation with an Agent.
• An Actor is the sandboxed process, provided by Substrate, that a Session runs on.

The following diagram shows how an Agent becomes a running conversation. The kagent controller compiles each Agent into an ActorTemplateActorTemplateThe compiled, immutable definition that the kagent controller produces from an Agent. Every Actor is created from one.Learn more, and each Session is created from that ActorTemplate and runs on an Actor.

    flowchart LR
    template["AgentTemplate<br>(CRD)"]
    harness["Harness<br>(CRD)"]
    agent["Agent<br>(CRD)"]
    controller["kagent controller"]
    actortemplate["ActorTemplate<br>(compiled, immutable)"]
    session["Session<br>(gRPC + database)"]
    actor["Actor<br>(Substrate)"]

    template --> agent
    harness --> agent
    agent --> controller
    controller -->|compiles into| actortemplate
    actortemplate -->|instantiated as| session
    session -->|runs on| actor

    classDef crd stroke:#a78bfa,stroke-width:2px
    class template,harness,agent crd
  

The three custom resources are what an operator applies directly. The kagent controller watches each Agent, resolves the template and harness that it names, and compiles the result into an ActorTemplate. From there, each Session created against that Agent gets its own Actor to run on.

Harness

A Harness is a Kubernetes custom resource that defines how an agent is allowed to run. It specifies:

• Runtime: The engine that executes the agent. A Harness selects exactly one of kagent, codex, claude, or byo, and kagent compiles all four. kagent runs kagent’s own Go and Python engines, codex and claude run those coding agents, and byo runs any image that implements kagent’s A2A contract.
• Workload: The container image, command, and arguments that the runtime runs as.
• Environment: Literal environment values for the runtime, set in spec.env.
• Substrate policy: The WorkerPool that the Harness’s Actors are scheduled onto, and where their snapshotsSnapshotThe stored state that an Actor suspends to, held in object storage. Resuming restores the Actor from its most recent snapshot, which is what makes suspending idle agents cheap.Learn more are stored.

A Harness names no AgentTemplate, and an AgentTemplate names no Harness. An Agent pairs the two, and nothing pairs them implicitly.

A byo Harness has one extra requirement: it must set spec.workload.command, because kagent has no default entrypoint for an image that it does not build.

A Harness owns no running compute by itself. Applying one registers a runtime and policy that an Agent can select.

For the complete Harness schema, see the API reference.

AgentTemplate

An AgentTemplate is a Kubernetes custom resource that defines what an agent does. It specifies:

• Model configuration: The large language model (LLM) provider and model the agent uses.
• System prompt: A literal prompt, or a Go-templated one that can include shared ConfigMaps.
• Tools: A list of tool bindingsTool bindingOne entry in an AgentTemplate's spec.tools list. Each binding selects exactly one source: tools from a Model Context Protocol server, or another AgentTemplate used as a tool.Learn more that the agent can call. Each binding is either a Model Context ProtocolModel Context ProtocolAn open protocol for exposing tools and resources to a model. kagent reaches an MCP server through a RemoteMCPServer resource, and an AgentTemplate binds individual tools from it.Learn more (MCP) server, or another AgentTemplate used as a subagent tool (see Subagent tools).
• Skills and plugins: Reusable capability packages, sourced from an Open Container Initiative (OCI) registry, Git, or S3.

An AgentTemplate does nothing on its own. It becomes runnable once an Agent pairs it with a Harness. One AgentTemplate can serve many Agents, so expect fewer templates than Agents where several runtimes run the same behavior.

For the complete AgentTemplate schema, see the API reference.

Agent

An Agent is a Kubernetes custom resource that pairs one AgentTemplate with one Harness. The pairing is explicit: each side takes either a reference to an existing resource or a complete inline spec, and exactly one of the two per side.

The template side and the harness side are set independently, so an Agent can reference both, inline both, or mix the two. An inline spec is a complete value rather than an override of a referenced one, and kagent creates no Kubernetes object to back it. Every reference, including one that is nested inside an inline spec, resolves in the Agent’s own namespace.

The following Agent resource references both sides:

apiVersion: api.kagent.dev/v1alpha3
kind: Agent
metadata:
  name: assistant
  namespace: kagent
spec:
  templateRef:
    name: shared-context
  harnessRef:
    name: kagent

The Agent owns readiness. Its status carries the desired revision, the latest revision that compiled and prepared successfully, any non-blocking compatibility warnings, and the Accepted, ResolvedRefs, Compatible, and Ready conditions. An AgentTemplate and a Harness are shared configuration and carry no runtime status of their own.

Deleting an Agent retires its definition. Existing Sessions keep the revisions that they pinned. Recreating an Agent under the same name creates a new identity, which cannot inherit the deleted Agent’s last successful revision.

For the complete Agent schema, see the API reference.

Session

A Session is a running conversation with one Agent. Unlike the Harness, AgentTemplate, and Agent that it is built from, a Session is not a Kubernetes custom resource and does not live in etcd. kagent’s own gRPC API creates it, and kagent’s PostgreSQL database tracks it.

This split is deliberate, not an implementation detail to work around:

• Applying a Harness, AgentTemplate, or Agent is a Kubernetes-native operation, governed by Kubernetes RBAC, exactly like any other CRD.
• Creating, suspending, resuming, sharing, or deleting a Session, and holding a conversation with it, are kagent-native operations, governed by kagent’s own gRPC authentication and authorization, independent of who can kubectl apply an Agent.

Each compile produces one 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., identified by a digest, which is a SHA-256 hash of the compiled configuration. Because that digest is derived from the configuration itself, editing an Agent or either resource it references compiles to a different digest, and therefore becomes a separate ActorTemplate. kagent never rewrites an existing one.

That immutability keeps running conversations stable. When you create a Session, kagent looks up the Agent’s latest successful revision and creates an Actor from it. Editing the Agent afterward does not disturb that Session, which keeps running on the revision that it was created from. Only Sessions created after the edit use the new revision.

You can create a Session with the following command:

kagent agent session create --agent assistant -n kagent

After it is created, a Session talks to callers 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, through kagent’s A2A gateway. Callers address the Agent rather than the Session. The HTTP endpoint is /agents/{namespace}/{name} and gRPC carries the same namespace/name in the standard A2A tenant field. The Session’s ID is the A2A contextId, so a message that carries no context identifier starts a new conversation, and a message that repeats one continues that conversation.

A Session that records no task activity for seven days is deleted by an expiration worker. The controller.sessionIdleTTL Helm value sets that window. A value of 0 turns the expiration worker off. For more information about what the deletion retains, see Expire idle conversations.

Actor

An Actor is the sandboxed unit of compute, provided by Agent Substrate, that runs a Session’s conversation loop. Every Session is backed by an Actor.

Actors are the reason why Sessions can suspend and resume cheaply instead of staying resident. An idle Actor can be snapshotted and torn down, then resumed from that snapshot on demand. To understand the full mechanics (WorkersWorkerA pre-started, sandboxed pod that hosts at most one Actor at a time. Actors are multiplexed across a pool of Workers over time.Learn more, WorkerPoolsWorkerPoolA Kubernetes custom resource declaring how many Workers to keep running and which sandbox class they use. An operator must provision one before any Agent can compile.Learn more, ActorTemplates, and snapshotting), see Agent Substrate architecture.

Subagent tools

An AgentTemplate’s tools are not limited to MCP servers. A tool binding can also point at another AgentTemplate, which lets one agent hand work to a specialist agent.

Each subagent binding sets tools[].subAgent.templateRef to name an AgentTemplate in the same namespace. The named template compiles under the parent Agent’s Harness and runs inside the parent’s Actor, so the two agents share one sandbox and the nesting creates no second Actor. A subagent needs no Agent of its own and no matching Harness reference.

Because a subagent runs inside its parent’s runtime boundary, the compiler constrains the shape of the resulting tree. Nesting stops at one level. A bound template cannot bind a third. That cap keeps the model predictable, because every agent runs either in its own Actor or in the Actor of the agent that bound it, never deeper. For the remaining rules that a tree must satisfy, see What a subagent tree allows.