AKS(Azure Kubernetes Service)용 에이전트 CLI 설치 및 사용(미리 보기)

이 문서에서는 AKS(Azure Kubernetes Service)용 에이전트 CLI를 클라이언트 모드 또는 클러스터 모드 에서 설치, 구성 및 사용하여 AKS 클러스터에 대한 AI 기반 문제 해결 및 인사이트를 얻는 방법을 보여 줍니다.

자세한 내용은 AKS용 에이전트 CLI 개요를 참조하세요.

중요합니다

AKS 미리 보기 기능은 셀프 서비스에서 사용할 수 있습니다(옵트인 방식). 미리 보기는 "있는 그대로" 및 "사용 가능한 상태로" 제공되며 서비스 수준 계약 및 제한적 보증에서 제외됩니다. AKS 미리 보기의 일부는 고객 지원팀에서 최선을 다해 지원합니다. 따라서 이러한 기능은 프로덕션 용도로 사용할 수 없습니다. 자세한 내용은 다음 지원 문서를 참조하세요.

• AKS 지원 정책
• Azure 지원 FAQ

필수 조건

• Azure CLI 버전 2.76 이상. az version 명령을 사용하여 버전을 확인합니다. 설치 또는 업데이트하려면 Azure CLI 설치를 참조하세요.

• LLM(대규모 언어 모델) API 키가 있습니다. 지원되는 공급자 중 하나에서 사용자 고유의 API 키를 가져와야 합니다.

  • Azure OpenAI(권장)
  • OpenAPI 사양과 호환되는 OpenAI 또는 기타 LLM 공급자

• 활성 Azure 구독을 az account set 명령을 사용하여 설정합니다.

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

• AKS 기능에 대한 에이전트 CLI를 제공하는 Azure CLI 확장 버전 aks-agent 1.0.0b16 이상 Azure CLI를 사용하여 확장을 설치하거나 업데이트할 수 있습니다.

• 로컬 컴퓨터에 Docker가 설치되고 실행됩니다. 설치 지침은 Docker 시작을 참조하세요.
• 설치를 계속하기 전에 Docker 디먼이 시작되고 실행 중인지 확인합니다.
• Azure 자격 증명이 제대로 구성되어 있고 클러스터 리소스에 액세스하는 데 필요한 권한이 있는지 확인합니다.

• 설치하기 전에 RBAC 권한이 있는 필수 Kubernetes 서비스 계정을 만들어야 합니다. (워크로드 ID 설정은 선택 사항입니다.)
• 에이전트가 배포될 Kubernetes 네임스페이스에 배포하려면 쓰기 권한이 필요합니다.

AKS 확장용 에이전트 CLI 설치

1. 명령을 사용하여 AKS 확장용 에이전트 CLI를 설치합니다 az extension add . 확장이 이미 설치된 경우 명령을 사용하여 최신 버전으로 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
   

2. 명령을 사용하여 설치에 성공했는지 확인합니다 az extension list .

   az extension list
   

   출력에 aks-agent항목이 포함되어야 합니다.

3. 에이전트 CLI가 AKS 명령에 대해 사용 가능한지 확인하려면 az aks agent 명령에 --help 매개 변수를 사용하여 [/cli/azure/aks#az-aks-agent]를 실행하세요.

   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(권장)

1. Azure OpenAI 리소스를 만듭니다.
2. 모델을 배포합니다. 배포 이름의 경우 액세스에 따라 gpt-4o 또는 gpt-4o-mini와 같은 모델 이름과 동일한 이름을 사용합니다. 모델에 대한 액세스 및 할당량이 있는 모든 지역을 사용할 수 있습니다. 배포에서 가능한 한 높은 TPM(분당 토큰) 제한을 선택합니다. 좋은 성능을 위해 100만 TPM 이상을 권장합니다.
3. 배포가 완료되면 API 기본 URL 및 API 키를 기록해 둡니다. API 버전은 모델 버전이 아닙니다. Microsoft Foundry Models v1 API의 Azure OpenAI에서 사용 가능하고 지원되는 모든 API 버전을 사용할 수 있습니다. Azure API 기본은 Foundry에서 배포된 대상 URI가 아닌 Azure OpenAI 엔드포인트(일반적으로 openai.azure.com/로 끝남)를 나타냅니다.

Microsoft Entra ID를 사용하는 Azure OpenAI(키 없는 인증)

LLM 공급자로 "Azure Open AI(Microsoft Entra ID)"를 선택하면 Microsoft Entra ID를 사용하여 키 없는 인증을 구성할 수 있습니다. 이 옵션을 사용하면 API 키를 제공할 필요가 없습니다. 대신 이 인증 방법에는 다음 역할 할당이 필요합니다.

• 클라이언트 모드: 로컬 Azure CLI 자격 증명에 Azure OpenAI 리소스에 Cognitive Services 사용자 또는 Azure AI 사용자 역할이 할당되어야 합니다.
• 클러스터 모드: 워크로드 ID는 Azure OpenAI 리소스에 Cognitive Services 사용자 또는 Azure AI 사용자 역할을 할당해야 합니다.

기타 LLM 공급자

다른 OpenAI 호환 공급자를 사용하는 경우 해당 설명서에 따라 계정을 만들고 API 키를 검색하는 방법에 대한 지침을 참조하세요.

Docker 설치 확인 및 Docker 디먼 시작

1. Docker가 설치되어 있고 Docker 디먼이 다음 명령을 사용하여 실행 중인지 확인합니다.

   docker --version
   docker ps
   

2. Docker 디먼이 실행되고 있지 않음을 나타내는 오류가 표시되면 운영 체제에 적절한 단계를 사용하여 Docker 서비스를 시작합니다.

   • macOS/Windows:

     • 애플리케이션에서 Docker Desktop을 시작합니다.
     • Docker가 시작될 때까지 기다립니다.

   • Linux:

     • 다음 명령을 사용하여 Docker 서비스를 시작합니다.

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

3. 다음 명령을 사용하여 Docker가 실행되고 있는지 확인합니다.

   docker info
   

   이 명령은 오류 없이 Docker 시스템 정보를 반환해야 합니다.

클라이언트 모드 초기화

1. 명령을 사용하여 클라이언트 모드로 에이전트 CLI를 초기화합니다 az aks agent-init . 자리 표시자 값을 실제 리소스 그룹 및 클러스터 이름으로 바꿔야 합니다.

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

2. 배포 모드를 선택하라는 메시지가 표시되면 클라이언트 모드에 대해 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
   

3. 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 키를 입력해야 합니다.

4. 초기화에 성공했는지 확인합니다. 에이전트는 첫 번째 명령을 실행할 때 필요한 Docker 이미지를 자동으로 끌어온다.

클러스터 모드 초기화

1. 명령을 사용하여 클러스터 모드로 에이전트 CLI를 초기화합니다 az aks agent-init . 자리 표시자 값을 실제 리소스 그룹 및 클러스터 이름으로 바꿔야 합니다.

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

2. 배포 모드를 선택하라는 메시지가 표시되면 클러스터 모드에 대해 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
   

3. 대상 네임스페이스를 지정하라는 메시지가 표시되면 서비스 계정을 만든 네임스페이스를 입력합니다. 다음 예제에서는 자리 표시자로 사용합니다 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
   

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

5. 에이전트 배포를 위해 만든 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
   

6. 배포가 완료될 때까지 기다립니다. 초기화는 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. 성공적인 배포를 확인하고 매개 변수와 함께 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: 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 제거

명령을 사용하여 AKS 확장에 대한 에이전트 CLI를 제거합니다 az extension remove .

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

관련 콘텐츠

• AKS용 에이전트 CLI에 대한 개요는 AKS용 에이전트 CLI를 참조하세요.
• AKS용 에이전트 CLI와 관련된 문제를 해결하려면 AKS용 에이전트 CLI 문제 해결을 참조하세요.
• AKS용 에이전트 CLI에 대한 일반적인 질문에 대한 답변은 AKS FAQ용 에이전트 CLI를 참조하세요.