Documentation
API Reference#
Packages#
kagent.dev/v1alpha2#
Package v1alpha1 contains API Schema definitions for the agent v1alpha1 API group.
Resource Types#
A2AConfig#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
skills AgentSkill array | MinItems: 1 |
Agent#
Agent is the Schema for the agents API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha2 | ||
kind string | Agent | ||
kind string | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | ||
apiVersion string | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec AgentSpec | |||
status AgentStatus |
AgentSkill#
Underlying type: AgentSkill
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
id string | ID is the unique identifier for the skill. | ||
name string | Name is the human-readable name of the skill. | ||
description string | Description is an optional detailed description of the skill. | ||
tags string array | Tags are optional tags for categorization. | ||
examples string array | Examples are optional usage examples. | ||
inputModes string array | InputModes are the supported input data modes/types. | ||
outputModes string array | OutputModes are the supported output data modes/types. |
AgentSpec#
AgentSpec defines the desired state of Agent.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type AgentType | Declarative | Enum: [Declarative BYO] | |
byo BYOAgentSpec | |||
declarative DeclarativeAgentSpec | |||
description string | |||
skills SkillForAgent | Skills to load into the agent. They will be pulled from the specified container images. and made available to the agent under the /skills folder. |
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 |
AnthropicConfig#
AnthropicConfig contains Anthropic-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
baseUrl string | Base URL for the Anthropic API (overrides default) | ||
maxTokens integer | Maximum tokens to generate | ||
temperature string | Temperature for sampling | ||
topP string | Top-p sampling parameter | ||
topK integer | Top-k sampling parameter |
AnthropicVertexAIConfig#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences | ||
maxTokens integer | Maximum tokens to generate |
AzureOpenAIConfig#
AzureOpenAIConfig contains Azure OpenAI-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
azureEndpoint string | Endpoint for the Azure OpenAI API | ||
apiVersion string | API version for the Azure OpenAI API | ||
azureDeployment string | Deployment name for the Azure OpenAI API | ||
azureAdToken string | Azure AD token for authentication | ||
temperature string | Temperature for sampling | ||
maxTokens integer | Maximum tokens to generate | ||
topP string | Top-p sampling parameter |
BYOAgentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
deployment ByoDeploymentSpec | Trust relationship to the agent. |
BaseVertexAIConfig#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences |
ByoDeploymentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
image string | MinLength: 1 | ||
cmd string | |||
args string array | |||
replicas integer | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) |
DeclarativeAgentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
systemMessage string | SystemMessage is a string specifying the system message for the agent | ||
systemMessageFrom ValueSource | SystemMessageFrom is a reference to a ConfigMap or Secret containing the system message. | ||
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 true. | ||
tools Tool array | MaxItems: 20 | ||
a2aConfig A2AConfig | A2AConfig instantiates an A2A server for this agent, served on the HTTP port of the kagent kubernetes controller (default 8083). The A2A server URL will be served at <kagent-controller-ip>:8083/api/a2a/<agent-namespace>/<agent-name> Read more about the A2A protocol here: https://github.com/google/A2A | ||
deployment DeclarativeDeploymentSpec | |||
executeCodeBlocks boolean | Allow code execution for python code blocks with this agent. If true, the agent will automatically execute python code blocks in the LLM responses. Code will be executed in a sandboxed environment. |
DeclarativeDeploymentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
imageRegistry string | |||
replicas integer | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) |
GeminiConfig#
Appears in:
GeminiVertexAIConfig#
GeminiVertexAIConfig contains Gemini Vertex AI-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
projectID string | The project ID | ||
location string | The project location | ||
temperature string | Temperature | ||
topP string | Top-p sampling parameter | ||
topK string | Top-k sampling parameter | ||
stopSequences string array | Stop sequences | ||
maxOutputTokens integer | Maximum output tokens | ||
candidateCount integer | Candidate count | ||
responseMimeType string | Response mime type |
MCPTool#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | |||
description string |
McpServerTool#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
kind string | |||
apiGroup string | |||
name 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 |
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 | ||
apiKeySecretKey string | The key in the secret that contains the API key | ||
defaultHeaders object (keys:string, values:string) | |||
provider ModelProvider | The provider of the model | OpenAI | Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI] |
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 | ||
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]
Appears in:
| Field | Description |
|---|---|
Anthropic | |
AzureOpenAI | |
OpenAI | |
Ollama | |
Gemini | |
GeminiVertexAI | |
AnthropicVertexAI |
OllamaConfig#
OllamaConfig contains Ollama-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
host string | Host for the Ollama API | ||
options object (keys:string, values:string) | Options for the Ollama API |
OpenAIConfig#
OpenAIConfig contains OpenAI-specific configuration options
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
baseUrl string | Base URL for the OpenAI API (overrides default) | ||
organization string | Organization ID for the OpenAI API | ||
temperature string | Temperature for sampling | ||
maxTokens integer | Maximum tokens to generate | ||
topP string | Top-p sampling parameter | ||
frequencyPenalty string | Frequency penalty | ||
presencePenalty string | Presence penalty | ||
seed integer | Seed value | ||
n integer | N value | ||
timeout integer | Timeout | ||
reasoningEffort OpenAIReasoningEffort | Reasoning effort | Enum: [minimal low medium high] |
OpenAIReasoningEffort#
Underlying type: string
OpenAIReasoningEffort represents how many reasoning tokens the model generates before producing a response.
Validation:
- Enum: [minimal low medium high]
Appears in:
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 | |||
sseReadTimeout Duration | |||
terminateOnClose boolean | true |
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 | Optional: {} |
SharedDeploymentSpec#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
replicas integer | |||
imagePullSecrets LocalObjectReference array | |||
volumes Volume array | |||
volumeMounts VolumeMount array | |||
labels object (keys:string, values:string) | |||
annotations object (keys:string, values:string) | |||
env EnvVar array | |||
imagePullPolicy PullPolicy | |||
resources ResourceRequirements | |||
tolerations Toleration array | |||
affinity Affinity | |||
nodeSelector object (keys:string, values:string) |
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 |
TLSConfig#
TLSConfig contains TLS/SSL configuration options for model provider connections. This enables agents to connect to internal LiteLLM gateways or other providers that use self-signed certificates or custom certificate authorities.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
disableVerify boolean | DisableVerify disables SSL certificate verification entirely. When false (default), SSL certificates are verified. When true, SSL certificate verification is disabled. WARNING: This should ONLY be used in development/testing environments. Production deployments MUST use proper certificates. | false | |
caCertSecretRef string | CACertSecretRef is a reference to a Kubernetes Secret containing CA certificate(s) in PEM format. The Secret must be in the same namespace as the ModelConfig. When set, the certificate will be used to verify the provider's SSL certificate. This field follows the same pattern as APIKeySecret. | ||
caCertSecretKey string | CACertSecretKey is the key within the Secret that contains the CA certificate data. This field follows the same pattern as APIKeySecretKey. Required when CACertSecretRef is set (unless DisableVerify is true). | ||
disableSystemCAs boolean | DisableSystemCAs disables the use of system CA certificates. When false (default), system CA certificates are used for verification (safe behavior). When true, only the custom CA from CACertSecretRef is trusted. This allows strict security policies where only corporate CAs should be trusted. | false |
Tool#
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type ToolProviderType | Enum: [McpServer Agent] | ||
mcpServer McpServerTool | |||
agent TypedLocalReference | |||
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 |
ValueRef#
ValueRef represents a configuration value
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | |||
value string | |||
valueFrom ValueSource |
ValueSource#
ValueSource defines a source for configuration values from a Secret or ConfigMap
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type ValueSourceType | Enum: [ConfigMap Secret] | ||
name string | The name of the ConfigMap or Secret. | ||
key string | The key of the ConfigMap or Secret. |
ValueSourceType#
Underlying type: string
Appears in:
| Field | Description |
|---|---|
ConfigMap | |
Secret |
Kagent Lab: Discover kagent and kmcp
Free, on‑demand lab: build custom AI agents with kagent and integrate tools via kmcp on Kubernetes.