From 7e8713399bd4c231124fbe9db395bd2e95f736d5 Mon Sep 17 00:00:00 2001 From: Rachael-Graham <29711887+Rachael-Graham@users.noreply.github.com> Date: Fri, 6 Nov 2026 17:10:18 +0000 Subject: [PATCH 1/5] docs: Update kagent 1.x reference docs at v1.0.0-rc3 Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../assets/kagent-docs/versions/agent-substrate-chart.md | 2 +- docs-site/assets/kagent-docs/versions/agent-substrate.md | 2 +- docs-site/assets/kagent-docs/versions/kagent.md | 2 +- .../assets/kagent-docs/versions/runtime-image-claude.md | 2 +- .../assets/kagent-docs/versions/runtime-image-codex.md | 2 +- docs-site/assets/kagent-docs/versions/runtime-image.md | 2 +- docs-site/content/kagent/1.x/reference/cli/_index.md | 2 +- .../kagent/1.x/reference/cli/kagent-agent-session-delete.md | 1 + .../content/kagent/1.x/reference/cli/kagent-uninstall.md | 6 ++++++ docs-site/content/kmcp/reference/cli/_index.md | 2 +- 10 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs-site/assets/kagent-docs/versions/agent-substrate-chart.md b/docs-site/assets/kagent-docs/versions/agent-substrate-chart.md index 12c42733..5825a1e0 100644 --- a/docs-site/assets/kagent-docs/versions/agent-substrate-chart.md +++ b/docs-site/assets/kagent-docs/versions/agent-substrate-chart.md @@ -1 +1 @@ -{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}1.0.0-rc2{{< /version >}} \ No newline at end of file +{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}1.0.0{{< /version >}} \ No newline at end of file diff --git a/docs-site/assets/kagent-docs/versions/agent-substrate.md b/docs-site/assets/kagent-docs/versions/agent-substrate.md index 12c42733..5825a1e0 100644 --- a/docs-site/assets/kagent-docs/versions/agent-substrate.md +++ b/docs-site/assets/kagent-docs/versions/agent-substrate.md @@ -1 +1 @@ -{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}1.0.0-rc2{{< /version >}} \ No newline at end of file +{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}1.0.0{{< /version >}} \ No newline at end of file diff --git a/docs-site/assets/kagent-docs/versions/kagent.md b/docs-site/assets/kagent-docs/versions/kagent.md index e76f7889..b43ee542 100644 --- a/docs-site/assets/kagent-docs/versions/kagent.md +++ b/docs-site/assets/kagent-docs/versions/kagent.md @@ -1 +1 @@ -{{< version include-if="0.x" >}}0.10.6{{< /version >}}{{< version include-if="1.x" >}}1.0.0-rc2{{< /version >}} \ No newline at end of file +{{< version include-if="0.x" >}}0.10.6{{< /version >}}{{< version include-if="1.x" >}}1.0.0-rc3{{< /version >}} \ No newline at end of file diff --git a/docs-site/assets/kagent-docs/versions/runtime-image-claude.md b/docs-site/assets/kagent-docs/versions/runtime-image-claude.md index 9bddf8cb..cea7a5f2 100644 --- a/docs-site/assets/kagent-docs/versions/runtime-image-claude.md +++ b/docs-site/assets/kagent-docs/versions/runtime-image-claude.md @@ -1 +1 @@ -ghcr.io/kagent-dev/kagent/claude-harness@sha256:c61047f0a9000f207c597beae15207622a08f2c79323d51e1d36d39f812c9a5d \ No newline at end of file +ghcr.io/kagent-dev/kagent/claude-harness@sha256:216613bf155d3d437765675144fee19c9045cb21cd2e481189f2dcae36c24b3b \ No newline at end of file diff --git a/docs-site/assets/kagent-docs/versions/runtime-image-codex.md b/docs-site/assets/kagent-docs/versions/runtime-image-codex.md index e84c381d..a8cad088 100644 --- a/docs-site/assets/kagent-docs/versions/runtime-image-codex.md +++ b/docs-site/assets/kagent-docs/versions/runtime-image-codex.md @@ -1 +1 @@ -ghcr.io/kagent-dev/kagent/codex-harness@sha256:183f447a7be6536ac12f2778e7cd6cedc7013c605c5706ecb673738c3db5844b \ No newline at end of file +ghcr.io/kagent-dev/kagent/codex-harness@sha256:84c3275e36c0d98472a8b930a628e47e08277e7ce4438908e2a44fd1d8a9efd2 \ No newline at end of file diff --git a/docs-site/assets/kagent-docs/versions/runtime-image.md b/docs-site/assets/kagent-docs/versions/runtime-image.md index 2246cf08..d13f3e60 100644 --- a/docs-site/assets/kagent-docs/versions/runtime-image.md +++ b/docs-site/assets/kagent-docs/versions/runtime-image.md @@ -1 +1 @@ -ghcr.io/kagent-dev/kagent/golang-adk@sha256:1f2f72c1743dad076beb4a7d12c1d6313f3814ec5ab56204c99783747a8451bc \ No newline at end of file +ghcr.io/kagent-dev/kagent/golang-adk@sha256:51859027b42b704c8f443876ef5155ace2f411752f297e5cb43e04d9b91545b7 \ No newline at end of file diff --git a/docs-site/content/kagent/1.x/reference/cli/_index.md b/docs-site/content/kagent/1.x/reference/cli/_index.md index 730a3be0..8cb13b5c 100644 --- a/docs-site/content/kagent/1.x/reference/cli/_index.md +++ b/docs-site/content/kagent/1.x/reference/cli/_index.md @@ -4,7 +4,7 @@ description: Review the reference docs for the kagent CLI commands. weight: 30 --- -Review the kagent CLI commands and learn how to use them effectively. +Review the commands and flags of the kagent CLI. - [`kagent agent`]({{< link path="reference/cli/kagent-agent" >}}) - Discover agents and work with their conversations - [`kagent apply`]({{< link path="reference/cli/kagent-apply" >}}) - Create or update an Agent or AgentTemplate diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-delete.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-delete.md index 3b8f1496..fe641831 100644 --- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-delete.md +++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-delete.md @@ -11,6 +11,7 @@ kagent agent session delete ID [flags] ``` **Flags:** +- `--force` - Terminate ongoing turns and delete the Session - `-h, --help` - help for delete **Global Flags:** diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md b/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md index 6bb42108..e0c3109a 100644 --- a/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md +++ b/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md @@ -12,11 +12,17 @@ resource created from them, such as agents and model configs. A database that kagent install did not deploy, such as one used with --skip-database-setup, stays. The kagent namespace stays. +Self-managed Substrate WorkerPools, ones kagent install did not create, run on +the Substrate that uninstall removes. Uninstall lists them and asks before +deleting them. Without a terminal it stops before deleting anything unless +--delete-worker-pools is set. + ```bash kagent uninstall [flags] ``` **Flags:** +- `--delete-worker-pools` - Delete self-managed Substrate WorkerPools without asking - `-h, --help` - help for uninstall **Global Flags:** diff --git a/docs-site/content/kmcp/reference/cli/_index.md b/docs-site/content/kmcp/reference/cli/_index.md index 33b2534a..9bc1cd72 100644 --- a/docs-site/content/kmcp/reference/cli/_index.md +++ b/docs-site/content/kmcp/reference/cli/_index.md @@ -4,7 +4,7 @@ description: Review the reference docs for the kmcp CLI commands. weight: 1 --- -Review the kmcp CLI commands and learn how to use them effectively. +Review the commands and flags of the kmcp CLI. - [`kmcp add-tool`](/docs/kmcp/reference/cli/kmcp-add-tool/) - Add a new MCP tool to your project - [`kmcp build`](/docs/kmcp/reference/cli/kmcp-build/) - Build MCP server as a Docker image From bf3abe524791bff5b91aee1f36c6d1ba993a859e Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Fri, 6 Nov 2026 11:12:18 -0600 Subject: [PATCH 2/5] Update debug.md Signed-off-by: Rachael Graham --- docs-site/content/kagent/1.x/operations/debug.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs-site/content/kagent/1.x/operations/debug.md b/docs-site/content/kagent/1.x/operations/debug.md index f6696189..6a707203 100644 --- a/docs-site/content/kagent/1.x/operations/debug.md +++ b/docs-site/content/kagent/1.x/operations/debug.md @@ -180,7 +180,6 @@ The controller applies the database migrations of the new version when it starts --db-url "postgresql://:@:5432/kagent" \ --db-role ``` - * Restore the database backup that you took in [Prepare to upgrade]({{< link path="operations/upgrade#prepare-to-upgrade" >}}). ## Collect logs From 68bf6836f47a4ef2dd9e9def8642550b174558ac Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Fri, 6 Nov 2026 11:33:21 -0600 Subject: [PATCH 3/5] docs changes for rc3 Signed-off-by: Rachael Graham --- .../content/kagent/1.x/about/core-concepts.md | 2 + .../1.x/about/substrate-runtime/identity.md | 4 +- .../kagent/1.x/agents/agent-harness.md | 6 ++- .../kagent/1.x/agents/bring-your-own-agent.md | 40 ++++++++++++------- .../kagent/1.x/agents/egress-policies.md | 2 +- .../content/kagent/1.x/examples/a2a-byo.md | 4 +- .../kagent/1.x/examples/agents-via-mcp.md | 31 ++++++++++---- .../kagent/1.x/observability/tracing.md | 2 +- .../kagent/1.x/operations/uninstall.md | 4 +- 9 files changed, 64 insertions(+), 31 deletions(-) diff --git a/docs-site/content/kagent/1.x/about/core-concepts.md b/docs-site/content/kagent/1.x/about/core-concepts.md index 9f07bd63..b6beb0b2 100644 --- a/docs-site/content/kagent/1.x/about/core-concepts.md +++ b/docs-site/content/kagent/1.x/about/core-concepts.md @@ -134,6 +134,8 @@ After it is created, a Session talks to callers over the {{< gloss "A2A" >}}A2A{ An expiration worker deletes a Session that does not record task activity for seven days. The `config.sessions.idleTtl` Helm value sets that window. A value of `0s` turns the expiration worker off. For more information about what the deletion retains, see [Expire idle Sessions]({{< link path="operations/operational-considerations#expire-idle-sessions" >}}). +To delete a Session yourself, run `kagent agent session delete `. The deletion fails while the Session has an active turn or other lifecycle work in progress, such as a resume. To end an active turn and delete the Session anyway, add the `--force` flag. A forced deletion cancels the active turn, and records its task as canceled with the message `Session deleted while the turn was active.` When a deletion returns an error, the Session can stay in the `DELETING` state. Run the command again to finish the deletion. + ## Actor An **Actor** is the sandboxed unit of compute, provided by [Agent Substrate]({{< link path="about/architecture/agent-substrate" >}}), that _runs a Session's conversation loop_. Every Session is backed by an Actor. diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md b/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md index 5088b890..d893c970 100644 --- a/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md +++ b/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md @@ -92,10 +92,10 @@ When an agent forwards the caller's token to a model or MCP server that sets `to ### Resources that the API writes -kagent's gRPC API also writes Harness and AgentTemplate resources. The AgentTemplate service creates, updates, and deletes AgentTemplates, and the Harness service creates and deletes Harnesses, both through the kagent controller. The `kagent apply -f` command calls the AgentTemplate service, and any client that reaches the gRPC endpoint can call either service. The controller writes these resources with its own service account rather than the caller's, so Kubernetes RBAC never evaluates the caller. The controller's authenticator resolves the caller instead, as described in [Controller authentication modes](#controller-authentication-modes). +kagent's gRPC API also writes Harness, AgentTemplate, and EgressPolicy resources. The AgentTemplate service creates, updates, and deletes AgentTemplates, the Harness service creates and deletes Harnesses, and the EgressPolicy service creates, updates, and deletes EgressPolicies, all through the kagent controller. The **Policies** page of the kagent UI calls the EgressPolicy service. The `kagent apply -f` command calls the AgentTemplate service, and any client that reaches the gRPC endpoint can call each of these services. The controller writes these resources with its own service account rather than the caller's, so Kubernetes RBAC never evaluates the caller. The controller's authenticator resolves the caller instead, as described in [Controller authentication modes](#controller-authentication-modes). > [!WARNING] -> By default, kagent neither authenticates nor authorizes this path. The `insecure` authenticator admits every request, and the authorizer it installs permits every check. Any caller that reaches the gRPC endpoint can author an agent's Harness and AgentTemplate, regardless of their Kubernetes permissions. Do not expose port `8083` outside the cluster. For the identity that this mode gives an anonymous caller, and for the mode that changes it, see [Controller authentication modes](#controller-authentication-modes). +> By default, kagent neither authenticates nor authorizes this path. The `insecure` authenticator admits every request, and the authorizer it installs permits every check. Any caller that reaches the gRPC endpoint can author an agent's Harness and AgentTemplate, and its EgressPolicies, regardless of their Kubernetes permissions. Do not expose port `8083` outside the cluster. For the identity that this mode gives an anonymous caller, and for the mode that changes it, see [Controller authentication modes](#controller-authentication-modes). ### Creator ownership diff --git a/docs-site/content/kagent/1.x/agents/agent-harness.md b/docs-site/content/kagent/1.x/agents/agent-harness.md index 5717ac0b..65448a9c 100644 --- a/docs-site/content/kagent/1.x/agents/agent-harness.md +++ b/docs-site/content/kagent/1.x/agents/agent-harness.md @@ -335,12 +335,14 @@ A `byo` image receives the same variable whenever any signal is enabled, but whe ## Environment variables on an Actor -kagent adds variables of its own to every revision, alongside the Harness `spec.env` entries: the agent configuration and the agent card as JSON payloads, a certificate-authority setting for each TLS client that must trust the egress gateway, and `OTEL_RESOURCE_ATTRIBUTES`, which records the revision's service version. Enabling a telemetry signal adds more. All added variables count toward the limits that Agent Substrate enforces, so a Harness cannot spend the whole allowance on `spec.env`. +kagent adds variables of its own to every revision, alongside the Harness `spec.env` entries. These include the `KAGENT_BOOTSTRAP_JSON` descriptor of the revision's bootstrap bundle, a certificate-authority setting for each TLS client that must trust the egress gateway, and `OTEL_RESOURCE_ATTRIBUTES`, which records the revision's service version. Enabling a telemetry signal adds more. All added variables count toward the limits that Agent Substrate enforces, so a Harness cannot spend the whole allowance on `spec.env`. Two limits bound the result, and kagent checks both when it builds the Actor template. A Harness that breaks one is admitted, and then reports the failure on its Agents. * Agent Substrate accepts at most 32 environment variables on an Actor. A revision that exceeds that count reports `runtime revision has environment variables; Substrate supports at most 32`. -* A single value is capped at 32768 characters. A revision that exceeds that length reports `environment variable "" is characters; Substrate supports at most 32768`. The agent configuration is one of those values, so a long system prompt or a large tool list counts against it. +* A single value is capped at 32768 characters. A revision that exceeds that length reports `environment variable "" is characters; Substrate supports at most 32768`. + +The agent configuration and the agent card are not environment variables. kagent publishes them in the revision's bootstrap bundle, and limits the two documents together to 256 KiB. A long system prompt or a large tool list counts against that limit. A revision that exceeds it reports `bootstrap configuration and Agent Card exceed 262144 bytes`. A Harness tunes telemetry for its own agents by setting `OTEL_*` variables in its `spec.env` field. Each harness reads its environment first and falls back to the installation's telemetry settings, so a value in `spec.env` wins for that Harness only and leaves every other Harness unchanged. Some variable names are reserved, and a Harness that sets one is rejected. diff --git a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md index 5ed63b81..9c21e698 100644 --- a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md +++ b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md @@ -23,7 +23,7 @@ kagent runs a BYO agent exactly as it runs one on a managed harness, and owns th - Running the {{< gloss "Actor" >}}Actor{{< /gloss >}} that hosts your image inside a sandbox. The {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}} that the Harness references sets the class: `gvisor`, which every installation provides, or `microvm`, which needs its own Agent Substrate provisioning. For more information, see [Sandbox classes]({{< link path="about/substrate-runtime/sandboxing#sandbox-classes" >}}). - [Suspending and resuming]({{< link path="about/substrate-runtime/suspend-and-resume#suspension-between-turns" >}}) the Actor between turns. A suspend keeps only the durable volume mounted at `/data`, so an image must write any state that it needs across turns to that directory. - Routing every conversation through the A2A gateway, so callers address the {{< gloss "Agent" >}}Agent{{< /gloss >}} rather than the Actor behind it. -- Delivering the agent configuration and agent card to the container, which the kagent helpers write to `/config/config.json` and `/config/agent-card.json` at startup. +- Publishing the agent configuration and agent card in a bootstrap bundle for the revision. At startup, the kagent helpers fetch the bundle and write its contents to `/config/config.json` and `/config/agent-card.json`. Because Agent Substrate snapshots the whole Actor, an image that keeps conversation state in memory keeps it across a suspend. Your image does not need to persist anything to survive the gap between turns. @@ -44,7 +44,7 @@ Both the Harness and the image must meet the following requirements, and kagent ## Compare BYO and declarative agents -kagent resolves the AgentTemplate in the same way for a BYO agent as for a [declarative agent]({{< link path="agents/declarative-agents" >}}), then delivers the result to the container as a JSON document in an environment variable. Both harnesses resolve a ModelConfig through the same code, so the same model providers work and the same ones are rejected. For the provider matrix, see [Model provider support]({{< link path="agents/agent-harness#model-provider-support" >}}). +kagent resolves the AgentTemplate in the same way for a BYO agent as for a [declarative agent]({{< link path="agents/declarative-agents" >}}), then publishes the result as a JSON document in the revision's bootstrap bundle. Both harnesses resolve a ModelConfig through the same code, so the same model providers work and the same ones are rejected. For the provider matrix, see [Model provider support]({{< link path="agents/agent-harness#model-provider-support" >}}). The kagent harness reads that document and assembles the agent from it. A BYO image decides whether to read it: @@ -53,12 +53,17 @@ The kagent harness reads that document and assembles the agent from it. A BYO im Two AgentTemplate features continue to apply regardless of this choice. First, a `byo` Harness rejects structured output, with `Harness runtime "byo" does not support structured output`. Second, the agent card that kagent advertises for a `byo` Agent leaves out the AgentTemplate's skills and declares no extension, so a client cannot discover human-in-the-loop support the way it can for a declarative agent. -Both kinds of BYO agent receive the same environment variables. Agent Substrate delivers the two JSON payloads as private variables, and the kagent helpers write them to files before the agent starts. An image in another language either reads the files that `MaterializeFromEnv` writes or parses the variables itself. +Both kinds of BYO agent receive the same configuration. kagent stores the agent configuration and the agent card in a bootstrap bundle for each revision, and limits the two documents together to 256 KiB. The Actor's environment contains only a small descriptor of that bundle. At startup, the kagent helpers fetch the bundle from the kagent API, verify it against the descriptor, save it to `/data/kagent/bootstrap/bundle.pb`, and write the two documents to files. A restarted process or a resumed Session reads the saved bundle, and does not fetch it again. -| Environment variable | Contents | -| -------------------- | -------- | -| `KAGENT_CONFIG_JSON`, which the helpers write to `/config/config.json` | The agent configuration, including the resolved system prompt, the model and its settings, every tool, skill, and plugin that the AgentTemplate binds, and a `runtime` object that sets the process settings. | -| `KAGENT_AGENT_CARD_JSON`, which the helpers write to `/config/agent-card.json` | The agent card that kagent advertises for this agent, rendered as JSON. | +An image built with the helpers of an earlier release looks for the configuration in environment variables, and fails to start. Build the image with the helpers from the same kagent release as the controller. + +The two files exist only after the helpers run. An image without the helpers reads the descriptor and fetches the bundle itself. + +| Item | Contents | +| ---- | -------- | +| `/config/config.json`, which the helpers write | The agent configuration, including the resolved system prompt, the model and its settings, every tool, skill, and plugin that the AgentTemplate binds, and a `runtime` object that sets the process settings. | +| `/config/agent-card.json`, which the helpers write | The agent card that kagent advertises for this agent, rendered as JSON. | +| `KAGENT_BOOTSTRAP_JSON` | The bootstrap descriptor, with the control-plane URL, the revision, the format version, and the SHA-256 digest of the bundle. | | Anything in `spec.env` | The literal values that the Harness sets. | | Certificate-authority variables and `SSL_CERT_DIR` | The egress gateway's trust bundle, which every Actor receives. For the list and the limit on how many variables an Actor takes, see [Environment variables on an Actor]({{< link path="agents/agent-harness#environment-variables-on-an-actor" >}}). | @@ -157,7 +162,7 @@ The A2A contract is a gRPC service and a readiness endpoint, so any language wit {{< tabs >}} {{% tab name="Go" %}} -`github.com/kagent-dev/kagent/go/adk/pkg/app` serves the A2A gRPC service, the readiness endpoint on 8081, and the agent card, given any type that implements `a2asrv.AgentExecutor`. The helper is framework-agnostic, so the executor is the only part that you write. `config.MaterializeFromEnv` writes the payloads that Agent Substrate delivers to `/config`, and `config.LoadAgentConfig` reads the document back. +`github.com/kagent-dev/kagent/go/adk/pkg/app` serves the A2A gRPC service, the readiness endpoint on 8081, and the agent card, given any type that implements `a2asrv.AgentExecutor`. The helper is framework-agnostic, so the executor is the only part that you write. `config.MaterializeFromBootstrap` fetches the bootstrap bundle and writes its documents to `/config`, and `config.LoadAgentConfig` reads the configuration back. ```go import ( @@ -174,7 +179,7 @@ import ( "github.com/kagent-dev/kagent/go/pkg/logging" ) -if err := config.MaterializeFromEnv("/config"); err != nil { +if err := config.MaterializeFromBootstrap(context.Background(), "/config"); err != nil { return err } compiled, err := config.LoadAgentConfig("/config/config.json") @@ -210,12 +215,13 @@ return application.Run() For a complete executor, see [`go/core/test/byoa2a/main.go`](https://github.com/kagent-dev/kagent/blob/main/go/core/test/byoa2a/main.go) in the kagent repository. {{% /tab %}} {{% tab name="Python" %}} -The `kagent-adk` package provides helpers for agents that are built with the Google Agent Development Kit (ADK). `KAgentApp` wraps an ADK agent rather than an arbitrary framework, serves A2A over gRPC, and answers the readiness endpoint on 8081. `KAgentConfig.from_file` materializes the payloads that Agent Substrate delivers and reads the `runtime` object back. The listener defaults to `[::]:80`, which matches what kagent dials. +The `kagent-adk` package provides helpers for agents that are built with the Google Agent Development Kit (ADK). `KAgentApp` wraps an ADK agent rather than an arbitrary framework, serves A2A over gRPC, and answers the readiness endpoint on 8081. `materialize_from_bootstrap` fetches the bootstrap bundle and writes its documents to `/config`, and `KAgentConfig.from_file` reads the `runtime` object back. The listener defaults to `[::]:80`, which matches what kagent dials. ```python from kagent.adk import KAgentApp -from kagent.core import KAgentConfig +from kagent.core import KAgentConfig, materialize_from_bootstrap +materialize_from_bootstrap("/config") config = KAgentConfig.from_file() app = KAgentApp( @@ -226,9 +232,9 @@ app = KAgentApp( ).build() ``` -`from_file` raises `ValueError` when the document omits `control_plane_url`, `gateway_url`, `name`, or `namespace`, so a standalone process that runs outside Agent Substrate must supply its own `/config/config.json`. +`from_file` raises `ValueError` when the document omits `control_plane_url`, `gateway_url`, `name`, or `namespace`. Because `from_file` only reads the file, a standalone process that runs outside Agent Substrate skips `materialize_from_bootstrap` and supplies its own `/config/config.json`. -The page uses two configuration objects. `KAgentConfig` holds only the `runtime` object, which supplies the API URL and the app name. `kagent.adk.types.parse_config` parses the whole document into a `Config`, and `KAgentApp` reads the listener address from that `Config`. To bind the address that the configuration names, pass a parsed `Config` as the `config` argument. `parse_config` takes JSON text or a dict rather than a path, so read the file first. Call `from_file` before `parse_config`, because `from_file` materializes the file. +The page uses two configuration objects. `KAgentConfig` holds only the `runtime` object, which supplies the API URL and the app name. `kagent.adk.types.parse_config` parses the whole document into a `Config`, and `KAgentApp` reads the listener address from that `Config`. To bind the address that the configuration names, pass a parsed `Config` as the `config` argument. `parse_config` takes JSON text or a dict rather than a path, so read the file first. Call `materialize_from_bootstrap` before either reader, because only `materialize_from_bootstrap` writes the file. ```python from pathlib import Path @@ -251,9 +257,13 @@ Implement the contract directly: 1. Serve `lf.a2a.v1.A2AService` over gRPC on port 80. Generate the stubs from the [A2A protocol](https://a2a-protocol.org) definitions. 2. Serve `GET /readyz` over HTTP on port 8081, returning `200`. -3. To honor the AgentTemplate, read the agent configuration from the `KAGENT_CONFIG_JSON` environment variable. An agent that ignores the variable runs as an opaque agent. +3. To honor the AgentTemplate, fetch the bootstrap bundle at startup. An agent that skips this step runs as an opaque agent. + 1. Read the descriptor from the `KAGENT_BOOTSTRAP_JSON` environment variable. + 2. Call `kagent.runtime.v1.BootstrapService/GetBootstrapConfig` over gRPC at the descriptor's `control_plane_url`. Send an `authorization` header with any bearer value, because Agent Substrate replaces that header with the Actor's own token. Without the header, the request reaches kagent with no credential. + 3. Check that the bundle's `revision` and `sha256` match the descriptor. For the digest algorithm, see [`go/api/bootstrap/bundle.go`](https://github.com/kagent-dev/kagent/blob/main/go/api/bootstrap/bundle.go) in the kagent repository. + 4. Read the agent configuration from the bundle's `config_json` field and the agent card from `agent_card_json`. -The kagent helpers read `KAGENT_CONFIG_JSON` and materialize its contents into `/config/config.json`. An image without those helpers parses the variable directly. +The kagent helpers also save the bundle to `/data/kagent/bootstrap/bundle.pb`, and read that file on a restart without calling the service again. {{% /tab %}} {{< /tabs >}} diff --git a/docs-site/content/kagent/1.x/agents/egress-policies.md b/docs-site/content/kagent/1.x/agents/egress-policies.md index 57d8dc3f..9efa1144 100644 --- a/docs-site/content/kagent/1.x/agents/egress-policies.md +++ b/docs-site/content/kagent/1.x/agents/egress-policies.md @@ -246,7 +246,7 @@ In a standalone Sandbox, a destination that no grant allows does not resolve. A An EgressPolicy is namespace-scoped, and kagent does not check who may select it. A user who can create or edit an Agent or a SandboxTemplate in a namespace can select every EgressPolicy in that namespace and use its credentials. Treat the namespace as the boundary for sharing policies and the Secrets that they reference. To give each team a namespace of its own, see [Run agents in multiple namespaces]({{< link path="operations/multiple-namespaces" >}}). For more information about how Kubernetes role-based access control (RBAC) governs who can write these resources, see [The Kubernetes plane]({{< link path="about/substrate-runtime/identity#the-kubernetes-plane" >}}). -To control who can grant access, give the permission to create and edit EgressPolicy resources only to administrators. The kagent controller needs only read access to EgressPolicy resources. +To control who can grant access, give the permission to create and edit EgressPolicy resources only to administrators. The kagent controller also writes EgressPolicy resources, with its own service account, for the **Policies** page of the kagent UI and the `EgressPolicyService` API. By default, kagent does not authenticate that path, so any caller that reaches the kagent API can create, edit, or delete a policy regardless of their Kubernetes permissions. For more information, see [Resources that the API writes]({{< link path="about/substrate-runtime/identity#resources-that-the-api-writes" >}}). The gateway keeps a credential out of the sandbox, but it cannot stop an allowed destination from returning the credential in a response. Grant a credential only to a destination that you trust with it. diff --git a/docs-site/content/kagent/1.x/examples/a2a-byo.md b/docs-site/content/kagent/1.x/examples/a2a-byo.md index 8c07cf39..14782a82 100644 --- a/docs-site/content/kagent/1.x/examples/a2a-byo.md +++ b/docs-site/content/kagent/1.x/examples/a2a-byo.md @@ -196,7 +196,7 @@ func (executor) Cancel(context.Context, *a2asrv.ExecutorContext) iter.Seq2[a2aty Two events make a complete turn. `NewSubmittedTask` acknowledges the message and opens the task, and a `TaskStateCompleted` status update carrying an agent message ends it. Between them, a real agent yields whatever its work produces. -`main` sets the rest up. First, `config.MaterializeFromEnv` writes the payloads that Agent Substrate delivers to `/config`. Then `config.LoadAgentConfig` reads the document back, and `config.ProcessConfig` returns its `runtime` object. `app.New` serves the A2A gRPC service and the readiness endpoint. +`main` sets the rest up. First, `config.MaterializeFromBootstrap` fetches the revision's bootstrap bundle from the kagent API and writes its documents to `/config`. Then `config.LoadAgentConfig` reads the configuration back, and `config.ProcessConfig` returns its `runtime` object. `app.New` serves the A2A gRPC service and the readiness endpoint. ```go compiled, err := config.LoadAgentConfig("/config/config.json") @@ -211,7 +211,7 @@ application, err := app.New(app.AppConfig{ }, executor{}) ``` -`ControlPlaneURL` is required because the helper reports task state to the kagent API. The `cmp.Or` fallbacks keep the image runnable outside Agent Substrate, where no configuration document exists. All of this stays as it is in an agent of your own. +`ControlPlaneURL` is required because the helper reports task state to the kagent API. The `cmp.Or` fallbacks cover a configuration document that omits the port or the name. Outside Agent Substrate, no bootstrap descriptor exists, so the image exits at startup. All of this stays as it is in an agent of your own. This agent ignores the rest of the configuration. To honor the AgentTemplate instead, read the other fields of the document that `LoadAgentConfig` returns. To review what the document contains, see [Compare BYO and declarative agents]({{< link path="agents/bring-your-own-agent#compare-byo-and-declarative-agents" >}}). diff --git a/docs-site/content/kagent/1.x/examples/agents-via-mcp.md b/docs-site/content/kagent/1.x/examples/agents-via-mcp.md index 256d4d8f..aba579d4 100644 --- a/docs-site/content/kagent/1.x/examples/agents-via-mcp.md +++ b/docs-site/content/kagent/1.x/examples/agents-via-mcp.md @@ -524,7 +524,7 @@ The checkpoint tools pin a Session's state. These tools do not need the tasks ex ```json { "session": { - "agent": "my-first-agent", + "agent": "kagent/my-first-agent", "id": "01a06d1a-2b7c-7d40-8e13-5c9f04b1a6d2", "state": "RUNTIME_STATE_READY" } @@ -535,11 +535,20 @@ You can now safely [clean up these resources](#clean-up). ## Clean up -1. Delete the checkpoint that you created. If you used Claude Code or Cursor, set `CHECKPOINT_ID` to the ID that the client reported. `CheckpointService` listens on the same port that serves MCP, so the port-forward from [Connect a client](#connect-a-client) already reaches the service. +1. Delete the checkpoint that you created with the `delete_session_checkpoint` tool. If you used Claude Code or Cursor, set `CHECKPOINT_ID` to the ID that the client reported, or ask the client to delete the checkpoint. ```bash - grpcurl -plaintext \ - -d '{"checkpointId":"'"$CHECKPOINT_ID"'"}' \ - localhost:8083 kagent.api.v1.CheckpointService/DeleteCheckpoint + curl -s -X POST http://localhost:8083/mcp \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{ + "jsonrpc": "2.0", + "id": 9, + "method": "tools/call", + "params": { + "name": "delete_session_checkpoint", + "arguments": { "checkpoint_id": "'"$CHECKPOINT_ID"'" } + } + }' ``` 2. Remove the server entry from your client. In Claude Code, run `claude mcp remove kagent`. In Cursor, delete the `kagent` entry from your MCP settings. @@ -548,15 +557,23 @@ You can now safely [clean up these resources](#clean-up). ## MCP tool reference -The server exposes the following agent and Session tools. Some cover discovery and conversation, and the rest expose the {{< gloss "Checkpoint" >}}checkpoint{{< /gloss >}} operations, so a client can pin an agent's state as well as talk to it. An Agent is addressed by its namespace and name, and a Session by its own universally unique identifier (UUID). None of these tools deletes a Session or a checkpoint. To delete a Session, run `kagent agent session delete`. To delete a checkpoint, call the gRPC API directly, because the CLI has no checkpoint command. The server also exposes a set of [standalone sandbox]({{< link path="about/substrate-runtime/standalone-sandboxes" >}}) tools, which this example does not cover. +The server exposes the following agent and Session tools. They cover discovery, conversation, reading back what an agent did, and the {{< gloss "Checkpoint" >}}checkpoint{{< /gloss >}} operations, so a client can manage an agent's state as well as talk to it. An Agent is addressed by its namespace and name, and a Session by its own universally unique identifier (UUID). Every tool that returns a Session reports its `agent` as `/`. The server also exposes a set of [standalone sandbox]({{< link path="about/substrate-runtime/standalone-sandboxes" >}}) tools, which this example does not cover. | Tool | Required arguments | What it does | | ---- | ------------------ | ------------ | | `list_agents` | None | Lists the Agents that the caller can see. Takes `namespace` to filter, and `page_size` and `page_token`. | -| `list_sessions` | None | Lists the ready Sessions that the caller created. Takes `page_size` and `page_token`. | +| `list_sessions` | None | Lists the ready Sessions that the caller created. Takes `agent` to filter by Agent, `all_states` to include failed and suspended Sessions, and `page_size` and `page_token`. | +| `create_session` | `agent` | Starts a Session with the Agent. Takes `message` to send a first message, `name` for a display name, and `request_id` for idempotency. With `message`, the call returns once the agent accepts the turn. To read the reply, call `get_session`. | | `invoke_agent` | `message`, and exactly one of `agent` or `session_id` | Starts a new Session with `agent`, or continues one with `session_id`, and returns the agent's reply with the Session and task IDs. Takes `message_id` for idempotency. | +| `get_session` | `session_id` | Returns the Session's state, its failure if it has one, and its turns, oldest first. Each turn summarizes the user message, the reply, and the tool calls. Takes `last_turns` to return only the most recent turns, and `max_bytes` to cap the answer, which drops the oldest turns first. To poll a running turn, pass `last_turns` set to `1`. | +| `list_tasks` | `session_id` | Pages through the Session's tasks, oldest first, each as the same summary that `get_session` returns. Takes `page_token` and `max_bytes`, and `page_size`, which accepts 1 to 100 and defaults to 50. | +| `get_task` | `session_id`, `task_id` | Returns one task's A2A messages and artifacts in timeline order. Takes `tool_call`, an index or an ID, to return only the A2A parts of one tool call, `from_item` to continue a paged answer, and `max_bytes`. | +| `rename_session` | `session_id`, `name` | Sets the Session's display name. An empty `name` clears it. | +| `delete_session` | `session_id` | Deletes the Session and its runtime state. The call fails while the Session has an active turn. It returns a conflict while another operation on the Session is in progress, and the client can retry it. | | `create_session_checkpoint` | `session_id`, `expected_head_task_id` | Pins the Session at a turn boundary. The call fails if the Session has advanced past that task. Takes `request_id` for idempotency. | | `list_session_checkpoints` | `session_id` | Lists that Session's checkpoints. Takes `page_size` and `page_token`. | +| `get_session_checkpoint` | `checkpoint_id` | Returns one checkpoint's state, and its failure if it has one. | +| `delete_session_checkpoint` | `checkpoint_id` | Deletes the checkpoint. | | `fork_session` | `checkpoint_id` | Starts a second Session from a checkpoint, replaying the Session's transcript through the pinned turn. Takes `request_id` for idempotency. | ## Next steps diff --git a/docs-site/content/kagent/1.x/observability/tracing.md b/docs-site/content/kagent/1.x/observability/tracing.md index 4a04dfdf..67e55108 100644 --- a/docs-site/content/kagent/1.x/observability/tracing.md +++ b/docs-site/content/kagent/1.x/observability/tracing.md @@ -78,7 +78,7 @@ Use attributes, not span names, to identify a request in a trace. The runtime co | `a2a.task.id` | Span | The A2A task ID, which identifies one turn of a conversation. | | `gen_ai.conversation.id` | Span | The A2A context ID, which identifies the conversation and is stable across its turns. | | `gen_ai.agent.id` | Span | The Agent, as `/`. The shorter `gen_ai.agent.name` carries the name alone. | -| `enduser.id` | Span | The authenticated caller, such as `admin@kagent.dev`. | +| `user.id` | Span | The authenticated caller, such as `admin@kagent.dev`, on the request span and the spans beneath it. Earlier releases recorded this attribute as `enduser.id`. On the `claude` runtime, the Claude Code spans set their own `user.id`, which is a hash of the Claude account. Read the kagent caller from the `invoke_agent` span. | | `gen_ai.main_agent.id` | Resource | The main Agent that the runtime process was compiled for, as `/`. This resource attribute replaces the resource-level `gen_ai.agent.id` name. | | `kagent.runtime` | Resource | The runtime that served the request, such as `adk-go`. | | `kagent.genai.producer` | Resource | `runtime` on a native `codex` or `claude` process. The value shows that kagent writes the GenAI model and tool spans for that process. A collector can use the value to avoid counting the native spans as duplicate model calls. | diff --git a/docs-site/content/kagent/1.x/operations/uninstall.md b/docs-site/content/kagent/1.x/operations/uninstall.md index 87618a6b..ccc87b3f 100644 --- a/docs-site/content/kagent/1.x/operations/uninstall.md +++ b/docs-site/content/kagent/1.x/operations/uninstall.md @@ -20,7 +20,7 @@ The command keeps the `kagent` namespace and anything else in it. A database tha ## Before you begin 1. Confirm that you have administrative access to the cluster. -2. Confirm that your kubeconfig points at the cluster that you want to uninstall from. The `kagent uninstall` command does not ask for confirmation, and it acts on the current context. +2. Confirm that your kubeconfig points at the cluster that you want to uninstall from. The `kagent uninstall` command acts on the current context, and asks for confirmation only before it deletes WorkerPools that `kagent install` did not create. ```bash kubectl config current-context ``` @@ -35,6 +35,8 @@ The command keeps the `kagent` namespace and anything else in it. A database tha Uninstall kagent with the kagent CLI. The command waits for each Helm release to finish its removal before it continues. 1. Uninstall kagent. When kagent runs in a namespace other than `kagent`, add the `--namespace` flag with that namespace. If the namespace does not match, the command stops before it deletes anything, and prints the namespace to use. + + A self-managed WorkerPool, one that `kagent install` did not create, runs on the Agent Substrate installation that the command removes. If the cluster has one, the command lists each self-managed WorkerPool and asks `Delete them and continue? [y/N]` before it deletes anything. To stop with nothing deleted, answer `n`. Without a terminal, such as in a continuous integration (CI) job, the command stops with nothing deleted. To delete the WorkerPools without the question, add the `--delete-worker-pools` flag. ```bash kagent uninstall ``` From 25708b30bdd05491bb932cf3e0175e27084109ab Mon Sep 17 00:00:00 2001 From: Rachael Graham Date: Fri, 6 Nov 2026 12:07:31 -0600 Subject: [PATCH 4/5] rc3 kind testing Signed-off-by: Rachael Graham --- docs-site/content/kagent/1.x/about/core-concepts.md | 2 +- .../content/kagent/1.x/agents/agent-harness.md | 2 +- .../kagent/1.x/agents/bring-your-own-agent.md | 4 ++-- docs-site/content/kagent/1.x/examples/a2a-byo.md | 13 ++++++++++++- .../content/kagent/1.x/examples/agents-via-mcp.md | 2 +- docs-site/content/kagent/1.x/operations/upgrade.md | 13 ++++++++++--- docs-site/content/kagent/1.x/setup/installation.md | 4 +++- 7 files changed, 30 insertions(+), 10 deletions(-) diff --git a/docs-site/content/kagent/1.x/about/core-concepts.md b/docs-site/content/kagent/1.x/about/core-concepts.md index b6beb0b2..95c9711e 100644 --- a/docs-site/content/kagent/1.x/about/core-concepts.md +++ b/docs-site/content/kagent/1.x/about/core-concepts.md @@ -134,7 +134,7 @@ After it is created, a Session talks to callers over the {{< gloss "A2A" >}}A2A{ An expiration worker deletes a Session that does not record task activity for seven days. The `config.sessions.idleTtl` Helm value sets that window. A value of `0s` turns the expiration worker off. For more information about what the deletion retains, see [Expire idle Sessions]({{< link path="operations/operational-considerations#expire-idle-sessions" >}}). -To delete a Session yourself, run `kagent agent session delete `. The deletion fails while the Session has an active turn or other lifecycle work in progress, such as a resume. To end an active turn and delete the Session anyway, add the `--force` flag. A forced deletion cancels the active turn, and records its task as canceled with the message `Session deleted while the turn was active.` When a deletion returns an error, the Session can stay in the `DELETING` state. Run the command again to finish the deletion. +To delete a Session yourself, run `kagent agent session delete `. kagent deletes a Session only when no turn or other lifecycle work, such as a resume, is in progress. To delete a Session during an active turn, add the `--force` flag. A forced deletion cancels the active turn, and records its task as canceled with the message `Session deleted while the turn was active.` ## Actor diff --git a/docs-site/content/kagent/1.x/agents/agent-harness.md b/docs-site/content/kagent/1.x/agents/agent-harness.md index 65448a9c..00ec5152 100644 --- a/docs-site/content/kagent/1.x/agents/agent-harness.md +++ b/docs-site/content/kagent/1.x/agents/agent-harness.md @@ -342,7 +342,7 @@ Two limits bound the result, and kagent checks both when it builds the Actor tem * Agent Substrate accepts at most 32 environment variables on an Actor. A revision that exceeds that count reports `runtime revision has environment variables; Substrate supports at most 32`. * A single value is capped at 32768 characters. A revision that exceeds that length reports `environment variable "" is characters; Substrate supports at most 32768`. -The agent configuration and the agent card are not environment variables. kagent publishes them in the revision's bootstrap bundle, and limits the two documents together to 256 KiB. A long system prompt or a large tool list counts against that limit. A revision that exceeds it reports `bootstrap configuration and Agent Card exceed 262144 bytes`. +The agent configuration and the agent card are not environment variables. kagent publishes them in the revision's bootstrap bundle, and limits the two documents together to 256 KiB. A long system prompt or a large tool list counts against that limit. A Harness tunes telemetry for its own agents by setting `OTEL_*` variables in its `spec.env` field. Each harness reads its environment first and falls back to the installation's telemetry settings, so a value in `spec.env` wins for that Harness only and leaves every other Harness unchanged. Some variable names are reserved, and a Harness that sets one is rejected. diff --git a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md index 9c21e698..e55f2603 100644 --- a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md +++ b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md @@ -55,7 +55,7 @@ Two AgentTemplate features continue to apply regardless of this choice. First, a Both kinds of BYO agent receive the same configuration. kagent stores the agent configuration and the agent card in a bootstrap bundle for each revision, and limits the two documents together to 256 KiB. The Actor's environment contains only a small descriptor of that bundle. At startup, the kagent helpers fetch the bundle from the kagent API, verify it against the descriptor, save it to `/data/kagent/bootstrap/bundle.pb`, and write the two documents to files. A restarted process or a resumed Session reads the saved bundle, and does not fetch it again. -An image built with the helpers of an earlier release looks for the configuration in environment variables, and fails to start. Build the image with the helpers from the same kagent release as the controller. +Build the image with the helpers from the same kagent release as the controller, because the helpers of each release read the configuration in the way that the release delivers it. The two files exist only after the helpers run. An image without the helpers reads the descriptor and fetches the bundle itself. @@ -259,7 +259,7 @@ Implement the contract directly: 2. Serve `GET /readyz` over HTTP on port 8081, returning `200`. 3. To honor the AgentTemplate, fetch the bootstrap bundle at startup. An agent that skips this step runs as an opaque agent. 1. Read the descriptor from the `KAGENT_BOOTSTRAP_JSON` environment variable. - 2. Call `kagent.runtime.v1.BootstrapService/GetBootstrapConfig` over gRPC at the descriptor's `control_plane_url`. Send an `authorization` header with any bearer value, because Agent Substrate replaces that header with the Actor's own token. Without the header, the request reaches kagent with no credential. + 2. Call `kagent.runtime.v1.BootstrapService/GetBootstrapConfig` over gRPC at the descriptor's `control_plane_url`. Send an `authorization` header with any bearer value, because Agent Substrate replaces that header with the Actor's own token. 3. Check that the bundle's `revision` and `sha256` match the descriptor. For the digest algorithm, see [`go/api/bootstrap/bundle.go`](https://github.com/kagent-dev/kagent/blob/main/go/api/bootstrap/bundle.go) in the kagent repository. 4. Read the agent configuration from the bundle's `config_json` field and the agent card from `agent_card_json`. diff --git a/docs-site/content/kagent/1.x/examples/a2a-byo.md b/docs-site/content/kagent/1.x/examples/a2a-byo.md index 14782a82..d95069d1 100644 --- a/docs-site/content/kagent/1.x/examples/a2a-byo.md +++ b/docs-site/content/kagent/1.x/examples/a2a-byo.md @@ -24,6 +24,17 @@ The agent that you build here does not call a model or bind tools. It answers ev export DOCKER_REGISTRY=localhost:5001 ``` + > [!TIP] + > On a local kind cluster, `atelet` pulls each agent image itself, so it must reach the registry at the address that the kind network uses. In the `substrate-atelet` release, point `localhost:5001` image references at the `kind-registry` container. + > ```bash + > helm upgrade substrate-atelet \ + > {{< reuse "kagent-docs/snippets/helm-substrate-path.md" >}}/substrate-atelet \ + > --version {{< reuse "kagent-docs/versions/agent-substrate-chart.md" >}} \ + > --namespace ate-system --reuse-values \ + > --set 'atelet.extraArgs[0]=--localhost-registry-replacement=kind-registry:5000' \ + > --wait + > ``` + 5. Know which {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}} and snapshot location your installation uses. The Harness that you created carries both. ```bash kubectl get harness my-first-harness -n kagent \ @@ -211,7 +222,7 @@ application, err := app.New(app.AppConfig{ }, executor{}) ``` -`ControlPlaneURL` is required because the helper reports task state to the kagent API. The `cmp.Or` fallbacks cover a configuration document that omits the port or the name. Outside Agent Substrate, no bootstrap descriptor exists, so the image exits at startup. All of this stays as it is in an agent of your own. +`ControlPlaneURL` is required because the helper reports task state to the kagent API. The `cmp.Or` fallbacks cover a configuration document that omits the port or the name. All of this stays as it is in an agent of your own. This agent ignores the rest of the configuration. To honor the AgentTemplate instead, read the other fields of the document that `LoadAgentConfig` returns. To review what the document contains, see [Compare BYO and declarative agents]({{< link path="agents/bring-your-own-agent#compare-byo-and-declarative-agents" >}}). diff --git a/docs-site/content/kagent/1.x/examples/agents-via-mcp.md b/docs-site/content/kagent/1.x/examples/agents-via-mcp.md index aba579d4..9e5c7435 100644 --- a/docs-site/content/kagent/1.x/examples/agents-via-mcp.md +++ b/docs-site/content/kagent/1.x/examples/agents-via-mcp.md @@ -569,7 +569,7 @@ The server exposes the following agent and Session tools. They cover discovery, | `list_tasks` | `session_id` | Pages through the Session's tasks, oldest first, each as the same summary that `get_session` returns. Takes `page_token` and `max_bytes`, and `page_size`, which accepts 1 to 100 and defaults to 50. | | `get_task` | `session_id`, `task_id` | Returns one task's A2A messages and artifacts in timeline order. Takes `tool_call`, an index or an ID, to return only the A2A parts of one tool call, `from_item` to continue a paged answer, and `max_bytes`. | | `rename_session` | `session_id`, `name` | Sets the Session's display name. An empty `name` clears it. | -| `delete_session` | `session_id` | Deletes the Session and its runtime state. The call fails while the Session has an active turn. It returns a conflict while another operation on the Session is in progress, and the client can retry it. | +| `delete_session` | `session_id` | Deletes the Session and its runtime state when no turn or other operation on the Session is in progress. | | `create_session_checkpoint` | `session_id`, `expected_head_task_id` | Pins the Session at a turn boundary. The call fails if the Session has advanced past that task. Takes `request_id` for idempotency. | | `list_session_checkpoints` | `session_id` | Lists that Session's checkpoints. Takes `page_size` and `page_token`. | | `get_session_checkpoint` | `checkpoint_id` | Returns one checkpoint's state, and its failure if it has one. | diff --git a/docs-site/content/kagent/1.x/operations/upgrade.md b/docs-site/content/kagent/1.x/operations/upgrade.md index e5346711..281ba287 100644 --- a/docs-site/content/kagent/1.x/operations/upgrade.md +++ b/docs-site/content/kagent/1.x/operations/upgrade.md @@ -26,7 +26,7 @@ Complete every step in this section before you change any release. The steps mak * The `substrate`, `substrate-atelet`, and `substrate-crds` releases are in the `ate-system` namespace. * The `substrate-podcert` release is in the `podcertificate-controller-system` namespace. - If the output does not list a `substrate-atelet` release, the `substrate` release still runs `atelet`. Move `atelet` to its own release first, as described in [Moving atelet to substrate-atelet](https://github.com/kagent-dev/substrate/releases/tag/v1.0.0-rc4#moving-atelet-to-substrate-atelet), with the kagent-specific changes in the [kagent Helm chart README](https://github.com/kagent-dev/kagent/blob/main/helm/README.md). + If the output does not list a `substrate-atelet` release, the `substrate` release still runs `atelet`. To upgrade that installation, follow the steps in [Upgrading from v1.0.0-rc2](https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-rc3#upgrading-from-v100-rc2). Those steps move `atelet` to its own release without deleting the `atelet` DaemonSet. 4. Back up the PostgreSQL database that kagent and Agent Substrate share. The upgrade keeps your data. However, the kagent controller and the Agent Substrate API server change the database schema when they start on the new version. To return to the previous version, you must restore the backup or roll the schema back. ```bash @@ -50,13 +50,20 @@ Complete every step in this section before you change any release. The steps mak ``` For an installation that you exported from the kagent CLI, the `kagent-values.yaml` file contains your model provider API key in plain text. Store the files securely. -6. Save the target versions in environment variables. The following values are the versions that this documentation describes. To upgrade across more than one minor release, set the versions of the next minor release, and repeat the upgrade for each minor release. +6. In `substrate-values.yaml` and `substrate-atelet-values.yaml`, turn on the `GoldenEgressPolicy` gate. The gate lets kagent give the Actor that builds each golden snapshot its own egress policy, so that the Actor can fetch its configuration from the kagent API. If the `preview` list in either file does not contain `GoldenEgressPolicy`, add it to both lists. The two lists must match. + ```yaml + preview: + - PerTemplateSnapshotLocation + - GoldenEgressPolicy + ``` + +7. Save the target versions in environment variables. The following values are the versions that this documentation describes. To upgrade across more than one minor release, set the versions of the next minor release, and repeat the upgrade for each minor release. ```bash export KAGENT_VERSION={{< reuse "kagent-docs/versions/kagent.md" >}} export SUBSTRATE_VERSION={{< reuse "kagent-docs/versions/agent-substrate-chart.md" >}} ``` -7. Save the installed kagent chart version. The [Agent Substrate upgrade](#upgrade-agent-substrate) uses this version to change the Worker image without upgrading kagent. +8. Save the installed kagent chart version. The [Agent Substrate upgrade](#upgrade-agent-substrate) uses this version to change the Worker image without upgrading kagent. ```bash export CURRENT_KAGENT_VERSION=$(helm get metadata kagent -n kagent -o json | jq -r .version) ``` diff --git a/docs-site/content/kagent/1.x/setup/installation.md b/docs-site/content/kagent/1.x/setup/installation.md index 5a6ac28f..4ef9e8ac 100644 --- a/docs-site/content/kagent/1.x/setup/installation.md +++ b/docs-site/content/kagent/1.x/setup/installation.md @@ -321,6 +321,7 @@ Agent Substrate installs as two releases in the `ate-system` namespace. The `sub cat > substrate-atelet-values.yaml < Date: Fri, 6 Nov 2026 12:48:04 -0600 Subject: [PATCH 5/5] Update upgrade.md Signed-off-by: Rachael Graham --- docs-site/content/kagent/1.x/operations/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-site/content/kagent/1.x/operations/upgrade.md b/docs-site/content/kagent/1.x/operations/upgrade.md index 281ba287..7b47d28c 100644 --- a/docs-site/content/kagent/1.x/operations/upgrade.md +++ b/docs-site/content/kagent/1.x/operations/upgrade.md @@ -26,7 +26,7 @@ Complete every step in this section before you change any release. The steps mak * The `substrate`, `substrate-atelet`, and `substrate-crds` releases are in the `ate-system` namespace. * The `substrate-podcert` release is in the `podcertificate-controller-system` namespace. - If the output does not list a `substrate-atelet` release, the `substrate` release still runs `atelet`. To upgrade that installation, follow the steps in [Upgrading from v1.0.0-rc2](https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-rc3#upgrading-from-v100-rc2). Those steps move `atelet` to its own release without deleting the `atelet` DaemonSet. + If the output does not list a `substrate-atelet` release, the `substrate` release still runs `atelet`, and the rest of this guide does not apply to that installation. First, back up the PostgreSQL database and record its schema version, as this section describes. Then follow the steps in [Upgrading from v1.0.0-rc2](https://github.com/kagent-dev/kagent/releases/tag/v1.0.0-rc3#upgrading-from-v100-rc2) instead of the remaining steps of this guide. Those steps move `atelet` to its own release without deleting the `atelet` DaemonSet, turn on the `GoldenEgressPolicy` gate, and upgrade kagent. To confirm the result, see [Verify the upgrade](#verify-the-upgrade). 4. Back up the PostgreSQL database that kagent and Agent Substrate share. The upgrade keeps your data. However, the kagent controller and the Agent Substrate API server change the database schema when they start on the new version. To return to the previous version, you must restore the backup or roll the schema back. ```bash