Edit

Share via

Install and use the agentic CLI for Azure Kubernetes Service (AKS) (Preview)

This article shows you how to install, configure, and use the agentic CLI for Azure Kubernetes Service (AKS) to get AI-powered troubleshooting and insights for your AKS clusters. The agentic CLI supports two deployment modes: client mode for local execution and cluster mode for in-cluster deployment.

For more information, see the agentic CLI for AKS overview.

Deployment modes

The agentic CLI for AKS supports two deployment modes that you can choose during initialization.

These two modes are only available from version "1.0.0b16" of the aks-agent extension

Client mode

  • Deployment: Runs the agent locally using Docker.
  • Authentication: Uses your local Azure credentials and cluster user credentials.
  • Use case: Ideal for development, testing, and scenarios where you want to run the agent from your local machine.
  • Requirements: Requires Docker to be installed locally.

Cluster mode

  • Deployment: Deploys the agent as a pod within your AKS cluster using Helm.
  • Authentication: Uses service account and optional workload identity for secure access to cluster and Azure resources.
  • Use case: Recommended for production scenarios, shared environments, and when you want the agent to run closer to your cluster resources.
  • Requirements: Requires existing namespace, service account with RBAC permissions, and workload identity setup for Azure resource access.

Prerequisites

Both deployment modes require the following:

  • Use the Azure CLI version 2.76 or later. To verify your Azure CLI version, use the az version command.

  • Have a large language model (LLM) API key. You must bring your own API key from one of the supported providers:

    • Azure OpenAI (recommended).
    • OpenAI or other LLM providers compatible with OpenAPI specifications.

  • Ensure that you're signed in to the proper subscription by using the az account set command.

  • Install the agentic CLI for AKS extension.

Install the agentic CLI for AKS extension

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

  1. Add the agentic CLI for AKS extension to your Azure CLI installation by using the az extension add command. If the extension is already installed, you can update to the latest version with the az extension update command. This step might take 5 to 10 minutes to complete.

    # Install the extension
az extension add --name aks-agent --debug

# Update the extension
az extension update --name aks-agent --debug

  2. Verify that the installation was successful by using the az version command.

    az extension list

    Your output should include an entry for aks-agent.

  3. Verify that the extension is installed by using the az aks agent command with the --help parameter.

    az aks agent --help

    Your output should show the aks-agent with its version information in the extensions section, as shown in the following condensed example output:

    ...
"extensions": {
"aks-agent": "1.0.0b17",
}

Set up your LLM API key

Before proceeding with installation, you need to set up your LLM API key. We recommend that you use newer models such as GPT-5, or Claude Opus MINI for better performance. Choose a model with a high context size of at least 128,000 tokens or higher.

Set up an Azure OpenAI resource by following the steps in the Microsoft documentation.

Note

For the deployment name, use the same name as the model name, such as gpt-4o or gpt-4o-mini, depending on the access. You can use any region where you have access and quota for the model. In the deployment, select a token-per-minute (TPM) limit as high as possible. We recommend upward of a 1-million TPM for good performance.

  1. Deploy the model that you plan to use in the Microsoft Foundry portal.

  2. After deployment is finished, note your API base URL and API key.

    image

The API version isn't the model version. You can use any API version that's available and supported on this webpage.

The Azure API base refers to the Azure OpenAI endpoint (which usually ends in openai.azure.com/), not the target URI of the deployment in Foundry.

Other LLM providers

We also support any OpenAI-compatible model. Check the documentation of the LLM provider for instructions on how to create an account and retrieve the API key.

Installation

Choose your deployment mode and follow the corresponding installation guide:

Client mode runs the agent locally using Docker and your existing Azure credentials.

Prerequisites for client mode

  • Docker: Docker must be installed and running on your local machine. You can download Docker from docker.com.
  • Docker daemon: Ensure the Docker daemon is started and running before proceeding with the installation.
  • Local Azure credentials: Ensure your Azure credentials are properly configured and you have the necessary permissions to access cluster resources.

Verify Docker installation and start Docker daemon

  1. Verify that Docker is installed and the Docker daemon is running:

    docker --version
docker ps

    If Docker isn't installed, follow the Docker installation guide for your operating system.

  2. Start the Docker daemon if it's not running:

    On macOS/Windows:

    • Launch Docker Desktop from your applications
    • Wait for Docker to start (you'll see the Docker icon in your system tray/menu bar)

    On Linux:

    sudo systemctl start docker
sudo systemctl enable docker  # Enable Docker to start on boot

  3. Verify Docker is running:

    docker info

    This command should return Docker system information without errors.

Initialize client mode

  1. Initialize the agentic CLI for client mode by using the az aks agent-init command. Replace <RESOURCE_GROUP> and <CLUSTER_NAME> with your AKS cluster's resource group and name.

    az aks agent-init --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME>

  2. When prompted to select a deployment mode, choose Option 2 for client mode:

    🚀 Welcome to AKS Agent initialization!

Please select the mode you want to use:
  1. Cluster mode - Deploys agent as a pod in your AKS cluster
     Uses service account and workload identity for secure access to cluster and Azure resources
  2. Client mode - Runs agent locally using Docker
     Uses your local Azure credentials and cluster user credentials for access

Enter your choice (1 or 2): 2

  3. Configure your LLM provider when prompted. For example:

    Welcome to AKS Agent LLM configuration setup. Type '/exit' to exit.
 1. Azure Open AI
 2. openai
 3. anthropic
 4. gemini
 5. openai_compatible
Enter the number of your LLM provider: 1
Your selected provider: azure
Enter value for MODEL_NAME:  (Hint: should be consistent with your deployed name, e.g., gpt-4.1) gpt-4.1
Enter your API key: 
Enter value for AZURE_API_BASE:  (Hint: https://{your-custom-endpoint}.openai.azure.com/) https://test-example.openai.azure.com
Enter value for AZURE_API_VERSION:  (Default: 2025-04-01-preview)
LLM configuration setup successfully.

    Note

    The API key appears empty as you type for security. Make sure to enter the correct API key.

  4. Verify the initialization was successful. The agent will automatically pull the necessary Docker images when you run your first command.

Use the agentic CLI for AKS

Once initialized, you can use the agentic CLI for AKS to troubleshoot your clusters and get intelligent insights by using natural language queries. The command syntax and functionality are the same regardless of whether you selected client mode or cluster mode during initialization.

Required parameters

All agent commands require the following parameters:

  • -n or --name: The name of your AKS cluster
  • -g or --resource-group: The resource group containing your AKS cluster

Additional parameters based on deployment mode:

For client mode:

  • --mode client: Specifies client mode execution (default mode is cluster)

For cluster mode:

  • --namespace: The Kubernetes namespace where the agent is deployed (required for cluster mode)

  • The default mode is cluster. You only need to specify --mode client when using client mode.

Basic queries

You can use the following example queries to get started with the agentic CLI for AKS. Replace <RESOURCE_GROUP> and <CLUSTER_NAME> with your actual values.

Note

If you have multiple models set up, you can specify the model to use for each query by using the --model parameter. For example, --model=azure/gpt-4o.

Client mode examples:

az aks agent "How many nodes are in my cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client
az aks agent "What is the Kubernetes version on the cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client
az aks agent "Why is coredns not working on my cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client
az aks agent "Why is my cluster in a failed state?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client

Cluster mode examples:

az aks agent "How many nodes are in my cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE>
az aks agent "What is the Kubernetes version on the cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE>
az aks agent "Why is coredns not working on my cluster?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE>
az aks agent "Why is my cluster in a failed state?" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE>

By default, the experience uses interactive mode, where you can continue asking questions with retained context until you want to leave. To leave the experience, enter /exit.

Agentic CLI for AKS parameters

Parameter Description
--max-steps Maximum number of steps the LLM can take to investigate the issue. Default: 40.
--mode The mode decides how the agent is deployed. Allowed values: client, cluster. Default: cluster.
--model Specify the LLM provider and model or deployment to use for the AI assistant.
--name, -n Name of the managed cluster. (Required)
--namespace The Kubernetes namespace where the AKS Agent is deployed. Required for cluster mode.
--no-echo-request Disable echoing back the question provided to AKS Agent in the output.
--no-interactive Disable interactive mode. When set, the agent will not prompt for input and will run in batch mode.
--refresh-toolsets Refresh the toolsets status.
--resource-group, -g Name of resource group. (Required)
--show-tool-output Show the output of each tool that was called.
--status Show AKS agent configuration and status information.

Model specification

The --model parameter determines which LLM and provider analyzes your cluster. For example:

  • OpenAI: Use the model name directly (for example, gpt-4o).
  • Azure OpenAI: Use azure/<deployment name> (for example, azure/gpt-4o).
  • Anthropic: Use anthropic/claude-sonnet-4.

Configuration file

The LLM configuration and deployment mode selection are stored in a config map through the az aks agent-init experience. If the init command doesn't work, you can still use the configuration file by adding the variables manually. For an example configuration file, see agentic-cli-for-aks/exampleconfig.yaml. You can find the default configuration file path through the az aks agent --help command.

The configuration file currently supports the following parameters:

  • Model
  • API key
  • Deployment mode (client or cluster)
  • Custom toolsets
  • Azure environment variables

You can also use your configuration file by specifying the --config-file parameter with the path to your configuration file when you use the az aks agent command.

az aks agent "Check kubernetes pod resource usage" --config-file exampleconfig.yaml

Interactive commands

The az aks agent has a set of subcommands that aid the troubleshooting experience. To access them, enter / inside the interactive mode experience.

Command Description
/exit Leave the interactive mode.
/help Show help messages with all commands.
/clear Clear the screen and reset the conversation context.
/tools Show available toolsets and their status.
/auto Switch the display of tool outputs after responses.
/last Show all tool outputs from the last response.
/run Run a Bash command and optionally share it with LLM.
/shell Drop into the interactive shell and then optionally share the session with LLM.
/context Show the conversation context size and token count.
/show Show the specific tool output in a scrollable view.
/feedback Provide feedback on the agent's response.

Disable interactive mode

To opt out of the default interactive mode, use the --no-interactive flag:

Client mode:

az aks agent "How many pods are in the kube-system namespace" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client --model=azure/gpt-4o --no-interactive --show-tool-output

Cluster mode:

az aks agent "How many pods are in the kube-system namespace" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE> --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --namespace <NAMESPACE> --model=azure/gpt-4o --no-interactive --show-tool-output

Toolsets

The agentic CLI for AKS includes prebuilt integrations for popular monitoring and observability tools through toolsets. Some integrations work automatically with Kubernetes. Other integrations require API keys or configuration.

For AKS, there are specific toolsets that help with the troubleshooting experience. These toolsets appear in the output at the start of the experience:

...
✅ Toolset kubernetes/kube-prometheus-stack
✅ Toolset internet
✅ Toolset bash
✅ Toolset runbook
✅ Toolset kubernetes/logs
✅ Toolset kubernetes/core
✅ Toolset kubernetes/live-metrics
✅ Toolset aks/core
✅ Toolset aks/node-health
Using 37 datasources (toolsets). To refresh: use flag `--refresh-toolsets`

AKS MCP server integration

The AKS Model Context Protocol (MCP) server is enabled by default with the agentic CLI for AKS. This experience spins up the AKS MCP server locally (or in the cluster with cluster mode) and uses it as the source for telemetry.

Clean up agentic CLI deployment

You can clean up the agentic CLI deployment based on the mode you selected during initialization.

Command parameters

All cleanup commands require the following parameters:

  • -n or --name: The name of your AKS cluster
  • -g or --resource-group: The resource group containing your AKS cluster

For client mode, the cleanup process removes the local configuration and any downloaded Docker images:

az aks agent-cleanup --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --mode client

This command:

  • Removes the local configuration file
  • Resets the agent configuration

Verify client mode cleanup

To verify that the cleanup was successful:

# Check if configuration file was removed
ls ~/.azure/aksAgent.config

# Check for remaining Docker images
docker images | grep aks-agent

Remove the agentic CLI for AKS extension

Remove the agentic CLI for AKS extension by using the az extension remove command.

az extension remove --name aks-agent --debug

Related content

  • Last updated on