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.

[SCREENSHOT: sezione Tool dell'agente con gruppi per client MCP e schede selezionabili dei tool]

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.

[SCREENSHOT: scheda Documenti con checkbox Capacità RAG, pulsante Seleziona e tabella dei documenti associati all'agente]

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.

[SCREENSHOT: campi di pre-guardrail e post-guardrail con regole statiche, scelta LLM e prompt di validazione]

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.