Rachael-Graham · Nov 5, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026
diff --git a/docs-site/content/kagent/1.x/agents/human-in-the-loop.md b/docs-site/content/kagent/1.x/agents/human-in-the-loop.md
diff --git a/docs-site/content/kagent/1.x/examples/a2a-agents.md b/docs-site/content/kagent/1.x/examples/a2a-agents.md
@@ -15,6 +15,8 @@ This example uses [grpcurl](https://github.com/fullstorydev/grpcurl) to show the
 
 The controller serves `lf.a2a.v1.A2AService` on port `8083`, alongside its REST API and its MCP endpoint. The kagent CLI reaches the same port and the same service.
 
+Every A2A call must send the `A2A-Version: 1.0` header, as gRPC metadata or as an HTTP header. Without it, the controller rejects the call with `this version is not supported: requested "0.3", served "1.0"`. The A2A client libraries set the header automatically, but a hand-assembled request such as a `grpcurl` call must set it.
+
 A gRPC caller identifies the Agent in the standard A2A `tenant` field, as `<namespace>/<name>`, and the controller routes the call to that Agent. The same controller serves A2A over HTTP JSON-RPC, where the URL path selects the Agent instead:
 
 | Transport | How a caller selects the Agent |
@@ -58,6 +60,7 @@ An A2A client typically starts by reading the agent card, which tells it what th
 1. Fetch the card for your Agent.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -d '{"tenant":"'"$AGENT"'"}' \
      localhost:8083 lf.a2a.v1.A2AService/GetExtendedAgentCard
    ```
@@ -122,6 +125,7 @@ A message part can also contain a file. Put the file's bytes in the part's `raw`
 1. Send a message to the Agent. Omitting a `contextId` starts a new Session.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -d '{"tenant":"'"$AGENT"'","message":{"messageId":"'"$(uuidgen)"'","role":"ROLE_USER","parts":[{"text":"What is 7 times 6? Answer with just the number."}]}}' \
      localhost:8083 lf.a2a.v1.A2AService/SendMessage
    ```
@@ -165,6 +169,7 @@ A message part can also contain a file. Put the file's bytes in the part's `raw`
 1. Send a message on the streaming method.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -d '{"tenant":"'"$AGENT"'","message":{"messageId":"'"$(uuidgen)"'","contextId":"'"$SESSION_ID"'","role":"ROLE_USER","parts":[{"text":"Count from 1 to 3."}]}}' \
      localhost:8083 lf.a2a.v1.A2AService/SendStreamingMessage
    ```
@@ -186,6 +191,7 @@ A task outlives the call that created it, so a caller that lost its connection c
 1. Read the task by ID.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -d '{"tenant":"'"$AGENT"'","id":"'"$TASK_ID"'"}' \
      localhost:8083 lf.a2a.v1.A2AService/GetTask
    ```
@@ -353,6 +359,7 @@ Answering a pause needs the human-in-the-loop extension, which a caller requests
 1. Send a message that requests the extension.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -H "A2A-Extensions: https://kagent.dev/extensions/hitl/v1" \
      -d '{"tenant":"'"$AGENT"'","message":{"messageId":"'"$(uuidgen)"'","role":"ROLE_USER","extensions":["https://kagent.dev/extensions/hitl/v1"],"parts":[{"text":"Should I increase the replica count?"}]}}' \
      localhost:8083 lf.a2a.v1.A2AService/SendMessage
@@ -397,6 +404,7 @@ Answering a pause needs the human-in-the-loop extension, which a caller requests
 4. Answer on the same task. The response goes in the same metadata key, references the request `id` that it answers, and sets `taskId` so that it answers the paused task rather than starting a new turn.
    ```bash
    grpcurl -plaintext \
+     -H 'A2A-Version: 1.0' \
      -H "A2A-Extensions: https://kagent.dev/extensions/hitl/v1" \
      -d '{"tenant":"'"$AGENT"'","message":{"messageId":"'"$(uuidgen)"'","taskId":"'"$PAUSED_TASK_ID"'","contextId":"'"$PAUSED_SESSION_ID"'","role":"ROLE_USER","extensions":["https://kagent.dev/extensions/hitl/v1"],"parts":[{"text":"staging"}],"metadata":{"https://kagent.dev/extensions/hitl/v1":{"type":"ask_user_response","id":"'"$REQUEST_ID"'","answers":[{"answer":["staging"]}]}}}}' \
      localhost:8083 lf.a2a.v1.A2AService/SendMessage

diff --git a/docs-site/content/kagent/1.x/examples/agents-via-mcp.md b/docs-site/content/kagent/1.x/examples/agents-via-mcp.md
diff --git a/docs-site/content/kagent/1.x/operations/multiple-namespaces.md b/docs-site/content/kagent/1.x/operations/multiple-namespaces.md
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
diff --git a/docs-site/content/kagent/1.x/operations/upgrade-from-0x.md b/docs-site/content/kagent/1.x/operations/upgrade-from-0x.md
diff --git a/docs-site/content/kagent/1.x/operations/upgrade.md b/docs-site/content/kagent/1.x/operations/upgrade.md
@@ -7,9 +7,7 @@ author: kagent.dev
 
 An installation of {{< reuse "kagent-docs/snippets/name-product.md" >}} consists of five Helm releases. Upgrade the releases in the order that you installed them, starting with the CRDs, then Agent Substrate, and then the kagent control plane.
 
-Upgrade from one stable release to the next, and do not skip a stable release. Before you move to the next stable release, upgrade to the latest patch version of your current stable release. Patch releases do not change the database schema, so you can upgrade directly to the latest patch release without the patch releases in between. To move a 0.10.x installation to 1.x, see [Upgrade from 0.x]({{< link path="operations/upgrade-from-0x" >}}) instead.
-
-<!-- REVIEW: kagent is moving from semantic versioning to calendar versioning. The release-order rule in the preceding paragraph follows the stable-release model that OSS and enterprise share and names no version format. Add version examples, and define a stable release, when the calendar version format is published. The calendar versioning scheme calls these releases LTS releases, so replace "stable" with "LTS" then. The version variables in "Prepare to upgrade" assume semver. -->
+Upgrade from one minor release to the next, such as from 1.0 to 1.1, and do not skip a minor release. Before you move to the next minor release, upgrade to the latest patch version of your current minor release. Patch releases do not change the database schema, so you can upgrade directly to the latest patch release without the patch releases in between. To move a 0.10.x installation to 1.x, see [Upgrade from 0.x]({{< link path="operations/upgrade-from-0x" >}}) instead.
 
 ## Prepare to upgrade
 
@@ -49,7 +47,7 @@ Complete every step in this section before you change any release. The steps mak
    ```
    For an installation that you exported from the kagent CLI, the `kagent-values.yaml` file contains your model provider API key in plain text. Store the files securely.
 
-6. Save the target versions in environment variables. The following values are the versions that this documentation describes. To upgrade across more than one stable release, set the versions of the next stable release, and repeat the upgrade for each stable release.
+6. Save the target versions in environment variables. The following values are the versions that this documentation describes. To upgrade across more than one minor release, set the versions of the next minor release, and repeat the upgrade for each minor release.
    ```bash
    export KAGENT_VERSION={{< reuse "kagent-docs/versions/kagent.md" >}}
    export SUBSTRATE_VERSION={{< reuse "kagent-docs/versions/agent-substrate-chart.md" >}}

diff --git a/docs-site/content/kagent/1.x/reference/release-notes/1.0.md b/docs-site/content/kagent/1.x/reference/release-notes/1.0.md
@@ -34,47 +34,45 @@ For the component versions that this release pins and the Kubernetes version tha
 
 ### 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 reusable resources, pairs them in a third, and tracks each running Session as a fourth object.
+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 {{< gloss "Harness" >}}Harness{{< /gloss >}} defines how an agent is allowed to run**, including its runtime, workload image, {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}}, and snapshot storage. One Harness serves many agents, so expect fewer Harnesses than you had 0.10.x Agents.
 - **An {{< gloss "AgentTemplate" >}}AgentTemplate{{< /gloss >}} defines what an agent does**, including its model, system prompt, tools, skills, and plugins.
 - **An {{< gloss "Agent" >}}Agent{{< /gloss >}} 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. Neither resource has a field that names the other, so only an Agent connects them. For the full model, see [Core concepts]({{< link path="about/core-concepts#agent" >}}).
+A Harness and an AgentTemplate do not reference each other, so only an Agent connects them. For the full model, see [Core concepts]({{< link path="about/core-concepts#agent" >}}).
 
 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 have no 0.10.x counterpart.
+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]({{< link path="agents/agent-harness#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]({{< link path="about/substrate-runtime/sandboxing#sandbox-classes" >}}).
-- **Access to destinations with EgressPolicy resources:** You can apply an EgressPolicy to an Agent or a SandboxTemplate to inject a credential into requests that the Agent or SandboxTemplate sends to a destination. For the procedure, see [Grant access to a destination]({{< link path="agents/egress-policies#grant-access-to-a-destination" >}}).
+- **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]({{< link path="agents/egress-policies#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]({{< link path="about/substrate-runtime/standalone-sandboxes#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]({{< link path="setup/model-providers/about-model-providers#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]({{< link path="agents/context-management#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]({{< link path="agents/structured-output#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]({{< link path="agents/share-a-session#a-share-is-a-capability-not-a-grant-to-a-user" >}}).
-- **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 conversation. For the procedure, see [Create a schedule in the UI]({{< link path="agents/scheduled-runs#create-a-schedule-in-the-ui" >}}).
+- **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]({{< link path="agents/scheduled-runs#create-a-schedule-in-the-ui" >}}).
 
 ### Removed and replaced resources
 
-Each 0.10.x resource kind is replaced, removed, or carried forward in 1.0. The distinction matters when you plan a move. A replaced kind has a destination for its configuration. A removed kind does not.
+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 {{< gloss "RemoteMCPServer" >}}RemoteMCPServer{{< /gloss >}}, 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 replacement. Every 1.0 agent runs in a sandbox by default. |
+| 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. It provisioned OpenClaw and Hermes coding-agent sandboxes with Slack and Telegram channels. |
-| ModelConfig, ModelProviderConfig, RemoteMCPServer | Carried forward. `v1alpha3` keeps every field that `v1alpha2` defines except one, so an exported resource needs a new `apiVersion` and one field rename. The ModelConfig field `apiKeyPassthrough` is now `tokenPassthrough`, the same name that RemoteMCPServer uses for the same behavior. |
-
-> [!IMPORTANT]
-> The 1.0 Harness and the 0.10.x AgentHarness share part of a name and nothing else. AgentHarness provisioned coding-agent sandboxes, while Harness governs how any agent is allowed to run. Read Harness as a new resource rather than a renamed one.
+| 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]({{< link path="operations/upgrade-from-0x#agents-become-an-agenttemplate-a-harness-and-an-agent" >}}).
 
@@ -86,4 +84,4 @@ Compatibility promises start at 1.0. Plan a migration from 0.10.x, not an upgrad
 - **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 once the new installation answers correctly. 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, Session history does not move to the new installation. For the full procedure, see [Upgrade from 0.x]({{< link path="operations/upgrade-from-0x#in-place-upgrade-blockers" >}}).
+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]({{< link path="operations/upgrade-from-0x" >}}).