Documentation
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 (e.g. OpenShell) and addressable by exec/SSH.
| 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 nemoclaw]
Appears in:
| Field | Description |
|---|---|
openclaw | |
nemoclaw |
AgentHarnessChannel#
AgentHarnessChannel declares one messenger binding inside an OpenClaw/NemoClaw 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 |
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. |
AgentHarnessNetwork#
AgentHarnessNetwork captures the minimal network-policy knobs exposed to users.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
allowedDomains string array | AllowedDomains is a list of DNS names the harness may reach. |
AgentHarnessSlackChannelSpec#
AgentHarnessSlackChannelSpec configures Slack when AgentHarnessChannel.type is Slack.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
botToken AgentHarnessChannelCredential | |||
appToken AgentHarnessChannelCredential | |||
channelAccess AgentHarnessChannelAccess | Enum: [allowlist open disabled] | ||
allowlistChannels string array | |||
interactiveReplies boolean | true |
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 nemoclaw] | |
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. | ||
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. | ||
network AgentHarnessNetwork | Network controls outbound access from the harness. When unset, backend defaults apply. | ||
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. |
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 nemoclaw] | ||
id string |
AgentHarnessTelegramChannelSpec#
AgentHarnessTelegramChannelSpec configures Telegram when AgentHarnessChannel.type is Telegram.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
botToken AgentHarnessChannelCredential | |||
allowedUserIDs string array | |||
allowedUserIDsFrom ValueSource |
AgentSkill#
Underlying type: AgentSkill
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. | ||
description string | Description is an optional detailed description of the skill. | ||
tags string array | Tags are optional tags for categorization. | ||
examples string array | Examples are optional usage examples. | ||
inputModes string array | InputModes are the supported input data modes/types. | ||
outputModes string array | OutputModes are the supported output data modes/types. |
AgentSpec#
AgentSpec defines the desired state of Agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type AgentType | Declarative | Enum: [Declarative BYO] | |
byo BYOAgentSpec | |||
declarative DeclarativeAgentSpec | |||
description string | |||
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-routing |
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 | Trust relationship to the agent. |
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}} |
ByoDeploymentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
image string | MinLength: 1 | ||
cmd string | |||
args string array | |||
replicas integer | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) | |||
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. - "python": Uses the Python ADK (default, slower startup, full feature set) - "go": Uses the Go ADK (faster startup, most features supported) The runtime determines both the container image and readiness probe configuration. | python | 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/google/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 (https://github.com/google/adk-python/issues/3921), this field is ignored for now. | ||
memory MemorySpec | Memory configuration for the agent. | ||
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 | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) | |||
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-routing
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. | ||
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-routing |
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 |
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 (agent-sandbox Sandbox CR).
| 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 AgentSpec | |||
status AgentStatus |
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. |
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) | |||
annotations object (keys:string, values:string) |
SharedDeploymentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
replicas integer | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) | |||
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 model provider connections. This enables agents to connect to internal LiteLLM gateways or other providers that use self-signed certificates or custom certificate authorities.
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 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). | ||
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 |
Kagent Lab: Discover kagent and kmcp
Free, on‑demand lab: build custom AI agents with kagent and integrate tools via kmcp on Kubernetes.