安裝和使用 Azure Kubernetes Service （AKS）的代理程式 CLI （預覽）

本文將教你如何在客戶端模式或叢集模式下安裝、設定並使用代理式 CLI for Azure Kubernetes Service（AKS），以獲得 AI 驅動的故障排除與對 AKS 叢集的洞察。

欲了解更多資訊，請參閱 AKS 代理 CLI 概述。

這很重要

AKS 預覽功能可透過自助服務，以加入方式使用。預覽是「依現況」及「可用時」提供的，並不包括在服務等級協定和有限保固之內。客戶支援部門會盡最大努力，部分支援 AKS 預覽。因此，這些功能不適合實際執行用途。如需詳細資訊，請參閱下列支援文章：

先決條件

Azure CLI 版本 2.76 或更新。使用 az version 命令來檢查您的版本。要安裝或更新，請參見安裝 Azure CLI。
擁有大型語言模型（LLM）API 金鑰。您必須從其中一個支援的提供者攜帶自己的 API 金鑰：
- Azure OpenAI （建議）
- OpenAI 或其他與 OpenAPI 規範相容的 LLM 提供者
用這個 az account set 指令設定你的有效 Azure 訂閱。
```
az account set --subscription "your-subscription-id-or-name"
```
aks-agent Azure CLI 擴充功能 1.0.0b16 或更新版本，提供 AKS 的 Agentic CLI 功能。你可以使用 Azure CLI 安裝或更新擴充功能。

Docker 已安裝並運行於你的本機。有關安裝說明，請參見「開始使用 Docker」。
在繼續安裝前，請確保 Docker 守護程序已經啟動並運行中。
確保你的 Azure 憑證設定正確，並且擁有存取叢集資源的必要權限。

安裝前，你需要建立一個必須擁有 RBAC 權限的 Kubernetes 服務帳號。（工作負載識別設定為可選。）
你需要寫入權限才能將代理程式部署到 Kubernetes 命名空間。

安裝適用於 AKS 延伸模組的代理程式 CLI

使用指令 az extension add 安裝 AKS 擴充功能的代理式 CLI。如果擴充功能已經安裝好，你可以用這個 az extension update 指令更新到最新版本。這個步驟可能需要5到10分鐘完成。
```
# Install the extension
az extension add --name aks-agent --debug

# Update the extension
az extension update --name aks-agent --debug
```
請使用該 az extension list 指令驗證安裝成功。
```
az extension list
```
您的輸出應包含一個 aks-agent 的項目。
請使用 [az aks agent][/cli/azure/aks#az-aks-agent] 指令並以參數 --help 確認 AKS 指令的代理 CLI 是否可用。
```
az aks agent --help
```
你的輸出應該在aks-agent區塊中顯示extensions及其版本資訊。例如：
```
...
"extensions": {
"aks-agent": "1.0.0b17",
}
```

設定您的 LLM API 金鑰

在開始安裝之前，你需要先設定好你的 LLM API 金鑰。我們建議使用更新的模型，如 GPT-5 或 Claude Opus MINI ，以提升效能。請務必選取內容大小至少為 128,000 e個詞元或更高的模型。

Azure OpenAI （建議）

建立 Azure OpenAI 資源。
部署模型。部署名稱應使用與模型名稱相同的名稱，如 gpt-4o 或 gpt-4o-mini，具體取決於存取方式。您可以使用任何您擁有模型存取權和配額的區域。在部署時，請盡可能選擇每分鐘代幣（TPM）上限。我們建議 TPM 超過 100 萬 以獲得良好的效能。
部署完成後，請記錄你的 API 基礎 URL 和 API 金鑰。 API 版本不是模型版本。您可以使用 Microsoft Foundry Models v1 API 中，Azure OpenAI 所提供且支援的任何 API 版本。 Azure API 基礎指的是 Azure OpenAI 端點（通常以openai.azure.com/結尾），而非 Foundry 部署的目標 URI。

Azure OpenAI 與 Microsoft Entra ID（無密鑰驗證）

當你選擇「Azure Open AI （Microsoft Entra ID）」作為你的 LLM 提供者時，你可以使用 Microsoft Entra ID 設定無金鑰認證。有了這個選項，你就不需要提供 API 金鑰。此認證方法需要以下角色分配：

用戶端模式：本地 Azure CLI 憑證必須在 Azure OpenAI 資源中指定為 認知服務使用者 或 Azure AI 使用者 角色。
叢集模式：工作負載身份必須在 Azure OpenAI 資源上被指派為 認知服務使用者 或 Azure AI 使用者 角色。

其他大型語言模型提供者

如果你使用其他相容 OpenAI 的服務提供者，請依照他們的文件了解如何建立帳號並取得 API 金鑰的說明。

驗證 Docker 安裝並啟動 Docker 精靈

請用以下指令確認 Docker 已安裝且 Docker 守護程序是否在執行：
```
docker --version
docker ps
```
如果您收到錯誤訊息顯示 Docker 後台程序未執行，請依照您的作業系統的適當步驟來確保 Docker 服務已啟動：
- macOS / Windows：
  - 從你的應用程式啟動 Docker Desktop。
  - 等 Docker 開始。
- Linux:
  - 請使用以下指令啟動 Docker 服務：
```
sudo systemctl start docker
sudo systemctl enable docker  # Enable Docker to start on boot
```
請使用以下指令驗證 Docker 是否執行：
```
docker info
```
此指令應能無錯誤地回傳 Docker 系統資訊。

初始化用戶端模式

用 az aks agent-init 指令以 client 模式初始化 Agentic CLI。務必將佔位符值替換成你的實際資源群組和叢集名稱。
```
az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
```

當被要求選擇部署模式時，請輸入 2 以選擇用戶端模式。

🚀 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

設定您的 LLM 提供者詳細資料。例如：

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.

備註

為了安全起見，API 金鑰在你輸入時會顯示為空。務必輸入正確的 API 金鑰。

確認初始化是否成功。當你執行第一個指令時，代理程式會自動拉取所需的 Docker 映像檔。

初始化叢集模式

使用 az aks agent-init 指令以叢集模式初始化代理 CLI。務必將佔位符值替換成你的實際資源群組和叢集名稱。
```
az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
```

當被要求選擇部署模式時，請輸入 1 以選擇叢集模式。

🚀 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

當被要求指定目標命名空間時，輸入你建立服務帳號的命名空間。以下範例作為佔位符使用 your-namespace 。記得用你實際使用的命名空間替換它。

✅ 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

設定您的 LLM 提供者詳細資料。例如：

📦 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

請使用你為代理部署建立的 Kubernetes 服務帳號提供服務帳號的詳細資訊。以下範例使用 aks-mcp 作為服務帳號名稱的佔位符。務必用你服務帳號的真實名稱替換。

👤 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

等待部署完成。初始化時會使用 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!

確認部署成功，並使用 az aks agent 帶有參數 --status 的指令檢查代理的狀態。

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

你的輸出應該顯示代理已經準備好並運作，類似以下操作：

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

備註

您也可以使用 kubectl，透過檢查目標命名空間中的 Pod 和部署來驗證部署是否成功：

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

使用適用於 AKS 的代理程式 CLI

初始化後，你可以使用 AKS 的代理式 CLI 來排除叢集問題，並透過自然語言查詢獲得智慧洞察。指令語法與功能在用戶端模式與叢集模式中是相同的，除了參數--mode和--namespace之外。叢集模式是預設部署模式，所以你只需要在使用客戶端模式時指定 --mode client 。叢集模式需要指定 --namespace 代理部署的命名空間參數。

基本查詢

備註

如果您設定了多個模型，您可以使用參數 --model 指定要用於每個查詢的模型。例如： --model=azure/gpt-4o 。

以下是你可以在客戶端模式下使用 agentic CLI for AKS 執行的基本查詢範例：

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

以下是你可以在叢集模式下用 agentic CLI for AKS 執行的基本查詢範例：

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

遊戲預設使用互動模式，讓你可以保留上下文繼續提問，直到想離開為止。要離開體驗，請輸入 /exit。

指令參數

這個 az aks agent 指令有多個參數，讓你可以自訂故障排除體驗。下表說明執行查詢時可使用的關鍵參數：

參數	Description
`--max-steps`	LLM 可以採取的調查問題的步驟數上限。預設值：40。
`--mode`	模式決定代理的部署方式。允許的值： `client`、 `cluster`。預設值：`cluster`。
`--model`	指定要用於 AI 助理的 LLM 提供者和模型或部署。
`--name`、`-n`	受控叢集的名稱。 (必要項)
`--namespace`	部署 AKS 代理的 Kubernetes 命名空間。叢集模式必備。
`--no-echo-request`	停用回顯輸出中提供給 AKS 代理程式的問題。
`--no-interactive`	停用互動模式。設定時，代理程式將不會提示輸入，並將以批次模式執行。
`--refresh-toolsets`	重新整理工具集狀態。
`--resource-group`、`-g`	資源群組的名稱。 (必要項)
`--show-tool-output`	顯示每個被呼叫工具的輸出。
`--status`	顯示 AKS 代理程式設定和狀態資訊。

型號規格

此 --model 參數會決定哪個 LLM 和提供者會分析您的叢集。例如：

OpenAI：直接使用型號名稱（例如）。 gpt-4o
Azure OpenAI：使用 azure/<deployment name> （例如， azure/gpt-4o）。
Anthropic：使用 anthropic/claude-sonnet-4。

互動式指令

有一 az aks agent 組子指令，可協助疑難排解體驗。要存取這些內容，請在互動模式體驗中輸入 /。

下表描述可用的互動指令：

Command	Description
`/exit`	離開互動模式。
`/help`	顯示所有命令的說明訊息。
`/clear`	清空螢幕並重置對話上下文。
`/tools`	顯示可用的工具集及其狀態。
`/auto`	回應後切換工具輸出的顯示。
`/last`	顯示上次回應中所有工具的輸出。
`/run`	執行 Bash 指令，並可選擇性地與 LLM（大型語言模型）分享。
`/shell`	進入互動式殼層，並可選擇與 LLM 共用工作階段。
`/context`	顯示對話內容、上下文大小和標記數量。
`/show`	以可捲動的視圖顯示特定工具輸出。
`/feedback`	提供有關客服專員回應的回饋。

停用互動模式

你可以用 --no-interactive 這個旗標來關閉互動模式。例如：

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

工具

適用於 AKS 的代理式 CLI 透過工具集包含了常用監視與觀察能力工具的預建整合。有些整合會自動在 Kubernetes 上運作。其他整合則需要 API 金鑰或設定。

針對 AKS，有一些特定的工具集可協助進行疑難排解體驗。這些工具集會出現在體驗開始時的輸出中：

...
✅ 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 伺服器整合

AKS 模型情境協定（MCP）伺服器預設啟用於 AKS 代理 CLI 中。此體驗會在本機 (或於叢集模式下在叢集中) 啟動 AKS MCP 伺服器，並將其作為遙測的來源。

清理代理式 CLI 部署

用 az aks agent-cleanup 帶有 --mode client 參數的指令清理你的客戶端模式部署。此指令會移除本地設定檔並重置代理設定。

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

用指令 az aks agent-cleanup 清理你的叢集模式部署。務必指定代理部署所在命名空間的 --namespace 參數。此指令會將代理 Pod 從指定的命名空間移除，並刪除叢集中儲存的 LLM 設定。

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

確認清理成功

請使用以下指令檢查本地設定檔和 Docker 映像檔是否已被移除：

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

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

請使用以下指令及適當的命名空間，檢查代理 Pod 及相關資源是否已從叢集中移除：

# 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

移除 AKS 延伸模組的代理程式 CLI

使用命令 az extension remove 移除 AKS 延伸模組的代理程式 CLI。

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

關於 AKS 代理 CLI 的概述，請參見關於 AKS 代理 CLI。
若要針對 AKS 代理程式 CLI 的任何問題進行疑難排解，請參閱針對 AKS 的代理程式 CLI 進行疑難排解。
關於 AKS 代理式 CLI 的常見問題解答，請參閱代理式 CLI for AKS 常見問題集。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-04-01