From 69b8f8dc3b688a335cbb524b3e4923af396db857 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 09:55:31 -0500 Subject: [PATCH 01/31] docs: add v0.10 release notes and update upgrade guide for 0.10 beta1 - Add v0.10 release notes section covering Go ADK default runtime switch, A2A AgentCard metadata, configurable streaming timeouts, controller service annotations, ACP substrate support, and out-of-band database migrations - Update agents concept page: Go ADK is now default, add A2A AgentCard metadata section - Update upgrade guide: new "Run migrations out-of-band" section and replace golang-migrate Option 2 with kagent db migrate CLI Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 36 ++++-- .../docs/kagent/operations/upgrade/page.mdx | 73 ++++++++---- .../kagent/resources/release-notes/page.mdx | 106 ++++++++++++++++++ 3 files changed, 186 insertions(+), 29 deletions(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 4cd4f5c4..91d3e533 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -238,13 +238,13 @@ To learn more about using skills in your agents, see the [Skills example guide]( ## Runtime -You can choose between two Agent Development Kit (ADK) runtimes for declarative agents: **Python** (default) and **Go**. +You can choose between two Agent Development Kit (ADK) runtimes for declarative agents: **Go** (default) and **Python**. -| Feature | Python ADK | Go ADK | -|---------|-----------|--------| -| Startup time | ~15 seconds | ~2 seconds | -| Ecosystem | Google ADK, LangGraph, CrewAI integrations | Native Go implementation | -| Resource usage | Higher (Python runtime) | Lower (compiled binary) | +| Feature | Go ADK | Python ADK | +|---------|--------|-----------| +| Startup time | ~2 seconds | ~15 seconds | +| Ecosystem | Native Go implementation | Google ADK, LangGraph, CrewAI integrations | +| Resource usage | Lower (compiled binary) | Higher (Python runtime) | | Default | Yes | No | | Memory support | Yes | Yes | | MCP support | Yes | Yes | @@ -256,7 +256,7 @@ Select the runtime via the `runtime` field in the declarative agent spec. spec: type: Declarative declarative: - runtime: go # or "python" (default) + runtime: go # or "python" modelConfig: default-model-config systemMessage: "You are a helpful agent." ``` @@ -304,6 +304,28 @@ You can run a declarative agent in an isolated sandbox by creating a `SandboxAge For setup steps, see the [Agent Substrate example](/docs/kagent/examples/agent-substrate). +## A2A AgentCard metadata + +When another agent or client discovers your agent over the [A2A protocol](https://google.github.io/A2A/specification/#5-agent-discovery-using-an-agent-card), it reads a machine-readable AgentCard from your agent's `/.well-known/agent.json` endpoint. You can enrich that card with optional metadata fields on the `Agent` spec. + +```yaml +spec: + iconUrl: https://example.com/icons/my-agent.png + documentationUrl: https://docs.example.com/my-agent/ + version: "1.0.0" + provider: + organization: My Organization + url: https://example.com +``` + +| Field | Description | +|-------|-------------| +| `iconUrl` | URL to an icon image representing the agent. Must be a valid URI. | +| `documentationUrl` | URL to human-readable documentation for the agent. Must be a valid URI. | +| `version` | Version string for the agent, such as `"1.0.0"`. | +| `provider.organization` | Name of the organization responsible for the agent. | +| `provider.url` | URL to the agent provider's website or documentation. Must be a valid URI. | + ## Agents as Tools kagent also supports using agents as tools. Any agent you create can be referenced and used by other agents you have. An example use case would be to have a PromQL agent that knows how to create PromQL queries from natural language. Then you'd create a second agent that would use the PromQL agent whenever it needs to create a PromQL query. diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index 87fbad37..40e33644 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -88,6 +88,44 @@ After upgrading, verify that kagent is running. kubectl get pods -n kagent ``` +## Run migrations out-of-band + +By default, kagent runs database migrations automatically at controller startup. You can disable this behavior and manage migrations separately—for example, from a CI/CD pipeline or a Helm pre-upgrade hook. + +### Enable skip migrations + +Set `database.postgres.skipMigrations: true` in your Helm values file: + +```yaml +database: + postgres: + skipMigrations: true +``` + +When enabled, the controller does not run migrations at startup. Instead, it verifies that the schema is already fully migrated and exits with an error if it is not. Apply all pending migrations before installing or upgrading kagent. + +### Apply migrations + +Use `kagent db migrate up` to apply all pending migrations before starting or upgrading the controller. Set `POSTGRES_DATABASE_URL` to your database connection string (see [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration)). + +```bash +export POSTGRES_DATABASE_URL="postgres://:@:5432/" +kagent db migrate up +``` + +### Check migration status + +```bash +kagent db migrate status +``` + +Example output: +``` +9 migration(s) applied, 0 pending + core: 6 applied (at v6), 0 pending + vector: 3 applied (at v3), 0 pending +``` + ## Roll back kagent If you need to roll back to a previous version after a successful upgrade, use the following steps. @@ -147,28 +185,24 @@ pg_restore \ After restoring, follow the steps to [roll back the kagent application](#steps-to-roll-back). -#### Option 2: Run down migrations +#### Option 2: Use the kagent CLI -Use `golang-migrate` to run down migrations one minor version at a time. This preserves data written after the snapshot but requires more steps. +Use the `kagent db migrate` command to run down migrations one minor version at a time. This preserves data written after the snapshot but requires more steps. -The source must be the current (newer) version that you are rolling back from, because it contains the down migrations needed to reverse the schema changes. The `goto` target is the highest migration sequence number present in the version that you are rolling back to. +The target is the highest migration sequence number present in the version that you are rolling back to. For example, `v0.9.9` has migrations up to `000005_a2a_protocol_version.up.sql` and `v0.9.3` has migrations up to `000004_feedback_single_pk.up.sql`. To roll back from `v0.9.9` to `v0.9.3`, you set `ROLLBACK_VERSION=0.9.3` and run `goto 4` because you want to go back to migration sequence 4 (v0.9.3's `000004`). -For example, `v0.9.9` has migrations up to `000005_a2a_protocol_version.up.sql` and `v0.9.3` has migrations up to `000004_feedback_single_pk.up.sql`. To roll back from `v0.9.9` to `v0.9.3`, you set `CURRENT_VERSION=0.9.9`, `ROLLBACK_VERSION=0.9.3`, and run `goto 4` because you want to go back to migration sequence 4 (v0.9.3's `000004`). - -1. Save your current kagent version and the kagent version you want to roll back to in environment variables. +1. Save your current kagent version and the version you want to roll back to in environment variables. ```bash export CURRENT_VERSION= export ROLLBACK_VERSION= ``` -2. Install [`golang-migrate`](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate). - -3. Stop the kagent controller. +2. Stop the kagent controller. ```bash kubectl -n kagent scale deploy/kagent-controller --replicas=0 ``` -4. Open the core migration directory for your rollback version and save the sequence number of the highest-numbered file in an environment variable, such as `4` from the previous v0.9.3 `goto 4` example. +3. Open the core migration directory for your rollback version and save the sequence number of the highest-numbered file in an environment variable. ```bash open "https://github.com/kagent-dev/kagent/tree/v${ROLLBACK_VERSION}/go/core/pkg/migrations/core/" ``` @@ -176,26 +210,21 @@ For example, `v0.9.9` has migrations up to `000005_a2a_protocol_version.up.sql` export ROLLBACK_MIGRATION_VERSION= ``` -5. Reset the core track. The `github://` source references the migration files directly from the release tag without a local checkout. For the database connection string, see [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration). +4. Reset the core track. For the database connection string, see [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration). ```bash - migrate \ - -source "github://kagent-dev/kagent/go/core/pkg/migrations/core#v$CURRENT_VERSION" \ - -database "postgres://:@:5432/?sslmode=require&x-migrations-table=schema_migrations" \ - goto $ROLLBACK_MIGRATION_VERSION + export POSTGRES_DATABASE_URL="postgres://:@:5432/" + kagent db migrate goto $ROLLBACK_MIGRATION_VERSION --source core ``` -6. If vector features are enabled, reset the vector track as well. - 1. Open the vector migration directory for your rollback version and save the sequence number of the highest-numbered file in an environment variable. +5. If vector features are enabled, reset the vector track as well. + 1. Open the vector migration directory for your rollback version and save the sequence number of the highest-numbered file. ```bash open "https://github.com/kagent-dev/kagent/tree/v${ROLLBACK_VERSION}/go/core/pkg/migrations/vector/" export ROLLBACK_VECTOR_MIGRATION_VERSION= ``` 2. Reset the vector track. ```bash - migrate \ - -source "github://kagent-dev/kagent/go/core/pkg/migrations/vector#v$CURRENT_VERSION" \ - -database "postgres://:@:5432/?sslmode=require&x-migrations-table=vector_schema_migrations" \ - goto $ROLLBACK_VECTOR_MIGRATION_VERSION + kagent db migrate goto $ROLLBACK_VECTOR_MIGRATION_VERSION --source vector ``` -7. After the database is at the correct schema version, follow the steps to [roll back the kagent application](#steps-to-roll-back). +6. After the database is at the correct schema version, follow the steps to [roll back the kagent application](#steps-to-roll-back). diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 3d42b59f..800ff626 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -18,6 +18,112 @@ The kagent documentation shows information only for the latest release. If you r For more details on the changes between versions, review the [kagent GitHub releases](https://github.com/kagent-dev/kagent/releases). +# v0.10 + +Review this summary of significant changes from kagent version 0.9 to v0.10. + +**What's included:** + +* Go ADK is now the default runtime — new declarative agents use the Go ADK by default. +* A2A AgentCard metadata — new optional fields on the Agent spec for enriching the A2A AgentCard. +* Configurable streaming timeouts — Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. +* Controller service annotations — `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. +* ACP protocol support for substrate agents — ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. +* Out-of-band database migrations — manage database migrations via the kagent CLI independently of controller startup. + +## Go ADK is now the default runtime + +The default declarative agent runtime is now **Go**. Previously, new declarative agents used the Python ADK unless `runtime: go` was explicitly set. The Go ADK starts in approximately 2 seconds (versus ~15 seconds for Python) and uses fewer resources. + +Existing agents with an explicit `runtime: python` are unaffected. Agents that relied on the Python default will now use Go unless you add `runtime: python` to their spec. + +For a full comparison, see [Agents — Runtime](/docs/kagent/concepts/agents#runtime). + +## A2A AgentCard metadata + +You can now enrich your agent's [A2A AgentCard](https://google.github.io/A2A/specification/#5-agent-discovery-using-an-agent-card) with optional metadata fields on the `Agent` spec. The AgentCard is served from `/.well-known/agent.json` and is read by other agents and A2A-compatible clients when they discover your agent. + +```yaml +spec: + iconUrl: https://example.com/icons/my-agent.png + documentationUrl: https://docs.example.com/my-agent/ + version: "1.0.0" + provider: + organization: My Organization + url: https://example.com +``` + +| Field | Description | +|-------|-------------| +| `iconUrl` | URL to an icon image representing the agent. | +| `documentationUrl` | URL to human-readable documentation for the agent. | +| `version` | Version string for the agent, such as `"1.0.0"`. | +| `provider.organization` | Name of the organization responsible for the agent. | +| `provider.url` | URL to the agent provider's website or documentation. | + +For more information, see [Agents — A2A AgentCard metadata](/docs/kagent/concepts/agents#a2a-agentcard-metadata). + +## Configurable streaming timeouts + +New Helm values let you tune how long nginx and the browser keep streaming connections open. The defaults are all set to 1800 seconds (30 minutes). + +| Helm value | Default | Description | +|---|---|---| +| `ui.streamTimeoutSeconds` | `1800` | Client-side EventSource inactivity timeout. Exposed to the UI container at runtime. | +| `ui.nginx.proxyReadTimeout` | `1800` | nginx `proxy_read_timeout` for the UI sidecar. | +| `ui.nginx.proxySendTimeout` | `1800` | nginx `proxy_send_timeout` for the UI sidecar. | +| `ui.openshiftRoute.annotations` | — | Annotations added to the OpenShift Route resource. Set `haproxy.router.openshift.io/timeout: 120m` to prevent the default 60-second HAProxy timeout from terminating A2A and SSE streams. | + +Example for OpenShift deployments: + +```yaml +ui: + openshiftRoute: + annotations: + haproxy.router.openshift.io/timeout: 120m +``` + +## Controller service annotations + +You can now add custom annotations to the kagent controller's Kubernetes Service via `controller.service.annotations`. This is useful for integrations such as AWS Load Balancer Controller and ExternalDNS. + +```yaml +controller: + service: + annotations: + service.beta.kubernetes.io/aws-load-balancer-type: external + external-dns.alpha.kubernetes.io/hostname: kagent.example.com +``` + +## ACP protocol support for substrate agents + +kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with openclaw and hermes to communicate over the substrate runtime without additional configuration. + +## Out-of-band database migrations + +Two new features give operators control over when and how database migrations run. + +### kagent db migrate CLI + +A new `kagent db migrate` command group lets you apply, inspect, and recover database migrations without relying on controller startup. This is useful for CI/CD pipelines and environments where migration timing must be explicit. + +| Subcommand | Description | +|---|---| +| `kagent db migrate up` | Apply all pending migrations across all sources. | +| `kagent db migrate status` | Show applied and pending migration counts per source. | +| `kagent db migrate version` | Print the highest applied version per source. | +| `kagent db migrate goto V --source ` | Move the schema to version V (forward or backward). Used for rollbacks. | +| `kagent db migrate down N --source ` | Roll back the N most recent migrations on the named source. | +| `kagent db migrate force V --source ` | Mark version V as applied without running SQL. Used to recover from a dirty migration state. | + +Set `POSTGRES_DATABASE_URL` or pass `--db-url` to provide the database connection string. If `DATABASE_VECTOR_ENABLED` is not set in the environment, the CLI reads it from the `kagent-controller` ConfigMap in the current cluster context. + +### Skip startup migrations + +A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents the controller from running migrations at startup. When enabled, the controller verifies the schema is already fully migrated and exits with an error if it is not. Apply migrations out-of-band before installing or upgrading when this option is set. + +For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). + # v0.9 Review this summary of significant changes from kagent version 0.8 to v0.9. From a488649ba30c762af4c7c9167e51205c9e5868ec Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 09:57:27 -0500 Subject: [PATCH 02/31] docs: add v0.10 beta2 release notes - Chat session sharing (read-only and read-write modes) - Substrate support expanded to BYO and Python runtime agents - Configurable A2A client timeout (controller.a2aClientTimeout) - SSO session expiry auto re-authentication - Update agent-substrate concept page to reflect all three supported runtimes Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Rachael Graham --- .../kagent/concepts/agent-substrate/page.mdx | 2 +- .../kagent/resources/release-notes/page.mdx | 32 +++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/src/app/docs/kagent/concepts/agent-substrate/page.mdx b/src/app/docs/kagent/concepts/agent-substrate/page.mdx index 7acbbfd1..8a3e1364 100644 --- a/src/app/docs/kagent/concepts/agent-substrate/page.mdx +++ b/src/app/docs/kagent/concepts/agent-substrate/page.mdx @@ -63,7 +63,7 @@ Agent Substrate is composed of a control plane, a data plane, and snapshot stora ### Declarative agents -Run a (Go) declarative agent on Agent Substrate by creating a `SandboxAgent` resource. It carries the same spec as a regular `Agent`, but the kagent controller runs it as a sandboxed workload on the runtime instead of a plain Deployment. +Run a declarative agent on Agent Substrate by creating a `SandboxAgent` resource. It carries the same spec as a regular `Agent`, but the kagent controller runs it as a sandboxed workload on the runtime instead of a plain Deployment. All three declarative runtimes are supported: **Go** (default), **Python**, and **BYO**. ### AgentHarness diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 800ff626..e585d05f 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -29,6 +29,10 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * Configurable streaming timeouts — Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. * Controller service annotations — `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. * ACP protocol support for substrate agents — ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. +* Chat session sharing — session owners can generate shareable links in read-only or read-write mode. +* Substrate support for BYO and Python agents — `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. +* Configurable A2A client timeout — `controller.a2aClientTimeout` removes the previous 3-minute hard cutoff for long-running agents. +* SSO session expiry re-authentication — expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. * Out-of-band database migrations — manage database migrations via the kagent CLI independently of controller startup. ## Go ADK is now the default runtime @@ -99,6 +103,34 @@ controller: kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with openclaw and hermes to communicate over the substrate runtime without additional configuration. +## Chat session sharing + +Session owners can now generate shareable links for any chat session. Shared sessions support two modes: + +- **Read-only** (default): recipients can view the conversation but cannot send messages or respond to tool confirmations. Useful for review, handoff documentation, and broadcasting agent output. +- **Read-write** (interactive): recipients can interact with the session as if they were the owner — sending messages, approving or rejecting tool calls, and answering agent questions. All parties see the results in real time. + +Shared sessions that a user has accessed appear in their sidebar alongside their own sessions, so recipients do not need to keep the original link to return. Agents can also generate and revoke share links as part of their own workflows. + +## Substrate support for BYO and Python agents + +`SandboxAgent` now supports running BYO agents and Python runtime declarative agents on Agent Substrate, in addition to Go declarative agents. This means any `Agent` type can be run as a sandboxed substrate workload. + +For setup details, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). + +## Configurable A2A client timeout + +A new `controller.a2aClientTimeout` Helm value (default: `""` — no timeout) lets you override the A2A client HTTP timeout. Previously, the a2a-go SDK applied a hard 3-minute timeout to all A2A client requests, causing `context deadline exceeded` errors during long-running agent interactions or SSE streams. + +```yaml +controller: + a2aClientTimeout: "10m" # or "" for no timeout (default) +``` + +## SSO session expiry re-authentication + +When deployed behind an OIDC proxy (such as oauth2-proxy), expired sessions now trigger an automatic redirect to `/oauth2/start` for re-authentication instead of showing an error. A loop guard prevents infinite redirects if re-authentication fails. Sessions in unsecured (no-proxy) mode are unaffected. + ## Out-of-band database migrations Two new features give operators control over when and how database migrations run. From b9422af8407ff539e2438682f048cc560c0efd2d Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 10:02:31 -0500 Subject: [PATCH 03/31] docs: add v0.10 beta3 release notes Beta3 is bug-fix only: CVE patches, Go ADK OpenAI embeddings fix, and Helm image registry handling fixes. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Rachael Graham --- src/app/docs/kagent/resources/release-notes/page.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index e585d05f..6c9be260 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -107,8 +107,8 @@ kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol Session owners can now generate shareable links for any chat session. Shared sessions support two modes: -- **Read-only** (default): recipients can view the conversation but cannot send messages or respond to tool confirmations. Useful for review, handoff documentation, and broadcasting agent output. -- **Read-write** (interactive): recipients can interact with the session as if they were the owner — sending messages, approving or rejecting tool calls, and answering agent questions. All parties see the results in real time. +- **Read-only** (default): Recipients can view the conversation but cannot send messages or respond to tool confirmations. Useful for review, handoff documentation, and broadcasting agent output. +- **Read-write** (interactive): Recipients can interact with the session as if they were the owner, such as sending messages, approving or rejecting tool calls, and answering agent questions. All parties see the results in real time. Shared sessions that a user has accessed appear in their sidebar alongside their own sessions, so recipients do not need to keep the original link to return. Agents can also generate and revoke share links as part of their own workflows. @@ -156,6 +156,12 @@ A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). +## Additional changes in v0.10 + +* **CVE patches** — critical and high CVEs patched in the Go ADK and app container images. +* **Go ADK OpenAI embeddings** — fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. +* **Helm image registry fixes** — Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. + # v0.9 Review this summary of significant changes from kagent version 0.8 to v0.9. From 4e266fdbd3b34cd3e224bc81dba7348a3669dbd1 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 10:17:51 -0500 Subject: [PATCH 04/31] Update page.mdx Signed-off-by: Rachael Graham --- src/app/docs/kagent/operations/upgrade/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index 40e33644..f6a4a42d 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -90,7 +90,7 @@ kubectl get pods -n kagent ## Run migrations out-of-band -By default, kagent runs database migrations automatically at controller startup. You can disable this behavior and manage migrations separately—for example, from a CI/CD pipeline or a Helm pre-upgrade hook. +By default, kagent runs database migrations automatically at controller startup. You can disable this behavior and manage migrations separately, for example, from a CI/CD pipeline or a Helm pre-upgrade hook. ### Enable skip migrations From 511e1bc78c7e0e771968310b557dd5b728f8036e Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 10:49:36 -0500 Subject: [PATCH 05/31] Apply suggestions from code review Co-authored-by: Kristin Brown Signed-off-by: Rachael Graham --- src/app/docs/kagent/resources/release-notes/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 6c9be260..8ea95c34 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -101,7 +101,7 @@ controller: ## ACP protocol support for substrate agents -kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with openclaw and hermes to communicate over the substrate runtime without additional configuration. +kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with OpenClaw and Hermes to communicate over the substrate runtime without additional configuration. ## Chat session sharing From 29c0b4f92ed254aa0fb08ea2dd54e71b3c00aa09 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 11:01:04 -0500 Subject: [PATCH 06/31] edits Signed-off-by: Rachael Graham --- .../docs/kagent/operations/upgrade/page.mdx | 5 +- .../kagent/resources/release-notes/page.mdx | 78 +++++++++---------- 2 files changed, 41 insertions(+), 42 deletions(-) diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index f6a4a42d..e28b1b58 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -92,7 +92,7 @@ kubectl get pods -n kagent By default, kagent runs database migrations automatically at controller startup. You can disable this behavior and manage migrations separately, for example, from a CI/CD pipeline or a Helm pre-upgrade hook. -### Enable skip migrations +### Skip startup migrations Set `database.postgres.skipMigrations: true` in your Helm values file: @@ -191,9 +191,8 @@ Use the `kagent db migrate` command to run down migrations one minor version at The target is the highest migration sequence number present in the version that you are rolling back to. For example, `v0.9.9` has migrations up to `000005_a2a_protocol_version.up.sql` and `v0.9.3` has migrations up to `000004_feedback_single_pk.up.sql`. To roll back from `v0.9.9` to `v0.9.3`, you set `ROLLBACK_VERSION=0.9.3` and run `goto 4` because you want to go back to migration sequence 4 (v0.9.3's `000004`). -1. Save your current kagent version and the version you want to roll back to in environment variables. +1. Save the version you want to roll back to in an environment variable. ```bash - export CURRENT_VERSION= export ROLLBACK_VERSION= ``` diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 8ea95c34..7d5e9277 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -24,16 +24,16 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. **What's included:** -* Go ADK is now the default runtime — new declarative agents use the Go ADK by default. -* A2A AgentCard metadata — new optional fields on the Agent spec for enriching the A2A AgentCard. -* Configurable streaming timeouts — Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. -* Controller service annotations — `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. -* ACP protocol support for substrate agents — ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. -* Chat session sharing — session owners can generate shareable links in read-only or read-write mode. -* Substrate support for BYO and Python agents — `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. -* Configurable A2A client timeout — `controller.a2aClientTimeout` removes the previous 3-minute hard cutoff for long-running agents. -* SSO session expiry re-authentication — expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. -* Out-of-band database migrations — manage database migrations via the kagent CLI independently of controller startup. +* Go ADK is now the default runtime: New declarative agents use the Go ADK by default. +* A2A AgentCard metadata: New optional fields on the Agent spec for enriching the A2A AgentCard. +* Configurable streaming timeouts: Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. +* Controller service annotations: `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. +* ACP protocol support for substrate agents: ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. +* Chat session sharing: Session owners can generate shareable links in read-only or read-write mode. +* Substrate support for BYO and Python agents: `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. +* Configurable A2A client timeout: `controller.a2aClientTimeout` removes the previous 3-minute hard cutoff for long-running agents. +* SSO session expiry re-authentication: Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. +* Out-of-band database migrations: Manage database migrations via the kagent CLI independently of controller startup. ## Go ADK is now the default runtime @@ -158,9 +158,9 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op ## Additional changes in v0.10 -* **CVE patches** — critical and high CVEs patched in the Go ADK and app container images. -* **Go ADK OpenAI embeddings** — fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. -* **Helm image registry fixes** — Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. +* **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. +* **Go ADK OpenAI embeddings**: Fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. +* **Helm image registry fixes**: Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. # v0.9 @@ -174,11 +174,11 @@ Review this summary of significant changes from kagent version 0.8 to v0.9. **What's included:** -* Agent Sandbox — run agents in isolated sandboxes with network controls using the Kubernetes agent-sandbox project. -* OIDC proxy authentication — optional enterprise authentication via oauth2-proxy with support for Cognito, Okta, Dex, and other OIDC providers. -* SAP AI Core provider — new model provider for SAP AI Core via the Orchestration Service. -* Database migration tooling — the database backend is refactored from GORM + AutoMigrate to golang-migrate + sqlc. -* Bedrock embedding support — native Bedrock embedding models for agent memory. +* Agent Sandbox: Run agents in isolated sandboxes with network controls using the Kubernetes agent-sandbox project. +* OIDC proxy authentication: Optional enterprise authentication via oauth2-proxy with support for Cognito, Okta, Dex, and other OIDC providers. +* SAP AI Core provider: New model provider for SAP AI Core via the Orchestration Service. +* Database migration tooling: The database backend is refactored from GORM + AutoMigrate to golang-migrate + sqlc. +* Bedrock embedding support: Native Bedrock embedding models for agent memory. ## Agent Sandbox @@ -277,32 +277,32 @@ Before you upgrade: ## Additional changes in v0.9 -* **Default model update** — the retired `claude-3-5-haiku-20241022` model is replaced with `claude-haiku-4-5`. -* **Bedrock embedding support** — native Bedrock embedding models are now available for agent memory, extending the existing AWS Bedrock provider. -* **Token exchange for model auth** — a new authentication mechanism that supports token exchange for model configurations. -* **Prompt templates in UI** — prompt templates are now manageable directly in the UI. -* **Require approval toggle in UI** — you can now enable or disable the `requireApproval` setting for tools directly in the UI. -* **Enhanced Go ADK model config** — broader model and provider support in the Go runtime. -* **IPv6/dual-stack support** — agent bind host and UI probes now support IPv6 and dual-stack configurations. -* **AWS LoadBalancer annotations** — the UI Service now supports AWS LoadBalancer service annotations for easier AWS deployment. -* **SSH auth for git-based skills** — fixed SSH authentication when loading skills from private Git repositories. -* **MCP connection error handling** — MCP connection errors are now returned to the LLM as context instead of raising exceptions. -* **RemoteMCPServer TLS (v0.9.6)** — you can now connect to an MCP server that uses a private CA, self-signed certificate, or corporate internal CA by setting the `spec.tls` field on a `RemoteMCPServer`. The `spec.tls` shape mirrors the `ModelConfig` TLS configuration. +* **Default model update**: The retired `claude-3-5-haiku-20241022` model is replaced with `claude-haiku-4-5`. +* **Bedrock embedding support**: Native Bedrock embedding models are now available for agent memory, extending the existing AWS Bedrock provider. +* **Token exchange for model auth**: A new authentication mechanism that supports token exchange for model configurations. +* **Prompt templates in UI**: Prompt templates are now manageable directly in the UI. +* **Require approval toggle in UI**: You can now enable or disable the `requireApproval` setting for tools directly in the UI. +* **Enhanced Go ADK model config**: Broader model and provider support in the Go runtime. +* **IPv6/dual-stack support**: Agent bind host and UI probes now support IPv6 and dual-stack configurations. +* **AWS LoadBalancer annotations**: The UI Service now supports AWS LoadBalancer service annotations for easier AWS deployment. +* **SSH auth for git-based skills**: Fixed SSH authentication when loading skills from private Git repositories. +* **MCP connection error handling**: MCP connection errors are now returned to the LLM as context instead of raising exceptions. +* **RemoteMCPServer TLS (v0.9.6)**: You can now connect to an MCP server that uses a private CA, self-signed certificate, or corporate internal CA by setting the `spec.tls` field on a `RemoteMCPServer`. The `spec.tls` shape mirrors the `ModelConfig` TLS configuration. # v0.8 Review this summary of significant changes from kagent version 0.7 to v0.8. -* Human-in-the-Loop (HITL) — tool approval gates and interactive `ask_user` tool. -* Agent Memory — vector-backed long-term memory for agents. -* Go ADK runtime — new Go-based agent runtime for faster startup and lower resource usage. -* Agents as MCP servers — expose A2A agents via MCP for cross-tool interoperability. -* Skills — markdown knowledge documents loaded from OCI images or Git repositories. -* Go workspace restructure — the Go codebase is split into `api`, `core`, and `adk` modules for composability. -* Prompt templates — reusable prompt fragments from ConfigMaps using Go template syntax. -* Context management — automatic event compaction for long conversations. -* AWS Bedrock support — new model provider for AWS Bedrock. -* **PostgreSQL-only database backend** — SQLite support has been removed. PostgreSQL is now the only supported database backend. +* Human-in-the-Loop (HITL): Tool approval gates and interactive `ask_user` tool. +* Agent Memory: Vector-backed long-term memory for agents. +* Go ADK runtime: New Go-based agent runtime for faster startup and lower resource usage. +* Agents as MCP servers: Expose A2A agents via MCP for cross-tool interoperability. +* Skills: Markdown knowledge documents loaded from OCI images or Git repositories. +* Go workspace restructure: The Go codebase is split into `api`, `core`, and `adk` modules for composability. +* Prompt templates: Reusable prompt fragments from ConfigMaps using Go template syntax. +* Context management: Automatic event compaction for long conversations. +* AWS Bedrock support: New model provider for AWS Bedrock. +* **PostgreSQL-only database backend**: SQLite support has been removed. PostgreSQL is now the only supported database backend. ## Human-in-the-Loop (HITL) From 9fad8d31d52b2bd7456f9ae54cc86da662b72809 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 12:56:00 -0500 Subject: [PATCH 07/31] Update page.mdx Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 7d5e9277..fe332706 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -34,6 +34,14 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * Configurable A2A client timeout: `controller.a2aClientTimeout` removes the previous 3-minute hard cutoff for long-running agents. * SSO session expiry re-authentication: Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. * Out-of-band database migrations: Manage database migrations via the kagent CLI independently of controller startup. +* Deployment annotations: `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. +* nodeSelector for agent Helm charts: Pin agent pods to specific node pools via `nodeSelector` in every bundled agent Helm chart. +* Durable session state for sandbox agents: Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and config rollouts. +* UI HTTPRoute: Optional Gateway API `HTTPRoute` for the UI, for use with kgateway, Istio, or Envoy Gateway. +* MCP App chat widgets: MCP tools that expose UI resources now render interactive widgets inline in the chat interface. +* Pod labels for controller and UI: `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. +* extraObjects: Deploy arbitrary Kubernetes manifests alongside kagent in the same chart lifecycle via `extraObjects`. +* Default nodeSelector for agent deployments: `controller.agentDeployment.nodeSelector` applies a global default nodeSelector to all agent Deployments created by the controller. ## Go ADK is now the default runtime @@ -156,11 +164,150 @@ A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). +## Durable session state for sandbox agents + +Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and config rollouts — a previous conversation continues seamlessly after a Deployment rollout triggered by a prompt change, for example. + +Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. + +You can override the session database endpoint with the `KAGENT_SESSION_DB_URL` environment variable. + +## UI HTTPRoute + +The kagent UI can now be fronted by a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) `HTTPRoute` instead of a plain `Ingress` or OpenShift `Route`. This is useful when your cluster uses kgateway, Istio, or Envoy Gateway as its traffic management layer. + +The HTTPRoute is off by default. Enable it with `ui.httpRoute.enabled: true` and configure `parentRefs` and `hostnames`: + +```yaml +ui: + httpRoute: + enabled: true + parentRefs: + - name: my-gateway + namespace: istio-system + hostnames: + - kagent.example.com +``` + +## MCP App chat widgets + +MCP tools that expose UI resources (MCP Apps) now render interactive widgets inline in the kagent chat interface. When an agent calls such a tool, the response appears as an embedded widget rather than raw text, and users can interact with it directly in the chat window. The backend compacts MCP App tool responses sent to the model to prevent redundant repeated calls. + +## Pod labels for controller and UI + +You can now add custom labels to the pod templates of the controller and UI Deployments. A global `podLabels` map applies to all component pods, with per-component overrides via `controller.podLabels` and `ui.podLabels` (component keys win on conflict). + +```yaml +podLabels: + team: platform + environment: production + +controller: + podLabels: + cost-center: infra + +ui: + podLabels: + cost-center: frontend +``` + +This is useful for clusters with admission policies (such as OPA Gatekeeper or Kyverno) that require specific labels on every pod template. Note that selector labels always take precedence and cannot be overridden. + +## Default nodeSelector for agent deployments + +A new `controller.agentDeployment.nodeSelector` Helm value sets a global default nodeSelector applied to every agent Deployment created by the controller. Per-agent `nodeSelector` values in the `Agent` CRD take precedence over this default (per-key merge, agent wins). + +```yaml +controller: + agentDeployment: + nodeSelector: + kubernetes.io/os: linux +``` + +This is useful in clusters where admission policies (Gatekeeper, Kyverno) require a `nodeSelector` on every Deployment. Without this, agents created through the UI wizard carry no nodeSelector and fail admission. + +## extraObjects + +A new top-level `extraObjects` Helm value lets you deploy arbitrary Kubernetes manifests in the same chart lifecycle as kagent. Entries are rendered through `tpl`, so they can reference the release context such as `{{ .Release.Namespace }}`. + +```yaml +extraObjects: + - apiVersion: external-secrets.io/v1beta1 + kind: ExternalSecret + metadata: + name: kagent-api-key + namespace: "{{ .Release.Namespace }}" + spec: + refreshInterval: 1h + secretStoreRef: + name: my-store + kind: ClusterSecretStore + target: + name: kagent-api-key + data: + - secretKey: ANTHROPIC_API_KEY + remoteRef: + key: anthropic-api-key +``` + +## Deployment annotations + +You can now add custom annotations to the kagent controller and UI Deployment resources. A global `annotations` map applies to all deployments, with per-component overrides via `controller.annotations` and `ui.annotations`. + +```yaml +controller: + annotations: + cluster-autoscaler.kubernetes.io/safe-to-evict: "false" + +ui: + annotations: + cluster-autoscaler.kubernetes.io/safe-to-evict: "false" +``` + +This is useful for tools that read Deployment annotations such as cluster autoscaler, Datadog, and Karpenter. + +## nodeSelector for agent Helm charts + +Every bundled agent Helm chart now accepts an optional `nodeSelector` value. Use it to constrain agent pods to specific node pools. + +```yaml +# Per-agent chart +nodeSelector: + disktype: ssd +``` + +When installing agents through the parent `kagent` chart, pass the value under the dependency name: + +```yaml +helm-agent: + nodeSelector: + kubernetes.io/os: linux +k8s-agent: + nodeSelector: + kubernetes.io/os: linux +``` + +When unset, `nodeSelector` is omitted entirely, so there is no change for existing deployments. + ## Additional changes in v0.10 * **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. * **Go ADK OpenAI embeddings**: Fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. * **Helm image registry fixes**: Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. +* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now scoped to their Kubernetes namespace (atespace = namespace). Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. +* **Concurrent memory search deadlock fix**: Fixed intermittent PostgreSQL deadlocks when concurrent memory searches (such as `PrefetchMemoryTool` fan-out) updated overlapping rows. Row locks are now acquired in ID order and access-count updates are best-effort. +* **Anthropic thinking blocks in Python ADK**: Google ADK bumped to 1.32.0, enabling Anthropic thinking block support for agents using the Python runtime. +* **Image registry updated to ghcr.io**: The `cr.kagent.dev` registry alias is removed. All default image references now use `ghcr.io/kagent-dev/kagent`. If you pinned images using the `cr.kagent.dev` alias, update your references to `ghcr.io`. +* **Migration orchestrator**: The internal database migration runner is refactored from two hardcoded tracks to an extensible orchestrator with ordered source registration and coordinated rollback. No change to the `kagent db migrate` CLI. +* **Claude ACP sandbox image**: A new `acp-sandbox-claude` image wraps the Claude Agent SDK behind the ACP protocol, enabling Claude-based agents to run in the ACP sandbox alongside the existing openclaw and hermes targets. Authenticate via `ANTHROPIC_API_KEY` at runtime. +* **SandboxAgent readiness gating**: `SandboxAgent` actors are now only marked ready once the agent application is confirmed to be serving traffic, preventing requests from reaching actors that have started but are not yet initialized. +* **Go ADK v2.0.0**: The Go Agent Development Kit is upgraded to v2.0.0. +* **`none` reasoning effort**: `none` is now a valid option for reasoning effort on `ModelConfig`, in addition to the existing `low`, `medium`, and `high` values. +* **Declarative agents referenced by tag**: Regular declarative agent images are now referenced by tag (`registry/repository:tag`) rather than digest, so they respect `IMAGE_TAG` overrides. Digest pinning is kept for sandbox agents where Substrate requires it. New controller flags (`--app-image-digest`, `--golang-adk-image-digest`, and their `-full` variants) let operators override baked-in sandbox digests when using a mirror registry. +* **Configurable cluster DNS domain**: A `clusterDomain` controller setting (default `cluster.local`) makes the in-cluster service URLs configurable for clusters that use a non-standard DNS domain. +* **MCP server startup resilience**: An MCP toolset is no longer silently dropped when an MCP server is unreachable at agent startup. The error is surfaced rather than causing tools to disappear. +* **Agent ready on first available replica**: An agent is now marked ready as soon as at least one replica is available, rather than waiting for all replicas. +* **UI tool call grouping**: Tool calls in the chat interface are now visually grouped, making it easier to follow multi-step agent reasoning. # v0.9 From 505a06bd4308531cdeb17bf6cc76416bd7140479 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 13:28:40 -0500 Subject: [PATCH 08/31] other doc guides Signed-off-by: Rachael Graham --- .../kagent/concepts/agent-substrate/page.mdx | 2 + src/app/docs/kagent/concepts/agents/page.mdx | 2 +- .../kagent/introduction/installation/page.mdx | 78 +++++++++++++++++++ .../kagent/observability/launch-ui/page.mdx | 52 +++++++++++++ .../operational-considerations/page.mdx | 37 +++++++++ .../kagent/resources/release-notes/page.mdx | 42 +++++----- .../supported-providers/openai/page.mdx | 14 ++++ 7 files changed, 206 insertions(+), 21 deletions(-) diff --git a/src/app/docs/kagent/concepts/agent-substrate/page.mdx b/src/app/docs/kagent/concepts/agent-substrate/page.mdx index 8a3e1364..523382da 100644 --- a/src/app/docs/kagent/concepts/agent-substrate/page.mdx +++ b/src/app/docs/kagent/concepts/agent-substrate/page.mdx @@ -65,6 +65,8 @@ Agent Substrate is composed of a control plane, a data plane, and snapshot stora Run a declarative agent on Agent Substrate by creating a `SandboxAgent` resource. It carries the same spec as a regular `Agent`, but the kagent controller runs it as a sandboxed workload on the runtime instead of a plain Deployment. All three declarative runtimes are supported: **Go** (default), **Python**, and **BYO**. +Session history for Go and Python declarative sandbox agents is persisted to a local SQLite database backed by the agent's `durableDir` volume, so conversation state survives pod restarts and Deployment rollouts. Session metadata is mirrored to PostgreSQL to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store. + ### AgentHarness An `AgentHarness` always runs on Agent Substrate; `spec.substrate` is required. The key fields are: diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 91d3e533..bcfd6d2a 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -300,7 +300,7 @@ Compaction removes older conversation events to free up space in the context win ## Sandboxed Agents -You can run a declarative agent in an isolated sandbox by creating a `SandboxAgent` resource instead of a regular `Agent`. A `SandboxAgent` runs on [Agent Substrate](/docs/kagent/concepts/agent-substrate): the kagent controller runs it as a gVisor-sandboxed actor instead of a Deployment, snapshotting it to object storage when idle and rehydrating it on demand. The spec mirrors the `Agent` spec, with a few constraints: sandboxed agents always use the Go ADK runtime, and `spec.skills` and `BYO` agents are not supported. Configure substrate placement with the optional `spec.substrate` field (for example, `workerPoolRef`). +You can run a declarative agent in an isolated sandbox by creating a `SandboxAgent` resource instead of a regular `Agent`. A `SandboxAgent` runs on [Agent Substrate](/docs/kagent/concepts/agent-substrate): the kagent controller runs it as a gVisor-sandboxed actor instead of a Deployment, snapshotting it to object storage when idle and rehydrating it on demand. The spec mirrors the `Agent` spec. All three runtimes are supported: **Go** (default), **Python**, and **BYO**. Session history is persisted to a local SQLite database in the agent's `durableDir` volume, so conversation state survives pod restarts and Deployment rollouts. Configure substrate placement with the optional `spec.substrate` field (for example, `workerPoolRef`). For setup steps, see the [Agent Substrate example](/docs/kagent/examples/agent-substrate). diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index c31bce32..544f71db 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -317,6 +317,84 @@ controller: This example loads all key-value pairs from the `controller-secrets` secret as environment variables in the controller pod. +### Customize Kubernetes resources + +Use the following Helm values to meet cluster admission policies or integrate with external tooling. + +#### Pod labels + +Add labels to the pod templates of the controller and UI Deployments. Pod labels can be useful for clusters with policies (OPA Gatekeeper, Kyverno) that require specific labels on every pod. + +A global `podLabels` map applies to all component pods; per-component values override it: + +```yaml +podLabels: + team: platform + +controller: + podLabels: + cost-center: infra + +ui: + podLabels: + cost-center: frontend +``` + +To add labels to all **agent** pods, use `controller.agentDeployment.podLabels`. + +#### Deployment annotations + +Add annotations to the controller and UI Deployment resources. For example, to add annotations for cluster autoscaler or Datadog: + +```yaml +controller: + annotations: + cluster-autoscaler.kubernetes.io/safe-to-evict: "false" + +ui: + annotations: + cluster-autoscaler.kubernetes.io/safe-to-evict: "false" +``` + +To add annotations to the controller **Service** (for AWS Load Balancer Controller or ExternalDNS), use `controller.service.annotations`. + +#### Default nodeSelector for agent deployments + +Set a default `nodeSelector` that is applied to every agent Deployment that the controller creates. This setting can be useful when admission policies require a `nodeSelector` on all Deployments, since agents created through the UI carry none by default. + +```yaml +controller: + agentDeployment: + nodeSelector: + kubernetes.io/os: linux +``` + +Per-agent `nodeSelector` values in the `Agent` spec take precedence over this default. + +#### Deploy companion resources with extraObjects + +Use `extraObjects` to deploy arbitrary Kubernetes manifests in the same Helm chart lifecycle as kagent. Entries are rendered through `tpl`, so they can reference the release context. + +```yaml +extraObjects: + - apiVersion: external-secrets.io/v1beta1 + kind: ExternalSecret + metadata: + name: kagent-api-key + namespace: "{{ .Release.Namespace }}" + spec: + refreshInterval: 1h + secretStoreRef: + name: my-store + kind: ClusterSecretStore + target: + name: kagent-api-key + data: + - secretKey: ANTHROPIC_API_KEY + remoteRef: + key: anthropic-api-key +``` + ## Uninstallation Refer to the [Uninstall](/docs/kagent/operations/uninstall) guide. diff --git a/src/app/docs/kagent/observability/launch-ui/page.mdx b/src/app/docs/kagent/observability/launch-ui/page.mdx index 4b740811..ae0e82c0 100644 --- a/src/app/docs/kagent/observability/launch-ui/page.mdx +++ b/src/app/docs/kagent/observability/launch-ui/page.mdx @@ -54,6 +54,58 @@ If you prefer to manually set up port-forwarding, or if you're on a platform whe 3. When you're done, stop the port-forward by pressing `Ctrl+C` in the terminal where the port-forward is running. +## Expose the UI outside the cluster + +Port-forwarding is suitable for local access. For persistent or team-accessible deployments, use one of the following options. + +### LoadBalancer service + +Set `ui.service.type: LoadBalancer` in your Helm values to provision a cloud load balancer for the UI service. + +```yaml +ui: + service: + type: LoadBalancer +``` + +After the load balancer is provisioned, get the external IP or hostname from the service. + +```bash +kubectl get svc -n kagent kagent-ui +``` + +### OpenShift Route + +On OpenShift clusters, kagent automatically creates an edge-terminated `Route` for the UI when the `route.openshift.io/v1` API is present. The route is enabled by default via `ui.route.enabled: true`. + +The default HAProxy timeout is overridden to 120 minutes to prevent long-lived A2A and SSE streams from being terminated. To adjust the timeout: + +```yaml +ui: + openshiftRoute: + annotations: + haproxy.router.openshift.io/timeout: 60m +``` + +To disable the auto-created Route and front the UI with your own ingress instead, set `ui.route.enabled: false`. + +### Gateway API HTTPRoute + +If your cluster uses a Gateway API implementation such as kgateway, Istio, or Envoy Gateway, you can enable a `HTTPRoute` for the UI with `ui.httpRoute.enabled: true`. + +```yaml +ui: + httpRoute: + enabled: true + parentRefs: + - name: my-gateway + namespace: gateway-system + hostnames: + - kagent.example.com +``` + +The `parentRefs` field is required and must reference an existing `Gateway`. The `HTTPRoute` resource requires the Gateway API CRDs (`gateway.networking.k8s.io/v1`) to be installed in your cluster. + ## Next steps You can use the UI to view and manage your agents, tools, and models. For more information, see the following guides: diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index 4e43ed9d..e809a64b 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -225,6 +225,43 @@ spec: ``` +## Long-running connections + +Agents that run multi-step tasks or stream results over SSE can take minutes or longer to respond. To ensure that long-running sessions work correctly from end to end, tune the following timeout values together. + +### Streaming timeouts + +The UI uses nginx as a sidecar proxy and a client-side EventSource for streaming. Both have independent inactivity timeouts that default to 1800 seconds (30 minutes). + +| Helm value | Default | Description | +|---|---|---| +| `ui.streamTimeoutSeconds` | `1800` | Client-side EventSource inactivity timeout. | +| `ui.nginx.proxyReadTimeout` | `1800s` | nginx `proxy_read_timeout` — max time between successive reads from the upstream. | +| `ui.nginx.proxySendTimeout` | `1800s` | nginx `proxy_send_timeout` — max time between successive writes to the upstream. | + +To ensure that the nginx proxy is not the silent limit, set `ui.streamTimeoutSeconds` to a value greater than or equal to `ui.nginx.proxyReadTimeout`. For example, to support 2-hour sessions: + +```yaml +ui: + streamTimeoutSeconds: 7200 + nginx: + proxyReadTimeout: 7200s + proxySendTimeout: 7200s +``` + +On OpenShift, also set the HAProxy route timeout via `ui.openshiftRoute.annotations`. For more information, see [Expose the UI outside the cluster](/docs/kagent/observability/launch-ui#expose-the-ui-outside-the-cluster). + +### A2A client timeout + +When one agent calls another agent as a tool over the A2A protocol, the request uses an HTTP client with a configurable timeout. The default is no timeout (`""`), which replaced a previous hard-coded 3-minute limit. + +If you need to enforce a ceiling on A2A call duration, set `controller.a2aClientTimeout`: + +```yaml +controller: + a2aClientTimeout: "10m" # empty string = no timeout (default) +``` + ## Proxy configuration for agent traffic When agents and MCP servers run behind an API gateway or proxy, you can configure kagent to route agent-to-agent and agent-to-MCP traffic through that proxy. Set `proxy.url` in your Helm values to the proxy endpoint. diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index fe332706..24573dd9 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -24,24 +24,24 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. **What's included:** -* Go ADK is now the default runtime: New declarative agents use the Go ADK by default. -* A2A AgentCard metadata: New optional fields on the Agent spec for enriching the A2A AgentCard. -* Configurable streaming timeouts: Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. -* Controller service annotations: `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. -* ACP protocol support for substrate agents: ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. -* Chat session sharing: Session owners can generate shareable links in read-only or read-write mode. -* Substrate support for BYO and Python agents: `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. -* Configurable A2A client timeout: `controller.a2aClientTimeout` removes the previous 3-minute hard cutoff for long-running agents. -* SSO session expiry re-authentication: Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. -* Out-of-band database migrations: Manage database migrations via the kagent CLI independently of controller startup. -* Deployment annotations: `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. -* nodeSelector for agent Helm charts: Pin agent pods to specific node pools via `nodeSelector` in every bundled agent Helm chart. -* Durable session state for sandbox agents: Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and config rollouts. -* UI HTTPRoute: Optional Gateway API `HTTPRoute` for the UI, for use with kgateway, Istio, or Envoy Gateway. -* MCP App chat widgets: MCP tools that expose UI resources now render interactive widgets inline in the chat interface. -* Pod labels for controller and UI: `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. -* extraObjects: Deploy arbitrary Kubernetes manifests alongside kagent in the same chart lifecycle via `extraObjects`. -* Default nodeSelector for agent deployments: `controller.agentDeployment.nodeSelector` applies a global default nodeSelector to all agent Deployments created by the controller. +* [Go ADK is now the default runtime](#go-adk-is-now-the-default-runtime): New declarative agents use the Go ADK by default. +* [A2A AgentCard metadata](#a2a-agentcard-metadata): New optional fields on the Agent spec for enriching the A2A AgentCard. +* [Configurable streaming timeouts](#configurable-streaming-timeouts): New Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. +* [Controller service annotations](#controller-service-annotations): New `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. +* [ACP protocol support for substrate agents](#acp-protocol-support-for-substrate-agents): New ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. +* [Chat session sharing](#chat-session-sharing): Session owners can now generate shareable links in read-only or read-write mode. +* [Substrate support for BYO and Python agents](#substrate-support-for-byo-and-python-agents): `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. +* [Configurable A2A client timeout](#configurable-a2a-client-timeout): New `controller.a2aClientTimeout` Helm value removes the previous 3-minute hard cutoff for long-running agents. +* [SSO session expiry re-authentication](#sso-session-expiry-re-authentication): Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. +* [Out-of-band database migrations](#out-of-band-database-migrations): New `kagent db migrate` CLI and `database.postgres.skipMigrations` Helm value for managing migrations independently of controller startup. +* [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. +* [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. +* [Durable session state for sandbox agents](#durable-session-state-for-sandbox-agents): Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and config rollouts. +* [UI HTTPRoute](#ui-httproute): New `ui.httpRoute` Helm value for fronting the UI with a Gateway API HTTPRoute (kgateway, Istio, Envoy Gateway). +* [MCP App chat widgets](#mcp-app-chat-widgets): MCP tools that expose UI resources now render interactive widgets inline in the chat interface. +* [Pod labels for controller and UI](#pod-labels-for-controller-and-ui): New `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. +* [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. +* [Default nodeSelector for agent deployments](#default-nodeselector-for-agent-deployments): New `controller.agentDeployment.nodeSelector` Helm value applies a global default nodeSelector to all agent Deployments created by the controller. ## Go ADK is now the default runtime @@ -166,7 +166,7 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op ## Durable session state for sandbox agents -Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and config rollouts — a previous conversation continues seamlessly after a Deployment rollout triggered by a prompt change, for example. +Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and config rollouts. For example, a previous conversation continues seamlessly after a Deployment rollout triggered by a prompt change. Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. @@ -174,7 +174,7 @@ You can override the session database endpoint with the `KAGENT_SESSION_DB_URL` ## UI HTTPRoute -The kagent UI can now be fronted by a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) `HTTPRoute` instead of a plain `Ingress` or OpenShift `Route`. This is useful when your cluster uses kgateway, Istio, or Envoy Gateway as its traffic management layer. +You can now front the kagent UI by a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) `HTTPRoute` instead of a plain `Ingress` or OpenShift `Route`. This is useful when your cluster uses kgateway, Istio, or Envoy Gateway as its traffic management layer. The HTTPRoute is off by default. Enable it with `ui.httpRoute.enabled: true` and configure `parentRefs` and `hostnames`: @@ -189,6 +189,8 @@ ui: - kagent.example.com ``` +For all UI exposure options including LoadBalancer service and OpenShift Route, see [Expose the UI outside the cluster](/docs/kagent/observability/launch-ui#expose-the-ui-outside-the-cluster). + ## MCP App chat widgets MCP tools that expose UI resources (MCP Apps) now render interactive widgets inline in the kagent chat interface. When an agent calls such a tool, the response appears as an embedded widget rather than raw text, and users can interact with it directly in the chat window. The backend compacts MCP App tool responses sent to the model to prevent redundant repeated calls. diff --git a/src/app/docs/kagent/supported-providers/openai/page.mdx b/src/app/docs/kagent/supported-providers/openai/page.mdx index c5855bde..0f2fd6be 100644 --- a/src/app/docs/kagent/supported-providers/openai/page.mdx +++ b/src/app/docs/kagent/supported-providers/openai/page.mdx @@ -40,3 +40,17 @@ For OpenAI's standard models like GPT-4 and GPT-3.5, kagent automatically config 3. Apply the above resource to the cluster. Once the resource is applied, you can select the model from the Model dropdown in the UI when creating or updating agents. + +## Reasoning effort + +For OpenAI reasoning models (o-series, GPT-5), you can control how many reasoning tokens the model generates before producing a response with the `openAI.reasoningEffort` field. Valid values are `none`, `minimal`, `low`, `medium`, and `high`. + +For models that require reasoning to be explicitly disabled (such as some GPT-5 variants), set `reasoningEffort: none`. For standard models that do not support it, omit the field. + +```yaml +spec: + provider: OpenAI + model: o3 + openAI: + reasoningEffort: medium +``` From 731300dda819e216ec7e3e3f37772823c2f07d90 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 13:40:07 -0500 Subject: [PATCH 09/31] links Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 24573dd9..5b0581e1 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -95,6 +95,8 @@ ui: haproxy.router.openshift.io/timeout: 120m ``` +For tuning timeouts end-to-end for long-running agent sessions, see [Long-running connections](/docs/kagent/operations/operational-considerations#long-running-connections). + ## Controller service annotations You can now add custom annotations to the kagent controller's Kubernetes Service via `controller.service.annotations`. This is useful for integrations such as AWS Load Balancer Controller and ExternalDNS. @@ -111,6 +113,8 @@ controller: kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with OpenClaw and Hermes to communicate over the substrate runtime without additional configuration. +For more information, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). + ## Chat session sharing Session owners can now generate shareable links for any chat session. Shared sessions support two modes: @@ -135,6 +139,8 @@ controller: a2aClientTimeout: "10m" # or "" for no timeout (default) ``` +For more information, see [Long-running connections](/docs/kagent/operations/operational-considerations#long-running-connections). + ## SSO session expiry re-authentication When deployed behind an OIDC proxy (such as oauth2-proxy), expired sessions now trigger an automatic redirect to `/oauth2/start` for re-authentication instead of showing an error. A loop guard prevents infinite redirects if re-authentication fails. Sessions in unsecured (no-proxy) mode are unaffected. @@ -172,6 +178,8 @@ Session metadata is mirrored to the PostgreSQL database to support session-listi You can override the session database endpoint with the `KAGENT_SESSION_DB_URL` environment variable. +For more information, see [Agent Substrate — Declarative agents](/docs/kagent/concepts/agent-substrate#declarative-agents). + ## UI HTTPRoute You can now front the kagent UI by a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) `HTTPRoute` instead of a plain `Ingress` or OpenShift `Route`. This is useful when your cluster uses kgateway, Istio, or Envoy Gateway as its traffic management layer. @@ -215,6 +223,8 @@ ui: This is useful for clusters with admission policies (such as OPA Gatekeeper or Kyverno) that require specific labels on every pod template. Note that selector labels always take precedence and cannot be overridden. +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## Default nodeSelector for agent deployments A new `controller.agentDeployment.nodeSelector` Helm value sets a global default nodeSelector applied to every agent Deployment created by the controller. Per-agent `nodeSelector` values in the `Agent` CRD take precedence over this default (per-key merge, agent wins). @@ -228,6 +238,8 @@ controller: This is useful in clusters where admission policies (Gatekeeper, Kyverno) require a `nodeSelector` on every Deployment. Without this, agents created through the UI wizard carry no nodeSelector and fail admission. +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## extraObjects A new top-level `extraObjects` Helm value lets you deploy arbitrary Kubernetes manifests in the same chart lifecycle as kagent. Entries are rendered through `tpl`, so they can reference the release context such as `{{ .Release.Namespace }}`. @@ -252,6 +264,8 @@ extraObjects: key: anthropic-api-key ``` +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## Deployment annotations You can now add custom annotations to the kagent controller and UI Deployment resources. A global `annotations` map applies to all deployments, with per-component overrides via `controller.annotations` and `ui.annotations`. @@ -268,6 +282,8 @@ ui: This is useful for tools that read Deployment annotations such as cluster autoscaler, Datadog, and Karpenter. +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## nodeSelector for agent Helm charts Every bundled agent Helm chart now accepts an optional `nodeSelector` value. Use it to constrain agent pods to specific node pools. @@ -310,6 +326,13 @@ When unset, `nodeSelector` is omitted entirely, so there is no change for existi * **MCP server startup resilience**: An MCP toolset is no longer silently dropped when an MCP server is unreachable at agent startup. The error is surfaced rather than causing tools to disappear. * **Agent ready on first available replica**: An agent is now marked ready as soon as at least one replica is available, rather than waiting for all replicas. * **UI tool call grouping**: Tool calls in the chat interface are now visually grouped, making it easier to follow multi-step agent reasoning. +* **oauth2-proxy subchart updated to ~10.7.0**: The bundled oauth2-proxy dependency is bumped to the 10.7.x chart series. +* **Model config name editing fix**: Fixed an issue where the model name field could not be edited on the model configuration form in the UI. +* **`kgateway.dev/a2a` appProtocol for BYO agents**: The controller now sets `kgateway.dev/a2a` as the `appProtocol` on the Service for BYO agents, which is required for A2A routing to work correctly in kgateway environments. +* **Azure OpenAI secretKeyRef fix**: Fixed an issue where an empty `secretKeyRef` was generated for Azure OpenAI model configurations that do not use a Kubernetes secret for credentials. +* **`nodeSelector` and `tolerations` for `kagent-tools` subchart**: The `kagent-tools` bundled subchart now accepts `nodeSelector` and `tolerations` values, so tools pods can be placed on specific nodes or tolerate taints. +* **Python ADK minimum version is now 3.11**: The Python Agent Development Kit now requires Python 3.11 or later. +* **Agent Substrate bumped to v0.0.9**: The bundled Agent Substrate runtime is updated to v0.0.9. # v0.9 From 0607b9387ab26e1a5990e3f34fc81872407ace01 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 14:59:15 -0500 Subject: [PATCH 10/31] beta10 Signed-off-by: Rachael Graham --- .../kagent/introduction/installation/page.mdx | 33 +++++++++++++++++++ .../docs/kagent/operations/upgrade/page.mdx | 2 ++ .../kagent/resources/release-notes/page.mdx | 28 ++++++++++++++++ 3 files changed, 63 insertions(+) diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 544f71db..1dbfa152 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -395,6 +395,39 @@ extraObjects: key: anthropic-api-key ``` +### Private registry and image mirroring + +If your cluster cannot pull from `ghcr.io` directly, such as in air-gapped environments, corporate proxies, or mandatory image scanning, you can mirror the kagent images to an internal registry and configure the chart to pull from the registry. + +kagent uses three independently configurable image locations: + +| Helm value | Default image | Description | +|---|---|---| +| `image.registry` | `ghcr.io` | Global registry prefix applied to all images that do not set their own registry. | +| `controller.agentImage` | `ghcr.io/kagent-dev/kagent/app` | Python ADK runtime image used for Python and BYO declarative agents. | +| `controller.goAgentImage` | `ghcr.io/kagent-dev/kagent/golang-adk` | Go ADK runtime image used for Go declarative agents. Must be set separately from `agentImage`. | + +To redirect all images to an internal mirror, set `image.registry` to your registry and override both agent images: + +```yaml +image: + registry: my-registry.example.com + +controller: + agentImage: + registry: my-registry.example.com + repository: kagent/app + tag: v0.10.0 + goAgentImage: + registry: my-registry.example.com + repository: kagent/golang-adk + tag: v0.10.0 +``` + +When unset, the `registry` and `pullPolicy` fields of `agentImage` and `goAgentImage` default to the global `image.registry` and `image.pullPolicy` values. For many mirror setups, setting only `image.registry` and overriding `repository` and `tag` on each image is sufficient. + +> **Note**: If you set only `agentImage` without also setting `controller.goAgentImage`, Go declarative agents still try to pull the Go ADK image from its default location, `ghcr.io`. The controller logs a startup warning when the two image registries differ. + ## Uninstallation Refer to the [Uninstall](/docs/kagent/operations/uninstall) guide. diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index e28b1b58..2d3f757c 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -35,6 +35,8 @@ Follow these steps to upgrade kagent to the latest version and keep your cluster 4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9-specific upgrades related to database migrations and RBAC scope. +5. **v0.10.0 and later — mirror registry operators**: If you mirror kagent images and previously relied on `agentImage` alone, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. In v0.10, the controller no longer derives the Go image location from the Python image path. If `controller.goAgentImage` is unset and you overrode `agentImage`, the controller will fall back to pulling `ghcr.io/kagent-dev/kagent/golang-adk` directly. The controller logs a startup warning when the two registries differ. For details, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). + ## Upgrade kagent 1. Get the Helm values file for your current kagent release. diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 5b0581e1..b30b236a 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -42,6 +42,7 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [Pod labels for controller and UI](#pod-labels-for-controller-and-ui): New `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. * [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. * [Default nodeSelector for agent deployments](#default-nodeselector-for-agent-deployments): New `controller.agentDeployment.nodeSelector` Helm value applies a global default nodeSelector to all agent Deployments created by the controller. +* [Configurable Go ADK agent image](#configurable-go-adk-agent-image): New `controller.goAgentImage` Helm values configure the Go ADK runtime image independently, fixing mirror registry layouts that the previous derivation could not produce. ## Go ADK is now the default runtime @@ -124,6 +125,8 @@ Session owners can now generate shareable links for any chat session. Shared ses Shared sessions that a user has accessed appear in their sidebar alongside their own sessions, so recipients do not need to keep the original link to return. Agents can also generate and revoke share links as part of their own workflows. +Read-only share tokens can also read A2A tasks on the shared session (`ListTasks`, `GetTask`, `SubscribeToTask`). Mutating operations (`SendMessage`, `CancelTask`) still require a read-write share token. + ## Substrate support for BYO and Python agents `SandboxAgent` now supports running BYO agents and Python runtime declarative agents on Agent Substrate, in addition to Go declarative agents. This means any `Agent` type can be run as a sandboxed substrate workload. @@ -307,6 +310,25 @@ k8s-agent: When unset, `nodeSelector` is omitted entirely, so there is no change for existing deployments. +## Configurable Go ADK agent image + +You can now use the `controller.goAgentImage` Helm values to configure the Go ADK runtime image independently of the main agent image. Previously, the controller derived the Go image repository from the Python image by replacing the last path segment with `golang-adk`. This pattern breaks in flat-name mirror registries where the image name cannot be produced by that derivation. + +```yaml +controller: + goAgentImage: + registry: my-registry.io + repository: kagent/golang-adk + tag: v0.10.0 + pullPolicy: IfNotPresent +``` + +The `registry` and `pullPolicy` fields default to the global `image.registry` and `image.pullPolicy` values. The `tag` coalesces to the global image tag, then the chart version. + +> **Breaking change for mirror registry operators**: If you mirror kagent images and only set `agentImage`, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. The controller logs a startup warning when the Go image registry differs from the main image registry, so that a misconfigured mirror is visible before a Go agent fails to pull. + +For more information, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). + ## Additional changes in v0.10 * **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. @@ -333,6 +355,12 @@ When unset, `nodeSelector` is omitted entirely, so there is no change for existi * **`nodeSelector` and `tolerations` for `kagent-tools` subchart**: The `kagent-tools` bundled subchart now accepts `nodeSelector` and `tolerations` values, so tools pods can be placed on specific nodes or tolerate taints. * **Python ADK minimum version is now 3.11**: The Python Agent Development Kit now requires Python 3.11 or later. * **Agent Substrate bumped to v0.0.9**: The bundled Agent Substrate runtime is updated to v0.0.9. +* **Custom annotations on the default ModelConfig**: A new per-provider `annotations` map under `providers..annotations` is applied to the Helm-generated default ModelConfig. Useful for downstream tooling or UI extensions that key off resource annotations. +* **Memory vector search normalization**: Agent names are now normalized before querying the memory vector index, fixing cases where a name stored in mixed case would miss records indexed under a different casing. +* **Bedrock nil tool-call args fix**: Nil tool-call arguments from the Bedrock API are now coerced to an empty JSON object before processing, preventing a nil-pointer panic in the Go ADK runtime. +* **Azure OpenAI API key env var name**: The `AZURE_OPENAI_API_KEY` environment variable name is now used consistently throughout the codebase, fixing providers that were reading a mismatched key name. +* **OpenTelemetry double-instrumentation fix**: The OpenAI client is no longer double-instrumented on the Go ADK runtime, preventing duplicate spans in OTel traces when using OpenAI with the Go runtime. +* **UI rendering optimization**: Redundant background fetches in the chat interface are reduced, improving rendering performance for long sessions. # v0.9 From 4c07f90c3dddb24b40243125fe2e808bdce938c8 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Mon, 27 Jul 2026 15:07:26 -0500 Subject: [PATCH 11/31] beta11 Signed-off-by: Rachael Graham --- .../kagent/introduction/installation/page.mdx | 16 +++ .../kagent/resources/release-notes/page.mdx | 98 +++++++++++++++---- .../supported-providers/openai/page.mdx | 19 +++- 3 files changed, 113 insertions(+), 20 deletions(-) diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 1dbfa152..0242b9e0 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -342,6 +342,22 @@ ui: To add labels to all **agent** pods, use `controller.agentDeployment.podLabels`. +#### ServiceAccount annotations + +Add annotations to the controller and UI ServiceAccount resources. These annotations are required for cloud-provider workload identity integrations (GCP Workload Identity, AWS IRSA, Azure Workload Identity) that grant IAM permissions to workloads by annotating their Kubernetes ServiceAccount. + +```yaml +controller: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent@my-project.iam.gserviceaccount.com + +ui: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent-ui@my-project.iam.gserviceaccount.com +``` + #### Deployment annotations Add annotations to the controller and UI Deployment resources. For example, to add annotations for cluster autoscaler or Datadog: diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index b30b236a..638587ea 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -43,6 +43,8 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. * [Default nodeSelector for agent deployments](#default-nodeselector-for-agent-deployments): New `controller.agentDeployment.nodeSelector` Helm value applies a global default nodeSelector to all agent Deployments created by the controller. * [Configurable Go ADK agent image](#configurable-go-adk-agent-image): New `controller.goAgentImage` Helm values configure the Go ADK runtime image independently, fixing mirror registry layouts that the previous derivation could not produce. +* [Max completion tokens for OpenAI](#max-completion-tokens-for-openai): New `openAI.maxCompletionTokens` field for capping output on reasoning models (o-series, GPT-5), which reject the deprecated `maxTokens` field. +* [ServiceAccount annotations](#serviceaccount-annotations): New `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations` Helm values for cloud workload identity integrations (GCP, AWS IRSA, Azure). ## Go ADK is now the default runtime @@ -329,37 +331,95 @@ The `registry` and `pullPolicy` fields default to the global `image.registry` an For more information, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). +## Max completion tokens for OpenAI + +OpenAI reasoning models (o-series, GPT-5) reject the `max_tokens` request parameter with a 400 error. Use the new `openAI.maxCompletionTokens` field instead, which maps to OpenAI's `max_completion_tokens` parameter and caps both visible output tokens and internal reasoning tokens. + +```yaml +spec: + provider: OpenAI + model: o3 + openAI: + reasoningEffort: medium + maxCompletionTokens: 16000 +``` + +The existing `openAI.maxTokens` field is unchanged and continues to work for standard models and OpenAI-compatible endpoints. The two fields are independent: set `maxCompletionTokens` for reasoning models and `maxTokens` only for endpoints that still require `max_tokens`. + +For more information, see [Max completion tokens](/docs/kagent/supported-providers/openai#max-completion-tokens). + +## ServiceAccount annotations + +You can now annotate the controller and UI Kubernetes ServiceAccounts via `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations`. This standard mechanism is required for cloud-provider workload identity integrations that grant IAM permissions by annotating a ServiceAccount. + +```yaml +controller: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent@my-project.iam.gserviceaccount.com + +ui: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent-ui@my-project.iam.gserviceaccount.com +``` + +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## Additional changes in v0.10 +**Security** + * **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. -* **Go ADK OpenAI embeddings**: Fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. -* **Helm image registry fixes**: Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. -* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now scoped to their Kubernetes namespace (atespace = namespace). Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. -* **Concurrent memory search deadlock fix**: Fixed intermittent PostgreSQL deadlocks when concurrent memory searches (such as `PrefetchMemoryTool` fan-out) updated overlapping rows. Row locks are now acquired in ID order and access-count updates are best-effort. -* **Anthropic thinking blocks in Python ADK**: Google ADK bumped to 1.32.0, enabling Anthropic thinking block support for agents using the Python runtime. +* **A2A task security scoping**: Task `get`, `create`, and `delete` operations are now scoped to the session owner, preventing one user from accessing another user's A2A tasks. + +**Helm and configuration** + * **Image registry updated to ghcr.io**: The `cr.kagent.dev` registry alias is removed. All default image references now use `ghcr.io/kagent-dev/kagent`. If you pinned images using the `cr.kagent.dev` alias, update your references to `ghcr.io`. -* **Migration orchestrator**: The internal database migration runner is refactored from two hardcoded tracks to an extensible orchestrator with ordered source registration and coordinated rollback. No change to the `kagent db migrate` CLI. -* **Claude ACP sandbox image**: A new `acp-sandbox-claude` image wraps the Claude Agent SDK behind the ACP protocol, enabling Claude-based agents to run in the ACP sandbox alongside the existing openclaw and hermes targets. Authenticate via `ANTHROPIC_API_KEY` at runtime. -* **SandboxAgent readiness gating**: `SandboxAgent` actors are now only marked ready once the agent application is confirmed to be serving traffic, preventing requests from reaching actors that have started but are not yet initialized. -* **Go ADK v2.0.0**: The Go Agent Development Kit is upgraded to v2.0.0. -* **`none` reasoning effort**: `none` is now a valid option for reasoning effort on `ModelConfig`, in addition to the existing `low`, `medium`, and `high` values. +* **Helm image registry fixes**: Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. * **Declarative agents referenced by tag**: Regular declarative agent images are now referenced by tag (`registry/repository:tag`) rather than digest, so they respect `IMAGE_TAG` overrides. Digest pinning is kept for sandbox agents where Substrate requires it. New controller flags (`--app-image-digest`, `--golang-adk-image-digest`, and their `-full` variants) let operators override baked-in sandbox digests when using a mirror registry. * **Configurable cluster DNS domain**: A `clusterDomain` controller setting (default `cluster.local`) makes the in-cluster service URLs configurable for clusters that use a non-standard DNS domain. -* **MCP server startup resilience**: An MCP toolset is no longer silently dropped when an MCP server is unreachable at agent startup. The error is surfaced rather than causing tools to disappear. -* **Agent ready on first available replica**: An agent is now marked ready as soon as at least one replica is available, rather than waiting for all replicas. -* **UI tool call grouping**: Tool calls in the chat interface are now visually grouped, making it easier to follow multi-step agent reasoning. -* **oauth2-proxy subchart updated to ~10.7.0**: The bundled oauth2-proxy dependency is bumped to the 10.7.x chart series. -* **Model config name editing fix**: Fixed an issue where the model name field could not be edited on the model configuration form in the UI. * **`kgateway.dev/a2a` appProtocol for BYO agents**: The controller now sets `kgateway.dev/a2a` as the `appProtocol` on the Service for BYO agents, which is required for A2A routing to work correctly in kgateway environments. -* **Azure OpenAI secretKeyRef fix**: Fixed an issue where an empty `secretKeyRef` was generated for Azure OpenAI model configurations that do not use a Kubernetes secret for credentials. * **`nodeSelector` and `tolerations` for `kagent-tools` subchart**: The `kagent-tools` bundled subchart now accepts `nodeSelector` and `tolerations` values, so tools pods can be placed on specific nodes or tolerate taints. -* **Python ADK minimum version is now 3.11**: The Python Agent Development Kit now requires Python 3.11 or later. -* **Agent Substrate bumped to v0.0.9**: The bundled Agent Substrate runtime is updated to v0.0.9. +* **oauth2-proxy subchart updated to ~10.7.0**: The bundled oauth2-proxy dependency is bumped to the 10.7.x chart series. * **Custom annotations on the default ModelConfig**: A new per-provider `annotations` map under `providers..annotations` is applied to the Helm-generated default ModelConfig. Useful for downstream tooling or UI extensions that key off resource annotations. -* **Memory vector search normalization**: Agent names are now normalized before querying the memory vector index, fixing cases where a name stored in mixed case would miss records indexed under a different casing. + +**Agent runtimes and providers** + +* **Go ADK v2.0.0**: The Go Agent Development Kit is upgraded to v2.0.0. +* **Anthropic thinking blocks in Python ADK**: Google ADK bumped to 1.32.0, enabling Anthropic thinking block support for agents using the Python runtime. +* **Go ADK OpenAI embeddings**: Fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. +* **Python ADK minimum version is now 3.11**: The Python Agent Development Kit now requires Python 3.11 or later. +* **Claude ACP sandbox image**: A new `acp-sandbox-claude` image wraps the Claude Agent SDK behind the ACP protocol, enabling Claude-based agents to run in the ACP sandbox alongside the existing openclaw and hermes targets. Authenticate via `ANTHROPIC_API_KEY` at runtime. +* **`none` reasoning effort**: `none` is now a valid option for reasoning effort on `ModelConfig`, in addition to the existing `low`, `medium`, and `high` values. +* **`xhigh` reasoning effort**: `xhigh` is now a valid value for `openAI.reasoningEffort`, in addition to `none`, `minimal`, `low`, `medium`, and `high`. * **Bedrock nil tool-call args fix**: Nil tool-call arguments from the Bedrock API are now coerced to an empty JSON object before processing, preventing a nil-pointer panic in the Go ADK runtime. +* **Azure OpenAI secretKeyRef fix**: Fixed an issue where an empty `secretKeyRef` was generated for Azure OpenAI model configurations that do not use a Kubernetes secret for credentials. * **Azure OpenAI API key env var name**: The `AZURE_OPENAI_API_KEY` environment variable name is now used consistently throughout the codebase, fixing providers that were reading a mismatched key name. * **OpenTelemetry double-instrumentation fix**: The OpenAI client is no longer double-instrumented on the Go ADK runtime, preventing duplicate spans in OTel traces when using OpenAI with the Go runtime. + +**Agent Substrate** + +* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now scoped to their Kubernetes namespace (atespace = namespace). Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. +* **SandboxAgent readiness gating**: `SandboxAgent` actors are now only marked ready once the agent application is confirmed to be serving traffic, preventing requests from reaching actors that have started but are not yet initialized. +* **Agent Substrate bumped to v0.0.9**: The bundled Agent Substrate runtime is updated to v0.0.9. +* **Substrate badge on agent cards**: Sandbox agents running on Agent Substrate are now visually marked in the UI agent card list. +* **OTel trace flush for substrate agents**: Trace spans are now force-flushed before the A2A response completes for substrate agents, ensuring spans are not lost at the end of a session. + +**Database** + +* **Migration orchestrator**: The internal database migration runner is refactored from two hardcoded tracks to an extensible orchestrator with ordered source registration and coordinated rollback. No change to the `kagent db migrate` CLI. +* **Concurrent memory search deadlock fix**: Fixed intermittent PostgreSQL deadlocks when concurrent memory searches (such as `PrefetchMemoryTool` fan-out) updated overlapping rows. Row locks are now acquired in ID order and access-count updates are best-effort. +* **Memory vector search normalization**: Agent names are now normalized before querying the memory vector index, fixing cases where a name stored in mixed case would miss records indexed under a different casing. +* **Database checkpoint write performance**: Session checkpoint writes are now batched, removing an N+1 query pattern that caused performance degradation for long conversations. + +**Reliability and UI** + +* **MCP server startup resilience**: An MCP toolset is no longer silently dropped when an MCP server is unreachable at agent startup. The error is surfaced rather than causing tools to disappear. +* **Agent ready on first available replica**: An agent is now marked ready as soon as at least one replica is available, rather than waiting for all replicas. +* **A2A `ListTasks` served from the task store**: `ListTasks` calls over A2A now return results from a persistent task store rather than being rebuilt from event history, improving reliability and performance for long sessions. +* **UI tool call grouping**: Tool calls in the chat interface are now visually grouped, making it easier to follow multi-step agent reasoning. +* **Model config name editing fix**: Fixed an issue where the model name field could not be edited on the model configuration form in the UI. * **UI rendering optimization**: Redundant background fetches in the chat interface are reduced, improving rendering performance for long sessions. # v0.9 diff --git a/src/app/docs/kagent/supported-providers/openai/page.mdx b/src/app/docs/kagent/supported-providers/openai/page.mdx index 0f2fd6be..8bc84f51 100644 --- a/src/app/docs/kagent/supported-providers/openai/page.mdx +++ b/src/app/docs/kagent/supported-providers/openai/page.mdx @@ -43,7 +43,7 @@ Once the resource is applied, you can select the model from the Model dropdown i ## Reasoning effort -For OpenAI reasoning models (o-series, GPT-5), you can control how many reasoning tokens the model generates before producing a response with the `openAI.reasoningEffort` field. Valid values are `none`, `minimal`, `low`, `medium`, and `high`. +For OpenAI reasoning models (o-series, GPT-5), you can control how many reasoning tokens the model generates before producing a response with the `openAI.reasoningEffort` field. Valid values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. For models that require reasoning to be explicitly disabled (such as some GPT-5 variants), set `reasoningEffort: none`. For standard models that do not support it, omit the field. @@ -54,3 +54,20 @@ spec: openAI: reasoningEffort: medium ``` + +## Max completion tokens + +For OpenAI reasoning models (o-series, GPT-5), use `openAI.maxCompletionTokens` to cap the total number of tokens the model can generate in a response, including both visible output tokens and reasoning tokens. + +> **Note**: Do not use `openAI.maxTokens` for reasoning models. OpenAI deprecated `max_tokens` for the Chat Completions API, and reasoning models reject it outright with a 400 error. Use `maxCompletionTokens` instead. + +```yaml +spec: + provider: OpenAI + model: o3 + openAI: + reasoningEffort: medium + maxCompletionTokens: 16000 +``` + +For standard (non-reasoning) models and OpenAI-compatible endpoints, `openAI.maxTokens` continues to work as before. The two fields are independent. From eb24bcd62d282f77c79c2c2186b74a3d5453a213 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:20:31 -0500 Subject: [PATCH 12/31] Update src/app/docs/kagent/observability/launch-ui/page.mdx Co-authored-by: Kristin Brown Signed-off-by: Rachael Graham --- src/app/docs/kagent/observability/launch-ui/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/observability/launch-ui/page.mdx b/src/app/docs/kagent/observability/launch-ui/page.mdx index ae0e82c0..ac555014 100644 --- a/src/app/docs/kagent/observability/launch-ui/page.mdx +++ b/src/app/docs/kagent/observability/launch-ui/page.mdx @@ -91,7 +91,7 @@ To disable the auto-created Route and front the UI with your own ingress instead ### Gateway API HTTPRoute -If your cluster uses a Gateway API implementation such as kgateway, Istio, or Envoy Gateway, you can enable a `HTTPRoute` for the UI with `ui.httpRoute.enabled: true`. +If your cluster uses a Gateway API implementation such as kgateway, Istio, or Envoy Gateway, you can enable an `HTTPRoute` for the UI with `ui.httpRoute.enabled: true`. ```yaml ui: From b4d863d48bba9aeaeb821b25396f5b203e51c72f Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:25:48 -0500 Subject: [PATCH 13/31] updates Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 2 +- .../docs/kagent/resources/release-notes/page.mdx | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index bcfd6d2a..bf891e8f 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -300,7 +300,7 @@ Compaction removes older conversation events to free up space in the context win ## Sandboxed Agents -You can run a declarative agent in an isolated sandbox by creating a `SandboxAgent` resource instead of a regular `Agent`. A `SandboxAgent` runs on [Agent Substrate](/docs/kagent/concepts/agent-substrate): the kagent controller runs it as a gVisor-sandboxed actor instead of a Deployment, snapshotting it to object storage when idle and rehydrating it on demand. The spec mirrors the `Agent` spec. All three runtimes are supported: **Go** (default), **Python**, and **BYO**. Session history is persisted to a local SQLite database in the agent's `durableDir` volume, so conversation state survives pod restarts and Deployment rollouts. Configure substrate placement with the optional `spec.substrate` field (for example, `workerPoolRef`). +You can run a declarative agent in an isolated sandbox by creating a `SandboxAgent` resource instead of a regular `Agent`. A `SandboxAgent` runs on [Agent Substrate](/docs/kagent/concepts/agent-substrate): the kagent controller runs it as a gVisor-sandboxed actor instead of a Deployment, snapshotting it to object storage when idle and rehydrating it on demand. The spec mirrors the `Agent` spec. All three runtimes are supported: **Go** (default), **Python**, and **BYO**. For Go and Python agents, session history is persisted to a local SQLite database in the agent's `durableDir` volume, so conversation state survives pod restarts and Deployment rollouts. BYO agents do not get local session storage automatically. Configure substrate placement with the optional `spec.substrate` field (for example, `workerPoolRef`). For setup steps, see the [Agent Substrate example](/docs/kagent/examples/agent-substrate). diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 5b0581e1..a1adf21a 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -34,14 +34,17 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [Configurable A2A client timeout](#configurable-a2a-client-timeout): New `controller.a2aClientTimeout` Helm value removes the previous 3-minute hard cutoff for long-running agents. * [SSO session expiry re-authentication](#sso-session-expiry-re-authentication): Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. * [Out-of-band database migrations](#out-of-band-database-migrations): New `kagent db migrate` CLI and `database.postgres.skipMigrations` Helm value for managing migrations independently of controller startup. -* [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. -* [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. -* [Durable session state for sandbox agents](#durable-session-state-for-sandbox-agents): Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and config rollouts. +* [Durable session state for sandbox agents](#durable-session-state-for-sandbox-agents): Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and Deployment rollouts. * [UI HTTPRoute](#ui-httproute): New `ui.httpRoute` Helm value for fronting the UI with a Gateway API HTTPRoute (kgateway, Istio, Envoy Gateway). * [MCP App chat widgets](#mcp-app-chat-widgets): MCP tools that expose UI resources now render interactive widgets inline in the chat interface. * [Pod labels for controller and UI](#pod-labels-for-controller-and-ui): New `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. -* [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. * [Default nodeSelector for agent deployments](#default-nodeselector-for-agent-deployments): New `controller.agentDeployment.nodeSelector` Helm value applies a global default nodeSelector to all agent Deployments created by the controller. +* [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. +* [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. +* [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. +* [Configurable Go ADK agent image](#configurable-go-adk-agent-image): New `controller.goAgentImage` Helm values configure the Go ADK runtime image independently, fixing mirror registry layouts that the previous derivation could not produce. +* [Max completion tokens for OpenAI](#max-completion-tokens-for-openai): New `openAI.maxCompletionTokens` field for capping output on reasoning models (o-series, GPT-5), which reject the deprecated `maxTokens` field. +* [ServiceAccount annotations](#serviceaccount-annotations): New `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations` Helm values for cloud workload identity integrations (GCP, AWS IRSA, Azure). ## Go ADK is now the default runtime @@ -172,7 +175,7 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op ## Durable session state for sandbox agents -Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and config rollouts. For example, a previous conversation continues seamlessly after a Deployment rollout triggered by a prompt change. +Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and Deployment rollouts — for example, a previous conversation continues seamlessly after a rollout triggered by a prompt change. Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. From 7a36826c2e6e37cb5028286f5dc28db706768c34 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:30:38 -0500 Subject: [PATCH 14/31] fixes Signed-off-by: Rachael Graham --- src/app/docs/kagent/resources/release-notes/page.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index a1adf21a..4f79c655 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -42,9 +42,6 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. * [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. * [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. -* [Configurable Go ADK agent image](#configurable-go-adk-agent-image): New `controller.goAgentImage` Helm values configure the Go ADK runtime image independently, fixing mirror registry layouts that the previous derivation could not produce. -* [Max completion tokens for OpenAI](#max-completion-tokens-for-openai): New `openAI.maxCompletionTokens` field for capping output on reasoning models (o-series, GPT-5), which reject the deprecated `maxTokens` field. -* [ServiceAccount annotations](#serviceaccount-annotations): New `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations` Helm values for cloud workload identity integrations (GCP, AWS IRSA, Azure). ## Go ADK is now the default runtime @@ -175,7 +172,7 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op ## Durable session state for sandbox agents -Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and Deployment rollouts — for example, a previous conversation continues seamlessly after a rollout triggered by a prompt change. +Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and Deployment rollouts; for example, a previous conversation continues seamlessly after a rollout triggered by a prompt change. Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. @@ -315,7 +312,7 @@ When unset, `nodeSelector` is omitted entirely, so there is no change for existi * **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. * **Go ADK OpenAI embeddings**: Fixed embeddings generation when using the OpenAI provider with the Go ADK runtime. * **Helm image registry fixes**: Helm charts for the grafana-mcp and querydoc subcharts now correctly handle an empty `image.registry` value, avoiding malformed image paths in air-gapped or registry-less deployments. -* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now scoped to their Kubernetes namespace (atespace = namespace). Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. +* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now isolated per Kubernetes namespace, so that actors in different namespaces cannot see or conflict with each other. Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. * **Concurrent memory search deadlock fix**: Fixed intermittent PostgreSQL deadlocks when concurrent memory searches (such as `PrefetchMemoryTool` fan-out) updated overlapping rows. Row locks are now acquired in ID order and access-count updates are best-effort. * **Anthropic thinking blocks in Python ADK**: Google ADK bumped to 1.32.0, enabling Anthropic thinking block support for agents using the Python runtime. * **Image registry updated to ghcr.io**: The `cr.kagent.dev` registry alias is removed. All default image references now use `ghcr.io/kagent-dev/kagent`. If you pinned images using the `cr.kagent.dev` alias, update your references to `ghcr.io`. From fb614709658cdb1351f60594e3b4297ebba9b612 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:45:15 -0500 Subject: [PATCH 15/31] Update page.mdx Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 30 ++++++++++++++----- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 77d82201..925b2c9e 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -24,19 +24,17 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. **What's included:** +**Agent runtimes** + * [Go ADK is now the default runtime](#go-adk-is-now-the-default-runtime): New declarative agents use the Go ADK by default. * [A2A AgentCard metadata](#a2a-agentcard-metadata): New optional fields on the Agent spec for enriching the A2A AgentCard. + +**Helm & configuration** + * [Configurable streaming timeouts](#configurable-streaming-timeouts): New Helm values for nginx proxy and client-side EventSource inactivity timeouts, including OpenShift HAProxy support. * [Controller service annotations](#controller-service-annotations): New `controller.service.annotations` Helm value for integrations like AWS Load Balancer Controller and ExternalDNS. -* [ACP protocol support for substrate agents](#acp-protocol-support-for-substrate-agents): New ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. -* [Chat session sharing](#chat-session-sharing): Session owners can now generate shareable links in read-only or read-write mode. -* [Substrate support for BYO and Python agents](#substrate-support-for-byo-and-python-agents): `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. * [Configurable A2A client timeout](#configurable-a2a-client-timeout): New `controller.a2aClientTimeout` Helm value removes the previous 3-minute hard cutoff for long-running agents. -* [SSO session expiry re-authentication](#sso-session-expiry-re-authentication): Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. -* [Out-of-band database migrations](#out-of-band-database-migrations): New `kagent db migrate` CLI and `database.postgres.skipMigrations` Helm value for managing migrations independently of controller startup. -* [Durable session state for sandbox agents](#durable-session-state-for-sandbox-agents): Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and Deployment rollouts. * [UI HTTPRoute](#ui-httproute): New `ui.httpRoute` Helm value for fronting the UI with a Gateway API HTTPRoute (kgateway, Istio, Envoy Gateway). -* [MCP App chat widgets](#mcp-app-chat-widgets): MCP tools that expose UI resources now render interactive widgets inline in the chat interface. * [Pod labels for controller and UI](#pod-labels-for-controller-and-ui): New `podLabels`, `controller.podLabels`, and `ui.podLabels` Helm values for pod template labels on the controller and UI Deployments. * [Default nodeSelector for agent deployments](#default-nodeselector-for-agent-deployments): New `controller.agentDeployment.nodeSelector` Helm value applies a global default nodeSelector to all agent Deployments created by the controller. * [Configurable Go ADK agent image](#configurable-go-adk-agent-image): New `controller.goAgentImage` Helm values configure the Go ADK runtime image independently, fixing mirror registry layouts that the previous derivation could not produce. @@ -46,6 +44,22 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. * [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. +**Agent Substrate** + +* [ACP protocol support for substrate agents](#acp-protocol-support-for-substrate-agents): New ACP shim enabling WebSocket-to-stdio translation for agents running on substrate. +* [Substrate support for BYO and Python agents](#substrate-support-for-byo-and-python-agents): `SandboxAgent` now supports BYO and Python runtime agents in addition to Go declarative agents. +* [Durable session state for sandbox agents](#durable-session-state-for-sandbox-agents): Go and Python declarative sandbox agents now persist session history to a local SQLite database in the `durableDir` volume, surviving pod restarts and Deployment rollouts. + +**UI & auth** + +* [Chat session sharing](#chat-session-sharing): Session owners can now generate shareable links in read-only or read-write mode. +* [SSO session expiry re-authentication](#sso-session-expiry-re-authentication): Expired OIDC proxy sessions now automatically redirect to re-authenticate instead of showing an error. +* [MCP App chat widgets](#mcp-app-chat-widgets): MCP tools that expose UI resources now render interactive widgets inline in the chat interface. + +**Database** + +* [Out-of-band database migrations](#out-of-band-database-migrations): New `kagent db migrate` CLI and `database.postgres.skipMigrations` Helm value for managing migrations independently of controller startup. + ## Go ADK is now the default runtime The default declarative agent runtime is now **Go**. Previously, new declarative agents used the Python ADK unless `runtime: go` was explicitly set. The Go ADK starts in approximately 2 seconds (versus ~15 seconds for Python) and uses fewer resources. @@ -400,7 +414,7 @@ For more information, see [Customize Kubernetes resources](/docs/kagent/introduc **Agent Substrate** -* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now scoped to their Kubernetes namespace (atespace = namespace). Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. +* **Substrate actor namespace scoping**: Actors created by `SandboxAgent` and `AgentHarness` are now isolated per Kubernetes namespace, so that actors in different namespaces cannot see or conflict with each other. Also fixes an infinite `ActorTemplate` delete/recreate loop caused by `SnapshotsConfig` defaults drift. * **SandboxAgent readiness gating**: `SandboxAgent` actors are now only marked ready once the agent application is confirmed to be serving traffic, preventing requests from reaching actors that have started but are not yet initialized. * **Agent Substrate bumped to v0.0.9**: The bundled Agent Substrate runtime is updated to v0.0.9. * **Substrate badge on agent cards**: Sandbox agents running on Agent Substrate are now visually marked in the UI agent card list. From 92e3253b497bb7b2738d4b6fce561b208447ed9c Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:53:32 -0500 Subject: [PATCH 16/31] Update page.mdx Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 208 +++++++++--------- 1 file changed, 104 insertions(+), 104 deletions(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 925b2c9e..6cbb9400 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -126,29 +126,6 @@ controller: external-dns.alpha.kubernetes.io/hostname: kagent.example.com ``` -## ACP protocol support for substrate agents - -kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with OpenClaw and Hermes to communicate over the substrate runtime without additional configuration. - -For more information, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). - -## Chat session sharing - -Session owners can now generate shareable links for any chat session. Shared sessions support two modes: - -- **Read-only** (default): Recipients can view the conversation but cannot send messages or respond to tool confirmations. Useful for review, handoff documentation, and broadcasting agent output. -- **Read-write** (interactive): Recipients can interact with the session as if they were the owner, such as sending messages, approving or rejecting tool calls, and answering agent questions. All parties see the results in real time. - -Shared sessions that a user has accessed appear in their sidebar alongside their own sessions, so recipients do not need to keep the original link to return. Agents can also generate and revoke share links as part of their own workflows. - -Read-only share tokens can also read A2A tasks on the shared session (`ListTasks`, `GetTask`, `SubscribeToTask`). Mutating operations (`SendMessage`, `CancelTask`) still require a read-write share token. - -## Substrate support for BYO and Python agents - -`SandboxAgent` now supports running BYO agents and Python runtime declarative agents on Agent Substrate, in addition to Go declarative agents. This means any `Agent` type can be run as a sandboxed substrate workload. - -For setup details, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). - ## Configurable A2A client timeout A new `controller.a2aClientTimeout` Helm value (default: `""` — no timeout) lets you override the A2A client HTTP timeout. Previously, the a2a-go SDK applied a hard 3-minute timeout to all A2A client requests, causing `context deadline exceeded` errors during long-running agent interactions or SSE streams. @@ -160,45 +137,6 @@ controller: For more information, see [Long-running connections](/docs/kagent/operations/operational-considerations#long-running-connections). -## SSO session expiry re-authentication - -When deployed behind an OIDC proxy (such as oauth2-proxy), expired sessions now trigger an automatic redirect to `/oauth2/start` for re-authentication instead of showing an error. A loop guard prevents infinite redirects if re-authentication fails. Sessions in unsecured (no-proxy) mode are unaffected. - -## Out-of-band database migrations - -Two new features give operators control over when and how database migrations run. - -### kagent db migrate CLI - -A new `kagent db migrate` command group lets you apply, inspect, and recover database migrations without relying on controller startup. This is useful for CI/CD pipelines and environments where migration timing must be explicit. - -| Subcommand | Description | -|---|---| -| `kagent db migrate up` | Apply all pending migrations across all sources. | -| `kagent db migrate status` | Show applied and pending migration counts per source. | -| `kagent db migrate version` | Print the highest applied version per source. | -| `kagent db migrate goto V --source ` | Move the schema to version V (forward or backward). Used for rollbacks. | -| `kagent db migrate down N --source ` | Roll back the N most recent migrations on the named source. | -| `kagent db migrate force V --source ` | Mark version V as applied without running SQL. Used to recover from a dirty migration state. | - -Set `POSTGRES_DATABASE_URL` or pass `--db-url` to provide the database connection string. If `DATABASE_VECTOR_ENABLED` is not set in the environment, the CLI reads it from the `kagent-controller` ConfigMap in the current cluster context. - -### Skip startup migrations - -A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents the controller from running migrations at startup. When enabled, the controller verifies the schema is already fully migrated and exits with an error if it is not. Apply migrations out-of-band before installing or upgrading when this option is set. - -For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). - -## Durable session state for sandbox agents - -Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and Deployment rollouts; for example, a previous conversation continues seamlessly after a rollout triggered by a prompt change. - -Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. - -You can override the session database endpoint with the `KAGENT_SESSION_DB_URL` environment variable. - -For more information, see [Agent Substrate — Declarative agents](/docs/kagent/concepts/agent-substrate#declarative-agents). - ## UI HTTPRoute You can now front the kagent UI by a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) `HTTPRoute` instead of a plain `Ingress` or OpenShift `Route`. This is useful when your cluster uses kgateway, Istio, or Envoy Gateway as its traffic management layer. @@ -218,10 +156,6 @@ ui: For all UI exposure options including LoadBalancer service and OpenShift Route, see [Expose the UI outside the cluster](/docs/kagent/observability/launch-ui#expose-the-ui-outside-the-cluster). -## MCP App chat widgets - -MCP tools that expose UI resources (MCP Apps) now render interactive widgets inline in the kagent chat interface. When an agent calls such a tool, the response appears as an embedded widget rather than raw text, and users can interact with it directly in the chat window. The backend compacts MCP App tool responses sent to the model to prevent redundant repeated calls. - ## Pod labels for controller and UI You can now add custom labels to the pod templates of the controller and UI Deployments. A global `podLabels` map applies to all component pods, with per-component overrides via `controller.podLabels` and `ui.podLabels` (component keys win on conflict). @@ -259,6 +193,60 @@ This is useful in clusters where admission policies (Gatekeeper, Kyverno) requir For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). +## Configurable Go ADK agent image + +You can now use the `controller.goAgentImage` Helm values to configure the Go ADK runtime image independently of the main agent image. Previously, the controller derived the Go image repository from the Python image by replacing the last path segment with `golang-adk`. This pattern breaks in flat-name mirror registries where the image name cannot be produced by that derivation. + +```yaml +controller: + goAgentImage: + registry: my-registry.io + repository: kagent/golang-adk + tag: v0.10.0 + pullPolicy: IfNotPresent +``` + +The `registry` and `pullPolicy` fields default to the global `image.registry` and `image.pullPolicy` values. The `tag` coalesces to the global image tag, then the chart version. + +> **Breaking change for mirror registry operators**: If you mirror kagent images and only set `agentImage`, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. The controller logs a startup warning when the Go image registry differs from the main image registry, so that a misconfigured mirror is visible before a Go agent fails to pull. + +For more information, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). + +## Max completion tokens for OpenAI + +OpenAI reasoning models (o-series, GPT-5) reject the `max_tokens` request parameter with a 400 error. Use the new `openAI.maxCompletionTokens` field instead, which maps to OpenAI's `max_completion_tokens` parameter and caps both visible output tokens and internal reasoning tokens. + +```yaml +spec: + provider: OpenAI + model: o3 + openAI: + reasoningEffort: medium + maxCompletionTokens: 16000 +``` + +The existing `openAI.maxTokens` field is unchanged and continues to work for standard models and OpenAI-compatible endpoints. The two fields are independent: set `maxCompletionTokens` for reasoning models and `maxTokens` only for endpoints that still require `max_tokens`. + +For more information, see [Max completion tokens](/docs/kagent/supported-providers/openai#max-completion-tokens). + +## ServiceAccount annotations + +You can now annotate the controller and UI Kubernetes ServiceAccounts via `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations`. This standard mechanism is required for cloud-provider workload identity integrations that grant IAM permissions by annotating a ServiceAccount. + +```yaml +controller: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent@my-project.iam.gserviceaccount.com + +ui: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: kagent-ui@my-project.iam.gserviceaccount.com +``` + +For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). + ## extraObjects A new top-level `extraObjects` Helm value lets you deploy arbitrary Kubernetes manifests in the same chart lifecycle as kagent. Entries are rendered through `tpl`, so they can reference the release context such as `{{ .Release.Namespace }}`. @@ -326,59 +314,71 @@ k8s-agent: When unset, `nodeSelector` is omitted entirely, so there is no change for existing deployments. -## Configurable Go ADK agent image +## ACP protocol support for substrate agents -You can now use the `controller.goAgentImage` Helm values to configure the Go ADK runtime image independently of the main agent image. Previously, the controller derived the Go image repository from the Python image by replacing the last path segment with `golang-adk`. This pattern breaks in flat-name mirror registries where the image name cannot be produced by that derivation. +kagent now includes an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) shim in the base images for agents running on substrate. The shim reuses the WebSocket connection from the substrate actor and translates it to stdio, enabling agents built with OpenClaw and Hermes to communicate over the substrate runtime without additional configuration. -```yaml -controller: - goAgentImage: - registry: my-registry.io - repository: kagent/golang-adk - tag: v0.10.0 - pullPolicy: IfNotPresent -``` +For more information, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). -The `registry` and `pullPolicy` fields default to the global `image.registry` and `image.pullPolicy` values. The `tag` coalesces to the global image tag, then the chart version. +## Substrate support for BYO and Python agents -> **Breaking change for mirror registry operators**: If you mirror kagent images and only set `agentImage`, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. The controller logs a startup warning when the Go image registry differs from the main image registry, so that a misconfigured mirror is visible before a Go agent fails to pull. +`SandboxAgent` now supports running BYO agents and Python runtime declarative agents on Agent Substrate, in addition to Go declarative agents. This means any `Agent` type can be run as a sandboxed substrate workload. -For more information, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). +For setup details, see [Agent Substrate](/docs/kagent/concepts/agent-substrate). -## Max completion tokens for OpenAI +## Durable session state for sandbox agents -OpenAI reasoning models (o-series, GPT-5) reject the `max_tokens` request parameter with a 400 error. Use the new `openAI.maxCompletionTokens` field instead, which maps to OpenAI's `max_completion_tokens` parameter and caps both visible output tokens and internal reasoning tokens. +Go and Python declarative `SandboxAgent` instances now persist session history to a local SQLite database backed by the agent's `durableDir` volume. Session history survives pod restarts and Deployment rollouts; for example, a previous conversation continues seamlessly after a rollout triggered by a prompt change. -```yaml -spec: - provider: OpenAI - model: o3 - openAI: - reasoningEffort: medium - maxCompletionTokens: 16000 -``` +Session metadata is mirrored to the PostgreSQL database to support session-listing APIs. BYO agents do not get local session storage automatically; set the `kagent.dev/local-session-storage` annotation on the `SandboxAgent` if your BYO agent implements its own local store and you want to enable the same behavior. -The existing `openAI.maxTokens` field is unchanged and continues to work for standard models and OpenAI-compatible endpoints. The two fields are independent: set `maxCompletionTokens` for reasoning models and `maxTokens` only for endpoints that still require `max_tokens`. +You can override the session database endpoint with the `KAGENT_SESSION_DB_URL` environment variable. -For more information, see [Max completion tokens](/docs/kagent/supported-providers/openai#max-completion-tokens). +For more information, see [Agent Substrate — Declarative agents](/docs/kagent/concepts/agent-substrate#declarative-agents). -## ServiceAccount annotations +## Chat session sharing -You can now annotate the controller and UI Kubernetes ServiceAccounts via `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations`. This standard mechanism is required for cloud-provider workload identity integrations that grant IAM permissions by annotating a ServiceAccount. +Session owners can now generate shareable links for any chat session. Shared sessions support two modes: -```yaml -controller: - serviceAccount: - annotations: - iam.gke.io/gcp-service-account: kagent@my-project.iam.gserviceaccount.com +- **Read-only** (default): Recipients can view the conversation but cannot send messages or respond to tool confirmations. Useful for review, handoff documentation, and broadcasting agent output. +- **Read-write** (interactive): Recipients can interact with the session as if they were the owner, such as sending messages, approving or rejecting tool calls, and answering agent questions. All parties see the results in real time. -ui: - serviceAccount: - annotations: - iam.gke.io/gcp-service-account: kagent-ui@my-project.iam.gserviceaccount.com -``` +Shared sessions that a user has accessed appear in their sidebar alongside their own sessions, so recipients do not need to keep the original link to return. Agents can also generate and revoke share links as part of their own workflows. -For more information, see [Customize Kubernetes resources](/docs/kagent/introduction/installation#customize-kubernetes-resources). +Read-only share tokens can also read A2A tasks on the shared session (`ListTasks`, `GetTask`, `SubscribeToTask`). Mutating operations (`SendMessage`, `CancelTask`) still require a read-write share token. + +## SSO session expiry re-authentication + +When deployed behind an OIDC proxy (such as oauth2-proxy), expired sessions now trigger an automatic redirect to `/oauth2/start` for re-authentication instead of showing an error. A loop guard prevents infinite redirects if re-authentication fails. Sessions in unsecured (no-proxy) mode are unaffected. + +## MCP App chat widgets + +MCP tools that expose UI resources (MCP Apps) now render interactive widgets inline in the kagent chat interface. When an agent calls such a tool, the response appears as an embedded widget rather than raw text, and users can interact with it directly in the chat window. The backend compacts MCP App tool responses sent to the model to prevent redundant repeated calls. + +## Out-of-band database migrations + +Two new features give operators control over when and how database migrations run. + +### kagent db migrate CLI + +A new `kagent db migrate` command group lets you apply, inspect, and recover database migrations without relying on controller startup. This is useful for CI/CD pipelines and environments where migration timing must be explicit. + +| Subcommand | Description | +|---|---| +| `kagent db migrate up` | Apply all pending migrations across all sources. | +| `kagent db migrate status` | Show applied and pending migration counts per source. | +| `kagent db migrate version` | Print the highest applied version per source. | +| `kagent db migrate goto V --source ` | Move the schema to version V (forward or backward). Used for rollbacks. | +| `kagent db migrate down N --source ` | Roll back the N most recent migrations on the named source. | +| `kagent db migrate force V --source ` | Mark version V as applied without running SQL. Used to recover from a dirty migration state. | + +Set `POSTGRES_DATABASE_URL` or pass `--db-url` to provide the database connection string. If `DATABASE_VECTOR_ENABLED` is not set in the environment, the CLI reads it from the `kagent-controller` ConfigMap in the current cluster context. + +### Skip startup migrations + +A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents the controller from running migrations at startup. When enabled, the controller verifies the schema is already fully migrated and exits with an error if it is not. Apply migrations out-of-band before installing or upgrading when this option is set. + +For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). ## Additional changes in v0.10 From 1559b817b31a898f1c03f8e68516706e9f8ecb96 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 10:58:31 -0500 Subject: [PATCH 17/31] edits Signed-off-by: Rachael Graham --- src/app/docs/kagent/introduction/installation/page.mdx | 4 ++-- src/app/docs/kagent/resources/release-notes/page.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 0242b9e0..f3572b74 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -344,7 +344,7 @@ To add labels to all **agent** pods, use `controller.agentDeployment.podLabels`. #### ServiceAccount annotations -Add annotations to the controller and UI ServiceAccount resources. These annotations are required for cloud-provider workload identity integrations (GCP Workload Identity, AWS IRSA, Azure Workload Identity) that grant IAM permissions to workloads by annotating their Kubernetes ServiceAccount. +Add annotations to the controller and UI ServiceAccount resources. These annotations are required for cloud provider workload identity integrations (GCP Workload Identity, AWS IRSA, Azure Workload Identity) that grant IAM permissions to workloads by annotating their Kubernetes ServiceAccount. ```yaml controller: @@ -413,7 +413,7 @@ extraObjects: ### Private registry and image mirroring -If your cluster cannot pull from `ghcr.io` directly, such as in air-gapped environments, corporate proxies, or mandatory image scanning, you can mirror the kagent images to an internal registry and configure the chart to pull from the registry. +If your cluster cannot pull from `ghcr.io` directly, such as in air-gapped environments, corporate proxies, or mandatory image scanning, you can mirror the kagent images to an internal registry and configure the chart to pull from this registry. kagent uses three independently configurable image locations: diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 6cbb9400..61b462a1 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -231,7 +231,7 @@ For more information, see [Max completion tokens](/docs/kagent/supported-provide ## ServiceAccount annotations -You can now annotate the controller and UI Kubernetes ServiceAccounts via `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations`. This standard mechanism is required for cloud-provider workload identity integrations that grant IAM permissions by annotating a ServiceAccount. +You can now annotate the controller and UI Kubernetes ServiceAccounts via `controller.serviceAccount.annotations` and `ui.serviceAccount.annotations`. This standard mechanism is required for cloud provider workload identity integrations that grant IAM permissions by annotating a ServiceAccount. ```yaml controller: From 631797fb50752c67421f9ded0fd8681aa27de02d Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Tue, 28 Jul 2026 11:21:49 -0500 Subject: [PATCH 18/31] Update page.mdx Signed-off-by: Rachael Graham --- src/app/docs/kagent/resources/release-notes/page.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 61b462a1..29668a7b 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -22,7 +22,7 @@ For more details on the changes between versions, review the [kagent GitHub rele Review this summary of significant changes from kagent version 0.9 to v0.10. -**What's included:** +## What's included **Agent runtimes** @@ -60,6 +60,8 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [Out-of-band database migrations](#out-of-band-database-migrations): New `kagent db migrate` CLI and `database.postgres.skipMigrations` Helm value for managing migrations independently of controller startup. +[**Additional changes**](#additional-changes-in-v010) + ## Go ADK is now the default runtime The default declarative agent runtime is now **Go**. Previously, new declarative agents used the Python ADK unless `runtime: go` was explicitly set. The Go ADK starts in approximately 2 seconds (versus ~15 seconds for Python) and uses fewer resources. From 7ff69ad34eb1ad949d1226f8e8392c323e27d5f9 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 09:34:04 -0500 Subject: [PATCH 19/31] gemini.maxOutputTokens Signed-off-by: Rachael Graham --- .../kagent/supported-providers/gemini/page.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/app/docs/kagent/supported-providers/gemini/page.mdx b/src/app/docs/kagent/supported-providers/gemini/page.mdx index 67a3b57d..b970a4c4 100644 --- a/src/app/docs/kagent/supported-providers/gemini/page.mdx +++ b/src/app/docs/kagent/supported-providers/gemini/page.mdx @@ -47,3 +47,17 @@ spec: 4. Apply the above resource to the cluster. Once the resource is applied, you can select the model from the Model dropdown in the UI when creating or updating agents. + +## Max output tokens + +Use `gemini.maxOutputTokens` to cap the number of tokens the model can generate in a single response. + +```yaml +spec: + provider: Gemini + model: gemini-2.5-pro + gemini: + maxOutputTokens: 8192 +``` + +A per-request value set by the agent always takes precedence over this model-level default. From 55af45b0e75dfc5414ed0d1e382a7a7c2fa07ad7 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 09:37:22 -0500 Subject: [PATCH 20/31] Bedrock guardrails & timeouts Signed-off-by: Rachael Graham --- .../amazon-bedrock/page.mdx | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx index 3c798a81..a100125c 100644 --- a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx +++ b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx @@ -106,6 +106,51 @@ spec: If you want to use one shared ServiceAccount for multiple agents, you can also set `controller.agentDeployment.serviceAccountName` in the [Helm chart configuration](/docs/kagent/resources/helm). +## Bedrock Guardrails + +You can apply [AWS Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) directly from the native Bedrock `ModelConfig` to enable content filtering, topic denial, and PII redaction. The guardrail is applied on every request to the Converse and ConverseStream APIs. + +```yaml +spec: + provider: Bedrock + model: us.anthropic.claude-sonnet-4-20250514-v1:0 + bedrock: + region: us-east-1 + guardrail: + identifier: "abc123def456" + version: "1" + trace: "enabled" +``` + +| Field | Description | +|---|---| +| `bedrock.guardrail.identifier` | The guardrail ID or ARN. Required when the `guardrail` block is present. | +| `bedrock.guardrail.version` | The guardrail version to apply. Required when the `guardrail` block is present. | +| `bedrock.guardrail.trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | + +Guardrail interventions are applied before content is returned to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so the agent loop continues. + +## Request timeouts + +By default, the Bedrock client uses botocore's ~60-second read timeout, which can cause `ReadTimeoutError` on long completions. Use `bedrock.readTimeout` and `bedrock.connectTimeout` to override these values. + +```yaml +spec: + provider: Bedrock + model: us.anthropic.claude-sonnet-4-20250514-v1:0 + bedrock: + region: us-east-1 + readTimeout: 1800 + connectTimeout: 30 +``` + +| Field | Description | +|---|---| +| `bedrock.readTimeout` | Maximum seconds to wait for a response chunk. Minimum: 1. | +| `bedrock.connectTimeout` | Maximum seconds to wait for the initial connection. Minimum: 1. Optional. | + +Both fields are optional. When neither is set, botocore defaults apply and existing behavior is unchanged. + ## Option 2: OpenAI-compatible API You can also use Bedrock models via the [OpenAI Chat Completions API](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-chat-completions.html). This option is useful when you need compatibility with the OpenAI API format or when using Bedrock's inference profiles. From fde24b2aef8d7df4989f62a043d1c3cee22e053f Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 09:42:12 -0500 Subject: [PATCH 21/31] agent deploy config (envFrom & deploymentAnnotations) Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 39 +++++++++++++++++++ .../amazon-bedrock/page.mdx | 4 +- 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index bf891e8f..a981363a 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -267,6 +267,45 @@ spec: For more benchmarks and details, see the [Go vs Python runtime blog post](/blog/go-vs-python-runtime). +## Deployment configuration + +The `spec.declarative.deployment` stanza controls how the agent's Kubernetes Deployment is configured. + +### Environment variables + +Use `env` to set individual environment variables, or `envFrom` to bulk-inject all keys from a ConfigMap or Secret. + +```yaml +spec: + declarative: + deployment: + env: + - name: LOG_LEVEL + value: debug + envFrom: + - configMapRef: + name: my-agent-config + - secretRef: + name: my-agent-secrets +``` + +### Deployment annotations + +Use `deploymentAnnotations` to add annotations to the Deployment object itself. This field is distinct from the `annotations` field, which targets pod template metadata only. + +```yaml +spec: + declarative: + deployment: + deploymentAnnotations: + argocd.argoproj.io/sync-wave: "5" + notifications.argoproj.io/subscribe.on-degraded.slack: my-channel + annotations: + prometheus.io/scrape: "true" # pod template only +``` + +`deploymentAnnotations` is useful for GitOps tooling such as Argo CD sync waves and Flux annotations, which key off Deployment-level metadata rather than pod metadata. + ## Memory Your agents can save and retrieve relevant context across conversations using vector similarity search. When you enable memory on an agent, it receives three additional tools (`save_memory`, `load_memory`, `prefetch_memory`) and automatically extracts key information every 5th user message. diff --git a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx index a100125c..38c7c01d 100644 --- a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx +++ b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx @@ -128,11 +128,11 @@ spec: | `bedrock.guardrail.version` | The guardrail version to apply. Required when the `guardrail` block is present. | | `bedrock.guardrail.trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | -Guardrail interventions are applied before content is returned to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so the agent loop continues. +Guardrail interventions are applied before content returns to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so that the agent loop continues. ## Request timeouts -By default, the Bedrock client uses botocore's ~60-second read timeout, which can cause `ReadTimeoutError` on long completions. Use `bedrock.readTimeout` and `bedrock.connectTimeout` to override these values. +By default, the Bedrock client uses botocore's ~60 second read timeout, which can cause `ReadTimeoutError` on long completions. Use `bedrock.readTimeout` and `bedrock.connectTimeout` to override these values. ```yaml spec: From 2632fbdbf0bfbe18cd41c3ccfa5de2c02c7fbabc Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 09:48:21 -0500 Subject: [PATCH 22/31] Disable default ModelConfig Signed-off-by: Rachael Graham --- src/app/docs/kagent/introduction/installation/page.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index f3572b74..254da7eb 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -411,6 +411,16 @@ extraObjects: key: anthropic-api-key ``` +### Disable the default ModelConfig + +By default, kagent creates a `ModelConfig` resource and associated Kubernetes Secret for the provider that you set with `providers.default`. To skip this and manage `ModelConfig` resources entirely outside the Helm chart, set `providers` to null: + +```yaml +providers: null +``` + +When `providers` is null (or omitted), neither the `ModelConfig` nor its Secret are created. Use this setting when you apply `ModelConfig` resources through GitOps, a separate Helm chart, or another external process. + ### Private registry and image mirroring If your cluster cannot pull from `ghcr.io` directly, such as in air-gapped environments, corporate proxies, or mandatory image scanning, you can mirror the kagent images to an internal registry and configure the chart to pull from this registry. From 16193f72cbd3274fbf7c4b7e7297726c53785945 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 09:50:04 -0500 Subject: [PATCH 23/31] Rel notes Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 29668a7b..3fa3a079 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -28,6 +28,8 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [Go ADK is now the default runtime](#go-adk-is-now-the-default-runtime): New declarative agents use the Go ADK by default. * [A2A AgentCard metadata](#a2a-agentcard-metadata): New optional fields on the Agent spec for enriching the A2A AgentCard. +* [maxOutputTokens for Gemini and Vertex AI](#maxoutputtokens-for-gemini-and-vertex-ai): New `maxOutputTokens` field on Gemini and Vertex AI providers for capping model output length. +* [AWS Bedrock Guardrails](#aws-bedrock-guardrails): Native guardrail support for the Bedrock provider, enabling content filtering, topic denial, and PII redaction. **Helm & configuration** @@ -43,6 +45,8 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [extraObjects](#extraobjects): New `extraObjects` Helm value for deploying arbitrary Kubernetes manifests in the same chart lifecycle as kagent. * [Deployment annotations](#deployment-annotations): New `controller.annotations` and `ui.annotations` Helm values for annotating the controller and UI Deployment resources. * [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. +* [envFrom for agent deployments](#envfrom-for-agent-deployments): New `envFrom` field on the agent deployment spec for bulk-injecting environment variables from ConfigMaps and Secrets. +* [Disable default ModelConfig](#disable-default-modelconfig): Set `providers: null` to suppress the Helm-generated default `ModelConfig` and `Secret`. **Agent Substrate** @@ -382,6 +386,81 @@ A new `database.postgres.skipMigrations` Helm value (default: `false`) prevents For details and usage examples, see [Run migrations out-of-band](/docs/kagent/operations/upgrade#run-migrations-out-of-band). +## maxOutputTokens for Gemini and Vertex AI + +The `maxOutputTokens` field is now wired for the native Gemini and Vertex AI providers. Previously, this field was declared on `GeminiVertexAIConfig` but never applied, and `GeminiConfig` had no such field at all. + +```yaml +spec: + provider: Gemini + model: gemini-2.5-pro + gemini: + maxOutputTokens: 8192 +``` + +```yaml +spec: + provider: GeminiVertexAI + model: gemini-2.5-pro + geminiVertexAI: + project: my-project + location: us-central1 + maxOutputTokens: 8192 +``` + +A per-request value set by the agent always takes precedence over the model-level default. + +## AWS Bedrock Guardrails + +You can now apply native [AWS Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) directly from `ModelConfig`. The controller passes the guardrail configuration to the Bedrock Converse and ConverseStream APIs, enabling content filtering, topic denial, and PII redaction without an external proxy. + +```yaml +spec: + provider: Bedrock + model: us.anthropic.claude-sonnet-4-20250514-v1:0 + bedrock: + region: us-east-1 + guardrail: + identifier: "abc123def456" + version: "1" + trace: "enabled" +``` + +| Field | Description | +|---|---| +| `identifier` | The guardrail ID or ARN. Required when the `guardrail` block is present. | +| `version` | The guardrail version to apply. Required when the `guardrail` block is present. | +| `trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | + +On the streaming path, guardrail interventions are applied before content is returned to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so the agent loop continues. + +## envFrom for agent deployments + +You can now bulk-inject environment variables from ConfigMaps and Secrets into agent pods using the `envFrom` field on the agent deployment spec. This complements the existing `env` field, which requires enumerating individual keys. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: Agent +spec: + declarative: + deployment: + envFrom: + - configMapRef: + name: my-agent-config + - secretRef: + name: my-agent-secrets +``` + +## Disable default ModelConfig + +Set `providers: null` in your Helm values to suppress the default `ModelConfig` and its associated `Secret` from being created. This is useful when you manage `ModelConfig` resources outside the kagent Helm chart. + +```yaml +providers: null +``` + +When `providers` is unset or null, neither the `modelconfig` nor the `modelconfig-secret` templates are rendered. Existing installs that supply `providers` are unaffected. + ## Additional changes in v0.10 **Security** @@ -399,6 +478,7 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op * **`nodeSelector` and `tolerations` for `kagent-tools` subchart**: The `kagent-tools` bundled subchart now accepts `nodeSelector` and `tolerations` values, so tools pods can be placed on specific nodes or tolerate taints. * **oauth2-proxy subchart updated to ~10.7.0**: The bundled oauth2-proxy dependency is bumped to the 10.7.x chart series. * **Custom annotations on the default ModelConfig**: A new per-provider `annotations` map under `providers..annotations` is applied to the Helm-generated default ModelConfig. Useful for downstream tooling or UI extensions that key off resource annotations. +* **`deploymentAnnotations` for agent deployments**: New `deploymentAnnotations` field on the agent deployment spec sets annotations on the Deployment object itself. The existing `annotations` field targets pod template metadata only. Useful for GitOps tooling such as Argo CD sync waves, Flux, and Kyverno policies that key off Deployment-level annotations. **Agent runtimes and providers** @@ -413,6 +493,8 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op * **Azure OpenAI secretKeyRef fix**: Fixed an issue where an empty `secretKeyRef` was generated for Azure OpenAI model configurations that do not use a Kubernetes secret for credentials. * **Azure OpenAI API key env var name**: The `AZURE_OPENAI_API_KEY` environment variable name is now used consistently throughout the codebase, fixing providers that were reading a mismatched key name. * **OpenTelemetry double-instrumentation fix**: The OpenAI client is no longer double-instrumented on the Go ADK runtime, preventing duplicate spans in OTel traces when using OpenAI with the Go runtime. +* **Configurable Bedrock read/connect timeout**: New `bedrock.readTimeout` and `bedrock.connectTimeout` fields on `ModelConfig` replace the ~60s botocore default that caused `ReadTimeoutError` on long completions. Both values are in seconds and are optional. +* **RFC 8707 resource and audience for STS token exchange**: The Go and Python ADK token-propagation plugins now read `KAGENT_STS_RESOURCE` and `KAGENT_STS_AUDIENCE` environment variables to scope issued STS tokens to a specific backend. Backwards compatible — existing deployments are unaffected when neither variable is set. **Agent Substrate** @@ -437,6 +519,9 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op * **UI tool call grouping**: Tool calls in the chat interface are now visually grouped, making it easier to follow multi-step agent reasoning. * **Model config name editing fix**: Fixed an issue where the model name field could not be edited on the model configuration form in the UI. * **UI rendering optimization**: Redundant background fetches in the chat interface are reduced, improving rendering performance for long sessions. +* **ADK token refresh loop resilience**: Exceptions during token reads in the Python ADK no longer kill the background refresh goroutine. Failed reads are logged and the loop continues on the next cycle instead of silently stopping. +* **ACP shim teardown deadlock fix**: Fixed a deadlock where `terminate()` could hang indefinitely when a WebSocket client stalled, blocking the stdout reader goroutine on a full channel and preventing the shim from shutting down. +* **ADK session state with `num_recent_events`**: Fixed a bug where `session.state` was built from only the last N events when `num_recent_events` was set, silently dropping state deltas from older events. Full event history is now always used to compute state; `num_recent_events` only trims the returned events list. # v0.9 From baff7e59592b0251cead8af2896dd055a6d00304 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 10:06:40 -0500 Subject: [PATCH 24/31] wording edits Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 2 +- src/app/docs/kagent/introduction/installation/page.mdx | 2 +- .../docs/kagent/supported-providers/amazon-bedrock/page.mdx | 6 +++--- src/app/docs/kagent/supported-providers/gemini/page.mdx | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index a981363a..fa35f954 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -269,7 +269,7 @@ For more benchmarks and details, see the [Go vs Python runtime blog post](/blog/ ## Deployment configuration -The `spec.declarative.deployment` stanza controls how the agent's Kubernetes Deployment is configured. +Control how the agent's Kubernetes Deployment is configured in the `spec.declarative.deployment` stanza. ### Environment variables diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 254da7eb..d7b36a09 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -419,7 +419,7 @@ By default, kagent creates a `ModelConfig` resource and associated Kubernetes Se providers: null ``` -When `providers` is null (or omitted), neither the `ModelConfig` nor its Secret are created. Use this setting when you apply `ModelConfig` resources through GitOps, a separate Helm chart, or another external process. +When `providers` is null (or omitted), kagent does not create the `ModelConfig` or its Secret. Use this setting when you apply `ModelConfig` resources through GitOps, a separate Helm chart, or another external process. ### Private registry and image mirroring diff --git a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx index 38c7c01d..212e5856 100644 --- a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx +++ b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx @@ -108,7 +108,7 @@ If you want to use one shared ServiceAccount for multiple agents, you can also s ## Bedrock Guardrails -You can apply [AWS Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) directly from the native Bedrock `ModelConfig` to enable content filtering, topic denial, and PII redaction. The guardrail is applied on every request to the Converse and ConverseStream APIs. +You can apply [AWS Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) directly from the native Bedrock `ModelConfig` to enable content filtering, topic denial, and PII redaction. The guardrail applies on every request to the Converse and ConverseStream APIs. ```yaml spec: @@ -128,11 +128,11 @@ spec: | `bedrock.guardrail.version` | The guardrail version to apply. Required when the `guardrail` block is present. | | `bedrock.guardrail.trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | -Guardrail interventions are applied before content returns to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so that the agent loop continues. +Guardrail interventions apply before content returns to the caller so that blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, enabling the agent loop to continue. ## Request timeouts -By default, the Bedrock client uses botocore's ~60 second read timeout, which can cause `ReadTimeoutError` on long completions. Use `bedrock.readTimeout` and `bedrock.connectTimeout` to override these values. +By default, the Bedrock client uses botocore's ~60 second read timeout, which can cause `ReadTimeoutError` on long completions. To override these values, use `bedrock.readTimeout` and `bedrock.connectTimeout`. ```yaml spec: diff --git a/src/app/docs/kagent/supported-providers/gemini/page.mdx b/src/app/docs/kagent/supported-providers/gemini/page.mdx index b970a4c4..4fde4aad 100644 --- a/src/app/docs/kagent/supported-providers/gemini/page.mdx +++ b/src/app/docs/kagent/supported-providers/gemini/page.mdx @@ -50,7 +50,7 @@ Once the resource is applied, you can select the model from the Model dropdown i ## Max output tokens -Use `gemini.maxOutputTokens` to cap the number of tokens the model can generate in a single response. +Use `gemini.maxOutputTokens` to cap the number of tokens that the model can generate in a single response. ```yaml spec: From 232d65a252a7916451a876677a1e19e78b7ba108 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 5 Aug 2026 10:12:57 -0500 Subject: [PATCH 25/31] Add links to other guides in relnotes Signed-off-by: Rachael Graham --- .../kagent/resources/release-notes/page.mdx | 22 +++++++++++++------ .../amazon-bedrock/page.mdx | 2 +- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 3fa3a079..2984c696 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -388,7 +388,7 @@ For details and usage examples, see [Run migrations out-of-band](/docs/kagent/op ## maxOutputTokens for Gemini and Vertex AI -The `maxOutputTokens` field is now wired for the native Gemini and Vertex AI providers. Previously, this field was declared on `GeminiVertexAIConfig` but never applied, and `GeminiConfig` had no such field at all. +The `maxOutputTokens` field is now wired for the native Gemini and Vertex AI providers. Previously, this field was declared on `GeminiVertexAIConfig` but never applied, and `GeminiConfig` did not define this field at all. ```yaml spec: @@ -410,6 +410,8 @@ spec: A per-request value set by the agent always takes precedence over the model-level default. +For more information, see [Gemini](/docs/kagent/supported-providers/gemini#max-output-tokens) and [Vertex AI](/docs/kagent/supported-providers/google-vertexai). + ## AWS Bedrock Guardrails You can now apply native [AWS Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) directly from `ModelConfig`. The controller passes the guardrail configuration to the Bedrock Converse and ConverseStream APIs, enabling content filtering, topic denial, and PII redaction without an external proxy. @@ -432,11 +434,13 @@ spec: | `version` | The guardrail version to apply. Required when the `guardrail` block is present. | | `trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | -On the streaming path, guardrail interventions are applied before content is returned to the caller, so blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, so the agent loop continues. +Guardrail interventions apply before content returns to the caller so that blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, allowing the agent loop to continue. + +For more information, see [Amazon Bedrock — Bedrock Guardrails](/docs/kagent/supported-providers/amazon-bedrock#bedrock-guardrails). ## envFrom for agent deployments -You can now bulk-inject environment variables from ConfigMaps and Secrets into agent pods using the `envFrom` field on the agent deployment spec. This complements the existing `env` field, which requires enumerating individual keys. +You can now bulk-inject environment variables from ConfigMaps and Secrets into agent pods using the `envFrom` field on the agent deployment spec. This field complements the existing `env` field, which requires enumerating individual keys. ```yaml apiVersion: kagent.dev/v1alpha2 @@ -451,15 +455,19 @@ spec: name: my-agent-secrets ``` +For more information, see [Agents — Deployment configuration](/docs/kagent/concepts/agents#deployment-configuration). + ## Disable default ModelConfig -Set `providers: null` in your Helm values to suppress the default `ModelConfig` and its associated `Secret` from being created. This is useful when you manage `ModelConfig` resources outside the kagent Helm chart. +To suppress the default `ModelConfig` and its associated `Secret` from being created, set `providers: null` in your Helm values. This setting is useful when you manage `ModelConfig` resources outside of the kagent Helm chart. ```yaml providers: null ``` -When `providers` is unset or null, neither the `modelconfig` nor the `modelconfig-secret` templates are rendered. Existing installs that supply `providers` are unaffected. +When `providers` is unset or null, neither the `modelconfig` nor the `modelconfig-secret` templates are rendered. Existing installs that define `providers` are unaffected. + +For more information, see [Disable the default ModelConfig](/docs/kagent/introduction/installation#disable-the-default-modelconfig). ## Additional changes in v0.10 @@ -494,7 +502,7 @@ When `providers` is unset or null, neither the `modelconfig` nor the `modelconfi * **Azure OpenAI API key env var name**: The `AZURE_OPENAI_API_KEY` environment variable name is now used consistently throughout the codebase, fixing providers that were reading a mismatched key name. * **OpenTelemetry double-instrumentation fix**: The OpenAI client is no longer double-instrumented on the Go ADK runtime, preventing duplicate spans in OTel traces when using OpenAI with the Go runtime. * **Configurable Bedrock read/connect timeout**: New `bedrock.readTimeout` and `bedrock.connectTimeout` fields on `ModelConfig` replace the ~60s botocore default that caused `ReadTimeoutError` on long completions. Both values are in seconds and are optional. -* **RFC 8707 resource and audience for STS token exchange**: The Go and Python ADK token-propagation plugins now read `KAGENT_STS_RESOURCE` and `KAGENT_STS_AUDIENCE` environment variables to scope issued STS tokens to a specific backend. Backwards compatible — existing deployments are unaffected when neither variable is set. +* **RFC 8707 resource and audience for STS token exchange**: The Go and Python ADK token-propagation plugins now read `KAGENT_STS_RESOURCE` and `KAGENT_STS_AUDIENCE` environment variables to scope issued STS tokens to a specific backend. Backwards compatible so that existing deployments are unaffected when neither variable is set. **Agent Substrate** @@ -521,7 +529,7 @@ When `providers` is unset or null, neither the `modelconfig` nor the `modelconfi * **UI rendering optimization**: Redundant background fetches in the chat interface are reduced, improving rendering performance for long sessions. * **ADK token refresh loop resilience**: Exceptions during token reads in the Python ADK no longer kill the background refresh goroutine. Failed reads are logged and the loop continues on the next cycle instead of silently stopping. * **ACP shim teardown deadlock fix**: Fixed a deadlock where `terminate()` could hang indefinitely when a WebSocket client stalled, blocking the stdout reader goroutine on a full channel and preventing the shim from shutting down. -* **ADK session state with `num_recent_events`**: Fixed a bug where `session.state` was built from only the last N events when `num_recent_events` was set, silently dropping state deltas from older events. Full event history is now always used to compute state; `num_recent_events` only trims the returned events list. +* **ADK session state with `num_recent_events`**: Fixed a bug where `session.state` was built from only the last `n` events when `num_recent_events` was set, silently dropping state deltas from older events. Full event history is now always used to compute state; `num_recent_events` only trims the returned events list. # v0.9 diff --git a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx index 212e5856..846295ee 100644 --- a/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx +++ b/src/app/docs/kagent/supported-providers/amazon-bedrock/page.mdx @@ -128,7 +128,7 @@ spec: | `bedrock.guardrail.version` | The guardrail version to apply. Required when the `guardrail` block is present. | | `bedrock.guardrail.trace` | Trace mode: `disabled` (default), `enabled`, or `enabled_full`. | -Guardrail interventions apply before content returns to the caller so that blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, enabling the agent loop to continue. +Guardrail interventions apply before content returns to the caller so that blocked content does not leak to the stream. Interventions surface in the response content rather than as hard errors, allowing the agent loop to continue. ## Request timeouts From 992ffe6237300feb0d48a2ef7b39f4a47d8be721 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:09:46 -0500 Subject: [PATCH 26/31] Docs for v0.10.0-rc2 release Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 16 +++ .../kagent/introduction/installation/page.mdx | 30 +++++ .../kagent/resources/release-notes/page.mdx | 106 ++++++++++++++++++ .../supported-providers/openai/page.mdx | 14 +++ 4 files changed, 166 insertions(+) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index fa35f954..4cedcbea 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -395,6 +395,22 @@ Here's how you could reference an existing agent (`promql-agent`) as a tool: namespace: other-namespace ``` +### Per-call session isolation + +By default, all calls to the same sub-agent share a single session, which preserves stateful continuity across calls. When a coordinator agent calls the same sub-agent in parallel, shared sessions can cause calls to interfere with each other. + +Set `isolateSessions: true` on the Agent-type tool to give each call its own fresh session, enabling safe parallel fan-out. + +```yaml +spec: + declarative: + tools: + - type: Agent + agent: + name: worker-agent + isolateSessions: true +``` + ### MCP server endpoint A2A-enabled agents are automatically exposed as an MCP server on the kagent controller. The MCP endpoint is available at `/mcp` on the same port as the A2A endpoint (default 8083). diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index e15fd503..7bf65c82 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -387,6 +387,36 @@ controller: Per-agent `nodeSelector` values in the `Agent` spec take precedence over this default. +#### Affinity and topology spread constraints + +Use `affinity` and `topologySpreadConstraints` to control pod scheduling for the controller and UI Deployments. Both fields accept standard Kubernetes scheduling objects. + +```yaml +controller: + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/component: controller + topologyKey: kubernetes.io/hostname + topologySpreadConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: DoNotSchedule + labelSelector: + matchLabels: + app.kubernetes.io/component: controller + +ui: + affinity: {} + topologySpreadConstraints: [] +``` + +When unset, no affinity or spread constraints are applied. + #### Deploy companion resources with extraObjects Use `extraObjects` to deploy arbitrary Kubernetes manifests in the same Helm chart lifecycle as kagent. Entries are rendered through `tpl`, so they can reference the release context. diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index e3a3cd8c..3a1b724d 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -30,6 +30,9 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [A2A AgentCard metadata](#a2a-agentcard-metadata): New optional fields on the Agent spec for enriching the A2A AgentCard. * [maxOutputTokens for Gemini and Vertex AI](#maxoutputtokens-for-gemini-and-vertex-ai): New `maxOutputTokens` field on Gemini and Vertex AI providers for capping model output length. * [AWS Bedrock Guardrails](#aws-bedrock-guardrails): Native guardrail support for the Bedrock provider, enabling content filtering, topic denial, and PII redaction. +* [Azure AI Foundry](#azure-ai-foundry): New provider for Azure AI Foundry models with Go ADK runtime support and Azure Workload Identity authentication. +* [OpenAI Responses API](#openai-responses-api): New `openAI.apiFormat: responses` field switches the harness to use the OpenAI Responses API instead of Chat Completions. +* [Per-call session isolation for Agent tools](#per-call-session-isolation-for-agent-tools): New `isolateSessions` flag gives each call to a sub-agent its own fresh session, enabling safe parallel fan-out. **Helm & configuration** @@ -47,6 +50,7 @@ Review this summary of significant changes from kagent version 0.9 to v0.10. * [nodeSelector for agent Helm charts](#nodeselector-for-agent-helm-charts): New `nodeSelector` value in every bundled agent Helm chart for pinning agent pods to specific node pools. * [envFrom for agent deployments](#envfrom-for-agent-deployments): New `envFrom` field on the agent deployment spec for bulk-injecting environment variables from ConfigMaps and Secrets. * [Disable default ModelConfig](#disable-default-modelconfig): Set `providers: null` to suppress the Helm-generated default `ModelConfig` and `Secret`. +* [Affinity and topologySpreadConstraints](#affinity-and-topologyspreadconstraints): New `controller.affinity`, `controller.topologySpreadConstraints`, `ui.affinity`, and `ui.topologySpreadConstraints` Helm values for advanced pod scheduling. **Agent Substrate** @@ -469,11 +473,110 @@ When `providers` is unset or null, neither the `modelconfig` nor the `modelconfi For more information, see [Disable the default ModelConfig](/docs/kagent/introduction/installation#disable-the-default-modelconfig). +## Azure AI Foundry + +[Azure AI Foundry](https://ai.azure.com/) is now a supported `ModelConfig` provider. The Foundry provider uses the Azure AI Inference SDK and supports both API key authentication and Azure Workload Identity (`DefaultAzureCredential`) when no key is configured. Only the Go declarative runtime is supported; the controller rejects other runtimes. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: ModelConfig +metadata: + name: foundry-model-config + namespace: kagent +spec: + provider: Foundry + model: gpt-5.4-mini + foundry: + endpoint: https://my-hub.services.ai.azure.com/models + deployment: my-deployment + apiVersion: "2025-01-01-preview" +``` + +To authenticate with an API key, create a Kubernetes Secret with the key stored as `FOUNDRY_API_KEY` and reference it via `spec.apiKeySecret`. To use Azure Workload Identity instead, omit `apiKeySecret` and annotate the agent's ServiceAccount with the appropriate IAM role. + +| Field | Description | +|---|---| +| `foundry.endpoint` | The Azure AI Foundry endpoint URL. | +| `foundry.endpointFrom` | Reference to a ConfigMap key containing the endpoint URL. Use with Azure Service Operator to inject the endpoint without hardcoding it. | +| `foundry.deployment` | The deployment name within the Foundry project. | +| `foundry.apiVersion` | The Azure AI Inference API version (for example, `2025-01-01-preview`). | + +Memory embeddings are supported and use 768-dimensional vectors. Anthropic (Claude) models on Foundry are not yet supported. + +For more information, see [Azure AI Foundry](/docs/kagent/supported-providers/azure-ai-foundry). + +## OpenAI Responses API + +You can now switch the harness to use the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) instead of Chat Completions by setting `openAI.apiFormat: responses` on a `ModelConfig`. This is also compatible with gateways such as AgentGateway that expose the Responses API. + +```yaml +spec: + provider: OpenAI + model: gpt-5.4-mini + openAI: + apiFormat: responses +``` + +Omit `apiFormat` (or set it to `chat`) to continue using Chat Completions, which remains the default. Native tool use and stateful Responses API chaining are not yet supported. + +For more information, see [OpenAI — Responses API](/docs/kagent/supported-providers/openai#responses-api). + +## Per-call session isolation for Agent tools + +When a coordinator agent calls the same sub-agent in parallel, all calls previously shared a single session, causing them to interfere with each other. Setting `isolateSessions: true` on an Agent-type tool gives each call its own fresh `context_id`, enabling safe parallel fan-out. + +```yaml +spec: + declarative: + tools: + - type: Agent + agent: + name: worker-agent + isolateSessions: true +``` + +The default (`isolateSessions: false`) preserves the existing behavior where calls to the same sub-agent share a session for stateful continuity. + +For more information, see [Agents — Per-call session isolation](/docs/kagent/concepts/agents#per-call-session-isolation). + +## Affinity and topologySpreadConstraints + +New Helm values let you configure pod affinity rules and topology spread constraints for the controller and UI Deployments. + +```yaml +controller: + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/component: controller + topologyKey: kubernetes.io/hostname + topologySpreadConstraints: + - maxSkew: 1 + topologyKey: topology.kubernetes.io/zone + whenUnsatisfiable: DoNotSchedule + labelSelector: + matchLabels: + app.kubernetes.io/component: controller + +ui: + affinity: {} + topologySpreadConstraints: [] +``` + +Both fields accept standard Kubernetes scheduling objects. When unset, no affinity or spread constraints are applied and existing behavior is unchanged. + +For more information, see [Installing kagent — Affinity and topology spread constraints](/docs/kagent/introduction/installation#affinity-and-topology-spread-constraints). + ## Additional changes in v0.10 **Security** * **CVE patches**: Critical and high CVEs patched in the Go ADK and app container images. +* **Python dependency CVE patches**: `aiohttp` bumped to 3.14.3 (CVE-2026-69244) and `cryptography` bumped to 50.0.0 (CVE-2026-69247) in the Python ADK container images. * **A2A task security scoping**: Task `get`, `create`, and `delete` operations are now scoped to the session owner, preventing one user from accessing another user's A2A tasks. **Helm and configuration** @@ -487,6 +590,7 @@ For more information, see [Disable the default ModelConfig](/docs/kagent/introdu * **oauth2-proxy subchart updated to ~10.7.0**: The bundled oauth2-proxy dependency is bumped to the 10.7.x chart series. * **Custom annotations on the default ModelConfig**: A new per-provider `annotations` map under `providers..annotations` is applied to the Helm-generated default ModelConfig. Useful for downstream tooling or UI extensions that key off resource annotations. * **`deploymentAnnotations` for agent deployments**: New `deploymentAnnotations` field on the agent deployment spec sets annotations on the Deployment object itself. The existing `annotations` field targets pod template metadata only. Useful for GitOps tooling such as Argo CD sync waves, Flux, and Kyverno policies that key off Deployment-level annotations. +* **pgx connection pool tuning**: New Helm values configure the idle connection timeout and check period for the PostgreSQL pgx driver, so that idle database connections are closed after a configurable period rather than held indefinitely. **Agent runtimes and providers** @@ -530,6 +634,8 @@ For more information, see [Disable the default ModelConfig](/docs/kagent/introdu * **ADK token refresh loop resilience**: Exceptions during token reads in the Python ADK no longer kill the background refresh goroutine. Failed reads are logged and the loop continues on the next cycle instead of silently stopping. * **ACP shim teardown deadlock fix**: Fixed a deadlock where `terminate()` could hang indefinitely when a WebSocket client stalled, blocking the stdout reader goroutine on a full channel and preventing the shim from shutting down. * **ADK session state with `num_recent_events`**: Fixed a bug where `session.state` was built from only the last `n` events when `num_recent_events` was set, silently dropping state deltas from older events. Full event history is now always used to compute state; `num_recent_events` only trims the returned events list. +* **Session sharing nil pointer fix**: Fixed a nil pointer panic on session sharing endpoints caused by `SessionSharesHandler` not being initialized at startup. +* **OTel traces no longer sent to api.openai.com**: The Python ADK no longer forwards traces to OpenAI's hardcoded endpoint by default, preventing key leakage for proxy or gateway deployments. Set `KAGENT_OPENAI_AGENTS_NATIVE_TRACING=true` to restore the original behavior. # v0.9 diff --git a/src/app/docs/kagent/supported-providers/openai/page.mdx b/src/app/docs/kagent/supported-providers/openai/page.mdx index 8bc84f51..789ac57d 100644 --- a/src/app/docs/kagent/supported-providers/openai/page.mdx +++ b/src/app/docs/kagent/supported-providers/openai/page.mdx @@ -71,3 +71,17 @@ spec: ``` For standard (non-reasoning) models and OpenAI-compatible endpoints, `openAI.maxTokens` continues to work as before. The two fields are independent. + +## Responses API + +By default, kagent uses the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). To switch to the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) instead, set `openAI.apiFormat: responses` on the `ModelConfig`. This is also compatible with gateways such as AgentGateway that expose the Responses API. + +```yaml +spec: + provider: OpenAI + model: gpt-4o + openAI: + apiFormat: responses +``` + +Omit `apiFormat` (or set it to `chat`) to continue using Chat Completions. Native tool use and stateful Responses API chaining are not yet supported. From f03e9b6cbdbb62a85128177cdb0fbca6d24262c5 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:26:03 -0500 Subject: [PATCH 27/31] style review Signed-off-by: Rachael Graham --- .../kagent/concepts/agent-substrate/page.mdx | 12 ++++++------ src/app/docs/kagent/concepts/agents/page.mdx | 18 +++++++++--------- .../kagent/introduction/installation/page.mdx | 16 ++++++++-------- .../operational-considerations/page.mdx | 2 +- .../docs/kagent/operations/upgrade/page.mdx | 2 +- .../kagent/supported-providers/gemini/page.mdx | 4 +--- .../kagent/supported-providers/openai/page.mdx | 6 ++---- 7 files changed, 28 insertions(+), 32 deletions(-) diff --git a/src/app/docs/kagent/concepts/agent-substrate/page.mdx b/src/app/docs/kagent/concepts/agent-substrate/page.mdx index 523382da..f1df32cd 100644 --- a/src/app/docs/kagent/concepts/agent-substrate/page.mdx +++ b/src/app/docs/kagent/concepts/agent-substrate/page.mdx @@ -12,7 +12,7 @@ export const metadata = { # Agent Substrate -Agent Substrate is a Kubernetes-native runtime for running AI agents and other stateful workloads efficiently. Instead of dedicating one pod per agent — which wastes capacity while agents sit idle — Substrate decouples an agent's lifecycle from pod infrastructure. Idle agents are snapshotted to object storage and rehydrated on demand, so a small pool of pre-warmed workers can host far more agents than there are pods. +Agent Substrate is a Kubernetes-native runtime for running AI agents and other stateful workloads efficiently. Instead of dedicating one pod per agent, which wastes capacity while agents sit idle, Substrate decouples an agent's lifecycle from pod infrastructure. Idle agents are snapshotted to object storage and rehydrated on demand, so a small pool of pre-warmed workers can host far more agents than there are pods. kagent can run workloads on Agent Substrate in two ways: @@ -21,10 +21,10 @@ kagent can run workloads on Agent Substrate in two ways: ## Why Agent Substrate -- **Fast startup** — Agents cold-start by restoring a compressed snapshot rather than booting a fresh pod, so they resume in a fraction of the time. -- **Efficient resource usage** — A pool of pre-warmed workers multiplexes many actors across far fewer pods, persisting idle actors to object storage instead of holding a pod each. -- **Secure execution** — Each workload runs inside a gVisor sandbox, isolating untrusted agent code from the host and from other actors. -- **Declarative management** — WorkerPools and ActorTemplates are Kubernetes CRDs, so the runtime is configured and versioned with the same GitOps workflow as the rest of your platform. +- **Fast startup**: Agents cold-start by restoring a compressed snapshot rather than booting a fresh pod, so they resume in a fraction of the time. +- **Efficient resource usage**: A pool of pre-warmed workers multiplexes many actors across far fewer pods, persisting idle actors to object storage instead of holding a pod each. +- **Secure execution**: Each workload runs inside a gVisor sandbox, isolating untrusted agent code from the host and from other actors. +- **Declarative management**: WorkerPools and ActorTemplates are Kubernetes CRDs, so the runtime is configured and versioned with the same GitOps workflow as the rest of your platform. ## Core concepts @@ -38,7 +38,7 @@ kagent can run workloads on Agent Substrate in two ways: ## How it works -When an agent is invoked, Substrate restores its actor onto an available worker from the WorkerPool — rehydrating from a snapshot if the actor was idle. The agent runs inside a gVisor sandbox for the duration of the session. When the actor goes idle, its state is checkpointed back to object storage and the worker is freed to host another actor. This snapshot-and-restore cycle is what lets a single worker pool serve many more agents than a pod-per-agent model. +When an agent is invoked, Substrate restores its actor onto an available worker from the WorkerPool, rehydrating from a snapshot if the actor was idle. The agent runs inside a gVisor sandbox for the duration of the session. When the actor goes idle, its state is checkpointed back to object storage and the worker is freed to host another actor. This snapshot-and-restore cycle is what lets a single worker pool serve many more agents than a pod-per-agent model. ## Architecture diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 4cedcbea..68fb627f 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -23,7 +23,7 @@ Each agent consists of the following components: ## Agent Instructions -Agent instructions tell the agent what its role is, how to interact with the user, what actions it can take, how to behave and respond to user queries, and how to interact with other agents. Here's an example of simple agent instructions: +Agent instructions tell the agent what its role is, how to interact with the user, what actions it can take, how to behave and respond to user queries, and how to interact with other agents. The following example shows simple agent instructions: ```yaml You're a Kubernetes agent that can help users manage their Kubernetes resources. @@ -32,7 +32,7 @@ Your responses should be clear and concise; you should provide helpful informati Instructions are an important part of the agent's behavior. They define the agent's role and capabilities and help the agent understand its environment and the tasks it can perform. -Writing good instructions is an art and a science. It requires a good understanding of the task at hand, the tools available, and the user's needs. In order to make it easier to write good instructions, we've created a [system prompt tutorial](/docs/kagent/getting-started/system-prompts) that can help you get started. +Writing good instructions is an art and a science. It requires a good understanding of the task at hand, the tools available, and the user's needs. To help you write good instructions, see the [system prompt tutorial](/docs/kagent/getting-started/system-prompts). ### Prompt templates @@ -94,13 +94,13 @@ Tools are functions that the agent can use to interact with its environment. For Tools definitions and their descriptions are made available to the agent and are sent to the LLMs together with the instructions. Based on the user query, the agent can use the tools to interact with the environment and generate responses. -For example, we could add the **list_resources** tool to agent that would allow it to list resources in the Kubernetes cluster. The agent will determine based on the user input if it makes sense to invoke any of the available tools. +For example, add the **list_resources** tool to your agent to allow it to list resources in the Kubernetes cluster. The agent determines, based on user input, whether to invoke any available tools. -If the user asks "List all pods in the cluster", the agent can use the **list_resources** tool to list all pods in the cluster. Note that depending on how the instructions/tools are written and configure, the agent might list all the namespaces first then list all the pods in each namespace. Alternatively, if the **list_resources** tool allows listing resources across namespaces, the agent will pick that option. +If the user asks "List all pods in the cluster", the agent can use the **list_resources** tool to list all pods in the cluster. Depending on how the instructions and tools are configured, the agent might list all namespaces first, then list all pods in each namespace. Alternatively, if the **list_resources** tool allows listing resources across namespaces, the agent picks that option. -Some tools support additional configuration that can be set in when adding the tool to the agent. For example, any Grafana or Prometheus tools will require an API endpoint URL to be set. +Some tools support additional configuration that you set when adding the tool to the agent. For example, any Grafana or Prometheus tools will require an API endpoint URL to be set. -kagent comes with a set of built-in tools that you can use to interact with your environment. kagent also supports the [MCP (Model Configuration Protocol)](https://modelcontextprotocol.io/introduction) tools. Using MCP, you can bring any external tool into kagent and make it available for your agents to run. +kagent comes with a set of built-in tools that you can use to interact with your environment. kagent also supports [MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) tools. Using MCP, you can bring any external tool into kagent and make it available for your agents to run. ## Human-in-the-Loop @@ -157,7 +157,7 @@ Skills can refer to two broad types: ### A2A skills metadata -Actions-to-actions (A2A) skills are metadata—structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do. +Actions-to-actions (A2A) skills are metadata-structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do. A2A skills metadata describes: @@ -261,7 +261,7 @@ spec: systemMessage: "You are a helpful agent." ``` -**Choose Go when** fast startup matters (autoscaling, cold starts), lower resource consumption is important, or you don't need Python-specific framework integrations. +**Choose Go when** fast startup matters (autoscaling, cold starts), lower resource consumption is important, or you do not need Python-specific framework integrations. **Choose Python when** you need Google ADK-native features, CrewAI/LangGraph/OpenAI framework integrations, or Python-based custom tools. @@ -369,7 +369,7 @@ spec: kagent also supports using agents as tools. Any agent you create can be referenced and used by other agents you have. An example use case would be to have a PromQL agent that knows how to create PromQL queries from natural language. Then you'd create a second agent that would use the PromQL agent whenever it needs to create a PromQL query. -Here's how you could reference an existing agent (`promql-agent`) as a tool: +The following example shows how to reference an existing agent (`promql-agent`) as a tool: ```yaml ... diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 7bf65c82..d35f04a8 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -14,7 +14,7 @@ export const metadata = { # Installing kagent -This guide covers ways to install and configure kagent in your Kubernetes environment. For a quick setup, check out our [Quick Start Guide](/docs/kagent/getting-started/quickstart). For enterpise offerings, check out [Solo Enterprise for kagent](/docs/kagent/introduction/what-is-kagent/#enterprise-distributions). +This guide covers ways to install and configure kagent in your Kubernetes environment. For a quick setup, see the [Quick Start Guide](/docs/kagent/getting-started/quickstart). For enterprise offerings, see [Solo Enterprise for kagent](/docs/kagent/introduction/what-is-kagent/#enterprise-distributions). ## Installation Methods @@ -52,7 +52,7 @@ Install kagent by using the kagent CLI or Helm. kagent installed successfully ``` -4. Optionally: Open the kagent dashboard. +4. Optional: Open the kagent dashboard. ```bash kagent dashboard ``` @@ -96,7 +96,7 @@ Another way to install kagent is using Helm. --set providers.openAI.apiKey=$OPENAI_API_KEY ``` -5. Optionally: Port-forward the kagent UI on port 8080. +5. Optional: Port-forward the kagent UI on port 8080. ```bash kubectl port-forward -n kagent svc/kagent-ui 8080:8080 ``` @@ -120,7 +120,7 @@ Another way to install kagent is using Helm. --set providers.anthropic.apiKey=$ANTHROPIC_API_KEY ``` -5. Optionally: Port-forward the kagent UI on port 8080. +5. Optional: Port-forward the kagent UI on port 8080. ```bash kubectl port-forward -n kagent svc/kagent-ui 8080:8080 ``` @@ -144,7 +144,7 @@ Another way to install kagent is using Helm. --set providers.azureOpenAI.apiKey=$OPENAI_API_KEY ``` -5. Optionally: Port-forward the kagent UI on port 8080. +5. Optional: Port-forward the kagent UI on port 8080. ```bash kubectl port-forward -n kagent svc/kagent-ui 8080:8080 ``` @@ -169,7 +169,7 @@ Another way to install kagent is using Helm. --set providers.gemini.apiKey=$GEMINI_API_KEY ``` -5. Optionally: Port-forward the kagent UI on port 8080. +5. Optional: Port-forward the kagent UI on port 8080. ```bash kubectl port-forward -n kagent svc/kagent-ui 8080:8080 ``` @@ -187,7 +187,7 @@ Another way to install kagent is using Helm. --set providers.default=ollama ``` -4. Optionally: Port-forward the kagent UI on port 8080. +4. Optional: Port-forward the kagent UI on port 8080. ```bash kubectl port-forward -n kagent svc/kagent-ui 8080:8080 ``` @@ -242,7 +242,7 @@ Review the following advanced configuration options that you might want to set u --set substrateWorkerPool.replicas=1 ``` - Pin the kagent chart to v0.9.9 or later — earlier versions do not include the `controller.substrate.*` and `substrateWorkerPool.*` values. + Pin the kagent chart to v0.9.9 or later. Earlier versions do not include the `controller.substrate.*` and `substrateWorkerPool.*` values. For an end-to-end walkthrough on a kind cluster, see the [Agent Substrate example](/docs/kagent/examples/agent-substrate). For more information about creating harness resources, see [Agent Harness](/docs/kagent/examples/agent-harness). diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index e809a64b..616802ad 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -92,7 +92,7 @@ urlFile > url > bundled connection string | External DB, bundled pod kept running | `true` | set | yes | external | | Bundled disabled, no external set | `false` | unset | no | error (misconfigured) | -**Migration**: This means that you can keep the bundled pod running while the controller points at an external database, which is useful for migrating data. +**Migration**: You can keep the bundled pod running while the controller points at an external database, which is useful for migrating data. ### Bundled PostgreSQL diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index 2d3f757c..aa63a5a0 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -35,7 +35,7 @@ Follow these steps to upgrade kagent to the latest version and keep your cluster 4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9-specific upgrades related to database migrations and RBAC scope. -5. **v0.10.0 and later — mirror registry operators**: If you mirror kagent images and previously relied on `agentImage` alone, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. In v0.10, the controller no longer derives the Go image location from the Python image path. If `controller.goAgentImage` is unset and you overrode `agentImage`, the controller will fall back to pulling `ghcr.io/kagent-dev/kagent/golang-adk` directly. The controller logs a startup warning when the two registries differ. For details, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). +5. **v0.10.0 and later, mirror registry operators**: If you mirror kagent images and previously relied on `agentImage` alone, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. In v0.10, the controller no longer derives the Go image location from the Python image path. If `controller.goAgentImage` is unset and you overrode `agentImage`, the controller will fall back to pulling `ghcr.io/kagent-dev/kagent/golang-adk` directly. The controller logs a startup warning when the two registries differ. For details, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). ## Upgrade kagent diff --git a/src/app/docs/kagent/supported-providers/gemini/page.mdx b/src/app/docs/kagent/supported-providers/gemini/page.mdx index 4fde4aad..826dc070 100644 --- a/src/app/docs/kagent/supported-providers/gemini/page.mdx +++ b/src/app/docs/kagent/supported-providers/gemini/page.mdx @@ -26,9 +26,7 @@ Make sure that your Google Cloud account has a project with the Gemini API enabl kubectl create secret generic kagent-gemini -n kagent --from-literal GOOGLE_API_KEY= ``` -3. Create a ModelConfig resource using the `Gemini` provider. - -You can find out the latest model names and capabilities on the [Gemini API docs](https://ai.google.dev/gemini-api/docs/models). Once you have chosen a model, replace the `model` field with the name such as `gemini-2.5-pro`. +3. Create a `ModelConfig` resource using the `Gemini` provider. You can find the latest model names and capabilities on the [Gemini API docs](https://ai.google.dev/gemini-api/docs/models). Replace the `model` field with your chosen model name, such as `gemini-2.5-pro`. ```yaml apiVersion: kagent.dev/v1alpha2 diff --git a/src/app/docs/kagent/supported-providers/openai/page.mdx b/src/app/docs/kagent/supported-providers/openai/page.mdx index 789ac57d..87f47ac7 100644 --- a/src/app/docs/kagent/supported-providers/openai/page.mdx +++ b/src/app/docs/kagent/supported-providers/openai/page.mdx @@ -19,7 +19,7 @@ export OPENAI_API_KEY= kubectl create secret generic kagent-openai -n kagent --from-literal OPENAI_API_KEY=$OPENAI_API_KEY ``` -2. Create a ModelConfig resource that references the secret and key name: +2. Create a `ModelConfig` resource that references the secret and key name. For standard models such as GPT-4 and GPT-3.5, kagent automatically configures the appropriate model capabilities. ```yaml apiVersion: kagent.dev/v1alpha2 @@ -35,9 +35,7 @@ spec: openAI: {} ``` -For OpenAI's standard models like GPT-4 and GPT-3.5, kagent automatically configures the appropriate model capabilities. - -3. Apply the above resource to the cluster. +3. Apply the resource to the cluster. Once the resource is applied, you can select the model from the Model dropdown in the UI when creating or updating agents. From 803eb02caa7db0557dfcfc2865d0754f0ff37951 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:34:21 -0500 Subject: [PATCH 28/31] =?UTF-8?q?fix:=20A2A=20skills=20metadata=20sentence?= =?UTF-8?q?=20=E2=80=94=20colon=20not=20hyphen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rachael Graham --- src/app/docs/kagent/concepts/agents/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 68fb627f..33f6afbd 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -157,7 +157,7 @@ Skills can refer to two broad types: ### A2A skills metadata -Actions-to-actions (A2A) skills are metadata-structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do. +Actions-to-actions (A2A) skills are metadata: structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do. A2A skills metadata describes: From 4c54fd6c04d0c78363014ea19f1f43096b0397f7 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:34:27 -0500 Subject: [PATCH 29/31] =?UTF-8?q?fix:=20correct=20apiFormat=20enum=20value?= =?UTF-8?q?=20=E2=80=94=20chatCompletions=20not=20chat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rachael Graham --- src/app/docs/kagent/resources/release-notes/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 3a1b724d..cbbb1bfb 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -517,7 +517,7 @@ spec: apiFormat: responses ``` -Omit `apiFormat` (or set it to `chat`) to continue using Chat Completions, which remains the default. Native tool use and stateful Responses API chaining are not yet supported. +Omit `apiFormat` (or set it to `chatCompletions`) to continue using Chat Completions, which remains the default. Native tool use and stateful Responses API chaining are not yet supported. For more information, see [OpenAI — Responses API](/docs/kagent/supported-providers/openai#responses-api). From b3acd626fed7b6797b5a4413f0d7cdfd9c08df66 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:34:34 -0500 Subject: [PATCH 30/31] =?UTF-8?q?fix:=20correct=20apiFormat=20enum=20value?= =?UTF-8?q?=20=E2=80=94=20chatCompletions=20not=20chat?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rachael Graham --- src/app/docs/kagent/supported-providers/openai/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/supported-providers/openai/page.mdx b/src/app/docs/kagent/supported-providers/openai/page.mdx index 87f47ac7..54b2dad3 100644 --- a/src/app/docs/kagent/supported-providers/openai/page.mdx +++ b/src/app/docs/kagent/supported-providers/openai/page.mdx @@ -82,4 +82,4 @@ spec: apiFormat: responses ``` -Omit `apiFormat` (or set it to `chat`) to continue using Chat Completions. Native tool use and stateful Responses API chaining are not yet supported. +Omit `apiFormat` (or set it to `chatCompletions`) to continue using Chat Completions. Native tool use and stateful Responses API chaining are not yet supported. From b0b1bcaedda9d115e5fce904015e00c69c024c90 Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Wed, 12 Aug 2026 10:34:37 -0500 Subject: [PATCH 31/31] fix: use parentheses not comma for mirror registry qualifier Signed-off-by: Rachael Graham --- src/app/docs/kagent/operations/upgrade/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/operations/upgrade/page.mdx b/src/app/docs/kagent/operations/upgrade/page.mdx index aa63a5a0..01a33601 100644 --- a/src/app/docs/kagent/operations/upgrade/page.mdx +++ b/src/app/docs/kagent/operations/upgrade/page.mdx @@ -35,7 +35,7 @@ Follow these steps to upgrade kagent to the latest version and keep your cluster 4. **v0.9.0 and later**: You must be running at least v0.8.0 before upgrading to v0.9.0. Check the [release notes](/docs/kagent/resources/release-notes#v09) for 0.9-specific upgrades related to database migrations and RBAC scope. -5. **v0.10.0 and later, mirror registry operators**: If you mirror kagent images and previously relied on `agentImage` alone, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. In v0.10, the controller no longer derives the Go image location from the Python image path. If `controller.goAgentImage` is unset and you overrode `agentImage`, the controller will fall back to pulling `ghcr.io/kagent-dev/kagent/golang-adk` directly. The controller logs a startup warning when the two registries differ. For details, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). +5. **v0.10.0 and later (mirror registry operators)**: If you mirror kagent images and previously relied on `agentImage` alone, you must now also set `controller.goAgentImage` to point to your mirrored Go ADK image. In v0.10, the controller no longer derives the Go image location from the Python image path. If `controller.goAgentImage` is unset and you overrode `agentImage`, the controller will fall back to pulling `ghcr.io/kagent-dev/kagent/golang-adk` directly. The controller logs a startup warning when the two registries differ. For details, see [Private registry and image mirroring](/docs/kagent/introduction/installation#private-registry-and-image-mirroring). ## Upgrade kagent