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

Find answers to common questions about kagent, its core resources, and what changed in the 1.0 release.

How do I get started with kagent?

Install kagent first, with a 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 provisioned, by following Install kagent. Then work through Your first agent, which applies a Harness and an AgentTemplate and holds a conversation with the AgentInstance that they produce. Those two resources and that conversation are the model that the rest of these docs assume. Your first MCP tool then gives that agent a tool.

What makes kagent different from other agent frameworks?

kagent is declarative and Kubernetes-native. You author an agent’s runtime and behavior as custom resources and let the controller reconcile them, rather than writing code that drives a model through each step. Those resources are then governed by the same role-based access control (RBAC), GitOps, and observability as your other workloads. What is kagent? covers the platform in full.

What is the difference between a Harness and an AgentTemplate?

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. 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. Separating the two lets a platform team own the runtime while an application team owns the behavior. Neither resource runs anything on its own, because an agent exists only once a Harness accepts a template. For the full definition of each resource and the fields that it carries, see Core concepts.

Is a Harness the same as 0.x’s AgentHarness?

No. The two share part of a name and nothing else. 0.x’s AgentHarness provisions OpenClaw or Hermes coding-agent sandboxes, while 1.0’s Harness governs how any agent is allowed to run. Read Harness as a new resource rather than a renamed one.

What is an AgentInstance?

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 those two, it is not a Kubernetes custom resource: kagent’s gRPC API creates it, kagent’s database tracks it, and 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 runs it. One template can back many concurrent instances, each with its own transcriptTranscriptThe record of an AgentInstance's conversation, held server-side and append-only. It survives the Actor suspending between turns, and a resumed runtime cannot shrink it..

How does suspend and resume work?

Agent conversations are mostly idle, so Agent Substrate does not hold a pod open between turns. When a turn ends, it 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 was hosting it. The next message restores that snapshot onto whichever Worker is free, and the conversation continues where it stopped. Suspend and resume covers the lifecycle, what a snapshot captures, and how checkpointsCheckpointA durable pin on the snapshot that an AgentInstance most recently suspended to, and a record of how far its transcript had advanced. Not a new state: tagging copies the snapshot so that Agent Substrate does not collect it, and a second AgentInstance can be forked from it.Learn more pin one.

How is 1.0 different from 0.x?

1.0 changes how agents run and how you declare them. Agents no longer run as long-lived Deployments; each conversation runs as a sandboxed Actor on Agent Substrate that suspends between turns. The single 0.x Agent resource is replaced by the Harness and AgentTemplate pair, ToolServer is 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, and the API group moves from v1alpha2 to v1alpha3.

1.0 has no in-place upgrade path. An existing 0.10.x installation has no migration bridge to 1.0, so moving to 1.0 means standing up a new installation and recreating your resources on it. For the procedure, see Upgrade from 0.x. Version support records which upgrade paths are supported, and the release notes list the breaking changes.

How do I report a bug or request a feature?

Open an issue on the kagent GitHub repository. For a bug, include your kagent version, the resources that reproduce it, and the controller logs. Debug covers how to collect those.

How do I contribute to kagent?

Start with the contribution guide, then open a pull request. Community and contributing collects the repository, the roadmap, and the project’s Discord.