1.0

Review 1.0, which moves the runtime to Agent Substrate and replaces the 0.x Agent resource with a Harness, an AgentTemplate, and a new Agent that pairs them.

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 pairs the efficiency and isolation of Agent Substrate, an open source runtime built for AI agents, with the Kubernetes-native agent platform that kagent users know.

An agent spends most of its life waiting, either for a person to reply or for a model to answer. 0.10.x kept a Deployment running for that whole wait. With Agent Substrate, each conversation runs in its own sandbox, suspends to a snapshot the moment it goes idle, and resumes on the next message. That makes 1.0 a big step forward in three ways:

Your capacity goes much further: A suspended Session holds no compute, so the same pool of Workers can serve far more Sessions than it could if every agent stayed resident. The Session stays ready the whole time, so users never notice.
Isolation is built in: Every conversation gets its own sandbox, with process, network, and filesystem isolation by default and no per-agent securityContext to write or maintain.
Agents are ready when you need them: Agent Substrate starts Workers in advance, so a Session rarely waits for a new pod to start.

To take full advantage of this foundation, 1.0 changes how an agent runs, how you declare one, and which custom resources exist. For how the pieces fit together, see the kagent architecture and Agent Substrate architecture pages.

Important

No upgrade path exists from 0.10.x to 1.0. Moving an existing installation is a migration to a new installation with a new database, and Session history does not carry over. For the options and their trade-offs, see Upgrade paths.

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

How agents run

1.0 moves the runtime off Kubernetes Deployments. The move changes the cost of an idle agent and the isolation boundary around a running agent.

Each 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 runs as an ActorActorThe sandboxed unit of compute, provided by Agent Substrate, that runs a Session's conversation loop. Every Session 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 Session for one agent.
Sessions 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. 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 splits that description across the following resources, and represents each running conversation as a Session.

A 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 defines how an agent is allowed to run, including 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 Agent can compile.Learn more, and snapshot storage. One Harness serves many agents, so expect fewer Harnesses than you had 0.10.x Agents.
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 defines what an agent does, including its model, system prompt, tools, skills, and plugins.
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 one AgentTemplate with one Harness. spec.template takes either a reference to an existing AgentTemplate or a complete inline spec. spec.harnessRef takes only a reference. The Agent reports readiness. Callers address the Agent, not the AgentTemplate or the Harness.
A Session is one running conversation with an Agent. Unlike a Harness, an AgentTemplate, or an Agent, a Session is not a custom resource. kagent’s gRPC API creates each Session, and kagent’s database stores it.

A Harness and an AgentTemplate do not reference each other, so only an Agent connects them. For the full model, see Core concepts.

The custom resource definition (CRD) API group also moves from kagent.dev/v1alpha2 to api.kagent.dev/v1alpha3. kagent does not convert resources between the two groups. 1.0 no longer bundles kmcp, so it does not install the mcpservers.kagent.dev CRD. 1.0 also no longer bundles the Grafana Model Context Protocol (MCP) server, so it does not create the kagent-grafana-mcp RemoteMCPServer. 0.10.x and 1.0 cannot run side by side on one cluster, because both charts name their ClusterRoles after the release. To keep 0.10.x serving while you move, install 1.0 on a second cluster.

New capabilities

The following features are new in 1.0 and do not have a 0.10.x counterpart.

Multi-harness support: Besides the built-in kagent harness, a Harness can run Codex, Claude, or a container image of your own that implements kagent’s Agent2Agent (A2A) contract. For what each harness supports, see Choose a harness.
Actors on Micro-VMs: gVisor remains the default sandbox class. The microvm class places a hypervisor boundary between the workload and the host. For how a pool selects its class, see Sandbox classes.
Access to destinations with EgressPolicy resources: To inject a credential into requests that an Agent or a SandboxTemplate sends to a destination, apply an EgressPolicy to that Agent or SandboxTemplate. For the procedure, see Grant access to a destination.
Standalone sandboxes with SandboxTemplates: A SandboxTemplate defines a scratch environment that is independent of any Session. A person, or an agent through the kagent MCP server, creates a Sandbox from the template to run commands and transfer files. For the procedure, see Create a SandboxTemplate.
Actor identity for model authentication: A ModelConfig can authenticate to a model endpoint as the calling Actor instead of with a stored credential. When you set actorJwt, the egress gateway sends a token that identifies the Actor to a model endpoint that you run, so the ModelConfig does not need a Secret. For the fields, see Authenticate as the Actor.
Context compaction: The kagent harness summarizes older Session events according to the spec.kagent.compaction block on the Harness. For the settings, see Configure compaction.
Structured output: You can constrain an agent’s final answer to a JSON Schema, so that callers receive a response in a predictable shape. The AgentTemplate sets the schema in its outputSchema field or reads it from a ConfigMap. For an example, see Set the schema inline.
Session sharing with share tokens: A share token gives another account read-only access to one Session. For the access model, see Share a Session.
Scheduled runs: You can run an Agent on a cron expression. Each execution sends a fixed prompt to a new Session, so scheduled runs do not continue an earlier Session. For the procedure, see Create a schedule in the UI.

Removed and replaced resources

Each 0.10.x resource kind is replaced, removed, carried forward, or carried forward with changes in 1.0. A replaced kind has a destination for its configuration. A removed kind does not.

0.10.x resource	Status in 1.0
Agent	Replaced by an AgentTemplate, a Harness, and a new Agent in the `api.kagent.dev` group that pairs them. The two Agent kinds share a name and nothing else.
ToolServer	Replaced by RemoteMCPServerRemoteMCPServerA Kubernetes custom resource pointing at a Model Context Protocol server that the cluster can reach. It is the only server kind that an AgentTemplate tool binding accepts.Learn more, which 0.10.x already served alongside it.
Memory	Replaced by `Harness.spec.kagent.memory`, so memory is a property of the runtime rather than of one agent.
SandboxAgent	Removed, with no equivalent. Every 1.0 agent runs in a sandbox by default.
MCPServer	Removed, because 1.0 no longer bundles kmcp or its controller. Run the MCP server outside of kagent, and set its URL on a RemoteMCPServer. The `kagent mcp` commands are removed with it.
AgentHarness	Removed, with no equivalent. AgentHarness provisioned OpenClaw and Hermes coding-agent sandboxes with Slack and Telegram channels. The 1.0 Harness is a new resource, not a renamed AgentHarness.
ModelConfig, RemoteMCPServer	Carried forward. An exported resource needs a new `apiVersion`. The ModelConfig field `apiKeyPassthrough` is now `tokenPassthrough`, the same name that RemoteMCPServer uses for the same behavior. `v1alpha3` removes the ModelConfig fields `spec.openAI.tokenExchange`, `spec.tls.caCertSecretRef`, `spec.tls.caCertSecretKey`, and `spec.tls.disableSystemCAs`.
ModelProviderConfig	Carried forward with changes. Model discovery accepts only the `OpenAI` type, so a ModelProviderConfig of another type does not have a 1.0 equivalent. The `spec.secretRef` field moves to `spec.discoveryAuth.secretRef`, which references both the Secret and the key within it.

Several Agent fields do not have a v1alpha3 equivalent, including a2aConfig, executeCodeBlocks, shareTools, and context. A2A is always on in 1.0. A caller addresses an Agent at /agents/{namespace}/{name} over HTTP, or through the A2A tenant field over gRPC. Tool bindings also have a new shape. A 1.0 ToolBinding contains an mcp or subAgent block and does not have a type discriminator. For the field-by-field mapping, see Agents become an AgentTemplate, a Harness, and an Agent.

Upgrade paths

Compatibility promises start at 1.0. Plan a migration from 0.10.x, not an upgrade.

0.10.x to 1.0 in place is not supported. kagent does not migrate a 0.10.x database to 1.0. 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 a migration. Install 1.0 on a second cluster, recreate your resources on it, and retire 0.10.x after the new installation answers correctly. 0.10.x and 1.0 cannot run side by side on one cluster, because both charts name their ClusterRoles after the release. Installing on the same cluster requires uninstalling 0.10.x first, so your agents are unavailable until 1.0 is running. Because 1.0 cannot read a 0.10.x database, 0.10.x conversation history does not move to the new installation. For the full procedure, see Upgrade from 0.x.