Instalowanie i używanie agentycznego interfejsu wiersza poleceń dla usługi Azure Kubernetes Service (AKS) (wersja zapoznawcza)

W tym artykule pokazano, jak zainstalować, skonfigurować i użyć interfejsu wiersza polecenia agenta dla usługi Azure Kubernetes Service (AKS) w trybie klienta lub w trybie klastra , aby uzyskać oparte na sztucznej inteligencji rozwiązywanie problemów i szczegółowe informacje dotyczące klastrów usługi AKS.

Więcej informacji znajdziesz w omówieniu interfejsu wiersza polecenia Agentic dla AKS.

Ważne

Funkcje usługi AKS w wersji zapoznawczej są dostępne na zasadzie samoobsługi i wymagają zapisania się. Wersje zapoznawcze są udostępniane w wersji "as is" i "jako dostępne" i są wykluczone z umów dotyczących poziomu usług i ograniczonej gwarancji. Wersje zapoznawcze usługi AKS są częściowo objęte pomocą techniczną dla klientów, świadczoną w miarę możliwości. W związku z tym te funkcje nie są przeznaczone do użytku produkcyjnego. Aby uzyskać więcej informacji, zobacz następujące artykuły pomocy technicznej:

Wymagania wstępne

  • CLI platformy Azure w wersji 2.76 lub nowszej. Sprawdź wersję przy użyciu polecenia az version. Aby zainstalować lub zaktualizować, zobacz Instalowanie interfejsu wiersza polecenia platformy Azure.

  • Posiadać klucz API modelu językowego (LLM). Musisz wprowadzić własny klucz interfejsu API od jednego z obsługiwanych dostawców:

    • Azure OpenAI (zalecane)
    • OpenAI lub inni dostawcy LLM zgodni ze specyfikacjami interfejsu OpenAPI

  • Ustaw aktywną subskrypcję platformy Azure używając polecenia az account set.

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

  • Wersja 1.0.0b16 lub nowsza rozszerzenia CLI platformy Azure aks-agent, które udostępnia obsługę agentycznego interfejsu wiersza polecenia dla funkcji AKS. Rozszerzenie można zainstalować lub zaktualizować przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Platforma Docker została zainstalowana i uruchomiona na komputerze lokalnym. Aby uzyskać instrukcje dotyczące instalacji, zobacz Wprowadzenie do platformy Docker.
  • Przed kontynuowaniem instalacji upewnij się, że demon Dockera jest uruchomiony i działa.
  • Upewnij się, że poświadczenia platformy Azure są prawidłowo skonfigurowane i masz uprawnienia niezbędne do uzyskiwania dostępu do zasobów klastra.

Zainstaluj agentic CLI dla rozszerzenia AKS

  1. Zainstaluj agentyczny interfejs wiersza polecenia dla rozszerzenia AKS przy użyciu polecenia az extension add. Jeśli rozszerzenie jest już zainstalowane, możesz przeprowadzić aktualizację do najnowszej wersji za az extension update pomocą polecenia . Wykonanie tego kroku może potrwać od 5 do 10 minut.

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

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

  2. Sprawdź pomyślną instalację za pomocą polecenia az extension list.

    az extension list

    Dane wyjściowe powinny zawierać wpis dla aks-agent.

  3. Sprawdź, czy agentowy interfejs wiersza poleceń dla poleceń AKS jest dostępny przy użyciu polecenia [az aks agent][/cli/azure/aks#az-aks-agent] z parametrem --help.

    az aks agent --help

    Wynik powinien pokazywać aks-agent z jego informacjami o wersji w sekcji extensions. Przykład:

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

Konfigurowanie klucza interfejsu API LLM

Przed kontynuowaniem instalacji należy skonfigurować klucz interfejsu API LLM. Zalecamy używanie nowszych modeli, takich jak GPT-5 lub Claude Opus MINI , aby uzyskać lepszą wydajność. Upewnij się, że wybrano model o wysokiej wielkości kontekstu, co najmniej 128 000 tokenów lub więcej.

  1. Utwórz zasób usługi Azure OpenAI.
  2. Wdróż model. W przypadku nazwy wdrożenia użyj tej samej nazwy co nazwa modelu, na przykład gpt-4o lub gpt-4o-mini, w zależności od dostępu. Możesz użyć dowolnego regionu, w którym masz dostęp i limit zasobów dla modelu. We wdrożeniu wybierz możliwie najwyższy limit tokenu na minutę (TPM). Zalecamy używanie ponad 1 miliona TPM dla dobrej wydajności.
  3. Po zakończeniu wdrażania zanotuj podstawowy adres URL interfejsu API i klucz interfejsu API. Wersja interfejsu API nie jest wersją modelu. Możesz użyć dowolnej dostępnej i obsługiwanej wersji API w Azure OpenAI w Microsoft Foundry Models API v1. Podstawowy interfejs API platformy Azure odnosi się do punktu końcowego usługi Azure OpenAI (który zwykle kończy się na openai.azure.com/), a nie do docelowego identyfikatora URI wdrożenia w systemie Foundry.

Azure OpenAI z identyfikatorem Entra firmy Microsoft (uwierzytelnianie bez klucza)

Po wybraniu pozycji "Azure Open AI (Microsoft Entra ID)" jako dostawcy LLM możesz skonfigurować uwierzytelnianie bez klucza przy użyciu identyfikatora Entra firmy Microsoft. W przypadku tej opcji nie musisz podawać klucza interfejsu API. Zamiast tego ta metoda uwierzytelniania wymaga następujących przypisań ról:

  • Tryb klienta: lokalne poświadczenia Azure CLI muszą być przypisane do roli Cognitive Services User lub Azure AI User w zasobie Azure OpenAI.
  • Tryb klastra: tożsamość obciążenia musi mieć przypisaną rolę Użytkownika usług Cognitive Services lub Użytkownika usługi Azure AI w zasobie Azure OpenAI.

Inni dostawcy LLM

Jeśli używasz innego dostawcy zgodnego z platformą OpenAI, postępuj zgodnie z ich dokumentacją, aby uzyskać instrukcje dotyczące sposobu tworzenia konta i pobierania klucza interfejsu API.

Weryfikowanie instalacji platformy Docker i uruchamianie demona platformy Docker

  1. Sprawdź, czy Docker jest zainstalowany, a usługa Docker jest uruchomiona przy użyciu następujących poleceń:

    docker --version
docker ps

  2. Jeśli otrzymasz komunikat o błędzie wskazujący, że demon Docker nie jest uruchomiony, uruchom usługę Docker, wykonując odpowiednie kroki dla Twojego systemu operacyjnego:

    • macOS/Windows:

      • Uruchom aplikację Docker Desktop z poziomu aplikacji.
      • Poczekaj na uruchomienie platformy Docker.

    • Linux:

      • Uruchom usługę Platformy Docker przy użyciu następujących poleceń:

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

  3. Sprawdź, czy platforma Docker jest uruchomiona przy użyciu następującego polecenia:

    docker info

    To polecenie powinno zwracać informacje o systemie platformy Docker bez błędów.

Inicjowanie trybu klienta

  1. Zainicjuj interfejs wiersza polecenia agentic w trybie klienta poleceniem az aks agent-init. Pamiętaj, aby zastąpić wartości symboli zastępczych rzeczywistą grupą zasobów i nazwą klastra.

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

  2. Po wyświetleniu monitu o wybranie trybu wdrożenia wprowadź 2 dla trybu klienta.

    🚀 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. Skonfiguruj ustawienia dostawcy LLM. Przykład:

    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.

    Uwaga / Notatka

    Klucz API jest niewidoczny podczas wpisywania ze względów bezpieczeństwa. Upewnij się, że wprowadzono prawidłowy klucz interfejsu API.

  4. Sprawdź, czy inicjowanie zakończyło się pomyślnie. Agent automatycznie ściąga niezbędne obrazy Docker podczas uruchamiania pierwszego polecenia.

Inicjowanie trybu klastra

  1. Zainicjuj agenta CLI w trybie klastra za pomocą polecenia az aks agent-init. Pamiętaj, aby zastąpić wartości symboli zastępczych rzeczywistą grupą zasobów i nazwą klastra.

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

  2. Po wyświetleniu monitu o wybranie trybu wdrożenia wprowadź 1 dla trybu klastra.

    🚀 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 wyświetleniu monitu o określenie docelowej przestrzeni nazw wprowadź przestrzeń nazw, w której utworzono konto usługi. W poniższym przykładzie użyto your-namespace jako symbolu zastępczego. Upewnij się, że zastąpiłeś ją rzeczywistą przestrzenią nazw, której użyłeś.

    ✅ 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. Skonfiguruj ustawienia dostawcy LLM. Przykład:

    📦 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. Podaj szczegóły konta usługi przy użyciu konta usługi Kubernetes utworzonego na potrzeby wdrożenia agenta. W poniższym przykładzie aks-mcp użyto jako symbolu zastępczego nazwy konta usługi. Pamiętaj, aby zastąpić ją rzeczywistą nazwą konta usługi.

    👤 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. Poczekaj na ukończenie wdrożenia. Inicjalizacja wdraża agenta przy użyciu programu 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. Sprawdź pomyślne wdrożenie i sprawdź stan agenta przy użyciu az aks agent polecenia z parametrem --status .

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

    Dane wyjściowe powinny wskazywać, że agent jest gotowy i uruchomiony, podobnie jak poniżej:

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

    Uwaga / Notatka

    Można również zweryfikować pomyślne wdrożenie, sprawdzając pody i wdrożenia w docelowej przestrzeni nazw, posługując się poleceniem kubectl.

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

Używanie interfejsu wiersza polecenia agenta dla usługi AKS

Po zainicjowaniu można użyć agentowego interfejsu wiersza polecenia dla AKS do rozwiązywania problemów z klastrami i uzyskiwania inteligentnych spostrzeżeń przy użyciu zapytań w języku naturalnym. Składnia poleceń i funkcjonalność są takie same zarówno w trybie klienta, jak i w trybie klastra, z wyjątkiem parametrów --mode i --namespace. Tryb klastra jest domyślnym trybem wdrażania, dlatego należy określić --mode client tylko podczas korzystania z trybu klienta. W przypadku trybu klastra należy określić --namespace parametr z przestrzenią nazw, w której wdrożono agenta.

Zapytania podstawowe

Uwaga / Notatka

Jeśli skonfigurowano wiele modeli, możesz określić model do użycia dla każdego zapytania przy użyciu parametru --model . Na przykład --model=azure/gpt-4o.

Poniżej przedstawiono przykłady podstawowych zapytań, które można uruchomić za pomocą agentowego interfejsu wiersza polecenia dla AKS w trybie 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

Poniżej przedstawiono przykłady podstawowych zapytań, które można uruchomić za pomocą agenty CLI dla AKS w trybie klastrowym:

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

Środowisko domyślnie używa trybu interaktywnego, więc możesz nadal zadawać pytania z zachowanym kontekstem, dopóki nie zechcesz zakończyć sesji. Aby opuścić doświadczenie, wpisz /exit.

Parametry polecenia

Polecenie az aks agent ma kilka parametrów, które umożliwiają dostosowanie środowiska rozwiązywania problemów. W poniższej tabeli opisano kluczowe parametry, których można użyć podczas uruchamiania zapytań:

Parametr Opis
--max-steps Maksymalna liczba kroków, które może wykonać LLM, aby zbadać problem. Wartość domyślna: 40.
--mode Tryb decyduje o sposobie wdrażania agenta. Dozwolone wartości: client, cluster. Wartość domyślna: cluster.
--model Określ dostawcę usługi LLM i model lub wdrożenie, które ma być używane dla asystenta sztucznej inteligencji.
--name, -n Nazwa klastra zarządzanego. (Wymagane)
--namespace Przestrzeń nazw Kubernetes, w której wdrożono agenta AKS. Wymagany dla trybu klastra.
--no-echo-request Wyłącz powtórzenie pytania dostarczonego do agenta usługi AKS w danych wyjściowych.
--no-interactive Wyłącz tryb interaktywny. Po ustawieniu agent nie wyświetli monitu o dane wejściowe i zostanie uruchomiony w trybie wsadowym.
--refresh-toolsets Odśwież stan zestawów narzędzi.
--resource-group, -g Nazwa grupy zasobów. (Wymagane)
--show-tool-output Pokaż dane wyjściowe każdego wywoływanego narzędzia.
--status Pokaż informacje o konfiguracji i stanie agenta usługi AKS.

Specyfikacja modelu

Parametr --model określa, który model LLM i dostawca analizuje klaster. Przykład:

  • OpenAI: użyj nazwy modelu bezpośrednio (na przykład gpt-4o).
  • Azure OpenAI: Użyj azure/<deployment name> (na przykład azure/gpt-4o).
  • Anthropic: użyj anthropic/claude-sonnet-4.

Polecenia interakcyjne

Zawiera az aks agent zestaw podpoleceń, które ułatwiają rozwiązywanie problemów. Aby uzyskać do nich dostęp, wprowadź / w środowisku trybu interaktywnego.

W poniższej tabeli opisano dostępne polecenia interaktywne:

Command Opis
/exit Pozostaw tryb interaktywny.
/help Pokaż komunikaty pomocy ze wszystkimi poleceniami.
/clear Wyczyść ekran i zresetuj kontekst konwersacji.
/tools Pokaż dostępne zestawy narzędzi i ich stan.
/auto Przełącz wyświetlanie danych wyjściowych narzędzia po odpowiedziach.
/last Pokaż wszystkie dane wyjściowe narzędzia z ostatniej odpowiedzi.
/run Uruchom polecenie Bash i opcjonalnie udostępnij je modelowi językowemu LLM.
/shell Przejdź do interaktywnej powłoki, a następnie opcjonalnie udostępnij sesję usłudze LLM.
/context Pokaż rozmiar kontekstu konwersacji i liczbę tokenów.
/show Pokaż dane wyjściowe określonego narzędzia w widoku z możliwością przewijania.
/feedback Prześlij opinię na temat odpowiedzi agenta.

Wyłączanie trybu interaktywnego

Tryb interaktywny można wyłączyć przy użyciu flagi --no-interactive za pomocą polecenia . Przykład:

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

Zestawy narzędzi

Interfejs wiersza polecenia agenta dla usługi AKS obejmuje wstępnie utworzone integracje na potrzeby popularnych narzędzi do monitorowania i obserwacji za pomocą zestawów narzędzi. Niektóre integracje działają automatycznie z platformą Kubernetes. Inne integracje wymagają kluczy interfejsu API lub konfiguracji.

W przypadku usługi AKS istnieją określone zestawy narzędzi, które ułatwiają rozwiązywanie problemów. Te zestawy narzędziowe pojawiają się w wynikach na początku działania.

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

Integracja serwera AKS MCP

Serwer protokołu kontekstu modelu AKS (MCP) jest domyślnie włączony z CLI agenta dla AKS. To środowisko uruchamia serwer MCP usługi AKS lokalnie (lub w klastrze w trybie klastra) i używa go jako źródła danych telemetrycznych.

Poprawa wdrożenia agentycznego CLI

Wyczyść wdrożenie trybu klienta, korzystając z polecenia az aks agent-cleanup i parametru --mode client. To polecenie usuwa lokalny plik konfiguracji i resetuje konfigurację agenta.

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

Wyczyść wdrożenie w trybie klastra, używając polecenia az aks agent-cleanup. Upewnij się, że określono --namespace parametr z przestrzenią nazw, w której wdrożono agenta. To polecenie usuwa pod agenta z określonej przestrzeni nazw i kasuje konfigurację LLM przechowywaną w klastrze.

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

Weryfikowanie pomyślnego czyszczenia

Sprawdź, czy lokalny plik konfiguracji i obrazy platformy Docker zostały usunięte przy użyciu następujących poleceń:

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

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

Sprawdź, czy pod agenta i powiązane zasoby zostały usunięte z klastra przy użyciu następujących poleceń z odpowiednią przestrzenią nazw.

# 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

Usuń agentyczny interfejs wiersza polecenia dla rozszerzenia AKS

Usuń interfejs wiersza poleceń agentu rozszerzenia AKS za pomocą polecenia az extension remove.

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

Treści powiązane

  • Last updated on