Partilhar via

Instalar e usar a CLI agentic para Azure Kubernetes Service (AKS) (versão de pré-visualização)

Este artigo mostra-lhe como instalar, configurar e usar a CLI agente para o Azure Kubernetes Service (AKS) em modo cliente ou cluster para obter resolução de problemas e insights com IA para os seus clusters AKS.

Para mais informações, consulte o Agentic CLI para a visão geral do AKS.

Importante

Os recursos de pré-visualização do AKS estão disponíveis numa base de autosserviço e adesão voluntária. As visualizações prévias são fornecidas "como estão" e "conforme disponíveis" e são excluídas dos contratos de nível de serviço e da garantia limitada. As versões de teste do AKS são parcialmente cobertas pelo suporte ao cliente numa base de melhor esforço. Assim sendo, estas funcionalidades não se destinam ao uso em produção. Para obter mais informações, consulte os seguintes artigos de suporte:

Pré-requisitos

  • Azure CLI versão 2.76 ou posterior. Verifique sua versão usando o az version comando. Para instalar ou atualizar, consulte Instalar Azure CLI.

  • Ter uma chave da API de um grande modelo de linguagem (LLM). Você deve trazer sua própria chave de API de um dos provedores suportados:

    • Azure OpenAI (recomendado)
    • OpenAI ou outros provedores LLM compatíveis com as especificações OpenAPI

  • Defina a sua subscrição ativa do Azure usando o az account set comando.

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

  • Versão 1.0.0b16 ou posterior da aks-agent extensão Azure CLI, que fornece a CLI agente para funcionalidades AKS. Pode instalar ou atualizar a extensão usando a CLI do Azure.

  • Docker instalado e a correr na sua máquina local. Para instruções de instalação, veja Começar com o Docker.
  • Certifique-se de que o daemon Docker está iniciado e a funcionar antes de prosseguir com a instalação.
  • Garante que as tuas credenciais Azure estão devidamente configuradas e que tens as permissões necessárias para aceder aos recursos do cluster.

Instale o CLI do Agentic para a extensão do AKS

  1. Instala a CLI agente para a extensão AKS usando o az extension add comando. Se a extensão já estiver instalada, podes atualizar para a versão mais recente com o az extension update comando. Este passo pode demorar entre 5 a 10 minutos a completar.

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

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

  2. Verifique a instalação bem-sucedida usando o az extension list comando.

    az extension list

    Sua saída deve incluir uma entrada para aks-agent.

  3. Verifique se a CLI do agente para os comandos AKS está disponível usando o comando [az aks agent][/cli/azure/aks#az-aks-agent] com o parâmetro --help.

    az aks agent --help

    A sua saída deve mostrar o aks-agent com a sua informação de versão na secção extensions. Por exemplo:

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

Configurar sua chave de API LLM

Antes de avançar com a instalação, precisa de configurar a chave API do seu LLM. Recomendamos o uso de modelos mais recentes como GPT-5 ou Claude Opus MINI para melhor desempenho. Certifique-se de selecionar um modelo com um tamanho de contexto elevado de pelo menos 128.000 tokens ou mais.

  1. Crie um recurso do Azure OpenAI.
  2. Implementa o modelo. Para o nome da implementação, use o mesmo nome do modelo, como gpt-4o ou gpt-4o-mini, dependendo do acesso. Você pode usar qualquer região onde tenha acesso e cota para o modelo. Na implementação, selecione um limite de token por minuto (TPM) o mais elevado possível. Recomendamos mais de 1 milhão de TPM para um bom desempenho.
  3. Após a implementação concluída, anote a URL base da sua API e a chave da API. A versão da API não é a versão do modelo. Pode usar qualquer versão da API que esteja disponível e suportada no Azure OpenAI na Microsoft Foundry Models v1 API. A base da API do Azure refere-se ao endpoint Azure OpenAI (que normalmente termina em openai.azure.com/), e não ao URI-alvo da implementação no Foundry.

Azure OpenAI com Microsoft Entra ID (autenticação sem chave)

Quando seleciona "Azure Open AI (Microsoft Entra ID)" como seu fornecedor de LLM, pode configurar a autenticação sem chave usando o Microsoft Entra ID. Com esta opção, não precisa de fornecer uma chave API. Em vez disso, este método de autenticação requer as seguintes atribuições de funções:

  • Modo cliente: As credenciais CLI locais do Azure devem ser atribuídas ao papel de Utilizador de Serviços Cognitivos ou Utilizador de IA Azure no recurso Azure OpenAI.
  • Modo cluster: A identidade da carga de trabalho deve ser atribuída ao papel de Utilizador de Serviços Cognitivos ou Utilizador de IA Azure no recurso Azure OpenAI.

Outros fornecedores de LLM

Se estiver a usar outro fornecedor compatível com OpenAI, siga a documentação deles para obter instruções sobre como criar uma conta e recuperar a chave da API.

Verificar a instalação do Docker e iniciar o daemon Docker

  1. Verifique se o Docker está instalado e que o daemon Docker está a correr usando os seguintes comandos:

    docker --version
docker ps

  2. Se receber um erro a indicar que o daemon Docker não está a funcionar, inicie o serviço Docker usando os passos apropriados para o seu sistema operativo:

    • macOS / Windows:

      • Inicie o Docker Desktop a partir das suas aplicações.
      • Espere que o Docker comece.

    • Linux:

      • Inicie o serviço Docker usando os seguintes comandos:

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

  3. Verificar que o Docker está a correr usando o seguinte comando:

    docker info

    Este comando deve devolver a informação do sistema Docker sem erros.

Inicializar modo cliente

  1. Inicialize a CLI agente com o modo cliente usando o az aks agent-init comando. Certifica-te de substituir os valores provisórios pelo nome real do teu grupo de recursos e cluster.

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

  2. Quando solicitado a selecionar um modo de implementação, introduza 2 para o modo cliente.

    🚀 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. Configure os dados do seu fornecedor de LLM. Por exemplo:

    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.

    Observação

    A chave API aparece vazia enquanto escreves por questões de segurança. Certifica-te de introduzir a chave API correta.

  4. Verifique se a inicialização foi bem-sucedida. O agente puxa automaticamente as imagens Docker necessárias quando executa o seu primeiro comando.

Inicializar o modo de cluster

  1. Inicialize a CLI agente com modo cluster usando o az aks agent-init comando. Certifica-te de substituir os valores provisórios pelo nome real do teu grupo de recursos e cluster.

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

  2. Quando solicitado a selecionar um modo de implantação, introduza 1 para o modo cluster.

    🚀 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. Quando solicitado para especificar o namespace de destino, introduza o namespace onde criou a conta de serviço. O exemplo seguinte usa your-namespace como marcador de lugar. Certifica-te de o substituir pelo namespace real que usaste.

    ✅ 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. Configure os dados do seu fornecedor de LLM. Por exemplo:

    📦 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. Forneça os detalhes da conta de serviço usando a conta de serviço Kubernetes que criou para a implementação do agente. O exemplo seguinte demonstra o uso de aks-mcp como marcador para o nome da conta de serviço. Certifica-te de que o substitues pelo nome real da tua conta de serviço.

    👤 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. Aguarde a conclusão da implantação. A inicialização implanta o agente usando o 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. Verifique a implementação bem-sucedida e verifique o estado do agente usando o az aks agent comando com o --status parâmetro.

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

    O seu resultado deve indicar que o agente está pronto e em execução, de forma semelhante ao seguinte:

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

    Observação

    Também pode verificar a implementação bem-sucedida verificando os pods e implementações no espaço de nomes do destino usando kubectl:

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

Utilize o agentic CLI para o AKS

Uma vez inicializado, pode usar a CLI agente do AKS para diagnosticar os seus clusters e obter insights inteligentes usando consultas em linguagem natural. A sintaxe e a funcionalidade dos comandos são as mesmas tanto para o modo cliente como para o modo cluster, exceto pelos parâmetros --mode e --namespace. O modo cluster é o modo de implementação predefinido, por isso só precisas de especificar --mode client quando usar o modo cliente. Para o modo cluster, precisa de especificar o --namespace parâmetro com o namespace onde o agente é implementado.

Consultas básicas

Observação

Se você tiver vários modelos configurados, poderá especificar o modelo a ser usado para cada consulta usando o --model parâmetro. Por exemplo, --model=azure/gpt-4o.

Seguem-se exemplos de consultas básicas que pode executar com a CLI agente para AKS em modo cliente:

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

Seguem-se exemplos de consultas básicas que pode executar com a CLI agente para AKS em modo cluster:

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

A experiência usa o modo interativo por padrão, por isso podes continuar a fazer perguntas mantendo o contexto até quereres sair. Para sair da experiência, introduza /exit.

Parâmetros de comando

O az aks agent comando tem vários parâmetros que permitem personalizar a experiência de resolução de problemas. A tabela seguinte descreve os parâmetros-chave que pode usar ao executar as suas consultas:

Parâmetro Description
--max-steps Número máximo de passos que o LLM pode tomar para investigar o problema. Padrão: 40.
--mode O modo decide como o agente é implementado. Valores permitidos: client, cluster. Padrão: cluster.
--model Especifique o provedor LLM e o modelo ou implantação a ser usado para o assistente de IA.
--name, -n Nome do cluster gerenciado. (Necessário)
--namespace O namespace Kubernetes onde o Agente do AKS está implantado. Obrigatório para o modo cluster.
--no-echo-request Desative o eco da pergunta fornecida ao Agente AKS na saída.
--no-interactive Desative o modo interativo. Quando definido, o agente não solicitará entrada e será executado no modo de lote.
--refresh-toolsets Atualize o status dos conjuntos de ferramentas.
--resource-group, -g Nome do grupo de recursos. (Necessário)
--show-tool-output Mostra a saída de cada ferramenta que foi chamada.
--status Mostrar informações de configuração e status do agente AKS.

Especificação do modelo

O --model parâmetro determina qual LLM e provedor analisa seu cluster. Por exemplo:

  • OpenAI: Use o nome do modelo diretamente (por exemplo, gpt-4o).
  • Azure OpenAI: Use azure/<deployment name> (por exemplo, azure/gpt-4o).
  • Anthropic: Use anthropic/claude-sonnet-4.

Comandos interativos

O az aks agent tem um conjunto de subcomandos que ajudam na experiência de solução de problemas. Para aceder a eles, entra / na experiência de modo interativo.

A tabela seguinte descreve os comandos interativos disponíveis:

Comando Description
/exit Sai do modo interativo.
/help Mostrar mensagens de ajuda com todos os comandos.
/clear Limpa o ecrã e redefine o contexto da conversa.
/tools Mostrar conjuntos de ferramentas disponíveis e seu status.
/auto Altera a exibição dos resultados da ferramenta após as respostas.
/last Mostrar todos os resultados das ferramentas da última resposta.
/run Executa um comando Bash e, opcionalmente, partilha-o com o LLM.
/shell Entra no shell interativo e depois, opcionalmente, partilha a sessão com o LLM.
/context Mostra o contexto da conversa, o tamanho e o número de tokens.
/show Mostra a saída específica da ferramenta numa vista deslocável.
/feedback Forneça feedback sobre a resposta do agente.

Desativar o modo interativo

Podes desativar o modo interativo usando a --no-interactive flag com o teu comando. Por exemplo:

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

Conjuntos de ferramentas

A CLI agente para AKS inclui integrações pré-construídas para ferramentas populares de monitorização e observabilidade através de conjuntos de ferramentas. Algumas integrações funcionam automaticamente com o Kubernetes. Outras integrações requerem chaves API ou configuração.

Para o AKS, existem conjuntos de ferramentas específicos que ajudam na experiência de solução de problemas. Esses conjuntos de ferramentas aparecem na saída no início da experiência:

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

Integração com o servidor AKS MCP

O servidor AKS Model Context Protocol (MCP) está ativado por defeito com a CLI agentic para o AKS. Esta experiência faz com que o servidor MCP do AKS seja ativado localmente (ou no cluster com modo cluster) e utiliza-o como fonte de telemetria.

Limpeza da implementação da CLI agentica

Limpe a implementação do seu modo cliente usando o comando az aks agent-cleanup com o parâmetro --mode client. Este comando remove o ficheiro de configuração local e reinicia a configuração do agente.

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

Limpe a implementação do seu modo cluster usando o az aks agent-cleanup comando. Certifica-te de especificar o --namespace parâmetro com o namespace onde o agente é implementado. Este comando remove o pod do agente do espaço de nomes especificado e elimina a configuração do LLM armazenada no cluster.

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

Verificar a limpeza bem-sucedida

Verifique se o ficheiro de configuração local e as imagens do Docker foram removidos usando os seguintes comandos:

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

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

Verifique se o agente pod e os recursos relacionados foram removidos do cluster usando os seguintes comandos com o namespace apropriado:

# 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

Remova a CLI agentic para extensão AKS

Remova a CLI agentic para a extensão AKS usando o az extension remove comando.

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

Conteúdo relacionado

  • Last updated on