> ## Documentation Index > Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configura agente > Configura l'identità, la personalità e le regole del tuo agente AI Edit Agent Module ## 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. 1. **Sicurezza (PII):** Vieta di richiedere password o dettagli della carta. 2. **Tono e ambito:** Impedisci a un bot farmaceutico di dare consigli sulla riparazione di auto. 3. **Escalation:** Digli quando arrendersi e chiamare un umano. ### 📝 Template da copiare e incollare (Sicurezza di base) ```markdown theme={null} - 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) 1. **Nome:** Il nome interno (es. `orari_negozio`). Usa `snake_case`. 2. **Tipo:** Che tipo di dato è? Le opzioni includono `String`, `Number`, `Boolean`, `List`. 3. **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." 4. **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: 1. **Nome:** Identificatore unico (es. `intent-agent-step-1`, `crea_ticket`). 2. **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! 🚀