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.
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 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.
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.
- 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
- Apri la sezione Agenti.
- Fai clic su Aggiungi.
- Attiva o disattiva l'agente secondo le tue esigenze.
- Inserisci Nome e Descrizione.
- Seleziona l'LLM da usare.
- Valuta se mantenere il system prompt dell'LLM oppure sovrascriverlo per questo agente.
- Seleziona i tool che l'agente potrà usare.
- Se necessario, abilita la capacità RAG e scegli i documenti.
- Configura eventuali guardrail.
- Salva la configurazione.
Campi principali
- 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.
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.
- 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.
- 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.