From 51ac992baa72b2858c2b787ee40ce42fd02849bf Mon Sep 17 00:00:00 2001 From: artberger <20074219+artberger@users.noreply.github.com> Date: Fri, 5 Jun 2026 07:55:24 +0000 Subject: [PATCH] docs: Update kagent and kmcp API reference docs Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../docs/kagent/resources/api-ref/page.mdx | 87 ++++++++++++++++--- src/app/docs/kagent/resources/helm/page.mdx | 14 ++- 2 files changed, 89 insertions(+), 12 deletions(-) diff --git a/src/app/docs/kagent/resources/api-ref/page.mdx b/src/app/docs/kagent/resources/api-ref/page.mdx index 9fb42f3..4ea62d8 100644 --- a/src/app/docs/kagent/resources/api-ref/page.mdx +++ b/src/app/docs/kagent/resources/api-ref/page.mdx @@ -253,6 +253,24 @@ _Appears in:_ | `interactiveReplies` _boolean_ | | true | | +#### AgentHarnessRuntime + +_Underlying type:_ _string_ + +AgentHarnessRuntime selects which control plane provisions the harness VM. + +_Validation:_ +- Enum: [openshell substrate] + +_Appears in:_ +- [AgentHarnessSpec](#agentharnessspec) + +| Field | Description | +| --- | --- | +| `openshell` | | +| `substrate` | | + + #### AgentHarnessSlackChannelSpec @@ -294,6 +312,8 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `backend` _[AgentHarnessBackendType](#agentharnessbackendtype)_ | Backend selects the control plane to use. Required. | | Enum: [openclaw nemoclaw hermes]
| +| `runtime` _[AgentHarnessRuntime](#agentharnessruntime)_ | Runtime selects the harness provisioning stack. Defaults to openshell when unset. | openshell | Enum: [openshell substrate]
| +| `substrate` _[AgentHarnessSubstrateSpec](#agentharnesssubstratespec)_ | Substrate is required when runtime is substrate. | | | | `description` _string_ | Description is a short human-readable summary shown in the UI (e.g. agents list). | | | | `image` _string_ | Image is the container image to run in the harness VM, if the backend
supports per-resource images. Backends openclaw and nemoclaw pin the image
to the NemoClaw sandbox base when this field is empty; backend hermes pins
to the Hermes sandbox base image when empty. | | | | `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Env is a list of environment variables injected into the harness workload.
Values use the Kubernetes EnvVar shape; ValueFrom references are
resolved server-side where supported. | | | @@ -338,6 +358,48 @@ _Appears in:_ | `id` _string_ | | | | +#### AgentHarnessSubstrateSnapshotsConfig + + + +AgentHarnessSubstrateSnapshotsConfig points at a GCS prefix for actor memory snapshots. +Substrate currently expects a gs:// location (see Agent Substrate SnapshotsConfig). + + + +_Appears in:_ +- [AgentHarnessSubstrateSpec](#agentharnesssubstratespec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `location` _string_ | Location is the GCS URI prefix for golden and incremental snapshots.
Example: gs://ate-snapshots/kagent/my-namespace/my-harness/ | | Pattern: `^gs://`
| + + +#### AgentHarnessSubstrateSpec + + + +AgentHarnessSubstrateSpec configures Agent Substrate (WorkerPool + ActorTemplate + Actor). + + +kagent generates a per-harness ActorTemplate and creates an Actor from it. WorkerPool +capacity is referenced from workerPoolRef or the controller default; it is not +created or deleted by the AgentHarness controller. + + + +_Appears in:_ +- [AgentHarnessSpec](#agentharnessspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `workerPoolRef` _[TypedLocalReference](#typedlocalreference)_ | WorkerPoolRef references an existing ate.dev WorkerPool in the harness namespace.
When unset, the controller uses its configured default WorkerPool. | | | +| `snapshotsConfig` _[AgentHarnessSubstrateSnapshotsConfig](#agentharnesssubstratesnapshotsconfig)_ | SnapshotsConfig configures actor memory snapshots. Defaults to
gs://ate-snapshots/<namespace>/<agentharnessname> when unset. | | | +| `workloadImage` _string_ | WorkloadImage overrides the default nemoclaw/openclaw sandbox image in the ActorTemplate. | | | +| `gatewayToken` _string_ | GatewayToken is the OpenClaw gateway Bearer token for this harness.
Prefer gatewayTokenSecretRef for production secrets. | | MinLength: 1
| +| `gatewayTokenSecretRef` _[TypedLocalReference](#typedlocalreference)_ | GatewayTokenSecretRef references a Secret key holding the OpenClaw gateway Bearer token.
The Secret must contain a "token" key. | | | + + #### AgentHarnessTelegramChannelSpec @@ -400,7 +462,7 @@ _Appears in:_ | `description` _string_ | | | | | `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from the specified container images.
and made available to the agent under the `/skills` folder. | | | | `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.
This is intended for sandboxed declarative execution today, and can also
be consumed by BYO agents. | | | -| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-routing | | | +| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | #### AgentStatus @@ -689,9 +751,9 @@ _Appears in:_ | `modelConfig` _string_ | The name of the model config to use.
If not specified, the default value is "default-model-config".
Must be in the same namespace as the Agent. | | | | `stream` _boolean_ | Whether to stream the response from the model.
If not specified, the default value is false. | | | | `tools` _[Tool](#tool) array_ | | | MaxItems: 20
| -| `a2aConfig` _[A2AConfig](#a2aconfig)_ | A2AConfig instantiates an A2A server for this agent,
served on the HTTP port of the kagent kubernetes
controller (default 8083).
The A2A server URL will be served at
<kagent-controller-ip>:8083/api/a2a/<agent-namespace>/<agent-name>
Read more about the A2A protocol here: https://github.com/google/A2A | | | +| `a2aConfig` _[A2AConfig](#a2aconfig)_ | A2AConfig instantiates an A2A server for this agent,
served on the HTTP port of the kagent kubernetes
controller (default 8083).
The A2A server URL will be served at
<kagent-controller-ip>:8083/api/a2a/<agent-namespace>/<agent-name>
Read more about the A2A protocol here: https://github.com/a2aproject/A2A | | | | `deployment` _[DeclarativeDeploymentSpec](#declarativedeploymentspec)_ | | | | -| `executeCodeBlocks` _boolean_ | Allow code execution for python code blocks with this agent.
If true, the agent will automatically execute python code blocks in the LLM responses.
Code will be executed in a sandboxed environment.
due to a bug in adk (https://github.com/google/adk-python/issues/3921), this field is ignored for now. | | | +| `executeCodeBlocks` _boolean_ | Allow code execution for python code blocks with this agent.
If true, the agent will automatically execute python code blocks in the LLM responses.
Code will be executed in a sandboxed environment.
due to a bug in adk (https://github.com/google/adk-python/issues/3921 ), this field is ignored for now. | | | | `memory` _[MemorySpec](#memoryspec)_ | Memory configuration for the agent. | | | | `context` _[ContextConfig](#contextconfig)_ | Context configures context management for this agent.
This includes event compaction (compression) and context caching. | | | @@ -753,7 +815,7 @@ _Underlying type:_ _string_ FromNamespaces specifies namespace from which references to this resource are allowed. This follows the same pattern as Gateway API's cross-namespace route attachment. -See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-routing +See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment _Validation:_ - Enum: [All Same Selector] @@ -1223,7 +1285,8 @@ _Appears in:_ | `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | | 30s | | | `sseReadTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | | | | | `terminateOnClose` _boolean_ | | true | | -| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this RemoteMCPServer.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this RemoteMCPServer.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-routing | | | +| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this RemoteMCPServer.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this RemoteMCPServer.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | +| `tls` _[TLSConfig](#tlsconfig)_ | TLS configuration for the upstream MCP server connection.
Use this for HTTPS upstreams that present a certificate the agent's
system trust store does not include (corporate CA, self-signed cert
on a test fixture, internal MCP gateway). Reuses the same TLSConfig
type as ModelConfig.spec.tls — disableVerify turns off certificate
validation entirely, caCertSecretRef + caCertSecretKey point at a
PEM bundle Secret in the same namespace, and disableSystemCAs
trusts only the named bundle.

Note one asymmetry with ModelConfig: a spec-level XValidation rule
on RemoteMCPServer rejects spec.tls when spec.url has the http://
scheme (a TLS opinion contradicts a plaintext URL). ModelConfig has
no equivalent rule, so a TLS block can sit alongside any baseUrl. | | | #### RemoteMCPServerStatus @@ -1242,6 +1305,7 @@ _Appears in:_ | `observedGeneration` _integer_ | INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
Important: Run "make" to regenerate code after modifying this file | | | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | | | | | `discoveredTools` _[MCPTool](#mcptool) array_ | | | | +| `secretHash` _string_ | SecretHash stores a hash of the TLS Secret referenced by spec.tls so
agents that consume this RemoteMCPServer can detect cert rotation and
roll on the next reconcile. Empty when spec.tls.caCertSecretRef is unset. | | | #### SAPAICoreConfig @@ -1410,20 +1474,22 @@ _Appears in:_ -TLSConfig contains TLS/SSL configuration options for model provider connections. -This enables agents to connect to internal LiteLLM gateways or other providers -that use self-signed certificates or custom certificate authorities. +TLSConfig contains TLS/SSL configuration options for outbound HTTPS +connections from the agent (model provider, RemoteMCPServer). The +XValidation rules below apply at admission to every CRD field that +uses TLSConfig, so callers don't need to re-declare them per spec. _Appears in:_ - [ModelConfigSpec](#modelconfigspec) +- [RemoteMCPServerSpec](#remotemcpserverspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `disableVerify` _boolean_ | DisableVerify disables SSL certificate verification entirely.
When false (default), SSL certificates are verified.
When true, SSL certificate verification is disabled.
WARNING: This should ONLY be used in development/testing environments.
Production deployments MUST use proper certificates. | false | | -| `caCertSecretRef` _string_ | CACertSecretRef is a reference to a Kubernetes Secret containing
CA certificate(s) in PEM format. The Secret must be in the same
namespace as the ModelConfig.
When set, the certificate will be used to verify the provider's SSL certificate.
This field follows the same pattern as APIKeySecret. | | | -| `caCertSecretKey` _string_ | CACertSecretKey is the key within the Secret that contains the CA certificate data.
This field follows the same pattern as APIKeySecretKey.
Required when CACertSecretRef is set (unless DisableVerify is true). | | | +| `caCertSecretRef` _string_ | CACertSecretRef is a reference to a Kubernetes Secret containing
CA certificate(s) in PEM format. The Secret must be in the same
namespace as the resource referencing it (ModelConfig,
RemoteMCPServer, or any future consumer of TLSConfig).
When set, the certificate will be used to verify the upstream's
SSL certificate. | | | +| `caCertSecretKey` _string_ | CACertSecretKey is the key within the Secret that contains the
CA certificate data (PEM-encoded). Required when CACertSecretRef
is set — admission rejects ref-without-key regardless of
DisableVerify (see the TLSConfig-level XValidation rules). | | | | `disableSystemCAs` _boolean_ | DisableSystemCAs disables the use of system CA certificates.
When false (default), system CA certificates are used for verification (safe behavior).
When true, only the custom CA from CACertSecretRef is trusted.
This allows strict security policies where only corporate CAs should be trusted. | false | | @@ -1507,6 +1573,7 @@ _Appears in:_ _Appears in:_ +- [AgentHarnessSubstrateSpec](#agentharnesssubstratespec) - [PromptSource](#promptsource) | Field | Description | Default | Validation | diff --git a/src/app/docs/kagent/resources/helm/page.mdx b/src/app/docs/kagent/resources/helm/page.mdx index 1264ead..a11c1d0 100644 --- a/src/app/docs/kagent/resources/helm/page.mdx +++ b/src/app/docs/kagent/resources/helm/page.mdx @@ -65,13 +65,14 @@ A Helm chart for kagent, built with Google ADK | controller.agentImage.tag | string | `""` | | | controller.auth.mode | string | `"unsecure"` | | | controller.auth.userIdClaim | string | `""` | | -| controller.env | list | `[]` | | +| controller.env | string | `nil` | | | controller.envFrom | list | `[]` | | | controller.image.pullPolicy | string | `""` | | | controller.image.registry | string | `""` | | | controller.image.repository | string | `"kagent-dev/kagent/controller"` | | | controller.image.tag | string | `""` | | | controller.loglevel | string | `"info"` | | +| controller.mcpEgressPlaintext | bool | `false` | Rewrite RemoteMCPServer tool URLs and the controller's tool-discovery dial from `https://host[:port]` to `http://host:` so MCP traffic egresses in plaintext to a proxy that originates TLS upstream off by default. | | controller.nodeSelector | object | `{}` | Node labels to match for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). | | controller.podAnnotations | object | `{}` | | | controller.readinessProbe | object | httpGet /health on port http, periodSeconds=30 | Custom readiness probe for the controller container. Setting a value replaces the default probe entirely — include a handler (httpGet / exec / tcpSocket / grpc) when overriding. | @@ -88,6 +89,14 @@ A Helm chart for kagent, built with Google ADK | controller.streaming.initialBufSize | string | `"4Ki"` | | | controller.streaming.maxBufSize | string | `"1Mi"` | | | controller.streaming.timeout | string | `"600s"` | | +| controller.substrate.ateApiEndpoint | string | `""` | | +| controller.substrate.ateApiInsecure | bool | `false` | | +| controller.substrate.ateApiServer.namespace | string | `"ate-system"` | | +| controller.substrate.ateApiServer.serviceAccount | string | `"ate-api-server"` | | +| controller.substrate.atenetRouterURL | string | `""` | | +| controller.substrate.defaultWorkerPool.name | string | `""` | | +| controller.substrate.defaultWorkerPool.namespace | string | `""` | | +| controller.substrate.enabled | bool | `false` | | | controller.tolerations | list | `[]` | Node taints which will be tolerated for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). | | controller.volumeMounts | list | `[]` | | | controller.volumes | list | `[]` | | @@ -171,7 +180,7 @@ A Helm chart for kagent, built with Google ADK | oauth2-proxy.extraArgs.redirect-url | string | `"$(OIDC_REDIRECT_URL)"` | | | oauth2-proxy.extraArgs.scope | string | `"openid profile email groups"` | | | oauth2-proxy.extraArgs.set-authorization-header | bool | `true` | | -| oauth2-proxy.extraArgs.skip-auth-regex | string | `"^/(login|_next/static|_next/image|login-bg\\.(jpg|png|webp)|logo-.*\\.png|favicon\\.ico).*$"` | | +| oauth2-proxy.extraArgs.skip-auth-regex | string | `"^/(login|_next/static|_next/image|login-bg\\.(jpg|png|webp)|logo-.*\\.png|favicon\\.ico|api/agentharnesses/.*/gateway).*$"` | | | oauth2-proxy.extraArgs.skip-auth-route | string | `"^/(health|login)$"` | | | oauth2-proxy.extraArgs.skip-jwt-bearer-tokens | bool | `true` | | | oauth2-proxy.extraArgs.upstream | string | `"$(UPSTREAM_URL)"` | | @@ -249,6 +258,7 @@ A Helm chart for kagent, built with Google ADK | rbac.namespaces | list | `[]` | Namespaces in which to create Role and RoleBinding resources. If empty (default), the chart creates cluster-scoped ClusterRole and ClusterRoleBinding resources and the controller watches all namespaces. If set, the chart creates a Role + RoleBinding per listed namespace and the controller's WATCH_NAMESPACES is derived from this list (unless controller.watchNamespaces is set explicitly, which always takes precedence). | | registry | string | `"cr.kagent.dev"` | | | securityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true}` | Security context for all containers | +| substrateWorkerPool | object | `{"ateomImage":"","create":false,"name":"kagent-default","replicas":1}` | Optional Agent Substrate WorkerPool installed by this chart. This is platform capacity and is not owned by individual AgentHarness resources. | | tag | string | `""` | | | tolerations | list | `[]` | Node taints which will be tolerated for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). | | ui.additionalForwardedHeaders | list | `[]` | Additional request headers (beyond Authorization) the UI proxy will forward to the backend. Names are case-insensitive. Hop-by-hop headers (Connection, Transfer-Encoding, etc.) are silently dropped. |