API reference

Look up every field in the kagent v1alpha3 custom resources, including AgentTemplate, Harness, ModelConfig, and RemoteMCPServer.

Packages

kagent.dev/v1alpha3

kagent.dev/v1alpha3

Package v1alpha3 contains API Schema definitions for the kagent.dev v1alpha3 API group.

Resource Types

AgentTemplate
Harness
ModelConfig
ModelProviderConfig
RemoteMCPServer

AgentTemplate

AgentTemplate defines portable agent behavior.

Field	Description	Default	Validation
`apiVersion` string	`kagent.dev/v1alpha3`
`kind` string	`AgentTemplate`
`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` AgentTemplateSpec
`status` AgentTemplateStatus

AgentTemplateConfigMapKeyReference

AgentTemplateConfigMapKeyReference identifies a key in a same-namespace ConfigMap.

Appears in:

AgentTemplateSpec

Field	Description	Default	Validation
`name` string			MinLength: 1
`key` string			MinLength: 1

AgentTemplateHarnessStatus

AgentTemplateHarnessStatus reports runtime revision state for one admitting Harness.

Appears in:

AgentTemplateStatus

Field	Description	Validation
`harness` string	Harness names a same-namespace Harness whose admission selector matches this AgentTemplate.	MinLength: 1
`desiredRevision` string		MinLength: 1
`latestSuccessfulRevision` string		MinLength: 1
`warnings` string array	Warnings reports non-blocking compatibility decisions made while compiling this AgentTemplate for the Harness.	MaxItems: 100
`conditions` Condition array		MaxItems: 4

AgentTemplatePromptSource

AgentTemplatePromptSource makes a same-namespace ConfigMap available to a prompt template.

Appears in:

AgentTemplatePromptTemplateSpec

Field	Description	Default	Validation
`name` string			MinLength: 1
`alias` string	Alias is the name used by include. The ConfigMap name is used when omitted.		MinLength: 1

AgentTemplatePromptTemplateSpec

AgentTemplatePromptTemplateSpec enables Go template rendering and ConfigMap includes.

Appears in:

AgentTemplateSpec

Field	Description	Default	Validation
`dataSources` AgentTemplatePromptSource array	DataSources are same-namespace ConfigMaps available to include(“source/key”).		MaxItems: 20

AgentTemplateSkill

AgentTemplateSkill identifies one standalone skill and its immutable source.

Appears in:

AgentTemplateSpec

Field	Description	Default	Validation
`name` string			MinLength: 1
`source` ArtifactSource

AgentTemplateSpec

AgentTemplateSpec defines portable agent behavior.

Appears in:

AgentTemplate

Field	Description	Validation
`modelConfig` LocalObjectReference	ModelConfig is required by managed harnesses and optional for BYO harnesses.
`description` string
`systemPrompt` string
`systemPromptFrom` AgentTemplateConfigMapKeyReference	SystemPromptFrom references prompt text in a same-namespace ConfigMap.
`promptTemplate` AgentTemplatePromptTemplateSpec
`tools` ToolBinding array		MaxItems: 50
`skills` AgentTemplateSkill array		MaxItems: 50
`plugins` PluginBundle array		MaxItems: 20

AgentTemplateStatus

AgentTemplateStatus is the controller-observed state for each admitting Harness.

Appears in:

AgentTemplate

Field	Description	Default	Validation
`observedGeneration` integer
`harnesses` AgentTemplateHarnessStatus array	Harnesses has at most one entry for each admitting Harness.

AgentToolBinding

AgentToolBinding exposes another same-namespace AgentTemplate as a logical tool.

Appears in:

ToolBinding

Field	Description	Default	Validation
`name` string			MinLength: 1
`description` string	Description tells the parent when to route work to this binding.		MinLength: 1
`templateRef` LocalObjectReference
`isolation` AgentToolIsolation		Shared	Enum: [Shared Dedicated]

AgentToolIsolation

Underlying type: string

AgentToolIsolation controls whether a referenced template shares its parent’s runtime boundary.

Validation:

Enum: [Shared Dedicated]

Appears in:

AgentToolBinding

Field	Description
`Shared`
`Dedicated`

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:

RemoteMCPServerSpec

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:

ModelConfigSpec

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:

ModelConfigSpec

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

ArtifactSource

ArtifactSource selects exactly one immutable artifact.

Appears in:

AgentTemplateSkill
PluginBundle

Field	Description	Validation
`oci` string	OCI is a digest-pinned image reference.	Pattern: `^[^[:space:]@]+@sha256:[0-9a-f]\{64\}$`
`git` GitArtifact
`bucket` BucketArtifact
`path` string	Path selects a directory within the immutable artifact.	MaxLength: 1024

AzureOpenAIConfig

AzureOpenAIConfig contains Azure OpenAI-specific configuration options

Appears in:

ModelConfigSpec

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

BYOHarness

BYOHarness selects an image that implements kagent’s private A2A contract.

Appears in:

HarnessSpec

BaseVertexAIConfig

Appears in:

AnthropicVertexAIConfig
GeminiVertexAIConfig

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:

ModelConfigSpec

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]
`guardrail` BedrockGuardrailConfig
`readTimeout` integer	ReadTimeout is the Bedrock HTTP client read timeout in seconds, applied by both the Python and Go ADK runtimes. Raise this for agents that make long Converse calls (large tool-augmented turns, extended reasoning). On the Python ADK it overrides botocore’s ~60s read timeout, which otherwise aborts long completions with a ReadTimeoutError; on the Go ADK it bounds the whole Converse request (default 30m). When unset, each runtime’s default is used.		Minimum: 1
`connectTimeout` integer	ConnectTimeout is the Bedrock HTTP client connection-establishment timeout in seconds, applied by both the Python and Go ADK runtimes. It bounds connection setup only, not the response read. When unset, each runtime’s default is used (Python ADK: botocore; Go ADK: net dialer).		Minimum: 1

BedrockGuardrailConfig

Appears in:

BedrockConfig

Field	Description	Default	Validation
`identifier` string	Identifier is the guardrail ID or full ARN. AWS accepts either a bare guardrail ID or an arn:aws:bedrock:…:guardrail/… ARN, so the value is only length-bounded here (AWS caps guardrailIdentifier at 2048 chars).		MaxLength: 2048 MinLength: 1
`version` string	Version is the guardrail version: a numeric version (e.g. “1”) or “DRAFT”.		MaxLength: 8 MinLength: 1
`trace` string		disabled	Enum: [disabled enabled enabled_full]

BucketArtifact

BucketArtifact selects the supported object-store provider.

Appears in:

ArtifactSource

Field	Description	Default	Validation
`s3` S3Object

ClaudeHarness

ClaudeHarness selects the Claude runtime adapter.

Appears in:

HarnessSpec

CodexHarness

CodexHarness selects the Codex runtime adapter.

Appears in:

HarnessSpec

FoundryAPIFormat

Underlying type: string

FoundryAPIFormat selects the Foundry API format for a Foundry ModelConfig.

Appears in:

FoundryConfig

Field	Description
`OpenAI`
`Anthropic`

FoundryConfig

FoundryConfig contains Azure AI Foundry-specific configuration options.

Authentication is implicit and mirrors the other cloud providers: if spec.apiKeySecret is set the API key is used; if it is absent, the Foundry runtime falls back to DefaultAzureCredential (which resolves to Azure Workload Identity in-cluster, or the az CLI in local development). There is no auth-type selector.

Appears in:

ModelConfigSpec

Field	Description	Default	Validation
`endpoint` string	Endpoint is the Foundry or Azure AI Services account endpoint (e.g., https://my-account.cognitiveservices.azure.com/). Mutually exclusive with EndpointFrom.
`endpointFrom` ConfigMapKeySelector	EndpointFrom resolves the Foundry endpoint from a ConfigMap key, such as one written by Azure Service Operator. Mutually exclusive with Endpoint. The selector’s optional flag only controls how a missing key is handled: when set to true, the missing key is ignored while reading the ConfigMap, but a Foundry endpoint must always be supplied, so an unresolved endpointFrom still leaves the model unusable and the agent fails to start.
`deployment` string	Deployment is the Foundry model deployment name.
`apiVersion` string	APIVersion is the Foundry OpenAI-compatible data-plane API version. Ignored when APIFormat is Anthropic (the Messages surface is versioned via the anthropic-version header instead).	2024-10-21
`apiFormat` FoundryAPIFormat	APIFormat selects the Foundry API format: “OpenAI” (default, chat completions) or “Anthropic” (Claude models served over the Anthropic Messages API).	OpenAI	Enum: [OpenAI Anthropic]

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:

AllowedNamespaces

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:

TokenExchangeConfig

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

GeminiConfig

GeminiConfig contains Gemini (AI Studio, API-key) specific configuration options

Appears in:

ModelConfigSpec

Field	Description	Default	Validation
`maxOutputTokens` integer	Maximum output tokens to generate for a single response		Minimum: 1

GeminiVertexAIConfig

GeminiVertexAIConfig contains Gemini Vertex AI-specific configuration options

Appears in:

ModelConfigSpec

Field	Description	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	Minimum: 1
`candidateCount` integer	Candidate count
`responseMimeType` string	Response mime type

GitArtifact

GitArtifact identifies immutable content at a full Git commit ID.

Appears in:

ArtifactSource

Field	Description	Default	Validation
`url` string			MinLength: 1 Pattern: `^https?://[^[:space:]]+$`
`commit` string			Pattern: `^([0-9a-fA-F]\{40\}\|[0-9a-fA-F]\{64\})$`

Harness

Harness defines a reusable agent runtime and infrastructure policy.

Field	Description	Default	Validation
`apiVersion` string	`kagent.dev/v1alpha3`
`kind` string	`Harness`
`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` HarnessSpec
`status` HarnessStatus

HarnessAgentTemplateAdmission

HarnessAgentTemplateAdmission selects AgentTemplates that this Harness admits. An omitted admission accepts no AgentTemplates.

Appears in:

HarnessSpec

Field	Description	Default	Validation
`selector` LabelSelector	Selector selects admitted AgentTemplates in the Harness namespace.

HarnessCapabilities

HarnessCapabilities records behavior proven for a pinned adapter and runtime. It is populated by the controller and is not user-authored configuration.

Appears in:

HarnessStatus

Field	Description	Validation
`version` string	Version identifies the controller capability catalog entry.	MinLength: 1
`nativeAgentTools` boolean
`maxNativeAgentDepth` integer		Minimum: 0
`dedicatedAgentTools` boolean
`mcpInjection` boolean
`streaming` boolean
`interruption` boolean
`inputRequired` boolean
`approvals` boolean
`inputModalities` string array		MaxItems: 16
`outputModalities` string array		MaxItems: 16
`resume` boolean
`checkpoint` boolean

HarnessEnvVar

HarnessEnvVar configures one runtime environment variable.

Appears in:

HarnessSpec

Field	Description	Validation
`name` string		MinLength: 1
`value` string	Value is a literal value, including an empty string.
`credentialRef` SecretKeySelector	CredentialRef references a key in a same-namespace Secret.

HarnessSnapshotPolicy

HarnessSnapshotPolicy configures storage for Substrate snapshots.

Appears in:

HarnessSubstratePolicy

Field	Description	Default	Validation
`location` string	Location is the snapshot storage location used by Substrate.		Pattern: `^[^[:space:]]+$`

HarnessSpec

HarnessSpec defines a reusable runtime and its infrastructure policy.

Appears in:

Harness

Field	Description	Validation
`kagent` KagentHarness
`codex` CodexHarness
`claude` ClaudeHarness
`byo` BYOHarness
`workload` HarnessWorkload
`env` HarnessEnvVar array		MaxItems: 100
`substrate` HarnessSubstratePolicy
`allowedAgentTemplates` HarnessAgentTemplateAdmission	AllowedAgentTemplates selects AgentTemplates this Harness admits. When omitted, the Harness admits none.

HarnessStatus

HarnessStatus reports controller-derived capabilities and current health.

Appears in:

Harness

Field	Description	Validation
`observedGeneration` integer	ObservedGeneration is the latest Harness generation observed by the controller.
`capabilities` HarnessCapabilities	Capabilities is the single capability record for the selected runtime.
`conditions` Condition array	Conditions report adapter and dependency health.	MaxItems: 8

HarnessSubstratePolicy

HarnessSubstratePolicy contains the Substrate policy shared by all runtime variants.

Appears in:

HarnessSpec

Field	Description	Default	Validation
`workerPoolRef` LocalObjectReference	WorkerPoolRef references a WorkerPool in the Harness namespace.
`snapshotPolicy` HarnessSnapshotPolicy	SnapshotPolicy configures runtime snapshot storage.

HarnessWorkload

HarnessWorkload identifies the immutable runtime image used by a Harness.

Appears in:

HarnessSpec

Field	Description	Validation
`image` string	Image is an OCI image reference pinned by sha256 digest.	Pattern: `^[^[:space:]@]+@sha256:[a-f0-9]\{64\}$`
`command` string array	Command overrides the image entrypoint when set.	MaxItems: 32
`args` string array	Args overrides the image command arguments when set.	MaxItems: 64

KagentHarness

KagentHarness configures the kagent runtime adapter.

Appears in:

HarnessSpec

Field	Description	Default	Validation
`memory` KagentHarnessMemory	Memory enables long-term memory for agents using this Harness.

KagentHarnessMemory

KagentHarnessMemory configures kagent’s long-term memory service.

Appears in:

KagentHarness

Field	Description	Default	Validation
`modelConfigRef` LocalObjectReference	ModelConfigRef references the embedding ModelConfig in the Harness namespace.
`ttlDays` integer	TTLDays controls how many days a stored memory entry remains valid.		Minimum: 1

MCPTool

Appears in:

RemoteMCPServerStatus

Field	Description	Default	Validation
`name` string
`description` string

MCPToolBinding

MCPToolBinding binds tools from a same-namespace MCP server.

Appears in:

ToolBinding

Field	Description	Validation
`server` TypedLocalObjectReference
`tools` string array	Tools optionally limits which server tools are exposed. An omitted or empty list exposes every tool. Harnesses that cannot enforce a partial selection may expose the whole server and report a warning.	MaxItems: 50
`requireApproval` boolean	RequireApproval pauses before each invocation of a tool exposed by this binding. It applies to the selected tools, or to every server tool when Tools is omitted or empty.

ModelConfig

ModelConfig is the Schema for the modelconfigs API.

Field	Description	Default	Validation
`apiVersion` string	`kagent.dev/v1alpha3`
`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:

ModelConfig

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 Foundry]
`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
`foundry` FoundryConfig	Azure AI Foundry-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:

ModelConfig

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

Appears in:

ModelConfigSpec
ModelProviderConfigSpec

Field	Description
`Anthropic`
`AzureOpenAI`
`OpenAI`
`Ollama`
`Gemini`
`GeminiVertexAI`
`AnthropicVertexAI`
`Bedrock`
`SAPAICore`
`Foundry`

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/v1alpha3`
`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:

ModelProviderConfig

Field	Description	Validation
`type` ModelProvider	Type is the model provider type (OpenAI, Anthropic, etc.)	Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore Foundry]
`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:

ModelProviderConfig

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

OllamaConfig

OllamaConfig contains Ollama-specific configuration options

Appears in:

ModelConfigSpec

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

OpenAIAPIFormat

Underlying type: string

OpenAIAPIFormat selects the OpenAI HTTP API shape used by the ADK runtime.

Validation:

Enum: [chatCompletions responses]

Appears in:

OpenAIConfig

Field	Description
`chatCompletions`
`responses`

OpenAIConfig

OpenAIConfig contains OpenAI-specific configuration options

Appears in:

ModelConfigSpec

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. Sent as the OpenAI `max_tokens` request parameter, which is deprecated and rejected by reasoning models (GPT-5 / o-series). For those models set maxCompletionTokens instead. Mutually exclusive with maxCompletionTokens.		Minimum: 1
`maxCompletionTokens` integer	Maximum completion tokens to generate. Sent as the OpenAI `max_completion_tokens` request parameter (an upper bound on visible output plus reasoning tokens). This is the parameter reasoning models (GPT-5 / o-series) require in place of the deprecated maxTokens. Mutually exclusive with maxTokens.		Minimum: 1
`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: [none minimal low medium high xhigh]
`apiFormat` OpenAIAPIFormat	APIFormat selects which OpenAI HTTP API the runtime uses for this model. chatCompletions (default) posts to /v1/chat/completions. responses posts to /v1/responses. Use responses for OpenAI-compatible gateways or models that require the Responses API.	chatCompletions	Enum: [chatCompletions responses]
`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. Supported values vary by model. Set to “none” to disable reasoning; some models (e.g. gpt-5.6-terra) require this to use function tools via the Chat Completions API.

Validation:

Enum: [none minimal low medium high xhigh]

Appears in:

OpenAIConfig

PluginBundle

PluginBundle selects Agent Skills from one immutable Agent Plugins package.

Appears in:

AgentTemplateSpec

Field	Description	Default	Validation
`source` ArtifactSource
`skills` string array	An empty selection enables nothing.		MaxItems: 50

RemoteMCPServer

RemoteMCPServer is the Schema for the RemoteMCPServers API.

Field	Description	Default	Validation
`apiVersion` string	`kagent.dev/v1alpha3`
`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:

RemoteMCPServerSpec

Field	Description
`SSE`
`STREAMABLE_HTTP`

RemoteMCPServerSpec

RemoteMCPServerSpec defines the desired state of RemoteMCPServer.

Appears in:

RemoteMCPServer

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:

RemoteMCPServer

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.

S3Object

S3Object identifies one immutable S3 object version.

Appears in:

BucketArtifact

Field	Description	Validation
`endpoint` string	Endpoint is the HTTP(S) endpoint of an AWS or S3-compatible service.	Pattern: `^https?://[^[:space:]]+$`
`bucket` string		MinLength: 1
`key` string		MinLength: 1
`versionId` string		MinLength: 1
`region` string	Region is used for request signing when required by the service.

SAPAICoreConfig

SAPAICoreConfig contains SAP AI Core-specific configuration options.

Appears in:

ModelConfigSpec

Field	Description	Default
`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)

SecretReference

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

Appears in:

ModelProviderConfigSpec

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

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:

ModelConfigSpec
RemoteMCPServerSpec

Field	Description	Default
`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:

OpenAIConfig

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:

TokenExchangeConfig

Field	Description
`GDCHServiceAccount`

ToolBinding

ToolBinding selects exactly one MCP or AgentTemplate-backed tool source.

Appears in:

AgentTemplateSpec

Field	Description	Default	Validation
`mcp` MCPToolBinding
`agent` AgentToolBinding

ValueRef

ValueRef represents a configuration value

Appears in:

RemoteMCPServerSpec

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:

ValueRef

Field	Description	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:

ValueSource

Field	Description
`ConfigMap`
`Secret`

Helm reference