AI Agent

Onde no admin: System › Settings › AI provider (/settings/ai) — interruptor do módulo e provedor; System › Admin › License & updates (/license) — interruptor do módulo. Onde no portal: AI Agent (/ai/agent) e a página /chat/agent, ou o modo Agent dentro do chat.

O que faz

O AI Agent se conecta à VM Linux própria de um cliente via SSH e executa tarefas descritas em linguagem natural: "verificar integridade do sistema", "instalar o Docker", "encontrar erros recentes", "liberar espaço em disco". Ele exibe cada comando proposto e sua saída. Comandos somente leitura podem ser executados automaticamente; qualquer alteração no servidor aguarda o cliente pressionar Run.

Requisitos

Item	Requisito
Módulo de IA e provedor	O módulo AI ativado e um AI provider funcional. O Agente também precisa de um modelo que suporte chamada de ferramentas.
openssh-client no servidor do painel	O Agente executa comandos com o programa ssh próprio do painel (/usr/bin/ssh). O instalador instala o openssh-client; verifique com ssh -V. Sem ele, o Agente relata "ssh client is not installed on the panel server".
Sem gateway SSH separado	Na instalação padrão, o SSH integrado é usado e o terminal web ssh-proxy não é necessário. Somente quando o recurso opcional de web SSH (feature_ssh_web) é habilitado e o serviço ssh-proxy é instalado é que o Agente passa pelo ssh-proxy.
Rede	O servidor do painel deve alcançar o IP da VM em sua porta SSH (22 por padrão). Verifique firewalls e grupos de segurança entre o painel e a rede de convidados.
VM	De propriedade do cliente, em execução, não bloqueada, Linux (VMs Windows são recusadas), com um endereço IP público ou alcançável.
Credenciais SSH	O usuário e senha de login da VM armazenados pelo NexCMP (salvos quando a VM foi criada ou sua senha foi redefinida, criptografados), ou a chave de operações do painel se houver uma instalada. Se nenhum dos dois existir, o Agente informará que não pode fazer login.

Preparar a infraestrutura

1. Verifique o cliente SSH no servidor do painel:

   ssh -V
   sudo apt-get install -y openssh-client   # only if missing

2. Verifique se o servidor do painel consegue abrir o SSH para uma VM convidada:

   nc -vz 198.51.100.10 22

   Substitua o endereço pelo IP de uma VM de teste. Se isso falhar, corrija o roteamento ou o firewall primeiro.

3. Certifique-se de que o convidado permita login por senha para o usuário armazenado pelo NexCMP (algumas imagens em nuvem o desativam) ou que a chave de operações do painel esteja instalada no convidado.

Conectar no NexCMP

1. Complete o AI provider: módulo ativado, provedor salvo, Test connection verde.
2. Nada mais é configurado no lado do admin. O interruptor do módulo faz com que as entradas do AI Agent apareçam no portal do cliente.
3. Como cliente: abra o AI Agent, escolha um servidor em execução e clique em Choose server. A página primeiro testa o SSH com um comando fixo inofensivo (nenhuma chamada de IA é usada) e exibe SSH connected ou o motivo da falha.
4. Digite uma tarefa ou escolha um início rápido (Check system health, Install Docker, Install Nginx, Find recent errors, Security check, Free up disk space).

Como ele executa comandos

• De onde: o servidor do painel, com o ssh client do sistema, um comando não interativo por vez. O destino é sempre o IP da VM proveniente do banco de dados, nunca da requisição; apenas a VM própria, em execução e desbloqueada do proprietário pode ser acessada.

• Autenticação: a senha armazenada é passada por meio de um auxiliar SSH_ASKPASS de uso único no ambiente de processo — ela não é gravada em disco nem inserida na linha de comando. As chaves de host não são fixadas (as VMs são reinstaladas com novas chaves). A saída por comando é limitada a 200 KB e cada comando possui um limite de tempo (60 segundos).

• Loop do agente: a IA propõe comandos e lê as saídas; um turno termina após no máximo 10 etapas.

• Modos:

  Modo	Comportamento
  Confirm	Cada comando aguarda por Run.
  Auto	Apenas comandos que passam por uma lista de permissões estrita somente leitura são executados sozinhos (por exemplo df -h, ps, journalctl). Qualquer outra coisa, e qualquer coisa que o analisador não possa analisar com certeza (variáveis, substituição de comando, redirecionamentos para arquivos), aguarda por Run.

• Rótulos de risco: comandos que sobrescrevem ou excluem arquivos, gravam em discos, alteram contas ou chaves SSH, enviam dados para um servidor externo, abrem conexões de rede brutas, executam código ofuscado, baixam e executam um script, desligam ou reiniciam a máquina, ou alcançam outros servidores sempre mostram Needs confirmation, mesmo no modo Auto.

• Saída não confiável: a saída do comando é mostrada ao modelo como dados não confiáveis; as instruções contidas nela não são seguidas.

Verificar

1. Escolha uma VM de teste em execução. A página exibe SSH connected.
2. Peça "Check CPU, RAM and disk". No modo Auto, os comandos somente leitura são executados e a resposta os resume.
3. Peça "Install Nginx". O comando de instalação aparece com Run e Skip; nada é executado até que você pressione Run.
4. O contador na parte superior mostra o número de chamadas de IA usadas hoje (por exemplo 3/300).

Limites e notas

• Limite diário: 300 chamadas de IA por cliente por dia (UTC); ele é redefinido às 00:00 UTC. Quando esgotado, o Agente responde "Daily AI quota reached".
• Concorrência: no máximo 2 execuções do Agente por cliente ao mesmo tempo; uma sessão executa um turno de cada vez.
• Sessões: até 100 mensagens por sessão, 4,000 caracteres por mensagem. Uma sessão pertence a uma VM; se a VM for excluída ou transferida, a sessão antiga torna-se somente leitura.
• VM bloqueada ou parada, ou Windows: a VM é exibida como Locked, Stopped, Windows ou No address e não pode ser escolhida.
• Personificação: um administrador personificando um cliente não pode usar os recursos de credencial do Agente (consulte Log in as a customer).
• Responsabilidade: o Agente pode cometer erros. O portal instrui os clientes a revisarem os comandos antes de executá-los. Informe aos clientes em seus termos que eles são responsáveis pelos comandos que aprovam.
• Desativar o módulo de IA remove as entradas do Agente e as rotas respondem com 404 module_disabled.

Resolução de problemas

Sintoma	Causa	Correção
"o cliente ssh não está instalado no servidor do painel (apt install openssh-client)"	Sem o binário ssh	sudo apt-get install -y openssh-client.
"O Agent não conseguiu fazer login" / ssh: no saved credentials for this VM	Sem senha armazenada e sem chave de operações	Redefina a senha da VM no portal para que ela seja salva novamente ou instale a chave de operações.
"O servidor não respondeu a tempo"	Firewall, SSH não escutando, VM ocupada	Teste nc -vz <ip> 22 a partir do servidor do painel; inicie sshd na VM.
"Não foi possível acessar o SSH neste servidor"	Roteamento ou grupo de segurança	Permita que o servidor do painel alcance a VM na porta 22.
"VM não está em execução" / "Proibido"	VM parada, bloqueada, excluída ou que não pertence ao cliente	Inicie-a, desbloqueie-a ou escolha outra.
"Não disponível: N (parada, bloqueada ou Windows)"	Motivos listados acima	A VM deve ser Linux e estar em execução.
"O gateway SSH está temporariamente indisponível"	Recurso de SSH Web ativado, mas o ssh-proxy está fora do ar	Inicie o ssh-proxy ou desative o recurso de SSH Web para usar o SSH integrado.
"A IA está demorando muito para responder (mais de 90 segundos)"	Provedor lento	Use um modelo mais rápido ou um Reasoning effort menor.
"Cota diária de IA atingida"	300 chamadas usadas	Aguarde até 00:00 UTC.
"Esta sessão ainda está em execução"	Outro turno em andamento	Aguarde ou pressione Stop.