AI Agent

Dove nell'admin: System › Settings › AI provider (/settings/ai) — interruttore del modulo e provider; System › Admin › License & updates (/license) — interruttore del modulo. Dove nel portale: AI Agent (/ai/agent) e la pagina /chat/agent, o la modalità Agent all'interno della chat.

Descrizione

L'AI Agent si connette alla VM Linux di un cliente tramite SSH ed esegue attività descritte in linguaggio naturale: "controlla lo stato del sistema", "installa Docker", "trova gli errori recenti", "libera spazio su disco". Mostra ogni comando che propone e il relativo output. I comandi in sola lettura possono essere eseguiti automaticamente; qualsiasi azione che modifichi il server richiede che il cliente prema Run.

Requisiti

Elemento	Requisito
Modulo AI e provider	Il modulo AI attivo e un AI provider funzionante. L'Agent richiede inoltre un modello che supporti il tool calling.
openssh-client sul server del pannello	L'Agent esegue i comandi con il programma ssh nativo del pannello (/usr/bin/ssh). L'installer installa openssh-client; verifica con ssh -V. Senza di esso l'Agent segnala "ssh client is not installed on the panel server".
Nessun gateway SSH separato	Nell'installazione predefinita viene utilizzato l'SSH integrato e il terminale web ssh-proxy non è necessario. Solo quando la funzione opzionale web SSH (feature_ssh_web) è stata abilitata e il servizio ssh-proxy è installato, l'Agent passa attraverso ssh-proxy.
Rete	Il server del pannello deve raggiungere l'IP della VM sulla sua porta SSH (22 per impostazione predefinita). Verifica i firewall e i gruppi di sicurezza tra il pannello e la rete guest.
VM	Di proprietà del cliente, in esecuzione, non bloccata, Linux (le VM Windows vengono rifiutate), con un indirizzo IP pubblico o raggiungibile.
Credenziali SSH	L'utente e la password di accesso della VM memorizzati da NexCMP (salvati al momento della creazione della VM o del ripristino della password, crittografati), o la chiave di operazioni del pannello se installata. Se nessuno dei due è presente, l'Agent indica di non potersi connettere.

Prepara l'infrastruttura

1. Verifica il client SSH sul server del pannello:

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

2. Verifica che il server del pannello possa aprire una connessione SSH verso una VM guest:

   nc -vz 198.51.100.10 22

   Sostituisci l'indirizzo con l'IP di una VM di test. Se questo passaggio fallisce, risolvi prima il routing o il firewall.

3. Assicurati che il guest consenta l'accesso tramite password per l'utente memorizzato da NexCMP (alcune immagini cloud lo disabilitano) o che la chiave di operazioni del pannello sia installata sul guest.

Collega in NexCMP

1. Completa AI provider: modulo attivo, provider salvato, Test connection verde.
2. Nient'altro è configurato dal lato admin. L'interruttore del modulo fa apparire le voci AI Agent nel portale clienti.
3. Come cliente: apri AI Agent, seleziona un server in esecuzione e fai clic su Choose server. La pagina esegue prima un test SSH con un comando fisso e sicuro (senza chiamate AI) e mostra SSH connected o il motivo del fallimento.
4. Digita un'attività o scegli un avvio rapido (Check system health, Install Docker, Install Nginx, Find recent errors, Security check, Free up disk space).

Come esegue i comandi

• Da dove: dal server del pannello, con il client di sistema ssh, un comando non interattivo alla volta. La destinazione è sempre l'IP della VM preso dal database, mai dalla richiesta; è possibile raggiungere solo la VM in esecuzione e sbloccata del proprietario.

• Autenticazione: la password memorizzata viene passata tramite un helper one-shot SSH_ASKPASS nell'ambiente di processo — non viene scritta su disco né inserita sulla riga di comando. Le chiavi host non vengono bloccate (le VM vengono reinstallate con nuove chiavi). L'output per comando è limitato a 200 KB e ciascun comando ha un limite di tempo (60 secondi).

• Ciclo dell'agente: l'IA propone i comandi e legge gli output; un turno termina dopo al massimo 10 passaggi.

• Modalità:

  Modalità	Comportamento
  Confirm	Ogni comando attende Run.
  Auto	Solo i comandi che superano un severo elenco di autorizzazioni in sola lettura vengono eseguiti autonomamente (ad esempio df -h, ps, journalctl). Qualsiasi altra cosa, e tutto ciò che il parser non è in grado di analizzare con certezza (variabili, sostituzione di comandi, reindirizzamenti a file), attende Run.

• Etichette di rischio: i comandi che sovrascrivono o eliminano file, scrivono su dischi, modificano account o SSH Keys, inviano dati a un server esterno, aprono connessioni di rete grezze, eseguono codice offuscato, scaricano ed eseguono uno script, spengono o riavviano la macchina o raggiungono altri server mostrano sempre Needs confirmation, anche in modalità Auto.

• Output non attendibile: l'output del comando viene mostrato al modello come dato non attendibile; le istruzioni in esso contenute non vengono seguite.

Verifica

1. Scegli una VM di test in esecuzione. La pagina mostra SSH connected.
2. Chiedi "Check CPU, RAM and disk". In modalità Auto i comandi in sola lettura vengono eseguiti e la risposta li riassume.
3. Chiedi "Install Nginx". Il comando di installazione viene visualizzato con Run e Skip; nulla viene eseguito finché non premi Run.
4. Il contatore in alto mostra il numero di chiamate IA utilizzate oggi (ad esempio 3/300).

Limiti e note

• Limite giornaliero: 300 chiamate IA per cliente al giorno (UTC); si azzera alle 00:00 UTC. Quando viene esaurito, l'Agent risponde "Daily AI quota reached".
• Concorrenza: al massimo 2 esecuzioni dell'Agent per cliente contemporaneamente; una sessione esegue un turno alla volta.
• Sessioni: fino a 100 messaggi per sessione, 4,000 caratteri per messaggio. Una sessione appartiene a una sola VM; se la VM viene eliminata o trasferita, la vecchia sessione diventa di sola lettura.
• VM bloccata o arrestata, o Windows: la VM viene mostrata come Locked, Stopped, Windows o No address e non può essere scelta.
• Impersonificazione: un amministratore che impersona un cliente non può utilizzare le funzioni di credenziali dell'Agent (vedi Log in as a customer).
• Responsabilità: l'Agent può commettere errori. Il portale invita i clienti a esaminare i comandi prima di eseguirli. Specifica nei termini di servizio che i clienti sono responsabili dei comandi che approvano.
• La disattivazione del modulo IA rimuove le voci dell'Agent e le rotte rispondono con 404 module_disabled.

Troubleshooting

Sintomo	Causa	Soluzione
"client ssh non installato sul server del pannello (apt install openssh-client)"	Nessun binario ssh	sudo apt-get install -y openssh-client.
"Impossibile accedere all'Agent" / ssh: no saved credentials for this VM	Nessuna password memorizzata e nessuna chiave di operations	Reimposta la password della VM nel portale in modo che venga salvata di nuovo, oppure installa la chiave di operations.
"Il server non ha risposto in tempo"	Firewall, SSH non in ascolto, VM occupata	Testa nc -vz <ip> 22 dal server del pannello; avvia sshd nella VM.
"Impossibile raggiungere SSH su questo server"	Routing o gruppo di sicurezza	Consenti al server del pannello di raggiungere la VM sulla porta 22.
"VM non in esecuzione" / "Accesso negato"	VM spenta, bloccata, eliminata o non appartenente al cliente	Avviala, sbloccala o scegline un'altra.
"Non disponibile: N (arrestata, bloccata o Windows)"	Motivi elencati sopra	La VM deve essere Linux e in esecuzione.
"Il gateway SSH è temporaneamente non disponibile"	Funzione Web SSH abilitata ma ssh-proxy non è attivo	Avvia ssh-proxy o disattiva la funzione Web SSH per utilizzare l'SSH integrato.
"L'IA risponde troppo lentamente (più di 90 secondi)"	Provider lento	Usa un modello più veloce o un Reasoning effort inferiore.
"Quota giornaliera AI esaurita"	300 chiamate utilizzate	Attendi fino alle 00:00 UTC.
"Questa sessione è ancora in esecuzione"	Un altro turno in corso	Attendi o premi Stop.