---
title: AI Agent
description: Consenti ai clienti di gestire le VM Linux descrivendo le attività: connessione via SSH dell'Agent, comandi autonomi consentiti e requisiti necessari.
url: https://nexcmp.com/it/docs/ai/ai-agent/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI Agent {#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 {#what-it-does}

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 {#requirements}

| Elemento | Requisito |
|---|---|
| Modulo AI e provider | Il modulo **AI** attivo e un [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/) 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 {#prepare-the-infrastructure}

1. Verifica il client SSH sul server del pannello:

   ```bash
   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:

   ```bash
   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 {#connect-in-nexcmp}

1. Completa [AI provider](https://nexcmp.com/it/docs/ai/ai-providers/): 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 {#how-it-runs-commands}

- **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 {#verify}

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 {#limits-notes}

- **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](https://nexcmp.com/it/docs/customers/login-as/)).
- **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 {#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**. |