Installare e usare il CLI agentic per Azure Kubernetes Service (AKS) (anteprima)

• Docker installato e in esecuzione nel computer locale. Per istruzioni sull'installazione, vedere Introduzione a Docker.
• Assicurarsi che il daemon Docker sia avviato e in esecuzione prima di procedere con l'installazione.
• Assicurarsi che le credenziali di Azure siano configurate correttamente e si disponga delle autorizzazioni necessarie per accedere alle risorse del cluster.

• Prima di eseguire l'installazione, è necessario creare un account di servizio Kubernetes richiesto con autorizzazioni RBAC. La configurazione dell'identità di carico di lavoro è facoltativa.
• È necessario l'accesso in scrittura per la distribuzione nello spazio dei nomi Kubernetes in cui verrà distribuito l'agente.

Verificare l'installazione di Docker e avviare il daemon Docker

1. Verificare che Docker sia installato e che il daemon Docker sia in esecuzione usando i comandi seguenti:

   docker --version
   docker ps
   

2. Se viene visualizzato un errore che indica che il daemon Docker non è in esecuzione, avviare il servizio Docker usando i passaggi appropriati per il sistema operativo:

   • macOS/Windows:

     • Avviare Docker Desktop dalle applicazioni.
     • Attendere l'avvio di Docker.

   • Linux:

     • Avviare il servizio Docker usando i comandi seguenti:

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

3. Verificare che Docker sia in esecuzione usando il comando seguente:

   docker info
   

   Questo comando deve restituire informazioni di sistema Docker senza errori.

Inizializzare la modalità client

1. Inizializzare la CLI agente con la modalità client usando il comando az aks agent-init. Assicurarsi di sostituire i valori segnaposto con il nome del cluster e del gruppo di risorse effettivi.

   az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
   

2. Quando viene richiesto di selezionare una modalità di distribuzione, immettere 2 per la modalità client.

   🚀 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. Configurare i dettagli del provider LLM. Per esempio:

   Welcome to AKS Agent LLM configuration setup. Type '/exit' to exit.
    1. Azure Open AI (API Key)
    1. Azure Open AI (Microsoft Entra ID)
    3. OpenAI
    4. Anthropic
    5. Gemini
    6. 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.
   

   Annotazioni

   La chiave API viene visualizzata vuota durante la digitazione per la sicurezza. Assicurarsi di immettere la chiave API corretta.

4. Verificare che l'inizializzazione sia riuscita. L'agente esegue automaticamente il pull delle immagini Docker necessarie quando si esegue il primo comando.

Inizializzare la modalità cluster

1. Inizializzare l'interfaccia a riga di comando dell'agente con la modalità cluster usando il comando az aks agent-init. Assicurarsi di sostituire i valori segnaposto con il nome del cluster e del gruppo di risorse effettivi.

   az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
   

2. Quando viene richiesto di selezionare una modalità di distribuzione, immettere 1 per la modalità cluster.

   🚀 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): 1
   

3. Quando viene richiesto di specificare lo spazio dei nomi di destinazione, immettere lo spazio dei nomi in cui è stato creato l'account del servizio. Nell'esempio seguente viene your-namespace utilizzato come segnaposto. Assicurati di sostituirlo con lo spazio dei nomi effettivo che hai usato.

   ✅ Cluster mode selected. This will set up the agent deployment in your cluster.
   
   Please specify the namespace where the agent will be deployed.
   
   Enter namespace (e.g., 'kube-system'): your-namespace
   

4. Configurare i dettagli del provider LLM. Per esempio:

   📦 Using namespace: your-namespace
   No existing LLM configuration found. Setting up new configuration...
   Please provide your LLM configuration. Type '/exit' to exit.
    1. Azure OpenAI
    2. OpenAI
    3. Anthropic
    4. Gemini
    5. OpenAI Compatible
    6. For other providers, see https://aka.ms/aks/agentic-cli/init
   Please choose the LLM provider (1-5): 1
   

5. Specificare i dettagli dell'account del servizio usando l'account del servizio Kubernetes creato per la distribuzione dell'agente. Nell'esempio seguente viene aks-mcp usato come segnaposto per il nome dell'account del servizio. Assicurarsi di sostituirlo con il nome effettivo dell'account del servizio.

   👤 Service Account Configuration
   The AKS agent requires a service account with appropriate permissions in the 'your-namespace'
   namespace.
   Please ensure you have created the necessary Role and RoleBinding in your namespace for 
   this service account.
   
   Enter service account name: aks-mcp
   

6. Attendere il completamento della distribuzione. L'inizializzazione distribuisce l'agente usando Helm.

   🚀 Deploying AKS agent (this typically takes less than 2 minutes)...
   ✅ AKS agent deployed successfully!
   Verifying deployment status...
   ✅ AKS agent is ready and running!
   
   🎉 Initialization completed successfully!
   

7. Verificare la corretta distribuzione e controllare lo stato dell'agente usando il az aks agent comando con il --status parametro .

   az aks agent \
   --status \
   --resource-group $RESOURCE_GROUP \
   --name $CLUSTER_NAME \
   --namespace $NAMESPACE
   

   L'output dovrebbe indicare che l'agente è pronto e operativo, simile al seguente:

   📊 Checking AKS agent status...
   
   ✅ Helm Release: deployed
   
   📦 Deployments:
     • aks-agent: 1/1 ready
     • aks-mcp: 1/1 ready
   
   🐳 Pods:
     • aks-agent-xxxxx-xxxxx: Running ✓
     • aks-mcp-xxxxx-xxxxx: Running ✓
   
   📋 LLM Configurations:
     • azure/gpt-4o
       API Base: https://your-service.openai.azure.com/
       API Version: 2025-04-01-preview
   
   ✅ AKS agent is ready and running!
   

   Annotazioni

   È anche possibile verificare la corretta distribuzione controllando i pod e le distribuzioni nello spazio dei nomi di destinazione usando kubectl:

   kubectl get pods --namespace $NAMESPACE | grep aks-
   kubectl get deployment --namespace $NAMESPACE | grep aks-
   

Di seguito sono riportati esempi di query di base che è possibile eseguire con l'interfaccia a riga di comando dell'agente per Azure Kubernetes Service (AKS) in modalità client.

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

Di seguito sono riportati esempi di query di base che si possono eseguire con l'agentic CLI per AKS in modalità cluster.

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

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

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

Pulire la distribuzione in modalità client usando il comando az aks agent-cleanup con il parametro --mode client. Questo comando rimuove il file di configurazione locale e reimposta la configurazione dell'agente.

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

Pulire la distribuzione in modalità cluster usando il comando az aks agent-cleanup. Assicurarsi di specificare il --namespace parametro con lo spazio dei nomi in cui viene distribuito l'agente. Questo comando rimuove il pod agente dallo spazio dei nomi specificato ed elimina la configurazione LLM archiviata nel cluster.

az aks agent-cleanup --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE

Verificare che il file di configurazione locale e le immagini Docker siano stati rimossi usando i comandi seguenti:

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

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

Verificare che il pod agente e le risorse correlate siano stati rimossi dal cluster utilizzando i comandi seguenti con il namespace appropriato.

# Check if agent pod was removed
kubectl get pods --namespace $NAMESPACE

# Check if service account was removed
kubectl get serviceaccount --namespace $NAMESPACE

# Check if namespace was removed (if it was created during init)
kubectl get namespace $NAMESPACE