Documentation

Release Notes#

The kagent documentation shows information only for the latest release. If you run an older version, review the release notes to understand the main changes from version to version.

v0.6#

Review the main changes from kagent version 0.5 to v0.6, then continue reading for more detailed information.

The apiVersion field in the kagent CRDs is now kagent.dev/v1alpha2.
A new Helm chart for kmcp CRDs is available.
API string references to resources in other namespaces in the format namespace/name now fail. Instead, the APIs have a separate field for you to specify the namespace of the resource.
The Tools API moves or eliminates some APIs entirely in favor of new kmcp APIs.
The Agents APIs now require a top-level type field to support the new BYO agent functionality.
The ModelConfig APIs rename the secret name field from apiKeySecret to apiKeySecret.
Memory APIs are not supported in ADK.

Upgraded API version#

The apiVersion field in the kagent CRDs is now kagent.dev/v1alpha2.

New! Helm chart for kmcp CRDs#

Previously, the kagent installation included only one CRD Helm chart. As of v0.6.3, the MCPServer CRD is part of a separate kmcp Helm subchart. This kmcp subchart is installed for you when you install the kagent CRD Helm chart.

If you installed the separate kmcp CRD Helm in earlier versions of v0.6, uninstall the Helm chart.
```
helm uninstall kmcp-crds -n kagent
```

Install the kagent CRD Helm chart that includes the kmcp subchart.

helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --namespace kagent \
  --create-namespace

General changes#

namespace/name references: API string references to resources in other namespaces in the format namespace/name now fail. Instead, the APIs have a separate field for you to specify the namespace of the resource.

Local development buildx access: The make helm-install command now creates a local Docker registry to push development images to. As part of the build process, you might need to allow the buildx builder to access your host network. For more information, see the developer docs in the kagent repo.

Tools APIs#

The Tools-related APIs are split up into several different APIs. Some functionality is moved to kmcp, such as the ToolServer API.

ToolServer#

The ToolServer API is completely removed from kagent. Instead, use other resources including some kmcp APIs to create and manage tools.

Stdio ToolServer now in kmcp MCPServer#

Flip through the following tabs to understand the API differences between the old kagent ToolServer and the new method of using kmcp along with a kagent MCPServer and Kubernetes Service for the Stdio transport type.

Old ToolServer example:

The stdio config section includes the Grafana deployment details.
The Grafana details, including the API key, are loaded as environment settings directly in the ToolServer.

apiVersion: kagent.dev/v1alpha2
kind: ToolServer
metadata:
  name: mcp-grafana
  namespace: kagent
spec:
  config:
    stdio:
      command: /app/python/bin/mcp-grafana
      args:
        - -t
        - stdio
        - debug
      readTimeoutSeconds: 30
      envFrom:
      - name: "GRAFANA_URL"
        value: my-url.com
      - name: "GRAFANA_API_KEY"
        valueFrom:
          type: Secret
          key: "grafana"
          valueRef: kagent-toolserver-secret
  description: ""

kmcp example:

The kagent MCPServer includes the Grafana deployment details, with stdio as the transport type.

apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: grafana
spec:
  deployment:
    image: "mcp/grafana:latest"
    port: 3000
    cmd: "/app/mcp-grafana"
    args:
      - "--transport"
      - "stdio"
    env:
      GRAFANA_URL: my-url.com
    secretRefs:
      - name: grafana-api-key
  transportType: "stdio"

The Grafana API key is stored separately in a Secret, which is more secure.

apiVersion: v1
kind: Secret
metadata:
  name: grafana-api-key
type: Opaque
data:
  GRAFANA_API_KEY: my-base-64-ikey

HTTP ToolServer moved to RemoteMCPServer#

ToolServer resources that used type: streamableHttp are now configured as RemoteMCPServer resources. For more detailed information, review the API definitions:

ToolServer: toolserver_types.go
RemoteMCPServer: remotemcpserver_types.go
MCPServer: mcpserver_types.go

Old ToolServer API:

apiVersion: kagent.dev/v1alpha2
kind: ToolServer
metadata:
  name: kagent-tool-server
spec:
  config:
    type: streamableHttp
    streamableHttp:
      url: "http://kagent-tools.kagent:8084/mcp"
      timeout: 30s
      sseReadTimeout: 5m0s
  description: "Official KAgent tool server"

New RemoteMCPServer API:

apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: kagent-tool-server
spec:
  url: "http://kagent-tools.kagent:8084/mcp"
  timeout: 30s
  sseReadTimeout: 5m0s
  description: "Official KAgent tool server"

Kubernetes Services as HTTP MCP servers#

Now, you can use Kubernetes Services as MCP Servers.

In the old configuration, you created a Service for your MCP Deployment, and then a ToolServer resource that referred to the Service.

apiVersion: v1
kind: Service
metadata:
  name: kagent-querydoc
  namespace: kagent
spec:
  ports:
    - name: http
      port: 8080
      protocol: TCP
      targetPort: http
---
apiVersion: kagent.dev/v1alpha2
kind: ToolServer
metadata:
  name: kagent-querydoc
  namespace: kagent
spec:
  description: Queries a documentation site
  config:
    sse:
      url: http://kagent-querydoc.kagent.svc.cluster.local/sse

In v0.6, you add certain fields to designate the Service as an MCP server.

In the following configuration file, notice the following settings:

kagent.dev/mcp-service: "true": Optional: Configure kagent to discover the tools for this Service.
appProtocol: mcp: Required: Configure the port that the controller uses. If not set, and there is a single port, the controller uses that port for the MCP server.

Additional annotations: You can use the following annotations to further configure the your MCP Service.

kagent.dev:mcp-service-path: Set the path on which the MCP server lives. The default value is /mcp.
kagent.dev/mcp-service-port: Set the port number to be used. No port is set by default.
kagent.dev/mcp-service-port: Set the protocol to use. Accepted values are SSE or STREAMABLE_HTTP. The default value is STREAMABLE_HTTP.

apiVersion: v1
kind: Service
metadata:
  labels:
    kagent.dev/mcp-service: "true"
  annotations:
    kagent.dev:mcp-service-path: /sse
    kagent.dev/mcp-service-port: 8080
    kagent.dev/mcp-service-protocol: SSE
  name: kagent-querydoc
  namespace: kagent
spec:
  ports:
  - appProtocol: mcp
    name: http
    port: 8080
    protocol: TCP
    targetPort: http

Agent APIs#

API to specify the MCP server#

Old API Example:

tools:
  - type: McpServer
    mcpServer:
      toolServer: kagent-querydoc
      toolNames:
        - query_documentation

New API Example:

tools:
  - type: McpServer
    mcpServer:
      name: kagent-querydoc
      kind: Service
      toolNames:
        - query_documentation

Key Changes:

The toolServer field has been removed
Replaced with: name, kind, and apiGroup fields
This allows specifying 3 different types: RemoteMCPServer, Service, and MCPServer

The toolServer field has been removed, and has been replaced with the following: name kind apiGroup This allows for specifying the 3 different types which may be used. Those are: RemoteMCPServer Service MCPServer Here are the 2 api defs:

Top-level field for Agent APIs#

A new top-level type field is added to the Agents API. For existing Agents, set the type to Declarative, and then nest the previous Agent configuration inline under the declarative setting.

This change supports the new type for BYO agents.

v1alpha1 Example:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: k8s-agent
  namespace: {{ include "kagent.namespace" . }}
  labels:
    {{- include "kagent.labels" . | nindent 4 }}
spec:
  description: An Kubernetes Expert AI Agent specializing in cluster operations, troubleshooting, and maintenance.
  systemMessage: |
    # Kubernetes AI Agent System Prompt

    You are KubeAssist, an advanced AI agent
    # ... (truncated for brevity)

v1alpha2 Example: Note that the entire agent configuration is now nested under the inline setting.

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: k8s-agent
  namespace: kagent
spec:
  description: An Kubernetes Expert AI Agent specializing in cluster operations, troubleshooting, and maintenance.
  type: Declarative
  declarative:
    systemMessage: |
      # Kubernetes AI Agent System Prompt

      You are KubeAssist, an advanced AI agent
      # ... (truncated for brevity)

Key Changes:

Added type: Declarative field to specify agent type
Agent configuration now under inline section
Supports new BYO deployment model

New! BYO agents#

A new agent type has been added to the Agents API so that you can bring your own (BYO) agent. The agent must be written in ADK, with other frameworks under development.

BYO Agent example configuration. For more information, see the BYO Agent guide.

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: basic-agent
  namespace: kagent
spec:
  description: This agent can do anything.
  type: BYO
  byo:
    deployment:
      image: my-byo:latest
      env:
        - name: GOOGLE_API_KEY
          valueFrom:
            secretKeyRef:
              name: kagent-google
              key: GOOGLE_API_KEY

ModelConfig API#

The secret name field is renamed from apiKeySecret to apiKeySecret.

ModelInfo removed#

The modelInfo setting is removed from the ModelConfig API.

Supported LLM providers are pre-configured by the kagent-dev/autogen project fork for you by default. Trying to override these default settings, such as to enable vision for image recognition, could cause unexpected behavior in models that do not support these settings. Therefore, the modelInfo field is removed.

Memory API#

The Memory API is not supported in ADK. The agent development kit is required to bring your own agents. As such, the Memory docs are removed.

Kagent Lab: Discover kagent and kmcp

Free, on‑demand lab: build custom AI agents with kagent and integrate tools via kmcp on Kubernetes.

Start the Lab