Helm install and upgrade

.github/workflows/update-ref-docs.yaml

@@ -662,6 +662,8 @@ jobs:
           echo "Version-split conrefs (writing the $LINE span):"
           write_span_conref "$VERSIONS_DIR/kagent.md"          "$LINE" "$KAGENT_VERSION"
           write_span_conref "$VERSIONS_DIR/agent-substrate.md" "$LINE" "$SUBSTRATE_VERSION"
+          # The Agent Substrate chart is published at the same version as the release.
+          write_span_conref "$VERSIONS_DIR/agent-substrate-chart.md" "$LINE" "$SUBSTRATE_VERSION"
           write_span_conref "$VERSIONS_DIR/max-kube.md"        "$LINE" "$MAX_KUBE"
 
           # Flat conrefs, read only by 1.x pages. On a 0.x run their values
@@ -1235,6 +1237,7 @@ jobs:
             | ------ | ----- | ------ |
             | `kagent` (${{ env.LINE }} span) | `${{ env.KAGENT_VERSION }}` | the release tag this run documents |
             | `agent-substrate` (${{ env.LINE }} span) | `${{ env.SUBSTRATE_VERSION }}` | `go/go.mod` replace target |
+            | `agent-substrate-chart` (${{ env.LINE }} span) | `${{ env.SUBSTRATE_VERSION }}` | `go/go.mod` replace target, the same as `agent-substrate` |
             | `max-kube` (${{ env.LINE }} span) | `${{ env.MAX_KUBE }}` | `Makefile` `KIND_IMAGE_VERSION` |
             ${{ env.FLAT_CONREF_ROWS }}
 

docs-site/assets/kagent-docs/snippets/setup/responses-api-files.md

@@ -8,4 +8,4 @@
 
 The runtime refuses a link whose scheme is not `http` or `https`. When the newest user message includes such a link, the turn fails with `cannot send link "<uri>" with media type "<type>": this provider integration can only pass http and https links`. A link in an older message does not fail the turn, because the runtime sends links from older messages as bare URLs. A model with a fetch tool can still retrieve the file.
 
-When a link or an inline PDF or Office file has a display name, the runtime adds a text part that reads `File: <name>` immediately before the file part. An inline image does not get this text part. For the file types and sizes that the UI accepts, see [Attach files to a message]({{< link path="observability/launch-ui#attach-files-to-a-message" >}}).
+When a link or an inline PDF or Office file has a display name, the runtime adds a text part that reads `File: <name>` immediately before the file part. An inline image does not get this text part. For the file types and sizes that the UI accepts, see [Attach files to a message]({{< link path="ui/launch-ui#attach-files-to-a-message" >}}).

docs-site/assets/kagent-docs/versions/agent-substrate-chart.md

@@ -1 +1 @@
-{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}0.4.0-alpha1{{< /version >}}
+{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}1.0.0-rc1{{< /version >}}

docs-site/content/kagent/1.x/agents/agent-harness.md

@@ -89,7 +89,7 @@ A Harness resource names exactly one of the following four harnesses, and that c
 
 The harnesses accept different model providers, which [Model provider support](#model-provider-support) lists, and they accept different AgentTemplate features, which [Tool and skill support](#tool-and-skill-support) lists.
 
-The agent chat in the kagent UI offers file attachments only on the `kagent` harness. An agent on a `byo`, `codex`, or `claude` Harness cannot attach files in the chat. For the file types and size limits that the UI enforces, see [Attach files to a message]({{< link path="observability/launch-ui#attach-files-to-a-message" >}}).
+The agent chat in the kagent UI offers file attachments only on the `kagent` harness. An agent on a `byo`, `codex`, or `claude` Harness cannot attach files in the chat. For the file types and size limits that the UI enforces, see [Attach files to a message]({{< link path="ui/launch-ui#attach-files-to-a-message" >}}).
 
 ### kagent harness
 

docs-site/content/kagent/1.x/examples/a2a-agents.md

@@ -117,7 +117,7 @@ An A2A client typically starts by reading the agent card, which tells it what th
 A message part can also contain a file. Put the file's bytes in the part's `raw` field, which JSON encodes as base64, and set `filename` and `mediaType` on the same part. To send a link to a file, set the part's `url` field in place of `raw`. When the ModelConfig sets `apiFormat: responses`, or the provider is Gemini, the model fetches the file from the link. Every other model receives the link as text.
 
 > [!NOTE]
-> Unlike the UI, which checks each file as you stage it, this path accepts any media type. When the ModelConfig sets `apiFormat: responses`, a PDF, `.docx`, `.xlsx`, or `.pptx` file reaches the model as a file. Any other file whose media type is not text-like reaches the model as the note `[Uploaded file "report.pdf" (application/pdf) could not be read as text.]` instead of contents. The controller's gRPC server rejects any message over 16 MiB, framing included. For how files reach the model, and the file types and sizes that the UI accepts, see [Attach files to a message]({{< link path="observability/launch-ui#attach-files-to-a-message" >}}).
+> Unlike the UI, which checks each file as you stage it, this path accepts any media type. When the ModelConfig sets `apiFormat: responses`, a PDF, `.docx`, `.xlsx`, or `.pptx` file reaches the model as a file. Any other file whose media type is not text-like reaches the model as the note `[Uploaded file "report.pdf" (application/pdf) could not be read as text.]` instead of contents. The controller's gRPC server rejects any message over 16 MiB, framing included. For how files reach the model, and the file types and sizes that the UI accepts, see [Attach files to a message]({{< link path="ui/launch-ui#attach-files-to-a-message" >}}).
 
 1. Send a message to the Agent. Omitting a `contextId` starts a new Session.
    ```bash

docs-site/content/kagent/1.x/observability/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Observability
-description: Open the kagent UI, set up an OpenTelemetry stack, and review the traces, metrics, and logs that kagent and Agent Substrate report.
+description: Set up an OpenTelemetry stack and review the traces, metrics, and logs that kagent and Agent Substrate report.
 weight: 70
 author: kagent.dev
 ---

docs-site/content/kagent/1.x/operations/debug.md

@@ -163,6 +163,26 @@ kubectl get agent <name> -n kagent \
 
 The other cause is deliberate. A {{< gloss "Session" >}}Session{{< /gloss >}} runs the revision that it was created from for its whole life, so editing an AgentTemplate never changes a conversation that already exists. Create a new Session to pick up the edit.
 
+## The controller restarts after an upgrade {#controller-restarts-after-upgrade}
+
+The controller applies the database migrations of the new version when it starts. When a migration fails, the controller stops and Kubernetes restarts it, so the log of the running container does not show the error.
+
+1. Read the log of the previous container. A failed migration logs an error that starts with `run database migrations`.
+   ```bash
+   kubectl logs -n kagent deployment/kagent-controller --previous | grep -i migration
+   ```
+
+2. To return to the previous version, return the database to the schema of the previous version before you roll back the kagent release. Use one of the following methods.
+   * Roll the schema back with the kagent CLI of the version that you upgraded to. Set `<version>` to the schema version that you recorded in [Prepare to upgrade]({{< link path="operations/upgrade#prepare-to-upgrade" >}}). A down migration can delete data.
+     ```bash
+     kagent db migrate goto <version> \
+       --source core \
+       --db-url "postgresql://<user>:<password>@<host>:5432/kagent" \
+       --db-role <owner-role>
+     ```
+     <!-- REVIEW: The goto command was verified only as a no-op at 1.0.0-rc1, which ships a single migration. Verify a real schema rollback when a release adds a second migration. -->
+   * Restore the database backup that you took in [Prepare to upgrade]({{< link path="operations/upgrade#prepare-to-upgrade" >}}).
+
 ## Collect logs
 
 When the conditions do not explain a failure, collect evidence from the logs. Read the controller log to locate a single failing call, or collect a bug report to give someone else the full diagnostic data at once.

docs-site/content/kagent/1.x/operations/export-to-helm.md

@@ -15,7 +15,7 @@ The export contains only the Helm releases. `kagent install` also creates the Ag
 
 ## Before you begin
 
-1. Install kagent with the kagent CLI, as described in [Install kagent]({{< link path="setup/installation#install-kagent" >}}). Keep the CLI configuration file that passes Helm values to `kagent install`, and the values files that it references. The CLI reads the configuration file from one of the following locations:
+1. Install kagent with the kagent CLI, as described in [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}). Keep the CLI configuration file that passes Helm values to `kagent install`, and the values files that it references. The CLI reads the configuration file from one of the following locations:
    * The path that you passed with the `--config` flag, such as `kagent-config.yaml`.
    * When you omit `--config`, `$XDG_CONFIG_HOME/kagent/config.yaml` on Linux, or `~/.config/kagent/config.yaml` when `XDG_CONFIG_HOME` is not set. On macOS, `~/Library/Application Support/kagent/config.yaml`.
 
@@ -80,4 +80,4 @@ The `install.sh` script runs `helm upgrade --install` for each release, in insta
 
 ## Manage the installation with Helm
 
-To change a value after you apply the export, edit the values file for that release in the exported directory, and run `install.sh` again. Commit the change to the repository so that the directory stays the record of the Helm releases.
+After you apply the export, manage each release with `helm upgrade`. The export moves the management of the releases from `kagent install` to Helm once, so do not run `install.sh` again. To upgrade to a later release, follow [Upgrade]({{< link path="operations/upgrade" >}}).

docs-site/content/kagent/1.x/operations/upgrade-from-0x.md

@@ -62,7 +62,7 @@ Your Kubernetes resources do carry forward, so export them before anything repla
 
 Install 1.0 against the empty database that you provisioned. kagent and Agent Substrate both store their state in that database, each with an owner login that applies migrations and a read/write login that serves runtime queries. `kagent install` normally creates a development database for both. The `--skip-database-setup` flag skips that database. The releases then read the connection Secrets that you create in this section.
 
-Before you start, complete the [Before you begin]({{< link path="setup/installation#before-you-begin" >}}) steps of the installation guide. Those steps prepare the kagent CLI, your provider API key, and a cluster at Kubernetes 1.37 or later.
+Before you start, complete the [Before you begin]({{< link path="setup/installation#before-you-begin" >}}) steps of the installation guide. Those steps prepare a cluster at Kubernetes 1.37 or later and your provider API key. Then install the CLI tools in step 1 of [Install with the CLI]({{< link path="setup/installation#install-kagent" >}}).
 
 1. Create the namespaces that contain the connection Secrets. `kagent install` uses the namespaces when they already exist.
    ```bash