Skip to content

page.mdx

Latest commit

 

History

History
1705 lines (945 loc) · 75.1 KB

page.mdx

File metadata and controls

1705 lines (945 loc) · 75.1 KB
Raw
title API docs
pageOrder 1
description kagent API reference documentation

export const metadata = { title: "API docs", description: "kagent API reference documentation", author: "kagent.dev" };

API Reference

Packages

kagent.dev/v1alpha2

Package v1alpha1 contains API Schema definitions for the agent v1alpha1 API group.

Resource Types

A2AConfig

Appears in:

Field Description Default Validation
skills AgentSkill array MinItems: 1

Agent

Agent is the Schema for the agents API.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string Agent
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec AgentSpec
status AgentStatus

AgentHarness

AgentHarness is a generic remote execution environment provisioned by a backend (OpenClaw or Hermes) running on Agent Substrate.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string AgentHarness
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec AgentHarnessSpec
status AgentHarnessStatus

AgentHarnessBackendType

Underlying type: string

AgentHarnessBackendType selects which sandbox control plane provisions the environment. Additional backends may be added in the future.

Validation:

  • Enum: [openclaw hermes]

Appears in:

Field Description
openclaw
hermes

AgentHarnessChannel

AgentHarnessChannel declares one messenger binding inside a harness VM.

Appears in:

Field Description Default Validation
name string Name is a stable id for this binding (OpenClaw channels.*.accounts key). MinLength: 1
type AgentHarnessChannelType Enum: [telegram slack]
telegram AgentHarnessTelegramChannelSpec
slack AgentHarnessSlackChannelSpec Slack configures Slack when type is Slack.

AgentHarnessChannelAccess

Underlying type: string

AgentHarnessChannelAccess controls whether the bot listens broadly or only on an allowlist.

Validation:

  • Enum: [allowlist open disabled]

Appears in:

Field Description
allowlist
open
disabled

AgentHarnessChannelCredential

AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key.

Appears in:

Field Description Default Validation
value string MaxLength: 8192
valueFrom ValueSource

AgentHarnessChannelType

Underlying type: string

AgentHarnessChannelType selects a messenger integration for OpenClaw harness VMs.

Validation:

  • Enum: [telegram slack]

Appears in:

Field Description
telegram
slack

AgentHarnessConnection

AgentHarnessConnection describes how clients reach the provisioned harness VM.

Appears in:

Field Description Default Validation
endpoint string Endpoint is the backend-specific address (gRPC target, SSH host:port,
...) clients should use to reach the harness.

AgentHarnessHermesSlackOptions

AgentHarnessHermesSlackOptions configures Hermes-specific Slack settings (env vars in the sandbox).

Appears in:

Field Description Default Validation
allowedUserIDs string array AllowedUserIDs restricts which Slack member IDs may interact with the bot (SLACK_ALLOWED_USERS). MaxItems: 1024
allowedUserIDsFrom ValueSource
homeChannel string HomeChannel is the default Slack channel ID for cron/scheduled messages (SLACK_HOME_CHANNEL).
homeChannelName string HomeChannelName is a human-readable label for HomeChannel (SLACK_HOME_CHANNEL_NAME).

AgentHarnessOpenClawSlackOptions

AgentHarnessOpenClawSlackOptions configures OpenClaw-specific Slack routing.

Appears in:

Field Description Default Validation
channelAccess AgentHarnessChannelAccess Enum: [allowlist open disabled]
allowlistChannels string array AllowlistChannels is required when channelAccess is allowlist. MaxItems: 1024
interactiveReplies boolean true

AgentHarnessSlackChannelSpec

AgentHarnessSlackChannelSpec configures Slack when AgentHarnessChannel.type is Slack. Backend-specific settings live under the matching backend key; AgentHarnessSpec validation requires the key to match spec.backend.

Appears in:

Field Description Default Validation
botToken AgentHarnessChannelCredential
appToken AgentHarnessChannelCredential
openclaw AgentHarnessOpenClawSlackOptions OpenClaw configures OpenClaw-specific Slack routing.
hermes AgentHarnessHermesSlackOptions Hermes configures Hermes-specific Slack settings.

AgentHarnessSpec

AgentHarnessSpec describes a generic remote execution environment that agents (or human operators) can attach to via exec or SSH.

An AgentHarness is distinct from a SandboxAgent: it has no agent runtime baked in. The backend is responsible for provisioning an environment that stays ready to accept incoming commands.

Appears in:

Field Description Default Validation
backend AgentHarnessBackendType Backend selects the control plane to use. Required. Enum: [openclaw hermes]
substrate AgentHarnessSubstrateSpec Substrate configures the Agent Substrate provisioning stack. Required.
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. Backend openclaw pins the image
to the OpenClaw sandbox base when this field is empty; backend hermes pins
to the Hermes sandbox base image when empty.
env EnvVar 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.
modelConfigRef string ModelConfigRef is the reference to the ModelConfig used to configure the harness.
The controller registers the gateway provider and, after the harness is Ready,
writes OpenClaw config inside the VM (~/.openclaw/openclaw.json) and starts the gateway.
channels AgentHarnessChannel array Channels configures Telegram and Slack integrations for OpenClaw inside the harness VM. MaxItems: 1024

AgentHarnessStatus

AgentHarnessStatus is the observed state of an AgentHarness.

Appears in:

Field Description Default Validation
observedGeneration integer
conditions Condition array
backendRef AgentHarnessStatusRef BackendRef points at the harness instance on the backend control
plane, once Ensure has succeeded at least once.
connection AgentHarnessConnection Connection is populated by the controller when the harness is ready.

AgentHarnessStatusRef

AgentHarnessStatusRef identifies a harness instance on an external control plane.

Appears in:

Field Description Default Validation
backend AgentHarnessBackendType Enum: [openclaw hermes]
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:

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:

Field Description Default Validation
workerPoolRef TypedLocalReference WorkerPoolRef references an existing ate.dev WorkerPool in the harness namespace.
When unset, the controller uses its configured default WorkerPool.
snapshotsConfig AgentHarnessSubstrateSnapshotsConfig SnapshotsConfig configures actor memory snapshots. Defaults to
gs://ate-snapshots/<namespace>/<agentharnessname> when unset.
workloadImage string WorkloadImage overrides the default openclaw sandbox image in the ActorTemplate.

AgentHarnessTelegramChannelSpec

AgentHarnessTelegramChannelSpec configures Telegram when AgentHarnessChannel.type is Telegram.

Appears in:

Field Description Default Validation
botToken AgentHarnessChannelCredential
allowedUserIDs string array MaxItems: 1024
allowedUserIDsFrom ValueSource

AgentProvider

AgentProvider identifies the organization responsible for an agent on its A2A AgentCard.

Appears in:

Field Description Default Validation
organization string Organization is the name of the agent provider's organization. MinLength: 1
url string URL is a URL for the agent provider's website or relevant documentation. Format: uri

AgentSkill

AgentSkill describes a specific capability or function of the agent.

Appears in:

Field Description Default Validation
id string ID is the unique identifier for the skill.
name string Name is the human-readable name of the skill. MinLength: 1
description string Description is an optional detailed description of the skill.
tags string array Tags are optional tags for categorization. MaxItems: 20
examples string array Examples are optional usage examples. MaxItems: 20
inputModes string array InputModes are the supported input MIME types for this skill, overriding the agent's defaults.
outputModes string array OutputModes are the supported output MIME types for this skill, overriding the agent's defaults.

AgentSpec

AgentSpec defines the desired state of Agent.

Appears in:

Field Description Default Validation
type AgentType Declarative Enum: [Declarative BYO]
byo BYOAgentSpec BYO configures a "bring your own" agent backed by a user-provided
container image. Kagent deploys the image and expects it to serve the
agent over the A2A protocol on port 8080.
Required if type is BYO.
declarative DeclarativeAgentSpec Declarative configures an agent that is fully described by this resource
(model, instructions, tools) and runs on one of kagent's built-in runtimes.
Required if type is Declarative.
description string
iconUrl string IconURL is a URL to an icon representing the agent. It is surfaced on the
agent's A2A AgentCard.		 Format: uri
documentationUrl string DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard.		 Format: uri
version string Version is the agent's version string, surfaced on the A2A AgentCard.
provider AgentProvider Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard.
skills 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 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 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

AgentStatus defines the observed state of Agent.

Appears in:

Field Description Default Validation
observedGeneration integer
conditions Condition array

AgentType

Underlying type: string

AgentType represents the agent type

Validation:

  • Enum: [Declarative BYO]

Appears in:

Field Description
Declarative
BYO

AllowedNamespaces

AllowedNamespaces defines which namespaces are allowed to reference this resource. This mechanism provides a bidirectional handshake for cross-namespace references, following the pattern used by Gateway API for cross-namespace route attachments.

By default (when not specified), only references from the same namespace are allowed.

Appears in:

Field Description Default Validation
from FromNamespaces From indicates where references to this resource can originate.
Possible values are:
* All: References from all namespaces are allowed.
* Same: Only references from the same namespace are allowed (default).
* Selector: References from namespaces matching the selector are allowed.		 Same Enum: [All Same Selector]
selector LabelSelector Selector is a label selector for namespaces that are allowed to reference this resource.
Only used when From is set to "Selector".

AnthropicConfig

AnthropicConfig contains Anthropic-specific configuration options

Appears in:

Field Description Default Validation
baseUrl string Base URL for the Anthropic API (overrides default)
maxTokens integer Maximum tokens to generate
temperature string Temperature for sampling
topP string Top-p sampling parameter
topK integer Top-k sampling parameter

AnthropicVertexAIConfig

Appears in:

Field Description Default Validation
projectID string The project ID
location string The project location
temperature string Temperature
topP string Top-p sampling parameter
topK string Top-k sampling parameter
stopSequences string array Stop sequences
maxTokens integer Maximum tokens to generate

AzureOpenAIConfig

AzureOpenAIConfig contains Azure OpenAI-specific configuration options

Appears in:

Field Description Default Validation
azureEndpoint string Endpoint for the Azure OpenAI API
apiVersion string API version for the Azure OpenAI API
azureDeployment string Deployment name for the Azure OpenAI API
azureAdToken string Azure AD token for authentication
temperature string Temperature for sampling
maxTokens integer Maximum tokens to generate
topP string Top-p sampling parameter

BYOAgentSpec

Appears in:

Field Description Default Validation
deployment ByoDeploymentSpec Deployment configures the Kubernetes Deployment created for the BYO agent container.

BaseVertexAIConfig

Appears in:

Field Description Default Validation
projectID string The project ID
location string The project location
temperature string Temperature
topP string Top-p sampling parameter
topK string Top-k sampling parameter
stopSequences string array Stop sequences

BedrockConfig

BedrockConfig contains AWS Bedrock-specific configuration options.

Appears in:

Field Description Default Validation
region string AWS region where the Bedrock model is available (e.g., us-east-1, us-west-2)
additionalModelRequestFields JSON AdditionalModelRequestFields passes model-specific parameters to Bedrock's
additionalModelRequestFields in the Converse API. Use this for provider-specific
options that are not part of the standard InferenceConfiguration block, such as
Claude extended thinking or top_k. Values are forwarded as-is to the API.
Example: {"top_k": 5, "thinking": {"type": "enabled", "budget_tokens": 16000}}
promptCaching boolean PromptCaching enables Bedrock prompt caching by appending a CachePoint
block at the end of the Converse request's system content array and
the end of the toolConfig.tools array. Bedrock will cache the prefix up to and
including those cache points across requests in the same region for
roughly 5 minutes after first use, billing the cached portion at a
reduced rate on cache hits.

Recommended for tool-using agents that make many Converse calls per
task with a stable system prompt and tool set — the per-call input
token count can drop by 70-90% on hit. Has no effect on models that
don't support caching; the marker is ignored by Bedrock for those.

See https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
for the current list of supported models and minimum prefix sizes.		 false
cacheTTL string CacheTTL controls how long Bedrock retains a cached prefix when
PromptCaching is enabled. Only meaningful when PromptCaching is true.

- "5m" (default): Bedrock's standard 5-minute sliding cache. Each cache
hit refreshes the window. Supported by all prompt-caching models.
- "1h": extended-TTL caching, useful for tasks whose Converse calls are
spaced more than 5 minutes apart.

NOTE: "1h" is NOT strictly better than "5m". Extended-TTL cache writes are
billed at a higher per-token rate than 5-minute writes, and 1h is supported
on a narrower set of models. Only choose "1h" when calls are spaced far
enough apart that a 5-minute cache would expire between them; otherwise the
higher write cost is wasted. See the AWS prompt-caching docs above.		 5m Enum: [5m 1h]

ByoDeploymentSpec

Appears in:

Field Description Default Validation
image string Image is the container image of the BYO agent.
The image is expected to serve the agent over the A2A protocol on port 8080.		 MinLength: 1
cmd string Cmd overrides the container entrypoint (the container's command).
args string array Args are the arguments passed to the container entrypoint.
workingDir string workingDir sets the container working directory. Defaults to the image WORKDIR when omitted.
replicas integer Replicas is the number of desired agent pods. Defaults to 1.
imagePullSecrets LocalObjectReference array ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image.
volumes Volume array Volumes are additional volumes added to the agent pod.
volumeMounts VolumeMount array VolumeMounts are additional volume mounts added to the agent container.
labels object (keys:string, values:string) Labels are additional labels added to the agent pods.
annotations object (keys:string, values:string) Annotations are additional annotations added to the agent pods.
env EnvVar array Env are additional environment variables set on the agent container.
imagePullPolicy PullPolicy
resources ResourceRequirements
tolerations Toleration array Tolerations applied to the agent pods.
affinity Affinity
nodeSelector object (keys:string, values:string) NodeSelector restricts the nodes the agent pods can be scheduled on.
securityContext SecurityContext
podSecurityContext PodSecurityContext
serviceAccountName string ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig.
serviceAccountConfig ServiceAccountConfig ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it.
extraContainers Container array ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents.

ContextCompressionConfig

ContextCompressionConfig configures event history compaction/compression.

Appears in:

Field Description Default Validation
compactionInterval integer The number of new user-initiated invocations that, once fully represented in the session's events, will trigger a compaction. 5 Minimum: 1
overlapSize integer The number of preceding invocations to include from the end of the last compacted range. This creates an overlap between consecutive compacted summaries, maintaining context. 2 Minimum: 0
summarizer ContextSummarizerConfig Summarizer configures an LLM-based summarizer for event compaction.
If not specified, compacted events are dropped from the context without summarization.
tokenThreshold integer Post-invocation token threshold trigger. If set, ADK will attempt a post-invocation compaction when the most recently
observed prompt token count meets or exceeds this threshold.
eventRetentionSize integer EventRetentionSize is the number of most recent events to always retain.

ContextConfig

ContextConfig configures context management for an agent.

Appears in:

Field Description Default Validation
compaction ContextCompressionConfig Compaction configures event history compaction.
When enabled, older events in the conversation are compacted (compressed/summarized)
to reduce context size while preserving key information.

ContextSummarizerConfig

ContextSummarizerConfig configures the LLM-based event summarizer.

Appears in:

Field Description Default Validation
modelConfig string ModelConfig is the name of a ModelConfig resource to use for summarization.
Must be in the same namespace as the Agent.
If not specified, uses the agent's own model.
promptTemplate string PromptTemplate is a custom prompt template for the summarizer.
See the ADK LlmEventSummarizer for template details:
https://github.com/google/adk-python/blob/main/src/google/adk/apps/llm_event_summarizer.py

DeclarativeAgentSpec

Appears in:

Field Description Default Validation
runtime DeclarativeRuntime Runtime specifies which ADK implementation to use for this agent.
- "go": Uses the Go ADK (default, faster startup, most features supported)
- "python": Uses the Python ADK (slower startup, full feature set)
The runtime determines both the container image and readiness probe configuration.		 go Enum: [python go]
systemMessage string SystemMessage is a string specifying the system message for the agent.
When PromptTemplate is set, this field is treated as a Go text/template
with access to an include("source/key") function and agent context variables
such as .AgentName, .AgentNamespace, .Description, .ToolNames, and .SkillNames.
systemMessageFrom ValueSource SystemMessageFrom is a reference to a ConfigMap or Secret containing the system message.
When PromptTemplate is set, the resolved value is treated as a Go text/template.
promptTemplate PromptTemplateSpec PromptTemplate enables Go text/template processing on the systemMessage field.
When set, systemMessage is treated as a Go template with access to the include function
and agent context variables.
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 array MaxItems: 20
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
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 (google/adk-python#3921 ), this field is ignored for now.
memory MemorySpec Memory configuration for the agent.
shareTools boolean ShareTools enables the built-in share link tools for this agent.
When true, the agent gains create_share_link, list_share_links, and delete_share_link tools
that allow it to manage share tokens for the current session.
context ContextConfig Context configures context management for this agent.
This includes event compaction (compression) and context caching.

DeclarativeDeploymentSpec

Appears in:

Field Description Default Validation
imageRegistry string
replicas integer Replicas is the number of desired agent pods. Defaults to 1.
imagePullSecrets LocalObjectReference array ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image.
volumes Volume array Volumes are additional volumes added to the agent pod.
volumeMounts VolumeMount array VolumeMounts are additional volume mounts added to the agent container.
labels object (keys:string, values:string) Labels are additional labels added to the agent pods.
annotations object (keys:string, values:string) Annotations are additional annotations added to the agent pods.
env EnvVar array Env are additional environment variables set on the agent container.
imagePullPolicy PullPolicy
resources ResourceRequirements
tolerations Toleration array Tolerations applied to the agent pods.
affinity Affinity
nodeSelector object (keys:string, values:string) NodeSelector restricts the nodes the agent pods can be scheduled on.
securityContext SecurityContext
podSecurityContext PodSecurityContext
serviceAccountName string ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig.
serviceAccountConfig ServiceAccountConfig ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it.
extraContainers Container array ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents.

DeclarativeRuntime

Underlying type: string

DeclarativeRuntime represents the runtime implementation for declarative agents

Validation:

  • Enum: [python go]

Appears in:

Field Description
python
go

FromNamespaces

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-route-attachment

Validation:

  • Enum: [All Same Selector]

Appears in:

Field Description
All NamespacesFromAll allows references from all namespaces.
Same NamespacesFromSame only allows references from the same namespace as the target resource (default).
Selector NamespacesFromSelector allows references from namespaces matching the selector.

GDCHServiceAccountConfig

GDCHServiceAccountConfig holds GDCH-specific token exchange parameters.

Appears in:

Field Description Default Validation
audience string Audience is the token exchange audience URL (the GDC inference gateway base URL)

GeminiConfig

Appears in:

GeminiVertexAIConfig

GeminiVertexAIConfig contains Gemini Vertex AI-specific configuration options

Appears in:

Field Description Default Validation
projectID string The project ID
location string The project location
temperature string Temperature
topP string Top-p sampling parameter
topK string Top-k sampling parameter
stopSequences string array Stop sequences
maxOutputTokens integer Maximum output tokens
candidateCount integer Candidate count
responseMimeType string Response mime type

GitRepo

GitRepo specifies a single Git repository to fetch skills from.

Appears in:

Field Description Default Validation
url string URL of the git repository (HTTPS or SSH).
ref string Git reference: branch name, tag, or commit SHA. main
path string Subdirectory within the repo to use as the skill root. The API validates
this input path, but treats repository contents as trusted: symlinks under
this path are dereferenced when materializing the skill.
name string Name for the skill directory under /skills. If omitted, defaults to the last
segment of Path when Path is set; otherwise defaults to the repo name (last
URL path segment, without .git).

MCPTool

Appears in:

Field Description Default Validation
name string
description string

McpServerTool

Appears in:

Field Description Default Validation
kind string
apiGroup string
name string
namespace string
toolNames string array The names of the tools to be provided by the ToolServer
For a list of all the tools provided by the server,
the client can query the status of the ToolServer object after it has been created		 MaxItems: 50
requireApproval string array RequireApproval lists tool names that require human approval before
execution. Each name must also appear in ToolNames. When a tool in
this list is invoked by the agent, execution pauses and the user is
prompted to approve or reject the call.		 MaxItems: 50
allowedHeaders string array AllowedHeaders specifies which headers from the A2A request should be
propagated to MCP tool calls. Header names are case-insensitive.

Authorization header behavior:
- Authorization headers CAN be propagated if explicitly listed in allowedHeaders
- When STS token propagation is enabled, STS-generated Authorization headers
will take precedence and replace any Authorization header from the A2A request
- This is a security measure to prevent request headers from overwriting
authentication tokens generated by the STS integration

Example: ["x-user-email", "x-tenant-id"]

MemorySpec

MemorySpec enables long-term memory for an agent.

Appears in:

Field Description Default Validation
modelConfig string ModelConfig is the name of the ModelConfig object whose embedding
provider will be used to generate memory vectors.
ttlDays integer TTLDays controls how many days a stored memory entry remains valid before
it is eligible for pruning. Defaults to 15 days when unset or zero.		 Minimum: 1

ModelConfig

ModelConfig is the Schema for the modelconfigs API.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string ModelConfig
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ModelConfigSpec
status ModelConfigStatus

ModelConfigSpec

ModelConfigSpec defines the desired state of ModelConfig.

Appears in:

Field Description Default Validation
model string
apiKeySecret string The name of the secret that contains the API key. Must be a reference to the name of a secret in the same namespace as the referencing ModelConfig.
For the SAPAICore provider, the secret must contain two keys: "client_id" and "client_secret"
(the OAuth2 client credentials for SAP AI Core). The apiKeySecretKey field is not used for SAPAICore.
apiKeySecretKey string The key in the secret that contains the API key.
Not used for the SAPAICore provider (which always reads "client_id" and "client_secret" from the secret).
apiKeyPassthrough boolean APIKeyPassthrough enables forwarding the Bearer token from incoming A2A requests
directly to the LLM provider as the API key. This is useful for organizations
with federated identity that want to avoid separate secret management.
Mutually exclusive with apiKeySecret.
defaultHeaders object (keys:string, values:string)
provider ModelProvider The provider of the model OpenAI Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore]
openAI OpenAIConfig OpenAI-specific configuration
anthropic AnthropicConfig Anthropic-specific configuration
azureOpenAI AzureOpenAIConfig Azure OpenAI-specific configuration
ollama OllamaConfig Ollama-specific configuration
gemini GeminiConfig Gemini-specific configuration
geminiVertexAI GeminiVertexAIConfig Gemini Vertex AI-specific configuration
anthropicVertexAI AnthropicVertexAIConfig Anthropic-specific configuration
bedrock BedrockConfig AWS Bedrock-specific configuration
sapAICore SAPAICoreConfig SAP AI Core-specific configuration
tls TLSConfig TLS configuration for provider connections.
Enables agents to connect to internal LiteLLM gateways or other providers
that use self-signed certificates or custom certificate authorities.

ModelConfigStatus

ModelConfigStatus defines the observed state of ModelConfig.

Appears in:

Field Description Default Validation
conditions Condition array
observedGeneration integer
secretHash string The secret hash stores a hash of any secrets required by the model config (i.e. api key, tls cert) to ensure agents referencing this model config detect changes to these secrets and restart if necessary.

ModelProvider

Underlying type: string

ModelProvider represents the model provider type

Validation:

  • Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore]

Appears in:

Field Description
Anthropic
AzureOpenAI
OpenAI
Ollama
Gemini
GeminiVertexAI
AnthropicVertexAI
Bedrock
SAPAICore

ModelProviderConfig

ModelProviderConfig is the Schema for the modelproviderconfigs API. It represents a model provider configuration with automatic model discovery.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string ModelProviderConfig
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ModelProviderConfigSpec
status ModelProviderConfigStatus

ModelProviderConfigSpec

ModelProviderConfigSpec defines the desired state of ModelProviderConfig.

Appears in:

Field Description Default Validation
type ModelProvider Type is the model provider type (OpenAI, Anthropic, etc.) Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore]
endpoint string Endpoint is the API endpoint URL for the provider.
If not specified, the default endpoint for the provider type will be used.		 Pattern: ^https?://.*
secretRef SecretReference SecretRef references the Kubernetes Secret containing the API key.
Optional for providers that don't require authentication (e.g., local Ollama).

ModelProviderConfigStatus

ModelProviderConfigStatus defines the observed state of ModelProviderConfig.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration reflects the generation of the most recently observed ModelProviderConfig spec
conditions Condition array Conditions represent the latest available observations of the ModelProviderConfig's state
discoveredModels string array DiscoveredModels is the cached list of model IDs available from this model provider
modelCount integer ModelCount is the number of discovered models (for kubectl display)
lastDiscoveryTime Time LastDiscoveryTime is the timestamp of the last successful model discovery
secretHash string SecretHash is a hash of the referenced secret data, used to detect secret changes

NetworkConfig

NetworkConfig configures outbound network access for sandboxed execution paths.

Appears in:

Field Description Default Validation
allowedDomains string array AllowedDomains lists the domains that sandboxed execution may contact.
Wildcards such as *.example.com are supported by the sandbox runtime.

OllamaConfig

OllamaConfig contains Ollama-specific configuration options

Appears in:

Field Description Default Validation
host string Host for the Ollama API
options object (keys:string, values:string) Options for the Ollama API

OpenAIConfig

OpenAIConfig contains OpenAI-specific configuration options

Appears in:

Field Description Default Validation
baseUrl string Base URL for the OpenAI API (overrides default)
organization string Organization ID for the OpenAI API
temperature string Temperature for sampling
maxTokens integer Maximum tokens to generate
topP string Top-p sampling parameter
frequencyPenalty string Frequency penalty
presencePenalty string Presence penalty
seed integer Seed value
n integer N value
timeout integer Timeout
reasoningEffort OpenAIReasoningEffort Reasoning effort Enum: [minimal low medium high]
tokenExchange TokenExchangeConfig TokenExchange configures dynamic bearer token acquisition via credential exchange.
Requires apiKeySecret (used as the service account secret) and is mutually exclusive with apiKeyPassthrough.

OpenAIReasoningEffort

Underlying type: string

OpenAIReasoningEffort represents how many reasoning tokens the model generates before producing a response.

Validation:

  • Enum: [minimal low medium high]

Appears in:

PromptSource

PromptSource references a ConfigMap whose keys are available as prompt fragments. In systemMessage templates, use include("alias/key") (or include("name/key") if no alias is set) to insert the value of a specific key from this source.

Appears in:

Field Description Default Validation
kind string
apiGroup string
name string
alias string Alias is an optional short identifier for use in include directives.
If set, use include("alias/key") instead of include("name/key").

PromptTemplateSpec

PromptTemplateSpec configures prompt template processing for an agent's system message.

Appears in:

Field Description Default Validation
dataSources PromptSource array DataSources defines the ConfigMaps whose keys can be included in the systemMessage
using Go template syntax, e.g. include("alias/key") or include("name/key").		 MaxItems: 20

RemoteMCPServer

RemoteMCPServer is the Schema for the RemoteMCPServers API.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string RemoteMCPServer
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec RemoteMCPServerSpec
status RemoteMCPServerStatus

RemoteMCPServerProtocol

Underlying type: string

Validation:

  • Enum: [SSE STREAMABLE_HTTP]

Appears in:

Field Description
SSE
STREAMABLE_HTTP

RemoteMCPServerSpec

RemoteMCPServerSpec defines the desired state of RemoteMCPServer.

Appears in:

Field Description Default Validation
description string
protocol RemoteMCPServerProtocol STREAMABLE_HTTP Enum: [SSE STREAMABLE_HTTP]
url string MinLength: 1
headersFrom ValueRef array
timeout Duration 30s
sseReadTimeout Duration
terminateOnClose boolean true
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

A cross-namespace-permitting value (from: All or from: Selector) is
mutually exclusive with spec.tls.caCertSecretRef (enforced by a spec-level
XValidation rule): a pinned CA Secret is mounted onto the consuming agent's
pod by bare name and Kubernetes resolves it in the agent's namespace, not
this RemoteMCPServer's, so a CA-pinning RemoteMCPServer cannot be referenced
cross-namespace. from: Same (the default) is always allowed.
tls 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

RemoteMCPServerStatus defines the observed state of RemoteMCPServer.

Appears in:

Field Description Default Validation
observedGeneration integer INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
Important: Run "make" to regenerate code after modifying this file
conditions Condition array
discoveredTools 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

SAPAICoreConfig contains SAP AI Core-specific configuration options.

Appears in:

Field Description Default Validation
baseUrl string Base URL for the SAP AI Core API (e.g., https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com)
resourceGroup string Resource group in SAP AI Core default
authUrl string OAuth2 token endpoint URL (e.g., https://tenant.authentication.eu10.hana.ondemand.com)

SandboxAgent

SandboxAgent declares an agent that runs in an isolated sandbox on Agent Substrate.

Field Description Default Validation
apiVersion string kagent.dev/v1alpha2
kind string SandboxAgent
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec SandboxAgentSpec
status AgentStatus

SandboxAgentSpec

Appears in:

Field Description Default Validation
type AgentType Declarative Enum: [Declarative BYO]
byo BYOAgentSpec BYO configures a "bring your own" agent backed by a user-provided
container image. Kagent deploys the image and expects it to serve the
agent over the A2A protocol on port 8080.
Required if type is BYO.
declarative DeclarativeAgentSpec Declarative configures an agent that is fully described by this resource
(model, instructions, tools) and runs on one of kagent's built-in runtimes.
Required if type is Declarative.
description string
iconUrl string IconURL is a URL to an icon representing the agent. It is surfaced on the
agent's A2A AgentCard.		 Format: uri
documentationUrl string DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard.		 Format: uri
version string Version is the agent's version string, surfaced on the A2A AgentCard.
provider AgentProvider Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard.
skills 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 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 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
substrate SandboxSubstrateSpec Substrate is optional Agent Substrate-specific settings.

SandboxConfig

SandboxConfig configures sandboxed execution behavior.

Appears in:

Field Description Default Validation
network NetworkConfig Network configures outbound network access for sandboxed execution paths.
When unset or when allowedDomains is empty, outbound access is denied by default.

SandboxSubstrateSpec

SandboxSubstrateSpec configures Agent Substrate for a SandboxAgent. WorkerPool capacity is referenced from workerPoolRef or the controller default.

Appears in:

Field Description Default Validation
workerPoolRef TypedLocalReference WorkerPoolRef references an existing ate.dev WorkerPool.
snapshotsConfig AgentHarnessSubstrateSnapshotsConfig SnapshotsConfig configures actor memory snapshots.
Defaults to gs://ate-snapshots/<namespace>/<agentname> when unset.

SecretReference

SecretReference references a Kubernetes Secret that must contain exactly one data key holding the API key or credential.

Appears in:

Field Description Default Validation
name string Name is the name of the secret in the same namespace as the ModelProviderConfig.

ServiceAccountConfig

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Labels are additional labels added to the created ServiceAccount.
annotations object (keys:string, values:string) Annotations are additional annotations added to the created ServiceAccount.

SharedDeploymentSpec

Appears in:

Field Description Default Validation
replicas integer Replicas is the number of desired agent pods. Defaults to 1.
imagePullSecrets LocalObjectReference array ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image.
volumes Volume array Volumes are additional volumes added to the agent pod.
volumeMounts VolumeMount array VolumeMounts are additional volume mounts added to the agent container.
labels object (keys:string, values:string) Labels are additional labels added to the agent pods.
annotations object (keys:string, values:string) Annotations are additional annotations added to the agent pods.
env EnvVar array Env are additional environment variables set on the agent container.
imagePullPolicy PullPolicy
resources ResourceRequirements
tolerations Toleration array Tolerations applied to the agent pods.
affinity Affinity
nodeSelector object (keys:string, values:string) NodeSelector restricts the nodes the agent pods can be scheduled on.
securityContext SecurityContext
podSecurityContext PodSecurityContext
serviceAccountName string ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig.
serviceAccountConfig ServiceAccountConfig ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it.
extraContainers Container array ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents.

SkillForAgent

Appears in:

Field Description Default Validation
insecureSkipVerify boolean Fetch images insecurely from registries (allowing HTTP and skipping TLS verification).
Meant for development and testing purposes only.
refs string array The list of skill images to fetch. MaxItems: 20
MinItems: 1
imagePullSecrets LocalObjectReference array ImagePullSecrets is a list of references to secrets in the same namespace to use for
pulling skill images from private registries. Each referenced secret must be of type
kubernetes.io/dockerconfigjson. The credentials from all secrets are merged and made
available to the skills-init container at /.kagent/.docker/config.json; krane will
use them automatically when pulling images.		 MaxItems: 20
gitAuthSecretRef LocalObjectReference Reference to a Secret containing git credentials.
Applied to all gitRefs entries.
The secret should contain a token key for HTTPS auth,
or ssh-privatekey for SSH auth.
gitRefs GitRepo array Git repositories to fetch skills from. MaxItems: 20
MinItems: 1
initContainer SkillsInitContainer Configuration for the skills-init init container.

SkillsInitContainer

SkillsInitContainer configures the skills-init init container.

Appears in:

Field Description Default Validation
resources ResourceRequirements Resource requirements for the skills-init init container.
env EnvVar array Additional environment variables for the skills-init init container.

TLSConfig

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:

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 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

TokenExchangeConfig

TokenExchangeConfig configures dynamic bearer token acquisition before model calls.

Appears in:

Field Description Default Validation
type TokenExchangeType Enum: [GDCHServiceAccount]
gdchServiceAccount GDCHServiceAccountConfig

TokenExchangeType

Underlying type: string

TokenExchangeType identifies the token exchange mechanism

Validation:

  • Enum: [GDCHServiceAccount]

Appears in:

Field Description
GDCHServiceAccount

Tool

Appears in:

Field Description Default Validation
type ToolProviderType Enum: [McpServer Agent]
mcpServer McpServerTool
agent TypedReference
headersFrom ValueRef array HeadersFrom specifies a list of configuration values to be added as
headers to requests sent to the Tool from this agent. The value of
each header is resolved from either a Secret or ConfigMap in the same
namespace as the Agent. Headers specified here will override any
headers of the same name/key specified on the tool.

ToolProviderType

Underlying type: string

ToolProviderType represents the tool provider type

Validation:

  • Enum: [McpServer Agent]

Appears in:

Field Description
McpServer
Agent

TypedLocalReference

Appears in:

Field Description Default Validation
kind string
apiGroup string
name string

TypedReference

Appears in:

Field Description Default Validation
kind string
apiGroup string
name string
namespace string

ValueRef

ValueRef represents a configuration value

Appears in:

Field Description Default Validation
name string
value string
valueFrom ValueSource

ValueSource

ValueSource defines a source for configuration values from a Secret or ConfigMap

Appears in:

Field Description Default Validation
type ValueSourceType Enum: [ConfigMap Secret]
name string The name of the ConfigMap or Secret. MaxLength: 253
key string The key of the ConfigMap or Secret. MaxLength: 253

ValueSourceType

Underlying type: string

Appears in:

Field Description
ConfigMap
Secret