diff --git a/docs-site/content/kagent/1.x/about/architecture/agent-substrate.md b/docs-site/content/kagent/1.x/about/architecture/agent-substrate.md index e820d447..20c7ec62 100644 --- a/docs-site/content/kagent/1.x/about/architecture/agent-substrate.md +++ b/docs-site/content/kagent/1.x/about/architecture/agent-substrate.md @@ -35,7 +35,7 @@ kagent names each atespace after the Kubernetes namespace of the Agent whose Act Because an Actor often runs a model-directed agent that calls tools and executes commands, Substrate runs each Actor in an isolated sandbox rather than a plain container. A WorkerPool's `sandboxClass` field selects the sandbox technology for its Workers: [gVisor](https://gvisor.dev), or a micro-VM that runs the workload under [Cloud Hypervisor](https://www.cloudhypervisor.org) with a [Kata Containers](https://katacontainers.io) kernel and root image. Both technologies isolate an Actor from its Worker's host kernel, and both support suspend and resume operations. -kagent compiles every ActorTemplate to the `gvisor` class, so a kagent agent runs in a {{< gloss "gVisor" >}}gVisor{{< /gloss >}} sandbox today and the micro-VM class is a Substrate capability that kagent does not yet select. Keep a WorkerPool that backs kagent Harnesses on `gvisor`. For what each class isolates, see [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). +kagent compiles each ActorTemplate to the sandbox class of the WorkerPool that hosts it, so a default installation runs kagent agents in a {{< gloss "gVisor" >}}gVisor{{< /gloss >}} sandbox, and a pool on the `microvm` class runs them under the micro-VM. A WorkerPool that backs kagent Harnesses must run the Worker build that matches its class. For what each class isolates, see [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). ## Suspend, snapshot, and resume diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/sandboxing.md b/docs-site/content/kagent/1.x/about/substrate-runtime/sandboxing.md index 9cc1a10b..16951b0c 100644 --- a/docs-site/content/kagent/1.x/about/substrate-runtime/sandboxing.md +++ b/docs-site/content/kagent/1.x/about/substrate-runtime/sandboxing.md @@ -35,7 +35,7 @@ A **sandbox class** is the sandbox runtime family that a Worker uses. {{< gloss A {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}} selects its class through the `sandboxClass` field, which defaults to `gvisor`. The choice is not only a runtime preference. It also shapes the Worker pods that Agent Substrate creates for that pool, including the virtualization device mounts and node placement that a micro-VM needs. > [!NOTE] -> kagent generates {{< gloss "ActorTemplate" >}}ActorTemplates{{< /gloss >}} that use the `gvisor` class. Keep a WorkerPool that backs kagent Harnesses on `gvisor`. +> kagent generates {{< gloss "ActorTemplate" >}}ActorTemplates{{< /gloss >}} that use the sandbox class of the pool that hosts them, and names the matching SandboxConfig on each template: `gvisor-default` for the `gvisor` class, `microvm` for the `microvm` class. A WorkerPool that backs kagent Harnesses must run the class it is meant to serve, with a matching Worker build. ## Sandbox configuration diff --git a/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md b/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md index 021e5d7e..ed2c9a40 100644 --- a/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md +++ b/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md @@ -7,7 +7,7 @@ author: kagent.dev {{< reuse "kagent-docs/snippets/name-product.md" >}} runs every agent on [Agent Substrate]({{< link path="about/architecture/agent-substrate" >}}), and a fresh installation is deliberately small: one {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}} holding a single Worker, snapshots in whichever object storage the Agent Substrate installation was given, and the `gvisor` sandbox class. -When preparing for real traffic to your agents, you can size the pool and check where snapshots land. Leave the sandbox class on `gvisor`. A pool set to any other class sits idle while turns time out. +When preparing for real traffic to your agents, you can size the pool and check where snapshots land. The sandbox class a pool backs can be `gvisor` or `microvm`, as long as the pool's Worker build and SandboxConfig match the class, as described in [Keep pools on the sandbox class they serve](#keep-pools-on-the-sandbox-class-they-serve). ## Before you begin @@ -175,13 +175,13 @@ Because the two places are configured independently, confirm the result rather t > [!WARNING] > A development installation points at an in-cluster object store with well-known credentials, and it is not durable. Snapshots hold agent conversation state, so a production installation needs a real bucket, credentials that are not shared defaults, and a backup policy that matches how much conversation history you are willing to lose. -## Keep pools on the gvisor class +## Keep pools on the sandbox class they serve A pool's sandbox class decides which sandbox runtime its Workers provide, and kagent constrains the choice more tightly than Agent Substrate does. -Agent Substrate supports the `gvisor` and `microvm` classes, as explained in [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). kagent compiles every ActorTemplate to the `gvisor` class and to a SandboxConfig named exactly `gvisor-default`. Placement never relaxes the class constraint, so Workers in a `microvm` pool accept no kagent Actor, and the pool sits idle while turns time out. +Agent Substrate supports the `gvisor` and `microvm` classes, as explained in [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). kagent compiles every ActorTemplate to the class that its pool selected and to the matching SandboxConfig: a pool on `gvisor` (or no `sandboxClass`, which defaults to `gvisor`) gets the `gvisor` class and a SandboxConfig named `gvisor-default`, while a pool on `microvm` gets the `microvm` class and a SandboxConfig named `microvm`. Placement never relaxes the class constraint: a Worker in a pool whose class does not match an ActorTemplate's class reports `RevisionInvalid` with `unsupported sandbox class ""`, and placement of that Actor fails with `WorkerPoolNotFound`. -Leave a pool that backs kagent Harnesses on `gvisor`, and keep the pool's image on the matching Worker build. +Leave a pool that backs kagent Harnesses on the class you intend to run, and keep the pool's image on the matching Worker build: `ateom-gvisor` for a pool on `gvisor`, `ateom-microvm` for a pool on `microvm`. ```yaml substrateWorkerPool: @@ -189,10 +189,16 @@ substrateWorkerPool: workerImage: "ghcr.io/kagent-dev/substrate/ateom-gvisor:v{{< reuse "kagent-docs/versions/agent-substrate.md" >}}" ``` +```yaml +substrateWorkerPool: + sandboxClass: microvm + workerImage: "ghcr.io/kagent-dev/substrate/ateom-microvm:v{{< reuse "kagent-docs/versions/agent-substrate.md" >}}" +``` + > [!NOTE] > The `ateomImage` field in the [Inspect the runtime](#inspect-the-runtime) response reports this same setting, which the WorkerPool resource calls `workerImage`. To check which build a pool is running, compare the two names. -A cluster-scoped SandboxConfig named `gvisor-default` must also exist, because kagent names it directly rather than resolving a default. A missing one fails template preparation with `SandboxConfig "gvisor-default" not found`. +A cluster-scoped SandboxConfig for the pool's class must also exist, because kagent names it directly rather than resolving a default: `gvisor-default` for the `gvisor` class and `microvm` for the `microvm` class. A missing one fails template preparation with `SandboxConfig "" not found`. On a default installation only the `gvisor` class is wired up: Substrate applies `sandboxconfig-gvisor.yaml`, and kagent installs nothing for `microvm`. A `microvm` pool therefore needs operator-staged assets: the `microvm` SandboxConfig is a template that the Substrate installer stages out of band (for example via `hack/install-microvm-deps.sh --install`), not something kagent provides. ```bash kubectl get sandboxconfigs @@ -201,6 +207,7 @@ Example output: ```console NAME CLASS AGE gvisor-default gvisor 26h +microvm microvm 26h ``` Two further constraints apply when you change any of this on a running cluster. diff --git a/docs-site/data/glossary.yaml b/docs-site/data/glossary.yaml index bb629f1d..cc47f749 100644 --- a/docs-site/data/glossary.yaml +++ b/docs-site/data/glossary.yaml @@ -135,5 +135,5 @@ A2A: link: "/docs/kagent/1.x/examples/a2a-agents/#about-the-kagent-a2a-service" gVisor: - short: "A user-space kernel that isolates a workload from the host kernel by intercepting its system calls. kagent compiles every ActorTemplate to the gvisor sandbox class." + short: "A user-space kernel that isolates a workload from the host kernel by intercepting its system calls. A default kagent installation compiles ActorTemplates to the gvisor sandbox class." link: "/docs/kagent/1.x/about/substrate-runtime/sandboxing/#sandbox-classes"