**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.
### **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. [](https://usermanual.vtenext.com/uploads/images/gallery/2026-07/xi3image.png)**Importante:** se l'endpoint dell'orchestratore non è configurato correttamente, gli agenti non possono essere eseguiti.
### **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. [](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** [](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** [](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.**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.
### **Tool disponibili per l'agente** Sotto ai campi principali trovi l'area **Tool**, dove scegli quali strumenti l'agente può usare. [](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.**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.
### **Capacità RAG e documenti** Se vuoi che l'agente lavori anche su contenuti del CRM, puoi attivare la capacità **RAG**. [](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.**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.
### **Guardrail** La sezione Agenti permette anche di definire controlli prima e dopo la generazione della risposta. [](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.**Attenzione:** i guardrail basati su LLM possono aumentare consumo di token e tempi di risposta, perché aggiungono passaggi di verifica.
### **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.