The agent runtime

An agent combines a tenant-scoped Agent, an AgentTemplate describing its behavior, and a Harness selecting its runtime. Sessions execute through Substrate workers. An agent definition is not a dedicated, always-running Deployment.

The pinned contract

The platform targets kagent 1.0.0-alpha5, with Go source pinned to d4ed7dea2079c43d734c7d77840ed328c7c4c728. Its resources use api.kagent.dev/v1alpha3; Substrate resources use ate.dev/v1alpha1. The cluster runs the kagent chart’s own controller at that version, one replica; the platform does not fork it.

The tenant baseline creates the spooky-kagent Harness and tenant WorkerPool. CreateAgent validates the requested configuration and establishes the required model, credentials and tool bindings before writing the agent resources. Kubernetes acceptance does not mean a session has started, and the multiple resource writes are not a database transaction. A durable creation reservation assigns the immutable agent UID before brokerage and credential publication. A matching retry reuses that UID; a background reconciler repairs accepted agents whose configuration publication or activation was interrupted. New work remains blocked while creation is incomplete.

See the pinned API source and current upstream concepts.

Skills and native tools

The skills catalog comes from the Spooky-Labs/skills Git plugin package. The custom runtime image bakes its selected package revision into /plugins/plugin-0; the image digest and skills_package_commit travel together in the deployment pin file. The legacy RPC name ListContainerSkills now lists this package. It does not enumerate OCI images.

An explicit skill selection must resolve in the catalog. An empty selection uses the defaults; disable_workspace_tools selects no skills. A skill provides instructions and resources for existing tools. Its presence alone does not create an arbitrary new native tool or MCP server.

The patched runtime keeps skill discovery/loading and workspace file tools when the skills capability is enabled. It removes the native bash tool and kagent’s ask_user tool from the model’s registry, including subagents. Agents are long running and autonomous, so no tool may stop a run to wait for a person. The platform MCP server exposes scheduling tools, not a replacement shell or code runner. See Runtime isolation.

Each existing package cache must carry a source marker matching the requested repository, commit and path, or the applicable OCI/S3 source fields. Missing, malformed or mismatching markers stop materialization before agent construction and server startup. The image build validates packaged skills with the pinned ADK parser and records that source marker. Missing or renamed selected skills also fail instead of silently selecting alternatives.

This check runs when each runtime starts. It is not an API check that the deployed image supports all saved skill revisions, or a cluster-wide promotion gate. A new catalog pin does not rewrite existing agents: preserve compatibility with their saved sources when promoting runtime images.

Capabilities and edits

Skills, workspace-tool choices, delegation targets, tool bindings and paper-trading markets are fixed at creation. Changing those choices requires a new agent. Ordinary edits preserve saved skill source pins and capability selections, even if the current catalog has changed or is unavailable. Unsupported arbitrary tools, mcp_servers, memory, workspace and per-edge subagent descriptions are refused.

Explicit changes to immutable selections return FailedPrecondition. UpdateAgent.update_mask records presence for these selections, including an explicitly empty list or false; it does not make the other mutable fields a general partial-update API. Importing over an existing agent must retain its exact saved capability configuration. A new import resolves skill names through the creation catalog.

Agent read-back includes selected skills with source URL, commit, path or OCI reference, workspace_tools_enabled, native_tools, and capability_selection_immutable. Without skills the native inventory is empty. With skills enabled it is list_skills, load_skill, load_skill_resource, read_file, write_file and edit_file. It does not advertise native Bash, ask_user or optional file tools that this runtime does not enable.

The supported capabilities are:

Tool availability also depends on configured services. The API’s read-back and runtime bindings, not a count inferred from selected skills, determine what an agent can call.

Configuration reconciliation

The Agent retains the desired template; the separate AgentTemplate is its runtime projection. Failed projection writes are retried from that desired configuration. Reconciliation also converges per-agent credentials, MCP server references and model gateway settings while preserving the selected model, skill pins and tool selections. It does not provision a replacement brokerage account. A successful definition update does not establish that an already prepared actor has loaded it.

Suspend, resume and history

Suspension records a platform annotation that blocks new work and requests suspension of the agent’s sessions. Substrate session suspension snapshots state and releases its worker allocation. Resume clears the platform gate; a later message can resume the session. This is not a replica-count change on a per-agent Deployment.

Deletion records durable intent and blocks new work before cleanup. Cleanup waits for admitted operations, stops active tasks and retries remaining steps. It retains session history and records the deleted agent’s immutable identity. Reusing the name creates a new incarnation; retained sessions cannot submit work to that replacement.

A suspension request, an admitted message and a completed task are different states. Partial failures must remain visible. Task history is a persisted projection with the reconciliation limits described on Streaming, not a promise to replay every live frame.

Retired runtime

The separate agents repository is archived historical material. The current Harness uses the custom runtime built from platform-api/runtime/kagent; the archived BYO image is not a supported alternative deployment path.