Gestione agenti

Gli agenti sono il cuore di Askme AI: ognuno e' una configurazione completa che determina come il sistema risponde all'utente, quali knowledge base consulta, quali strumenti MCP puo' invocare e con quale modello LLM ragiona.

Lista agenti

La pagina mostra per ciascun agente: nome, modello AI, stato, data di creazione.

Stati possibili

Stato	Significato
Bozza (draft)	In fase di configurazione, non utilizzabile in chat
Attivo (active)	Disponibile agli utenti del tenant
In pausa (paused)	Temporaneamente disabilitato
Archiviato (archived)	Non utilizzabile e nascosto dalla chat, conservato per storico

Azioni di riga

• Dettaglio — apre la pagina con riepilogo configurazione, risposte incerte e versioni
• Modifica — riapre il wizard sui campi precompilati
• Chat — avvia una chat preconfigurata con l'agente
• Elimina — rimuove l'agente (operazione irreversibile)

Creare un nuovo agente

Clicca Nuovo agente: il form e' organizzato in step sequenziali.

Step 1 — Informazioni generali

• Nome agente — es. "Assistente vendite" (massimo 100 caratteri)
• Descrizione
• Agente padre (opzionale) — abilita la catena di ereditarieta' (vedi sotto)

Step 2 — System prompt

Scrivi le istruzioni in linguaggio naturale. Mentre scrivi, digita @ per aprire un menu con i prompt template disponibili: selezionandone uno, il contenuto viene inserito nel punto del cursore.

Variabili dinamiche

Inserisci {{detected_language}} nel system prompt se vuoi che l'agente risponda automaticamente nella lingua dell'utente. Puoi usare anche segnaposto {{nome_variabile}} arbitrari: in chat verranno richiesti come input compilabili dall'utente prima dell'invio.

Step 3 — Parametri modello

• Modello AI principale — dropdown con tutti i modelli disponibili (OpenAI, Anthropic, Mistral, Google, Ollama locale, ecc.)
• Temperatura — 0.0-0.3 per risposte precise, 0.7-1.0 per risposte creative
• Top P, Max Token
• Reasoning + Sforzo di ragionamento (Auto / Basso / Medio / Alto) per i modelli che supportano il pensiero esteso

Step 4 — Knowledge base e RAG

• Knowledge base associate — multi-select; un agente puo' attingere a piu' KB contemporaneamente
• Abilita RAG
• Top-K risultati — numero di chunk recuperati per ciascuna query
• Soglia score — similarita' minima per accettare un chunk

• Scope check (out-of-scope refusal) — toggle che, se attivo, fa rispondere "fuori ambito" quando la domanda non e' coperta dalle KB. Disattivalo per agenti generalisti che devono rispondere anche senza fonti
• Modalita' riscrittura query: Nessuna / Semplice / Multi-query (espansione + fusione RRF, consigliata per migliorare il recall)
• Messaggio quando non ho fonti — testo fisso da mostrare; lascia vuoto per una risposta generata dal modello

Step 5 — Server MCP

• MCP Server associati — selezione bulk multi-select
• L'elenco degli strumenti effettivamente disponibili e' l'unione di quelli dei server selezionati e di quelli ereditati dai parent

Per i dettagli su configurazione, health check e tool dei server MCP vedi Server MCP.

Step 6 — Handoff a operatore

L'handoff è il meccanismo che, quando uno o più criteri si attivano, genera un evento di escalation: la conversazione viene segnalata come da prendere in carico da un operatore umano (oppure smistata via webhook al sistema di ticketing del cliente).

L'handoff si abilita con il toggle generale Abilita handoff a operatore. Quando attivo, vengono valutati 6 criteri indipendenti (in OR logico — se ne basta uno per scattare). Ogni criterio ha il proprio toggle e i propri parametri: puoi tenerli tutti attivi o disabilitare quelli non rilevanti per il tuo caso d'uso.

I 6 criteri di handoff

#	Criterio	Default	Quando scatta	Parametri
1	Parola chiave (keyword)	Attivo	L'utente usa una frase di richiesta esplicita di operatore umano	Lista personalizzabile di keywords (default include: "operatore", "parlare con umano", "assistenza umana", "agente umano", "human agent", "speak to someone", "real person", "transfer", ...)
2	Sentiment negativo (sentiment)	Attivo	Il sentiment dei messaggi recenti dell'utente è sotto soglia per N messaggi consecutivi	Soglia sentiment (default 0.35) — sotto è considerato negativo. Conteggio messaggi consecutivi (default 3) prima dell'attivazione
3	Fuori ambito (scope)	Attivo	Lo scope-check ha classificato la domanda come fuori dalla copertura dell'agente / KB	(Nessun parametro — il toggle dello scope-check si configura nello Step 4 RAG)
4	Loop / ripetizione (loop)	Attivo	L'utente ripete la stessa domanda perché non riceve risposta soddisfacente	Max ripetizioni (default 3) — dopo N giri identici scatta
5	Complessità / intent di escalation (complexity)	Attivo	L'intent classificato del messaggio appartiene a una lista di "intent escalation" con confidenza alta	Lista intent escalation (default: complaint, cancellation, legal). Confidenza minima dell'intent (default 0.8). Soglia complessità (default 0.75) per intent generici complessi
6	Confidenza bassa (confidence)	Attivo	La risposta dell'agente ha confidenza troppo bassa (proattivo: l'agente stesso si segnala incerto)	Soglia confidenza (default 0.30)

Come si valuta

Per ogni messaggio dell'utente la piattaforma:

1. Classifica intent + sentiment + complessità in un'unica chiamata LLM
2. Verifica i 6 criteri in ordine di priorità (parola chiave → fuori ambito → confidenza → loop → complessità → sentiment)
3. Al primo criterio scattato pubblica un evento di handoff (con reason + payload diagnostico) e marca la conversazione

I criteri non scattati ma vicini alla soglia compaiono nelle risposte incerte del dettaglio agente: usali come segnale per affinare prompt e KB.

Webhook in uscita

L'evento di handoff può essere inoltrato a sistemi esterni (helpdesk, CRM) tramite webhook configurati in Amministrazione → Webhook. Il payload include conversation_id, reason, intent classificato, sentiment score, ultimi messaggi.

Strategia consigliata

Disabilita i criteri rumorosi nei primi giorni di rollout (sentiment + complessità in particolare) e attivali progressivamente man mano che osservi le metriche di handoff in Monitoraggio.

Step 7 — Output strutturato (opzionale)

Per agenti che devono produrre JSON rigoroso (es. estrazione dati, integrazioni macchina-a-macchina):

1. Attiva il toggle Output strutturato
2. Nell'editor Monaco incolla o scrivi lo JSON Schema che descrive l'output atteso
3. La piattaforma valida lo schema in tempo reale ed evidenzia errori di sintassi

Output strutturato e tool calling

Output strutturato e tool calling MCP sono mutuamente esclusivi. Se l'agente ha sia un JSON Schema sia tool MCP configurati, prevalgono i tool e lo schema viene ignorato.

Step 8 — Intent personalizzati

Definisci categorie di intent per la classificazione automatica delle conversazioni: ogni intent ha nome e descrizione che guidano il classificatore.

Catena di parent prompt

Un agente puo' avere un agente padre, che a sua volta puo' averne uno, fino a 10 livelli. La piattaforma:

• Concatena i system prompt non vuoti di tutta la catena (root → … → figlio) separandoli con \n\n
• Unisce gli mcp_server_ids di tutti i livelli (deduplicati)
• Protegge automaticamente da cicli

Nella pagina di dettaglio dell'agente vedi l'indicazione Eredita da con il nome del padre.

Pattern consigliato

Crea un agente "base" con il tono di voce aziendale e gli MCP comuni. Tutti gli agenti specializzati puntano a quello come padre: cosi' aggiorni in un solo posto le linee guida di brand.

Dettaglio agente

Apri il dettaglio per accedere a:

• Configurazione — riepilogo di tutti i parametri impostati
• Risposte incerte — elenco dei messaggi con bassa confidenza. Per ognuno puoi cliccare Aggiungi a FAQ per crearla nella KB associata e migliorare le risposte future
• Versioni — storico delle versioni dell'agente; clicca Ripristina per tornare a una configurazione precedente

Best practice

1. Inizia in draft — completa tutti gli step, prova in chat, e solo poi pubblica come active
2. Sfrutta i parent prompt — riduce la duplicazione e centralizza le linee guida
3. Rivedi periodicamente le risposte incerte — sono la tua fonte primaria di FAQ candidate
4. Pausa anziche' eliminare — usa paused per disattivare temporaneamente; archivia quando l'agente non serve piu' ma vuoi conservare lo storico