From e89bc775ad5df26a54ca6d482c49c5986e296187 Mon Sep 17 00:00:00 2001 From: Eitan Yarmush Date: Sat, 7 Nov 2026 14:46:19 +0000 Subject: [PATCH 1/4] Simplify the kagent 1.x CLI install for kagent-dev/kagent#3566 Hold until a kagent release that includes #3566 ships and the version conref is bumped. - CLI install: drop the grpcReflection values file and take --provider instead of a config file for the provider. Keep the clusterDomain step, since kagent install does not detect the domain; the CLI config file now lives there. - Install the CLI with curl -sL https://kagent.dev/install | bash, which installs the newest release; --version pins one. List the published platforms. - Document the kagent-default, codex-default and claude-default Harnesses (namespace-local to the release namespace), the harnesses.* Helm values with the s3://ate-snapshots/kagent/ default, and add a verify step. - grpcurl guides: drop the grpcReflection step for kagent install (Helm installs still set it) and explain that reflection needs the same authentication as other gRPC calls, in a shared grpcurl-reflection snippet. - Debug: golden build image-pull failures now name the image. - UI: describe the Harness and Agent form improvements, ModelConfig dropdowns and the agent page's update-failure reason. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Eitan Yarmush --- .../snippets/grpcurl-prerequisites.md | 2 +- .../snippets/grpcurl-reflection.md | 1 + .../kagent-docs/snippets/install-cli.md | 6 +- .../main/about/substrate-runtime/identity.md | 4 +- .../kagent/main/agents/agent-memory.md | 2 +- .../kagent/main/agents/scheduled-runs.md | 2 +- .../kagent/main/examples/agents-via-mcp.md | 2 +- .../main/get-started/your-first-agent.md | 3 + .../content/kagent/main/operations/debug.md | 2 +- .../main/operations/tune-agent-substrate.md | 2 +- .../kagent/main/operations/upgrade-from-0x.md | 2 +- .../content/kagent/main/setup/installation.md | 86 +++++++++++-------- docs-site/content/kagent/main/ui/launch-ui.md | 6 +- 13 files changed, 73 insertions(+), 47 deletions(-) create mode 100644 docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md diff --git a/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md b/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md index dd9d5d62..138cfdf1 100644 --- a/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md +++ b/docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md @@ -1,4 +1,4 @@ -1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `config.server.grpcReflection=true`. Reflection lets grpcurl discover the controller's methods without a local copy of kagent's protocol buffer definitions. +1. [Install kagent]({{< link path="setup/installation" >}}). {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}} 2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), then save the Agent's namespace and name to an environment variable, in the `/` form that the A2A `tenant` field takes. To list your Agents, run `kagent agent list`. ```bash diff --git a/docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md b/docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md new file mode 100644 index 00000000..22d811e1 --- /dev/null +++ b/docs-site/assets/kagent-docs/snippets/grpcurl-reflection.md @@ -0,0 +1 @@ +grpcurl uses gRPC server reflection to discover the controller's methods without a local copy of kagent's protocol buffer definitions. `kagent install` turns reflection on. A Helm installation must set `config.server.grpcReflection=true`. Reflection requires the same authentication as the other gRPC calls. In the default `insecure` [authentication mode]({{< link path="about/substrate-runtime/identity#controller-authentication-modes" >}}), grpcurl needs no credentials. When authentication is on, pass credentials on every grpcurl command, even one that only lists services, such as `-H "authorization: Bearer "`. diff --git a/docs-site/assets/kagent-docs/snippets/install-cli.md b/docs-site/assets/kagent-docs/snippets/install-cli.md index 5a1ec64b..6dfb2257 100644 --- a/docs-site/assets/kagent-docs/snippets/install-cli.md +++ b/docs-site/assets/kagent-docs/snippets/install-cli.md @@ -1,5 +1,7 @@ -Download the kagent CLI. The `--version` flag matches the CLI to the release that these docs cover. +Download the kagent CLI. ```bash -curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v{{< reuse "kagent-docs/versions/kagent.md" >}} +curl -sL https://kagent.dev/install | bash ``` + +The script installs the newest kagent release. To install the release that these docs cover instead, run `curl -sL https://kagent.dev/install | bash -s -- --version v{{< reuse "kagent-docs/versions/kagent.md" >}}`. diff --git a/docs-site/content/kagent/main/about/substrate-runtime/identity.md b/docs-site/content/kagent/main/about/substrate-runtime/identity.md index 6dfc0cd9..f6da90f1 100644 --- a/docs-site/content/kagent/main/about/substrate-runtime/identity.md +++ b/docs-site/content/kagent/main/about/substrate-runtime/identity.md @@ -57,7 +57,7 @@ config: authority: prod-cluster ``` -The workload sends a ServiceAccount token whose audience is `kagent-invocation` as a bearer token in the `Authorization` header. A workload usually mounts the token as a projected volume. To test from a terminal, create a token with `kubectl`, port-forward the controller's port `8083`, and call the API. The `grpcurl` command relies on gRPC reflection, so your installation must set `config.server.grpcReflection=true`. +The workload sends a ServiceAccount token whose audience is `kagent-invocation` as a bearer token in the `Authorization` header. A workload usually mounts the token as a projected volume. To test from a terminal, create a token with `kubectl`, port-forward the controller's port `8083`, and call the API. The `grpcurl` command relies on gRPC reflection, which `kagent install` turns on and a Helm installation turns on with `config.server.grpcReflection=true`. Reflection requires the same authentication as the other gRPC calls, and the `-H` flag sends the token on the reflection requests as well as on the call. ```bash kubectl create namespace ci-bots @@ -181,7 +181,7 @@ actorJwt: audiences: [ticket-api, kagent-agent-info] ``` -The service sends the token that it received as a bearer token, with an empty request. In the following command, `$ACTOR_TOKEN` holds that token. The `grpcurl` command relies on gRPC reflection, so your installation must set `config.server.grpcReflection=true`. The `-rpc-header` flag keeps the token off the reflection requests. +The service sends the token that it received as a bearer token, with an empty request. In the following command, `$ACTOR_TOKEN` holds that token. The `grpcurl` command relies on gRPC reflection, which `kagent install` turns on and a Helm installation turns on with `config.server.grpcReflection=true`. The `-rpc-header` flag sends the Actor token on the call only, so the reflection requests that grpcurl makes first carry no token. Reflection requires the same authentication as the other user calls. In the default `insecure` mode it needs no credentials. When authentication is on, also pass a user credential with `-reflect-header`, such as `-reflect-header "authorization: Bearer "`. ```bash grpcurl -plaintext -rpc-header "Authorization: Bearer $ACTOR_TOKEN" -d '{}' \ diff --git a/docs-site/content/kagent/main/agents/agent-memory.md b/docs-site/content/kagent/main/agents/agent-memory.md index 20664752..036839fe 100644 --- a/docs-site/content/kagent/main/agents/agent-memory.md +++ b/docs-site/content/kagent/main/agents/agent-memory.md @@ -220,7 +220,7 @@ No CLI command manages memories, so these examples call the service with [grpcur Each call also takes the `agent_name` exactly as the memory table stores it. An incorrect name fails silently, so copy the value from the table instead of typing it by hand. -1. Port-forward the controller's gRPC port, and confirm that your kagent installation sets `config.server.grpcReflection=true`. +1. Port-forward the controller's gRPC port. {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}} ```bash kubectl port-forward -n kagent svc/kagent-controller 8083:8083 ``` diff --git a/docs-site/content/kagent/main/agents/scheduled-runs.md b/docs-site/content/kagent/main/agents/scheduled-runs.md index 23c17934..7bdaff57 100644 --- a/docs-site/content/kagent/main/agents/scheduled-runs.md +++ b/docs-site/content/kagent/main/agents/scheduled-runs.md @@ -11,7 +11,7 @@ kagent stores schedules in its database, not as Kubernetes resources. You manage ## Before you begin -1. [Install kagent]({{< link path="setup/installation" >}}). To call the API with grpcurl, set `config.server.grpcReflection=true`. grpcurl uses server reflection to find the `ScheduledRunService` methods. +1. [Install kagent]({{< link path="setup/installation" >}}). If you call the `ScheduledRunService` API with grpcurl rather than the UI, note the following. {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}} 2. Create an Agent that answers a prompt, such as the one in [Your first agent]({{< link path="get-started/your-first-agent" >}}). ## Create a schedule in the UI diff --git a/docs-site/content/kagent/main/examples/agents-via-mcp.md b/docs-site/content/kagent/main/examples/agents-via-mcp.md index 9e5c7435..11a33573 100644 --- a/docs-site/content/kagent/main/examples/agents-via-mcp.md +++ b/docs-site/content/kagent/main/examples/agents-via-mcp.md @@ -23,7 +23,7 @@ The MCP server runs on the controller's HTTP port, so a default installation alr ## Before you begin -1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `config.server.grpcReflection=true`. Reflection lets a gRPC client discover the controller's methods without a local copy of kagent's protocol buffer definitions. +1. [Install kagent]({{< link path="setup/installation" >}}). {{< reuse "kagent-docs/snippets/grpcurl-reflection.md" >}} 2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), so that the cluster has an {{< gloss "Agent" >}}Agent{{< /gloss >}} to invoke. diff --git a/docs-site/content/kagent/main/get-started/your-first-agent.md b/docs-site/content/kagent/main/get-started/your-first-agent.md index f0b19a7c..f8b20cdf 100644 --- a/docs-site/content/kagent/main/get-started/your-first-agent.md +++ b/docs-site/content/kagent/main/get-started/your-first-agent.md @@ -42,6 +42,9 @@ Three resources define a runnable agent: a Harness holds the runtime, an AgentTe location: s3://ate-snapshots/kagent/ ``` + > [!TIP] + > Your installation also comes with the `kagent-default`, `codex-default`, and `claude-default` Harnesses in the kagent namespace, for the kagent, Codex, and Claude runtimes. An Agent in the kagent namespace can name one of them in `spec.harnessRef` instead of a Harness of your own. `spec.harnessRef` is namespace-local, so an Agent in another namespace needs its own Harness. This guide creates its own Harness so that you can see each field, and because later guides build on it. + 2. Apply an `AgentTemplate`. The `modelConfig` field references the `default-model-config` {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} that was automatically created for the model provider API key that you provided during kagent installation. ```yaml apiVersion: api.kagent.dev/v1alpha3 diff --git a/docs-site/content/kagent/main/operations/debug.md b/docs-site/content/kagent/main/operations/debug.md index 6a707203..9304af00 100644 --- a/docs-site/content/kagent/main/operations/debug.md +++ b/docs-site/content/kagent/main/operations/debug.md @@ -72,7 +72,7 @@ Compatible=False Blocked: blocked by ResolvedRefs Ready=False Blocked: blocked by ResolvedRefs ``` -A failed golden snapshot is not final. When Agent Substrate fails to build the golden snapshot, kagent deletes the failed ActorTemplate and rebuilds it after about 15 seconds, 1 minute, and 4 minutes, and then about every 10 minutes indefinitely. While a rebuild waits, `Ready` is `False` with the reason `ActorTemplateRetrying` and a message such as `golden build failed (GoldenActorCrashed), retry 1 at