Alibaba Cloud CLI writes its help information and error messages for human readers. An AI agent must parse this content, which increases the parsing cost and the number of retries. When you enable AI Mode, the CLI identifies the caller as an AI agent in the User-Agent of each request. Help information, error information, and next-step guidance then take a form that is easier for programs to parse. - Alibaba Cloud CLI: Central de Documentação do Alibaba Cloud

O Alibaba Cloud CLI gera informações de ajuda e mensagens de erro voltadas para leitores humanos. Um agente de IA precisa analisar esse conteúdo, o que aumenta o custo de processamento e o número de tentativas necessárias. Ao ativar o Modo AI, o CLI identifica o chamador como um agente de IA no User-Agent de cada requisição. A saída local do CLI também passa a adotar um formato mais fácil de ser processado por programas.

Visão geral

O Modo AI traz as seguintes mudanças:

Os services da Alibaba Cloud utilizam esse identificador para diferenciar chamadas de agentes de operações manuais, facilitando a solução de problemas e a coleta de estatísticas de chamadas.
Um agente consegue analisar a saída do CLI diretamente, reduzindo o número de novas tentativas.

Nota

O Modo AI não altera as permissões de uma chamada de API nem os parâmetros da requisição.
Não há garantia de compatibilidade futura no Modo AI. Se seu fluxo de trabalho de automação utilizar esse modo, evite depender de uma estrutura de saída fixa.

Mudanças de comportamento com o Modo AI ativado

Os recursos do Modo AI exigem o Alibaba Cloud CLI versão 3.5.0 ou superior. Quando você ativa o Modo AI, a saída local do CLI muda de várias formas, incluindo, mas não se limitando a:

O CLI retorna informações de ajuda em um formato mais compacto.
As informações de erro são retornadas em formato estruturado, contendo a causa da falha e a próxima etapa recomendada.
A validação dos valores dos parâmetros ocorre localmente no CLI.
A saída não contém caracteres de controle de cores.

Quando o conteúdo é apresentado de forma resumida, a saída indica como recuperar o conteúdo completo.

Gerencie o Modo AI

Gerencie o Modo AI com o grupo de comandos aliyun configure ai-mode.

Visualize a configuração atual

Execute o comando abaixo para visualizar a configuração atual do Modo AI:

aliyun configure ai-mode show

Exemplo de saída:

{
  "enabled": true,
  "user_agent": "",
  "effective_user_agent": "AlibabaCloud-Agent-Skills",
  "request_user_agent_suffix": "AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills",
  "config_file": "/home/user/.aliyun/ai-mode.json"
}

Descrição dos campos:

Campo	Descrição
`enabled`	Indica se o Modo AI está ativado.
`user_agent`	Segmento personalizado do identificador de habilidades do User-Agent. Um valor vazio significa que o valor padrão está em uso.
`effective_user_agent`	Segmento do identificador de habilidades efetivo: o valor personalizado ou o valor padrão `AlibabaCloud-Agent-Skills`.
`request_user_agent_suffix`	Sufixo completo anexado ao User-Agent da requisição.
`config_file`	Caminho para o arquivo de configuração.

Ative e desative o Modo AI

Por comando

Execute os comandos a seguir para ativar ou desativar o Modo AI:

# Enable AI Mode
aliyun configure ai-mode enable

# Disable AI Mode
aliyun configure ai-mode disable

Por variável de ambiente

O status do Modo AI é transmitido pelas seguintes variáveis de ambiente. Defina essas variáveis para controlar o Modo AI:

Variável de ambiente	Descrição
`ALIBABA_CLOUD_CLI_AI_MODE`	O valor `1` ou `true` ativa o Modo AI. O valor `0` ou `false` o desativa.
`ALIBABA_CLOUD_CLI_AI_USER_AGENT`	Sufixo completo do User-Agent anexado quando o Modo AI está ativo. Exemplo: `AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills`.

Nota

Em um ambiente de execução de agente, execute export ALIBABA_CLOUD_CLI_AI_MODE=1 para ativar o Modo AI na sessão atual. Essa configuração se aplica a todos os comandos da sessão, eliminando a necessidade de adicionar a flag --cli-ai-mode a cada comando. Para persistir a configuração, utilize o comando configure ai-mode.

Personalize o segmento do identificador de habilidades do User-Agent

O segmento padrão do identificador de habilidades é AlibabaCloud-Agent-Skills. Para distinguir diferentes agentes de IA, personalize este valor:

# Set a custom skills identifier segment
aliyun configure ai-mode set-user-agent --user-agent "MyAgent/1.0"

# Reset to the default value
aliyun configure ai-mode reset-user-agent

Após a personalização, o sufixo do User-Agent da requisição torna-se:

AlibabaCloud-AIMode/enabled MyAgent/1.0

Substituição por comando

Ao realizar uma chamada OpenAPI, use uma flag na linha de comando para substituir a configuração global do Modo AI apenas para o comando atual:

Flag	Efeito
`--cli-ai-mode`	Ativa o Modo AI para este comando, mesmo que esteja desativado globalmente.
`--no-cli-ai-mode`	Desativa o Modo AI para este comando, mesmo que esteja ativado globalmente.

Se ambas as flags aparecerem no mesmo comando, --no-cli-ai-mode tem precedência.

Exemplos:

# AI Mode is disabled globally, but this command appends the AI identifier
aliyun ecs DescribeInstances --cli-ai-mode

# AI Mode is enabled globally, but this command does not append the identifier
aliyun ecs DescribeInstances --no-cli-ai-mode

Arquivo de configuração

Para visualizar manualmente ou fazer backup do arquivo de configuração do Modo AI, localize-o no seguinte caminho conforme seu sistema operacional:

Sistema operacional	Caminho
Linux / macOS	`~/.aliyun/ai-mode.json`
Windows	`C:\Users\<USER_NAME>\.aliyun\ai-mode.json`

Exemplo de formato de arquivo:

{
  "enabled": true,
  "user_agent": "MyAgent/1.0"
}

Descrição dos campos:

Campo	Tipo	Descrição
`enabled`	boolean	Especifica se o Modo AI deve ser ativado. Padrão: `false`.
`user_agent`	string	Segmento personalizado do identificador de habilidades do User-Agent. Se estiver vazio, o valor padrão `AlibabaCloud-Agent-Skills` será utilizado.

Nota

Caso o arquivo de configuração não exista, o Modo AI permanece desativado por padrão. Utilize o comando aliyun configure ai-mode para gerenciar a configuração em vez de editar o arquivo manualmente.

Precedência

As configurações do Modo AI são aplicadas na seguinte ordem (da maior para a menor prioridade):

Flags de linha de comando (--cli-ai-mode / --no-cli-ai-mode)
Variável de ambiente (ALIBABA_CLOUD_CLI_AI_MODE)
Arquivo de configuração (ai-mode.json)

Quando uma configuração de maior prioridade entra em vigor, as de menor prioridade são ignoradas. Se tanto --cli-ai-mode quanto --no-cli-ai-mode forem especificados no mesmo comando, --no-cli-ai-mode terá precedência.

Escopo

O Modo AI entra em vigor nos seguintes cenários:

Chamadas OpenAPI: O segmento identificador de IA é anexado ao User-Agent tanto para requisições RPC quanto RESTful iniciadas por meio de comandos.
Comandos de plugin: O CLI transmite o status do Modo AI aos processos filhos do plugin através das variáveis de ambiente ALIBABA_CLOUD_CLI_AI_MODE e ALIBABA_CLOUD_CLI_AI_USER_AGENT, permitindo que os plugins anexem o identificador às suas próprias requisições.

Apêndice: Referência de subcomandos

Subcomandos disponíveis em aliyun configure ai-mode:

Subcomando	Descrição
`show`	Exibe a configuração atual do Modo AI.
`enable`	Ativa o Modo AI globalmente.
`disable`	Desativa o Modo AI globalmente.
`set-user-agent --user-agent <value>`	Define um segmento personalizado para o identificador de habilidades do User-Agent.
`reset-user-agent`	Restaura o segmento do identificador de habilidades para o valor padrão `AlibabaCloud-Agent-Skills`.
`set-ossutil --ossutil <json>`	Configura as definições do plugin ossutil (string JSON).
`reset-ossutil`	Limpa as configurações do plugin ossutil.