> For the complete documentation index, see [llms.txt](/docs/llms.txt). Markdown versions of all docs pages are available by appending .md to any docs URL.

# API reference

## Packages

- [api.kagent.dev/v1alpha3](#apikagentdevv1alpha3)

## api.kagent.dev/v1alpha3

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

### Resource Types

- [Agent](#agent)
- [AgentTemplate](#agenttemplate)
- [EgressPolicy](#egresspolicy)
- [Harness](#harness)
- [ModelConfig](#modelconfig)
- [ModelProviderConfig](#modelproviderconfig)
- [RemoteMCPServer](#remotemcpserver)
- [SandboxTemplate](#sandboxtemplate)

#### Agent

Agent is a runnable definition with an explicit template and harness.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.kagent.dev/v1alpha3` |  |  |
| `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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*AgentSpec*](#agentspec) |  |  | **Required** |
| `status` [*AgentStatus*](#agentstatus) |  |  |  |

#### AgentSpec

AgentSpec pairs portable behavior with a platform-managed runtime. References are local to the Agent's namespace, including references nested in inline template specs.

*Appears in:*

- [Agent](#agent)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `template` [*AgentTemplateSource*](#agenttemplatesource) | Template selects the portable behavior this Agent exposes. |  | ExactlyOneOf: \[inline ref] **Required** |
| `harnessRef` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | HarnessRef selects the platform-managed runtime configuration that executes the behavior. |  | **Required** |
| `egressPolicyRefs` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array* | EgressPolicyRefs grants additional access to the whole runtime, including shared subagents. Policies resolve in this Agent's namespace. Integration access inferred from models and tools is always included. Changes update existing Sessions without a new invocation or runtime restart. |  | MaxItems: 16 |

#### AgentStatus

AgentStatus reports compilation and preparation of an Agent.

*Appears in:*

- [Agent](#agent)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `observedGeneration` *integer* |  |  |  |
| `desiredRevision` *string* |  |  | MinLength: 1 |
| `latestSuccessfulRevision` *string* |  |  | MinLength: 1 |
| `workloadImage` *string* | WorkloadImage is the digest-pinned image selected for the desired revision. Existing Sessions may still use an older revision and image. |  | Pattern: `^[^[:space:]@]+@sha256:[a-f0-9]\{64\}$` |
| `warnings` *string array* | Warnings reports non-blocking compatibility decisions made while compiling this Agent. |  | MaxItems: 100 |
| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array* | Conditions report runtime readiness and independent egress grant admission. EgressPoliciesApplied is False for EgressPolicyNotFound, InvalidEgressPolicy, or EgressGrantConflict; Applied means all grants are admitted. Grant issues do not affect Ready. |  | MaxItems: 5 |

#### AgentTemplate

AgentTemplate defines portable agent behavior.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*AgentTemplateSpec*](#agenttemplatespec) |  |  | AtMostOneOf: \[outputSchema outputSchemaFrom] **Required** |

#### AgentTemplatePromptSource

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

*Appears in:*

- [AgentTemplatePromptTemplateSpec](#agenttemplateprompttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MinLength: 1 **Required** |
| `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](#agenttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `dataSources` *[AgentTemplatePromptSource](#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](#agenttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MinLength: 1 **Required** |
| `source` [*ArtifactSource*](#artifactsource) |  |  | ExactlyOneOf: \[oci git bucket] **Required** |

#### AgentTemplateSource

AgentTemplateSource selects portable behavior inline or by local reference.

*Validation:*

- ExactlyOneOf: \[inline ref]

*Appears in:*

- [AgentSpec](#agentspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `inline` [*AgentTemplateSpec*](#agenttemplatespec) | Inline defines the Agent's portable behavior directly. It cannot be set together with Ref. |  | AtMostOneOf: \[outputSchema outputSchemaFrom] |
| `ref` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | Ref names an AgentTemplate in the Agent's namespace. It cannot be set together with Inline. |  |  |

#### AgentTemplateSpec

AgentTemplateSpec defines portable agent behavior.

*Validation:*

- AtMostOneOf: \[outputSchema outputSchemaFrom]

*Appears in:*

- [AgentTemplate](#agenttemplate)
- [AgentTemplateSource](#agenttemplatesource)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `modelConfig` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ModelConfig is required by managed harnesses and optional for BYO harnesses. |  |  |
| `description` *string* |  |  |  |
| `systemPrompt` *string* |  |  |  |
| `systemPromptFrom` [*ConfigMapKeyReference*](#configmapkeyreference) | SystemPromptFrom references prompt text in a same-namespace ConfigMap. |  |  |
| `outputSchema` [*JSON*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#json-v1-apiextensions-k8s-io) | OutputSchema constrains successful terminal output when this template is compiled as the root agent. |  | Type: object |
| `outputSchemaFrom` [*ConfigMapKeyReference*](#configmapkeyreference) | OutputSchemaFrom references a JSON Schema stored as JSON in a same-namespace ConfigMap key. |  |  |
| `promptTemplate` [*AgentTemplatePromptTemplateSpec*](#agenttemplateprompttemplatespec) |  |  |  |
| `tools` *[ToolBinding](#toolbinding) array* |  |  | ExactlyOneOf: \[mcp subAgent] MaxItems: 50 |
| `skills` *[AgentTemplateSkill](#agenttemplateskill) array* |  |  | MaxItems: 50 |
| `plugins` *[PluginBundle](#pluginbundle) array* |  |  | MaxItems: 20 |

#### 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](#remotemcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `from` [*FromNamespaces*](#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*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#labelselector-v1-meta) | 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](#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 |  |  |
| `promptCaching` *boolean* | PromptCaching enables Anthropic prompt caching by marking the reusable prefix of every Messages API request with `cache_control` breakpoints: the last tool definition, the last system prompt block and the last content block of the most recent conversation turn. Anthropic caches the prefix up to each breakpoint and bills a cache hit at a fraction of the normal input price on later requests within the TTL. Because the conversation breakpoint moves with every turn, each call of an agent loop reads the whole previous history from the cache and writes only the new turn. Recommended for tool-using agents that make many model calls per task with a stable system prompt and tool set -- without it the full history is billed as fresh input on every call. Cache writes are billed at a premium over normal input, so a prefix has to be read at least once to pay off, and each model has a minimum cacheable prefix (1024-4096 tokens depending on the model) below which the markers are silently ignored. See [https://platform.claude.com/docs/en/build-with-claude/prompt-caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the current list of supported models, minimum prefix sizes and pricing. | false |  |
| `cacheTTL` *string* | CacheTTL controls how long Anthropic retains a cached prefix when PromptCaching is enabled. Only meaningful when PromptCaching is true. \- "5m" (default): the standard 5-minute cache. Each cache hit refreshes the window, so an agent loop whose calls are less than 5 minutes apart keeps its prefix cached for the whole task. \- "1h": the extended 1-hour cache, useful for tasks whose model calls are spaced more than 5 minutes apart. NOTE: "1h" is NOT strictly better than "5m". 1-hour cache writes are billed at a higher per-token rate than 5-minute writes. 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 Anthropic prompt-caching docs above. | 5m | Enum: \[5m 1h] |

#### AnthropicVertexAIConfig

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `projectID` *string* | The project ID |  | **Required** |
| `location` *string* | The project location |  | **Required** |
| `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.

*Validation:*

- ExactlyOneOf: \[oci git bucket]

*Appears in:*

- [AgentTemplateSkill](#agenttemplateskill)
- [PluginBundle](#pluginbundle)

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

#### AzureOpenAIConfig

AzureOpenAIConfig contains Azure OpenAI-specific configuration options

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `azureEndpoint` *string* | Endpoint for the Azure OpenAI API |  | **Required** |
| `apiVersion` *string* | API version for the Azure OpenAI API. Required unless apiFormat is responses. |  |  |
| `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 |  | Minimum: 1 |
| `topP` *string* | Top-p sampling parameter |  |  |
| `apiFormat` [*OpenAIAPIFormat*](#openaiapiformat) | APIFormat selects chatCompletions (default, the dated deployments path) or responses (the /openai/v1 surface, which needs no apiVersion and reads files by link). | chatCompletions | Enum: \[chatCompletions responses] |

#### BYOHarness

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

*Appears in:*

- [HarnessSpec](#harnessspec)

#### BaseVertexAIConfig

*Appears in:*

- [AnthropicVertexAIConfig](#anthropicvertexaiconfig)
- [GeminiVertexAIConfig](#geminivertexaiconfig)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `projectID` *string* | The project ID |  | **Required** |
| `location` *string* | The project location |  | **Required** |
| `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](#modelconfigspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `region` *string* | AWS region where the Bedrock model is available (e.g., us-east-1, us-west-2) |  | **Required** |
| `additionalModelRequestFields` [*JSON*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#json-v1-apiextensions-k8s-io) | 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}} |  | Type: object |
| `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](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*](#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](#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 **Required** |
| `version` *string* | Version is the guardrail version: a numeric version (e.g. "1") or "DRAFT". |  | MaxLength: 8 MinLength: 1 **Required** |
| `trace` *string* |  | disabled | Enum: \[disabled enabled enabled\_full] |

#### BucketArtifact

BucketArtifact selects the supported object-store provider.

*Appears in:*

- [ArtifactSource](#artifactsource)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `s3` [*S3Object*](#s3object) |  |  | **Required** |

#### ClaudeHarness

ClaudeHarness selects the Claude runtime adapter.

*Appears in:*

- [HarnessSpec](#harnessspec)

#### CodexHarness

CodexHarness selects the Codex runtime adapter.

*Appears in:*

- [HarnessSpec](#harnessspec)

#### ConfigMapKeyReference

ConfigMapKeyReference identifies a key in a same-namespace ConfigMap.

*Appears in:*

- [AgentTemplateSpec](#agenttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MinLength: 1 **Required** |
| `key` *string* |  |  | MinLength: 1 **Required** |

#### EgressAuthentication

EgressAuthentication replaces a request header with a prefix and Secret value.

*Appears in:*

- [EgressDestination](#egressdestination)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `header` *string* | Header is the request header carrying the credential, for example Authorization or X-API-Key. |  | MaxLength: 256 Pattern: `^[!#$%&'*+.^_\|~0-9A-Za-z-]+$` **Required** |
| `prefix` *string* | Prefix is prepended verbatim to the Secret value, for example "Bearer ". Include any separating space. Omitted or empty means no prefix. |  | MaxLength: 256 Pattern: `^[^\x00-\x08\x0a-\x1f\x7f]*$` |
| `secretKeyRef` [*SecretKeySelector*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#secretkeyselector-v1-core) | SecretKeyRef selects a required key in the EgressPolicy's namespace. |  | **Required** |

#### EgressDestination

EgressDestination grants access to one HTTP(S) origin, including all its paths.

*Appears in:*

- [EgressPolicySpec](#egresspolicyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `origin` *string* | Origin is a scheme, DNS hostname, and optional port. A wildcard replaces exactly one leftmost DNS label, for example https://\*.example.com. |  | MaxLength: 270 Pattern: `^https?://(\*\.([a-z0-9]([-a-z0-9]\{0,61\}[a-z0-9])?\.)+\|([a-z0-9]([-a-z0-9]\{0,61\}[a-z0-9])?\.)*)[a-z]([-a-z0-9]\{0,61\}[a-z0-9])?(:([1-9][0-9]\{0,3\}\|[1-5][0-9]\{4\}\|6[0-4][0-9]\{3\}\|65[0-4][0-9]\{2\}\|655[0-2][0-9]\|6553[0-5]))?$` **Required** |
| `authentication` [*EgressAuthentication*](#egressauthentication) | Authentication replaces a placeholder header at the gateway. Requests must send the header; its credential value is never supplied to the runtime. |  |  |

#### EgressPolicy

EgressPolicy is a reusable grant of additional network access. Workloads in its namespace select it explicitly; changes update their existing runtime Actors.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.kagent.dev/v1alpha3` |  |  |
| `kind` *string* | `EgressPolicy` |  |  |
| `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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*EgressPolicySpec*](#egresspolicyspec) |  |  | **Required** |

#### EgressPolicySpec

EgressPolicySpec grants additional HTTP(S) access to workloads in its namespace.

*Appears in:*

- [EgressPolicy](#egresspolicy)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `destinations` *[EgressDestination](#egressdestination) array* | Destinations are additional origins the workload may reach. |  | MaxItems: 64 MinItems: 1 **Required** |

#### FoundryAPIFormat

*Underlying type:* *string*

FoundryAPIFormat selects the Foundry API format for a Foundry ModelConfig.

*Appears in:*

- [FoundryConfig](#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](#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/)](https://my-account.cognitiveservices.azure.com/%29). Mutually exclusive with EndpointFrom. |  |  |
| `endpointFrom` [*ConfigMapKeySelector*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#configmapkeyselector-v1-core) | 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. |  | **Required** |
| `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*](#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](https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment)

*Validation:*

- Enum: \[All Same Selector]

*Appears in:*

- [AllowedNamespaces](#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. |

#### GeminiConfig

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

*Appears in:*

- [ModelConfigSpec](#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](#modelconfigspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `projectID` *string* | The project ID |  | **Required** |
| `location` *string* | The project location |  | **Required** |
| `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](#artifactsource)

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

#### Harness

Harness defines a reusable agent runtime and infrastructure policy.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*HarnessSpec*](#harnessspec) |  |  | ExactlyOneOf: \[kagent codex claude byo] **Required** |
| `status` [*HarnessStatus*](#harnessstatus) |  |  |  |

#### 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](#harnessstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `version` *string* | Version identifies the controller capability catalog entry. |  | MinLength: 1 **Required** |
| `nativeAgentTools` *boolean* |  |  | **Required** |
| `maxNativeAgentDepth` *integer* |  |  | Minimum: 0 **Required** |
| `dedicatedAgentTools` *boolean* |  |  | **Required** |
| `mcpInjection` *boolean* |  |  | **Required** |
| `streaming` *boolean* |  |  | **Required** |
| `interruption` *boolean* |  |  | **Required** |
| `inputRequired` *boolean* |  |  | **Required** |
| `approvals` *boolean* |  |  | **Required** |
| `structuredOutput` *boolean* | StructuredOutput reports whether the pinned adapter can enforce a root JSON output contract and emit it as an A2A DataPart. |  | **Required** |
| `inputModalities` *string array* |  |  | MaxItems: 16 |
| `outputModalities` *string array* |  |  | MaxItems: 16 |
| `resume` *boolean* |  |  | **Required** |
| `checkpoint` *boolean* |  |  | **Required** |

#### HarnessSpec

HarnessSpec defines a reusable runtime and its infrastructure policy.

*Validation:*

- ExactlyOneOf: \[kagent codex claude byo]

*Appears in:*

- [Harness](#harness)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `kagent` [*KagentHarness*](#kagentharness) |  |  |  |
| `codex` [*CodexHarness*](#codexharness) |  |  |  |
| `claude` [*ClaudeHarness*](#claudeharness) |  |  |  |
| `byo` [*BYOHarness*](#byoharness) |  |  |  |
| `workload` [*HarnessWorkload*](#harnessworkload) | Workload overrides the built-in runtime image and its command. BYO requires it. |  |  |
| `env` *[RuntimeEnvVar](#runtimeenvvar) array* |  |  | MaxItems: 100 |
| `substrate` [*RuntimeSubstratePolicy*](#runtimesubstratepolicy) |  |  | **Required** |

#### HarnessStatus

HarnessStatus reports controller-derived capabilities and current health.

*Appears in:*

- [Harness](#harness)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `observedGeneration` *integer* | ObservedGeneration is the latest Harness generation observed by the controller. |  |  |
| `capabilities` [*HarnessCapabilities*](#harnesscapabilities) | Capabilities is the single capability record for the selected runtime. |  |  |
| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array* | Conditions report adapter and dependency health. |  | MaxItems: 8 |

#### HarnessWorkload

HarnessWorkload identifies the immutable runtime image used by a Harness.

*Appears in:*

- [HarnessSpec](#harnessspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `image` *string* | Image overrides the release's built-in runtime image. BYO requires an image. When set, it must be 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](#harnessspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `memory` [*KagentHarnessMemory*](#kagentharnessmemory) | Memory enables long-term memory for agents using this Harness. |  |  |
| `compaction` [*KagentHarnessCompaction*](#kagentharnesscompaction) | Compaction summarizes older session events so the prompt stays small as a conversation grows. Omitted leaves the history uncompacted. |  | AtLeastOneOf: \[compactionInterval tokenThreshold] |

#### KagentHarnessCompaction

KagentHarnessCompaction selects the compaction strategies and the model that writes the summaries. The sliding window (compactionInterval, overlapSize) summarizes each group of completed invocations; tail retention (tokenThreshold, eventRetentionSize) bounds the prompt by summarizing everything but the most recent events once the prompt grows past a token count. At least one strategy must be configured.

*Validation:*

- AtLeastOneOf: \[compactionInterval tokenThreshold]

*Appears in:*

- [KagentHarness](#kagentharness)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `compactionInterval` *integer* | CompactionInterval is the number of new user-initiated invocations that, once fully represented in the session, triggers a sliding-window compaction of those invocations. |  | Minimum: 1 |
| `overlapSize` *integer* | OverlapSize is the number of already-compacted invocations pulled back into the next sliding window so consecutive summaries overlap. |  | Minimum: 0 |
| `tokenThreshold` *integer* | TokenThreshold is the prompt token count at which tail-retention compaction summarizes the history before the next model call. |  | Minimum: 1 |
| `eventRetentionSize` *integer* | EventRetentionSize is the number of most recent events that tail retention keeps uncompacted. |  | Minimum: 1 |
| `summarizer` [*KagentHarnessSummarizer*](#kagentharnesssummarizer) | Summarizer selects the model and prompt that write the summaries. Omitted summarizes with the agent's own model and the runtime's default prompt. |  |  |

#### KagentHarnessMemory

KagentHarnessMemory configures kagent's long-term memory service.

*Appears in:*

- [KagentHarness](#kagentharness)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `modelConfigRef` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ModelConfigRef references the embedding ModelConfig in the Harness namespace. |  | **Required** |
| `ttlDays` *integer* | TTLDays controls how many days a stored memory entry remains valid. |  | Minimum: 1 |

#### KagentHarnessSummarizer

KagentHarnessSummarizer configures the model that summarizes compacted events.

*Appears in:*

- [KagentHarnessCompaction](#kagentharnesscompaction)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `modelConfigRef` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ModelConfigRef references the ModelConfig in the Harness namespace that writes the summaries. Omitted uses the agent's own model. |  |  |
| `promptTemplate` *string* | PromptTemplate replaces the runtime's default summarization prompt. It must contain {conversation\_history}, which the runtime replaces with the rendered events. |  | MinLength: 1 |

#### MCPTool

*Appears in:*

- [RemoteMCPServerStatus](#remotemcpserverstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | **Required** |
| `description` *string* |  |  | **Required** |

#### MCPToolBinding

MCPToolBinding binds tools from a same-namespace MCP server.

*Appears in:*

- [ToolBinding](#toolbinding)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `server` [*TypedLocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#typedlocalobjectreference-v1-core) |  |  | **Required** |
| `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 items:MinLength: 1 |
| `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. |  |  |

#### MistralConfig

MistralConfig contains Mistral-specific configuration options. Mistral exposes an OpenAI-compatible wire protocol; the runtime posts to {baseURL}/chat/completions with a Bearer token from MISTRAL\_API\_KEY.

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `baseUrl` *string* | Base URL for the Mistral API (overrides default [https://api.mistral.ai/v1](https://api.mistral.ai/v1)) |  |  |
| `temperature` *string* | Temperature for sampling |  |  |
| `topP` *string* | Top-p sampling parameter |  |  |
| `maxTokens` *integer* | Maximum tokens to generate |  | Minimum: 1 |
| `timeout` *integer* | Timeout in seconds for the underlying HTTP client |  | Minimum: 1 |

#### ModelConfig

ModelConfig is the Schema for the modelconfigs API.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*ModelConfigSpec*](#modelconfigspec) |  |  |  |
| `status` [*ModelConfigStatus*](#modelconfigstatus) |  |  |  |

#### ModelConfigSpec

ModelConfigSpec defines the desired state of ModelConfig.

*Appears in:*

- [ModelConfig](#modelconfig)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `model` *string* |  |  | **Required** |
| `stream` *boolean* | Stream controls LLM response streaming for the kagent harness. Set to false for model endpoints that do not support streaming. Defaults to true. | true |  |
| `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). |  |  |
| `tokenPassthrough` *boolean* | TokenPassthrough 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*](#modelprovider) | The provider of the model | OpenAI | Enum: \[Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore Foundry Mistral] |
| `openAI` [*OpenAIConfig*](#openaiconfig) | OpenAI-specific configuration |  | AtMostOneOf: \[maxTokens maxCompletionTokens] |
| `anthropic` [*AnthropicConfig*](#anthropicconfig) | Anthropic-specific configuration |  |  |
| `azureOpenAI` [*AzureOpenAIConfig*](#azureopenaiconfig) | Azure OpenAI-specific configuration |  |  |
| `ollama` [*OllamaConfig*](#ollamaconfig) | Ollama-specific configuration |  |  |
| `gemini` [*GeminiConfig*](#geminiconfig) | Gemini-specific configuration |  |  |
| `geminiVertexAI` [*GeminiVertexAIConfig*](#geminivertexaiconfig) | Gemini Vertex AI-specific configuration |  |  |
| `anthropicVertexAI` [*AnthropicVertexAIConfig*](#anthropicvertexaiconfig) | Anthropic-specific configuration |  |  |
| `bedrock` [*BedrockConfig*](#bedrockconfig) | AWS Bedrock-specific configuration |  |  |
| `sapAICore` [*SAPAICoreConfig*](#sapaicoreconfig) | SAP AI Core-specific configuration |  |  |
| `foundry` [*FoundryConfig*](#foundryconfig) | Azure AI Foundry-specific configuration |  |  |
| `mistral` [*MistralConfig*](#mistralconfig) | Mistral-specific configuration |  |  |
| `tls` [*TLSConfig*](#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](#modelconfig)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) 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 Mistral]

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)
- [ModelProviderConfigSpec](#modelproviderconfigspec)

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

#### 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* | `api.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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*ModelProviderConfigSpec*](#modelproviderconfigspec) |  |  |  |
| `status` [*ModelProviderConfigStatus*](#modelproviderconfigstatus) |  |  |  |

#### ModelProviderConfigSpec

ModelProviderConfigSpec defines the desired state of ModelProviderConfig.

*Appears in:*

- [ModelProviderConfig](#modelproviderconfig)

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

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `observedGeneration` *integer* | ObservedGeneration reflects the generation of the most recently observed ModelProviderConfig spec |  |  |
| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) 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*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | 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](#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:*

- [AzureOpenAIConfig](#azureopenaiconfig)
- [OpenAIConfig](#openaiconfig)

| Field | Description |
| --- | --- |
| `chatCompletions` |  |
| `responses` |  |

#### OpenAIConfig

OpenAIConfig contains OpenAI-specific configuration options

*Validation:*

- AtMostOneOf: \[maxTokens maxCompletionTokens]

*Appears in:*

- [ModelConfigSpec](#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 |  | Minimum: 1 |
| `timeout` *integer* | Timeout |  | Maximum: 9.223372036e+09 Minimum: 1 |
| `reasoningEffort` [*OpenAIReasoningEffort*](#openaireasoningeffort) | Reasoning effort |  | Enum: \[none minimal low medium high xhigh] |
| `apiFormat` [*OpenAIAPIFormat*](#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] |

#### 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](#openaiconfig)

#### PluginBundle

PluginBundle selects Agent Skills from one immutable Agent Plugins package.

*Appears in:*

- [AgentTemplateSpec](#agenttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `source` [*ArtifactSource*](#artifactsource) |  |  | ExactlyOneOf: \[oci git bucket] **Required** |
| `skills` *string array* | An empty selection enables nothing. |  | MaxItems: 50 items:MinLength: 1 |

#### RemoteMCPServer

RemoteMCPServer is the Schema for the RemoteMCPServers API.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*RemoteMCPServerSpec*](#remotemcpserverspec) |  |  |  |
| `status` [*RemoteMCPServerStatus*](#remotemcpserverstatus) |  |  |  |

#### RemoteMCPServerProtocol

*Underlying type:* *string*

*Validation:*

- Enum: \[SSE STREAMABLE\_HTTP]

*Appears in:*

- [RemoteMCPServerSpec](#remotemcpserverspec)

| Field | Description |
| --- | --- |
| `SSE` |  |
| `STREAMABLE_HTTP` |  |

#### RemoteMCPServerSpec

RemoteMCPServerSpec defines the desired state of RemoteMCPServer.

*Appears in:*

- [RemoteMCPServer](#remotemcpserver)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `description` *string* |  |  | **Required** |
| `protocol` [*RemoteMCPServerProtocol*](#remotemcpserverprotocol) |  | STREAMABLE\_HTTP | Enum: \[SSE STREAMABLE\_HTTP] |
| `url` *string* |  |  | MinLength: 1 **Required** |
| `headersFrom` *[ValueRef](#valueref) array* | HeadersFrom supplies request headers. Secret-backed headers are injected by the egress gateway and cannot use routing, framing, hop-by-hop, proxy-authentication, or Cookie headers. At most 64 headers may be supplied. |  | ExactlyOneOf: \[value valueFrom] MaxItems: 64 items:XValidation: {!has(self.valueFrom) \|\| self.valueFrom.type != 'Secret' \|\| !(self.name.lowerAscii() in \['host', 'connection', 'content-length', 'transfer-encoding', 'te', 'trailer', 'upgrade', 'keep-alive', 'proxy-authorization', 'proxy-authenticate', 'cookie']) this header cannot carry an egress credential .name <nil>} |
| `tokenPassthrough` *boolean* | TokenPassthrough forwards the bearer token from the incoming A2A request to this server as its Authorization header. Requests without a caller token fail. Controller tool discovery has no caller token, so servers that require one should disable discovery with the kagent.dev/discovery label. |  |  |
| `timeout` [*Duration*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#duration-v1-meta) |  | 30s |  |
| `sseReadTimeout` [*Duration*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#duration-v1-meta) |  |  |  |
| `terminateOnClose` *boolean* |  | true |  |
| `allowedNamespaces` [*AllowedNamespaces*](#allowednamespaces) | AllowedNamespaces defines which namespaces are allowed to reference this RemoteMCPServer. This follows the Gateway API pattern for cross-namespace route attachments. If not specified, only Agents in the same namespace can reference this RemoteMCPServer. See: [https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment](https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment) |  |  |
| `tls` [*TLSConfig*](#tlsconfig) | TLS configuration for the upstream MCP server connection. DisableVerify turns off certificate validation for development or testing. Custom CA bundles are not supported. TLS must be unset for HTTP URLs. |  |  |

#### RemoteMCPServerStatus

RemoteMCPServerStatus defines the observed state of RemoteMCPServer.

*Appears in:*

- [RemoteMCPServer](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array* |  |  |  |
| `discoveredTools` *[MCPTool](#mcptool) array* |  |  |  |

#### RuntimeEnvVar

RuntimeEnvVar configures one literal runtime environment variable.

*Appears in:*

- [HarnessSpec](#harnessspec)
- [SandboxTemplateSpec](#sandboxtemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MinLength: 1 **Required** |
| `value` *string* | Value is a literal value, including an empty string. |  | **Required** |

#### RuntimeSnapshotPolicy

RuntimeSnapshotPolicy configures storage for Substrate snapshots.

*Appears in:*

- [RuntimeSubstratePolicy](#runtimesubstratepolicy)

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

#### RuntimeSubstratePolicy

RuntimeSubstratePolicy contains the Substrate policy shared by all runtime variants.

*Appears in:*

- [HarnessSpec](#harnessspec)
- [SandboxTemplateSpec](#sandboxtemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `workerPoolRef` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | WorkerPoolRef references a WorkerPool in the resource's namespace. |  | **Required** |
| `snapshotPolicy` [*RuntimeSnapshotPolicy*](#runtimesnapshotpolicy) | SnapshotPolicy configures runtime snapshot storage. |  | **Required** |

#### S3Object

*Underlying type:* [*struct{Endpoint string "json:"endpoint""; Bucket string "json:"bucket""; Key string "json:"key""; VersionID string "json:"versionId""; Region string "json:"region,omitempty""}*](#struct%7bendpoint-string-%22json:%5c%22endpoint%5c%22%22;-bucket-string-%22json:%5c%22bucket%5c%22%22;-key-string-%22json:%5c%22key%5c%22%22;-versionid-string-%22json:%5c%22versionid%5c%22%22;-region-string-%22json:%5c%22region,omitempty%5c%22%22%7d)

S3Object identifies one immutable S3 object version.

*Appears in:*

- [BucketArtifact](#bucketartifact)

#### SAPAICoreConfig

SAPAICoreConfig contains SAP AI Core-specific configuration options.

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)

| 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](https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com)) |  | **Required** |
| `resourceGroup` *string* | Resource group in SAP AI Core | default |  |
| `authUrl` *string* | OAuth2 token endpoint URL (e.g., [https://tenant.authentication.eu10.hana.ondemand.com](https://tenant.authentication.eu10.hana.ondemand.com)) |  |  |

#### SandboxTemplate

SandboxTemplate defines standalone sandbox configuration. Creating one does not allocate a user sandbox. The controller prepares its reusable runtime.

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` *string* | `api.kagent.dev/v1alpha3` |  |  |
| `kind` *string* | `SandboxTemplate` |  |  |
| `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](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](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |  |  |
| `metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. |  |  |
| `spec` [*SandboxTemplateSpec*](#sandboxtemplatespec) |  |  | **Required** |
| `status` [*SandboxTemplateStatus*](#sandboxtemplatestatus) |  |  |  |

#### SandboxTemplateSpec

SandboxTemplateSpec defines standalone sandbox environment configuration.

*Appears in:*

- [SandboxTemplate](#sandboxtemplate)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `workload` [*SandboxTemplateWorkload*](#sandboxtemplateworkload) | Workload selects the immutable runtime image. |  | **Required** |
| `env` *[RuntimeEnvVar](#runtimeenvvar) array* | Env supplies runtime environment defaults. Credential references do not grant permission to read the referenced Secret. |  | MaxItems: 100 |
| `substrate` [*RuntimeSubstratePolicy*](#runtimesubstratepolicy) | Substrate configures compute placement and snapshot storage. References are resolved in this template's namespace. |  | **Required** |
| `egressPolicyRefs` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array* | EgressPolicyRefs grants additional access in this template's namespace. Changes update the access of existing sandboxes without restarting them. |  | MaxItems: 16 |

#### SandboxTemplateStatus

SandboxTemplateStatus reports preparation of the current template inputs.

*Appears in:*

- [SandboxTemplate](#sandboxtemplate)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `observedGeneration` *integer* | ObservedGeneration is the generation considered by preparation. |  |  |
| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array* | Conditions report runtime readiness and independent egress grant admission. EgressPoliciesApplied is False for EgressPolicyNotFound, InvalidEgressPolicy, or EgressGrantConflict; Applied means all grants are admitted. Grant issues do not affect Ready. |  |  |

#### SandboxTemplateWorkload

SandboxTemplateWorkload identifies available software without selecting an agent or guest entrypoint. The consumer owns startup.

*Appears in:*

- [SandboxTemplateSpec](#sandboxtemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `image` *string* | Image is an OCI image reference pinned by sha256 digest. |  | Pattern: `^[^[:space:]@]+@sha256:[a-f0-9]\{64\}$` **Required** |

#### SecretReference

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

*Appears in:*

- [ModelProviderConfigSpec](#modelproviderconfigspec)

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

#### SubAgentToolBinding

SubAgentToolBinding exposes a same-namespace AgentTemplate as a logical tool.

*Appears in:*

- [ToolBinding](#toolbinding)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MinLength: 1 **Required** |
| `description` *string* | Description tells the parent when to route work to this binding. |  | MinLength: 1 **Required** |
| `templateRef` [*LocalObjectReference*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | TemplateRef selects a Shared subagent compiled into the parent's runtime using its Harness. |  | **Required** |

#### TLSConfig

TLSConfig contains TLS/SSL configuration options for outbound HTTPS connections from the agent (model provider, RemoteMCPServer).

*Appears in:*

- [ModelConfigSpec](#modelconfigspec)
- [RemoteMCPServerSpec](#remotemcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `disableVerify` *boolean* | DisableVerify disables SSL certificate verification entirely. When false (default), SSL certificates are verified. When true, SSL certificate verification is disabled. WARNING: This should ONLY be used in development/testing environments. Production deployments MUST use proper certificates. | false |  |

#### ToolBinding

ToolBinding selects exactly one MCP or subagent tool source.

*Validation:*

- ExactlyOneOf: \[mcp subAgent]

*Appears in:*

- [AgentTemplateSpec](#agenttemplatespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mcp` [*MCPToolBinding*](#mcptoolbinding) |  |  |  |
| `subAgent` [*SubAgentToolBinding*](#subagenttoolbinding) |  |  |  |

#### ValueRef

ValueRef represents a configuration value

*Validation:*

- ExactlyOneOf: \[value valueFrom]

*Appears in:*

- [RemoteMCPServerSpec](#remotemcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` *string* |  |  | MaxLength: 256 **Required** |
| `value` *string* |  |  |  |
| `valueFrom` [*ValueSource*](#valuesource) |  |  |  |

#### ValueSource

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

*Appears in:*

- [ValueRef](#valueref)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `type` [*ValueSourceType*](#valuesourcetype) |  |  | Enum: \[ConfigMap Secret] **Required** |
| `name` *string* | The name of the ConfigMap or Secret. |  | MaxLength: 253 **Required** |
| `key` *string* | The key of the ConfigMap or Secret. |  | MaxLength: 253 **Required** |

#### ValueSourceType

*Underlying type:* *string*

*Appears in:*

- [ValueSource](#valuesource)

| Field | Description |
| --- | --- |
| `ConfigMap` |  |
| `Secret` |  |