Skip to content

Update kagent and kmcp API reference docs #380

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
+89 −12
Open

Update kagent and kmcp API reference docs #380

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 77 additions & 10 deletions src/app/docs/kagent/resources/api-ref/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down Expand Up @@ -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] <br /> |
| `runtime` _[AgentHarnessRuntime](#agentharnessruntime)_ | Runtime selects the harness provisioning stack. Defaults to openshell when unset. | openshell | Enum: [openshell substrate] <br /> |
| `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<br />supports per-resource images. Backends openclaw and nemoclaw pin the image<br />to the NemoClaw sandbox base when this field is empty; backend hermes pins<br />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.<br />Values use the Kubernetes EnvVar shape; ValueFrom references are<br />resolved server-side where supported. | | |
Expand Down Expand Up @@ -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.<br />Example: gs://ate-snapshots/kagent/my-namespace/my-harness/ | | Pattern: `^gs://` <br /> |


#### 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.<br />When unset, the controller uses its configured default WorkerPool. | | |
| `snapshotsConfig` _[AgentHarnessSubstrateSnapshotsConfig](#agentharnesssubstratesnapshotsconfig)_ | SnapshotsConfig configures actor memory snapshots. Defaults to<br />gs://ate-snapshots/&lt;namespace&gt;/&lt;agentharnessname&gt; 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.<br />Prefer gatewayTokenSecretRef for production secrets. | | MinLength: 1 <br /> |
| `gatewayTokenSecretRef` _[TypedLocalReference](#typedlocalreference)_ | GatewayTokenSecretRef references a Secret key holding the OpenClaw gateway Bearer token.<br />The Secret must contain a "token" key. | | |


#### AgentHarnessTelegramChannelSpec


Expand Down Expand Up @@ -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.<br />and made available to the agent under the `/skills` folder. | | |
| `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.<br />This is intended for sandboxed declarative execution today, and can also<br />be consumed by BYO agents. | | |
| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.<br />This follows the Gateway API pattern for cross-namespace route attachments.<br />If not specified, only Agents in the same namespace can reference this Agent as a tool.<br />This field only applies when this Agent is used as a tool by another Agent.<br />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.<br />This follows the Gateway API pattern for cross-namespace route attachments.<br />If not specified, only Agents in the same namespace can reference this Agent as a tool.<br />This field only applies when this Agent is used as a tool by another Agent.<br />See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | |


#### AgentStatus
Expand Down Expand Up @@ -689,9 +751,9 @@ _Appears in:_
| `modelConfig` _string_ | The name of the model config to use.<br />If not specified, the default value is "default-model-config".<br />Must be in the same namespace as the Agent. | | |
| `stream` _boolean_ | Whether to stream the response from the model.<br />If not specified, the default value is false. | | |
| `tools` _[Tool](#tool) array_ | | | MaxItems: 20 <br /> |
| `a2aConfig` _[A2AConfig](#a2aconfig)_ | A2AConfig instantiates an A2A server for this agent,<br />served on the HTTP port of the kagent kubernetes<br />controller (default 8083).<br />The A2A server URL will be served at<br />&lt;kagent-controller-ip&gt;:8083/api/a2a/&lt;agent-namespace&gt;/&lt;agent-name&gt;<br />Read more about the A2A protocol here: https://github.com/google/A2A | | |
| `a2aConfig` _[A2AConfig](#a2aconfig)_ | A2AConfig instantiates an A2A server for this agent,<br />served on the HTTP port of the kagent kubernetes<br />controller (default 8083).<br />The A2A server URL will be served at<br />&lt;kagent-controller-ip&gt;:8083/api/a2a/&lt;agent-namespace&gt;/&lt;agent-name&gt;<br />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.<br />If true, the agent will automatically execute python code blocks in the LLM responses.<br />Code will be executed in a sandboxed environment.<br />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.<br />If true, the agent will automatically execute python code blocks in the LLM responses.<br />Code will be executed in a sandboxed environment.<br />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.<br />This includes event compaction (compression) and context caching. | | |

Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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.<br />This follows the Gateway API pattern for cross-namespace route attachments.<br />If not specified, only Agents in the same namespace can reference this RemoteMCPServer.<br />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.<br />This follows the Gateway API pattern for cross-namespace route attachments.<br />If not specified, only Agents in the same namespace can reference this RemoteMCPServer.<br />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.<br />Use this for HTTPS upstreams that present a certificate the agent's<br />system trust store does not include (corporate CA, self-signed cert<br />on a test fixture, internal MCP gateway). Reuses the same TLSConfig<br />type as ModelConfig.spec.tls — disableVerify turns off certificate<br />validation entirely, caCertSecretRef + caCertSecretKey point at a<br />PEM bundle Secret in the same namespace, and disableSystemCAs<br />trusts only the named bundle.<br /><br />Note one asymmetry with ModelConfig: a spec-level XValidation rule<br />on RemoteMCPServer rejects spec.tls when spec.url has the http://<br />scheme (a TLS opinion contradicts a plaintext URL). ModelConfig has<br />no equivalent rule, so a TLS block can sit alongside any baseUrl. | | |


#### RemoteMCPServerStatus
Expand All @@ -1242,6 +1305,7 @@ _Appears in:_
| `observedGeneration` _integer_ | INSERT ADDITIONAL STATUS FIELD - define observed state of cluster<br />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<br />agents that consume this RemoteMCPServer can detect cert rotation and<br />roll on the next reconcile. Empty when spec.tls.caCertSecretRef is unset. | | |


#### SAPAICoreConfig
Expand Down Expand Up @@ -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.<br />When false (default), SSL certificates are verified.<br />When true, SSL certificate verification is disabled.<br />WARNING: This should ONLY be used in development/testing environments.<br />Production deployments MUST use proper certificates. | false | |
| `caCertSecretRef` _string_ | CACertSecretRef is a reference to a Kubernetes Secret containing<br />CA certificate(s) in PEM format. The Secret must be in the same<br />namespace as the ModelConfig.<br />When set, the certificate will be used to verify the provider's SSL certificate.<br />This field follows the same pattern as APIKeySecret. | | |
| `caCertSecretKey` _string_ | CACertSecretKey is the key within the Secret that contains the CA certificate data.<br />This field follows the same pattern as APIKeySecretKey.<br />Required when CACertSecretRef is set (unless DisableVerify is true). | | |
| `caCertSecretRef` _string_ | CACertSecretRef is a reference to a Kubernetes Secret containing<br />CA certificate(s) in PEM format. The Secret must be in the same<br />namespace as the resource referencing it (ModelConfig,<br />RemoteMCPServer, or any future consumer of TLSConfig).<br />When set, the certificate will be used to verify the upstream's<br />SSL certificate. | | |
| `caCertSecretKey` _string_ | CACertSecretKey is the key within the Secret that contains the<br />CA certificate data (PEM-encoded). Required when CACertSecretRef<br />is set — admission rejects ref-without-key regardless of<br />DisableVerify (see the TLSConfig-level XValidation rules). | | |
| `disableSystemCAs` _boolean_ | DisableSystemCAs disables the use of system CA certificates.<br />When false (default), system CA certificates are used for verification (safe behavior).<br />When true, only the custom CA from CACertSecretRef is trusted.<br />This allows strict security policies where only corporate CAs should be trusted. | false | |


Expand Down Expand Up @@ -1507,6 +1573,7 @@ _Appears in:_


_Appears in:_
- [AgentHarnessSubstrateSpec](#agentharnesssubstratespec)
- [PromptSource](#promptsource)

| Field | Description | Default | Validation |
Expand Down
14 changes: 12 additions & 2 deletions src/app/docs/kagent/resources/helm/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:<port-or-443>` 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. |
Expand All @@ -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 | `[]` | |
Expand Down Expand Up @@ -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)"` | |
Expand Down Expand Up @@ -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. |
Expand Down