Instalace a použití agentního rozhraní příkazového řádku pro Azure Kubernetes Service (AKS) (náhled)

V tomto článku se dozvíte, jak nainstalovat, nakonfigurovat a používat agentské rozhraní příkazového řádku pro Azure Kubernetes Service (AKS) v režimu klienta nebo v režimu clusteru , abyste získali přehledy a řešení potíží s AI pro clustery AKS.

Další informace najdete v přehledu Agentic CLI pro AKS.

Důležité

Funkce AKS ve verzi Preview jsou k dispozici na bázi samoobsluhy a dobrovolného přihlášení. Ukázky jsou poskytovány "jak jsou" a "podle aktuální dostupnosti" a jsou vyloučené ze smluv o úrovni služeb a omezené záruky. Předběžné verze AKS jsou částečně pokryty zákaznickou podporou podle možností. Proto tyto funkce nejsou určené pro produkční použití. Další informace najdete v následujících článcích podpory:

Předpoklady

  • Azure CLI verze 2.76 nebo novější Pomocí příkazu zkontrolujte svoji verzi az version . Pokud chcete nainstalovat nebo aktualizovat, přečtěte si téma Instalace Azure CLI.

  • Mít klíč API pro velký jazykový model (LLM). Musíte použít vlastní klíč rozhraní API od některého z podporovaných poskytovatelů:

    • Azure OpenAI (doporučeno)
    • OpenAI nebo jiní poskytovatelé LLM kompatibilní se specifikacemi OpenAPI

  • Nastavte aktivní předplatné Azure pomocí příkazu az account set .

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

  • Verze 1.0.0b16 nebo novější rozšíření Azure CLI, která poskytuje agentské rozhraní příkazového aks-agent řádku pro funkce AKS. Rozšíření můžete nainstalovat nebo aktualizovat pomocí Azure CLI.

  • Docker je nainstalovaný a spuštěný na místním počítači. Pokyny k instalaci najdete v tématu Začínáme s Dockerem.
  • Než budete pokračovat v instalaci, ujistěte se, že je Docker démon spuštěný a běží.
  • Ujistěte se, že jsou vaše přihlašovací údaje Azure správně nakonfigurované a máte potřebná oprávnění pro přístup k prostředkům clusteru.

Nainstalujte agentic CLI pro rozšíření AKS

  1. Nainstalujte agentic CLI pro rozšíření AKS pomocí příkazu az extension add. Pokud už je rozšíření nainstalované, můžete ho az extension update pomocí příkazu aktualizovat na nejnovější verzi. Dokončení tohoto kroku může trvat 5 až 10 minut.

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

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

  2. Pomocí příkazu ověřte úspěšnou az extension list instalaci.

    az extension list

    Výstup by měl obsahovat položku pro aks-agent.

  3. Pomocí příkazu [az aks agent][/cli/azure/aks#az-aks-agent] s parametrem --help ověřte dostupnost agentického rozhraní příkazového řádku pro AKS.

    az aks agent --help

    Výstup by měl zobrazit aks-agent s informacemi o verzi v oddílu extensions. Například:

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

Nastavení klíče rozhraní LLM API

Než budete pokračovat v instalaci, musíte nastavit klíč rozhraní LLM API. Pro lepší výkon doporučujeme používat novější modely, jako je GPT-5 nebo Claude Opus MINI . Nezapomeňte vybrat model s vysokou velikostí kontextu nejméně 128 000 tokenů nebo vyšších.

  1. Vytvořte prostředek Azure OpenAI.
  2. Nasaďte model. Pro název nasazení použijte stejný název jako název modelu, například gpt-4o nebo gpt-4o-mini v závislosti na přístupu. Můžete použít libovolnou oblast, ve které máte přístup a kvótu modelu. V nasazení vyberte maximální limit tokenu za minutu (TPM). Pro dosažení dobrého výkonu doporučujeme více než 1 milion TPM.
  3. Po dokončení nasazení si poznamenejte základní adresu URL rozhraní API a klíč rozhraní API. Verze rozhraní API není verzí modelu. V rozhraní API Microsoft Foundry Models v1 můžete použít libovolnou dostupnou a podporovanou verzi rozhraní API Azure OpenAI. Základní adresa Azure API se vztahuje na koncový bod Azure OpenAI (který obvykle končí openai.azure.com/), nikoli na cílový URI pro nasazení ve Foundry.

Azure OpenAI s ID Microsoft Entra (ověřování bez klíčů)

Když jako poskytovatele LLM vyberete Azure Open AI (Microsoft Entra ID), můžete nakonfigurovat ověřování bez klíčů pomocí Microsoft Entra ID. S touto možností nemusíte zadávat klíč rozhraní API. Místo toho tato metoda ověřování vyžaduje následující přiřazení rolí:

  • Režim klienta: Místní přihlašovací údaje Azure CLI musí být přiřazeny roli uživatele služeb Cognitive Services nebo uživatele Azure AI v prostředku Azure OpenAI.
  • Režim clusteru: Identitě úlohy musí být přiřazena role uživatele služeb Cognitive Services nebo uživatele Azure AI v prostředku Azure OpenAI.

Další poskytovatelé LLM

Pokud používáte jiného zprostředkovatele kompatibilního s OpenAI, postupujte podle jeho dokumentace a zjistěte, jak vytvořit účet a načíst klíč rozhraní API.

Ověření instalace Dockeru a spuštění démona Dockeru

  1. Pomocí následujících příkazů ověřte, že je nainstalovaný Docker a proces démon Dockeru běží:

    docker --version
docker ps

  2. Pokud se zobrazí chyba oznamující, že proces démon Dockeru není spuštěný, spusťte službu Docker pomocí příslušných kroků pro váš operační systém:

    • macOS / Windows:

      • Spusťte Docker Desktop z vašich aplikací.
      • Počkejte na spuštění Dockeru.

    • Linux:

      • Spusťte službu Docker pomocí následujících příkazů:

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

  3. Pomocí následujícího příkazu ověřte, že docker běží:

    docker info

    Tento příkaz by měl vrátit systémové informace Dockeru bez chyb.

Inicializace režimu klienta

  1. Inicializace agentického rozhraní příkazového řádku pomocí režimu klienta pomocí az aks agent-init příkazu Nezapomeňte nahradit zástupné hodnoty vaším skutečným názvem skupiny prostředků a názvem clusteru.

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

  2. Po zobrazení výzvy k výběru režimu nasazení zadejte 2 pro klientský režim.

    🚀 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. Nakonfigurujte podrobnosti o poskytovateli LLM. Například:

    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.

    Poznámka:

    Klíč rozhraní API se během psaní jeví jako prázdný z důvodu zabezpečení. Nezapomeňte zadat správný klíč rozhraní API.

  4. Ověřte, že inicializace proběhla úspěšně. Agent automaticky načítá potřebné image Dockeru při spuštění prvního příkazu.

Inicializace režimu clusteru

  1. Inicializujte CLI agenta v režimu clusteru pomocí příkazu az aks agent-init. Nezapomeňte nahradit zástupné hodnoty vaším skutečným názvem skupiny prostředků a názvem clusteru.

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

  2. Po zobrazení výzvy k výběru režimu nasazení zadejte 1 pro režim clusteru.

    🚀 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. Po zobrazení výzvy k zadání cílového oboru názvů zadejte obor názvů, ve kterém jste vytvořili účet služby. Následující příklad používá your-namespace jako zástupný symbol. Nezapomeňte ho nahradit skutečným oborem názvů, který jste použili.

    ✅ 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. Nakonfigurujte podrobnosti o poskytovateli LLM. Například:

    📦 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. Zadejte podrobnosti o účtu služby pomocí účtu služby Kubernetes, který jste vytvořili pro nasazení agenta. Následující příklad používá aks-mcp jako zástupný symbol názvu účtu služby. Nezapomeňte ho nahradit skutečným názvem vašeho účtu služby.

    👤 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. Počkejte na dokončení nasazení. Inicializace nasadí agenta pomocí nástroje 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. Pomocí příkazu s az aks agent parametrem ověřte úspěšné nasazení a zkontrolujte stav agenta --status .

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

    Výstup by měl znamenat, že agent je připravený a spuštěný, podobně jako v následujícím příkladu:

    📊 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!

    Poznámka:

    Úspěšné nasazení můžete ověřit také kontrolou podů a nasazení v cílovém oboru názvů pomocí kubectl:

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

Použití rozhraní příkazového řádku CLI pro AKS

Po inicializaci můžete pomocí agentického rozhraní příkazového řádku pro AKS řešit potíže s clustery a získat inteligentní přehledy pomocí dotazů v přirozeném jazyce. Syntaxe příkazů a funkce jsou stejné pro klientský režim i režim clusteru, s výjimkou parametrů --mode a --namespace. Režim clusteru je výchozím režimem nasazení, takže při použití klientského režimu je nutné zadat --mode client pouze režim nasazení. V režimu clusteru --namespace je potřeba zadat parametr s oborem názvů, ve kterém je agent nasazen.

Základní dotazy

Poznámka:

Pokud máte nastavených více modelů, můžete určit model, který se má použít pro každý dotaz pomocí parametru --model . Například: --model=azure/gpt-4o.

Tady jsou příklady základních dotazů, které můžete spustit pomocí agentického rozhraní příkazového řádku pro AKS v režimu klienta:

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

Tady jsou příklady základních dotazů, které můžete spustit pomocí agentického rozhraní příkazového řádku pro AKS v režimu clusteru:

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

Prostředí ve výchozím nastavení používá interaktivní režim, takže můžete pokračovat v kladení otázek se zachováním kontextu, dokud nechcete odejít. Pokud chcete prostředí opustit, zadejte /exit.

Parametry příkazu

Příkaz az aks agent má několik parametrů, které umožňují přizpůsobit prostředí pro řešení potíží. Následující tabulka popisuje klíčové parametry, které můžete použít při spouštění dotazů:

Parameter Description
--max-steps Maximální počet kroků, které může LLM provést k prozkoumání problému. Výchozí hodnota: 40.
--mode Režim určuje, jak se agent nasadí. Povolené hodnoty: client, cluster. Výchozí hodnota: cluster.
--model Zadejte zprostředkovatele LLM a model nebo nasazení, které se mají použít pro pomocníka s AI.
--name, -n Název spravovaného clusteru (Požadováno)
--namespace Namespace Kubernetes, ve kterém je nasazen agent AKS. Vyžaduje se pro režim clusteru.
--no-echo-request Ve výstupu zakažte opakování otázky poskytnuté agentu AKS.
--no-interactive Zakažte interaktivní režim. Při nastavení agent nezobrazí výzvu k zadání vstupu a spustí se v dávkovém režimu.
--refresh-toolsets Aktualizujte stav sad nástrojů.
--resource-group, -g Název skupiny prostředků. (Požadováno)
--show-tool-output Zobrazí výstup každého volaného nástroje.
--status Zobrazení informací o konfiguraci a stavu agenta AKS

Specifikace modelu

Parametr --model určuje, který LLM a poskytovatel analyzuje váš cluster. Například:

  • OpenAI: Použijte přímo název modelu (například gpt-4o).
  • Azure OpenAI: Použijte azure/<deployment name> (například azure/gpt-4o).
  • Anthropic: Použijte anthropic/claude-sonnet-4.

Interaktivní příkazy

Obsahuje az aks agent sadu dílčích příkazů, které pomáhají s řešením potíží. Chcete-li k nim přistoupit, zadejte / v rámci interaktivního režimu.

Následující tabulka popisuje dostupné interaktivní příkazy:

Command Description
/exit Nechte interaktivní režim.
/help Umožňuje zobrazit zprávy nápovědy se všemi příkazy.
/clear Vymažte obrazovku a obnovte kontext konverzace.
/tools Zobrazí dostupné sady nástrojů a jejich stav.
/auto Po odpovědích přepněte zobrazení výstupů nástrojů.
/last Zobrazí všechny výstupy nástroje z poslední odpovědi.
/run Spusťte příkaz Bash a volitelně ho sdílejte s LLM.
/shell Přejděte do interaktivního prostředí a pak volitelně sdílejte relaci s LLM.
/context Zobrazí velikost kontextu konverzace a počet tokenů.
/show Zobrazení konkrétního výstupu nástroje v posuvném zobrazení
/feedback Poskytněte zpětnou vazbu k odpovědi agenta.

Zakázání interaktivního režimu

Interaktivní režim můžete zakázat pomocí příznaku --no-interactive s příkazem. Například:

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

Nástrojové sady

Agentické rozhraní příkazového řádku pro AKS zahrnuje předem připravené integrace pro oblíbené nástroje pro monitorování a pozorovatelnost prostřednictvím sad nástrojů. Některé integrace fungují automaticky s Kubernetes. Jiné integrace vyžadují klíče rozhraní API nebo konfiguraci.

Pro AKS existují konkrétní sady nástrojů, které vám pomůžou s řešením potíží. Tyto sady nástrojů se zobrazí ve výstupu na začátku prostředí:

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

Integrace serveru AKS MCP

Server AKS Model Context Protocol (MCP) je ve výchozím nastavení povolený pomocí agentického rozhraní příkazového řádku pro AKS. Tento proces spouští server AKS MCP místně (nebo v clusteru v režimu clusteru) a používá jej jako zdroj telemetrie.

Vyčištění nasazení rozhraní příkazového řádku agenta

Vyčistěte nasazení v režimu klienta pomocí příkazu az aks agent-cleanup s parametrem --mode client. Tento příkaz odebere místní konfigurační soubor a resetuje konfiguraci agenta.

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

Nasazení v režimu clusteru můžete vyčistit pomocí příkazu az aks agent-cleanup. Nezapomeňte zadat parametr --namespace s oborem názvů, ve kterém je agent nasazen. Tento příkaz odebere pod agenta ze zadaného jmenného prostoru a odstraní konfiguraci LLM uloženou v klastru.

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

Ověření úspěšného vyčištění

Pomocí následujících příkazů zkontrolujte, jestli se místní konfigurační soubor a image Dockeru odebraly:

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

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

Pomocí následujících příkazů s příslušným oborem názvů zkontrolujte, že pod agenta a související prostředky byly z clusteru odebrány:

# 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

Odebrání autonomního rozhraní příkazového řádku pro rozšíření AKS

Pomocí příkazu odeberte agentické rozhraní příkazového řádku pro rozšíření az extension remove AKS.

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

Související obsah

  • Poslední aktualizace v