Azure Kubernetes Service (AKS) 用のエージェント CLI をインストールして使用する (プレビュー)

この記事では、クライアントモードまたはクラスターモードで Azure Kubernetes Service (AKS) のエージェント CLI をインストール、構成、および使用して、AKS クラスターの AI を利用したトラブルシューティングと分析情報を取得する方法について説明します。

詳細については、 AKS の Agentic CLI の概要を参照してください。

Important

AKS のプレビュー機能は、セルフサービスのオプトイン単位で利用できます。プレビューは、"現状有姿のまま" および "利用可能な限度" で提供され、サービスレベルアグリーメントおよび限定保証から除外されるものとします。 AKS プレビューは、ベストエフォートベースでカスタマーサポートによって部分的にカバーされます。そのため、これらの機能は運用環境での使用を目的としていません。詳細については、次のサポート記事を参照してください。

[前提条件]

Azure CLI バージョン 2.76 以降。 az version コマンドを使用してバージョンを確認します。インストールまたは更新するには、 Azure CLI のインストールに関するページを参照してください。
大規模言語モデル (LLM) API キーを持っている。サポートされているプロバイダーの 1 つから独自の API キーを持ち込む必要があります。
- Azure OpenAI (推奨)
- OpenAPI 仕様と互換性のある OpenAI または他の LLM プロバイダー
az account set コマンドを使用して、アクティブな Azure サブスクリプションを設定します。
```
az account set --subscription "your-subscription-id-or-name"
```
aks-agent Azure CLI 拡張機能のバージョン 1.0.0b16 以降。AKS 機能用のエージェント CLI が提供されます。 Azure CLI を使用して拡張機能をインストールまたは更新できます。

Docker がローカルコンピューターにインストールされ、実行されている。インストール手順については、「 Docker の概要」を参照してください。
インストールを続行する前に、Docker デーモンが起動して実行されていることを確認します。
Azure 資格情報が正しく構成されていること、およびクラスターリソースにアクセスするために必要なアクセス許可があることを確認します。

インストールする前に、 RBAC アクセス許可を持つ必要な Kubernetes サービスアカウントを作成する必要があります。 (ワークロード ID のセットアップは省略可能です)。
エージェントをデプロイする Kubernetes 名前空間にデプロイするには、書き込みアクセス権が必要です。

AKS 拡張機能用の agentic CLI をインストールする

az extension add コマンドを使用して、AKS 拡張機能用の agentic 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 トークン以上のモデルを選択してください。

Azure OpenAI (推奨)

Azure OpenAI リソースを作成します。
モデルをデプロイします。デプロイ名には、アクセスに応じて、gpt-4o や gpt-4o-mini などのモデル名と同じ名前を使用します。モデルのアクセス権とクォータがある任意のリージョンを使用できます。デプロイで、可能な限り高い 1 分あたりのトークン (TPM) の制限を選択します。良好なパフォーマンスのためには、100 万台以上の TPM をお勧めします。
デプロイが完了したら、API ベース URL と API キーを書き留めます。 API バージョンはモデルバージョンではありません。 Microsoft Foundry Models v1 API の Azure OpenAI で使用可能でサポートされている任意の API バージョンを使用できます。 Azure API ベースは、Foundry のデプロイのターゲット URI ではなく、Azure OpenAI エンドポイント (通常は openai.azure.com/ で終わる) を指します。

Azure OpenAI と Microsoft Entra ID (キーレス認証)

LLM プロバイダーとして "Azure Open AI (Microsoft Entra ID)" を選択すると、Microsoft Entra ID を使用してキーレス認証を構成できます。このオプションでは、API キーを指定する必要はありません。代わりに、この認証方法には次のロールの割り当てが必要です。

クライアントモード: ローカルの Azure CLI 資格情報には、Azure OpenAI リソースの Cognitive Services ユーザー ロールまたは Azure AI ユーザー ロールが割り当てられている必要があります。
クラスターモード: ワークロードアイデンティティには、Azure OpenAI リソースに対して Cognitive Services User または Azure AI User のロールが割り当てられている必要があります。

その他の LLM プロバイダー

別の 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 コマンドを使用して、クライアントモードでエージェント 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を使用して、ターゲット名前空間のポッドとデプロイを確認して、デプロイが成功したことを確認することもできます。

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 」のように入力します。

クライアントモードで AKS のエージェント CLI を使用して実行できる基本的なクエリの例を次に示します。

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

クラスターモードで AKS のエージェント CLI を使用して実行できる基本的なクエリの例を次に示します。

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/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 向けの Agentic 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 パラメーターを指定してください。このコマンドは、指定された名前空間からエージェントポッドを削除し、クラスターに格納されている 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

適切な名前空間で次のコマンドを使用して、エージェントポッドと関連リソースがクラスターから削除されたことを確認します。

# 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 に関する一般的な質問への回答については、 AKS の Agentic CLI に関する FAQ を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-28