Condividi tramite

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

Questo articolo illustra come installare, configurare e usare l'interfaccia della riga di comando agente per il servizio Azure Kubernetes in modalità client o cluster per ottenere informazioni dettagliate e risoluzione dei problemi basati sull'intelligenza artificiale per i cluster del servizio Azure Kubernetes.

Per ulteriori informazioni, consultare l'overview di Agentic CLI per AKS.

Importante

Le funzionalità di anteprima di AKS sono disponibili su base self-service, su scelta. Le anteprime vengono fornite "così come sono" e "come disponibili" e sono escluse dai contratti di servizio e dalla garanzia limitata. Le anteprime del servizio Azure Kubernetes sono parzialmente coperte dal supporto clienti con la massima diligenza possibile. Di conseguenza, queste funzionalità non sono destinate all'uso in produzione. Per altre informazioni, vedere gli articoli di supporto seguenti:

Prerequisiti

  • Interfaccia della riga di comando di Azure versione 2.76 o successiva. Verificare la versione usando il comando az version. Per installare o aggiornare, vedere Installare l'interfaccia della riga di comando di Azure.

  • Avere una chiave API LLM (Large Language Model). È necessario usare una chiave API personalizzata da uno dei provider supportati:

    • Azure OpenAI (scelta consigliata)
    • OpenAI o altri provider LLM compatibili con le specifiche OpenAPI

  • Imposta la sottoscrizione di Azure attiva usando il comando az account set.

    az account set --subscription "your-subscription-id-or-name"

  • Versione 1.0.0b16 o successiva dell'estensione CLI di Azure, che fornisce il CLI agentico per la funzionalità AKS. È possibile installare o aggiornare l'estensione usando l'interfaccia della riga di comando di Azure.

  • 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.

Installare l'interfaccia a riga di comando agentica per l'estensione di AKS

  1. Installare l'interfaccia della riga di comando (CLI) agentic per l'estensione AKS usando il comando az extension add. Se l'estensione è già installata, è possibile eseguire l'aggiornamento alla versione più recente con il az extension update comando . Il completamento di questo passaggio può richiedere da 5 a 10 minuti.

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

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

  2. Verificare che l'installazione abbia esito positivo usando il az extension list comando .

    az extension list

    L'output deve includere una voce per aks-agent.

  3. Verificare nell'interfaccia della riga di comando agentica che i comandi del servizio Azure Kubernetes siano disponibili usando il comando [az aks agent][/cli/azure/aks#az-aks-agent] con il parametro --help.

    az aks agent --help

    L'output dovrebbe mostrare aks-agent con le informazioni sulla relativa versione nella sezione extensions. Per esempio:

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

Configurare la chiave API LLM

Prima di procedere con l'installazione, è necessario configurare la chiave API LLM. È consigliabile usare modelli più recenti, ad esempio GPT-5 o Claude Opus MINI , per ottenere prestazioni migliori. Assicurarsi di selezionare un modello con dimensioni di contesto elevate di almeno 128.000 token o superiore.

  1. Creare una risorsa OpenAI di Azure.
  2. Distribuire il modello. Per il nome della distribuzione, usare lo stesso nome del modello, ad esempio gpt-4o o gpt-4o-mini, a seconda dell'accesso. È possibile usare qualsiasi area in cui si dispone dell'accesso e della quota per il modello. Nella distribuzione selezionare un limite di token al minuto (TPM) il più alto possibile. Si consiglia oltre 1 milione di TPM per buone prestazioni.
  3. Al termine della distribuzione, prendere nota dell'URL di base dell'API e della chiave API. La versione dell'API non è la versione del modello. È possibile usare qualsiasi versione dell'API disponibile e supportata in Azure OpenAI nell'API Microsoft Foundry Models v1. La base dell'API di Azure fa riferimento all'endpoint OpenAI di Azure (che in genere termina in openai.azure.com/), non all'URI di destinazione della distribuzione in Foundry.

Azure OpenAI con Microsoft Entra ID (autenticazione senza chiave)

Quando si seleziona "Azure Open AI (Microsoft Entra ID)" come provider LLM, è possibile configurare l'autenticazione senza chiave usando Microsoft Entra ID. Con questa opzione non è necessario fornire una chiave API. Questo metodo di autenticazione richiede invece le assegnazioni di ruolo seguenti:

  • Modalità client: alle credenziali dell'interfaccia della riga di comando di Azure locale deve essere assegnato il ruolo Utente di Servizi cognitivi o Utente di Intelligenza artificiale di Azure nella risorsa OpenAI di Azure.
  • Modalità cluster: all'identità del carico di lavoro deve essere assegnato il ruolo Utente di Servizi cognitivi o Utente di Intelligenza artificiale di Azure nella risorsa OpenAI di Azure.

Altri fornitori LLM

Se si usa un altro provider compatibile con OpenAI, seguire la relativa documentazione per istruzioni su come creare un account e recuperare la chiave API.

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-

Usare l'interfaccia della riga di comando agentica per il servizio Azure Kubernetes

Dopo l'inizializzazione, è possibile utilizzare l'agentic CLI per AKS per risolvere i problemi dei cluster e ottenere approfondimenti intelligenti tramite query in linguaggio naturale. La sintassi e la funzionalità dei comandi sono uguali sia per la modalità client che per la modalità cluster, ad eccezione dei --mode parametri e --namespace . La modalità cluster è la modalità di distribuzione predefinita, quindi è necessario specificare --mode client solo quando si usa la modalità client. Per la modalità cluster, è necessario specificare il --namespace parametro con lo spazio dei nomi in cui viene distribuito l'agente.

Ricerche di base

Annotazioni

Se sono configurati più modelli, è possibile specificare il modello da usare per ogni query usando il --model parametro . Ad esempio: --model=azure/gpt-4o.

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

L'esperienza usa la modalità interattiva per impostazione predefinita, quindi puoi continuare a porre domande con il contesto conservato fino a quando non vuoi uscire. Per lasciare l'esperienza, immettere /exit.

Parametri del comando

Il az aks agent comando include diversi parametri che consentono di personalizzare l'esperienza di risoluzione dei problemi. La tabella seguente descrive i parametri chiave che è possibile usare durante l'esecuzione delle query:

Parametro Descrzione
--max-steps Numero massimo di passaggi che l'LLM può eseguire per analizzare il problema. Impostazione predefinita: 40.
--mode La modalità decide come viene distribuito l'agente. Valori consentiti: client, cluster. Impostazione predefinita: cluster.
--model Specificare il provider LLM e il modello o la distribuzione da usare per l'assistente di intelligenza artificiale.
--name, -n Nome del cluster gestito. (obbligatorio).
--namespace Spazio dei nomi Kubernetes in cui viene distribuito l'agente AKS. Obbligatorio per la modalità cluster.
--no-echo-request Disabilitare la richiamata della domanda fornita all'agente del servizio Azure Kubernetes nell'output.
--no-interactive Disabilitare la modalità interattiva. Se impostato, l'agente non richiederà l'input e verrà eseguito in modalità batch.
--refresh-toolsets Aggiorna lo stato degli strumenti.
--resource-group, -g Nome del gruppo di risorse. (obbligatorio).
--show-tool-output Visualizzare l'output di ogni strumento chiamato.
--status Mostra informazioni di configurazione e stato dell'agente AKS.

Specifica del modello

Il --model parametro determina l'LLM e il provider che analizza il cluster. Per esempio:

  • OpenAI: usare direttamente il nome del modello , ad esempio gpt-4o.
  • Azure OpenAI: usare azure/<deployment name> (ad esempio, azure/gpt-4o).
  • Anthropic: usare anthropic/claude-sonnet-4.

Comandi interattivi

Il az aks agent ha un set di sottocomandi che agevolano il processo di risoluzione dei problemi. Per accedervi, immettere / all'interno dell'esperienza in modalità interattiva.

La tabella seguente descrive i comandi interattivi disponibili:

Comando Descrzione
/exit Lasciare la modalità interattiva.
/help Visualizzare i messaggi della guida con tutti i comandi.
/clear Cancellare la schermata e reimpostare il contesto della conversazione.
/tools Mostra i set di strumenti disponibili e il relativo stato.
/auto Cambiare la visualizzazione degli output degli strumenti dopo le risposte.
/last Mostra tutti gli output degli strumenti dall'ultima risposta.
/run Eseguire un comando Bash e, facoltativamente, condividerlo con LLM.
/shell Passare alla shell interattiva e quindi, facoltativamente, condividere la sessione con LLM.
/context Mostra le dimensioni del contesto della conversazione e il numero di token.
/show Mostra l'output specifico dello strumento in una visualizzazione scorrevole.
/feedback Fornire commenti e suggerimenti sulla risposta dell'agente.

Disabilitare la modalità interattiva

È possibile disabilitare la modalità interattiva usando il flag --no-interactive con il comando. Per esempio:

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

Set di strumenti

Il CLI agentico per il servizio Azure Kubernetes include integrazioni predefinite per i più diffusi strumenti di monitoraggio e osservabilità tramite toolsets. Alcune integrazioni funzionano automaticamente con Kubernetes. Altre integrazioni richiedono chiavi API o configurazione.

Per il servizio Azure Kubernetes sono disponibili set di strumenti specifici utili nel processo di risoluzione dei problemi. Questi set di strumenti vengono visualizzati nell'output all'inizio dell'esperienza:

...
✅ 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`

Integrazione del server MCP di AKS

Il server del protocollo MCP (Model Context Protocol) per il servizio Azure Kubernetes è abilitato per impostazione predefinita con l'interfaccia della riga di comando agentica per il servizio. Questa esperienza avvia localmente il server MCP di AKS (o nel cluster in modalità cluster) e lo utilizza come fonte per la telemetria.

Pulire la distribuzione dell'interfaccia della riga di comando agentica

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 la corretta pulizia

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

Rimuovere l'interfaccia della riga di comando agentica per l'estensione del servizio Azure Kubernetes

Rimuovere l'interfaccia a riga di comando agentica per l'estensione del servizio Azure Kubernetes con il comando az extension remove.

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

Contenuti correlati

  • Last updated on