Instalar e usar a CLI agente do AKS (Serviço de Kubernetes do Azure) (versão prévia)

Este artigo mostra como instalar, configurar e usar a CLI agente do AKS (Serviço de Kubernetes do Azure) no modo de cliente ou no modo de cluster para obter informações e solução de problemas de IA para seus clusters do AKS.

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

Importante

As funcionalidades em versão preliminar do AKS estão disponíveis de forma optativa e por autoatendimento. As versões prévias são fornecidas “no estado em que se encontram” e “conforme disponíveis” e são excluídas dos contratos de nível de serviço e da garantia limitada. As versões prévias do AKS são parcialmente cobertas pelo suporte ao cliente em uma base de melhor esforço. Dessa forma, esses recursos não são destinados ao uso em produção. Para obter mais informações, consulte os seguintes artigos:

Pré-requisitos

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

  • Tenha uma chave de API LLM (modelo de linguagem de grande porte). Você deve trazer sua própria chave de API de um dos provedores com suporte:

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

  • Defina sua assinatura 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 extensão da CLI do aks-agent Azure, que fornece uma CLI com funcionalidades de agente para o AKS. Você pode instalar ou atualizar a extensão usando a CLI do Azure.

  • Docker instalado e em execução no computador local. Para obter instruções de instalação, consulte Introdução ao Docker.
  • Verifique se o daemon do Docker está iniciado e em execução antes de prosseguir com a instalação.
  • Verifique se suas credenciais do Azure estão configuradas corretamente e se você tem as permissões necessárias para acessar os recursos do cluster.

Instalar a CLI agentic para a extensão do AKS

  1. Instale a CLI agente para a extensão do AKS usando o comando az extension add. Se a extensão já estiver instalada, você poderá atualizar para a versão mais recente com o az extension update comando. Essa etapa pode levar de 5 a 10 minutos para ser concluída.

    # 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 comandos do 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

    Sua saída deve mostrar o aks-agent com suas informações de versão na seção extensions. Por exemplo:

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

Configure sua chave de API LLM

Antes de prosseguir com a instalação, você precisa configurar sua chave de API llm. É recomendável usar modelos mais recentes, como GPT-5 ou Claude Opus MINI , para melhorar o desempenho. Selecione um modelo com um tamanho de contexto alto de pelo menos 128.000 tokens ou superior.

  1. Crie um recurso do Azure OpenAI.
  2. Implante o modelo. Para o nome da implantação, use o mesmo nome do modelo, como gpt-4o ou gpt-4o-mini, dependendo do acesso. Você pode usar qualquer região em que tenha acesso e cota para o modelo. Na implementação, selecione um limite de token por minuto (TPM) o mais alto possível. Recomendamos mais de 1 milhão de TPM para um bom desempenho.
  3. Após a conclusão da implantação, observe a URL base da API e a chave de API. A versão da API não é a versão do modelo. Você pode usar qualquer versão da API disponível e com suporte no Azure OpenAI na API do Microsoft Foundry Models v1. A base da API do Azure refere-se ao ponto de extremidade do Azure OpenAI (que geralmente termina em openai.azure.com/), não ao URI de destino da implantação no Foundry.

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

Ao selecionar "IA aberta do Azure (ID do Microsoft Entra)" como seu provedor de LLM, você pode configurar a autenticação sem chave usando a ID do Microsoft Entra. Com essa opção, você não precisa fornecer uma chave de API. Em vez disso, esse método de autenticação requer as seguintes atribuições de função:

  • Modo de cliente: as credenciais da CLI local do Azure devem ser atribuídas ao usuário dos Serviços Cognitivos ou à função de usuário de IA do Azure no recurso do Azure OpenAI.
  • Modo de cluster: a identidade da carga de trabalho deve ser atribuída ao usuário dos Serviços Cognitivos ou à função de usuário de IA do Azure no recurso do Azure OpenAI.

Outros provedores LLM

Se você estiver usando outro provedor compatível com OpenAI, siga a documentação deles para obter instruções sobre como criar uma conta e recuperar a chave de API.

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

  1. Verifique se o Docker está instalado e se o daemon do Docker está em execução usando os seguintes comandos:

    docker --version
docker ps

  2. Se você receber um erro indicando que o daemon do Docker não está em execução, inicie o serviço docker usando as etapas apropriadas para seu sistema operacional:

    • macOS/Windows:

      • Inicie o Docker Desktop a partir de seus aplicativos.
      • Aguarde até o Docker começar.

    • Linux:

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

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

  3. Verifique se o Docker está em execução usando o seguinte comando:

    docker info

    Esse comando deve retornar informações do sistema do Docker sem erros.

Inicializar o modo de cliente

  1. Inicialize o CLI agente no modo cliente usando o comando az aks agent-init. Certifique-se de substituir os valores de preenchimento por seu grupo de recursos e nome de cluster reais.

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

  2. Quando solicitado a selecionar um modo de implantação, insira 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 detalhes do provedor 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 de API não é exibida enquanto você a digita, por questões de segurança. Insira a chave de API correta.

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

Inicializar o modo de cluster

  1. Inicialize a CLI agente com o modo de cluster usando o comando az aks agent-init. Certifique-se de substituir os valores de preenchimento por seu grupo de recursos e nome de cluster reais.

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

  2. Quando solicitado a selecionar um modo de implantação, insira 1 para o modo de 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 a especificar o namespace de destino, insira o namespace no qual você criou a conta de serviço. O exemplo a seguir usa your-namespace como espaço reservado. Substitua-o pelo namespace real usado.

    ✅ 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 detalhes do provedor 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 detalhes da conta de serviço usando a conta de serviço do Kubernetes que você criou para a implantação do agente. O exemplo a seguir usa aks-mcp como um espaço reservado para o nome da conta de serviço. Substitua-o pelo nome real da sua 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 implementa 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 implantação bem-sucedida e verifique o status 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

    A saída deve indicar que o agente está pronto e em execução, 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

    Você também pode verificar se a implantação foi bem-sucedida verificando os pods e as implantações no namespace de destino usando kubectl:

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

Usar a CLI agente do AKS

Depois de inicializado, você pode usar a CLI agente do AKS para solucionar problemas de clusters e obter insights inteligentes usando consultas de linguagem natural. A sintaxe de comando e a funcionalidade são as mesmas para o modo cliente e o modo de cluster, exceto para os parâmetros --mode e --namespace. O modo de cluster é o modo de implantação padrão, portanto, você só precisa especificar --mode client ao usar o modo cliente. Para o modo de cluster, você precisa especificar o --namespace parâmetro com o namespace em que o agente é implantado.

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.

Veja a seguir exemplos de consultas básicas que podem ser executadas com a CLI agente do AKS no 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

Veja a seguir exemplos de consultas básicas que podem ser executadas com a CLI agente do AKS no modo de 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, para que você possa continuar fazendo perguntas com o contexto retido até que deseje sair. Para sair da experiência, digite /exit.

Parâmetros de comando

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

Parâmetro DESCRIÇÃO
--max-steps Número máximo de etapas que o LLM pode executar para investigar o problema. Padrão: 40.
--mode O modo decide como o agente é implantado. Valores permitidos: client, cluster. Padrão: cluster.
--model Especifique o provedor LLM e o modelo ou implantação a serem usados para o assistente de IA.
--name, -n Nome do cluster gerenciado. (Obrigatória)
--namespace O namespace do Kubernetes em que o agente do AKS é implantado. Necessário para o modo de cluster.
--no-echo-request Desabilite o eco da pergunta fornecida ao Agente do AKS na saída.
--no-interactive Desabilitar 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. (Obrigatória)
--show-tool-output Mostrar a saída de cada ferramenta que foi chamada.
--status Mostrar informações de configuração e status do agente do AKS.

Especificação do modelo

O parâmetro --model determina qual LLM e provedor analisam 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 auxiliam na experiência de solução de problemas. Para acessá-los, insira / dentro da experiência de modo interativo.

A tabela a seguir descreve os comandos interativos disponíveis:

Comando DESCRIÇÃO
/exit Deixe o modo interativo.
/help Mostrar mensagens de ajuda com todos os comandos.
/clear Desmarque a tela e redefina o contexto da conversa.
/tools Mostrar conjuntos de ferramentas disponíveis e seu status.
/auto Alterne a exibição das saídas da ferramenta após as respostas.
/last Mostrar todos os resultados da ferramenta da última resposta.
/run Execute um comando Bash e, opcionalmente, compartilhe-o com LLM.
/shell Entre no shell interativo e, opcionalmente, compartilhe a sessão com o LLM.
/context Mostrar o tamanho do contexto da conversa e a contagem de tokens.
/show Mostrar a saída da ferramenta específica em um modo de exibição rolável.
/feedback Forneça comentários sobre a resposta do agente.

Desabilitar o modo interativo

Você pode desabilitar o modo interativo usando o --no-interactive sinalizador com seu 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 do AKS inclui integrações predefinidas para ferramentas populares de monitoramento e observabilidade por meio de conjuntos de ferramentas. Algumas integrações funcionam automaticamente com o Kubernetes. Outras integrações exigem chaves de API ou configuração.

Para o AKS, há 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 do servidor MCP do AKS

O servidor MCP (Protocolo de Contexto de Modelo) do AKS é habilitado por padrão com a CLI agente do AKS. Essa experiência ativa o servidor MCP do AKS localmente (ou no cluster com o respectivo modo) e o usa como a origem da telemetria.

Limpar a implantação da CLI de agente

Organize sua implantação no modo cliente usando o comando az aks agent-cleanup com o parâmetro --mode client. Esse comando remove o arquivo de configuração local e redefine a configuração do agente.

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

Limpe sua implantação no modo cluster usando o comando az aks agent-cleanup. Especifique o --namespace parâmetro com o namespace em que o agente é implantado. Esse comando remove o pod do agente do namespace especificado e exclui a configuração de 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 arquivo 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 pod do agente 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

Remover a interface de linha de comando (CLI) para a extensão do AKS.

Remova a CLI agente da extensão do AKS usando o comando az extension remove.

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

Conteúdo relacionado

  • Last updated on