> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/avanzate/integrazioni/funzioni/funzioni-di-aisuru.md). # Funzioni di AIsuru AIsuru offre una serie di funzioni integrate pronte all'uso che permettono al tuo Agente di interagire con il mondo esterno. Queste funzioni sono già configurate e possono essere attivate facilmente, ma richiedono un'attenta configurazione nelle istruzioni dell'Agente per essere utilizzate in modo efficace. ### Panoramica delle funzioni disponibili AIsuru offre sette funzioni integrate principali: 1. **Variabili di contesto**: permettono all'Agente di gestire dinamicamente gli argomenti della conversazione; 2. **Artifacts**: crea e scarica contenuti interattivi in diversi formati (HTML, CSS, JavaScript, JSON, markdown, svg, ecc.) all'interno della chat; 3. **Invio email**: permette all'Agente di inviare comunicazioni email agli utenti registrati; 4. **Converti OpenAPI in funzioni**: genera automaticamente funzioni a partire da specifiche OpenAPI; 5. **Creazione di funzione da file:** permetti all'agente di accedere a quel file durante le conversazioni; 6. **Ricerca Perplexity:** consente all'Agente di effettuare ricerche web intelligenti con sintesi AI delle informazioni trovate; 7. **Emotions:** permette al tuo Agente di esprimere emozioni attraverso espressioni facciali e animazioni quando viene visualizzato con un avatar 3D. Puoi cominciare ad utilizzarle da subito: ti basterà attivare l'interruttore della funzione che vuoi utilizzare all'interno del tuo Agente! Ricorda, però, che per semplificare l'interazione con l'Agente e migliorare l'esperienza utente, è necessario spiegare all'Agente come e quando utilizzarle all'interno delle [istruzioni](/ai-generativa/prompt-engineering.md). Vediamole nel dettaglio 👇 ## 1. Variabili di contesto Le variabili di contesto permettono al tuo Agente di gestire dinamicamente i contesti durante la conversazione. Questa funzione è particolarmente utile per: * Applicare automaticamente contesti specifici in base alle risposte dell'utente; * Rimuovere contesti quando non sono più rilevanti; * Guidare la conversazione in modo naturale tra diversi argomenti. #### Come funziona L'IA generativa può: * Impostare un nuovo contesto quando riconosce un cambio di argomento; * Rimuovere un contesto quando l'argomento non è più pertinente; * Utilizzare più contesti contemporaneamente per rispondere in modo preciso. #### Configurazione nelle istruzioni È importante guidare l'Agente nell'utilizzo delle variabili di contesto attraverso le istruzioni, specificando: * Quali contesti può applicare (specifica precisamente il contesto da applicare); * Quando applicare i diversi contesti; * Come gestire il passaggio tra contesti diversi: quali contesti sono compatibili tra loro e quando rimuovere i contesti non più rilevanti. Ad esempio: ``` Quando si parla di un prodotto specifico, imposta PRODOTTO:[nome prodotto]. Se l'utente cambia argomento, rimuovi il contesto con PRODOTTO:-. Esempio: se l'utente chiede del prodotto X, imposta PRODOTTO:X ``` ## 2. Artifacts #### Cosa sono Gli artifact sono contenuti che il tuo Agente può creare all'interno della chat con l'utente. Questi contenuti possono essere utilizzati (contenuti interattivi), scaricati e successivamente condivisi. L'Agente può creare qualsiasi tipo di file sfruttando gli artifact, ad esempio: * Pagine web interattive: un unico file HTML contenente anche codice CSS e JS; * File di testo: come txt e markdown; * File CSV, SVG, ecc. #### Come funzionano Una volta abilitata la funzione "Artifacts", il tuo Agente sarà da subito in grado di creare questi contenuti. Per guidarlo con maggiore precisione, ricorda di spiegare nelle [istruzioni](/ai-generativa/prompt-engineering.md) quando deve ricorrere agli artifact e come deve utilizzarli. Durante la conversazione, se l'Agente creerà un artifact, l'utente sarà in grado di vederlo in una sezione separata dalla chat nel lato destro della pagina. #### Interagire con gli artifacts Nella parte superiore di ogni artifact è presente una barra degli strumenti con diversi pulsanti per gestire il contenuto. Da sinistra a destra trovi: * **Icona codice:** permette di visualizzare il codice sorgente dell'artifact; * **Icona occhio:** permette di visualizzare il file formattato o renderizzato (disponibile solo per file Markdown e HTML; per altri tipi di file vedrai solo il codice); * **Pulsante "Copia":** copia il codice sorgente negli appunti; * **Menu opzioni aggiuntive (freccia verso il basso):** premendo la freccia accanto al pulsante "Copia" si apre un menu con le seguenti opzioni: * Scarica come HTML o Markdown (solo per file HTML e Markdown); * Scarica come PDF (solo per file Markdown); * Apri in una nuova finestra; * Stampa. Tutte queste funzioni rendono semplice visualizzare, copiare, condividere o salvare qualsiasi artifact generato durante la conversazione. #### Limitazioni Gli artifact non possono essere visualizzati se l'utente sta interagendo con [layout di condivisione](/condivisione/crea-e-gestisci-i-layout-di-condivisione.md) "Website Assistant". ## 3. Invio email La funzione **Invio email** permette al tuo Agente di inviare comunicazioni email a tutti gli utenti registrati in piattaforma (su aisuru.com o all'interno della tua PaaS). Questa funzione utilizza il protocollo SMTP e può essere configurata con qualsiasi provider di email che supporti questo standard. #### 3.1 Come funziona L'Agente può inviare email automaticamente durante le conversazioni, utilizzando le credenziali SMTP che hai configurato. La funzione prende automaticamente l'indirizzo email dell'utente dal suo account registrato, quindi non è necessario che l'utente fornisca il proprio indirizzo email durante la conversazione. **Importante**: Questa integrazione funziona solo con utenti che si sono registrati ed hanno effettuato il login sulla piattaforma. Non funziona con utenti anonimi. #### 3.2 Configurazione SMTP Per configurare l'invio email nel tuo Agente: 1. Accedi alla sezione **Funzioni** del tuo Agente; 2. Trova il riquadro **"Invio Email"** e attiva la funzione premendo sul tasto "modifica parametri" che ti comparirà quando il cursore si troverà sopra il riquadro. 3. Scegli la tua "Modalità configurazione SMTP": 1. Eredita dal tenant: l'agente utilizza la [configurazione SMTP del tenant](/paas/pannello-di-amministrazione/gestione-tenant.md) (disabilitata se non configurata); 2. Configurazione SMTP personalizzata: inserisci credenziali SMTP specifiche per questo agente. Se scegli questa opzione, compila i campi richiesti. **Campi di configurazione** | Campo | Descrizione | Esempio | | ---------------------- | ------------------------------------------------------ | -------------------------------------------- | | **Server SMTP** | L'indirizzo del server email del tuo provider | smtp.gmail.com, smtp-mail.outlook.com | | **Porta** | La porta SMTP del server | 465 (SSL), 587 (STARTTLS), 25 (non criptato) | | **Nome utente** | Il tuo indirizzo email completo | | | **Password** | La password dell'account email o password applicazione | ••••••••••••••••• | | **Email del mittente** | L'indirizzo che apparirà come mittente | | | **Nome del mittente** | Il nome che apparirà come mittente | Nome Azienda | | **Sicurezza socket** | Tipo di crittografia utilizzata | SSL/TLS, STARTTLS | 5. Premi il tasto **"Salva"** per confermare le impostazioni. #### 3.3 Configurazione specifica per Gmail/Google Workspace Se utilizzi Gmail o Google Workspace, segui questa guida dettagliata per una configurazione sicura e conforme alle policy di Google: **3.3.1 Credenziali SMTP per Gmail**
CampoValore da inserire
Server SMTPsmtp.gmail.com
Porta465 (SSL) oppure 587 (TLS)
Metodo di sicurezzaSslOnConnect o StartTls (vedi porta)
Nome utenteindirizzo completo (es. nome@azienda.com)
PasswordPassword app generata da Google*
Limite invii2.000 email/giorno per account
**3.3.2 Guida step-by-step per Gmail** 1. **Attiva la Verifica in due passaggi** nel tuo account Google; 2. **Genera una Password app**: * Accedi a [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords); * Scrivi un nome descrittivo per la tua app password (es. "Mail AIsuru"); * Premi su Crea e copia la password generata. 3. **Configura nel pannello AIsuru**: * Server SMTP: `smtp.gmail.com`; * Porta: `465` (SSL) * Nome utente: il tuo indirizzo email completo; * Password: l'app assword copiata prima; * Sicurezza socket: lascialo vuoto a meno che tu non sia un utente esperto. Può essere None, Auto, SslOnConnect, StartTls o StartTlsWhenAvailable. Il valore predefinito è Auto. 4. **Salva e testa**: dovresti ricevere un'email di prova entro pochi secondi. #### 3.4 Altri provider email La funzione di invio email può essere configurata con qualsiasi provider che supporti SMTP. Consulta la documentazione del tuo provider per ottenere: * Server SMTP e porta; * Tipo di crittografia supportata; * Credenziali di autenticazione. #### 3.5 Configurazione nelle istruzioni dell'Agente È fondamentale definire nelle **Istruzioni** dell'Agente come utilizzare questa funzione, qui sotto c'è un esempio, ma assicurati di adattarlo al tuo specifico caso d'uso: ``` FUNZIONE INVIO EMAIL QUANDO UTILIZZARE L'EMAIL: - Invia email solo quando l'utente richiede esplicitamente di ricevere documentazione, report o materiale specifico FORMATO EMAIL STANDARD: - Oggetto: "Documentazione richiesta - [argomento]" - Corpo: breve introduzione, link/allegato, contatti per supporto MESSAGGIO DI CONFERMA: ``` #### 3.6 Best practices * **Definisci template chiari** per diversi tipi di comunicazione; * **Stabilisci limiti** per la frequenza di invio (massimo 2 email per conversazione); * **Implementa verifiche di sicurezza** nelle istruzioni; * **Gestisci correttamente i dati personali** secondo normative privacy; * **Monitora l'utilizzo** per evitare sovraccarichi del server SMTP; * **Testa regolarmente** la configurazione per verificarne il funzionamento. #### 3.7 Sicurezza e conformità * Non condividere mai le credenziali SMTP in chiaro; * Utilizza sempre connessioni crittografate (SSL/TLS); * Rigenera periodicamente le password applicazione; * Monitora i log di invio per rilevare utilizzi impropri; * Rispetta i limiti di invio del tuo provider per evitare blocchi. Con questa configurazione, il tuo Agente potrà inviare email in modo sicuro e professionale, migliorando l'esperienza utente e fornendo un canale di comunicazione diretto. ## 4. Converti OpenAPI in funzioni La funzione **Converti OpenAPI in funzioni** ti permette di generare automaticamente funzioni AIsuru a partire da una specifica OpenAPI esistente. #### Come funziona Questa funzione ti permette di: * **Caricare un file JSON OpenAPI** con la documentazione di un'API esistente e il relativo webhook; * **Generare automaticamente** tutte le funzioni necessarie per interagire con l'API; * **Avere funzioni subito pronte** con parametri, descrizioni e configurazioni già impostati. #### Configurazione della conversione OpenAPI Per convertire una specifica OpenAPI in funzioni: 1. Accedi alla sezione **Funzioni** del tuo Agente; 2. Seleziona la scheda **Funzioni AIsuru**; 3. Identifica il box **Converti OpenAPI in funzioni**: 1. Inserisci l'URL base del webhook, cioè delle API (es. `https://api.example.com`); 2. Premi sul pulsante "Carica JSON OpenAPI" e seleziona il file da caricare. #### Best practice 1. **Controlla le funzioni generate**: rivedi le funzioni create per assicurarti che siano corrette; 2. **Testa le funzioni**: usa il pulsante "Test" per verificare che funzionino; 3. **Aggiorna le istruzioni**: spiega all'Agente come e quando usare le nuove funzioni. ## 5. Creazione di funzione da file La funzione di creazione da file permette all'Agente di accedere a file come Excel, PDF, HTML o TXT durante le conversazioni, consentendogli di utilizzare informazioni contenute in questi documenti. **Come funziona** Questa funzione ti permette di: * Caricare un file (Excel, PDF, HTML o TXT) di dimensione inferiore a 500.000 caratteri * Fornire una descrizione che spieghi all'IA generativa come utilizzare questo file durante le conversazioni * Rendere il file accessibile all'Agente come fonte di informazioni **Configurazione della funzione da file** Per creare una nuova funzione a partire da un file: 1. Accedi alla sezione **Funzioni** del tuo Agente 2. Seleziona la scheda **Funzioni avanzate** 3. Clicca sul pulsante **Crea funzione da file** 4. Nella pagina che si apre, potrai: * Caricare un file (Excel, PDF, HTML o TXT) di dimensione inferiore a 500.000 caratteri * Inserire una **descrizione della funzione** che spieghi all'IA generativa come utilizzare il contenuto del file La **descrizione della funzione** è fondamentale: deve indicare chiaramente all'IA quando utilizzare questa funzione e come interpretare i dati del file. **Esempio di utilizzo** Se carichi un listino prezzi in formato Excel, potresti scrivere una descrizione come: ``` Utilizza questa funzione quando l'utente chiede informazioni sui prezzi dei nostri prodotti. Il file contiene il listino prezzi aggiornato con le seguenti colonne: - Codice prodotto - Nome prodotto - Categoria - Prezzo di listino - Prezzo scontato - Disponibilità Quando l'utente chiede il prezzo di un prodotto specifico, cerca nel listino e fornisci tutte le informazioni disponibili per quel prodotto. ``` **Best practices per la creazione di funzioni da file** * Utilizza file ben strutturati per facilitare la lettura da parte dell'IA * Fornisci descrizioni dettagliate che guidino l'IA nell'utilizzo del file * Mantieni i file sotto il limite di 500.000 caratteri per prestazioni ottimali * Aggiorna periodicamente i file per mantenere le informazioni sempre corrette ## 6. Ricerca Perplexity La **Ricerca Perplexity** permette al tuo Agente di effettuare ricerche web intelligenti utilizzando l'AI di Perplexity, che combina la ricerca in tempo reale con la capacità di sintetizzare e analizzare le informazioni trovate. #### Come funziona A differenza di una semplice ricerca web, Perplexity: * Cerca informazioni aggiornate su internet; * Analizza e sintetizza i risultati trovati; * Fornisce risposte complete con citazioni delle fonti; * Restituisce sia i risultati di ricerca che una risposta elaborata dall'IA. #### Configurazione di Ricerca Perplexity Puoi configurare la chiave API in due modalità: * **Eredita dal tenant**: la chiave API viene ereditata dalla configurazione del tenant (PaaS). Qualsiasi amministratore del tenant può modificare questa chiave in qualsiasi momento nella pagina dedicata. Le modifiche si applicano automaticamente a tutti gli agenti che utilizzano la configurazione del tenant. * **Chiave API personalizzata:** puoi configurare una chiave API specifica per questo agente. **Passaggi di configurazione** Per attivare questa funzione: 1. Nella sezione Funzioni di AIsuru, trova "Ricerca Perplexity"; 2. Attiva l'interruttore per abilitare la funzione; 3. Scegli la modalità chiave API: * Seleziona "Eredita dal tenant" per utilizzare la configurazione centralizzata; * Seleziona "Chiave API personalizzata" e inserisci la tua API Key di Perplexity nel campo richiesto; 4. Premi sul tasto "Salva" per confermare le impostazioni. #### Istruzioni Ricorda di aggiornare le istruzioni del tuo Agente spiegando come deve comporre la query da passare a Perplexity (che si occuperà di fare la ricerca vera e propria). ## 7. Emotions La funzione **Emotions** di AIsuru permette al tuo Agente di esprimere emozioni attraverso espressioni facciali e animazioni quando viene visualizzato con un avatar 3D. Questo sistema migliora significativamente l'interazione, rendendo la comunicazione più naturale ed espressiva. #### Come attivare la funzione Emotions Per attivare questa funzione: 1. Accedi al **pannello di gestione** del tuo Agente 2. Vai alla sezione "**Funzioni**" dalla barra laterale 3. Trova la funzione "**Emotions**" nella scheda "**Funzioni di AIsuru**" 4. Attiva l'**interruttore** per abilitare questa funzionalità #### Come funzionano le Emotions Quando attivi la funzione Emotions, il comportamento dipende dal tipo di avatar che stai utilizzando: * **Con avatar**: Avrai immediatamente accesso a 5 emozioni predefinite che possono essere mostrate dall'avatar (Felicità, Tristezza, Rabbia, Sorpresa, Paura) * **Con modelli GLB personalizzati**: È necessario che il modello includa le animazioni e le espressioni desiderate La funzione **non richiede alcun prompt specifico** per essere attivata. Una volta abilitata, il backend di AIsuru gestirà automaticamente le emozioni inserendo i tag necessari nelle risposte dell'Agente in base al contesto della conversazione. #### Visualizzazione delle emozioni Per vedere le emozioni in azione, devi visualizzare il tuo Agente in un ambiente che supporti gli avatar 3D, come: * Negli **Spazi Virtuali** di AIsuru * Utilizzando **layout** che supportano avatar 3D #### Sistema di categorizzazione delle animazioni Il sistema categorizza automaticamente le animazioni in base al loro nome: * **IDLE**: Animazioni di base che si ripetono continuamente (il nome dell'animazione contiene "idle") * **LOADING**: Animazioni che indicano uno stato di attesa (il nome contiene "loading" o "wait") * **ACTION**: Tutte le altre animazioni che mostrano azioni o emozioni specifiche #### Modelli GLB personalizzati e animazioni Se utilizzi un modello GLB personalizzato: * Se il modello ha uno **scheletro compatibile con RPM** (Ready Player Me), le animazioni standard funzioneranno automaticamente * Il modello **deve avere almeno un'animazione di tipo IDLE** (il nome dell'animazione deve contenere la parola "idle") per funzionare correttamente * Le animazioni vengono attivate dal backend in base al contesto della conversazione * Per un funzionamento ottimale, il modello dovrebbe includere animazioni per le emozioni di base (felicità, tristezza, rabbia, sorpresa, paura) #### Personalizzazioni avanzate tramite istruzioni Per un controllo più dettagliato delle animazioni, puoi aggiungere istruzioni specifiche nelle **Istruzioni del tuo Agente** (Impostazioni > IA > Istruzioni). **Animazioni singole** ``` NomeAnimazione ``` **Animazioni con loop** ``` NomeAnimazione[loop=N] ``` Dove i valori per il loop sono: * **\[loop=0]**: Ripete l'animazione all'infinito * **\[loop=1]**: Riproduce l'animazione una sola volta (impostazione predefinita) * **\[loop=N]**: Ripete l'animazione N volte Le animazioni di tipo IDLE hanno un valore predefinito di `loop=0` (infinito). **Sequenze di animazioni** ``` Animazione1->Animazione2->Animazione3 ``` È possibile specificare un parametro loop anche per le sequenze: ``` Animazione1->Animazione2->Animazione3[loop=2] ``` **Emozioni predefinite (per avatar RPM)** ``` Happiness ``` #### Guida per le istruzioni all'Agente Puoi guidare l'IA generativa aggiungendo specifiche istruzioni nelle **Istruzioni del tuo Agente** (Impostazioni > IA > Istruzioni). Esempio di istruzioni per l'Agente: ``` GUIDA PER LE ESPRESSIONI EMOTIVE:Quando comunichi con l'utente, esprimi le tue emozioni scrivendo precisamente i seguenti pattern:1. Per una SEQUENZA DI EMOZIONI: Surprise->Happiness Esempio: "All'inizio ero sorpreso, ma ora sono felice della notizia! Surprise->Happiness"2. Per ANIMAZIONI RIPETUTE (usa per enfatizzare): Wave[loop=3]Esempio: "Ti saluto con entusiasmo! Wave[loop=3]" ``` #### Esempio di istruzioni per movimenti di danza Se il tuo modello supporta movimenti specifici, puoi creare istruzioni personalizzate come: ``` MOVIMENTI DI DANZA:- AIDA1: Giro lento con le braccia distese verso l'alto- AIDA2: Movimento ondulatorio dei fianchi e delle braccia- AIDA3: Passo laterale con incrocio delle gambe e rotazione del bustoSTATI EMOTIVI:- Gioia (Gioia1, Gioia2, Gioia3)- Tristezza (Tristezza1, Tristezza2, Tristezza3)Per creare una sequenza di danza, usa questa sintassi:AIDA1->AIDA2->Gioia1->AIDA3Regole per le sequenze:1. Usa -> per collegare le animazioni2. Massimo 5 animazioni per sequenza3. Non usare spazi4. Puoi combinare liberamente movimenti di danza ed emozioni nella stessa sequenza ``` #### Best Practices 1. **Attiva la funzione Emotions** dal pannello Funzioni 2. **Non modificare le istruzioni** se non hai bisogno di personalizzazioni avanzate 3. Per un avatar creato con l'avatar maker di AIsuru, il sistema utilizzerà automaticamente le 5 emozioni predefinite 4. Per **modelli GLB personalizzati**, assicurati che abbiano almeno un'animazione di tipo IDLE e uno scheletro compatibile 5. Per **sequenze complesse**, utilizza le istruzioni avanzate con i tag di animazione 6. **Limita le sequenze** a 3-5 animazioni per le migliori prestazioni 7. **Testa le animazioni** con diversi tipi di avatar per verificarne la compatibilità Attivando la funzione Emotions, il tuo Agente sarà in grado di comunicare in modo più espressivo e coinvolgente, migliorando significativamente l'esperienza utente nelle interazioni in ambienti 3D. ### Considerazioni sulla sicurezza Per tutte queste funzioni, è fondamentale: * Configurare attentamente le istruzioni dell'Agente; * Limitare l'accesso a risorse sensibili; * Monitorare l'utilizzo delle funzioni; * Implementare meccanismi di verifica; * Rispettare le normative sulla privacy e la protezione dei dati. ### Ottimizzazione delle prestazioni Per ottenere i migliori risultati: * Combina diverse funzioni in modo sinergico; * Mantieni le istruzioni chiare e aggiornate; * Monitora regolarmente l'utilizzo delle funzioni; * Raccogli feedback dagli utenti; * Affina continuamente le configurazioni.