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

Review 1.0, which moves the runtime to Agent Substrate and replaces the Agent resource with a Harness and an AgentTemplate.

Each section covers one patch release in the kagent 1.0 line, newest first. For the commit-level changelog behind a release, see the kagent GitHub releases.

1.0.0

kagent 1.0 is a clean break from the 0.10.x line rather than an incremental release. It changes how an agent runs, how you declare one, and which custom resources exist. Because 1.0 shares no database schema with 0.10.x, moving an existing installation means standing up a new one rather than running helm upgrade.

For the component versions that this release pins and the Kubernetes version that it is tested against, see Version support.

How agents run

The runtime moved off Kubernetes Deployments, so the cost of an idle agent and the isolation boundary around a running one both changed.

• Each conversation runs as an ActorActorThe sandboxed unit of compute, provided by Agent Substrate, that runs an AgentInstance's conversation loop. Every AgentInstance is backed by one.Learn more on Agent SubstrateAgent SubstrateThe runtime that kagent runs agents on. It multiplexes many sandboxed Actors onto a smaller pool of pre-started Workers, suspending idle ones to snapshots.Learn more, rather than as a long-lived Deployment that serves every conversation for one agent.
• Conversations suspend between turns. When a turn ends, Agent Substrate writes the Actor’s memory and filesystem to a snapshotSnapshotThe 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 and releases the WorkerWorkerA 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 that hosted it. The next message restores that snapshot onto whichever Worker is free. For the lifecycle, see Suspend and resume.
• Every agent runs in a gVisor sandbox by default. 0.10.x relied on a Kubernetes securityContext to constrain an agent, and 1.0 provides process, network, and filesystem isolation without per-agent security context configuration. For what the sandbox separates, see Sandboxing.

How you declare an agent

The single 0.10.x Agent resource described both what an agent does and how it runs. 1.0 separates those concerns across two resources and adds a third object for a running conversation.

• A HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: its runtime, workload image, WorkerPool and snapshot storage, and which AgentTemplates it accepts.Learn more defines how an agent is allowed to run: its runtime, workload image, WorkerPoolWorkerPoolA Kubernetes custom resource declaring how many Workers to keep running and which sandbox class they use. An operator must provision one before any Harness can create AgentInstances.Learn more, snapshot storage, and which templates it accepts. One Harness serves many templates, so expect fewer Harnesses than you had Agents.
• An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once a Harness accepts it.Learn more defines what an agent does: its model, system prompt, tools, skills, and plugins.
• An AgentInstanceAgentInstanceA running, conversational pairing of a Harness and an AgentTemplate. Unlike the two, it is not a Kubernetes resource: kagent's gRPC API creates it and its database tracks it.Learn more is one running conversation between a Harness and an AgentTemplate. Unlike the other two, an AgentInstance is not a custom resource: kagent’s gRPC API creates it and kagent’s database tracks it.

Attachment between the two custom resources runs one way. A Harness names the templates that it admits through spec.allowedAgentTemplates.selector, and an AgentTemplate carries no field naming a Harness. For the full model, see Core concepts.

The CRD API group also moves from kagent.dev/v1alpha2 to kagent.dev/v1alpha3.

Removed and replaced resources

Four resource kinds are removed or replaced and three carry forward, and the distinction matters when you plan a move: a replaced kind has somewhere for its configuration to go, while a removed kind has none.

Several Agent fields have no v1alpha3 equivalent at all, including a2aConfig, stream, executeCodeBlocks, shareTools, and context. A2A is always on in 1.0, and a caller addresses an AgentInstance by ID rather than by a URL path. Tool bindings also changed shape: a 1.0 ToolBinding carries an mcp or agent block and no type discriminator. For the field-by-field mapping, see Agents become an AgentTemplate and a Harness.

Upgrade paths

Compatibility promises start at 1.0 rather than continuing from the 0.10.x line, so plan a migration rather than an upgrade.

• 0.10.x to 1.0 in place is not supported. An existing 0.10.x database has no migration bridge to 1.0 and 1.0 requires a new PostgreSQL database.
• Downgrade from 1.0 to 0.10.x is not supported.
• 1.0 to a later minor release is supported. From 1.0 onward, migrations are append-only and each minor release retains compatibility with the previous release line.

Moving an existing installation therefore means installing 1.0 alongside the old one, recreating your resources on it, and retiring 0.10.x once the new installation answers correctly. Conversation history does not carry across, because nothing in 1.0 can read a 0.10.x database. For the full procedure, see Upgrade from 0.x.