# 22 Strumenti AI

La sezione **Strumenti AI** raccoglie tutte le impostazioni dedicate alle funzionalità di intelligenza artificiale integrate nel CRM. Da qui è possibile configurare il modello linguistico (LLM), gestire i client e i server MCP, definire gli agenti AI e personalizzare la **chat AI** integrata nel sistema.

# 22.1 LLM

La sezione **LLM** delle impostazioni permette di registrare i **modelli linguistici (LLM)** che vtenext può usare per gli agenti e altre funzioni AI collegate. Qui si definiscono i dati di connessione del modello, il nome con cui identificarlo e alcuni parametri che influenzano il comportamento delle risposte.

<p class="callout warning">**vtenext non include un modello AI già pronto all'interno del CRM**. Per configurare un LLM è necessario disporre di un modello remoto accessibile tramite API compatibili con OpenAI, oppure di un modello locale già installato e raggiungibile. In altre parole, questa configurazione serve a collegare vtenext a un servizio AI esterno o locale: il modello non è "a bordo" del CRM.</p>

### **La schermata elenco**

Nella lista sono visibili le configurazioni già salvate. Per ogni voce puoi vedere:

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/1XZimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/1XZimage.png)

- Stato attivo o non attivo
- Nome della configurazione
- URL del servizio
- Modello utilizzato

Dalla lista puoi creare una nuova configurazione, modificare una voce esistente, eliminarla oppure attivarla e disattivarla rapidamente.

### **Creare un nuovo LLM**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/0K1image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/0K1image.png)

1. Apri la sezione LLM.
2. Fai clic su Aggiungi.
3. Compila i campi richiesti.
4. Se necessario, esegui un test della configurazione.
5. Salva.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/WRIimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/WRIimage.png)

<table border="1" cellpadding="5" cellspacing="5" id="bkmrk-processi%3A-cliccando-" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235, 247, 255); height: 103.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 29.7995%; height: 29.7969px; vertical-align: middle;">**Attivo**

</td><td style="width: 70.2005%; height: 29.7969px; vertical-align: middle;">rende il modello disponibile per l'utilizzo</td></tr><tr style="height: 10px;"><td style="width: 29.7995%; height: 10px; vertical-align: middle;">**Nome**

</td><td style="width: 70.2005%; height: 10px; vertical-align: middle;">nome descrittivo del modello visualizzato in vtenext. **Campo obbligatorio**.

</td></tr><tr style="height: 63.3906px;"><td style="width: 29.7995%; height: 63.3906px; vertical-align: middle;">**URL**

</td><td style="width: 70.2005%; height: 63.3906px; vertical-align: middle;">endpoint API a cui vtenext invia le richieste al modello (ad esempio `https://api.openai.com/v1/chat/completions`). **Campo obbligatorio**

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Modello**

</td><td style="width: 70.2005%; vertical-align: middle;">identificativo del modello da utilizzare (ad esempio `gpt-5.2`). **Campo obbligatorio**.

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Base URL**

</td><td style="width: 70.2005%; vertical-align: middle;">è l'indirizzo di base del servizio che ospita il modello. In pratica dice agli agenti AI e all'orchestratore Python dove si trova il servizio del modello. Diventa particolarmente importante quando si utilizza un modello locale o un servizio interno all'infrastruttura, per esempio un endpoint come `http://127.0.0.1:11434`.

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Provider**

</td><td style="width: 70.2005%; vertical-align: middle;">indica a vtenext e all'orchestratore Python che tipo di servizio c'è dietro al modello, ad esempio OpenAI oppure Ollama

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**API Key**

</td><td style="width: 70.2005%; vertical-align: middle;">chiave di autenticazione fornita dal provider, necessaria per autorizzare le richieste API

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Temperatura**

</td><td style="width: 70.2005%; vertical-align: middle;">controlla il livello di casualità delle risposte generate. Valori bassi (ad esempio `0,2`) producono risposte più coerenti, prevedibili e ripetibili; valori più alti (ad esempio `0,8` o superiori) favoriscono risposte più varie e creative

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Token massimi**

</td><td style="width: 70.2005%; vertical-align: middle;">definisce il numero massimo complessivo di token che il modello può utilizzare per elaborare la richiesta, includendo sia i messaggi inviati sia la risposta generata (se supportato dal provider)

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Token di completamento massimi**

</td><td style="width: 70.2005%; vertical-align: middle;">limita il numero massimo di token che il modello può utilizzare esclusivamente per la risposta generata

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**Developer Message**

</td><td style="width: 70.2005%; vertical-align: middle;">istruzioni rivolte al modello con ruolo *developer*, utilizzate per definire regole di comportamento o vincoli applicativi

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**System Message**

</td><td style="width: 70.2005%; vertical-align: middle;">istruzioni generali che definiscono il comportamento del modello durante la conversazione

</td></tr><tr><td style="width: 29.7995%; vertical-align: middle;">**User Message**

</td><td style="width: 70.2005%; vertical-align: middle;">messaggio di prova inviato al modello per verificarne il funzionamento. **Campo obbligatorio**

</td></tr></tbody></table>

### **Come funziona il test**

Il pulsante di PROVA invia una richiesta reale al modello con i parametri configurati e mostra:

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/UbJimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/UbJimage.png)

- esito dell'operazione
- codice di risposta
- header restituiti
- corpo completo della risposta

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/Gh2image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/Gh2image.png)

*Risultato della chiamata: tab RISULTATO*

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/Lmcimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/Lmcimage.png)

*Risultato della chiamata: tab HEADERS*

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/8qbimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/8qbimage.png)

*Risultato della chiamata: tab RISPOSTA*

<p class="callout warning">Il test serve a verificare la configurazione, ma non sostituisce il salvataggio.</p>

<p class="callout warning">Il test invia una richiesta reale al modello remoto o locale. Se il modello non è raggiungibile via API, il test non può funzionare.</p>

### **Esempi pratici**

#### Esempio 1: modello compatibile OpenAI

Usa questa configurazione quando il modello è disponibile come servizio remoto tramite API esterna. Imposta nome, URL, modello e API Key, poi invia un semplice messaggio di test.

#### Esempio 2: modello locale

Se il modello gira in locale o su infrastruttura interna, compila anche Base URL e Provider. Anche in questo caso il modello deve essere già installato, attivo e raggiungibile via rete.

# 22.2 Server MCP

La sezione **Server MCP** permette di pubblicare, tramite vtenext, un endpoint MCP che rende disponibili tool e operazioni del CRM a client esterni compatibili. In pratica, in questa sezione si decide **quale server esporre** e **quali strumenti pubblicare** attraverso di esso.

<p class="callout info">**In sintesi:** un server MCP non è un modello AI e non sostituisce un agente. È un punto di accesso che espone funzioni del CRM in modo controllato, così che un client MCP possa richiamarle dall'esterno.</p>

### **Quando usarla**

- Per esporre tool del CRM verso client esterni compatibili con MCP.
- Per selezionare in modo preciso quali operazioni rendere disponibili.
- Per creare un endpoint interno stabile da usare nelle integrazioni AI.
- Per generare, se serve, anche un MCP client collegato allo stesso server.

### **La schermata elenco**

Nella lista sono visibili i server MCP già configurati.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/xTyimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/xTyimage.png)

<table id="bkmrk-processi%3A-cliccando-" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235,247,255); height: 129.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 16.345%; height: 29.7969px; vertical-align: middle;">**Attivo**

</td><td style="width: 83.655%; height: 29.7969px; vertical-align: middle;">indica se il server è disponibile e pubblico</td></tr><tr style="height: 29.7969px;"><td style="width: 16.345%; height: 29.7969px; vertical-align: middle;">**Endpoint**

</td><td style="width: 83.655%; height: 29.7969px; vertical-align: middle;">identificatore del server pubblicato

</td></tr><tr style="height: 10px;"><td style="width: 16.345%; height: 10px; vertical-align: middle;">**Descrizione**

</td><td style="width: 83.655%; height: 10px; vertical-align: middle;">testo descrittivo del server

</td></tr><tr style="height: 29.7969px;"><td style="width: 16.345%; vertical-align: middle; height: 29.7969px;">**Tool pubblicati**

</td><td style="width: 83.655%; vertical-align: middle; height: 29.7969px;">numero di strumenti resi disponibili tramite quel server

</td></tr><tr style="height: 29.7969px;"><td style="width: 16.345%; vertical-align: middle; height: 29.7969px;">**MCP**

</td><td style="width: 83.655%; vertical-align: middle; height: 29.7969px;">eventuale client MCP collegato, con stato di sincronizzazione

</td></tr></tbody></table>

Dalla lista puoi creare un nuovo server, modificarlo, eliminarlo oppure copiare il suo URL completo.

### **Creare un nuovo Server MCP**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/vRhimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/vRhimage.png)

1. Apri la sezione **Server MCP**.
2. Fai clic su **Aggiungi**.
3. Controlla il **Base URL** mostrato dal sistema e **verifica che sia raggiungibile dall'esterno**.
4. Inserisci il nome dell'**Endpoint**.
5. Aggiungi una descrizione, se utile.
6. Decidi se creare anche il client MCP collegato.
7. Seleziona i tool da pubblicare.
8. Salva la configurazione.

### **Parametri da impostare**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/3Stimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/3Stimage.png)

<table id="bkmrk-attivo-rende-il-serv" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235,247,255); height: 129.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 16.345%; height: 29.7969px; vertical-align: middle;">**Attivo**

</td><td style="width: 83.655%; height: 29.7969px; vertical-align: middle;">rende il server disponibile all'uso</td></tr><tr style="height: 29.7969px;"><td style="width: 16.345%; height: 29.7969px; vertical-align: middle;">**Base URL**

</td><td style="width: 83.655%; height: 29.7969px; vertical-align: middle;">parte iniziale dell'indirizzo del server (`$site_URL`), mostrato in sola lettura. Viene predisposta automaticamente dal sistema

</td></tr><tr style="height: 10px;"><td style="width: 16.345%; height: 10px; vertical-align: middle;">**Endpoint**

</td><td style="width: 83.655%; height: 10px; vertical-align: middle;">identificatore finale del server. È la parte che completa l'URL pubblico del server MCP. Deve essere univoco e può contenere lettere, numeri, underscore e trattino

</td></tr><tr><td style="width: 16.345%; vertical-align: middle;">**Descrizione**

</td><td style="width: 83.655%; vertical-align: middle;">serve a spiegare lo scopo del server agli amministratori o a chi lo mantiene

</td></tr><tr><td style="width: 16.345%; vertical-align: middle;">**Crea MCP client**

</td><td style="width: 83.655%; vertical-align: middle;">crea automaticamente un client MCP che punta a questo server. Il collegamento viene mantenuto sincronizzato e, se il server viene eliminato, anche il client collegato viene rimosso

</td></tr></tbody></table>

### **Selezione dei tool pubblicati**

Dopo i campi principali, la schermata mostra l'area dedicata ai tool pubblicati.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/MqJimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/MqJimage.png)

I tool disponibili possono provenire da più aree del sistema, ad esempio:

- Tool Base
- Tool SDK (vedi [MCP Server](https://usermanual.vtenext.com/books/developers/page/mcp-server) per ulteriori dettagli)
- [Processi](https://usermanual.vtenext.com/books/manuale-dei-processi/chapter/16-processi-tool)

Puoi selezionarli per gruppo oppure cercarli rapidamente tramite il campo di ricerca. Alcuni tool di base vengono mantenuti automaticamente dal sistema, anche se non li selezioni manualmente, per garantire il corretto funzionamento dell'integrazione.

### **Esempi pratici**

#### Esempio 1: server MCP per tool interni del CRM

Puoi creare un server dedicato a un insieme ristretto di tool, per esempio solo quelli necessari a un assistente interno o a un'integrazione controllata.

#### Esempio 2: server MCP con client collegato

Se vuoi che il server sia subito utilizzabile anche dal lato client, puoi attivare l'opzione **Crea MCP client**. In questo modo vtenext prepara automaticamente anche il client che punta a quel server.

#### Esempio 3: pubblicazione selettiva dei tool

Se non vuoi esporre tutte le funzioni disponibili, puoi pubblicare solo i tool realmente necessari. Questo approccio aiuta a mantenere l'integrazione più ordinata e controllata.

# 22.3 Client MCP

La sezione **Client MCP** serve a collegare vtenext ad un server MCP esterno o interno, così da scaricare e usare i tool disponibili nei processi e negli agenti. In pratica, qui configuri **come raggiungere il server MCP**, **come autenticarti** e **come mantenere aggiornato l'elenco dei tool**.

<p class="callout info">**In sintesi:** il client MCP non pubblica funzioni verso l'esterno. Fa l'operazione opposta: si collega ad un server MCP, ne legge i tool e li rende disponibili dentro vtenext.</p>

### **Quando usarla**

- Per collegare vtenext a un server MCP già disponibile.
- Per usarla in processi e agenti i tool esposti da un server MCP (vedi [Azioni AI](https://usermanual.vtenext.com/books/manuale-dei-processi/chapter/3a-azioni-ai)).
- Per mantenere sincronizzato nel tempo l'elenco dei tool disponibili.
- Per collegare rapidamente un server MCP creato nella sezione [Server MCP](https://usermanual.vtenext.com/books/manuale-vtenext-2607/page/222-server-mcp).

### **La schermata elenco**

Nella lista sono visibili i client MCP già configurati.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/jbvimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/jbvimage.png)

<table border="1" cellpadding="5" cellspacing="5" id="bkmrk-processi%3A-cliccando-" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235, 247, 255); height: 129.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Attivo**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">indica se il client è abilitato</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Nome**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">nome interno con cui riconosci la connessione

</td></tr><tr style="height: 10px;"><td style="width: 22.2897%; height: 10px; vertical-align: middle;">**URL**

</td><td style="width: 77.7103%; height: 10px; vertical-align: middle;">indirizzo del server MCP a cui il client si collega

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; vertical-align: middle; height: 29.7969px;">**Ultima sincronizzazione**

</td><td style="width: 77.7103%; vertical-align: middle; height: 29.7969px;">mostra quando i tool sono stati sincronizzati l'ultima volta, oppure segnala che il client non è mai stato sincronizzato

</td></tr></tbody></table>

Dalla lista puoi creare un nuovo client, modificarlo o eliminarlo. Se il client è collegato a un Server MCP interno, dalla lista puoi anche aprire direttamente quel server.

### **Creare un nuovo Client MCP**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/vpTimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/vpTimage.png)

1. Apri la sezione **Client MCP**.
2. Fai clic su **Aggiungi**.
3. Inserisci un **Nome** facile da riconoscere.
4. Indica l'**URL** del server MCP.
5. Scegli il tipo di **Autenticazione**.
6. Compila le credenziali richieste, se previste.
7. Decidi se attivare la **Sincronizzazione** periodica.
8. Attiva la **Notifica** se vuoi essere avvisato quando i tool cambiano.
9. Salva la configurazione.

<p class="callout warning">**Importante:** al salvataggio vtenext prova a collegarsi davvero al server MCP. Se la connessione non riesce, la configurazione non viene accettata.</p>

### **Parametri da impostare**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/dAximage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/dAximage.png)

<table border="1" cellpadding="5" cellspacing="5" id="bkmrk-attivo-abilita-o-dis" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235, 247, 255); height: 129.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Attivo**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">abilita o disabilita il client</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Nome**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">nome descrittivo della connessione

</td></tr><tr style="height: 10px;"><td style="width: 22.2897%; height: 10px; vertical-align: middle;">**URL**

</td><td style="width: 77.7103%; height: 10px; vertical-align: middle;">indirizzo completo del server MCP da contattare

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; vertical-align: middle; height: 29.7969px;">**Autenticazione**

</td><td style="width: 77.7103%; vertical-align: middle; height: 29.7969px;">definisce come il client si autentica al server MCP

</td></tr><tr><td style="width: 22.2897%; vertical-align: middle;">**Username e Password**

</td><td style="width: 77.7103%; vertical-align: middle;">compaiono se scegli l'autenticazione **Basic**

</td></tr><tr><td style="width: 22.2897%; vertical-align: middle;">**API Key**

</td><td style="width: 77.7103%; vertical-align: middle;">compare se scegli autenticazione **Bearer** oppure **X-API-Key**

</td></tr><tr><td style="width: 22.2897%; vertical-align: middle;">**Sincronizza**

</td><td style="width: 77.7103%; vertical-align: middle;">permette ad un cron di controllare periodicamente i tool disponibili e aggiornarli in caso di novità

</td></tr><tr><td style="width: 22.2897%; vertical-align: middle;">**Notifica**

</td><td style="width: 77.7103%; vertical-align: middle;">invia una notifica quando la sincronizzazione rileva modifiche nei tool del server

</td></tr></tbody></table>

### **Come funziona l'autenticazione**

La scelta dell'autenticazione cambia i campi mostrati nella scheda.

<table border="1" cellpadding="5" cellspacing="5" id="bkmrk-nessuna-autenticazio" style="width: 100%; border-collapse: collapse; vertical-align: middle; background-color: rgb(235, 247, 255); height: 129.188px;"><tbody><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Nessuna autenticazione**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">non vengono richieste credenziali aggiuntive</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; height: 29.7969px; vertical-align: middle;">**Basic**

</td><td style="width: 77.7103%; height: 29.7969px; vertical-align: middle;">devi inserire username e password

</td></tr><tr style="height: 10px;"><td style="width: 22.2897%; height: 10px; vertical-align: middle;">**Bearer**

</td><td style="width: 77.7103%; height: 10px; vertical-align: middle;">devi inserire un token o API key

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.2897%; vertical-align: middle; height: 29.7969px;">**X-API-Key**

</td><td style="width: 77.7103%; vertical-align: middle; height: 29.7969px;">devi inserire la chiave API nel campo dedicato

</td></tr><tr><td style="width: 22.2897%; vertical-align: middle;">**VTE (Access Key)**

</td><td style="width: 77.7103%; vertical-align: middle;">vtenext usa automaticamente l'access key MCP dedicata dell'utente che effettua la chiamata. Non devi inserire manualmente credenziali

</td></tr></tbody></table>

<p class="callout info">**Quando usare VTE (Access Key):** questa opzione è particolarmente utile quando il client punta a un Server MCP esposto da vtenext, perché permette al sistema di gestire l'autenticazione in modo automatico.</p>

### **Verifica della connessione e mappatura dei tool**

La schermata del client mette a disposizione anche una funzione di verifica.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/Uf8image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/Uf8image.png)

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/gOyimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/gOyimage.png)

*Risultato della chiamata: RISULTATO*

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/AL5image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/AL5image.png)

*Risultato della chiamata: HEADERS*

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/6Nbimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/6Nbimage.png)

*Risultato della chiamata: RISPOSTA*

- Il pulsante di test controlla se il server MCP risponde correttamente.
- In caso di esito positivo, vtenext può leggere la lista dei tool disponibili.
- Dalla finestra di verifica puoi aggiornare la sezione dei tool disponibili con il comando **Mappa tool disponibili**.

Questa verifica è utile soprattutto quando stai configurando un nuovo server o quando vuoi controllare se l'autenticazione è corretta prima del salvataggio definitivo.

### **Tool disponibili**

Dopo il salvataggio, oppure dopo la mappatura dalla verifica, vtenext mostra la lista dei tool letti dal server MCP.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/wM5image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/wM5image.png)

Per ogni tool puoi vedere:

- nome del tool
- descrizione
- parametri di input
- campi obbligatori e facoltativi
- struttura dell'output restituito

Queste informazioni vengono salvate localmente, così i tool possono poi essere richiamati dentro gli agenti e i processi senza dover reinterpretare ogni volta la struttura del server remoto.

### **Sincronizzazione periodica**

Se attivi **Sincronizza**, un processo schedulato può controllare periodicamente se sul server MCP sono disponibili tool nuovi o modificati.

- Se trova cambiamenti, aggiorna la configurazione locale dei tool.
- Se non trova differenze, aggiorna comunque la data dell'ultima sincronizzazione.
- Se hai attivato anche **Notifica**, ricevi un avviso quando il set dei tool cambia.

<p class="callout warning">**Attenzione:** quando i tool cambiano sul server MCP, può essere necessario verificare eventuali processi o agenti che li usano, soprattutto se sono cambiati parametri o output.</p>

### **Esempi pratici**

#### Esempio 1: collegamento a un server MCP esterno

Puoi configurare un client MCP che punta a un server esterno pubblicato da un altro sistema. In questo caso inserisci URL, autenticazione richiesta e poi verifichi i tool disponibili.

#### Esempio 2: collegamento a un Server MCP di vtenext

Se hai già creato un Server MCP nella relativa sezione, puoi collegare il client allo stesso endpoint e usare l'autenticazione **VTE (Access Key)** per semplificare la configurazione.

#### Esempio 3: aggiornamento controllato dei tool

Se i tool del server remoto possono cambiare nel tempo, conviene attivare la sincronizzazione periodica e, se necessario, anche le notifiche, così mantieni allineati processi e agenti.

### **Web Search MCP - Exa**

vtenext mette a disposizione anche un client MCP preconfigurato chiamato **Web Search MCP - Exa**. Questa voce viene creata automaticamente ma resta **disattivata** finché non decidi di usarla.

Exa è un servizio di ricerca web pensato per agenti AI. Permette di fare ricerche sul web in tempo reale, recuperare contenuti di pagine specifiche e fornire ai modelli informazioni più aggiornate rispetto alla sola conoscenza già incorporata nel modello.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/IX3image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/IX3image.png)

#### Come attivarlo

1. Apri la scheda **Web Search MCP - Exa** nella lista dei Client MCP.
2. Lascia invariato l'**URL** precompilato, che punta al server MCP pubblico di Exa.
3. Imposta o completa l'autenticazione **X-API-Key** con la chiave API del tuo account Exa.
4. Attiva il client.
5. Salva e verifica i tool disponibili.

In questo caso l'autenticazione prevista da vtenext è **X-API-Key**, già selezionata nella configurazione iniziale del client.

#### Tool disponibili con Exa

Il server MCP espone questi tool:

- **web\_search\_exa**: esegue ricerche sul web e restituisce contenuti già pronti da usare da parte dell'agente.
- **web\_fetch\_exa**: recupera il contenuto completo di una pagina web a partire da un URL noto.

<p class="callout info">**Quando può essere utile:** Exa è particolarmente adatto quando vuoi dare agli agenti e ai processi accesso a ricerca web aggiornata, analisi di pagine online o raccolta rapida di informazioni esterne.</p>

Per ulteriori dettagli sul servizio e sulle funzionalità del server MCP di Exa, consulta il sito ufficiale: [https://exa.ai/mcp](https://exa.ai/mcp).

# 22.4 Agenti

La sezione **Agenti** permette di configurare agenti AI che combinano un modello LLM, uno o più tool MCP e, se necessario, documenti del CRM da usare come base di conoscenza. In pratica, qui definisci **come l'agente ragiona**, **quali strumenti può usare** e **quali contenuti può consultare** per svolgere un task.

<p class="callout info">**In sintesi:** un agente non è solo un modello AI. È una configurazione completa che unisce LLM, tool operativi e fonti documentali, così da eseguire attività in modo più controllato e utile nel contesto di vtenext.</p>

### **Prerequisito: orchestratore agenti**

Per usare gli agenti è necessario che il servizio [**orchestratore agenti**](https://usermanual.vtenext.com/books/developers/page/agent-orchestrator) sia installato e raggiungibile. Nella schermata elenco degli Agenti è disponibile una scheda dedicata in cui puoi indicare l'**Endpoint orchestratore**, cioè l'URL base del servizio.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/xi3image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/xi3image.png)

<p class="callout warning">**Importante:** se l'endpoint dell'orchestratore non è configurato correttamente, gli agenti non possono essere eseguiti.</p>

### **Quando usarla**

- Per configurare agenti AI da usare nell'assistente o nei processi.
- Per associare ad un agente un LLM specifico.
- Per dare all'agente accesso a tool MCP selezionati.
- Per abilitare la capacità RAG scegliendo documenti del CRM come fonti di conoscenza.
- Per applicare regole di controllo prima e dopo la generazione della risposta (guardrail).

### **La schermata elenco**

Nella lista sono visibili gli agenti già configurati.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/wSXimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/wSXimage.png)

- **Attivo**: indica se l'agente è abilitato.
- **Nome**: nome dell'agente.
- **Descrizione**: testo che spiega lo scopo dell'agente.
- **LLM**: mostra il modello associato.
- **Documenti**: indica se l'agente ha accesso a documenti RAG.

Dalla lista puoi creare un nuovo agente, modificarlo o eliminarlo.

### **Creare un nuovo agente**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/4J0image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/4J0image.png)

1. Apri la sezione **Agenti**.
2. Fai clic su **Aggiungi**.
3. Attiva o disattiva l'agente secondo le tue esigenze.
4. Inserisci **Nome** e **Descrizione**.
5. Seleziona l'**LLM** da usare.
6. Valuta se mantenere il system prompt dell'LLM oppure sovrascriverlo per questo agente.
7. Seleziona i tool che l'agente potrà usare.
8. Se necessario, abilita la capacità RAG e scegli i documenti.
9. Configura eventuali guardrail.
10. Salva la configurazione.

### **Campi principali**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/UdKimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/UdKimage.png)

- **Attivo**: abilita o disabilita l'agente.
- **Nome**: nome interno con cui riconosci l'agente.
- **Descrizione**: breve descrizione interna che riassume il compito dell'agente.
- **LLM**: modello linguistico usato dall'agente.
- **System prompt dell'LLM**: mostra il system prompt attualmente configurato sul modello selezionato.
- **Sovrascrivi system prompt**: se attivato, l'agente usa un system prompt specifico invece di quello standard dell'LLM.
- **System prompt**: istruzioni specifiche dell'agente, visibili solo se scegli di sovrascrivere il prompt del modello.

<p class="callout info">**Quando usare la sovrascrittura del system prompt:** è utile quando vuoi mantenere lo stesso LLM ma cambiare in modo netto comportamento, tono o responsabilità di un singolo agente.</p>

### **Tool disponibili per l'agente**

Sotto ai campi principali trovi l'area **Tool**, dove scegli quali strumenti l'agente può usare.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/Vm5image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/Vm5image.png)

I tool sono mostrati per gruppi, in base ai client MCP attivi e ai tool interni disponibili.

- **Kitt tools**: include tool interni di base come **calculator** e **user\_manual**.
- **Client MCP**: per ogni client MCP attivo puoi selezionare i tool sincronizzati e disponibili.

Per ogni gruppo puoi selezionare tutti i tool oppure deselezionarli rapidamente. È disponibile anche una ricerca per filtrare i tool per nome o descrizione.

<p class="callout warning">**Attenzione:** l'agente può usare solo i tool che selezioni in questa sezione. Se un client MCP non è configurato o non ha tool sincronizzati, non comparirà come sorgente utilizzabile.</p>

### **Capacità RAG e documenti**

Se vuoi che l'agente lavori anche su contenuti del CRM, puoi attivare la capacità **RAG**.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/ZFiimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/ZFiimage.png)

- **Capacità RAG**: abilita l'uso di documenti come fonti di conoscenza.
- **Seleziona**: apre il selettore documenti per aggiungere file del CRM.
- **Tabella documenti**: mostra titolo, file, assegnatario e cartella dei documenti già associati.

Una volta aggiunti, i documenti restano collegati all'agente e possono essere rimossi in qualsiasi momento dalla tabella.

<p class="callout info">**Quando conviene usare RAG:** è utile quando l'agente deve rispondere o lavorare partendo da documentazione, file o contenuti aziendali presenti nel CRM, non solo da istruzioni generiche.</p>

### **Guardrail**

La sezione Agenti permette anche di definire controlli prima e dopo la generazione della risposta.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/li3image.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/li3image.png)

- **Pre-guardrail statico**: blocca input che contengono parole o espressioni non consentite.
- **LLM pre-guardrail**: usa un LLM per valutare l'input prima dell'elaborazione.
- **Prompt pre-guardrail**: definisce le istruzioni con cui il controllo valuta l'input.
- **Post-guardrail statico**: blocca output che contengono contenuti non consentiti.
- **LLM post-guardrail**: usa un LLM per valutare la risposta prima di restituirla.
- **Prompt post-guardrail**: definisce le istruzioni del controllo finale.

Le regole statiche possono includere testo semplice oppure espressioni regolari, una per riga.

<p class="callout warning">**Attenzione:** i guardrail basati su LLM possono aumentare consumo di token e tempi di risposta, perché aggiungono passaggi di verifica.</p>

### **Esempi pratici**

#### Esempio 1: agente con tool operativi

Puoi creare un agente che usa un LLM e alcuni tool MCP per interrogare dati, eseguire azioni consentite o consultare servizi esterni come la ricerca web.

#### Esempio 2: agente documentale

Puoi creare un agente focalizzato su documenti interni, abilitando RAG e selezionando solo i file rilevanti per uno specifico reparto o processo.

#### Esempio 3: agente con controlli rafforzati

Se l'agente opera su contenuti sensibili, puoi applicare pre-guardrail e post-guardrail per limitare richieste o risposte non appropriate.

# 22.5 Assistente Kitt

La sezione **Assistente** permette di definire come deve rispondere l'**assistente Kitt** di vtenext. In pratica, qui scegli **quale motore usare** per le risposte: un LLM diretto, un agente già configurato oppure un Webservice REST personalizzato.

<p class="callout info">**In sintesi:** l'assistente è il punto di accesso con cui l'utente interagisce. A seconda della configurazione, può rispondere direttamente con un modello, usare strumenti avanzati tramite un agente oppure delegare la risposta a un servizio esterno.</p>

### **Prerequisiti**

- Per usare un **LLM**, devi prima configurare almeno un modello nella sezione LLM.
- Per usare un **Agente**, devi prima configurare almeno un agente nella sezione Agenti.
- Per usare un **Webservice REST**, devi prima configurare il servizio nella relativa sezione.
- Per il funzionamento dell'assistente è necessario attivare il **worker per le attività in background**.

### **Creare o modificare l'assistente**

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/uxoimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/uxoimage.png)

1. Apri la sezione **Assistente**.
2. Attiva o disattiva la configurazione.
3. Seleziona il **Tipo** di assistente.
4. Compila il campo mostrato in base al tipo scelto.
5. Salva la configurazione.

### **Tipo: Agente**

Se scegli **Agente**, l'assistente userà uno degli agenti già configurati in vtenext.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/9OHimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/9OHimage.png)

- Selezioni un agente dall'elenco disponibile.
- L'assistente eredita le capacità dell'agente scelto.
- Questo include, se configurati nell'agente, tool MCP, documenti RAG, prompt specifici e guardrail.

<p class="callout info">**Quando conviene usare un agente:** è la scelta giusta quando vuoi che l'assistente faccia più di una semplice risposta testuale, per esempio usare tool, consultare documenti o seguire controlli più avanzati.</p>

### **Tipo: LLM**

Se scegli **LLM**, l'assistente userà direttamente un modello linguistico configurato nella sezione LLM.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/EIVimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/EIVimage.png)

- Selezioni il modello LLM da usare.
- Puoi visualizzare il **system prompt dell'LLM** attualmente configurato.
- Puoi attivare l'opzione **Sovrascrivi system prompt** per usare un prompt specifico solo per l'assistente.

Questa modalità è più semplice rispetto all'uso di un agente, perché non coinvolge tool MCP o documenti RAG.

#### Sovrascrivere il system prompt

Quando l'assistente è configurato in modalità LLM, puoi decidere se mantenere il system prompt del modello oppure sostituirlo.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/Yvyimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/Yvyimage.png)

- **System prompt dell'LLM**: mostra il prompt standard già presente sul modello selezionato.
- **Sovrascrivi system prompt**: se attivato, l'assistente usa il testo specificato nella configurazione dell'assistente.
- **System prompt**: campo in cui definisci istruzioni dedicate all'assistente.

<p class="callout info">**Quando è utile:** la sovrascrittura del system prompt serve quando vuoi mantenere lo stesso modello ma cambiare tono, obiettivo o comportamento dell'assistente rispetto ad altre configurazioni che usano lo stesso LLM.</p>

### **Tipo: Webservice REST**

Se scegli **Webservice REST**, l'assistente delega la risposta a un servizio REST esterno già configurato.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/s9ximage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/s9ximage.png)

- Selezioni un webservice REST custom dall'elenco.
- Il messaggio dell'utente deve essere passato nel corpo grezzo usando il tag **$content**.
- La risposta attesa deve essere mappata nel campo restituito **message**.

<p class="callout warning">**Limite da considerare:** in questa modalità non sono supportate la modalità stream e la memoria conversazionale.</p>

Questa opzione è utile quando vuoi collegare l'assistente a un sistema esterno già esistente o a un servizio AI personalizzato non gestito direttamente come LLM o agente in vtenext.

### **Esempi pratici**

#### Esempio 1: assistente solo LLM

Puoi configurare un assistente leggero che usa direttamente un modello per rispondere a domande generali, senza tool o documenti aggiuntivi.

#### Esempio 2: assistente basato su agente

Puoi usare un agente quando vuoi che l'assistente abbia accesso a ricerca web, documenti aziendali o strumenti operativi del CRM.

#### Esempio 3: assistente con servizio esterno

Puoi collegare un webservice REST custom se il tuo flusso prevede un motore di risposta esterno o una logica già sviluppata fuori da vtenext.

# 22.6 Esempi

Di seguito alcune richieste di esempio per mostrare le capacità dell'assistente.

---

### Creazione azienda

Posso creare qualsiasi record gestito dal CRM come in questo caso un'azienda. Vengono mostrati eventuali tool utilizzati dall'assistente e nel caso di operazioni di scrittura viene richiesta l'approvazione a procedere.

![Screenshot 2026-07-09 alle 13.59.37.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-13-59-37.png) ![Screenshot 2026-07-09 alle 14.00.13.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-00-13.png)

![Screenshot 2026-07-09 alle 14.00.33.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/pE3screenshot-2026-07-09-alle-14-00-33.png)

L'azienda viene creata innescando eventuali processi: in questo caso è attivo il processo descritto in [questo esempio](https://usermanual.vtenext.com/link/6303#bkmrk-web-scraping) che esegue dello scraping web per arricchire le informazioni dell'anagrafica.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/5zcimage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/5zcimage.png)

---

### Rielaborazione risposta a ticket

In questo esempio ho necessità di rispondere ad un ticket in cui il cliente riscontrava problemi al login. Posso creare una bozza di risposta digitandola direttamente nel campo Aggiungi commento.  
In questo modo avendo cliccato quel campo esso sarà aggiunto al contesto di Kitt e verrà resa disponibile l'azione rapita **Elabora testo**.

[![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/S4Ximage.png)](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/S4Ximage.png)

![Screenshot 2026-07-09 alle 14.27.20.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-27-20.png) ![Screenshot 2026-07-09 alle 14.28.17.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-28-17.png)

Nella risposta sarà disponibile il tasto **Applica** per sostituire il testo elaborato a quello presente nel campo indicato come contesto e si può procedere ad inviare il messaggio.

![image.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/57Limage.png)

---

### Da ticket a FAQ

Prendendo in esempio il ticket del punto precedente chiedo all'assistente di scrivere una soluzione basandosi sui commenti e poi di realizzare una FAQ.

![Screenshot 2026-07-09 alle 14.40.39.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-40-39.png) ![Screenshot 2026-07-09 alle 14.41.23.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-41-23.png)

![Screenshot 2026-07-09 alle 14.43.25.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-43-25.png)

---

### Invio email

Se l'assistente utilizza un agente tutti i tool attivi possono essere utilizzati direttamente in chat. Per esempio posso configurare un processo tool per l'invio di mail e chiedere quindi all'assistente di inviare una mail.

Il processo sarà così configurato e una volta attivato assicurarsi che il tool sia attivato nell'agente.

![Screenshot 2026-07-09 alle 14.51.17.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-51-17.png)

![Screenshot 2026-07-09 alle 14.51.33.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-14-51-33.png)

Chiedendo all'assistente di inviare una mail ad un contatto verranno quindi utilizzati i tool di VTE

![Screenshot 2026-07-09 alle 15.00.50.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-15-00-50.png) ![Screenshot 2026-07-09 alle 15.01.33.png](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/scaled-1680-/screenshot-2026-07-09-alle-15-01-33.png)