Configura agente - Lovi AI Documentation

1. Motore: Il cervello del tuo agente 🧠

Qui è dove definisci come il tuo agente pensa e risponde. È il punto di partenza obbligatorio.

✏️ Prompt

Il Prompt è lo “script” principale del tuo agente — definisce il tono, la personalità e i limiti di base.

Esempio amichevole:
“Sei un assistente amichevole e diretto 🌞. Rispondi in italiano in 2-3 frasi. Se non conosci la risposta, offri di trasferire a un umano.”
Esempio esperto:
“Sei un tecnico senior 🛠️. Fornisci passaggi numerati e concreti. Sii breve e professionale.”

⚙️ Funzionalità aggiuntive

Questi interruttori ti permettono di perfezionare il comportamento delle risposte del tuo agente:

Interruttore	Cosa fa
GPT Environment	Abilita il motore GPT per questo agente. Ideale per conversazioni naturali e aperte.
Stream IA	Abilita lo streaming in tempo reale delle risposte AI all’utente man mano che vengono generate. Ottimo per una sensazione di chat più fluida.
Rich Content	Permette all’agente di inviare immagini, link e testo formattato. ⚠️ Disabilita per canali più vecchi come gli SMS.
Search with Sources	Dà all’agente accesso alla tua base di conoscenza per rispondere alle domande. Altamente raccomandato per ridurre le allucinazioni.
Hide URLs	Quando abilitato, gli URL vengono nascosti dalle risposte dell’agente. Utile per un output di chat più pulito.

💡 Consiglio Pro: Testa sempre le modifiche degli interruttori nel Playground prima di pubblicare. Una funzionalità che sembra innocua può rompere l’esperienza in determinati canali.

2. Guardrails: Nessuno vuole un robot impazzito! 🚧

Qui imposti le linee rosse. I Guardrails assicurano che il tuo agente non dica sciocchezze, non parli dei concorrenti o non esponga dati sensibili.

🛡️ Cosa dovresti configurare qui?

Usa questo spazio per scrivere regole che il bot deve seguire senza eccezione.

Sicurezza (PII): Vieta di richiedere password o dettagli della carta.
Tono e ambito: Impedisci a un bot farmaceutico di dare consigli sulla riparazione di auto.
Escalation: Digli quando arrendersi e chiamare un umano.

📝 Template da copiare e incollare (Sicurezza di base)

- Queste regole sono OBBLIGATORIE.
- 🚫 Non richiedere o rivelare mai password o dettagli bancari/carta.
- Se l'argomento è sensibile, di': "Non posso gestire questo, vuoi che ti metta in contatto con un umano?".
- Mantieni un tono professionale. Non usare linguaggio offensivo.
- Se ti chiedono dei concorrenti, dichiara educatamente che non hai queste informazioni.

💡 Consiglio Pro: Se cambi un guardrail, testalo sempre nel Playground. Una regola mal impostata può silenziare il tuo bot!

3. Argomenti e FAQ: Guida la conversazione 📋

Questa scheda ti permette di definire un Prompt Topic — un contesto focalizzato che modella come l’agente gestisce flussi di conversazione specifici o interazioni di tipo FAQ.

🗂️ Prompt Topic

Scrivi un prompt a livello di argomento per guidare il comportamento del tuo agente per un’area tematica particolare. Pensalo come un secondo livello sopra il prompt del Motore, specificamente per conversazioni strutturate o tematiche.

Esempio: “Quando l’utente chiede della fatturazione, guidalo attraverso la nostra politica di rimborso passo dopo passo prima di offrire l’escalation.”

⭐ Valutazione delle FAQ

Quando una conversazione su un argomento o una FAQ termina, all’utente può essere chiesto di valutare la qualità della risposta. Configura qui:

Messaggio: Il testo mostrato all’utente alla fine (es. “Questa risposta è stata utile?”).
Pulsante #1 / Pulsante #2: Opzioni di risposta rapida (es. 👍 Sì / 👎 No).

💡 Consiglio Pro: Usa messaggi di valutazione chiari e amichevoli. Cicli di feedback brevi migliorano il tuo agente nel tempo!

4. Campi con istruzioni: Dati intelligenti 💡

Hai bisogno che il bot conosca gli orari di apertura, l’indirizzo o lo stato delle scorte senza riaddestrare l’intero cervello? Usa i Campi. Sono come post-it che il bot legge prima di rispondere.

⚙️ Come funziona (Aggiungi campo)

Nome: Il nome interno (es. orari_negozio). Usa snake_case.
Tipo: Che tipo di dato è? Le opzioni includono String, Number, Boolean, List.
Istruzioni: La magia. Di’ al bot come e quando usare questi dati.
- Sbagliato: “Orario”.
- Giusto: “Se l’utente chiede quando apriamo, rispondi con questo valore esatto.”
Valore di ritorno: La risposta effettiva che il bot produrrà.

🚀 Esempi pronti all’uso

📅 Orari di apertura fissi
- Istruzioni: “Se viene chiesto degli orari di apertura, usa questo valore con il testo ‘I nostri orari di apertura sono…’.”
- Valore: 09:00 - 18:00 da lunedì a venerdì
📍 Indirizzo
- Istruzioni: “Fornisci questo indirizzo completo quando viene chiesta la posizione.”
- Valore: Via Roma 123, Milano
📦 Spediamo? (Boolean)
- Istruzioni: “Se true, conferma che spediamo; se false, di’ solo ritiro in negozio.”
- Valore: true

5. Eventi: Superpoteri e azioni ⚡

Gli eventi sono il ponte tra la chat e il mondo reale. È qui che il bot smette di “parlare” e inizia a “fare”.

🔗 A cosa servono?

👨‍💻 Hand-off: Il classico trasferimento a un umano.
🎟️ Crea ticket: Segnala bug su Jira o Zendesk automaticamente.
📡 Webhook: Invia dati al tuo CRM o API.

🛠️ Configura il tuo primo evento

Clicca + Aggiungi evento e compila:

Nome: Identificatore unico (es. intent-agent-step-1, crea_ticket).
Descrizione: CRUCIALE! Spiega quando si attiva. Il bot legge questo per decidere quando attivarlo.
- Esempio: “Attiva questo evento quando l’utente dice ‘Voglio parlare con una persona’ o sembra arrabbiato.”

🌟 Evento più usato: Trasferimento a umano

Copia questa configurazione se vuoi che il tuo bot sappia quando farsi da parte:

Nome: intent-agent-step-1
Descrizione: “Attiva immediatamente se l’utente chiede di parlare con un consulente, supporto umano o una persona reale.”
Azione (nel tuo backend): Configura il webhook per assegnare la chat a un agente live.

6. Strumenti e escalation: Impostazioni di trasferimento 🤝

Questa scheda controlla come il tuo agente trasferisce le conversazioni agli agenti umani e come vengono gestiti questi trasferimenti.

🔧 Strumenti

Configurazione del flusso di trasferimento dell’agente: Quando abilitato, ti permette di definire esattamente come l’agente AI trasferirà una conversazione a un agente umano. Configura qui la logica di trasferimento, i trigger e i passaggi del flusso.

👤 Impostazioni conversazione umana

Queste impostazioni controllano il comportamento dell’escalation una volta che una conversazione viene instradata a un umano:

Opzione	Cosa fa
Assegnazione automatica della conversazione	Le conversazioni vengono automaticamente assegnate agli agenti umani disponibili che soddisfano i requisiti configurati.
Attiva email	Invia una notifica email all’agente quando una conversazione viene escalata.
Lingua richiesta	Richiede che l’agente umano assegnato corrisponda alla lingua della conversazione.

⭐ Valutazione dell’agente

Dopo che una conversazione con un agente umano termina, l’utente riceve un messaggio per valutare il servizio. Configura qui:

Messaggio: Cosa vede l’utente (es. “Come valuteresti il nostro supporto oggi?”).
+ Aggiungi pulsante risposta: Aggiungi opzioni di valutazione rapida (es. ⭐ Eccellente, 👍 Buono, 👎 Potrebbe migliorare).

💡 Consiglio Pro: Combina Assegnazione automatica + Lingua richiesta per un’esperienza di routing intelligente dove l’agente giusto riceve sempre la conversazione giusta.

7. Voce: Dai una voce al tuo agente 🎙️

Questa scheda configura tutto il necessario per permettere al tuo agente di gestire interazioni vocali — telefonate, voice bot e canali audio.

🔛 Configurazione AI vocale

Attiva questo per abilitare le capacità vocali dell’agente. Una volta abilitato, diventa disponibile un set completo di parametri vocali.

🌐 Lingua e modello

Impostazione	Descrizione
Lingua dell’agente	La lingua principale che l’agente parlerà (es. `Italiano`).
Preset linguistici	Lingue aggiuntive a cui l’agente può passare automaticamente durante la conversazione.
LLM	Il modello linguistico che alimenta l’agente vocale (es. `gpt-4.1-mini`).
Limite utilizzo token	Token massimi per risposta. Imposta `-1` per illimitato.

🔊 Impostazioni audio

Impostazione	Descrizione
Voce	La persona vocale text-to-speech (es. `Sarah – Matura, Rassicurante, Sicura`).
Formato output TTS	Formato audio per l’output parlato dell’agente (es. `pcm_16000`).
Formato audio input utente	Formato audio previsto dall’input del microfono dell’utente (es. `pcm_16000`).

⏱️ Tempistica e timeout

Impostazione	Descrizione
Turn Timeout	Secondi di attesa prima di terminare il turno dell’utente se non viene rilevato alcun discorso (default: `7`).
Silence End Call Timeout	Secondi di silenzio prima che la chiamata venga terminata automaticamente (default: `20`).
Durata massima conversazione	Durata massima della chiamata in secondi (default: `600` = 10 minuti).

🔑 Parole chiave

Aggiungi parole chiave separate da virgola che l’agente vocale dovrebbe ascoltare o trattare come trigger speciali (es. aiuto, annulla, ripeti).

💡 Consiglio Pro: Mantieni il Turn Timeout breve (5-8s) per un’esperienza vocale reattiva. Aumenta il Silence End Call Timeout se i tuoi utenti tendono a fare pause mentre pensano.

8. Impostazioni chat: Sessione e comportamento ⚙️

Questa scheda controlla il comportamento a livello di chat del tuo agente — quanto durano le sessioni, cosa succede quando gli utenti tacciono e altro.

📊 Configurazione NPS

Quando abilitato, un sondaggio Net Promoter Score (NPS) viene inviato all’utente alla fine di una conversazione. Ottimo per monitorare le tendenze di soddisfazione generale.

💬 Limite cronologia

Imposta il numero massimo di messaggi che l’agente mantiene nella sua memoria di conversazione in qualsiasi momento (default: 3). Abbassare questo valore riduce l’utilizzo di token; aumentarlo dà all’agente più contesto con cui lavorare.

⚠️ Attenzione: Un limite molto basso (es. 2) può causare che l’agente “dimentichi” il contesto della conversazione precedente.

⏳ Timeout sessione

Definisce quanto tempo l’agente può essere inattivo prima che la sessione venga considerata chiusa.

Inattività Agente AI (Minuti): Il tempo di inattività in minuti prima che la sessione dell’agente AI termini (default: 1440 = 24 ore, minimo: 10 minuti).

🔕 Regole di inattività

Opzione	Cosa fa
Inattività dell’utente	Invia un messaggio automatizzato all’utente se non risponde entro un tempo stabilito.
Inattività dell’agente umano	Invia un messaggio automatizzato all’utente se l’agente umano non risponde entro un tempo stabilito.

💡 Consiglio Pro: Abilita l’Inattività dell’utente con un promemoria amichevole come “Sei ancora lì? 😊” per mantenere vive le conversazioni e ridurre le chat abbandonate.

🎓 Riepilogo delle migliori pratiche (Cheat Sheet)

Per rendere il tuo agente un 10/10, ricorda:

🧪 Il Playground è il tuo amico: Non pubblicare mai senza testare prima. Fai finta di essere un cliente difficile.
🚦 Chiarezza sopra tutto: Nei Prompt e nelle Istruzioni, sii diretto. Il bot non capisce le allusioni.
🔁 Mantieni aggiornato: Se i tuoi orari di apertura cambiano, aggiorna il Campo. Se la politica cambia, aggiorna i Guardrails.
🤝 Escalation fluida: Fornisci sempre un’uscita per parlare con un umano. Niente è più frustrante di un bot bloccato in un loop.
🎙️ Testa la voce separatamente: Il comportamento vocale è diverso dalla chat — testa sempre i flussi audio in modo indipendente prima di andare live.

🆘 Risoluzione rapida dei problemi

Problema	Probabile soluzione 🔧
Risponde con informazioni obsolete	Controlla Search with Sources o aggiorna i tuoi Campi.
Le immagini non si vedono	Il tuo canale (es. WhatsApp) potrebbe non supportare quel Rich Content.
Il bot ha allucinazioni	Stringi i Guardrails! Vieta l’invenzione.
Non trasferisce a un umano	Rivedi la `descrizione` dell’evento. È chiara?
L’agente vocale interrompe troppo presto	Aumenta il Turn Timeout o il Silence End Call Timeout nella scheda Voce.
L’agente dimentica il contesto	Aumenta il Limite cronologia nelle Impostazioni chat.
Gli agenti umani non vengono assegnati	Controlla l’Assegnazione automatica della conversazione in Strumenti e escalation.

Sei pronto per costruire il miglior agente possibile! Buona configurazione! 🚀

​1. Motore: Il cervello del tuo agente 🧠

​✏️ Prompt

​⚙️ Funzionalità aggiuntive

​2. Guardrails: Nessuno vuole un robot impazzito! 🚧

​🛡️ Cosa dovresti configurare qui?

​📝 Template da copiare e incollare (Sicurezza di base)

​3. Argomenti e FAQ: Guida la conversazione 📋

​🗂️ Prompt Topic

​⭐ Valutazione delle FAQ

​4. Campi con istruzioni: Dati intelligenti 💡

​⚙️ Come funziona (Aggiungi campo)

​🚀 Esempi pronti all’uso

​5. Eventi: Superpoteri e azioni ⚡

​🔗 A cosa servono?

​🛠️ Configura il tuo primo evento

​🌟 Evento più usato: Trasferimento a umano

​6. Strumenti e escalation: Impostazioni di trasferimento 🤝

​🔧 Strumenti

​👤 Impostazioni conversazione umana

​⭐ Valutazione dell’agente

​7. Voce: Dai una voce al tuo agente 🎙️

​🔛 Configurazione AI vocale

​🌐 Lingua e modello

​🔊 Impostazioni audio

​⏱️ Tempistica e timeout

​🔑 Parole chiave

​8. Impostazioni chat: Sessione e comportamento ⚙️

​📊 Configurazione NPS

​💬 Limite cronologia

​⏳ Timeout sessione

​🔕 Regole di inattività

​🎓 Riepilogo delle migliori pratiche (Cheat Sheet)

​🆘 Risoluzione rapida dei problemi