For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
API Reference
kagent API reference documentation
Packages
kagent.dev/v1alpha2
Package v1alpha2 contains API Schema definitions for the kagent.dev v1alpha2 API group.
Resource Types
A2AConfig
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
skills AgentSkill array | MinItems: 1 |
Agent
Agent is the Schema for the agents API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | Agent | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec AgentSpec | |||
status AgentStatus |
AgentHarness
AgentHarness is a generic remote execution environment provisioned by a backend (OpenClaw or Hermes) running on Agent Substrate.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | AgentHarness | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec AgentHarnessSpec | |||
status AgentHarnessStatus |
AgentHarnessBackendType
Underlying type: string
AgentHarnessBackendType selects which sandbox control plane provisions the environment. Additional backends may be added in the future.
Validation:
- Enum: [openclaw hermes]
Appears in:
| Field | Description |
|---|---|
openclaw | |
hermes |
AgentHarnessChannel
AgentHarnessChannel declares one messenger binding inside a harness VM.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name is a stable id for this binding (OpenClaw channels.*.accounts key). | MinLength: 1 | |
type AgentHarnessChannelType | Enum: [telegram slack] | ||
telegram AgentHarnessTelegramChannelSpec | |||
slack AgentHarnessSlackChannelSpec | Slack configures Slack when type is Slack. |
AgentHarnessChannelAccess
Underlying type: string
AgentHarnessChannelAccess controls whether the bot listens broadly or only on an allowlist.
Validation:
- Enum: [allowlist open disabled]
Appears in:
| Field | Description |
|---|---|
allowlist | |
open | |
disabled |
AgentHarnessChannelCredential
AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
value string | MaxLength: 8192 | ||
valueFrom ValueSource |
AgentHarnessChannelType
Underlying type: string
AgentHarnessChannelType selects a messenger integration for OpenClaw harness VMs.
Validation:
- Enum: [telegram slack]
Appears in:
| Field | Description |
|---|---|
telegram | |
slack |
AgentHarnessConnection
AgentHarnessConnection describes how clients reach the provisioned harness VM.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
endpoint string | Endpoint is the backend-specific address (gRPC target, SSH host:port, …) clients should use to reach the harness. |
AgentHarnessHermesSlackOptions
AgentHarnessHermesSlackOptions configures Hermes-specific Slack settings (env vars in the sandbox).
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
allowedUserIDs string array | AllowedUserIDs restricts which Slack member IDs may interact with the bot (SLACK_ALLOWED_USERS). | MaxItems: 1024 | |
allowedUserIDsFrom ValueSource | |||
homeChannel string | HomeChannel is the default Slack channel ID for cron/scheduled messages (SLACK_HOME_CHANNEL). | ||
homeChannelName string | HomeChannelName is a human-readable label for HomeChannel (SLACK_HOME_CHANNEL_NAME). |
AgentHarnessOpenClawSlackOptions
AgentHarnessOpenClawSlackOptions configures OpenClaw-specific Slack routing.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
channelAccess AgentHarnessChannelAccess | Enum: [allowlist open disabled] | ||
allowlistChannels string array | AllowlistChannels is required when channelAccess is allowlist. | MaxItems: 1024 | |
interactiveReplies boolean | true |
AgentHarnessSlackChannelSpec
AgentHarnessSlackChannelSpec configures Slack when AgentHarnessChannel.type is Slack. Backend-specific settings live under the matching backend key; AgentHarnessSpec validation requires the key to match spec.backend.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
botToken AgentHarnessChannelCredential | |||
appToken AgentHarnessChannelCredential | |||
openclaw AgentHarnessOpenClawSlackOptions | OpenClaw configures OpenClaw-specific Slack routing. | ||
hermes AgentHarnessHermesSlackOptions | Hermes configures Hermes-specific Slack settings. |
AgentHarnessSpec
AgentHarnessSpec describes a generic remote execution environment that agents (or human operators) can attach to via exec or SSH.
An AgentHarness is distinct from a SandboxAgent: it has no agent runtime baked in. The backend is responsible for provisioning an environment that stays ready to accept incoming commands.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
backend AgentHarnessBackendType | Backend selects the control plane to use. Required. | Enum: [openclaw hermes] | |
substrate AgentHarnessSubstrateSpec | Substrate configures the Agent Substrate provisioning stack. Required. | ||
description string | Description is a short human-readable summary shown in the UI (e.g. agents list). | ||
image string | Image is the container image to run in the harness VM, if the backend supports per-resource images. Backend openclaw pins the image to the OpenClaw sandbox base when this field is empty; backend hermes pins to the Hermes sandbox base image when empty. | ||
env EnvVar array | Env is a list of environment variables injected into the harness workload. Values use the Kubernetes EnvVar shape; ValueFrom references are resolved server-side where supported. | ||
modelConfigRef string | ModelConfigRef is the reference to the ModelConfig used to configure the harness. The controller registers the gateway provider and, after the harness is Ready, writes OpenClaw config inside the VM (~/.openclaw/openclaw.json) and starts the gateway. | ||
channels AgentHarnessChannel array | Channels configures Telegram and Slack integrations for OpenClaw inside the harness VM. | MaxItems: 1024 |
AgentHarnessStatus
AgentHarnessStatus is the observed state of an AgentHarness.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer | |||
conditions Condition array | |||
backendRef AgentHarnessStatusRef | BackendRef points at the harness instance on the backend control plane, once Ensure has succeeded at least once. | ||
connection AgentHarnessConnection | Connection is populated by the controller when the harness is ready. |
AgentHarnessStatusRef
AgentHarnessStatusRef identifies a harness instance on an external control plane.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
backend AgentHarnessBackendType | Enum: [openclaw hermes] | ||
id string |
AgentHarnessSubstrateSnapshotsConfig
AgentHarnessSubstrateSnapshotsConfig points at a GCS prefix for actor memory snapshots. Substrate currently expects a gs:// location (see Agent Substrate SnapshotsConfig).
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
location string | Location is the GCS URI prefix for golden and incremental snapshots. Example: gs://ate-snapshots/kagent/my-namespace/my-harness/ | Pattern: ^gs:// |
AgentHarnessSubstrateSpec
AgentHarnessSubstrateSpec configures Agent Substrate (WorkerPool + ActorTemplate + Actor).
kagent generates a per-harness ActorTemplate and creates an Actor from it. WorkerPool capacity is referenced from workerPoolRef or the controller default; it is not created or deleted by the AgentHarness controller.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
workerPoolRef TypedLocalReference | WorkerPoolRef references an existing ate.dev WorkerPool in the harness namespace. When unset, the controller uses its configured default WorkerPool. | ||
snapshotsConfig AgentHarnessSubstrateSnapshotsConfig | SnapshotsConfig configures actor memory snapshots. Defaults to gs://ate-snapshots/<namespace>/<agentharnessname> when unset. | ||
workloadImage string | WorkloadImage overrides the default openclaw sandbox image in the ActorTemplate. |
AgentHarnessTelegramChannelSpec
AgentHarnessTelegramChannelSpec configures Telegram when AgentHarnessChannel.type is Telegram.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
botToken AgentHarnessChannelCredential | |||
allowedUserIDs string array | MaxItems: 1024 | ||
allowedUserIDsFrom ValueSource |
AgentProvider
AgentProvider identifies the organization responsible for an agent on its A2A AgentCard.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
organization string | Organization is the name of the agent provider’s organization. | MinLength: 1 | |
url string | URL is a URL for the agent provider’s website or relevant documentation. | Format: uri |
AgentSkill
AgentSkill describes a specific capability or function of the agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
id string | ID is the unique identifier for the skill. | ||
name string | Name is the human-readable name of the skill. | MinLength: 1 | |
description string | Description is an optional detailed description of the skill. | ||
tags string array | Tags are optional tags for categorization. | MaxItems: 20 | |
examples string array | Examples are optional usage examples. | MaxItems: 20 | |
inputModes string array | InputModes are the supported input MIME types for this skill, overriding the agent’s defaults. | ||
outputModes string array | OutputModes are the supported output MIME types for this skill, overriding the agent’s defaults. |
AgentSpec
AgentSpec defines the desired state of Agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type AgentType | Declarative | Enum: [Declarative BYO] | |
byo BYOAgentSpec | BYO configures a “bring your own” agent backed by a user-provided container image. Kagent deploys the image and expects it to serve the agent over the A2A protocol on port 8080. Required if type is BYO. | ||
declarative DeclarativeAgentSpec | Declarative configures an agent that is fully described by this resource (model, instructions, tools) and runs on one of kagent’s built-in runtimes. Required if type is Declarative. | ||
description string | |||
iconUrl string | IconURL is a URL to an icon representing the agent. It is surfaced on the agent’s A2A AgentCard. | Format: uri | |
documentationUrl string | DocumentationURL is a URL to human-readable documentation for the agent. It is surfaced on the agent’s A2A AgentCard. | Format: uri | |
version string | Version is the agent’s version string, surfaced on the A2A AgentCard. | ||
provider AgentProvider | Provider identifies the organization responsible for the agent. It is surfaced on the agent’s A2A AgentCard. | ||
skills SkillForAgent | Skills to load into the agent. They will be pulled from OCI images, git repos, and/or S3, and made available to the agent under the /skills folder. | ||
sandbox SandboxConfig | Sandbox configures sandboxed execution behavior shared across runtimes. This is intended for sandboxed declarative execution today, and can also be consumed by BYO agents. | ||
allowedNamespaces AllowedNamespaces | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool. This follows the Gateway API pattern for cross-namespace route attachments. If not specified, only Agents in the same namespace can reference this Agent as a tool. This field only applies when this Agent is used as a tool by another Agent. See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment |
AgentStatus
AgentStatus defines the observed state of Agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer | |||
conditions Condition array |
AgentType
Underlying type: string
AgentType represents the agent type
Validation:
- Enum: [Declarative BYO]
Appears in:
| Field | Description |
|---|---|
Declarative | |
BYO |
AllowedNamespaces
AllowedNamespaces defines which namespaces are allowed to reference this resource. This mechanism provides a bidirectional handshake for cross-namespace references, following the pattern used by Gateway API for cross-namespace route attachments.
By default (when not specified), only references from the same namespace are allowed.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
from FromNamespaces | From indicates where references to this resource can originate. Possible values are: * All: References from all namespaces are allowed. * Same: Only references from the same namespace are allowed (default). * Selector: References from namespaces matching the selector are allowed. | Same | Enum: [All Same Selector] |
selector LabelSelector | Selector is a label selector for namespaces that are allowed to reference this resource. Only used when From is set to “Selector”. |
AnthropicConfig
AnthropicConfig contains Anthropic-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
baseUrl string | Base URL for the Anthropic API (overrides default) | ||
maxTokens integer | Maximum tokens to generate | ||
temperature string | Temperature for sampling | ||
topP string | Top-p sampling parameter | ||
topK integer | Top-k sampling parameter |
AnthropicVertexAIConfig
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences | ||
maxTokens integer | Maximum tokens to generate |
AzureOpenAIConfig
AzureOpenAIConfig contains Azure OpenAI-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
azureEndpoint string | Endpoint for the Azure OpenAI API | ||
apiVersion string | API version for the Azure OpenAI API | ||
azureDeployment string | Deployment name for the Azure OpenAI API | ||
azureAdToken string | Azure AD token for authentication | ||
temperature string | Temperature for sampling | ||
maxTokens integer | Maximum tokens to generate | ||
topP string | Top-p sampling parameter |
BYOAgentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
deployment ByoDeploymentSpec | Deployment configures the Kubernetes Deployment created for the BYO agent container. |
BaseVertexAIConfig
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences |
BedrockConfig
BedrockConfig contains AWS Bedrock-specific configuration options.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
region string | AWS region where the Bedrock model is available (e.g., us-east-1, us-west-2) | ||
additionalModelRequestFields JSON | AdditionalModelRequestFields passes model-specific parameters to Bedrock’s additionalModelRequestFields in the Converse API. Use this for provider-specific options that are not part of the standard InferenceConfiguration block, such as Claude extended thinking or top_k. Values are forwarded as-is to the API. Example: {“top_k”: 5, “thinking”: {“type”: “enabled”, “budget_tokens”: 16000}} | ||
promptCaching boolean | PromptCaching enables Bedrock prompt caching by appending a CachePoint block at the end of the Converse request’s system content array andthe end of the toolConfig.tools array. Bedrock will cache the prefix up to andincluding 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:
| 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] |
ByoDeploymentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
image string | Image is the container image of the BYO agent. The image is expected to serve the agent over the A2A protocol on port 8080. | MinLength: 1 | |
cmd string | Cmd overrides the container entrypoint (the container’s command). | ||
args string array | Args are the arguments passed to the container entrypoint. | ||
workingDir string | workingDir sets the container working directory. Defaults to the image WORKDIR when omitted. | ||
replicas integer | Replicas is the number of desired agent pods. Defaults to 1. | ||
imagePullSecrets LocalObjectReference array | ImagePullSecrets are references to secrets in the agent’s namespace used for pulling the agent container image. | ||
volumes Volume array | Volumes are additional volumes added to the agent pod. | ||
volumeMounts VolumeMount array | VolumeMounts are additional volume mounts added to the agent container. | ||
labels object (keys:string, values:string) | Labels are additional labels added to the agent pods. | ||
annotations object (keys:string, values:string) | Annotations are additional annotations added to the agent pods. | ||
deploymentAnnotations object (keys:string, values:string) | DeploymentAnnotations are additional annotations added to the agent Deployment object itself. Unlike Annotations, which apply to the agent pods, these apply to the Deployment metadata. Keys set here take precedence over annotations inherited from the agent resource metadata. This has no effect when the agent runs with the Sandbox workload mode, as no Deployment is created in that mode. | ||
env EnvVar array | Env are additional environment variables set on the agent container. | ||
envFrom EnvFromSource array | EnvFrom are sources (ConfigMaps/Secrets) used to populate environment variables on the agent container. Values defined in Env with a duplicate key take precedence. | ||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | Tolerations applied to the agent pods. | ||
affinity Affinity | |||
topologySpreadConstraints TopologySpreadConstraint array | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. All topologySpreadConstraints are ANDed. | ||
nodeSelector object (keys:string, values:string) | NodeSelector restricts the nodes the agent pods can be scheduled on. | ||
securityContext SecurityContext | |||
podSecurityContext PodSecurityContext | |||
serviceAccountName string | ServiceAccountName specifies the name of an existing ServiceAccount to use. If this field is set, the Agent controller will not create a ServiceAccount for the agent. This field is mutually exclusive with ServiceAccountConfig. | ||
serviceAccountConfig ServiceAccountConfig | ServiceAccountConfig configures the ServiceAccount created by the Agent controller. This field can only be used when ServiceAccountName is not set. If ServiceAccountName is not set, a default ServiceAccount (named after the agent) is created, and this config will be applied to it. | ||
extraContainers Container array | ExtraContainers is a list of additional containers to run alongside the main agent container. Useful for sidecars such as token proxies, log shippers, or security agents. |
ContextCompressionConfig
ContextCompressionConfig configures event history compaction/compression.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
compactionInterval integer | The number of new user-initiated invocations that, once fully represented in the session’s events, will trigger a compaction. | 5 | Minimum: 1 |
overlapSize integer | The number of preceding invocations to include from the end of the last compacted range. This creates an overlap between consecutive compacted summaries, maintaining context. | 2 | Minimum: 0 |
summarizer ContextSummarizerConfig | Summarizer configures an LLM-based summarizer for event compaction. If not specified, compacted events are dropped from the context without summarization. | ||
tokenThreshold integer | Post-invocation token threshold trigger. If set, ADK will attempt a post-invocation compaction when the most recently observed prompt token count meets or exceeds this threshold. | ||
eventRetentionSize integer | EventRetentionSize is the number of most recent events to always retain. |
ContextConfig
ContextConfig configures context management for an agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
compaction ContextCompressionConfig | Compaction configures event history compaction. When enabled, older events in the conversation are compacted (compressed/summarized) to reduce context size while preserving key information. |
ContextSummarizerConfig
ContextSummarizerConfig configures the LLM-based event summarizer.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
modelConfig string | ModelConfig is the name of a ModelConfig resource to use for summarization. Must be in the same namespace as the Agent. If not specified, uses the agent’s own model. | ||
promptTemplate string | PromptTemplate is a custom prompt template for the summarizer. See the ADK LlmEventSummarizer for template details: https://github.com/google/adk-python/blob/main/src/google/adk/apps/llm_event_summarizer.py |
DeclarativeAgentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
runtime DeclarativeRuntime | Runtime specifies which ADK implementation to use for this agent. - “go”: Uses the Go ADK (default, faster startup, most features supported) - “python”: Uses the Python ADK (slower startup, full feature set) The runtime determines both the container image and readiness probe configuration. | go | Enum: [python go] |
systemMessage string | SystemMessage is a string specifying the system message for the agent. When PromptTemplate is set, this field is treated as a Go text/template with access to an include(“source/key”) function and agent context variables such as .AgentName, .AgentNamespace, .Description, .ToolNames, and .SkillNames. | ||
systemMessageFrom ValueSource | SystemMessageFrom is a reference to a ConfigMap or Secret containing the system message. When PromptTemplate is set, the resolved value is treated as a Go text/template. | ||
promptTemplate PromptTemplateSpec | PromptTemplate enables Go text/template processing on the systemMessage field. When set, systemMessage is treated as a Go template with access to the include function and agent context variables. | ||
modelConfig string | The name of the model config to use. If not specified, the default value is “default-model-config”. Must be in the same namespace as the Agent. | ||
stream boolean | Whether to stream the response from the model. If not specified, the default value is false. | ||
tools Tool array | MaxItems: 20 | ||
a2aConfig A2AConfig | A2AConfig instantiates an A2A server for this agent, served on the HTTP port of the kagent kubernetes controller (default 8083). The A2A server URL will be served at <kagent-controller-ip>:8083/api/a2a/<agent-namespace>/<agent-name> Read more about the A2A protocol here: https://github.com/a2aproject/A2A | ||
deployment DeclarativeDeploymentSpec | |||
memory MemorySpec | Memory configuration for the agent. | ||
shareTools boolean | ShareTools enables the built-in share link tools for this agent. When true, the agent gains create_share_link, list_share_links, and delete_share_link tools that allow it to manage share tokens for the current session. | ||
context ContextConfig | Context configures context management for this agent. This includes event compaction (compression) and context caching. |
DeclarativeDeploymentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
imageRegistry string | |||
replicas integer | Replicas is the number of desired agent pods. Defaults to 1. | ||
imagePullSecrets LocalObjectReference array | ImagePullSecrets are references to secrets in the agent’s namespace used for pulling the agent container image. | ||
volumes Volume array | Volumes are additional volumes added to the agent pod. | ||
volumeMounts VolumeMount array | VolumeMounts are additional volume mounts added to the agent container. | ||
labels object (keys:string, values:string) | Labels are additional labels added to the agent pods. | ||
annotations object (keys:string, values:string) | Annotations are additional annotations added to the agent pods. | ||
deploymentAnnotations object (keys:string, values:string) | DeploymentAnnotations are additional annotations added to the agent Deployment object itself. Unlike Annotations, which apply to the agent pods, these apply to the Deployment metadata. Keys set here take precedence over annotations inherited from the agent resource metadata. This has no effect when the agent runs with the Sandbox workload mode, as no Deployment is created in that mode. | ||
env EnvVar array | Env are additional environment variables set on the agent container. | ||
envFrom EnvFromSource array | EnvFrom are sources (ConfigMaps/Secrets) used to populate environment variables on the agent container. Values defined in Env with a duplicate key take precedence. | ||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | Tolerations applied to the agent pods. | ||
affinity Affinity | |||
topologySpreadConstraints TopologySpreadConstraint array | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. All topologySpreadConstraints are ANDed. | ||
nodeSelector object (keys:string, values:string) | NodeSelector restricts the nodes the agent pods can be scheduled on. | ||
securityContext SecurityContext | |||
podSecurityContext PodSecurityContext | |||
serviceAccountName string | ServiceAccountName specifies the name of an existing ServiceAccount to use. If this field is set, the Agent controller will not create a ServiceAccount for the agent. This field is mutually exclusive with ServiceAccountConfig. | ||
serviceAccountConfig ServiceAccountConfig | ServiceAccountConfig configures the ServiceAccount created by the Agent controller. This field can only be used when ServiceAccountName is not set. If ServiceAccountName is not set, a default ServiceAccount (named after the agent) is created, and this config will be applied to it. | ||
extraContainers Container array | ExtraContainers is a list of additional containers to run alongside the main agent container. Useful for sidecars such as token proxies, log shippers, or security agents. |
DeclarativeRuntime
Underlying type: string
DeclarativeRuntime represents the runtime implementation for declarative agents
Validation:
- Enum: [python go]
Appears in:
| Field | Description |
|---|---|
python | |
go |
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:
| 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. | 2024-10-21 |
FromNamespaces
Underlying type: string
FromNamespaces specifies namespace from which references to this resource are allowed. This follows the same pattern as Gateway API’s cross-namespace route attachment. See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment
Validation:
- Enum: [All Same Selector]
Appears in:
| Field | Description |
|---|---|
All | NamespacesFromAll allows references from all namespaces. |
Same | NamespacesFromSame only allows references from the same namespace as the target resource (default). |
Selector | NamespacesFromSelector allows references from namespaces matching the selector. |
GDCHServiceAccountConfig
GDCHServiceAccountConfig holds GDCH-specific token exchange parameters.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
audience string | Audience is the token exchange audience URL (the GDC inference gateway base URL) |
GeminiConfig
GeminiConfig contains Gemini (AI Studio, API-key) specific configuration options
Appears in:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences | ||
maxOutputTokens integer | Maximum output tokens | Minimum: 1 | |
candidateCount integer | Candidate count | ||
responseMimeType string | Response mime type |
GitRepo
GitRepo specifies a single Git repository to fetch skills from.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
url string | URL of the git repository (HTTPS or SSH). | ||
ref string | Git reference: branch name, tag, or commit SHA. | main | |
path string | Subdirectory within the repo to use as the skill root. The API validates this input path, but treats repository contents as trusted: symlinks under this path are dereferenced when materializing the skill. | ||
name string | Name for the skill directory under /skills. If omitted, defaults to the last segment of Path when Path is set; otherwise defaults to the repo name (last URL path segment, without .git). |
MCPTool
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | |||
description string |
McpServerTool
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
kind string | |||
apiGroup string | |||
name string | |||
namespace string | |||
toolNames string array | The names of the tools to be provided by the ToolServer For a list of all the tools provided by the server, the client can query the status of the ToolServer object after it has been created | MaxItems: 50 | |
requireApproval string array | RequireApproval lists tool names that require human approval before execution. Each name must also appear in ToolNames. When a tool in this list is invoked by the agent, execution pauses and the user is prompted to approve or reject the call. | MaxItems: 50 | |
allowedHeaders string array | AllowedHeaders specifies which headers from the A2A request should be propagated to MCP tool calls. Header names are case-insensitive. Authorization header behavior: - Authorization headers CAN be propagated if explicitly listed in allowedHeaders - When STS token propagation is enabled, STS-generated Authorization headers will take precedence and replace any Authorization header from the A2A request - This is a security measure to prevent request headers from overwriting authentication tokens generated by the STS integration Example: [“x-user-email”, “x-tenant-id”] |
MemorySpec
MemorySpec enables long-term memory for an agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
modelConfig string | ModelConfig is the name of the ModelConfig object whose embedding provider will be used to generate memory vectors. | ||
ttlDays integer | TTLDays controls how many days a stored memory entry remains valid before it is eligible for pruning. Defaults to 15 days when unset or zero. | Minimum: 1 |
ModelConfig
ModelConfig is the Schema for the modelconfigs API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | ModelConfig | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec ModelConfigSpec | |||
status ModelConfigStatus |
ModelConfigSpec
ModelConfigSpec defines the desired state of ModelConfig.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
model string | |||
apiKeySecret string | The name of the secret that contains the API key. Must be a reference to the name of a secret in the same namespace as the referencing ModelConfig. For the SAPAICore provider, the secret must contain two keys: “client_id” and “client_secret” (the OAuth2 client credentials for SAP AI Core). The apiKeySecretKey field is not used for SAPAICore. | ||
apiKeySecretKey string | The key in the secret that contains the API key. Not used for the SAPAICore provider (which always reads “client_id” and “client_secret” from the secret). | ||
apiKeyPassthrough boolean | APIKeyPassthrough enables forwarding the Bearer token from incoming A2A requests directly to the LLM provider as the API key. This is useful for organizations with federated identity that want to avoid separate secret management. Mutually exclusive with apiKeySecret. | ||
defaultHeaders object (keys:string, values:string) | |||
provider ModelProvider | The provider of the model | OpenAI | Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore 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:
| 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:
| 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/v1alpha2 | ||
kind string | ModelProviderConfig | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec ModelProviderConfigSpec | |||
status ModelProviderConfigStatus |
ModelProviderConfigSpec
ModelProviderConfigSpec defines the desired state of ModelProviderConfig.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type ModelProvider | Type is the model provider type (OpenAI, Anthropic, etc.) | Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore 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:
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer | ObservedGeneration reflects the generation of the most recently observed ModelProviderConfig spec | ||
conditions Condition array | Conditions represent the latest available observations of the ModelProviderConfig’s state | ||
discoveredModels string array | DiscoveredModels is the cached list of model IDs available from this model provider | ||
modelCount integer | ModelCount is the number of discovered models (for kubectl display) | ||
lastDiscoveryTime Time | LastDiscoveryTime is the timestamp of the last successful model discovery | ||
secretHash string | SecretHash is a hash of the referenced secret data, used to detect secret changes |
NetworkConfig
NetworkConfig configures outbound network access for sandboxed execution paths.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
allowedDomains string array | AllowedDomains lists the domains that sandboxed execution may contact. Wildcards such as *.example.com are supported by the sandbox runtime. |
OllamaConfig
OllamaConfig contains Ollama-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
host string | Host for the Ollama API | ||
options object (keys:string, values:string) | Options for the Ollama API |
OpenAIAPIFormat
Underlying type: string
OpenAIAPIFormat selects the OpenAI HTTP API shape used by the Go ADK runtime.
Validation:
- Enum: [chatCompletions responses]
Appears in:
| Field | Description |
|---|---|
chatCompletions | |
responses |
OpenAIConfig
OpenAIConfig contains OpenAI-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
baseUrl string | Base URL for the OpenAI API (overrides default) | ||
organization string | Organization ID for the OpenAI API | ||
temperature string | Temperature for sampling | ||
maxTokens integer | Maximum tokens to generate. Sent as the OpenAI max_tokens requestparameter, 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 OpenAImax_completion_tokens request parameter (an upper bound on visibleoutput 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:
PromptSource
PromptSource references a ConfigMap whose keys are available as prompt fragments. In systemMessage templates, use include(“alias/key”) (or include(“name/key”) if no alias is set) to insert the value of a specific key from this source.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
kind string | |||
apiGroup string | |||
name string | |||
alias string | Alias is an optional short identifier for use in include directives. If set, use include(“alias/key”) instead of include(“name/key”). |
PromptTemplateSpec
PromptTemplateSpec configures prompt template processing for an agent’s system message.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
dataSources PromptSource array | DataSources defines the ConfigMaps whose keys can be included in the systemMessage using Go template syntax, e.g. include(“alias/key”) or include(“name/key”). | MaxItems: 20 |
RemoteMCPServer
RemoteMCPServer is the Schema for the RemoteMCPServers API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | RemoteMCPServer | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec RemoteMCPServerSpec | |||
status RemoteMCPServerStatus |
RemoteMCPServerProtocol
Underlying type: string
Validation:
- Enum: [SSE STREAMABLE_HTTP]
Appears in:
| Field | Description |
|---|---|
SSE | |
STREAMABLE_HTTP |
RemoteMCPServerSpec
RemoteMCPServerSpec defines the desired state of RemoteMCPServer.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
description string | |||
protocol RemoteMCPServerProtocol | STREAMABLE_HTTP | Enum: [SSE STREAMABLE_HTTP] | |
url string | MinLength: 1 | ||
headersFrom ValueRef array | |||
timeout Duration | 30s | ||
sseReadTimeout Duration | |||
terminateOnClose boolean | true | ||
allowedNamespaces AllowedNamespaces | AllowedNamespaces defines which namespaces are allowed to reference this RemoteMCPServer. This follows the Gateway API pattern for cross-namespace route attachments. If not specified, only Agents in the same namespace can reference this RemoteMCPServer. See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment A cross-namespace-permitting value (from: All or from: Selector) is mutually exclusive with spec.tls.caCertSecretRef (enforced by a spec-level XValidation rule): a pinned CA Secret is mounted onto the consuming agent’s pod by bare name and Kubernetes resolves it in the agent’s namespace, not this RemoteMCPServer’s, so a CA-pinning RemoteMCPServer cannot be referenced cross-namespace. from: Same (the default) is always allowed. | ||
tls TLSConfig | TLS configuration for the upstream MCP server connection. Use this for HTTPS upstreams that present a certificate the agent’s system trust store does not include (corporate CA, self-signed cert on a test fixture, internal MCP gateway). Reuses the same TLSConfig type as ModelConfig.spec.tls — disableVerify turns off certificate validation entirely, caCertSecretRef + caCertSecretKey point at a PEM bundle Secret in the same namespace, and disableSystemCAs trusts only the named bundle. Note one asymmetry with ModelConfig: a spec-level XValidation rule on RemoteMCPServer rejects spec.tls when spec.url has the http:// scheme (a TLS opinion contradicts a plaintext URL). ModelConfig has no equivalent rule, so a TLS block can sit alongside any baseUrl. |
RemoteMCPServerStatus
RemoteMCPServerStatus defines the observed state of RemoteMCPServer.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer | INSERT ADDITIONAL STATUS FIELD - define observed state of cluster Important: Run “make” to regenerate code after modifying this file | ||
conditions Condition array | |||
discoveredTools MCPTool array | |||
secretHash string | SecretHash stores a hash of the TLS Secret referenced by spec.tls so agents that consume this RemoteMCPServer can detect cert rotation and roll on the next reconcile. Empty when spec.tls.caCertSecretRef is unset. |
S3SkillRef
S3SkillRef specifies a skill bundle in an S3 bucket.
Two bundle shapes are supported:
- Prefix: s3://bucket/path/to/skill/ containing SKILL.md (and siblings); synced recursively
- Archive: a single .zip / .tgz / .tar.gz object; downloaded and extracted
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
uri string | S3 URI of the skill: s3://bucket/key-or-prefix | MinLength: 1 Pattern: ^s3://.+ | |
region string | AWS region for the bucket. Optional when AWS_REGION / AWS_DEFAULT_REGION is set on the skills-init container (e.g. via initContainer.env). | ||
name string | Name for the skill directory under /skills. If omitted, defaults to the last non-empty path segment of the URI (archive extension stripped). |
SAPAICoreConfig
SAPAICoreConfig contains SAP AI Core-specific configuration options.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
baseUrl string | Base URL for the SAP AI Core API (e.g., https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com) | ||
resourceGroup string | Resource group in SAP AI Core | default | |
authUrl string | OAuth2 token endpoint URL (e.g., https://tenant.authentication.eu10.hana.ondemand.com) |
SandboxAgent
SandboxAgent declares an agent that runs in an isolated sandbox on Agent Substrate.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | SandboxAgent | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec SandboxAgentSpec | |||
status AgentStatus |
SandboxAgentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type AgentType | Declarative | Enum: [Declarative BYO] | |
byo BYOAgentSpec | BYO configures a “bring your own” agent backed by a user-provided container image. Kagent deploys the image and expects it to serve the agent over the A2A protocol on port 8080. Required if type is BYO. | ||
declarative DeclarativeAgentSpec | Declarative configures an agent that is fully described by this resource (model, instructions, tools) and runs on one of kagent’s built-in runtimes. Required if type is Declarative. | ||
description string | |||
iconUrl string | IconURL is a URL to an icon representing the agent. It is surfaced on the agent’s A2A AgentCard. | Format: uri | |
documentationUrl string | DocumentationURL is a URL to human-readable documentation for the agent. It is surfaced on the agent’s A2A AgentCard. | Format: uri | |
version string | Version is the agent’s version string, surfaced on the A2A AgentCard. | ||
provider AgentProvider | Provider identifies the organization responsible for the agent. It is surfaced on the agent’s A2A AgentCard. | ||
skills SkillForAgent | Skills to load into the agent. They will be pulled from OCI images, git repos, and/or S3, and made available to the agent under the /skills folder. | ||
sandbox SandboxConfig | Sandbox configures sandboxed execution behavior shared across runtimes. This is intended for sandboxed declarative execution today, and can also be consumed by BYO agents. | ||
allowedNamespaces AllowedNamespaces | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool. This follows the Gateway API pattern for cross-namespace route attachments. If not specified, only Agents in the same namespace can reference this Agent as a tool. This field only applies when this Agent is used as a tool by another Agent. See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | ||
substrate SandboxSubstrateSpec | Substrate is optional Agent Substrate-specific settings. |
SandboxConfig
SandboxConfig configures sandboxed execution behavior.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
network NetworkConfig | Network configures outbound network access for sandboxed execution paths. When unset or when allowedDomains is empty, outbound access is denied by default. |
SandboxSubstrateSpec
SandboxSubstrateSpec configures Agent Substrate for a SandboxAgent. WorkerPool capacity is referenced from workerPoolRef or the controller default.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
workerPoolRef TypedLocalReference | WorkerPoolRef references an existing ate.dev WorkerPool. | ||
snapshotsConfig AgentHarnessSubstrateSnapshotsConfig | SnapshotsConfig configures actor memory snapshots. Defaults to gs://ate-snapshots/<namespace>/<agentname> when unset. |
SecretReference
SecretReference references a Kubernetes Secret that must contain exactly one data key holding the API key or credential.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name is the name of the secret in the same namespace as the ModelProviderConfig. |
ServiceAccountConfig
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
labels object (keys:string, values:string) | Labels are additional labels added to the created ServiceAccount. | ||
annotations object (keys:string, values:string) | Annotations are additional annotations added to the created ServiceAccount. |
SharedDeploymentSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
replicas integer | Replicas is the number of desired agent pods. Defaults to 1. | ||
imagePullSecrets LocalObjectReference array | ImagePullSecrets are references to secrets in the agent’s namespace used for pulling the agent container image. | ||
volumes Volume array | Volumes are additional volumes added to the agent pod. | ||
volumeMounts VolumeMount array | VolumeMounts are additional volume mounts added to the agent container. | ||
labels object (keys:string, values:string) | Labels are additional labels added to the agent pods. | ||
annotations object (keys:string, values:string) | Annotations are additional annotations added to the agent pods. | ||
deploymentAnnotations object (keys:string, values:string) | DeploymentAnnotations are additional annotations added to the agent Deployment object itself. Unlike Annotations, which apply to the agent pods, these apply to the Deployment metadata. Keys set here take precedence over annotations inherited from the agent resource metadata. This has no effect when the agent runs with the Sandbox workload mode, as no Deployment is created in that mode. | ||
env EnvVar array | Env are additional environment variables set on the agent container. | ||
envFrom EnvFromSource array | EnvFrom are sources (ConfigMaps/Secrets) used to populate environment variables on the agent container. Values defined in Env with a duplicate key take precedence. | ||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | Tolerations applied to the agent pods. | ||
affinity Affinity | |||
topologySpreadConstraints TopologySpreadConstraint array | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. All topologySpreadConstraints are ANDed. | ||
nodeSelector object (keys:string, values:string) | NodeSelector restricts the nodes the agent pods can be scheduled on. | ||
securityContext SecurityContext | |||
podSecurityContext PodSecurityContext | |||
serviceAccountName string | ServiceAccountName specifies the name of an existing ServiceAccount to use. If this field is set, the Agent controller will not create a ServiceAccount for the agent. This field is mutually exclusive with ServiceAccountConfig. | ||
serviceAccountConfig ServiceAccountConfig | ServiceAccountConfig configures the ServiceAccount created by the Agent controller. This field can only be used when ServiceAccountName is not set. If ServiceAccountName is not set, a default ServiceAccount (named after the agent) is created, and this config will be applied to it. | ||
extraContainers Container array | ExtraContainers is a list of additional containers to run alongside the main agent container. Useful for sidecars such as token proxies, log shippers, or security agents. |
SkillForAgent
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
insecureSkipVerify boolean | Fetch images insecurely from registries (allowing HTTP and skipping TLS verification). Meant for development and testing purposes only. | ||
refs string array | The list of skill images to fetch. | MaxItems: 20 MinItems: 1 | |
imagePullSecrets LocalObjectReference array | ImagePullSecrets is a list of references to secrets in the same namespace to use for pulling skill images from private registries. Each referenced secret must be of type kubernetes.io/dockerconfigjson. The credentials from all secrets are merged and made available to the skills-init container at /.kagent/.docker/config.json; krane will use them automatically when pulling images. | MaxItems: 20 | |
gitAuthSecretRef LocalObjectReference | Reference to a Secret containing git credentials. Applied to all gitRefs entries. The secret should contain a token key for HTTPS auth,or ssh-privatekey for SSH auth. | ||
gitRefs GitRepo array | Git repositories to fetch skills from. | MaxItems: 20 MinItems: 1 | |
s3Refs S3SkillRef array | S3 object prefixes or archives to fetch skills from. Auth uses the AWS SDK default credential chain (typically static keys via skills.initContainer.env: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION). | MaxItems: 20 MinItems: 1 | |
initContainer SkillsInitContainer | Configuration for the skills-init init container. |
SkillsInitContainer
SkillsInitContainer configures the skills-init init container.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
resources ResourceRequirements | Resource requirements for the skills-init init container. | ||
env EnvVar array | Additional environment variables for the skills-init init container. |
TLSConfig
TLSConfig contains TLS/SSL configuration options for outbound HTTPS connections from the agent (model provider, RemoteMCPServer). The XValidation rules below apply at admission to every CRD field that uses TLSConfig, so callers don’t need to re-declare them per spec.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
disableVerify boolean | DisableVerify disables SSL certificate verification entirely. When false (default), SSL certificates are verified. When true, SSL certificate verification is disabled. WARNING: This should ONLY be used in development/testing environments. Production deployments MUST use proper certificates. | false | |
caCertSecretRef string | CACertSecretRef is a reference to a Kubernetes Secret containing CA certificate(s) in PEM format. The Secret must be in the same namespace as the resource referencing it (ModelConfig, RemoteMCPServer, or any future consumer of TLSConfig). When set, the certificate will be used to verify the upstream’s SSL certificate. | ||
caCertSecretKey string | CACertSecretKey is the key within the Secret that contains the CA certificate data (PEM-encoded). Required when CACertSecretRef is set — admission rejects ref-without-key regardless of DisableVerify (see the TLSConfig-level XValidation rules). | ||
disableSystemCAs boolean | DisableSystemCAs disables the use of system CA certificates. When false (default), system CA certificates are used for verification (safe behavior). When true, only the custom CA from CACertSecretRef is trusted. This allows strict security policies where only corporate CAs should be trusted. | false |
TokenExchangeConfig
TokenExchangeConfig configures dynamic bearer token acquisition before model calls.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type TokenExchangeType | Enum: [GDCHServiceAccount] | ||
gdchServiceAccount GDCHServiceAccountConfig |
TokenExchangeType
Underlying type: string
TokenExchangeType identifies the token exchange mechanism
Validation:
- Enum: [GDCHServiceAccount]
Appears in:
| Field | Description |
|---|---|
GDCHServiceAccount |
Tool
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type ToolProviderType | Enum: [McpServer Agent] | ||
mcpServer McpServerTool | |||
agent TypedReference | |||
isolateSessions boolean | IsolateSessions controls per-call session isolation for Agent-type tools. Only valid when Type is Agent. When unset or false (default), every call this agent makes to the referenced sub-agent reuses the same A2A context_id, so all calls land in one shared sub-agent session (session continuity for stateful sub-agents). When true, each call mints a fresh context_id, so every invocation runs in its own isolated sub-agent session. This is required for parallel fan-out to a sub-agent: without it, N parallel calls in one turn collapse into a single shared sub-agent session instead of N independent ones. Cross-turn/conversation continuity for stateful sub-agents does not depend on this flag; it rides the x-kagent-root-context-id header, which stays stable regardless of IsolateSessions. | ||
headersFrom ValueRef array | HeadersFrom specifies a list of configuration values to be added as headers to requests sent to the Tool from this agent. The value of each header is resolved from either a Secret or ConfigMap in the same namespace as the Agent. Headers specified here will override any headers of the same name/key specified on the tool. |
ToolProviderType
Underlying type: string
ToolProviderType represents the tool provider type
Validation:
- Enum: [McpServer Agent]
Appears in:
| Field | Description |
|---|---|
McpServer | |
Agent |
TypedLocalReference
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
kind string | |||
apiGroup string | |||
name string |
TypedReference
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
kind string | |||
apiGroup string | |||
name string | |||
namespace string |
ValueRef
ValueRef represents a configuration value
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | |||
value string | |||
valueFrom ValueSource |
ValueSource
ValueSource defines a source for configuration values from a Secret or ConfigMap
Appears in:
- AgentHarnessChannelCredential
- AgentHarnessHermesSlackOptions
- AgentHarnessTelegramChannelSpec
- DeclarativeAgentSpec
- ValueRef
| Field | Description | Default | Validation |
|---|---|---|---|
type ValueSourceType | Enum: [ConfigMap Secret] | ||
name string | The name of the ConfigMap or Secret. | MaxLength: 253 | |
key string | The key of the ConfigMap or Secret. | MaxLength: 253 |
ValueSourceType
Underlying type: string
Appears in:
| Field | Description |
|---|---|
ConfigMap | |
Secret |