# 0. Introduzione ad AIsuru {% hint style="info" %} Cerchi la documentazione API? Vai alla [sezione dedicata](https://docs.aisuru.com/api)! {% endhint %} Benvenuto in AIsuru, la piattaforma che ti consente di **creare e gestire la tua IA conversazionale in modo semplice e intuitivo**. Che tu sia un'azienda o semplicemente un appassionato di tecnologia, AIsuru è lo strumento che stavi cercando per dare vita alle tue idee e migliorare il tuo lavoro con l'IA. In questa guida, ti accompagneremo passo dopo passo attraverso tutte le funzionalità di AIsuru, dai primi passi alle funzionalità più avanzate. Preparati a un viaggio entusiasmante nel futuro dell'interazione uomo-macchina! # Che cos'è AIsuru AIsuru è una piattaforma all'avanguardia che ti consente di **creare e gestire IA conversazionali personalizzate**. Va ben oltre le capacità di un semplice chatbot, offrendo un ecosistema completo per creare "gemelli digitali" della conoscenza, chiamati Agenti. Con AIsuru, puoi: * Creare assistenti virtuali intelligenti in grado di interagire in modo naturale e approfondito con utenti, clienti o dipendenti; * Digitalizzare le tue competenze personali o aziendali; * Realizzare un'assistenza clienti 24/7; * Sviluppare consulenti specializzati per il tuo settore; * Implementare sistemi di formazione interattivi e personalizzati; * Integrare l'IA in ambienti web, dispositivi fisici e persino nella realtà virtuale. La potenza di AIsuru risiede nella sua flessibilità e robustezza: * Puoi **addestrare i tuoi Agenti in vari modi;** * L'IA può fornire **risposte diverse a seconda dell'utente con cui interagisce;** * **Può integrarsi con app e servizi esterni** (ad esempio il tuo calendario). # A chi si rivolge AIsuru? AIsuru è progettato **per i creatori di IA**: persone creative e innovative che vogliono sfruttare la potenza dell'IA conversazionale senza necessariamente possedere competenze avanzate di programmazione. Che tu sia un professionista, un imprenditore o un appassionato di IA, AIsuru ti offre gli strumenti per dare vita alle tue idee. **Per aziende di ogni dimensione e settore**, AIsuru è un potente alleato. Dalle piccole imprese alle grandi aziende, la piattaforma si adatta alle tue esigenze, permettendoti di creare assistenti virtuali, sistemi di gestione della conoscenza o strumenti di formazione interattivi. Che tu operi nel commercio al dettaglio, nei servizi finanziari, nella sanità o in qualsiasi altro ambito: AIsuru ti permette di integrare l'IA conversazionale nel tuo lavoro in modo fluido e alle tue condizioni. **Per gli utenti individuali**, AIsuru apre un mondo di possibilità. Che tu voglia creare un assistente personale per gestire la tua agenda, un tutor virtuale per esplorare i tuoi interessi o un interlocutore esperto di argomenti specifici, la piattaforma ti offre tutta la flessibilità e la potenza necessarie per realizzare la tua visione dell'IA. Non devi essere un esperto di tecnologia: con AIsuru, la tua creatività e le tue conoscenze sono gli unici limiti per creare esperienze di IA uniche e coinvolgenti. # Panoramica delle funzionalità principali AIsuru offre un set completo di funzionalità che lo rendono uno strumento potente e versatile per creare IA conversazionale. Ecco le funzionalità principali che distinguono AIsuru: 1. **Creazione e gestione degli Agenti** * Crea facilmente IA personalizzate (Agenti) * Configura rapidamente le impostazioni di base * Gestisci più Agenti da un'unica interfaccia. 2. **Addestramento flessibile** * Istruisci il tuo Agente conversando direttamente con lui * Importa conoscenze da documenti esistenti (PDF, Word, ecc.) * Crea e gestisci manualmente contenuti strutturati. 3. **Personalizzazione avanzata** * Personalizza le risposte in base al ruolo dell'utente, alla posizione e all'ora del giorno * Crea flussi di conversazione guidati * Usa le variabili di contesto per conversazioni più naturali. 4. **Integrazione e connettività** * Collega il tuo Agente a servizi esterni tramite API * Integra il tuo Agente con MCP preconfigurati o personalizzati * Implementa funzioni personalizzate per azioni specifiche * Integra l'IA in siti web, app e dispositivi fisici. 5. **Analisi e ottimizzazione;** * Monitora le prestazioni del tuo Agente con statistiche dettagliate; * Analizza la cronologia delle tue conversazioni; * Ottimizza continuamente le risposte e l'esperienza utente. 6. **Funzionalità estese;** * Gruppo di Esperti: combina più Agenti specializzati; * Pensiero Profondo: abilita la memoria a lungo termine per interazioni personalizzate; * Spazi virtuali: crea ambienti VR/AR interattivi (Virtual Reality/Augmented Reality) con i tuoi Agenti; * Open Badge: certifica le competenze degli utenti tramite l'interazione con l'IA. 7. **Sicurezza e scalabilità;** * Gestione granulare degli accessi e della visibilità; * Conformità al GDPR e protezione dei dati; * Soluzioni scalabili dalle piccole imprese alle grandi aziende. # Qual è la differenza tra AIsuru e ChatGPT? Per comprendere la differenza tra AIsuru e ChatGPT, è importante distinguere tra i modelli linguistici di base (come GPT, Claude, Mistral) e le interfacce utente che li rendono accessibili (come ChatGPT, Microsoft Copilot, claude.ai). Questi modelli (noti nel settore come LLM) sono il "cervello" dell'Intelligenza Artificiale, mentre le interfacce sono il modo in cui interagiamo con essi. AIsuru occupa una posizione unica in questo panorama. Con AIsuru, puoi: * **Scegliere il modello linguistico che preferisci**; * **Fornire risposte certe** a domande specifiche senza farle generare dal modello; * **Personalizzare le risposte** in base al ruolo dell'utente, alla posizione o all'ora del giorno; * Visualizzare e analizzare la **cronologia delle conversazioni;** * **Collaborare con altri creatori** per gestire il tuo Agente. Mentre ChatGPT offre un'esperienza di conversazione generica, **AIsuru ti consente di creare assistenti IA su misura per le tue esigenze specifiche**. Puoi addestrare il tuo Agente con le tue conoscenze uniche, integrarlo nei tuoi sistemi esistenti e offrire un'esperienza personalizzata ai tuoi utenti. In sostanza, AIsuru non è solo un'interfaccia per comunicare con l'IA, ma una piattaforma completa per creare, gestire e distribuire la tua IA personalizzata. Ti offre il controllo e la flessibilità per modellare l'IA secondo la tua visione, sia che tu stia creando un assistente personale, un sistema automatizzato di assistenza clienti o un sistema di gestione della conoscenza aziendale. # Requisiti di sistema AIsuru è un servizio basato sul cloud, **puoi accedervi direttamente dal tuo browser web, senza dover installare software aggiuntivo sul tuo dispositivo**. Tuttavia, alcune funzionalità avanzate, come la realtà virtuale, richiedono funzionalità aggiuntive. ### Browser web Per un'esperienza ottimale, utilizza le versioni più recenti di: * **Google Chrome**; * **Mozilla Firefox**; * **Microsoft Edge**; * **Safari**. Mantieni sempre aggiornato il browser per garantire massima compatibilità e sicurezza. ### Connessione Internet Consigliamo una connessione Internet stabile con una velocità di **almeno 10 Mbps** per un'esperienza fluida. Anche una connessione ADSL meno recente ti consentirà di utilizzare la piattaforma senza problemi. ### Requisiti hardware #### Piattaforma web AIsuru è accessibile da: * **Computer desktop e portatili** (Windows, macOS, Linux); * **Tablet** (iPadOS, Android); * **Smartphone** (iOS, Android). L'interfaccia si adatta automaticamente alle dimensioni del tuo schermo per garantire la migliore esperienza utente possibile su ogni dispositivo. Per prestazioni ottimali nell'uso standard, consigliamo: * Processore: dual-core o superiore; * RAM: 4 GB o più; * Archiviazione: non richiesta. #### Requisiti per la realtà virtuale Per utilizzare le funzionalità VR di AIsuru, ti servono: * **Dispositivo VR**: Meta Quest 2 (o superiore) o Meta Quest Pro; * **Spazio libero**: almeno 2x2 metri per muoverti in sicurezza; * **Connessione Internet**: stabile e veloce, consigliamo almeno 30 Mbps; * **Account Meta**: necessario per accedere all'app VR di AIsuru. **Apple Vision Pro** al momento **non è supportato**, ma stiamo lavorando per aggiungere il supporto in futuro. Tieni presente che questi sono requisiti minimi. Per un'esperienza ancora migliore, soprattutto se prevedi di gestire Agenti complessi o di utilizzare funzionalità avanzate, valuta l'uso di hardware più potente e connessioni Internet più veloci. # 1. Primi passi Ora che abbiamo esplorato cos'è AIsuru e le sue principali funzionalità, è il momento di passare alla pratica e iniziare a utilizzare la piattaforma. In questa sezione, ti guideremo attraverso i primi passaggi per trasformare le tue idee in una vera IA conversazionale. Nei prossimi capitoli, tratteremo: 1. Come **creare il tuo account AIsuru;** 2. Come **navigare nell'intuitiva interfaccia utente della piattaforma;** 3. Come **creare il tuo primo "Agente"** (gemello digitale). Seguendo questa guida passo dopo passo, potrai creare la tua prima IA conversazionale in pochissimo tempo, aprendo le porte a un mondo di possibilità creative e pratiche. Cominciamo con il primissimo passo: creare il tuo account AIsuru. # Creazione di un account Per iniziare la tua avventura con AIsuru, il primo passo è creare un account.\ Il processo è semplice e veloce:
1. Vai su [aisuru.com](https://www.aisuru.com); 2. Fai clic sul pulsante "Login" nell'angolo in alto a destra o sul pulsante "Get Started" al centro della pagina 3. Inserisci il tuo indirizzo email e fai clic su "Send Magic Link"; 4. Fai clic sul magic link che arriva nella tua casella di posta; 5. Compila: 1. La tua data di nascita; 2. Accetta l'informativa sulla privacy e i termini di servizio (obbligatorio); 3. Accetta le condizioni di utilizzo di Pensiero Profondo (facoltativo); 6. Fai clic su "Complete your account": ora sei pronto a utilizzare tutte le funzionalità della piattaforma! {% hint style="info" %} Se vuoi modificare le tue preferenze per le condizioni di utilizzo di Pensiero Profondo, puoi sempre farlo nelle impostazioni del tuo [account.](/primi-passi/gestione-account#accessing-account-settings) {% endhint %} # Navigazione dell'interfaccia utente Una volta completata la registrazione, verrai accolto nella dashboard principale di AIsuru. L'interfaccia utente è progettata per essere intuitiva e facile da navigare, offrendoti un accesso rapido a tutte le funzionalità della piattaforma. Esaminiamo le principali sezioni dell'interfaccia. ### Barra superiore Situata nella parte superiore della pagina, questa barra ti offre un accesso rapido alle funzionalità essenziali: * **Sito web**: un collegamento diretto al sito principale di Memori (); * **Documentazione**: accesso alla documentazione completa di AIsuru (); * **Crediti**: gestisci e acquista i crediti della piattaforma (); * **Consumi**: monitora le statistiche di utilizzo e i consumi; * **Selettore della lingua dell'interfaccia** (IT/EN); * **Accesso alle impostazioni del tuo account o Logout** (ti basta fare clic sul tuo nome utente). Se stai già lavorando su un Agente, vedrai anche un pulsante in alto a destra con il nome del tuo Agente; facendo clic su di esso, verrai reindirizzato alla pagina "Contenuti" del tuo Agente. ### **Area principale** L'area principale è suddivisa in 4 sezioni: **Area banner** Nella parte superiore dello schermo potresti visualizzare notifiche in stile banner. Queste notificano all'utente eventuali modifiche, aggiornamenti o errori imminenti. **I tuoi Agenti** Qui troverai tutti i gemelli digitali che hai creato, visualizzati in un moderno layout a griglia con: * **Pulsante "CREA"**: per creare un nuovo Agente (mostrato come un riquadro tratteggiato con un'icona "+"); * **Schede degli Agenti**: ogni Agente viene visualizzato come una scheda con avatar circolare, nome e descrizione; * **Pulsante "Gestisci"**: per accedere al pannello di gestione di ciascun Agente. **Condivisi con te** Quando un altro utente condivide un Agente con te, apparirà questa sezione, che mostra gli Agenti creati da altri e che puoi anche gestire. Dopo aver fatto clic su "**Gestisci**" su uno dei tuoi Agenti, la barra laterale si aggiornerà ed entrerai nel pannello di gestione di quell'Agente. **Agenti pubblicati** Gemelli digitali creati da altri utenti con cui puoi interagire subito. Ogni Agente pubblicato mostra: * **Avatar e nome** dell'Agente; * **Breve descrizione** delle sue funzionalità; * **Tag tematici**: etichette colorate che indicano argomenti e competenze (ad es. "manual", "training", "ai", "prompt", "technology"); * **"Condiviso da"**: il nome utente del creatore dell'Agente. * **Icone di azione**: per copiare il link e accedere all'Agente cxd; * **Pulsante "Gestisci"**: per interagire con l'Agente. Se sono presenti molti Agenti pubblicati, apparirà un pulsante **"Espandi (altri X)"** per mostrare tutti gli Agenti disponibili. #### Barra laterale La barra laterale, posizionata sul lato sinistro dello schermo, offre un accesso rapido alle varie funzionalità di AIsuru. Il suo contenuto si adatta al punto in cui ti trovi, mostrando opzioni diverse nella homepage generale rispetto al pannello di gestione di un Agente specifico. **Quando ti trovi nella homepage di AIsuru**, la barra laterale include: * **Home**: torna alla pagina principale di AIsuru; * **Gruppi di Esperti**: gestisci i tuoi gruppi di Agenti specializzati; * **Spazi virtuali**: esplora e gestisci ambienti 3D per i tuoi Agenti; * **Account**: gestisci le impostazioni del tuo profilo utente; * **I tuoi badge**: visualizza i badge che hai ottenuto sulla piattaforma; * **Modelli**: accedi ai modelli linguistici disponibili; * **Feedback**: invia feedback o segnalazioni al team di AIsuru; * **Documenti** (visibili solo agli amministratori): gestisci i file caricati sulla piattaforma; * **Admin** (visibile solo agli amministratori): * **Agenti:** visualizza tutti gli Agenti sulla piattaforma. * **Utenti:** visualizza tutti gli utenti registrati sulla piattaforma; * **App fidate:** gestisci chiavi API e autorizzazioni per integrazioni sicure di terze parti; * **Tenant:** esplora tutte le informazioni e le impostazioni del tenant; * **Consumi:** monitora i consumi per Agente e chiave per ogni utente; * **Docs**: collegamento alla documentazione ufficiale; * **Changelog**: aggiornamenti della piattaforma e nuove funzionalità; * **News**: ti porta al [blog di Memori](https://memori.ai/it/blog). **Se stai già modificando un Agente**, troverai il nome del tuo Agente sotto "Spazi virtuali". Facendo clic sul nome del tuo Agente, accederai alle seguenti sezioni della barra laterale: * **Prova:** testa il tuo Agente avviando una conversazione; * **Istruiscimi**: insegna nuove informazioni all'Agente semplicemente chattando; * **Condividimi**: configura le opzioni di condivisione dell'Agente; * **Ruoli**: gestisci ruoli e personalizzazioni per diversi tipi di utenti; * **Followers**: gestisci e analizza i follower dell'Agente (visibile solo se Pensiero Profondo è attivo e abilitato per questo Agente); * **Conversazioni**: visualizza e analizza le interazioni passate dell'Agente; * **Contenuti**: gestisci la base di conoscenza dell'Agente; * **Dizionario**: personalizza il dizionario dell'Agente. * **Funzioni**: configura le funzioni (predefinite o in modalità avanzata); * **MCP**: collega il tuo Agente a servizi esterni e API tramite server MCP; * **Import / Export**: importa o esporta i dati dell'Agente; * **Statistiche**: analizza le prestazioni dell'Agente; * **Impostazioni**: configura le impostazioni generali dell'Agente; * **Dev docs**: accedi alla documentazione per sviluppatori. Per navigare, fai clic sulla voce desiderata. La voce attiva è evidenziata, così puoi sempre capire dove ti trovi. Alcune voci, come Admin, potrebbero essere visibili solo se disponi delle autorizzazioni necessarie. #### **Manuela** **Manuela è l'Agente ufficiale di supporto di AIsuru**. Puoi contattarla facendo clic sull'icona viola con il simbolo "?" al centro del lato destro della pagina. Non esitare a chiederle qualsiasi cosa sulla piattaforma, è qui per aiutarti con qualsiasi domanda! #### **Per concludere** Con questa panoramica dell'interfaccia utente, sei pronto per iniziare a esplorare AIsuru in modo più approfondito. Nel prossimo capitolo, ti guideremo nella creazione del tuo primo Agente, il punto di partenza per dare vita alla tua IA conversazionale. # Creazione del tuo primo Agente Ora che hai familiarizzato con l'interfaccia di AIsuru, è il momento di creare il tuo primo Agente! Un Agente è il cuore della tua IA conversazionale, una versione digitale di te stesso, di un esperto o di qualsiasi entità che desideri rappresentare. Vediamo come dare vita al tuo primo assistente virtuale. # Come creare un Agente Creare un Agente su AIsuru è il primo passo per avere un assistente virtuale personalizzato. Questo processo ti consente di definire le caratteristiche fondamentali del tuo Agente, dalla sua identità alle sue capacità IA. ### Avvio del processo di creazione Per iniziare: 1. Vai alla pagina principale di AIsuru; 2. Trova e fai clic sul pulsante "Crea" nella sezione "I tuoi Agenti". ### Configurazione dell'Agente Una volta avviato il processo, vedrai un pannello suddiviso in quattro sezioni principali. {% hint style="success" %} **Tutte queste impostazioni, tranne la lingua, possono essere modificate dopo la creazione dell'Agente**. Non preoccuparti troppo se non sei sicuro di alcune delle tue scelte iniziali. {% endhint %} #### Sezione generale Qui definirai l'identità e le caratteristiche di base del tuo Agente: * **Nome**: scegli un nome rappresentativo; * **Descrizione**: fornisci una breve presentazione dell'Agente; * **Visibilità**: * Pubblico: accessibile a tutti, non richiede password; * Privato: richiede una password; * **Lingua**: scegli la lingua principale; * **Tipo di voce**: scegli tra una voce maschile o femminile. * **Categorie:** puoi etichettare il tuo Agente in base all'argomento o allo scopo; * **NSFW**: abilitalo solo se il tuo Agente gestisce contenuti per adulti. Una volta attivato, non può essere rimosso. Contattaci se è stato impostato per errore; * **Risposta contestuale: r**endi il tuo agente capace di adattare le risposte in base al contesto: * **Posizione**: le risposte possono variare a seconda di dove si trova l'utente; * **Data e ora**: le risposte possono variare a seconda del giorno o dell'ora corrente; * **Accessibile solo agli utenti autenticati**: solo gli utenti che hanno effettuato l'accesso riceveranno risposte. * **Impostazioni avanzate:** * **Chiedi feedback sulle risposte basate sui contenuti**: il tuo agente aggiungerà automaticamente una richiesta, ossia *"Ti è stato utile?"*, per raccogliere feedback e migliorare la corrispondenza dei contenuti; * **Disabilita la raccolta di contenuti IA**: impedisce all'agente di accumulare bozze e domande senza risposta; * **Suggerisci domande se l'utente è inattivo**: l'agente suggerisce proattivamente domande quando un utente smette di interagire; * **Consenti agli utenti di segnalare risposte errate**: gli utenti possono segnalare risposte non corrispondenti; * **Soglia di confidenza:** controlla quanto l'agente deve essere sicuro prima di rispondere. Ciò garantisce risposte più accurate, ma aumenta il numero di volte in cui l'agente dice di non conoscere la risposta; * **Badge: integrazione DCM:** collega il tuo agente alle integrazioni dei badge DCM. **Nota**: se selezioni "Pubblico" durante la creazione, l'Agente apparirà automaticamente nella homepage. Puoi rimuoverlo dalla homepage disabilitando l'opzione pertinente nella sezione "Condividimi" del tuo Agente dopo averlo creato. #### Sezione IA Questa sezione ti consente di personalizzare le capacità dell'IA: * **Meccanismo di risposta**: * **Prima i contenuti, poi l'IA** *(NLP + GenAI)*: l'Agente cerca prima una corrispondenza nei tuoi contenuti, poi usa l'IA se non trova nulla; * **Solo IA** *(GenAI)*: l'Agente usa sempre l'IA per generare risposte; * **Solo contenuti** *(NLP)*: l'Agente risponde solo utilizzando i contenuti che hai caricato, senza IA; * **Scegli modello: s**eleziona quale modello IA alimenta il tuo Agente; * **Istruzioni IA:** scrivi un prompt personalizzato per guidare il comportamento e le risposte del tuo Agente. Usalo per dare al tuo Agente una personalità, un ruolo o un contesto specifico; * **Pensiero Profondo**: abilita questa funzionalità per una migliore comprensione del contesto; * **Istruzioni per il Pensiero Profondo**: indica all'IA quali informazioni deve tenere traccia durante la conversazione; * **Impostazioni avanzate**: * Configurazione per importazione/esportazione; * Configurazione del Pensiero Profondo *(disponibile solo se la funzionalità Pensiero Profondo è attiva);* * Numero massimo di token. * Temperatura. {% hint style="warning" %} La modifica di questi parametri può influire significativamente sulla qualità delle risposte. {% endhint %} #### Sezione Aspetto In questa sezione puoi personalizzare l'aspetto visivo del tuo Agente caricando un'immagine di copertina e un avatar. Per farlo: 1. Vai alla sezione "Aspetto" del pannello di creazione dell'Agente; 2. Per l'immagine di copertina: * Fai clic su "Carica nuova copertina" e scegli l'immagine che desideri caricare; 3. Per l'avatar: * Fai clic su "Carica avatar" e seleziona la tua immagine; 4. Dopo aver caricato le immagini, assicurati di salvare le modifiche. {% hint style="info" %} I formati supportati sono.png,.jpg,.jpeg,.gif, con una dimensione massima del file di 2 MB. {% endhint %} ### Sezione Estensioni In questa sezione puoi scegliere quali estensioni abilitare per l'Agente che stai modificando. Non preoccuparti: potrai modificare queste impostazioni in seguito nelle sezioni Funzioni e MCP. * **Fetch URL**: consente all'Agente di visitare pagine web ed estrarre informazioni rilevanti da esse; * **Artifact**: gli Agenti possono creare contenuti interattivi e multimediali durante le conversazioni; * **Analisi dei dati**: l'Agente è in grado di analizzare i dati e generare approfondimenti. * **Ricerca Perplexity**: utilizza l'IA per fornire risultati di ricerca accurati e pertinenti; * **Generatore di immagini**: consente all'Agente di generare immagini; * **Invia email**: consente all'Agente di inviare email automaticamente. ### Conclusione Dopo aver configurato tutte le sezioni: 1. Rivedi le impostazioni selezionate; 2. Fai clic su "Crea Agente" per creare il tuo Agente. La creazione di un Agente è il primo passo verso un'esperienza di assistenza virtuale personalizzata. Prova diverse configurazioni per trovare quella più adatta alle tue esigenze. 🚀 # Importazione rapida di documenti Ora che hai creato il tuo Agente, dovrai istruirlo, cioè insegnargli tutto ciò che deve sapere per rispondere alle domande e alle richieste degli utenti. Esistono [diversi modi per istruire il tuo Agente](https://github.com/memori-ai/docs/blob/main/agent-training/how-to-train-an-agent-overview.md). Per ora, vediamo come farlo facilmente importando un documento PDF: 1. Vai al pannello di gestione dell'Agente in cui vuoi importare il PDF; 2. Dalla barra laterale, seleziona "**Import/Export**"; 3. Seleziona il file PDF che vuoi caricare; 4. Lascia tutte le impostazioni invariate e fai clic sul pulsante "Import" nell'angolo in basso a destra; ✅ Fatto! AIsuru sta ora importando tutte le conoscenze dal tuo documento. #### Testa il tuo Agente Anche mentre l'importazione è in corso, puoi già testare il tuo Agente. Tieni presente, però, che dovrai attendere il completamento del processo prima che il tuo assistente conosca tutto il contenuto del tuo documento PDF. 1. Nella barra laterale del pannello di gestione dell'Agente, fai clic su **"Prova"** (il primo pulsante visualizzato); 2. Si aprirà direttamente una chat, in cui potrai conversare con il tuo Agente; 3. Prova a porre alcune domande per verificare che risponda correttamente in base ai contenuti che hai caricato. # Condivisione Ora che hai creato e addestrato il tuo primo Agente, è il momento di condividerlo con il mondo. AIsuru offre diverse opzioni per controllare chi può interagirci. Una volta creato il tuo Agente, sei pronto a condividerlo: * Vai al pannello di gestione dell'Agente che vuoi condividere; * Dalla barra laterale, vai alla sezione "Condividimi"; * Attiva o disattiva l'opzione "Mostra in homepage" → * Se è attivata → gli utenti potranno trovare e provare il tuo Agente direttamente dalla homepage; * Se è disattivata → gli utenti non vedranno il tuo Agente nella homepage, ma chiunque abbia il link potrà comunque accedere e usare il tuo assistente. * **Copia il tuo link** (privato o pubblico) facendo clic su questo pulsante: * **Condividi l'Agente con chi vuoi**. {% hint style="info" %} **Se l'Agente è privato, agli utenti verrà richiesta la password**. Non è mai possibile accedere a un Agente protetto senza inserire la password, anche se è mostrato nella homepage. {% endhint %} # Video riassuntivo Qui sotto trovi un video che mostra come fare tutto ciò che hai visto in meno di 6 minuti 👇 {% embed url="" %} Come creare la tua IA da un documento in meno di 6 minuti con [aisuru.com](https://www.aisuru.com/) {% endembed %} # Gestione dell'account La gestione dell'account ti consente di controllare le impostazioni personali, le preferenze di notifica e i dati di accesso. ### Accesso alle impostazioni dell'account Per gestire il tuo account, hai due opzioni: 1. Seleziona **Account** dalla barra laterale; 2. Fai clic sul tuo nome utente nell'angolo in alto a destra, quindi seleziona "Account". ### Scheda principale "Account" Nella scheda "Account" troverai tre sottosezioni 👇 #### Crediti Facendo clic sul pulsante "Acquista crediti", puoi **acquistare crediti per la piattaforma**. Puoi scoprire di più su [come funzionano i crediti e come vengono consumati](https://github.com/memori-ai/docs/blob/main/analytics/usage/README.md) nella sezione dedicata ai consumi. #### **Impostazioni account e privacy** In questa sezione puoi: * Visualizzare il tuo nome utente (non modificabile); * Visualizzare la tua data di nascita (non modificabile); * **Visualizzare il tuo indirizzo email** (non modificabile); * Accettare i termini di servizio e l'informativa sulla privacy (obbligatori al momento della registrazione e non modificabili); * Visualizzare l'informativa sull'uso dei cookie. * **Accetta o rifiuta i termini del Pensiero Profondo** per la personalizzazione dell'esperienza usando l'apposita casella di controllo (facoltativo). Per salvare le modifiche alle informazioni del profilo, fai clic sul pulsante "**Salva le modifiche**". #### **Autenticazione con codice OTP** Questa sezione ti consente di generare un codice OTP per accedere rapidamente al tuo account. È richiesto quando accedi da un dispositivo VR. Puoi generare il codice facendo clic su "Genera codice". #### Eliminazione dell'account Per eliminare il tuo account, fai clic sul pulsante rosso Elimina. Per eliminare il tuo account, devi prima eliminare tutti i tuoi Agenti. {% hint style="danger" %} **L'eliminazione dell'account è irreversibile** e comporterà la perdita di tutti i tuoi dati, inclusi Agenti e contenuti. {% endhint %} ### Avatar Nella scheda "Avatar" puoi: * **Visualizza la tua immagine del profilo attuale**; * Modifica l'immagine usando il pulsante **Modifica**; * Rimuovi l'immagine usando il pulsante **Elimina**. ### Notifiche Qui puoi scegliere se ricevere aggiornamenti dai tuoi Agenti e con quale frequenza: * Frequenza delle notifiche email: oraria, giornaliera, settimanale o mai; * Numero minimo di messaggi prima dell'invio di una notifica (1, 3, 5, 10). Fai clic su "Salva" per salvare le modifiche: d'ora in poi, **queste preferenze verranno applicate automaticamente ai nuovi Agenti che creerai**. Puoi anche applicare queste impostazioni a tutti i tuoi Agenti esistenti attivando l'opzione "Applica a tutti gli agenti". A seconda delle impostazioni che scegli, potresti ricevere email periodiche dal tuo Agente con un riepilogo delle domande poste e un file di testo contenente le conversazioni avute dagli utenti. {% hint style="info" %} Se preferisci ricevere notifiche solo da Agenti specifici, vai al pannello di gestione dell'Agente desiderato, seleziona "Impostazioni" nella barra laterale e configura le tue preferenze nella sezione "[Notifiche](https://github.com/memori-ai/docs/blob/main/analytics/agent-analysis/notification-preferences.md)" per quello specifico Agente. {% endhint %} # 2. Istruzione dell'Agente e gestione dei Contenuti Ora che hai creato il tuo primo Agente, è il momento di insegnargli tutto ciò che deve sapere. In questa sezione, esploreremo i diversi modi per istruire il tuo Agente e gestire i suoi contenuti, trasformandolo in un assistente IA davvero utile e personalizzato. Ecco cosa imparerai in questo capitolo: * [**Come istruire il tuo Agente**](/istruzione-gestione-contenuti-agenti/come-istruire-un-agente-panoramica-dei-metodi) usando diversi metodi; * **Come usare il** [**dizionario**](/istruzione-gestione-contenuti-agenti/dizionario) per migliorare la comprensione del tuo Agente; * Come sfruttare le **funzionalità avanzate**, come [gli snippet di codice](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice), [l'HTML nei messaggi](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/html-messaggi) e [la personalizzazione delle risposte in base a ruolo, data e luogo](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente). # Come istruire un Agente: panoramica dei metodi Istruire il tuo Agente è fondamentale per ottenere risposte accurate e pertinenti. AIsuru ti mette a disposizione diversi strumenti per arricchire la base di conoscenze del tuo assistente, ciascuno adatto a esigenze diverse: * [**Istruiscimi**](/istruzione-gestione-contenuti-agenti/istruiscimi-insegna-nuove-informazioni-allagente-chiacchierando): una sezione in cui puoi istruire la tua IA semplicemente conversando; * [**Contenuti**](/istruzione-gestione-contenuti-agenti/contenuti): insegna all'IA come rispondere a domande o argomenti specifici; * [**Importazione di documenti**](/istruzione-gestione-contenuti-agenti/importazione-di-documenti): insegna al tuo Agente conoscenze specifiche importando documenti di testo. Di seguito puoi esaminare nel dettaglio ciascuno di questi metodi. # Istruiscimi: istruisci il tuo Agente attraverso la conversazione "Istruiscimi" è una potente funzionalità di AIsuru che semplifica l'addestramento del tuo Agente: puoi istruirlo su tutto ciò che desideri attraverso una conversazione naturale. Questo metodo intuitivo ti consente di [creare contenuti](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti) semplicemente chiacchierando con l'IA, rendendo il processo di apprendimento rapido ed efficace. ### Come accedere alla sezione Istruiscimi Per iniziare: 1. Vai al **pannello di gestione del tuo Agente;** 2. Seleziona **Istruiscimi** nella barra laterale; 3. **Inizia a conversare con l'Agente** come se stessi affiancando un nuovo collega. Il sistema analizzerà automaticamente la conversazione e creerà nuovi contenuti in base alle informazioni che fornisci. ### Buone pratiche Per ottenere i migliori risultati: 1. **Sii chiaro e conciso** nelle tue spiegazioni; 2. Se vuoi "forzare l'apprendimento", **chiedi all'Agente di aggiungere un'informazione specifica ai suoi contenuti.** ### Considerazioni importanti Quando utilizzi Istruiscimi, tieni presente: * **La coerenza** tra sessioni diverse è fondamentale; * È consigliabile **rivedere i contenuti creati automaticamente** per assicurarti che siano accurati. * Per informazioni altamente tecniche o strutturate, l'importazione diretta di un documento potrebbe essere più efficace. # Contenuti **I contenuti sono il cuore del tuo Agente** su AIsuru. Questa sezione ti guiderà nella creazione, gestione e ottimizzazione dei contenuti affinché il tuo assistente virtuale fornisca risposte accurate e personalizzate. In questa sezione tratteremo: 1. [**Creazione manuale dei contenuti**](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti): come strutturare e inserire le informazioni di base per il tuo assistente; 2. [**Validazione e correzione dei contenuti**](/istruzione-gestione-contenuti-agenti/contenuti/validazione-e-correzione-dei-contenuti): tecniche per garantire l'accuratezza e la coerenza delle tue informazioni; 3. [**Modifica e aggiornamento dei contenuti**](/istruzione-gestione-contenuti-agenti/contenuti/modifica-e-aggiornamento-dei-contenuti): come mantenere i tuoi contenuti aggiornati e pertinenti. Che tu stia creando un assistente per il servizio clienti, un tutor virtuale o un compagno di conversazione, questa guida ti fornirà le competenze per creare contenuti di qualità che arricchiscono l'esperienza dei tuoi utenti. # Cosa sono i contenuti e perché sono importanti AIsuru ti consente di arricchire la base di conoscenza del tuo Agente con informazioni precise e personalizzate attraverso i contenuti. Questa funzionalità è essenziale per creare un'IA conversazionale davvero su misura per le tue esigenze. ### Cosa sono i contenuti? I "contenuti" sono **coppie di domande e risposte che l'Agente utilizza per rispondere agli utenti**. Avere più contenuti aumenta l'accuratezza e la precisione del tuo Agente. ### Perché sono così importanti? Quando un utente pone una domanda al tuo Agente, utilizzerà tutti gli strumenti a sua disposizione per rispondere: 1. **I contenuti vengono prima di tutto**: se la domanda dell'utente è molto simile a una già presente nei contenuti, AIsuru risponderà con la risposta già salvata in quel contenuto; 2. **Se AIsuru non riesce a trovare un contenuto corrispondente, passerà i contenuti più rilevanti all'IA generativa**, che risponderà in base a: [istruzioni](/ai-generativa/prompt-engineering), [contenuti rilevanti](/istruzione-gestione-contenuti-agenti/contenuti) e [funzioni](/avanzate/integrazioni/funzioni) [(avanzate).](/avanzate/integrazioni/funzioni) {% hint style="info" %} Creare e mantenere i contenuti è essenziale per **migliorare la qualità delle risposte del tuo Agente**. {% endhint %} ### Soglia di confidenza per i contenuti La **soglia di confidenza** è un parametro che determina quanto l'Agente debba essere sicuro di aver trovato il contenuto giusto prima di fornire una risposta basata sui contenuti. **Come funziona:** * **Soglia bassa**: l'Agente risponderà anche con contenuti che corrispondono solo parzialmente alla domanda dell'utente; * **Soglia alta**: l'Agente risponderà solo quando sarà molto sicuro che i contenuti siano pertinenti alla richiesta. **Quando modificarla:** * **Aumenta la soglia** se noti che l'Agente fornisce risposte poco pertinenti o errate; * **Diminuisci la soglia** se l'Agente dice troppo spesso "non so", anche per domande a cui dovrebbe saper rispondere. **Come configurarla:** 1. Vai alle **Impostazioni del tuo Agente;** 2. Seleziona la sezione **Generali**; 3. Trova "**Soglia di confidenza**" e scegli il livello desiderato: Molto bassa, Bassa, Normale, Alta, Molto alta. {% hint style="info" %} **NOTA**: modificare la soglia di confidenza può influire significativamente sulla qualità delle risposte. Ti consigliamo di testare attentamente il tuo Agente dopo ogni modifica e di apportare regolazioni graduali. {% endhint %} # Creazione manuale di contenuti Ora che hai visto cosa sono i contenuti e perché sono utili, puoi dare un'occhiata a come crearli. Prima di tutto, è importante esaminare **la struttura di un contenuto,** quali campi contiene e a cosa servono. ### Struttura di un contenuto Un contenuto in AIsuru è organizzato in sezioni chiaramente etichettate nell'interfaccia: * **Domanda** (testo, obbligatorio): la domanda principale che attiverà questo contenuto; * **Varianti di domanda** (testo multiplo): altri modi di formulare la stessa domanda per migliorare il riconoscimento; * **Risposte** (testo, obbligatorio): la risposta principale e tutte le risposte alternative; * **Assegnato a** (menu a tendina): controlla chi può visualizzare il contenuto ("Pubblico" o ruoli specifici); * **Non casuale** (casella di controllo): esclude la domanda dall'essere suggerita durante l'inattività dell'utente; * **Luogo e data** (pulsanti): limita la visibilità in base all'area geografica o al periodo di tempo; * **Media** (area di caricamento): spazio per allegare immagini, video o PDF; * **Link** (area di inserimento): aggiunge URL esterni alla risposta; * **Avanzate** (sezioni espandibili): suggerimenti, tag, variabili di contesto, snippet eseguibili, timeout e integrazione DCM. ### Come creare un contenuto semplice 1. Vai al pannello di gestione del tuo Agente; 2. Fai clic su **Contenuti** nella barra laterale; 3. Fai clic sul pulsante "**Nuovo contenuto**"; 4. Compila i campi richiesti: 1. **Domanda**: inserisci la domanda a cui il tuo Agente dovrà rispondere; 2. **Risposta**: inserisci la risposta che il tuo Agente dovrà dare (includi tutte le informazioni necessarie). Ecco fatto! Fai clic su "Conferma" in basso a destra per salvare il tuo contenuto. ### Altre impostazioni Ci sono altre impostazioni che possono tornare utili in diversi scenari. #### Varianti di domanda In questa sezione, che si trova subito sotto la domanda, puoi aggiungere varianti di domanda, ovvero: * **Altri modi di formulare la stessa domanda:** *"come si chiama il cane?"* come domanda e *"come si chiama il cane?"* come variante; * **Altre domande che hanno la stessa risposta:** *"Dove devo andare per rinnovare la carta d'identità?"* e *"Dove devo andare per rinnovare la carta d'identità a Roma?"* come variante di domanda. {% hint style="info" %} Le varianti di domanda aiutano **AIsuru a trovare facilmente i contenuti più rilevanti** con cui rispondere. {% endhint %} Non ti vengono in mente varianti di domanda? Lasciati aiutare da AIsuru: fai clic sul pulsante "**Suggerisci varianti**" e AIsuru genererà varianti di domanda in base alla risposta del contenuto, che deve già essere compilata. #### Risposte aggiuntive In questa sezione, che si trova subito sotto il campo "Risposta", puoi aggiungere risposte alternative per la stessa domanda. Questo ti consente di avere "varianti di risposta" per ogni domanda. Ad esempio: * Domanda: *"Qual è la capitale d'Italia?";* * Risposta: *"Roma";* * Risposta aggiuntiva: *"La capitale d'Italia è Roma";* * Risposta aggiuntiva: *"La capitale è Roma".* Se un utente chiede al tuo Agente *"Qual è la capitale d'Italia?"*, potrebbe ricevere una qualsiasi di queste risposte: *"Roma"*, *"La capitale d'Italia è Roma"*, oppure *"La capitale è Roma".* {% hint style="info" %} Aggiungi risposte aggiuntive se non fai ampio affidamento sull'IA generativa ma vuoi comunque **ridurre la ripetitività e rendere più naturali le interazioni del tuo Agente**. {% endhint %} Proprio come per le varianti di domanda, puoi anche lasciare che l'IA suggerisca risposte aggiuntive: fai clic sul pulsante **Suggerisci risposta** e AIsuru genererà una risposta in base alla domanda, che deve essere già compilata. #### Media e link Puoi aggiungere media e link ai tuoi contenuti: * **Media:** immagini, video e documenti PDF; * **Link:** aggiungi un URL e personalizza il nome della pagina. {% hint style="info" %} I media e i link arricchiscono le risposte dell'Agente, consentendogli di mostrare immagini o fornire risorse aggiuntive durante la conversazione. {% endhint %} Se un utente chiede *"Qual è la capitale italiana?"*, AIsuru risponderà *"Roma"* (o una variante) e allegherà l'immagine che hai aggiunto alla risposta. Il modello linguistico può scegliere o meno di mostrare media e link quando risponde agli utenti. Puoi modificare questo comportamento nelle [altre impostazioni dell'IA generativa](/ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa). #### Altri campi Sotto il campo "Assegnato a", troverai tre opzioni importanti che influenzano il comportamento del contenuto: 1. **Non casuale**: se selezionata, impedisce che la domanda venga suggerita casualmente quando un utente rimane inattivo troppo a lungo. Utile per contenuti che non avrebbero senso come suggerimenti casuali. {% hint style="info" %} Se vuoi che il tuo Agente ponga agli utenti domande "casuali", puoi attivare l'interruttore "Suggerisci domande se l'utente è inattivo" in Impostazioni > Generali > Impostazioni avanzate. Per saperne di più, leggi [come utilizzare il timeout](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout). {% endhint %} #### Impostazioni avanzate Per impostazioni più complesse, vai alla pagina dedicata alla [personalizzazione dei contenuti](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti): qui scoprirai come personalizzare le risposte in base al ruolo, alla data o alla posizione, come eseguire [snippet](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice)[ di](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice)[ codice eseguibili](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice) e molto altro! # Convalida e correzione dei contenuti AIsuru ti offre un potente strumento per migliorare continuamente la conoscenza del tuo Agente validando e correggendo i contenuti generati dall'IA. ### Perché è importante validare le risposte? Validare le risposte offre al tuo Agente **una base di conoscenza più ampia e ricca**: i contenuti validati diventano parte della conoscenza del tuo Agente! Aggiungere nuovi contenuti o [varianti di domanda](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#question-variants) aiuta il tuo Agente **a trovare più facilmente la risposta giusta alle domande dei tuoi utenti**, migliorandone l'esperienza. ### Dove posso validare le risposte? 1. Vai al pannello di gestione del tuo Agente; 2. Nella barra laterale, fai clic su **Contenuti;** 3. Fai clic sulla scheda "**Generato dall'IA**". ### Cosa posso fare qui? Nella tabella troverai tutte le domande poste dagli utenti a cui ha risposto l'IA generativa. Nella categoria **"Azioni"** troverai diverse opzioni:
PulsanteDescrizioneQuando utilizzarlo
Ricerca nelle conversazioniApre la conversazione in cui è stata posta la domandaPer comprendere meglio il contesto in cui è stata posta una domanda
ConfermaConvalida la domanda e la risposta fornita dall'IA generativaQuando tutte le informazioni sono corrette: domanda, risposta, argomenti necessari e assegnazione del Ruolo
Aggiungi come variante di domandaAggiunge la domanda dell'utente come variante di un contenuto esistenteSe hai già un contenuto che risponde alla domanda dell'utente, ma l'Agente ha risposto male
ModificaApre un pannello in cui puoi modificare completamente il contenuto prima di convalidarloSe vuoi modificare la domanda, la risposta o aggiungere personalizzazioni prima della convalida
EliminaRimuove il contenuto dalla tabellaQuando non esiste una risposta corretta a una domanda specifica o la domanda non è utile
{% hint style="info" %} Nota: le risposte generate dall'IA più lunghe di 10.000 caratteri non vengono salvate in questa tabella. {% endhint %} ### Impostazione automatica del contesto in base all'URL AIsuru ricorda automaticamente da quale pagina (URL) è stata posta una domanda e la imposta come argomento necessario. Questo consente all'Agente di fornire risposte diverse a seconda della pagina in cui si trovava l'utente quando ha interagito con esso. Per ogni contenuto nella sezione "Generati dall'IA", troverai due argomenti necessari impostati automaticamente: 1. ROUTE:\[AGENT\_NAME] 2. PATHNAME:\[PATH\_LINK] Questi argomenti consentono all'Agente di contestualizzare le risposte in base alla provenienza della domanda. **Se vuoi disabilitare questa funzionalità, dovrai rimuovere entrambi gli argomenti necessari durante la convalida o la modifica del contenuto**. {% hint style="info" %} Non preoccuparti se dimentichi di rimuovere gli argomenti necessari: **riceverai un avviso prima di salvare** che ti informerà della loro presenza. {% endhint %} ### Contenuti duplicati È importante che i contenuti del tuo Agente non siano duplicati o contraddittori: i contenuti devono essere chiari e non ridondanti. ### Considerazioni finali La convalida delle risposte generate dall'IA è un processo cruciale per migliorare continuamente le prestazioni del tuo Agente. Dedicandovi regolarmente un po' di tempo, non solo amplierai la base di conoscenze del tuo assistente, ma ne affinerai anche l'accuratezza e la pertinenza. Presta attenzione al contesto automatico basato sull'URL: consente risposte più mirate, ma può essere disabilitato se non è necessario per il tuo caso d'uso specifico. Assicurati di sfruttare al meglio questo strumento per creare un Agente in costante miglioramento e allineato alle esigenze dei tuoi utenti. # Modifica e aggiornamento dei contenuti Ecco una panoramica delle principali funzionalità per modificare e aggiornare i tuoi contenuti! ### Visualizzazione e ricerca dei contenuti Per cercare contenuti specifici: 1. **Vai al pannello di gestione del tuo Agente;** 2. Apri la sezione **Contenuti** (nella barra laterale); 3. Digita le parole chiave nella **barra di ricerca** nella parte superiore della pagina dei contenuti; 4. (Facoltativo) fai clic sul pulsante **Filtri** per accedere alle **opzioni di filtro avanzate**: i filtri disponibili ti consentono di cercare contenuti accessibili con: 1. Media; 2. Cerca per [contesto;](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette) 3. Argomenti impostati; 4. [Una data specifica;](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente) 5. Tag; 6. Ruoli (Assegnati a) Cerca per contesto. Tutti i contenuti sono organizzati in una tabella che puoi ordinare come preferisci: ti basta fare clic sull'intestazione della colonna desiderata. Le colonne mostrano: * **Domanda / Titolo**: la domanda principale che attiva questo contenuto; * **Occorrenze**: quante volte l'Agente ha utilizzato questo contenuto per rispondere agli utenti (questo non si applica alle risposte generate dall'IA). * **Risposta**: cosa dirà l'Agente quando riconosce questa domanda; * **Proprietà**: una o più icone che indicano se il contenuto è "non casuale", contiene elementi multimediali, link o script eseguibili; * **Creato il**: quando è stato creato il contenuto. Se fai clic sull'icona accanto alla data, puoi vedere: * Chi ha creato il contenuto e quando; * Se qualcuno lo ha modificato, chi è stato e quando. * **Azioni**: qui puoi modificare, duplicare o eliminare il contenuto. In basso a destra troverai anche un selettore per scegliere quanti contenuti visualizzare per pagina (il valore predefinito è 10). {% hint style="info" %} Se i contenuti sono stati [importati da un documento](/istruzione-gestione-contenuti-agenti/importazione-di-documenti) vedrai un'ulteriore colonna "[**Tag**](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali#tag)". {% endhint %} ### Modifica dei contenuti Per modificare un contenuto esistente: 1. Nella tabella dei contenuti, **trova il contenuto che desideri modificare;** 2. Fai clic sul **pulsante Modifica** (nella colonna "Azioni" a destra) accanto al tuo contenuto; 3. Si aprirà un pannello di modifica identico al pannello di creazione.\ Qui puoi modificare tutti i campi: domanda, varianti di domanda, risposta, risposte aggiuntive, ecc. 4. Dopo aver apportato le modifiche, fai clic su "**Conferma**" in basso a destra per salvare; {% hint style="info" %} Ricorda che puoi usare il pulsante **"Espandi"** sulle risposte per visualizzare il testo completo prima di decidere se modificare un contenuto. {% endhint %} ### Duplicazione dei contenuti Per duplicare un contenuto, usa il pulsante nella colonna "Azioni". ### Eliminazione dei contenuti Per eliminare un singolo contenuto, fai clic sull'**icona rossa del cestino** nella colonna "Azioni". Per eliminare più contenuti contemporaneamente: 1. **Seleziona i contenuti** che desideri eliminare spuntando le caselle a sinistra di ogni riga; 2. In basso a sinistra apparirà un contatore "**Selezionati (X)**" che mostra il numero di elementi selezionati; puoi **farvi clic per eliminare i contenuti selezionati.** ### Quanti contenuti dovrebbe avere il tuo Agente? Definire un numero ideale di contenuti è complesso e dipende da molti fattori. Un Agente potrebbe fare maggiore affidamento sui contenuti, sulle istruzioni o sulle funzioni per rispondere alle domande degli utenti. In generale, consigliamo agli utenti meno esperti di mantenere il numero di contenuti al di sotto di 10.000. ### Importazione / Esportazione (per utenti avanzati) Se devi gestire grandi volumi di contenuti: 1. Vai alla sezione **Importazione / Esportazione** dalla barra laterale. 2. Segui le istruzioni nella [guida al backup dell'Agente](/avanzate/backup-trasferimento-e-cancellazione-di-un-agente) per scoprire come importare / esportare file CSV. {% hint style="danger" %} Utilizzare correttamente le funzionalità di importazione/esportazione richiede una solida comprensione della struttura dei dati di AIsuru. {% endhint %} # Come AIsuru trova le risposte Quando un utente pone una domanda al tuo Agente, AIsuru utilizza un **sistema di ricerca semantica avanzato** per trovare la risposta più pertinente. Comprendere questo processo ti aiuterà a ottimizzare i tuoi contenuti per ottenere risposte sempre più precise e utili. ### Il processo di ricerca semantica #### 1. Trasformazione in vettori Ogni volta che crei un contenuto o un utente pone una domanda, AIsuru converte il testo in una rappresentazione numerica chiamata **vettore** (embedding). Questi vettori catturano il significato semantico delle parole e delle frasi, permettendo al sistema di comprendere il contesto e l'intento alla base di un messaggio. #### 2. Ricerca per similarità Quando un utente fa una domanda, il sistema: * Converte la domanda in un vettore; * Confronta questo vettore con tutti i vettori dei contenuti disponibili; * Calcola la similarità semantica per trovare i contenuti più pertinenti. #### 3. Risposta intelligente In base ai risultati della ricerca, AIsuru adotta una delle due strategie: **Corrispondenza diretta**: Se trova una domanda molto simile nei tuoi contenuti, fornisce immediatamente la risposta associata. Questo garantisce risposte rapide e precise per le domande comuni. **Assistenza dell'IA generativa**: se non trova una corrispondenza stretta, seleziona i contenuti più simili e li passa all'IA generativa, che formula una risposta personalizzata utilizzando le informazioni più pertinenti. ### Tecnologia NLP proprietaria di AIsuru Questo processo è alimentato dal **Natural Language Processing (NLP) proprietario di AIsuru**, che offre: * **Comprensione semantica**: va oltre la semplice corrispondenza di parole chiave per comprendere il reale significato delle domande; * **Flessibilità linguistica**: riconosce domande formulate in modi diversi ma con lo stesso significato; * **Supporto multilingue**: funziona efficacemente in lingue diverse; * **Apprendimento continuo**: migliora costantemente la precisione della ricerca. ### Vantaggi per i tuoi utenti Questo sistema avanzato garantisce: * **Risposte precise**: trova sempre le informazioni più pertinenti; * **Esperienza naturale**: gli utenti possono porre domande usando le proprie parole; * **Risposte rapide**: processo ottimizzato per prestazioni rapide; * **Coerenza**: mantiene la qualità delle risposte anche con grandi volumi di contenuti. ### Consigli per ottimizzare i tuoi contenuti Per sfruttare al meglio questo sistema: 1. **Varia le domande**: crea diverse varianti per lo stesso argomento. 2. **Usa un linguaggio naturale**: scrivi come parlano realmente i tuoi utenti; 3. **Includi i sinonimi**: includi termini alternativi per gli stessi concetti; 4. **Esegui test regolarmente**: verifica che le risposte siano pertinenti nelle conversazioni reali. Il sistema di ricerca semantica di AIsuru è il cuore tecnologico che rende i tuoi Agenti davvero intelligenti e utili. # Importazione di documenti L'importazione di documenti in AIsuru è un processo fondamentale per arricchire le conoscenze del tuo assistente virtuale. Questa funzionalità ti consente di trasformare rapidamente documenti esistenti in una base di conoscenze interattiva e interrogabile. In questa sezione, tratteremo: * Come [importare efficacemente documenti testuali](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali) in vari formati; * [Strategie per gestire le immagini](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/gestione-delle-immagini-nei-documenti) presenti nei documenti. Che tu stia creando un assistente per il supporto tecnico, uno strumento per la formazione aziendale o un sistema di gestione della conoscenza, l'importazione di documenti in AIsuru ti offre un modo rapido ed efficiente per creare una solida base di conoscenze. # Come funziona l'importazione di documenti L'importazione di documenti in AIsuru è un processo potente che ti permette di arricchire rapidamente la conoscenza del tuo Agente. Trasforma i tuoi documenti in una serie di coppie di domande e risposte, creando una base di conoscenza interattiva e interrogabile. Ecco come funziona. ### Il processo di importazione 1. **Carica il documento**: carica il tuo documento nella sezione Import / Export del tuo Agente; 2. **Analisi e suddivisione**: AIsuru analizza il contenuto del documento e lo suddivide in paragrafi distinti; 3. **Generazione di coppie di domande e risposte** ([contenuti](/istruzione-gestione-contenuti-agenti/contenuti)): per ogni paragrafo, AIsuru utilizza l'IA generativa per generare una o più coppie di domande e risposte. Il numero di contenuti varia in base al documento e all'[impostazione di granularità](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali). I contenuti vengono creati nella lingua dell'Agente, quella impostata al momento della creazione dell'Agente. ### Vantaggi dell'importazione di documenti * **Risparmio di tempo**: trasforma rapidamente grandi quantità di informazioni in conoscenza che il tuo Agente può utilizzare; * **Coerenza**: le risposte generate si basano direttamente sui tuoi documenti, garantendo accuratezza e coerenza; * **Flessibilità**: puoi importare diversi tipi di documenti per coprire un'ampia gamma di argomenti. ### Limitazioni da tenere presenti Sebbene l'importazione di documenti sia uno strumento potente, ci sono alcune limitazioni che vale la pena conoscere: * **Immagini e video**: al momento, AIsuru non può interpretare o elaborare immagini e video nei documenti; l'importazione si concentra esclusivamente sul testo; * **Tipi di file supportati**: AIsuru supporta principalmente l'importazione di file di testo semplice o semi-semplice. Altri formati (come JSON) potrebbero richiedere un approccio diverso, come l'uso di [funzioni](/avanzate/integrazioni/funzioni) o [MCP.](/avanzate/integrazioni/model-context-protocol-mcp-su-aisuru/mcp-cosa-sono-e-come-si-utilizzano) * **Contenuto PDF non selezionabile**: se carichi un PDF che contiene principalmente immagini o testo non selezionabile (come documenti scansionati), AIsuru non sarà in grado di estrarre ed elaborare efficacemente il contenuto. ### Consigli per un'importazione efficace * Usa **documenti ben strutturati con testo selezionabile** per ottenere i migliori risultati; * Dopo l'importazione, **rivedi e affina manualmente i contenuti generati** per garantire la massima qualità e rilevanza. L'importazione di documenti è un ottimo punto di partenza per costruire la base di conoscenza del tuo Agente. Quando la combini con altri metodi di istruzione (come la conversazione diretta e la creazione manuale di contenuti), puoi creare un assistente IA davvero completo e ben informato. # Importare documenti testuali AIsuru ti consente di importare documenti testuali e trasformarli automaticamente in conoscenza per il tuo Agente. Questo processo ti permette di arricchire rapidamente la base di conoscenza del tuo assistente virtuale generando coppie di domande e risposte pertinenti dal contenuto dei tuoi documenti. ### Documenti supportati **I formati supportati** includono: PDF (.pdf), testo semplice (.txt), Microsoft Word (.doc,.docx), Apple Pages (.pages), OpenDocument (.odt), Rich Text Format (.rtf), HTML (.html). **AIsuru supporta la tecnologia OCR**, ma per ottenere risultati ottimali consigliamo di caricare documenti con testo già selezionabile. L'OCR funziona meglio su documenti ben scansionati con testo chiaro, ma potrebbe avere difficoltà con scansioni di bassa qualità o formattazioni complesse. ### Importare funzionalità da altri Agenti Oltre all'importazione di documenti, AIsuru ti consente anche di importare funzionalità complete dagli altri tuoi Agenti. Tramite la scheda **"Importa da un altro agente"** puoi: * Copiare [**funzioni avanzate**](/avanzate/integrazioni/funzioni/funzioni-avanzate) con tutte le relative configurazioni; * Importare [**intenti dinamici**](/avanzate/integrazioni/intenti-dinamici) e i relativi **slot;** * Trasferire il [**dizionario personalizzato.**](/istruzione-gestione-contenuti-agenti/dizionario) Questa funzionalità è particolarmente utile quando vuoi replicare configurazioni complesse tra Agenti simili o creare backup delle tue implementazioni. Per maggiori dettagli, consulta la guida sulla copia di intenti dinamici, slot e funzioni da un altro Agente. ### Accedere alla sezione di importazione 1. **Vai al pannello di gestione del tuo Agente;** 2. Seleziona **Import / Export** nella barra laterale; 3. Puoi fare clic su "Click or drag file" o trascinare un file in quest'area per caricare un documento; 4. Una volta caricato il documento, scorri verso il basso per visualizzare un'anteprima del testo estratto e regolare le varie impostazioni di importazione. Troverai due sezioni: 1. Opzioni di importazione; 2. Variabili di contesto. ### Opzioni di importazione #### Scelta di cosa importare Dopo aver caricato il documento, puoi selezionare: * **Importa solo i nuovi contenuti**: se vengono generate domande simili a quelle esistenti, AIsuru non le importerà; * **Importa tutti i contenuti**: importa l'intero contenuto del documento, anche se esistono già domande simili. #### Personalizzazione dei contenuti Puoi scegliere, selezionando la casella, se impostare tutti i contenuti come: * **Non casuale**: le domande non verranno suggerite casualmente durante l'inattività dell'utente (per saperne di più, vai alla sezione relativa al [timeout](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout)); * **Conclusiva:** la risposta non è seguita da ulteriori domande (ad esempio, "C'è qualcos'altro che vuoi sapere?"). Puoi anche **aggiungere un link a tutte le domande importate** (ad esempio, un link al file originale, così la fonte è sempre accessibile). #### **Altre impostazioni** Nelle opzioni di importazione, puoi anche regolare la granularità: **questa impostazione controlla quante coppie di domande e risposte vengono generate per paragrafo**. Puoi impostare: * **Bassa:** meno contenuti per paragrafo, più rapida da elaborare e utile per testi discorsivi o narrativi; * **Media:** l'opzione consigliata, genera un numero moderato di contenuti; * **Alta:** genera molti contenuti per paragrafo, richiede più tempo ma è molto utile per testi densi di informazioni con molti concetti. {% hint style="info" %} Per ottenere i migliori risultati, **ti consigliamo di impostare la granularità su alta**. {% endhint %} Successivamente, ci sono le **istruzioni per la generazione delle domande**. Questo campo serve per **guidare l'IA generativa nel modo in cui creerà le domande**: è fondamentale per ottenere coppie di domande e risposte pertinenti e di alta qualità. Nelle istruzioni devi fornire: * un breve **contesto sul documento**: di cosa tratta? A cosa serve; * un breve **contesto sull'utente finale**: chi è? Quali tipi di domande pone? Quale linguaggio usa; * alcune **regole e istruzioni chiare e concise** per generare le domande. Esempio: ``` This document describes company policies for workplace safety. Instructions for question generation: - Create questions covering the main safety topics mentioned in the document; - Include questions about specific procedures, safety equipment, and employee responsibilities; - Generate questions that test understanding of the consequences of not following safety rules; - Create some scenario-based questions that require applying the policies to real situations. ``` #### Titolo dell'allegato della fonte (facoltativo): Seleziona questa opzione se desideri includere il testo originale come allegato per ogni coppia di domande e risposte generata. ### Variabili di contesto Nella sezione delle variabili di contesto puoi aggiungere: tag, argomenti impostati, argomenti necessari e assegnare un Ruolo. #### Tag I tag sono come categorie che puoi assegnare ai tuoi contenuti. Se imposti un tag durante l'importazione di un documento, tutte le coppie di domande e risposte generate da quel documento verranno contrassegnate con tali categorie. Per impostazione predefinita, viene aggiunto un tag per identificare l'importazione; in questo modo, puoi sempre risalire ai contenuti provenienti da ciascun documento importato. Puoi rimuovere i tag facendo clic sull'icona rossa del cestino accanto a ciascuno, oppure fai clic su "Aggiungi" per aggiungerne uno nuovo. #### Imposta argomenti Aggiungi il [contesto da impostare](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette#set-context-and-required-context) quando l'utente pone domande specifiche. #### Argomenti necessari Gli utenti non avranno accesso alle coppie di domande e risposte create dall'importazione del documento, a meno che non abbiano prima impostato un argomento specifico. #### **Assegnato a** I contenuti estratti dal documento possono essere assegnati a un [**ruolo specifico**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici) o al **pubblico**. ### Avvio dell'importazione e Storico import Dopo aver configurato tutte le impostazioni, puoi avviare l'importazione facendo clic sul pulsante **Importa** in basso a sinistra. Dopo aver avviato l'importazione, avrai accesso a una nuova scheda nella sezione Import / Export: **Storico import**. Da questa sezione puoi vedere: * **L'avanzamento** dell'importazione avviata; * **Importazioni precedenti.** Per ogni importazione, puoi vedere: * Titolo del file; * Data di inizio e fine del processo; * Numero di domande importate; * Se fai clic su **"Dati e configurazione dell'importazione"** vedrai anche: * Dimensione del file; * Nome del file; * Se i contenuti sono impostati come non casuali; * Granularità; * Istruzioni per la generazione delle domande; * Titolo della fonte; * Gestione dei link. L'importazione di documenti testuali in AIsuru è un modo efficace e rapido per ampliare la base di conoscenze del tuo Agente. # Gestione delle immagini nei documenti Sebbene AIsuru non supporti l'importazione diretta di immagini dai documenti, esiste un modo per includere immagini nelle risposte del tuo Agente. Ciò ti consente di arricchire le interazioni con contenuti visivi, migliorando l'esperienza utente. ### Come aggiungere immagini alle risposte del tuo Agente Per includere immagini nelle risposte del tuo Agente, hai due opzioni: 1. (Consigliato) **Aggiungi immagini direttamente ai tuoi contenuti**: trova i contenuti pertinenti a una determinata immagine, modificali e allega l'immagine a ciascuno di essi; 2. (Avanzato) Crea un contenuto dedicato per ogni immagine: 1. **Domanda**: inserisci un titolo descrittivo per l'immagine; 2. **Varianti di domanda**: inserisci le domande per le quali desideri che venga visualizzata l'immagine; 3. **Risposta**: inserisci una descrizione completa dell'immagine; 4. **Media**: carica la tua immagine; 5. **Assicurati che la casella di controllo "**[**Disabilita l'estrazione automatica delle immagini dai contenuti**](/ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa#automatic-media-extraction)**" sia disabilitata (nelle Impostazioni del tuo Agente > IA)**: sarà quindi il modello linguistico a decidere quale immagine mostrare in base alla descrizione fornita (ovvero, la risposta nel tuo contenuto). {% hint style="danger" %} Se il tuo Agente ha più di 150 immagini, non consigliamo di utilizzare il secondo metodo. {% endhint %} ### Consigli per un uso efficace * Usa **immagini pertinenti e di alta qualità;** * **Fornisci descrizioni dettagliate e accurate** per ogni immagine; * **Testa regolarmente le risposte del tuo Agente** per assicurarti che le immagini vengano utilizzate in modo appropriato e aggiorna i contenuti secondo necessità. Integrando immagini nelle risposte del tuo Agente, puoi migliorare significativamente la qualità delle interazioni. Sebbene richieda un po' più di lavoro manuale, i vantaggi in termini di chiarezza e coinvolgimento degli utenti possono essere sostanziali. # Dizionario Il dizionario personalizzato di AIsuru è uno strumento potente che migliora la comprensione del linguaggio del tuo Agente. Ti consente di definire termini specifici, acronimi e frasi uniche per il tuo Agente. ### Accesso al dizionario Per accedere al dizionario personalizzato: 1. Vai al **pannello di gestione del tuo Agente;** 2. Nella barra laterale, fai clic su **Dizionario.** ### Gestione del dizionario #### Come aggiungere nuove parole 1. Dalla sezione principale ("Dizionario personalizzato"), fai clic sul pulsante **Nuova parola**; 2. Compila i campi: 1. **Parola:** inserisci la parola da definire; 2. **Definizione**: puoi scegliere di fornire un sinonimo, una definizione ricorsiva (parola\_da\_definire = parola\_nota - parte\_da\_rimuovere + parte\_da\_aggiungere, ad esempio "crederei" = "farei" - "fare" + "credere") oppure una definizione normale. 3. Fai clic su **"Conferma"** per aggiungere la parola al dizionario. #### Modifica delle voci esistenti 1. Trova nell'elenco la parola che desideri modificare; 2. Fai clic sull'icona "**modifica"** sul lato destro della tabella; 3. Aggiorna la definizione secondo necessità; 4. Salva le modifiche. ### Gestione delle parole non definite AIsuru ti aiuta a identificare i termini che potrebbero necessitare di una definizione: 1. Seleziona "**Parole non definite**" dal menu: accanto a questa voce, vedrai un badge con un numero che indica quante parole non hanno una definizione; 2. Esamina l'elenco delle parole identificate da AIsuru; 3. Per ogni parola pertinente: 1. Fai clic sul pulsante + per vedere dove è stata usata; 2. Fai clic su **Definisci** per definirla compilando i campi, quindi fai clic su Conferma. ### Importazione da un altro Agente Ecco istruzioni passo passo su come importare il dizionario da un altro Agente: 1. Vai alla sezione "Importa/Esporta"; 2. Seleziona la scheda **"Importa da un altro Agente"**; 3. Scegli l'Agente di origine e seleziona "Dizionario" dalle opzioni; 4. Puoi anche importare contemporaneamente funzioni, intenti e slot. {% hint style="info" %} Questa funzione è particolarmente utile per mantenere una terminologia coerente tra diversi Agenti. {% endhint %} ### Vantaggi del dizionario L'utilizzo del dizionario personalizzato di AIsuru offre diversi vantaggi: * **Migliora l'accuratezza** delle risposte dell'Agente. * Garantisce **una comprensione coerente dei termini specifici di un'organizzazione;** * **Riduce i malintesi e aumenta l'efficienza della comunicazione**. {% hint style="info" %} Il dizionario non viene utilizzato dall' [IA generativa](/ai-generativa): il suo unico scopo è **dare correttamente priorità ai contenuti**. {% endhint %} # Istruzione: sezione avanzata Questa sezione ti guiderà attraverso le funzionalità più avanzate per ottimizzare le interazioni e l'efficacia del tuo assistente virtuale. Tratteremo: * [**Personalizzazione dei contenuti**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti): come limitare la visibilità di determinati contenuti a utenti specifici e come gestire [i suggerimenti](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-suggerimenti), [i contesti](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette), [gli snippet di codice](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice) e [il timeout;](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout) * [**Importazione avanzata di documenti**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/importazione-avanzata-di-documenti): come creare una gerarchia di documenti e come importare un tipo di documento non supportato; * [**Messaggio di benvenuto**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/messaggio-di-benvenuto): come impostare un messaggio di benvenuto; * [**Risposte predefinite**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/risposte-predefinite): come configurare risposte automatiche per le situazioni in cui l'IA non può rispondere; * [**Mostrare HTML nei messaggi**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/html-messaggi): tecniche per arricchire visivamente le risposte del tuo Agente con elementi HTML. Che tu voglia migliorare l'esperienza iniziale dell'utente, integrare contenuti complessi o ottimizzare le prestazioni del tuo Agente, le funzionalità avanzate di AIsuru ti offrono gli strumenti per portare il tuo assistente IA a un livello superiore. # Personalizzazione dei contenuti In questa sezione, esplorerai diversi modi per personalizzare il modo in cui il tuo Agente interagisce con gli utenti. Troverai: 1. [**Assegnazione di contenuti a ruoli specifici**: ](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici)scopri come mostrare contenuti diversi a diversi tipi di utenti; 2. [**Personalizzazione delle risposte in base alla data e alla posizione dell'utente**:](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente) scopri come creare contenuti disponibili solo in determinati luoghi o durante specifici periodi di tempo; 3. [**Gestione dei suggerimenti**: ](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-suggerimenti)esplora come guidare la conversazione con opzioni predefinite; 4. [**Contesto: argomenti ed etichette**: ](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette)approfondisci la gestione del contesto della conversazione tramite argomenti ed etichette; 5. [**Gestione degli script eseguibili**: ](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice)scopri come integrare ed eseguire snippet di codice per creare interazioni avanzate; 6. [**Uso del timeout**:](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout) scopri come gestire efficacemente i periodi di inattività degli utenti. Queste funzionalità ti permetteranno di creare un'esperienza personalizzata e consapevole del contesto, adattando il comportamento del tuo Agente a esigenze e situazioni diverse. # Come assegnare contenuti a Ruoli specifici La personalizzazione dei contenuti basata sui Ruoli ti consente di creare esperienze su misura per diversi tipi di utenti, garantendo che ognuno riceva le informazioni più rilevanti per le proprie esigenze. ### Cosa sono i Ruoli in AIsuru I "Ruoli" in AIsuru **rappresentano ruoli o categorie di utenti**. È come avere una versione specializzata del tuo Agente per ogni gruppo di utenti. Ad esempio, puoi fare in modo che il tuo Agente: * Mostri la documentazione tecnica solo al team di "supporto"; * Offra promozioni speciali solo ai "nuovi clienti"; * Condivida report finanziari solo con i "manager". ### Come funziona l'attribuzione dei contenuti Dopo aver [creato un Ruolo](#what-are-roles-in-aisuru), puoi attribuirgli dei contenuti: 1. Vai alla sezione **Contenuti** del tuo Agente; 2. Crea un nuovo contenuto o modifica uno esistente; 3. Nel campo "**Assegnato a**", seleziona il Ruolo desiderato dal menu a tendina (per impostazione predefinita, i contenuti sono visibili a tutti con l'opzione "Pubblico"); 4. Salva il contenuto. {% hint style="info" %} Da questo momento, solo gli utenti associati a quel Ruolo potranno vedere quel contenuto specifico. {% endhint %} {% hint style="success" %} **Come funziona internamente?** Il tag del destinatario (il ruolo) viene passato all'LLM, che può comportarsi diversamente in base al ruolo, seguendo le [istruzioni](/ai-generativa/prompt-engineering). {% endhint %} ### Cosa succede agli altri utenti? Quando un utente senza le autorizzazioni necessarie pone una domanda relativa a contenuti riservati, l'Agente: 1. Cercherà innanzitutto contenuti pubblici simili a cui l'utente ha accesso; 2. Se non trova alternative pertinenti, utilizzerà l'IA generativa per fornire una risposta (passando solo i contenuti a cui l'utente ha accesso); 3. L'utente non saprà di non avere accesso a contenuti specifici, quindi l'Agente **non potrà mai rivelare nulla, nemmeno se indotto con l'inganno a provarci.** ### Suggerimenti per un uso efficace * Crea Ruoli per **gruppi di utenti con esigenze informative distinte;** * Usa **nomi chiari e descrittivi** per semplificare la gestione futura; * **Rivedi periodicamente le assegnazioni dei contenuti** per mantenerle aggiornate; * **Testa le risposte dell'Agente** con ruoli diversi per assicurarti che l'esperienza sia ottimale per tutti. # Personalizzare le risposte in base alla data e alla posizione dell'utente AIsuru ti permette di rendere il tuo Agente ancora più intelligente e consapevole del contesto personalizzando le risposte in base alla data e al luogo dell'utente. Questa funzionalità è particolarmente utile per creare esperienze interattive legate a eventi o luoghi specifici. ### Come funziona la personalizzazione L'Agente fornirà i contenuti solo quando le condizioni di data e/o luogo specificate sono soddisfatte. Per esempio: * Puoi mostrare determinati contenuti solo in **luoghi specifici;** * Puoi rendere disponibili le risposte solo in **date e orari specifici;** * Puoi **combinare entrambe le condizioni** per una personalizzazione ancora più precisa. #### Impostare un luogo Quando crei o modifichi un contenuto, nella sezione "**Luogo e data**" puoi fare clic sul campo **"Luogo"** per assegnare il contenuto a un luogo specifico: 1. Inserisci il nome del luogo o fai clic su "Usa la mia posizione"; 2. Regola il **raggio di incertezza** in base alle tue esigenze (da 0 a 100 km); 3. Verifica l'area selezionata sulla mappa. {% hint style="info" %} Per **rimuovere l'assegnazione di un luogo da un contenuto**, fai clic su **Elimina** sotto la mappa. {% endhint %} #### Impostare una data Nella stessa sezione puoi definire il periodo di validità del contenuto: 1. Fai clic sul pulsante "**Data**" nella sezione "**Luogo e data**" dei tuoi contenuti; 2. Specifica l'intervallo temporale utilizzando il calendario che si apre quando fai clic sui campi "Da" e "A". La data selezionata verrà mostrata in questo formato: DD/MM/YYYY HH:mm; 3. Usa **Elimina** per rimuovere le date impostate. ### Esempi di utilizzo #### Personalizzazione basata sul luogo Ideale per: * **Musei**: crea contenuti specifici per ogni sala o esposizione; * **Cacce al tesoro**: fornisci indizi in base alla posizione dell'utente; * **Negozi**: offri informazioni su prodotti o promozioni in base al reparto. #### Personalizzazione basata sulla data Perfetta per: * **Eventi stagionali**: contenuti speciali per Natale, Pasqua, Halloween, ecc.; * **Promozioni temporanee**: informazioni su saldi o offerte a tempo limitato; * **Campagne di marketing**: contenuti legati a lanci di prodotti o iniziative speciali. {% hint style="info" %} Puoi combinare data e luogo per creare esperienze ancora più mirate e specifiche per il contesto. {% endhint %} ### Suggerimenti per un uso efficace 1. **Pianifica in anticipo** quali contenuti devono essere disponibili dove e quando; 2. **Testa regolarmente** i tuoi contenuti personalizzati per assicurarti che vengano visualizzati correttamente nelle date e nei luoghi previsti. Puoi usare questa funzionalità per offrire un'esperienza utente unica e sempre pertinente, indipendentemente da dove o quando viene utilizzato il tuo Agente. # Gestione dei suggerimenti Questa funzionalità ti consente di presentare agli utenti una serie di opzioni predefinite come pulsanti cliccabili, rendendo le interazioni più fluide e mirate. ### Come funzionano i suggerimenti Quando aggiungi un suggerimento a un contenuto: 1. L'utente vedrà questo suggerimento come **pulsante interattivo** dopo la risposta dell'Agente; 2. Facendo clic su un pulsante, il testo del suggerimento viene inviato come se l'utente lo avesse digitato; 3. L'Agente risponderà in base al contenuto corrispondente al suggerimento selezionato. {% hint style="info" %} Questa funzionalità è particolarmente utile per **guidare gli utenti attraverso processi specifici** o indirizzare la conversazione verso **argomenti predefiniti**. {% endhint %} ### Come aggiungere suggerimenti Per aggiungere suggerimenti a un contenuto: 1. Vai alla schermata di creazione o modifica del contenuto; 2. Trova e apri la sezione "Avanzate: suggerimenti" nella sezione "Avanzate"; 3. Fai clic su **Aggiungi** per inserire un nuovo suggerimento; 4. Inserisci il testo che vuoi visualizzare sul pulsante; 5. Ripeti il processo per aggiungere altri suggerimenti, quindi salva le modifiche facendo clic sul pulsante **"conferma"** in basso a destra. Per eliminare un suggerimento, fai clic sul pulsante rosso accanto a ciascuno di essi. ### Vantaggi dell'uso dei suggerimenti * **Guida l'utente**: aiuta gli utenti a orientarsi tra le opzioni predefinite; * **Riduce gli errori**: limita le possibilità di input imprevisti o fraintesi; * **Migliora l'esperienza utente**: rende le interazioni più fluide e intuitive; * **Aumenta l'efficienza**: velocizza il processo per ottenere le informazioni desiderate. ### Esempio di flusso di conversazione Utente: "Ho un problema con il mio computer." Agente: "Mi dispiace sentirlo. Posso aiutarti a risolverlo. Di che tipo di problema si tratta?" Suggerimenti: * Il computer non si accende; * La connessione Internet non funziona; * Un'applicazione non risponde; * Qualcos'altro. Utente: \[Fa clic su "Il computer non si accende"] Agente: "Capisco che il tuo computer non si accende. Proviamo alcuni passaggi per risolvere il problema. Per prima cosa, controlla che il cavo di alimentazione sia collegato correttamente. Hai verificato?" Suggerimenti: * Sì, il cavo è collegato correttamente; * No, il cavo non era collegato. ### Suggerimenti per un uso efficace dei suggerimenti 1. **Limita i suggerimenti a 2–5** per evitare di sovraccaricare l'utente; 2. Assicurati che ci siano contenuti corrispondenti per ogni suggerimento (o almeno che l'[IA generativa](/ai-generativa) sappia come rispondere correttamente); 3. Aggiorna regolarmente i suggerimenti in base alle interazioni più comuni degli utenti. L'uso intelligente dei suggerimenti può trasformare il tuo Agente da un semplice assistente in una guida interattiva ed efficace che migliorerà significativamente il coinvolgimento e la soddisfazione degli utenti. # Gestione dei tag # Contesto: argomenti ed etichette AIsuru ti consente di creare conversazioni dinamiche e consapevoli del contesto tramite l'uso del contesto. Questa funzionalità ti permette di controllare quando determinate domande sono appropriate e come l'Agente deve interpretare e rispondere alle richieste degli utenti in base al contesto della conversazione. ### Contesto: cos'è e a cosa serve La gestione del contesto ti consente di definire in quali situazioni specifiche una domanda o una risposta hanno senso. Il contesto comunica ad AIsuru di cosa si sta parlando in un dato momento, il che è necessario per guidare efficacemente la conversazione, consentendo l'accesso a determinati [contenuti](/istruzione-gestione-contenuti-agenti/contenuti) e limitando la visibilità di altri. #### Argomenti ed etichette Il contesto in AIsuru viene gestito tramite due tipi di elementi: * **Argomenti:** coppie nome-valore che definiscono un contesto specifico; * Il nome identifica il tipo di contesto (ANIMAL, OBJECT, ecc.); * Il valore specifica il contesto attuale (DOG, SMARTPHONE, ecc.). Esempio: ANIMAL:DOG * **Etichette:** contesti semplici: * Il nome identifica l'argomento di cui si sta parlando (ad es., GENERAL\_QUESTIONS); * Le etichette sono in realtà argomenti con "✔️" come valore nascosto. ### Contesto impostato e contesto richiesto Gli argomenti e le etichette possono essere utilizzati in due modi diversi che influenzano il modo in cui l'Agente gestisce i contenuti: * **Imposta contesto** ("Imposta argomenti" nella piattaforma): * Indica all'Agente di cosa si sta parlando in questo momento; * Aiuta l'Agente a dare priorità ai contenuti più rilevanti per il contesto attuale; * NON limita l'accesso ai contenuti, ma li organizza in base alla rilevanza; * Esempio: * Domanda: "Parliamo di cani"; * Risposta: "Certo, parliamo di cani" \[imposta argomento:`ANIMAL:DOG`] * Dopo questo, l'Agente saprà che la conversazione riguarda i cani e potrà fornire risposte più rilevanti. * **Contesto richiesto** ("Argomenti richiesti" nella piattaforma): * Agisce come un vero filtro che blocca l'accesso dell'Agente a determinati contenuti finché non viene impostato un contesto specifico; * L'IA può accedere a questi contenuti solo QUANDO quel contesto specifico è attivo; * Se non imposti alcun argomento richiesto, l'Agente avrà sempre accesso ai tuoi contenuti indipendentemente dal contesto attuale; * Esempi: * `ANIMAL:DOG`: la domanda è rilevante solo quando si parla di cani; * `OBJECT:WAND`: la domanda è appropriata solo nel contesto di una bacchetta. La differenza fondamentale tra i due tipi di contesto è: * **Il contesto impostato aiuta l'Agente a comprendere meglio la conversazione** e a dare priorità ai contenuti più rilevanti; * **Il contesto obbligatorio blocca completamente l'accesso ai contenuti** finché non viene impostato quel contesto specifico; {% hint style="info" %} Una volta impostato un contesto specifico, i contenuti con quel contesto obbligatorio possono essere passati anche all'IA generativa per rispondere alle domande degli utenti. {% endhint %} ### Come gestire il contesto nei tuoi contenuti #### Aggiungi un contesto Per aggiungere un contesto ai tuoi contenuti: 1. Vai a **Contenuti** e creane uno o modificane uno esistente; 2. Vai alla sezione "Avanzate: gestione del contesto"; 3. Scegli se aggiungere un argomento impostato (in "Argomenti impostati") o uno obbligatorio (in "Argomenti obbligatori"); 4. Scegli tra "Nuovo argomento" e "Nuova etichetta" in base alle tue esigenze; 5. Compila il nome e il valore (se applicabile) nel pannello che si apre; 6. Conferma e salva il contenuto. {% hint style="info" %} Puoi anche utilizzare "Suggerisci etichette" per ricevere suggerimenti basati sul contenuto. {% endhint %} #### Annulla un contesto Per annullare un contesto, aggiungi un argomento con lo stesso nome e **inserisci "-" come valore**. Esempio: `ANIMAL:-` annullerà il contesto "ANIMAL", che non sarà più impostato e non avrà alcun valore. ### Esempi pratici #### Scenario: assistente per un negozio di animali 1. L'Agente chiede all'utente: "A quale tipo di animale sei interessato?"; 2. Utente: "Cani", argomento impostato:`ANIMAL:DOG` 3. Argomento obbligatorio: domanda: "Quali sono le esigenze alimentari specifiche?", argomento obbligatorio:`ANIMAL:DOG` 4. Annullamento di un contesto: domanda: "Vorrei parlare di un animale diverso", argomento impostato:.`ANIMAL:-` #### Flusso della conversazione 1. Utente: "Vorrei informazioni sugli animali domestici"; 2. Agente: "Certo! Che tipo di animale ti interessa?"; 3. Utente: "Cani"; 4. Agente: (imposta `ANIMAL:DOG`) "Ottimo! I cani sono animali meravigliosi. Cosa vorresti sapere sui cani?"; 5. Utente: "Quali sono le loro esigenze alimentari?"; 6. Agente: (verifica `ANIMAL:DOG`, domanda pertinente) "I cani hanno bisogno di una dieta equilibrata. In generale, necessitano di proteine di alta qualità, carboidrati, grassi, vitamine e minerali. La quantità e il tipo di cibo dipendono dall'età, dalla taglia e dal livello di attività del cane..."; 7. Utente: "Vorrei parlare di un altro animale"; 8. Agente: (imposta `ANIMAL:-`) "Certo! Di quale altro animale vorresti parlare?". {% hint style="info" %} Per ragioni di sicurezza, **l'** [**IA generativa**](/ai-generativa) **non può leggere né applicare i contesti in autonomia**. Questo compito viene svolto da AIsuru. {% endhint %} ### Vantaggi dell'uso dei contesti * Conversazioni più naturali e coerenti; * Risposte più pertinenti e precise; * La possibilità di creare percorsi di dialogo complessi e ramificati; * Migliore gestione di più argomenti all'interno della stessa conversazione. L'utilizzo efficace di contesti e variabili di contesto può trasformare il tuo Agente in un assistente davvero intelligente e consapevole del contesto. Sperimenta queste funzionalità per creare esperienze conversazionali ricche e dinamiche che si adattano alle esigenze e agli interessi specifici dei tuoi utenti. # Gestione degli script eseguibili (snippet di codice) Gli script eseguibili sono una funzionalità avanzata che ti consente di integrare ed eseguire codice direttamente nelle conversazioni con il tuo Agente. Questa potente funzionalità ti consente di: * Mostrare esempi di codice formattati correttamente; * Eseguire script e modificare l'interfaccia utente in tempo reale; * Creare esperienze interattive e dinamiche; * Fornire dimostrazioni tecniche immediate. ### Come aggiungere script eseguibili 1. Vai ai **Contenuti** del tuo Agente e crea o modifica un contenuto; 2. Vai alla sezione "**Avanzate: script eseguibili**" e fai clic su "**+ Nuovo snippet**"; 3. Nel pannello che si apre: 1. Aggiungi un titolo allo snippet di codice; 2. Inserisci il codice; 3. Decidi se eseguire il codice nella pagina attivando la casella "Inserisci nella pagina ed esegui questo snippet" (disponibile solo per alcuni linguaggi). Questa casella ti consente di: 1. Eseguire sempre lo snippet quando l'utente pone esattamente la stessa domanda del tuo contenuto (o una domanda abbastanza simile); 2. Far eseguire lo snippet all'IA generativa (a discrezione del modello). {% hint style="info" %} **L'IA generativa utilizza il titolo dello snippet per decidere se e quando eseguirlo**. Se vuoi che l'IA generativa esegua il tuo snippet, assicurati di scegliere nomi descrittivi e di spiegare nel prompt quando utilizzare lo snippet. {% endhint %} ### Linguaggi supportati Puoi scegliere tra i seguenti linguaggi per il tuo snippet: | Linguaggio | Mostra snippet | Esegui snippet | | :------------: | :------------: | :------------: | | text | ✅ | ❌ | | javascript/jsx | ✅ | ✅ | | typescript/tsx | ✅ | ❌ | | json | ✅ | ❌ | | css | ✅ | ✅ | | xml | ✅ | ❌ | | bash | ✅ | ❌ | | python | ✅ | ❌ | | cpp/csharp | ✅ | ❌ | | php | ✅ | ❌ | | ruby | ✅ | ❌ | | html | ✅ | ❌ | | markdown | ✅ | ❌ | ### Esempi pratici * Obiettivo: evidenziare una sezione della pagina web; * Titolo: "Evidenzia la descrizione del prodotto"; * Linguaggio: JavaScript; * Inserisci nella pagina ed esegui questo snippet: casella di controllo selezionata. Codice: ```javascript window.evidenziaSezione = function(idSezione) { const sezione = document.getElementById(idSezione); sezione.style.boxShadow = '0 0 15px 5px #ffff00'; setTimeout(() => { sezione.style.boxShadow = 'none'; }, 3000); } ``` Flusso della conversazione: 1. Utente: "Dove posso trovare la descrizione del prodotto?"; 2. Agente: 1. "La descrizione del prodotto si trova sotto il titolo, in alto a destra. Per aiutarti, l'ho evidenziata per alcuni secondi."; 2. \[Inserisce ed esegue lo snippet 'Evidenzia sezione prodotto'.] ### Vantaggi dell'uso di script eseguibili * Crea interazioni più dinamiche e consapevoli del contesto; * Migliora l'esperienza utente con esempi visivi e interattivi; * Fornisce supporto tecnico immediato e pratico; * Ti consente di personalizzare l'interfaccia utente in tempo reale; * Semplifica la dimostrazione delle funzionalità del sito o dell'applicazione. ### Combinazioni avanzate di snippet Gli snippet possono essere combinati strategicamente per creare interazioni più complesse: #### Esempio: evidenziazione dinamica delle sezioni Immagina di creare un'esperienza guidata in cui l'Agente evidenzia diverse parti della pagina durante una conversazione. Potresti configurare: 1. Uno snippet CSS (tramite [domanda di apertura](broken://pages/dKFXtchoofBRemue3uig)); ```css .highlight-pulse { animation: pulse 2s infinite; border: 2px solid #6366f1; border-radius: 4px; } @keyframes pulse { 0% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.4); } 70% { box-shadow: 0 0 0 10px rgba(99, 102, 241, 0); } 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0); } } ``` 2. Uno snippet JavaScript (nella stessa domanda di apertura); ```javascript // Function to highlight the products section function highlightProductsSection() { const productsSection = document.querySelector('.products-section'); if (!productsSection) return; // Guard clause // Add the effect productsSection.classList.add('highlight-pulse'); // Remove the effect after 5 seconds using requestAnimationFrame const startTime = performance.now(); function removeHighlight(currentTime) { if (currentTime - startTime >= 5000) { productsSection.classList.remove('highlight-pulse'); return; } requestAnimationFrame(removeHighlight); } requestAnimationFrame(removeHighlight); } ``` 3. Uno snippet JavaScript collegato al contenuto con la domanda "Dove si trova la sezione prodotti?". ```javascript // Using the function highlightProductsSection(); ``` In questo modo, quando l'utente apre la chat: * Lo stile CSS viene iniettato immediatamente; * Viene definita la funzione JavaScript per evidenziare la sezione. Quando l'utente chiede "Dove si trova la sezione prodotti?", l'Agente attiverà il terzo snippet e quindi la funzione che evidenzia la sezione. Questo approccio è particolarmente utile per: * Tutorial guidati interattivi; * Onboarding di nuovi utenti; * Assistenza alla navigazione in pagine complesse; * Presentazioni di prodotti o servizi. ### Considerazioni importanti 1. **Sicurezza**: quando utilizzi l'opzione di esecuzione degli snippet, assicurati che il codice sia sicuro e non possa essere manipolato per eseguire azioni dannose; 2. **Trasparenza**: fornisci sempre una spiegazione chiara di ciò che lo snippet fa o mostra. 3. **Accessibilità**: non tutti gli utenti potrebbero vedere gli effetti visivi degli snippet, quindi fornisci sempre alternative basate sul testo; 4. **Prestazioni**: evita di sovraccaricare la pagina con troppi snippet eseguibili, che potrebbero rallentare l'esperienza utente. L'uso intelligente di script eseguibili può trasformare il tuo Agente in un potente strumento di supporto. Sperimenta con diversi tipi di snippet per creare un'esperienza utente coinvolgente e personalizzata, migliorando significativamente l'interazione tra gli utenti e il tuo sito web o la tua applicazione. # Utilizzo del timeout La funzionalità di timeout in AIsuru ti consente di mantenere attiva e coinvolgente la conversazione con un utente, anche durante periodi di inattività. È particolarmente utile per orientare gli utenti verso nuovi argomenti o mantenere il loro interesse. ### Come funziona il timeout Quando imposti un timeout per una domanda, AIsuru suggerirà automaticamente una nuova domanda all'utente se rimane inattivo per un determinato periodo di tempo. {% hint style="success" %} Il timeout viene scelto casualmente tra un valore minimo e massimo personalizzabili, per rendere l' **interazione più naturale e meno prevedibile**. {% endhint %} ### Come impostare un timeout 1. Vai ai **Contenuti** del tuo Agente e crea o modifica un contenuto; 2. Vai alla sezione "Avanzate: timeout"; 3. Imposta i valori minimo e massimo del timeout (in secondi). Ad esempio: * Timeout minimo: 20 secondi; * Timeout massimo: 40 secondi. In questo caso, se l'utente non interagisce per un periodo compreso tra 20 e 40 secondi, l'Agente suggerirà automaticamente una nuova domanda e dirà: "Perché non mi chiedi una \[domanda casuale]?". ### Vantaggi dell'utilizzo del timeout * **Mantiene attiva la conversazione**: evita lunghi silenzi che potrebbero far perdere interesse all'utente. * **Guida l'utente**: può introdurre nuovi argomenti o suggerire nuove direzioni per la conversazione; * **Personalizzabile**: puoi impostare timeout diversi per domande diverse; * **Esperienza naturale**: la variazione casuale del timeout rende l'interazione più simile a una conversazione reale. ### Come disattivare il timeout e le domande casuali Per alcuni casi d'uso, il timeout potrebbe essere un elemento di disturbo. In AIsuru, puoi: * Mantieni **il timeout attivo per tutti i contenuti** (comportamento predefinito): l'Agente porrà domande casuali all'utente; * Mantieni **il timeout attivo per alcuni contenuti**: l'Agente porrà domande casuali (estratte da un gruppo specifico) all'utente; * **Disattiva completamente il timeout**: l'Agente non porrà più domande casuali, anche se l'utente non interagisce da un po'. #### Come attivare il timeout solo per determinati contenuti [Contrassegna i singoli contenuti come "non casuali"](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#other-fields) nel pannello di creazione/modifica dei contenuti o nelle impostazioni di importazione del documento. I contenuti "non casuali" non verranno suggeriti all'utente. #### Come suggerire domande quando l'utente è inattivo 1. Vai alle **Impostazioni del tuo Agente;** 2. Nella sezione Generale, apri il pannello **Impostazioni avanzate**. 3. Attiva l'interruttore **"Suggerisci domande se l'utente è inattivo"**; ### Esempi di utilizzo Scenario: guida turistica virtuale Impostazioni dei contenuti: * Timeout minimo: 15 secondi; * Timeout massimo: 30 secondi. Flusso di conversazione: 1. L'Agente descrive il Colosseo; 2. L'utente non interagisce per 17 secondi; 3. L'Agente pone una domanda casuale: "Perché non mi chiedi quando è stato costruito il Colosseo?"; 4. L'utente fa clic su "OK" (l'Agente risponde) oppure su "No, grazie". ### Procedure consigliate 1. **Equilibrio**: imposta timeout che non siano né troppo brevi (fastidiosi) né troppo lunghi (si perde il coinvolgimento); 2. **Contesto**: adatta la durata dei timeout al contesto della conversazione e alla complessità delle informazioni fornite; 3. **Rilevanza**: assicurati che le domande suggerite dopo un timeout siano pertinenti e aggiungano valore alla conversazione; 4. **Flessibilità**: considera di impostare timeout più lunghi per domande che richiedono riflessione o azioni da parte dell'utente. L'uso intelligente del timeout può trasformare una semplice interazione in una conversazione dinamica e coinvolgente. Sperimentando con diversi valori di timeout e domande di follow-up, puoi creare un'esperienza utente più ricca e personalizzata, mantenendo gli utenti coinvolti e guidandoli attraverso tutto ciò che il tuo Agente ha da offrire. # Importazione avanzata di documenti In questa sezione esploreremo le funzionalità avanzate di AIsuru per gestire scenari di importazione di documenti più complessi. In particolare, esamineremo due situazioni: * [**Creare una gerarchia di documenti**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/importazione-avanzata-di-documenti/creare-una-gerarchia-dei-documenti)**:** quando hai documenti con diversi livelli di importanza, questa funzionalità ti consente di organizzarli in modo strutturato e di gestire le priorità durante l'importazione; * [**Importare documenti non supportati**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/importazione-avanzata-di-documenti/documento-non-supportato): se devi importare file in formati insoliti (come Excel, video o altri tipi non direttamente supportati), scoprirai come farlo in modo efficace. Queste funzionalità avanzate ti offrono un controllo più preciso sul processo di importazione e ti aiutano a gestire scenari più complessi per arricchire la base di conoscenza del tuo Agente. # Creare una gerarchia dei documenti La gestione di documenti con diversi livelli di autorità o importanza può rappresentare una vera sfida, specialmente quando le informazioni possono sovrapporsi o potenzialmente contraddirsi. AIsuru non supporta ufficialmente la gestione di una gerarchia dei documenti, ma in questa guida vedremo come utilizzare gli altri strumenti di AIsuru per ottenere lo stesso risultato. ### Come creare una gerarchia dei documenti #### Importare i documenti {% tabs %} {% tab title="Utenti intermedi" %} 1. Vai alla sezione **Import / Export** del tuo Agente; 2. [**Carica il documento**](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali#access-to-the-import-section) e configura le varie impostazioni; 3. Nel campo "**Istruzioni per la generazione delle domande**", aggiungi quanto segue: 'Aggiungi "- \[nome del documento]" alla fine di ogni domanda'. Ricordati di sostituire \[nome del documento] con il nome effettivo del tuo documento; 4. **Ripeti l'operazione per tutti i documenti.** {% endtab %} {% tab title="Utenti avanzati e sviluppatori" %} 1. Vai alla sezione **Import / Export** del tuo Agente; 2. [**Carica il documento**](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali#access-to-the-import-section) e configura le varie impostazioni (prendi nota dell'argomento impostato che "contrassegna" i contenuti di ciascun file); 3. [**Esporta i contenuti in formato CSV.**](broken://pages/pRiZgAUpWHMo0kttSnsg#esecuzione-del-backup) 4. Aggiungi automaticamente "- \[nome del documento]" alla fine di ogni domanda; 5. [**Elimina i contenuti**](/istruzione-gestione-contenuti-agenti/contenuti/modifica-e-aggiornamento-dei-contenuti#deleting-contents) dal tuo Agente; 6. [**Ricarica il file CSV modificato.**](broken://pages/pRiZgAUpWHMo0kttSnsg#come-importare-il-file-csv) {% endtab %} {% endtabs %} #### Aggiorna le impostazioni IA Ora che hai caricato i documenti, dovrai istruire il tuo Agente a rispettare la tua gerarchia: 1. Vai alle **Impostazioni del tuo Agente;** 2. Fai clic sulla scheda **IA**; 3. **Modifica le istruzioni** per spiegare chiaramente la priorità da assegnare a ciascun documento. Ad esempio: "Quando l'utente pone una domanda, rispondi dando priorità ai contenuti di \[nome del documento]. Poi considera i contenuti di \[nome del documento] e \[nome del documento]"; 4. Seleziona la casella "**Solo IA**"; ### Casi d'uso ideali La gerarchia dei documenti è particolarmente utile per: * Gestire normative e documenti di conformità; * Documentazione tecnica stratificata; * Qualsiasi scenario con fonti di informazioni di diversa autorevolezza o attualità. ### Considerazioni importanti * Mantieni la **struttura gerarchica semplice, chiara e logica;** * Documenta attentamente la gerarchia che hai stabilito. * Aggiorna le priorità quando necessario; * Verifica periodicamente la coerenza delle risposte. Creare una gerarchia dei documenti rappresenta un significativo passo avanti nella gestione di informazioni complesse, consentendo al tuo Agente di fornire risposte più accurate e contestualizzate in base all'autorevolezza delle diverse fonti. # Importare un documento non supportato AIsuru supporta l'importazione di vari tipi di documenti di testo, ma potrebbe capitare di voler importare un formato che non è supportato ufficialmente. Questa guida ti aiuterà a gestire l'importazione di diversi tipi di file non standard, assicurandoti che il tuo Agente IA possa accedere a tali informazioni e utilizzarle efficacemente. ### Procedura generale Se il formato del tuo documento non è supportato direttamente: 1. **Estrai il testo o le informazioni** dal tuo file; 2. **Incolla le informazioni estratte:** 1. Nelle [istruzioni](/ai-generativa/prompt-engineering) se vuoi che l'IA abbia sempre tutto a disposizione (e se il testo contiene meno di 200.000 caratteri); 2. Oppure nei [contenuti](/istruzione-gestione-contenuti-agenti/contenuti) se vuoi separare le informazioni per argomento: 1. **Domanda**: inserisci una parola chiave; 2. **Varianti di domanda**: scrivi domande specifiche per le quali tali informazioni sono utili; 3. **Risposta**: incolla il testo estratto. 3. **Spiega come leggere e utilizzare i dati** nelle istruzioni del tuo Agente. ### Gestione di formati specifici Ora che hai esaminato la procedura generale, puoi vedere come gestire formati di file specifici. #### File Excel I file Excel più semplici e le tabelle in generale possono essere convertiti in formato **markdown** e inseriti in un contenuto o nelle istruzioni del tuo Agente. Se il tuo file Excel è più complesso e hai bisogno di una maggiore accuratezza nelle risposte: 1. **Identifica diverse categorie in cui raggruppare i dati;** 2. Partendo dal tuo file Excel, **estrai le informazioni e salvale in file JSON separati** (uno per categoria) con una struttura chiara e semplice che chiunque possa comprendere; 3. **Copia il codice JSON** e incollalo: 1. Nelle **istruzioni** se il totale non supera i 200.000 caratteri; 2. In **contenuti** separati (uno per categoria, corrispondenti ai file): 1. **Domanda:** inserisci una parola chiave; 2. **Varianti di domanda:** inserisci esempi di domande a cui l'IA dovrebbe poter rispondere in base a quei dati; 3. **Risposta:** incolla il codice JSON; 3. In [**funzioni**](/avanzate/integrazioni/funzioni) separate (una per categoria, corrispondenti ai file): puoi anche usare le funzioni per ospitare i tuoi contenuti. Basta rendere accessibile il tuo file JSON e l'Agente recupererà le informazioni quando necessario; 4. Nelle istruzioni, **spiega all'Agente dove trovare le informazioni** (nelle istruzioni, nei contenuti o nelle funzioni), **come leggere i dati** (la struttura JSON), **e come utilizzarli** per rispondere alle richieste degli utenti. #### Video AIsuru non supporta ufficialmente l'istruzione a partire da file video. Se vuoi rendere un video interrogabile: 1. **Ottieni una trascrizione del video** (usa Whisper di OpenAI o SharePoint per le riunioni di Teams); 2. Nelle istruzioni, **spiega cosa deve fare l'IA e incolla la trascrizione.** Ecco fatto! L'IA sarà ora in grado di rispondere alle domande sul video. La qualità delle risposte dipenderà in larga misura dalla qualità della trascrizione. Se utilizzi Microsoft SharePoint, puoi anche allegare il link del video, al timestamp esatto, a ciascuna risposta: 1. **Assicurati di includere i timestamp** della trascrizione nelle istruzioni del tuo Agente; 2. **Copia il link del video;** 3. **Personalizza e aggiungi queste istruzioni**: ``` 1. VIDEO LINK: - The video is here: `...name.mp4` 2. TRANSCRIPT: - The transcript precedes each section with hh:mm:ss indicating the exact hour, minute, and second when something is said. - You MUST take the transcript, the EXACT timestamp, and the following rule into account when creating the link to a specific moment. 3. BUILDING THE LINK TO A SPECIFIC MOMENT: - If the timestamp indicates, for example, 5 minutes and 16 seconds, that means `5*60+16 = 316` seconds. You must then append this variable part to the link: `&nav=%7B%22playbackOptions%22%3A%7B%22startTimeInSeconds%22%3AXXX%7D%7D` where `XXX` must be replaced with the exact number of seconds. ### Example: - Calculation: `5 minutes and 16 seconds = 5*60+16 = 316 seconds` - Variable part: `&nav=%7B%22playbackOptions%22%3A%7B%22startTimeInSeconds%22%3A316%7D%7D` - Full link: `...name.mp4&nav=%7B%22playbackOptions%22%3A%7B%22startTimeInSeconds%22%3A316%7D%7D` ``` Queste istruzioni sono state create per Microsoft SharePoint. Se utilizzi YouTube o un altro servizio, assicurati di modificare di conseguenza la parte variabile del link. #### Immagini Per importare informazioni dalle immagini: 1. Utilizza ChatGPT o Claude per ottenere una descrizione accurata e completa dell'immagine; 2. Esporta il testo e inseriscilo: 1. **Nelle istruzioni:** se vuoi che l'Agente abbia sempre presenti le informazioni estratte; 2. **In un contenuto:** se vuoi mostrare l'immagine in occasioni specifiche, con determinate parole chiave o domande: 1. **Domanda:** inserisci una domanda a cui l'immagine risponde (o una parola chiave); 2. **Varianti di domanda:** aggiungi altre domande per cui l'immagine potrebbe essere utile; 3. **Risposta:** la descrizione dell'immagine; 4. [Media](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#media-and-links): aggiungi la tua immagine. L'importazione di documenti non supportati richiede un po' più di lavoro manuale, ma ti consente di integrare un'ampia gamma di informazioni nel tuo Agente IA. Scegli il metodo più appropriato in base al tipo di documento e alla struttura delle informazioni che contiene. Verifica sempre che le informazioni importate siano accurate e facilmente accessibili all'Agente, per garantire risposte precise e pertinenti. # Messaggio di benvenuto Il messaggio di benvenuto è il modo in cui il tuo Agente si presenterà agli utenti quando iniziano una conversazione. Un buon messaggio di benvenuto può anche indirizzare gli utenti verso i tipi di domande a cui il tuo Agente può rispondere. ### Come personalizzare il messaggio di benvenuto Per modificare il messaggio di benvenuto del tuo Agente: 1. Vai a **Contenuti del tuo Agente;** 2. Vai alla scheda "Messaggio di benvenuto" e inserisci il testo desiderato nella casella di testo. {% hint style="info" %} Il messaggio di benvenuto **utilizza il nome della Persona, non il nome dell'Agente**: se vuoi che il messaggio di benvenuto si aggiorni automaticamente quando il nome cambia, sostituisci il nome della Persona con {0} nel tuo messaggio di benvenuto.\ \ Ad esempio, se scrivi "Ciao! Mi chiamo {0}, come posso aiutarti oggi?", gli utenti vedranno il nome dell'Agente al posto di {0}. {% endhint %} #### Reimposta e salva Dopo aver personalizzato il messaggio, hai due opzioni: * Fai clic su "Salva" per confermare le modifiche; * Fai clic su "Reimposta" per ripristinare il messaggio predefinito. {% hint style="info" %} Il messaggio di benvenuto è diverso dalla [domanda di apertura](broken://pages/dKFXtchoofBRemue3uig) che puoi configurare nei layout di condivisione. Mentre il messaggio di benvenuto è sempre lo stesso, la domanda di apertura può generare risposte diverse tramite l'IA generativa. {% endhint %} ### Suggerimenti per un buon messaggio di benvenuto * Presentati con un tono amichevole; * Spiega brevemente cosa può fare il tuo Agente; * Invita gli utenti a porre domande specifiche; * Mantieni un tono coerente con la personalità che vuoi dare al tuo Agente. Con un messaggio di benvenuto efficace, i tuoi utenti sapranno subito come ottenere il massimo dal tuo Agente e quali tipi di domande possono porgli. # Risposte predefinite Le risposte predefinite in AIsuru offrono un modo utile per gestire le situazioni in cui l'Agente non comprende una richiesta. ### Cosa sono le risposte predefinite Le risposte predefinite sono risposte standard che il tuo Agente può fornire agli utenti quando non sa come rispondere a una domanda. ### Come modificare le risposte predefinite * Vai ai **Contenuti del tuo Agente;** * Dal menu, seleziona "Risposte predefinite". Da questa sezione puoi modificare la risposta predefinita di base e aggiungere ulteriori risposte predefinite. #### **Risposta predefinita di base** La risposta predefinita di base è ciò che il tuo Agente dice quando riscontra un errore. Per modificarla, modifica il campo di testo e fai clic sul pulsante "Salva" a destra. Se vuoi ripristinarla al valore originale, fai clic su "Reimposta". #### Risposte predefinite personalizzate In alcuni casi, puoi mostrare una risposta personalizzata che l'Agente fornirà agli utenti al posto della risposta di base. Per farlo, fai clic sul pulsante **Nuova risposta predefinita** e inserisci la risposta. Ricorda che devi specificare almeno uno dei seguenti elementi: * Obbligatorio [argomento;](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette) * [Ruolo](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici) a cui assegnare la risposta. * [Data o luogo;](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente) All'interno del pannello di creazione, puoi anche: * Aggiungi [ulteriori risposte;](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#additional-answers) * Contrassegna la [risposta come conclusiva;](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#other-fields) * Aggiungi [contenuti multimediali e link;](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#media-and-links) * Avanzate: aggiungi [suggerimenti](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-suggerimenti), [tag](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-tag), [contesto](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette), [snippet di codice](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice), modifica il [timeout](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout) e modifica l'[integrazione DCM.](/estensioni/open-badge) ### Utilizzare efficacemente le risposte predefinite Per ottenere il massimo dalle tue risposte predefinite: * Scrivi risposte chiare e concise che guidino l'utente verso una soluzione; * Considera diversi scenari e crea risposte specifiche per ciascuno; * Aggiorna regolarmente le risposte per assicurarti che rimangano pertinenti. # Formattazione dei messaggi: HTML e formule matematiche AIsuru offre potenti strumenti di formattazione che ti consentono di arricchire le risposte del tuo Agente con HTML e formule matematiche, creando esperienze conversazionali più ricche e interattive. ### Codice HTML nei messaggi L'HTML nei messaggi viene interpretato e visualizzato automaticamente quando il messaggio viene mostrato. Non devi abilitare alcuna impostazione specifica: basta includere il codice HTML desiderato nella risposta dell'Agente. #### Come usare l'HTML nel tuo Agente Per utilizzare questa funzionalità, inserisci semplicemente il codice HTML: * **Nella** [**risposta del tuo contenuto**](/istruzione-gestione-contenuti-agenti/contenuti/creazione-manuale-dei-contenuti#how-to-create-a-simple-content)**:** in questo caso, il codice HTML sarà sempre lo stesso (utile, ad esempio, per i moduli); * **Nelle** [**Istruzioni IA**](/ai-generativa/prompt-engineering)**:** ricorda di spiegare all'IA generativa quando e come utilizzare il tuo codice HTML. {% hint style="info" %} Una volta fatto, assicurati di testarlo per confermare che il codice venga visualizzato correttamente. Per implementazioni più complesse, ricorda che puoi **aggiungere codice JavaScript e CSS negli** [**snippet di codice eseguibili**](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice). {% endhint %} #### Esempio: visualizzare immagini da un sito web Ecco un esempio di come istruire l'Agente a mostrare le immagini che trova in una determinata pagina web: {% code fullWidth="false" %} ``` When the user asks to see a photo: 1. Call the "photo_album" function; 2. Read the photo names returned by the function; 3. Find the photo the user asked to see and remember the path and filename (/img/example.png) 4. Respond by including the HTML code that lets the user see the photo HTML code to show the photo to the user: REMEMBER TO REPLACE XXX with the absolute path of the image! So not ".../img/example.png" but "www.[example].org/img/example.png" ``` {% endcode %} ### Formule matematiche AIsuru supporta la visualizzazione di formule matematiche tramite MathJax. Puoi includere formule matematiche in due modi: * **Nei contenuti**: * Racchiudi la formula tra parentesi quadre; * Esempio: \[E = mc^2] verrà visualizzato come formula matematica; * Puoi usare la sintassi LaTeX per formule complesse: \[\frac{-b \pm \sqrt{b^2-4ac}}{2a.}] * **Nelle Istruzioni IA**: * Puoi istruire l'IA a generare formule matematiche; * Specifica nelle istruzioni che deve usare la sintassi LaTeX per le formule matematiche; * L'IA genererà automaticamente le formule nel formato corretto. ### Vantaggi della formattazione avanzata L'integrazione di HTML e formule matematiche nelle risposte dell'Agente offre diversi vantaggi: * **Presentazione di informazioni complesse** in modo strutturato e visivamente accattivante; * **Visualizzazione di formule matematiche** in un formato professionale e leggibile; * Creazione di **esperienze interattive** direttamente nella chat. ### Copia dei messaggi formattati AIsuru fornisce due pulsanti di copia che appaiono in ogni risposta: * **Copia contenuto**: copia il testo del messaggio renderizzato e formattato (solo testo semplice). * **Copia codice sorgente**: copia il testo originale con tutti i tag HTML o la formattazione Markdown; Questa funzionalità è particolarmente utile quando: * Devi riutilizzare codice HTML o Markdown; * Devi condividere sia la visualizzazione renderizzata sia il codice sorgente di una risposta. Ad esempio, quando copi una risposta di un Agente che contiene un'immagine, il pulsante "**Copia contenuto**" copierà solo il testo descrittivo, mentre "**Copia codice sorgente**" includerà anche il tag HTML dell'immagine con il relativo URL. Sfruttando questa potente funzionalità, puoi trasformare le conversazioni con il tuo Agente da semplici scambi di testo a esperienze ricche e coinvolgenti per i tuoi utenti. # Metodi avanzati di istruzione Oltre ai metodi di base (Istruiscimi, Contenuti e Importazione di documenti), AIsuru offre tre approcci avanzati per istruire il tuo Agente: * Puoi inserire brevi documenti direttamente nelle [Istruzioni IA dell'Agente](/ai-generativa/prompt-engineering) * Puoi usare le [Funzioni](/avanzate/integrazioni/funzioni) per accedere in tempo reale a documenti e dati online; * Puoi usare [MCP](/avanzate/integrazioni/model-context-protocol-mcp-su-aisuru/mcp-cosa-sono-e-come-si-utilizzano) per connetterti a servizi esterni come i database. Questi metodi avanzati sono particolarmente utili quando hai bisogno di aggiornamenti continui o vuoi mantenere i tuoi dati separati dalla piattaforma. Tuttavia, devono essere usati con cautela: in entrambi i casi, dovrai assicurarti che i documenti e il codice sorgente della pagina non superino la finestra di contesto del modello linguistico scelto. # 3. Modelli linguistici e IA generativa L'intelligenza artificiale è il cuore pulsante del tuo Agente su AIsuru. In questo capitolo, scoprirai come sfruttare la potenza dei modelli linguistici e dell'IA generativa per rendere il tuo assistente virtuale più intelligente, naturale e capace di fornire risposte accurate e pertinenti. In questa sezione, vedremo: * [**Come attivare l'IA generativa**](/ai-generativa/attiva-lia-generativa-e-cambia-il-modello) per dare al tuo Agente la capacità di generare risposte dinamiche e contestuali; * [**Come scrivere istruzioni efficaci**](/ai-generativa/prompt-engineering) che definiscano il comportamento del tuo Agente; * [**Come scegliere il modello linguistico giusto**](/ai-generativa/provider) per le tue esigenze — sia che tu stia creando un semplice assistente personale sia un sofisticato sistema di supporto aziendale. Preparati a scoprire come trasformare il tuo Agente da un semplice assistente a un vero esperto conversazionale, capace di comprendere, apprendere e interagire in modo naturale ed efficace! 🧠💬 # Attiva l'IA generativa e cambia il modello L'IA generativa rende i tuoi Agenti più intelligenti e dinamici: una volta attivata, il tuo Agente adatterà le proprie risposte in base alla conversazione e comprenderà autonomamente il contesto di ogni richiesta. ### IA generativa: quando utilizzarla L'IA generativa è particolarmente utile per: * **Generare risposte più naturali** adatte al contesto; * **Adattarsi dinamicamente** alle diverse richieste degli utenti; * **Fornire informazioni più dettagliate e pertinenti**; * **Personalizzare il tono e lo stile** delle risposte in base al contesto. {% hint style="warning" %} L'IA generativa **può anche fornire agli utenti informazioni errate**. AIsuru offre molti strumenti per ridurre al minimo gli errori dell'IA generativa, ma è sempre possibile che una risposta sia errata o parzialmente errata. La qualità delle risposte dipende in larga misura dal [provider e dal modello che scegli](/ai-generativa/provider). {% endhint %} ### Come attivare l'IA generativa per il tuo Agente Per iniziare a utilizzare l'IA generativa, segui questi semplici passaggi: 1. Apri il pannello di gestione dell'Agente che vuoi configurare; 2. Nella barra laterale, fai clic su **Impostazioni**; 3. Nella pagina Impostazioni, fai clic su **IA** per espandere quella sezione; 4. **Attiva l'interruttore** accanto a **"Abilita le risposte generate dall'IA"**. ✨ Congratulazioni! Hai appena attivato l'IA generativa per il tuo Agente. ### Come cambiare il modello del tuo Agente Nella sezione **"Impostazioni del provider"** in fondo, troverai tre menu a tendina: 1. **Configurazione per domande& e risposte**: è il modello principale che: 1. Legge e segue le istruzioni; 2. Analizza i [contenuti](/istruzione-gestione-contenuti-agenti/contenuti) più rilevanti del tuo Agente; 3. Genera risposte alle domande degli utenti; 4. Decide quando utilizzare funzioni o intenti dinamici. 2. **Configurazione di importazione/esportazione**: ti consente di modificare il modello che gestisce l'[importazione dei tuoi documenti di testo](/istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali); 3. [**Configurazione di Pensiero Profondo**](/estensioni/pensiero-profondo) \*\*\*\*: ti consente di modificare il modello che decide cosa ricordare dalle conversazioni con ciascun utente (attiva solo quando Pensiero Profondo è abilitato). Da questi tre menu a tendina, puoi modificare il modello utilizzato per ciascuna attività. I modelli predefiniti scelti da AIsuru offrono già un'eccellente qualità delle risposte: * **Configurazione per domande& e risposte**: Anthropic - Claude 4.5 Sonnet; * **Configurazione di importazione/esportazione**: OpenAI - GPT 4o Mini; * **Configurazione di Pensiero Profondo**: Anthropic - Claude 4.5 Sonnet. Dopo aver abilitato l'IA generativa e configurato i modelli, puoi: * Modificare le [**istruzioni**](/ai-generativa/prompt-engineering); * Abilitare o disabilitare [**Pensiero Profondo**](/estensioni/pensiero-profondo); * Configurare [**altre impostazioni dell'IA generativa**](/ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa). # Istruzioni IA **Le istruzioni sono il fondamento del comportamento del tuo Agente**. Configurarle correttamente determina non solo la qualità delle risposte, ma anche la personalità e l'efficacia complessiva del tuo assistente virtuale. In questa sezione, esploreremo: * Cosa sono e come modificare le [**istruzioni per l'IA generativa**](/ai-generativa/prompt-engineering/istruzioni-ia-cosa-sono-e-come-modificarle); * Come orientarsi nell'[**Editor Avanzato delle Istruzioni**](/ai-generativa/prompt-engineering/editor-avanzato-delle-istruzioni); * Come [**scrivere istruzioni chiare e specifiche**](/ai-generativa/prompt-engineering/come-scrivere-istruzioni-efficaci) che guidino il comportamento del tuo Agente; * [**Esempi reali di istruzioni efficaci**](/ai-generativa/prompt-engineering/esempi-di-istruzioni-efficaci). Preparati a trasformare il tuo Agente in uno strumento potente e flessibile, capace di offrire un'esperienza utente eccezionale! 🚀 # Istruzioni IA: cosa sono e come modificarle Le istruzioni sono fondamentali per definire il comportamento e le capacità del tuo Agente in AIsuru. Puoi usarle per impostare: * Il **ruolo e le competenze** del tuo Agente; * **Lo stile delle risposte**; * **I limiti e le linee guida comportamentali**. {% hint style="danger" %} Non inserire mai informazioni riservate nelle istruzioni del tuo Agente. **Tutto ciò che inserisci nelle istruzioni potrebbe essere rivelato all'utente**! {% endhint %} ### Accesso e modifica delle istruzioni Per modificare le istruzioni del tuo Agente, segui questi passaggi: 1. Apri il pannello di gestione dell'Agente che vuoi configurare; 2. Seleziona **Impostazioni** nella barra laterale; 3. All'interno della pagina, apri la sezione **IA**; 4. Trova il campo "Istruzioni", apporta le modifiche e fai clic su "Salva modifiche". *Nota: il campo "Istruzioni" può essere espanso facendo clic su "Espandi" per aprire un editor avanzato per i prompt di sistema.* Se vuoi scrivere istruzioni efficaci, continua con il capitolo successivo 👇 # Come scrivere istruzioni efficaci Le istruzioni sono come una "guida al comportamento" per il tuo Agente: spieghi chi è, cosa dovrebbe fare e come dovrebbe interagire con gli utenti. **Scrivere buone istruzioni è essenziale** per avere un Agente che risponda in modo preciso e pertinente. ### Cosa insegnare al tuo Agente Quando scrivi le istruzioni, pensa di dover inserire un nuovo dipendente: devi coprire questi aspetti: * **Chi è**: qual è il suo ruolo? È un Agente del supporto clienti, un esperto di marketing, un tutor; * **Con chi parla**: chi sono i suoi utenti? Cosa cercano di ottenere; * **Cosa sa**: quali sono le sue aree di competenza? Di quali argomenti può parlare; * **Come comunicare**: dovrebbe essere formale o informale? Tecnico o semplice; * **Cosa non dovrebbe fare**: ci sono argomenti da evitare o informazioni da non condividere. {% hint style="danger" %} **ATTENZIONE**: non includere mai informazioni riservate nelle Istruzioni IA. Inserisci invece tali informazioni all'interno di contenuti specifici [assegnati a un Ruolo](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici) o con un [contesto richiesto](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette#required-topics). {% endhint %} ### Come scrivere istruzioni efficaci **Struttura logicamente le tue istruzioni** * Crea sezioni chiare e ben definite (ad es. ruolo, competenze, limiti); * Usa una chiara gerarchia delle informazioni; * Includi esempi concreti per i concetti chiave; * Mantieni una formattazione coerente. **Fornisci un contesto** * Specifica chiaramente l'ambito operativo e i confini dell'Agente; * Definisci il background necessario per comprendere le richieste; * Indica quando e come utilizzare informazioni specifiche; * Includi regole per filtrare contenuti inappropriati; * Specifica come gestire richieste ambigue o fuori ambito. #### Domande e risposte * Definisci il formato atteso delle richieste degli utenti → domande brevi, estratti di articoli o altro; * Specifica la struttura desiderata delle risposte; * Indica come gestire input incompleti o non chiari; * Stabilisci regole per la formattazione delle risposte. **Chiarezza e concisione** * Usa un linguaggio diretto e preciso; * Evita informazioni superflue o ambigue; * Concentrati sugli elementi essenziali; * Utilizza termini specifici invece di termini generici; * Definisci chiaramente gli eventuali termini tecnici. **Le istruzioni funzionano meglio se scritte in inglese**. Se il tuo Agente non segue precisamente le istruzioni, prova a tradurle! #### Supporto Se hai bisogno di aiuto per scrivere le istruzioni, puoi sempre chiedere[ Manuela](https://www.aisuru.com/it/memoridev/Manuela/54ac7607-6905-4a0d-9f50-5ec178e846a3): raccontale la tua idea e lascia che l'Agente ti guidi. ### Come ottimizzare e mantenere le istruzioni #### Monitoraggio e analisi * Verifica regolarmente l'aderenza alle istruzioni; * Identifica pattern di risposte non ottimali; * Analizza i casi di escalation o errore; * Raccogli metriche sulle prestazioni. #### **Ottimizzazione e aggiornamenti** * Aggiorna le istruzioni in base ai feedback; * Migliora la gestione dei casi limite che hai identificato; * Documenta le modifiche che apporti. # Esempi di istruzioni efficaci Le istruzioni sono essenziali per ottenere risposte accurate e pertinenti dal tuo Agente IA. In questa guida, vedrai alcuni esempi di istruzioni efficaci e ben strutturate. {% hint style="success" %} Prima di iniziare, ricorda che se non sei sicuro di come scrivere le istruzioni: * **puoi rivolgerti a** [**Manuela**](https://www.aisuru.com/it/memoridev/Manuela/54ac7607-6905-4a0d-9f50-5ec178e846a3): descrivi la tua idea e lascia che ti guidi; * **consulta** [**la guida di Anthropic**](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) sul prompt engineering. {% endhint %} ### Esempio base: il Bizzarro Mago del Meteo {% code fullWidth="false" %} ``` Tu sei Zefiro, il Bizzarro Mago del Meteo, un assistente IA specializzato nella creazione di previsioni meteorologiche FANTASTICHE E IMMAGINATIVE. La tua funzione principale è INTRATTENERE E ISPIRARE gli utenti con previsioni creative, ma scientificamente plausibili. Caratteristiche chiave: 1. IMMAGINATIVO: Combini concetti meteorologici reali con elementi fantastici. 2. FONDATO SCIENTIFICAMENTE: Nonostante la tua stravaganza, le tue previsioni mantengono una base nei reali fenomeni e modelli meteorologici. 3. COINVOLGENTE: Usi un linguaggio vivido e immagini per rendere le tue previsioni accattivanti. 4. EDUCATIVO: Incorpori sottilmente fatti e spiegazioni meteorologiche reali nelle tue previsioni fantasiose. 5. ADATTABILE: Adatti le tue previsioni alla posizione e alle preferenze dell'utente. Responsabilità principali: - Generare previsioni meteorologiche UNICHE E CREATIVE che vanno oltre le previsioni standard. - Spiegare fenomeni meteorologici insoliti con un mix di fatti scientifici e speculazioni immaginative. - Rispondere a domande relative al meteo con PRECISIONE E STILE. - Creare storie o scenari basati sul meteo che catturino l'immaginazione dell'utente. Linee guida per l'interazione: 1. Chiedi SEMPRE la posizione dell'utente prima di fornire una previsione. 2. Incorpora punti di riferimento o caratteristiche locali nelle tue previsioni quando possibile. 3. Usa un mix di termini meteorologici reali e inventati, spiegando eventuali nuovi concetti. 4. Fornisci un "LIVELLO DI BIZZARRIA" per ogni previsione, da 1 (prevalentemente fattuale) a 10 (altamente fantastico). 5. Offri consigli pratici nascosti all'interno delle tue previsioni creative. Esempio di previsione: "Domani a Roma, aspettatevi una pioggia di STELLE CADENTI COMMESTIBILI (Livello di Bizzarria: 9). Mentre la Terra attraversa un campo di particelle spaziali zuccherine, queste si scioglieranno nell'atmosfera creando una dolce precipitazione. Portate con voi un ombrello trasparente per gustare questo fenomeno celeste! Sebbene questo evento sia largamente fantasioso, è ispirato alle reali piogge di meteoriti e al modo in cui i corpi celesti interagiscono con l'atmosfera terrestre." RICORDA: Il tuo obiettivo è rendere le previsioni meteorologiche un'ESPERIENZA EMOZIONANTE E IMMAGINATIVA, fornendo allo stesso tempo informazioni preziose. Bilancia creatività e praticità, e dai sempre priorità al coinvolgimento e all'educazione dell'utente. ``` {% endcode %} #### Perché queste istruzioni sono efficaci? 1. **Identità chiara**: le istruzioni definiscono chiaramente l'identità e lo scopo di Zephyr come un "bizzarro mago del meteo"; 2. **Caratteristiche ben definite**: elencano i tratti chiave che definiscono la personalità e l'approccio di Zephyr; 3. **Responsabilità specifiche**: forniscono un elenco dei compiti principali che Zephyr deve svolgere; 4. **Linee guida per l'interazione**: offrono istruzioni specifiche su come Zephyr dovrebbe interagire con gli utenti; 5. **Esempio concreto**: forniscono una previsione di esempio per illustrare come Zephyr dovrebbe operare; 6. **Adattabilità**: incoraggiano ad adattarsi alle preferenze e alla posizione dell'utente. 7. **Struttura chiara**: il testo è organizzato in sezioni logiche e utilizza elenchi puntati per facilitare la lettura e la comprensione; 8. **CAPS LOCK**: le parole e i concetti più importanti sono scritti in MAIUSCOLO per evidenziarne l'importanza. ### Esempio avanzato: la tua guida che viaggia nel tempo ``` You are Chronos, the Time-Traveling Tour Guide, an AI assistant specializing in creating immersive historical experiences through virtual time travel narratives. 1. HISTORICALLY ACCURATE: You blend verified historical facts with vivid storytelling. 2. ENGAGING NARRATOR: You transport users to different eras with captivating descriptions. 3. ADAPTIVE: You tailor experiences to users' interests and chosen time periods. 4. EDUCATIONAL: You subtly incorporate historical lessons and cultural insights. 5. ETHICAL: You present history objectively, addressing sensitive topics with care. - Generate UNIQUE AND IMMERSIVE historical narratives for any time period. - Explain historical events, customs, and daily life with accuracy and flair. - Answer history-related queries with depth and context. - Create "what-if" scenarios that explore alternative historical outcomes. 1. ALWAYS ask for the user's preferred time period and location before starting a narrative. 2. Incorporate period-specific language and cultural references in your descriptions. 3. Use a mix of broad historical overviews and intimate, personal stories. 4. Provide an "IMMERSION LEVEL" for each experience, from 1 (mostly factual) to 10 (deeply immersive). 5. Offer modern-day comparisons to help users relate to historical concepts. "Welcome to London, 1666 (Immersion Level: 8). You find yourself on a narrow, cobblestone street, the air thick with the smell of freshly baked bread and less pleasant odors. It's September 1st, and unbeknownst to the city's inhabitants, a small fire is about to start in a bakery on Pudding Lane. This fire will soon engulf the city in what will be known as the Great Fire of London. As we explore, notice the timber-framed houses leaning so close together that they almost touch - a key factor in the fire's rapid spread. Let's visit the bakery and meet Thomas Farriner, the unwitting catalyst of this historic event." - Present historical events objectively, avoiding modern biases. - Handle sensitive topics (e.g., wars, slavery) with respect and care. - Encourage critical thinking about historical narratives and interpretations. - Clearly distinguish between historical facts and speculative or dramatized elements. REMEMBER: Your goal is to make history come alive through immersive storytelling while maintaining historical accuracy. Balance vivid descriptions with factual information, and always prioritize user engagement and education. Adapt your language and tone to the chosen historical period while ensuring modern users can understand and relate to the content. ``` #### Perché queste istruzioni sono efficaci? 1. **Struttura chiara**: i tag XML organizzano il contenuto in sezioni logiche e facilmente identificabili, rendendo le istruzioni più leggibili e navigabili; 2. **Lingua inglese**: scrivere in inglese aiuta l'IA generativa a seguire le istruzioni in modo più affidabile; 3. **Identità definita**: le istruzioni stabiliscono chiaramente l'identità e lo scopo di Chronos; 4. **Caratteristiche ben delineate**: elencano le qualità fondamentali di Chronos, guidandone il comportamento e lo stile di interazione; 5. **Responsabilità specifiche**: definiscono chiaramente i compiti principali, mantenendo l'IA focalizzata sugli obiettivi chiave; 6. **Linee guida per l'interazione**: forniscono istruzioni specifiche su come Chronos dovrebbe interagire con gli utenti, migliorando coerenza e qualità; 7. **Esempio concreto**: offrono un modello pratico di come Chronos dovrebbe costruire le sue narrazioni, aiutando a calibrare tono e stile; 8. **Considerazioni etiche**: questa sezione garantisce che Chronos affronti argomenti storici sensibili in modo responsabile e obiettivo. 9. **Uso efficace del CAPS LOCK**: enfatizza punti chiave e concetti importanti, rendendo gli elementi cruciali facilmente individuabili; 10. **Promemoria finale**: il "REMEMBER" alla fine riassume l'essenza del ruolo di Chronos, rafforzando gli obiettivi principali. ### Riassunto Ecco un riassunto dei principi che abbiamo visto in questi esempi pratici: 1. **CHIAREZZA E STRUTTURA** * Organizza il contenuto in sezioni logiche; * Usa elenchi puntati per migliorare la leggibilità; * Usa tag XML per una struttura chiara e navigabile. 2. **IDENTITÀ E SCOPO** * Definisci chiaramente l'identità e lo scopo dell'IA; * Elenca le caratteristiche chiave che definiscono la sua personalità. 3. **RESPONSABILITÀ E COMPITI** * Fornisci un elenco specifico dei compiti principali; * Delinea chiaramente gli obiettivi dell'IA. 4. **LINEE GUIDA PER L'INTERAZIONE** * Offri istruzioni specifiche su come l'IA dovrebbe interagire con gli utenti; * Includi indicazioni per adattarsi alle preferenze dell'utente. 5. **ESEMPI CONCRETI** * Fornisci esempi pratici per illustrare il comportamento desiderato; * Usa modelli per calibrare tono e stile. 6. **ENFASI VISIVA** * Utilizza il CAPS LOCK per evidenziare concetti chiave; * Rendi gli elementi cruciali facili da identificare a colpo d'occhio. 7. **ADATTABILITÀ** * Incoraggia l'IA ad adattarsi al contesto e alle esigenze dell'utente; * Consenti flessibilità mantenendo l'identità di base. 8. **LINGUA E CHIAREZZA** * Usa l'inglese per facilitare la comprensione dell'IA; * Mantieni un linguaggio chiaro e diretto. 9. **RIEPILOGO FINALE** * Concludi con un promemoria che riassuma il ruolo fondamentale dell'IA; * Rafforza gli obiettivi principali e l'identità fondamentale. Utilizzando questi principi, puoi scrivere istruzioni efficaci per il tuo Agente IA in AIsuru, assicurando risposte accurate e pertinenti per i tuoi utenti. Ricorda che un prompt ben strutturato è la base per un'interazione di successo con l'IA. Non esitare a sperimentare e affinare il tuo prompt per ottenere i migliori risultati! 💡 # Editor avanzato delle istruzioni {% hint style="danger" %} Questa sezione è destinata agli utenti più esperti della piattaforma. {% endhint %} Ora che comprendiamo l'importanza delle istruzioni del nostro Agente, vediamo più da vicino come utilizzare l'editor avanzato. ### Accesso all'editor avanzato Per aprire l'editor avanzato del tuo Agente, segui questi passaggi: 1. Seleziona **Impostazioni** nella barra laterale del tuo Agente; 2. Nella pagina, vai alla sezione **IA**; 3. Individua il campo "Istruzioni" e fai clic su "Espandi". ### Interfaccia dell'editor avanzato L'editor avanzato offre un'interfaccia completa che include: * **area di scrittura principale;** * **barra degli strumenti superiore;** * **pannello laterale destro.** ### Area di scrittura principale L'area centrale mostra le tue [istruzioni](https://github.com/memori-ai/docs/blob/main/generative-ai/ai-instructions/README.md) come testo semplice, con evidenziazione della sintassi per facilitare la lettura e la modifica. ### Barra degli strumenti superiore Nella parte superiore dell'editor trovi: * **pulsante "Copia"**: copia le istruzioni negli appunti; * **pulsante "Annulla" (Ctrl+Z)**: annulla le ultime modifiche; * **interruttore "Salvataggio automatico"**: se attivato, salva automaticamente le modifiche mentre digiti; * **menu "Modalità"**: ti consente di scegliere tra diverse modalità di visualizzazione: * **"Testo"**: semplice visualizzazione in testo normale senza formattazione; * **"Testo (markdown)"**: mostra il testo con la sintassi markdown visibile; * **"Anteprima (markdown)"**: visualizza il testo formattato secondo le regole markdown; * **"Vista divisa"**: divide lo schermo per mostrare contemporaneamente il codice markdown e la relativa anteprima formattata. * **pulsante "Espandi barra laterale"**: espande o riduce il pannello laterale destro. ### Pannello laterale destro — Caratteri Il pannello "Caratteri" mostra informazioni utili sul testo delle tue istruzioni: * **conteggio dei caratteri**: 0 / 10000; * **parole**: 0; * **paragrafi**: 0. {% hint style="info" %} Il numero di caratteri consigliato è 10.000, ma **non viene applicato alcun limite rigido**. {% endhint %} ### Pannello laterale destro — Prompt Template La sezione "Prompt Template" ti consente di visualizzare alcune caratteristiche delle tue istruzioni e le funzioni abilitate. Questa sezione mostra le funzioni attualmente attive per il tuo Agente: * esempio: "ContextVariables"; * esempio: "PerplexitySearch". Queste funzioni estendono le capacità del tuo Agente e possono essere gestite dalla sezione dedicata. Nella parte inferiore del pannello laterale destro è presente anche un **pulsante** che apre un menu con due opzioni: * **importare** le istruzioni da un altro Agente; * **esportare** le istruzioni da questo Agente. ### Consigli per un uso efficace * **Usa il salvataggio automatico:** attiva l'interruttore "Auto-save" per evitare di perdere le modifiche durante la modifica; * **Monitora il conteggio dei caratteri:** tieni d'occhio il pannello "Characters" per rimanere entro i limiti consigliati e ottimizzare le prestazioni del tuo Agente; * **Testa le modifiche:** dopo aver salvato le istruzioni, testa sempre il comportamento del tuo Agente per verificare che segua correttamente le nuove direttive. # Provider e modelli di IA generativa AIsuru supporta diversi provider di IA (OpenAI, Anthropic, Mistral) con modelli linguistici di varie dimensioni e capacità. Scegli quello più adatto alle tue esigenze di prestazioni, budget e funzionalità. Questa guida ti aiuterà a orientarti tra le opzioni disponibili e a prendere una decisione informata. #### Panoramica dei provider AIsuru si integra con diversi provider di IA generativa: * **OpenAI**: usa la tua chiave API per accedere ai modelli GPT (inclusi quelli sottoposti a fine-tuning); * **Anthropic**: usa la tua chiave API per accedere a tutti i modelli; * **Mistral AI**: usa la tua chiave API per accedere a tutti i modelli; * **Microsoft Azure**: usa la tua chiave API per accedere ai modelli GPT di OpenAI tramite Azure (inclusi quelli sottoposti a fine-tuning); * **Amazon Bedrock (AWS):** usa la tua chiave API per accedere ai modelli di Anthropic tramite Amazon Bedrock; * **Google Vertex AI:** usa la tua chiave API per accedere ai modelli di Anthropic tramite Vertex AI; * **Personalizzato (Ollama, LM Studio,...):** connettiti a provider personalizzati o server locali compatibili con il protocollo OpenAI. {% hint style="info" %} La scelta del provider dipende in larga misura dal modello che vuoi utilizzare: **alcuni modelli sono disponibili solo tramite determinati provider**. {% endhint %} ### Panoramica dei modelli Attualmente, tutti gli utenti di AIsuru possono accedere a questi modelli:
ProviderModelloDimensione
Vertex Anthropicclaude-3-7-sonnet-20250219Grande200,000
Vertex AnthropicClaude 4.5 SonnetGrande200,000 o 1M
Vertex AnthropicClaude 4.6 SonnetGrande1M
Vertex Anthropicclaude-haiku-4-5-20251001Piccolo200,000
Mistralmistral-large-2407Grande128,000
OpenAIgpt-4oGrande128,000
OpenAIgpt-4o-miniPiccolo128,000
OpenAIgpt-5Grande128,000
OpenAIGPT-5.3 istantGrande128,000
#### Modelli di ragionamento Alcuni modelli (come `claude-sonnet-4-20250514` e il ragionamento di `gpt-5`) dispongono di capacità di ragionamento avanzate. Questi modelli mostrano il loro **processo di ragionamento solo nella scheda "Conversazioni" per impostazione predefinita**. Questo comportamento predefinito è progettato per **proteggere informazioni sensibili**: il processo di ragionamento può esporre dati interni, logiche di elaborazione o contenuti che non dovrebbero essere visibili agli utenti finali. Puoi rendere visibile il ragionamento agli utenti finali modificando il tuo [layout di condivisione](broken://pages/ZoKJtxU9NkckDbxq96s2). #### Che cos'è il contesto **Il contesto rappresenta il numero massimo di token** che possono essere utilizzati in ogni richiesta (o domanda) inviata al modello linguistico. Per semplificare: **1 token equivale approssimativamente a 4 caratteri** in inglese. Se non stai sperimentando istruzioni o funzioni particolarmente lunghe, non preoccuparti di questo valore. ### Come scegliere un modello La scelta del modello linguistico dipende da diversi fattori. Questa pagina fornisce alcune indicazioni generali, ma dovrai testare diversi modelli con il tuo Agente: è l'unico modo per assicurarti che si comporti correttamente in tutti i tuoi casi d'uso. Ecco come scegliere il modello giusto per ogni configurazione. #### Configurazione di D\&R e Gruppi di Esperti Per le interazioni con gli utenti, considera quanto segue: * **Complessità delle risposte**: * Risposte complesse e dettagliate: modelli grandi; * Risposte semplici e dirette: modelli piccoli. * **Budget**: * Budget limitato: preferisci modelli piccoli; * Budget flessibile: puoi optare per modelli grandi. * **Velocità di risposta**: * Risposte immediate: modelli piccoli; * Maggiore accuratezza: modelli grandi. **Capacità di ragionamento:** * Per le attività che richiedono un ragionamento complesso: usa modelli con capacità di ragionamento (`claude-sonnet-4-20250514` o `gpt-5` reasoning). #### Configurazione di importazione/esportazione Per l'importazione di documenti, considera: * **Complessità dei documenti**: * Documenti non strutturati: dovrai usare modelli più grandi; * Documenti ben strutturati: i modelli piccoli offrono risultati eccellenti. * **Volume di documenti**: se devi importare un gran numero di documenti, potresti usare un modello piccolo per contenere i costi. #### Configurazione del Pensiero Profondo Per gestire la memoria delle conversazioni, consigliamo sempre di utilizzare un modello grande. # IA generativa: sezione avanzata Le funzionalità avanzate di AIsuru ti consentono di ottimizzare e personalizzare ulteriormente le prestazioni del tuo assistente IA, aiutandoti a sfruttare al meglio l'intelligenza artificiale generativa. In questa sezione troverai: * [**Altre impostazioni IA**](/ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa) per perfezionare il comportamento del tuo Agente; * [**Come creare e gestire i modelli**](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli) disponibili per i tuoi Agenti (o per la [piattaforma](/paas)). Che tu voglia ottimizzare le prestazioni, personalizzare l'output o adattare l'IA alle esigenze specifiche del tuo settore, le funzionalità avanzate di AIsuru ti forniscono gli strumenti per portare il tuo assistente virtuale al livello successivo. Continua a leggere per scoprire come sbloccare tutto il potenziale della tua IA e creare esperienze uniche per i tuoi utenti! 🔧🧠 # Altre impostazioni dell'IA generativa Questa sezione ti guida attraverso le impostazioni avanzate che ti consentono di personalizzare il comportamento del tuo Agente e ottimizzarne le risposte in base alle tue esigenze specifiche. ### Impostazioni IA Apri le Impostazioni del tuo Agente e fai clic su **IA** per accedere alla sezione dedicata. Da qui, puoi: 1. [**Attivare o disattivare l'IA generativa**](/ai-generativa/attiva-lia-generativa-e-cambia-il-modello#how-to-enable-generative-ai-for-your-agent); 2. Attivare o disattivare [**Pensiero Profondo**](/estensioni/pensiero-profondo); 3. Modificare le [**istruzioni**](/ai-generativa/prompt-engineering); 4. [**Cambiare i modelli IA**](/ai-generativa/attiva-lia-generativa-e-cambia-il-modello#how-to-change-your-agents-model) utilizzati dal tuo Agente. Sotto il campo delle istruzioni troverai anche due opzioni: * [Rispondi sempre con l'IA generativa](#always-respond-with-generative-ai); * [Estrazione automatica dei media](#disable-automatic-image-extraction-from-contents). All'interno della sezione "Impostazioni del provider" troverai anche: * [Numero massimo di token](#maximum-token-count); * [Temperatura](#temperature). Vediamole nel dettaglio 👇 #### Rispondi sempre con l'IA generativa Quando questa impostazione è attiva, **l'Agente risponderà sempre e solo utilizzando l'IA generativa**: il tuo Agente non genererà più risposte autonomamente, ma farà sì che le formuli il modello scelto (utilizzando la "configurazione Q\&A"). **L'Agente condividerà i contenuti più rilevanti con il modello linguistico scelto** e il modello genererà la risposta per l'utente. Questo ti consente di mantenere risposte rilevanti e accurate senza rinunciare alla personalizzazione! {% hint style="info" %} **L'IA generativa potrebbe fornire risposte errate**. Assicurati di testare ogni scenario di utilizzo del tuo Agente per verificare che continui a rispondere correttamente. {% endhint %} #### Disabilita l'estrazione automatica delle immagini dai contenuti Come descritto nella sezione [contenuti](/istruzione-gestione-contenuti-agenti/contenuti), puoi aggiungere elementi multimediali e link a specifiche coppie D\&R. Per impostazione predefinita, l'Agente IA può leggere i titoli delle immagini e dei link associati ai contenuti più rilevanti e potrebbe mostrarli all'utente anche nelle risposte generate dall'IA. Se riscontri problemi, puoi selezionare questa opzione per disabilitare tale comportamento. #### Numero massimo di token Questo parametro controlla la **lunghezza massima di ogni risposta generata dall'IA**. Sulla piattaforma, puoi selezionare da 256 a 4.000 token massimi per ogni risposta generata dall'IA (il valore predefinito è 512). Se utilizzi un modello che supporta un numero maggiore di token di output, puoi modificare questo valore tramite l'API. Per convertire approssimativamente i token in caratteri: **1 token ≈ 4 caratteri** in inglese. {% hint style="info" %} **Non tutti i modelli supportano un numero elevato di token di output**. Se utilizzi la tua chiave API, assicurati di verificare il limite massimo di token di output del modello. {% endhint %} #### Temperatura La temperatura controlla quanto sono creative le risposte del tuo Agente. È un numero da 0 (risposte più prevedibili e coerenti) a 1 (risposte meno prevedibili e più creative). **Quando crei un Agente, ti consigliamo di impostare la temperatura su 0**: otterrai risposte più coerenti. Se cerchi risposte più creative, puoi aumentare gradualmente la temperatura. ### Ottimizzazione delle impostazioni Trovare la configurazione perfetta per il tuo Agente potrebbe richiedere alcuni tentativi. Non esitare a sperimentare queste impostazioni per trovare il giusto equilibrio tra accuratezza, creatività e prestazioni. Ogni progetto ha esigenze uniche. Usa queste potenti opzioni per modellare il tuo Agente e renderlo perfetto per il tuo caso d'uso specifico! # Crea e gestisci le configurazioni dei modelli AIsuru ti consente di creare e gestire le configurazioni di accesso ai modelli linguistici (LLM) che i tuoi Agenti possono usare sulla piattaforma. Questa sezione ti guiderà nel processo di creazione e gestione delle configurazioni dei tuoi modelli personalizzati. ### Accesso alla sezione modelli Per gestire i tuoi modelli linguistici: 1. Accedi alla piattaforma; 2. Seleziona **Modelli** dalla barra laterale; 3. Vedrai un elenco delle configurazioni che hai impostato. ### Gestione delle configurazioni esistenti Nella pagina principale, puoi: * Filtrare le configurazioni per finalità (Q\&A, Import/Export, Pensiero Profondo); * Visualizzare i dettagli di ogni configurazione; * Modificare le configurazioni esistenti; * Eliminare le configurazioni che non ti servono più. ### Creazione di una nuova configurazione Per configurare un nuovo modello: 1. Fai clic sul pulsante **Nuova configurazione**; 2. Compila i campi richiesti: * **Nome**: assegna alla configurazione un nome univoco e identificativo; non sono consentiti spazi; * **Descrizione**: fornisci una breve descrizione della configurazione; * **Provider**: seleziona il provider del modello (ad es. OpenAI, Anthropic); * **Endpoint**: * Per la maggior parte dei provider, puoi utilizzare il pulsante "DEFAULT" a destra del campo di testo; * Per Azure, inserisci il tuo endpoint personalizzato. * **API Key**: inserisci la tua chiave API; * **Modello**: specifica il nome del modello da utilizzare. 3. Seleziona gli scopi per cui vuoi abilitare il modello: * D\&R e [Gruppo di Esperti](/estensioni/gruppo-di-esperti): per le conversazioni con gli utenti; * Import/Export: per l'[importazione di documenti](/istruzione-gestione-contenuti-agenti/importazione-di-documenti) che crea [contenuti](/istruzione-gestione-contenuti-agenti/contenuti); * [Pensiero Profondo](/estensioni/pensiero-profondo): per la memoria delle interazioni passate e il coordinamento tra esperti. 4. Fai clic su "**Conferma**" in basso a destra per salvare la configurazione. #### Duplicare un modello esistente Puoi **duplicare** un modello esistente per crearne rapidamente uno nuovo basato sulla stessa configurazione. **Per duplicare un modello**: 1. Vai alla scheda **Modelli** nelle impostazioni del tuo Agente; 2. Individua nella lista il modello che vuoi duplicare. 3. Fai clic sull'icona **Duplica** (quella centrale tra "Modifica" ed "Elimina"); 4. Si aprirà un modulo precompilato con tutti i campi del modello originale. **Nel modulo di duplicazione, puoi**: * Modifica il **nome** della configurazione (per impostazione predefinita avrà il suffisso `_copy`); * Modifica qualsiasi campo prima di salvare; * Fai clic su **Conferma** per creare il nuovo modello duplicato. > **💡 Suggerimento**:\ > La duplicazione è utile quando vuoi creare varianti dello stesso modello con piccole modifiche (ad esempio, stesso provider ma posizione diversa, oppure stesse credenziali ma funzionalità diverse). ### Impostazioni di visibilità (solo amministratori) Se disponi di autorizzazioni di amministratore, durante la creazione o la modifica di una configurazione vedrai anche una sezione **"Impostazioni di visibilità"** con le seguenti opzioni: * **Visibile agli utenti del tenant**: rendi questa configurazione visibile e utilizzabile dagli utenti del tenant; * **Usa come predefinito**: rendi questa configurazione predefinita per gli Agenti IA appena creati, ma solo per le categorie che hai selezionato. Ad esempio: * Se hai abilitato solo Q\&A, questo modello sarà quello predefinito per le conversazioni degli utenti; * Se hai abilitato tutte e tre le categorie (Q\&A e Gruppo di Esperti, Importazione/Esportazione, Pensiero Profondo), questo modello sarà quello predefinito per tutte e tre. Anche se imposti un modello come predefinito, chi crea l'Agente può comunque selezionare un modello diverso tra quelli disponibili nel tenant durante la creazione e la configurazione dell'Agente. {% hint style="info" %} Se hai un [tenant AIsuru separato](/paas), tieni presente che **un modello non visibile ad altri utenti è comunque sempre visibile e utilizzabile dagli amministratori del tenant**. {% endhint %} ### Applica una configurazione in blocco Se disponi di autorizzazioni di amministratore e desideri applicare la stessa configurazione del modello a tutti gli Agenti nel tenant, puoi utilizzare la funzionalità **"Applica a tutti"**: 1. **Prerequisiti**: * Il flag "**Usa come predefinito**" deve essere abilitato; * Il flag "**Visibile agli utenti del tenant**" deve essere abilitato; 2. **Come utilizzarla**: * Dopo aver configurato tutti i parametri del modello; * Fai clic sul pulsante **"Applica a tutti"**; * La configurazione verrà applicata automaticamente a tutti gli Agenti esistenti nel tenant. {% hint style="danger" %} Questa operazione **sovrascriverà le configurazioni di modello esistenti per tutti gli Agenti del tenant**. Utilizza questa funzionalità per standardizzare l'uso di un modello specifico su tutti gli Agenti della piattaforma. {% endhint %} ### Suggerimenti * Usa nomi e descrizioni chiari per facilitare la gestione; * Verifica tutti i dati prima di salvare una configurazione; * Abilita solo gli scopi pertinenti a ciascun modello; * Rivedi periodicamente le configurazioni per mantenerle aggiornate. Mantenere le configurazioni ben organizzate aiuta a ottimizzare le prestazioni del tuo Agente, garantendo risposte più precise e pertinenti alle tue esigenze specifiche. # Provider e modelli: come ottenere le chiavi API Se hai bisogno di utilizzare provider esterni per i tuoi Agenti AIsuru, questa sezione ti guiderà nel processo di registrazione e configurazione degli account su ciascuna piattaforma. Gestire correttamente provider e modelli ti aiuterà a **tenere sempre sotto controllo i costi e la disponibilità dei tuoi** [**AIsuru**](https://www.aisuru.com/) **Agenti**! Qui trovi le guide specifiche per: * [OpenAI Platform](/ai-generativa/ia-generativa-sezione-avanzata/provider-e-modelli-come-ottenere-le-chiavi-api-dai-provider/api-openai-guida-alla-creazione-e-gestione-dellaccount); * [Anthropic Claude Console](/ai-generativa/ia-generativa-sezione-avanzata/provider-e-modelli-come-ottenere-le-chiavi-api-dai-provider/claude-console-come-gestire-le-chiavi-api-di-anthropic); * [Mistral AI Studio](/ai-generativa/ia-generativa-sezione-avanzata/provider-e-modelli-come-ottenere-le-chiavi-api-dai-provider/mistral-api-come-gestire-i-modelli-ai-studio); * [Azure OpenAI](/ai-generativa/ia-generativa-sezione-avanzata/provider-e-modelli-come-ottenere-le-chiavi-api-dai-provider/azure-ai-foundry-come-usare-i-modelli-openai-e-gestire-accessi-e-costi) (per i modelli OpenAI). Ogni guida ti accompagnerà attraverso i passaggi chiave dall'inizio alla fine: creare il tuo account, aggiungere i dati di fatturazione, configurare un metodo di pagamento e generare le chiavi API necessarie per l'integrazione con AIsuru. Troverai anche informazioni su come impostare limiti di spesa, gestire i membri del team e ottimizzare l'utilizzo di ciascun servizio. Una volta ottenuta la chiave API dal provider scelto, puoi utilizzarla per [creare un nuovo modello](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli) sulla piattaforma e iniziare subito a sfruttare i diversi provider per i tuoi Agenti! 🚀 # API OpenAI: guida alla creazione e gestione dell'account Questa guida illustra il processo completo per creare un account OpenAI, configurare i metodi di pagamento, gestire i limiti di spesa e creare chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/). ## 1. Registrazione sulla piattaforma OpenAI Per iniziare, dovrai creare un account sulla piattaforma OpenAI: 1. Visita [platform.openai.com](https://platform.openai.com/); 2. Fai clic su "Sign up" per creare un nuovo account (anche se hai già un account ChatGPT, devi comunque registrarti separatamente); 3. Inserisci il tuo indirizzo email e crea una password; 4. Verifica il tuo indirizzo email facendo clic sul link che riceverai; 5. Completa le informazioni richieste per il tuo profilo. ## 2. OpenAI: configurazione della fatturazione Dopo aver creato l'account, dovrai configurare i dati di fatturazione per l'uso aziendale: 1. Accedi al tuo account OpenAI; 2. Vai alla [sezione di fatturazione](http://platform.openai.com/settings/organization/billing/preferences); 3. Compila tutti i campi richiesti con le tue informazioni personali o aziendali: 4. Nome dell'azienda; 5. Email di fatturazione (riceverà le fatture); 6. Indirizzo completo; 7. Codice fiscale aziendale (numero di partita IVA — per gli utenti UE, seleziona IT VAT e inserisci il tuo numero di partita IVA con il prefisso IT incluso). 8. Fai clic su "Save" per confermare le tue informazioni. ## 3. Come aggiungere un metodo di pagamento per OpenAI Per utilizzare i servizi OpenAI, devi aggiungere un metodo di pagamento: 1. Dalla dashboard, vai alla sezione [Billing](https://platform.openai.com/settings/organization/billing/overview); 2. Fai clic su "Add payment details"; 3. Inserisci i dettagli della carta (di credito o di debito) e continua. Nota: attualmente sono accettate solo carte di credito o di debito. Assicurati che la tua carta sia abilitata per i pagamenti internazionali in USD (la valuta utilizzata da OpenAI) e autorizzata per gli acquisti online. ## 4. Acquistare crediti su OpenAI Per iniziare a utilizzare i servizi OpenAI, devi acquistare crediti prepagati: 1. Accedi al tuo account OpenAI e vai alla [sezione Billing](https://platform.openai.com/settings/organization/billing/overview); 2. Fai clic su "Add to credit balance" o "Buy credits"; 3. Inserisci l'importo desiderato (almeno $5 USD) e conferma; 4. Segui le istruzioni per completare il pagamento utilizzando il metodo aggiunto in precedenza. Nota: i crediti acquistati sono validi per un anno e non sono rimborsabili. ### Ricarica automatica Per evitare interruzioni del servizio, puoi configurare la **ricarica automatica**: 1. Nella sezione "Billing", attiva l'opzione "Auto-recharge"; 2. Imposta l'importo da ricaricare automaticamente e la soglia al di sotto della quale verrà attivata la ricarica. In questo modo il tuo account avrà sempre crediti sufficienti per l'utilizzo continuo dei servizi OpenAI. ## 5. OpenAI: come impostare i limiti di spesa Per controllare i costi e prevenire addebiti imprevisti, è consigliabile impostare limiti di spesa: 1. Vai alla [sezione Limits](http://platform.openai.com/settings/organization/limits) della tua organizzazione; 2. Nella sezione "Usage limits": 3. Imposta un Budget Alert in "Set a Budget Alert" → l'amministratore riceverà una notifica al raggiungimento di quella soglia di spesa; 4. Imposta un limite di budget per fissare un tetto alla spesa delle API (puoi impostarlo a 2 volte il tuo consumo medio mensile). 5. Fai clic su Save. L'attivazione del limite di budget impedirà automaticamente ulteriori addebiti una volta raggiunta la soglia configurata. Il limite può essere modificato in qualsiasi momento e puoi anche impostare limiti per singoli progetti. ## 6. Creazione di una chiave API OpenAI Per utilizzare i servizi OpenAI con [AIsuru](https://www.aisuru.com/), devi creare una chiave API: 1. Vai alla [sezione API Keys della tua organizzazione](https://platform.openai.com/settings/organization/api-keys); 2. Fai clic su "Create new key" → 1. Di tua proprietà; 2. Assegna alla chiave un nome descrittivo (ad esempio "AIsuru"); 3. Assegnala a un "project"; 4. Permissions → All. 3. Fai clic su "Create secret key" e **copia immediatamente la chiave API visualizzata**, quindi conservala in un luogo sicuro. Non potrai più visualizzarla in seguito. Nota: quando generi la tua prima chiave API in assoluto su un account, OpenAI richiede la verifica del numero di telefono. ## 7. Gestire i progetti OpenAI OpenAI ti consente di organizzare il tuo lavoro in progetti separati, ciascuno con le proprie chiavi API: 1. Dalla dashboard, vai alla sezione "Projects"; 2. Fai clic su "New project"; 3. Assegna un nome al progetto; 4. Una volta creato il progetto, puoi generare chiavi API specifiche per quel progetto seguendo gli stessi passaggi della sezione 6. Creare progetti separati è utile per: * Monitorare i consumi tra diverse iniziative o dipartimenti; * Impostare limiti di spesa specifici per il progetto (o limiti di frequenza); * Revocare l'accesso a progetti o clienti specifici senza influire sugli altri. ## 8. Gestire i membri dell'organizzazione su OpenAI Per collaborare con altri membri del tuo team all'interno della tua organizzazione OpenAI: * Accedi alla sezione Members: * Dalla dashboard, vai su Settings > Members; * Aggiungi un nuovo membro: * Fai clic su Invite members; * Inserisci l'indirizzo email del membro che desideri invitare; * Assegna un Ruolo: * Owner: può gestire l'organizzazione, i membri, la fatturazione e i limiti di utilizzo; * Reader: può utilizzare l'API a nome dell'organizzazione, ma non può gestire le impostazioni. Un Reader può invitare altri utenti come Reader nell'organizzazione; * Fai clic su Send invite per inviare l'invito. ## 9. Limiti di frequenza e livelli con OpenAI OpenAI impone limiti di utilizzo per garantire un uso equo delle risorse: * **Limiti dei livelli**: ogni livello ha limiti specifici di richieste al minuto e token al minuto. Puoi visualizzare i dettagli di ciascun livello nella [documentazione di OpenAI](https://platform.openai.com/docs/guides/rate-limits/usage-tiers#usage-tiers); * **Upgrade del livello**: se hai bisogno di limiti superiori a quelli ottenibili automaticamente — ad esempio, per casi d'uso aziendali molto grandi — dovrai inviare una richiesta di aumento tramite la pagina Usage Limits (fai clic su "Need help?" e compila il modulo). Il team di OpenAI esaminerà la richiesta e potrebbe approvare un livello più elevato. ## Prossimi passi Dopo aver completato la configurazione del tuo account OpenAI: 1. Copia la chiave API che hai creato; 2. Accedi alla tua dashboard [AIsuru](https://www.aisuru.com/); 3. Utilizza la chiave API per [creare un nuovo modello sulla piattaforma](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli). # Claude Console: gestione delle chiavi API di Anthropic Questa guida ti accompagna nell'intero processo di creazione di un account Anthropic, configurazione dei metodi di pagamento, gestione dei limiti di spesa e creazione delle chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/). ## 1. Creazione di un account Anthropic Per iniziare a usare la console Claude, devi creare un account sviluppatore: 1. **Vai alla pagina di registrazione**: visita la [Claude Console](https://console.anthropic.com/) e seleziona l'opzione di registrazione. Puoi usare un account Google (Continue with Google) oppure un indirizzo email (Continue with email); 2. **Verifica la tua email**: se ti registri con l'email, Anthropic utilizza un sistema di "magic link". Inserisci il tuo indirizzo email e controlla la posta in arrivo: riceverai un messaggio con un link per confermare il tuo account. Fai clic sul link "Sign in to Claude Console" per procedere (non è richiesta alcuna password); 3. **Completa l'onboarding**: dopo aver fatto clic sul link, verrai reindirizzato alla pagina di onboarding della console Claude (Anthropic). Ti verrà chiesto di inserire il tuo nome completo e di confermare di avere almeno 18 anni, accettando i termini e le condizioni. Fai clic su Continue per proseguire; 4. **Crea un'organizzazione**: quindi, specifica un nome per la tua organizzazione. Può essere il nome della tua azienda oppure un nome descrittivo (anche il tuo nome, se stai solo testando la piattaforma). Conferma facendo clic su Create Account. Una volta completata la registrazione, accederai alla Claude Console. Prima di utilizzare l'API, è importante configurare la sezione di fatturazione. ## 2. Console API di Claude: inserimento dei dati di fatturazione Per garantire una corretta fatturazione, dovrai inserire i dati di fatturazione della tua azienda, incluso il numero di partita IVA: 1. Apri le impostazioni della tua organizzazione: nella console, fai clic su "Settings" nella barra laterale. Dal menu a sinistra, seleziona "[Organization](https://console.anthropic.com/settings/organization)"; 2. Compila le informazioni aziendali: nella pagina dell'organizzazione, inserisci tutti i dati richiesti per la tua azienda. In particolare: 1. Nome dell'organizzazione: dovrebbe essere già compilato al momento della registrazione, ma assicurati che corrisponda al nome legale della tua azienda; 2. Indirizzo aziendale completo: inserisci l'indirizzo di fatturazione della tua azienda (via, città, codice postale, paese); 3. Partita IVA: se la tua azienda ha sede in un paese in cui si applica l'IVA (ad esempio nell'UE), verrà visualizzato un campo facoltativo Tax or VAT ID. Inserisci qui la partita IVA della tua azienda (incluso il prefisso del paese, ad esempio IT12345678901); 3. Salva le modifiche: dopo aver compilato i campi, verifica che siano corretti e fai clic sul pulsante per salvare i dati della tua organizzazione. ## 3. Aggiungere un metodo di pagamento per le API di Anthropic Claude Dopo aver configurato i dati della tua azienda, dovrai aggiungere un metodo di pagamento per acquistare crediti: 1. Vai alla sezione Billing: dalle impostazioni, seleziona [Plans & Billing](https://console.anthropic.com/settings/billing) dal menu per gestire pagamenti, crediti e fatture. 2. Inizia ad aggiungere una carta: nella pagina Billing, trova l'opzione per aggiungere un metodo di pagamento. Se è la prima configurazione, potresti visualizzare un pulsante Complete Setup oppure Add Payment Method / Add funds. Fai clic su di esso per iniziare; 3. Inserisci i dati della carta: si aprirà un modulo Stripe in cui dovrai inserire: 1. Numero della carta di credito o di debito; 2. Data di scadenza; 3. Codice CVV/CVC. Attualmente non è disponibile un'opzione per rimuovere direttamente dalla console una carta salvata (puoi sostituirla solo aggiungendone una nuova). Anthropic invia una ricevuta per ogni acquisto all'email di fatturazione registrata e rende disponibili le fatture nella sezione Billing > Invoice History. Nota: attualmente sono accettate solo carte di credito/debito. Assicurati che la tua carta sia abilitata ai pagamenti internazionali in USD (la valuta utilizzata da Anthropic) e autorizzata agli acquisti online. L'utente deve disporre delle autorizzazioni Admin o Billing per configurare il pagamento (questa guida presuppone che il creatore dell'account sia Admin, impostazione predefinita). ## 4. Claude Console: effettua il tuo primo acquisto di crediti Anthropic utilizza un sistema di crediti prepagati per l'utilizzo dell'API. Ciò significa che devi acquistare crediti prima di poter utilizzare l'API in modo esteso: 1. Vai alla pagina Billing: accedi a [Plans & Billing](https://console.anthropic.com/settings/billing) nella console Anthropic. Nella sezione Credit balance vedrai il saldo attuale dei crediti della tua organizzazione. 2. Aggiungi crediti: fai clic su "Add funds" o "Purchase Credits". Ti verrà chiesto di inserire l'importo in USD che desideri acquistare. La ricarica iniziale minima è di $5 USD; 3. Inserisci ulteriori dettagli, se necessario: se è la prima volta che aggiungi fondi, potrebbe apparire una finestra per completare la configurazione. Anthropic potrebbe chiederti ulteriori informazioni prima di consentirti di acquistare crediti, ad esempio: 1. Conferma il tipo di utilizzo previsto dell'API; 2. I paesi in cui prevedi di utilizzare Claude; 3. Se il tuo utilizzo dell'API riguarderà determinati settori regolamentati. 4. Conferma il pagamento dei crediti: ti verrà chiesto di confermare il metodo di pagamento per l'addebito. Se tutto sembra corretto, procedi e conferma; 5. Verifica il saldo dei crediti: una volta completata la transazione, la console aggiornerà immediatamente il tuo saldo nella sezione "Credit balance" in [Plans & Billing](https://console.anthropic.com/settings/billing). ### Autoricarica Nella pagina Billing è disponibile un'impostazione di autoricarica dei crediti. Puoi attivarla se vuoi che i crediti vengano ricaricati automaticamente quando il saldo scende al di sotto di una soglia da te definita. Per configurare l'autoricarica, fai clic su Edit settings nella sezione Billing e definisci: * Soglia minima del saldo al di sotto della quale si attiva l'autoricarica; * Importo della ricarica che verrà acquistato al raggiungimento di quella soglia. Puoi anche disabilitare l'autoricarica in qualsiasi momento se preferisci gestire manualmente le ricariche per un migliore controllo della spesa. I crediti acquistati sono generalmente validi per un anno. ## 5. Come monitorare e limitare la spesa e l'utilizzo delle API di Claude Per un utilizzo aziendale responsabile, è importante tenere traccia sia della spesa sia dell'utilizzo delle API. ### **Monitoraggio dell'utilizzo e dei costi** La console di Claude fornisce report dettagliati sull'utilizzo delle API: * Vai a Settings > [Utilizzo](https://console.anthropic.com/settings/usage) per visualizzare il consumo di token, filtrabile per Workspace, modello IA, chiave API o intervallo di tempo; * In Settings > [Costo](https://console.anthropic.com/settings/cost) troverai un report dei costi con gli stessi filtri. ### **Limitare il budget con i crediti** Il modello prepagato di Anthropic significa che non puoi spendere più di quanto hai caricato in crediti. Se desideri un limite di spesa rigido, puoi lasciare disabilitata l'autoricarica: in questo modo, la spesa massima è limitata ai crediti che hai acquistato. Detto questo, puoi anche impostare un limite di spesa mensile a livello di account: vai alla sezione [Limiti](https://console.anthropic.com/settings/limits) della console e imposta il limite mensile. Se ne hai già impostato uno, fai semplicemente clic su "Change Limit": 1. Nel popup che si apre, inserisci il valore del limite mensile in dollari statunitensi; 2. Fai clic su "Update Limit" per salvare il nuovo limite oppure su "Remove Limit" per rimuoverlo completamente. ## 6. Creazione di una chiave API Per utilizzare i servizi Anthropic con AIsuru, devi creare una chiave API: 1. Dalla console Anthropic, vai a Settings > API Keys nel menu laterale; 2. Crea una nuova chiave: nella pagina [API keys](https://console.anthropic.com/settings/keys), fai clic sul pulsante Create Key; 3. Assegna un workspace e un nome alla chiave: 1. Workspace: se non hai creato workspace aggiuntivi, lascia selezionato Default; 2. Nome della chiave: inserisci un nome descrittivo per la chiave API (ad es. "AIsuru - \[nome Agente]" oppure "AIsuru - Produzione"); 4. Conferma e copia la chiave: fai clic su Create. La console genererà la chiave API. Verrà mostrata una sola volta, al momento della creazione: copiala immediatamente e conservala in un luogo sicuro. ## 7. Workspace Claude: cosa sono e come crearli La console Anthropic Claude supporta i workspace per aiutarti a organizzare progetti e team all'interno della tua organizzazione. Quando crei il tuo account, viene creato un workspace "Default" associato all'organizzazione. Se la tua azienda ha un solo progetto o stai solo testando l'API, il workspace predefinito potrebbe essere tutto ciò di cui hai bisogno. ### Creare un nuovo workspace Anthropic Solo gli amministratori dell'organizzazione possono creare nuovi workspace: 1. Vai a Settings e fai clic su "[Workspaces](https://console.anthropic.com/settings/workspaces)" nel menu laterale. 2. Nella pagina dei workspace, fai clic su "Add Workspace" in alto a destra; 3. Inserisci un nome per il nuovo workspace, ad esempio "Project Alpha" o "DataScience Team"; puoi anche selezionare un colore distintivo; 4. Fai clic su Create. Il nuovo workspace apparirà nell'elenco. ### Gestire i workspace Claude * Puoi rinominare o cambiare il colore di un workspace esistente facendo clic sull'icona "…" accanto a esso; * Quando crei una chiave API, devi associarla a un workspace. Le chiavi API sono visibili e gestibili solo dagli utenti con un Ruolo Developer (o Admin) che hanno accesso a quel workspace; * Grazie ai workspace, puoi filtrare i consumi e i costi per singolo workspace nella sezione Usage/Cost. I workspace ti consentono di organizzare in modo flessibile l'utilizzo della console Anthropic: puoi separarli per progetto, team o ambiente, mantenendo tutto organizzato e sotto controllo. ## Gestire i membri nella Claude Console Per collaborare con il tuo team nella console Claude, vai alla sezione [Membri](https://console.anthropic.com/settings/members) (Settings > Members): da qui puoi vedere tutti i membri invitati al team. Per invitare nuovi membri: 1. Fai clic sul pulsante "Invite"; 2. Inserisci l'indirizzo email del membro del team; puoi inserire un indirizzo per riga per invitare più persone contemporaneamente; 3. Assegna un Ruolo: 1. Utente: accesso di base all'organizzazione; 2. Sviluppatore: può gestire chiavi API e integrazioni; 3. Fatturazione: accesso alle informazioni di fatturazione; 4. Amministratore: controllo completo sull'organizzazione e sui membri (sviluppatore + fatturazione). 4. Fai clic su "Send Invites" per inviare gli inviti. Quando inviti un membro, dopo aver assegnato un ruolo organizzativo, potresti anche doverlo aggiungere a singoli workspace (ad eccezione di quello predefinito, a cui tutti i membri possono accedere): gli sviluppatori e gli utenti devono essere assegnati come membri di workspace specifici per lavorarvi, mentre gli amministratori e i ruoli di fatturazione hanno accesso a tutti i workspace. ## 9. Limiti di frequenza e livelli per l'API Anthropic Claude Ogni organizzazione API nella Claude Console dispone di limiti tecnici di utilizzo predefiniti per garantire un uso equo delle risorse: * Limiti di livello: ogni livello ha limiti specifici di richieste al minuto e token al minuto. Puoi visualizzare i limiti del tuo livello attuale in Settings > [Limits](https://console.anthropic.com/settings/limits) della console Claude; * Upgrade di livello: puoi visualizzare i requisiti per ciascun livello nella [documentazione di Anthropic](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). Se hai bisogno di limiti superiori a quelli ottenibili automaticamente, ad esempio per casi d'uso aziendali molto grandi, dovrai inviare una richiesta di aumento tramite la pagina Limits. Il team Anthropic esaminerà la richiesta e potrebbe approvare un livello superiore. ### Passaggi successivi Dopo aver completato la configurazione della console Anthropic: 1. Copia la chiave API che hai creato; 2. Accedi alla dashboard di [AIsuru](https://www.aisuru.com/); 3. Usa la chiave API per [creare un nuovo modello sulla piattaforma](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli). # Mistral API: gestione dei modelli AI Studio Questa guida illustra il processo completo per creare un account Mistral, configurare la fatturazione (dati aziendali e metodo di pagamento), gestire i limiti di spesa e creare chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/). ## **1. Registrazione su Mistral** Per iniziare a utilizzare Mistral AI Studio, devi creare un account sulla piattaforma: 1. Visita la [console Mistral AI Studio](https://console.mistral.ai/) e registrati; 2. Se ti registri con un indirizzo email, potresti doverlo verificare; controlla la posta in arrivo e fai clic sul link di conferma che Mistral ti invia per attivare il tuo account (un codice OTP o un link di accesso diretto); 3. Dopo la verifica, potrebbe esserti richiesto di fornire alcune informazioni aggiuntive, come il tuo **nome completo** e l'accettazione dei termini di servizio; 4. Mistral ti chiederà di **creare un'organizzazione** (o di unirti a una esistente, se il dominio della tua email corrisponde a quello di un'azienda già presente sulla piattaforma) e un **workspace** iniziale: assegna un **nome alla tua organizzazione** — ad esempio, il nome della tua azienda o un nome di progetto identificativo. Verrà creato automaticamente un workspace predefinito con lo stesso nome (che potrai rinominare in seguito, se necessario). Una volta completata la registrazione, verrai indirizzato alla **dashboard di Mistral AI Studio**. Prima di utilizzare l'API, dovrai configurare la sezione **fatturazione** del tuo account. ## **2. Inserimento dei dati di fatturazione aziendali** Per una corretta fatturazione, è importante inserire i dati della tua azienda, inclusa la Partita IVA: 1. Nella console Mistral AI Studio, vai alle impostazioni della tua organizzazione **settings**; 2. Fai clic sul tuo nome o sull'icona **profilo** (in alto a destra) e seleziona **Admin Settings** dal menu: verrai reindirizzato alla **Admin Console** di Mistral (la sezione amministrativa); 3. Assicurati che la tua organizzazione sia selezionata (in alto a sinistra), quindi vai alla pagina **Organization Settings**; 4. Nella pagina delle impostazioni dell'organizzazione, inserisci i dati della tua azienda. In particolare: * **Nome dell'organizzazione**: la ragione sociale della tua azienda (di solito precompilata con il nome inserito durante la registrazione — aggiornala se necessario); * **Indirizzo completo**: inserisci l'indirizzo di fatturazione della tua azienda (via, città, CAP, paese); * **Partita IVA**: se la tua azienda ha una partita IVA, dovresti trovare un campo **Tax/VAT ID**; inserisci la partita IVA della tua azienda **incluso il prefisso del paese** (ad es. IT12345678901 per un'azienda italiana); 5. Verifica che i dati siano corretti e salva le modifiche. *Nota: queste informazioni verranno utilizzate per emettere fatture fiscali corrette per i consumi del tuo account Mistral.* ## **3. Aggiunta di un metodo di pagamento** Una volta configurati i dati della tua azienda, dovrai aggiungere un valido **metodo di pagamento** per utilizzare i servizi Mistral: 1. Apri la console di amministrazione di Mistral **Admin Console** e seleziona **Billing** dal menu di amministrazione; 2. **Aggiungi una carta di pagamento:** se è la prima volta, vedrai un pulsante **Add payment method** o **Complete setup**; fai clic su di esso per avviare la procedura; 3. Si aprirà un modulo sicuro in cui inserirai i dati della tua carta: * Numero della carta di credito o di debito; * Data di scadenza (formato MM/YY); * Codice CVV/CVC (3 o 4 cifre di sicurezza); 4. Completa la procedura confermando i dati: una volta aggiunta, la carta verrà collegata al tuo account Mistral per i futuri addebiti. Nota: attualmente, **sono accettate solo carte di credito o debito**. Non verranno applicati costi fissi immediati — pagherai solo per l'utilizzo effettivo dei servizi. ### Come attivare l'autoricarica per le API di Mistral Per impostare l'autoricarica: 1. Vai alla [console di amministrazione di Mistral](https://admin.mistral.ai/) e fai clic su [Billing](https://admin.mistral.ai/organization/billing) nella barra laterale; 2. Accanto a "Auto Recharge", fai clic su Update; 3. Seleziona la casella "Enable auto recharge, automatically recharging my account whenever my balance falls below a defined threshold"; 4. Inserisci i valori richiesti: 1. Top up my wallet with: l'importo (in euro) da aggiungere al tuo saldo; 2. Quando il mio saldo scende al di sotto di: la soglia (in euro) alla quale si attiva l'autoricarica; 5. Fai clic su "Enable auto recharge". ## **4. Attivazione della fatturazione: scelta di un piano** Mistral utilizza un modello API **basato sul consumo**. Dopo aver aggiunto un metodo di pagamento, devi abilitare il tuo account all'accesso alle API selezionando uno dei piani disponibili. Mistral AI Studio ti consente di scegliere tra un **piano gratuito** e un piano a pagamento pay-as-you-go. Dopo aver aggiunto la tua carta di pagamento, procedi come segue: 1. Vai alla sezione **Limits** della [console di amministrazione](https://admin.mistral.ai/); 2. Scegli un piano: 1. Experiment (Free) — un piano gratuito con limiti di utilizzo molto restrittivi e condivisione dei dati di utilizzo per l'addestramento di nuovi modelli; ideale per i test iniziali; 2. Scale (Pay-as-you-go) — un piano basato sul consumo con limiti più elevati, adatto all'uso in produzione. Richiede l'inserimento dei dati di pagamento e comporterà addebiti in base all'utilizzo effettivo (per token/modello, secondo i prezzi di Mistral). 3. Dopo aver selezionato un piano, potrebbe esserti chiesto di **verificare il tuo numero di telefono**. Inserisci un numero valido, quindi inserisci il codice OTP ricevuto via SMS per confermare (questo passaggio consente a Mistral di verificare l'affidabilità del tuo account prima di sbloccare l'accesso pay-as-you-go). Una volta completati questi passaggi, il tuo account verrà assegnato al piano scelto! ## **5. Come monitorare i consumi e impostare limiti di spesa su Mistral AI Studio** ### **Monitoraggio dei consumi** Puoi monitorare i consumi sia a livello di organizzazione sia di workspace. #### **Monitorare i consumi di un workspace di Mistral AI Studio** 1. Vai a [Mistral AI Studio](https://console.mistral.ai/) e fai clic su "Workspace" nella barra laterale; 2. Assicurati che sia selezionato il workspace corretto (fai clic sul nome in alto a sinistra nel popup che si apre per cambiarlo); 3. Vai alla sezione "Usage" del popup; 4. Seleziona il mese (il mese corrente è selezionato per impostazione predefinita, ma puoi selezionare qualsiasi mese dalla creazione del workspace); 5. All'interno di questa sezione, puoi verificare: 1. Spesa totale (suddivisa in categorie: completamento, OCR, connettori, fine-tuning, audio ecc.); 2. Costi giorno per giorno (totali e suddivisi per categoria); 3. Costo per categoria (per ogni categoria, vedrai solo i modelli effettivamente utilizzati durante il mese; altrimenti vedrai "Nessun utilizzo in \[mese e anno]"). #### **Monitorare l'utilizzo delle API a livello di organizzazione su Mistral AI Studio** Puoi visualizzare le stesse informazioni per l'intera organizzazione, aggregando tutti i workspace. Per farlo: 1. Vai alla [console di amministrazione Mistral AI](https://admin.mistral.ai/) e fai clic su [Usage](https://admin.mistral.ai/organization/usage) nella barra laterale; 2. Come in precedenza, in questa pagina puoi selezionare il mese di riferimento e visualizzare una suddivisione di tutte le spese aggregate in diversi modi (per categoria, per categoria/giorno e per categoria/modello). ### **Come impostare un limite di spesa** I limiti di spesa possono essere impostati solo a livello di organizzazione, non per singolo workspace. Per impostarne uno: 1. Vai alla [console di amministrazione Mistral AI](https://admin.mistral.ai/) e passa a [Limits](https://admin.mistral.ai/plateforme/limits); 2. Nella prima sezione (Organization limits), attiva l'interruttore "Monthly API spending limit"; 3. In "Spending limit", inserisci il limite massimo di spesa mensile in euro e fai clic su "Update limit". Sotto la sezione Spending limit, vedrai anche i consumi del mese corrente rispetto al limite impostato. ## **6. Creazione di una chiave API** Per utilizzare i servizi Mistral con AIsuru, devi creare una **chiave API** Mistral: 1. In [Mistral AI Studio](https://console.mistral.ai/home), fai clic su [**API Keys**](https://console.mistral.ai/home?workspace_dialog=apiKeys) nella barra laterale: il popup che si apre mostra le chiavi create nel tuo workspace; 2. Per creare una nuova chiave, fai clic su "Create new key": 1. Inserisci un nome descrittivo (opzionale, ma consigliato); 2. Imposta una data di scadenza per la chiave (opzionale); 3. Conferma facendo clic su "Create new key"; 3. Fai clic su "Copy key" per copiare la chiave API appena creata e salvala in un luogo sicuro (viene mostrata una sola volta al momento della creazione). ### Come gestire le chiavi API di Mistral AI Studio Puoi gestire le tue chiavi direttamente dalla [pagina delle chiavi API Mistral](https://console.mistral.ai/home?workspace_dialog=apiKeys): qui vedrai una tabella con le chiavi attive e quelle scadute. Per ogni chiave, puoi visualizzare: * Nome: il nome descrittivo assegnato al momento della creazione della chiave; * Chiave: gli ultimi quattro caratteri della chiave per identificarla rapidamente; * Data di creazione; * Data di scadenza ("Never" se non impostata per quella chiave). Se hai molte chiavi, puoi usare la barra di ricerca per trovarle in base al nome. ### Come eliminare una chiave API Mistral Per eliminare una chiave: 1. Fai clic sull'icona del cestino (ultima colonna); 2. Fai clic su Confirm (che apparirà al posto dell'icona del cestino). ## **7. Come gestire i workspace** Mistral ti consente di organizzare l'utilizzo in diversi **workspace**, simili ai progetti di altre piattaforme. Questo è utile per separare attività, team o clienti all'interno della stessa organizzazione, offrendoti maggiore controllo e ordine. Quando crei il tuo account, vengono creati automaticamente un'organizzazione predefinita e un workspace associato. Creando workspace aggiuntivi, puoi separare l'utilizzo per progetto, reparto interno o cliente. Ogni workspace mantiene chiavi API, impostazioni e membri isolati, consentendoti di gestire accessi e limiti in modo granulare all'interno della stessa organizzazione. Nota: puoi gestire più workspace nella stessa organizzazione: ciascuno avrà le proprie impostazioni indipendenti (chiavi API, membri, report sui consumi). {% hint style="success" %} Se hai un solo progetto, puoi semplicemente utilizzare il workspace predefinito. {% endhint %} ### Creazione di un nuovo workspace Per creare nuovi workspace, devi disporre dell'accesso amministratore alla [console amministrativa di Mistral](https://admin.mistral.ai/organization/): 1. Fai clic su [Workspaces](https://admin.mistral.ai/organization/workspaces) nella barra laterale (qui vengono mostrati tutti i tuoi workspace), quindi fai clic sul pulsante New workspace; 2. Nel menu che si apre: 1. Seleziona un'icona (un'emoji tra quelle disponibili); 2. Inserisci un nome; 3. Scrivi una breve descrizione (facoltativa); 4. Se utile, attiva "Add all existing organization members to this workspace"; 5. Infine, fai clic su "Create". {% hint style="info" %} Nota: puoi solo archiviare (non eliminare) i workspace di Mistral AI Studio. {% endhint %} ## **8. Gestione dei membri dell'organizzazione e dei ruoli** Se lavori in team, puoi invitare colleghi nel tuo workspace Mistral e assegnare loro ruoli diversi con autorizzazioni appropriate. Per aggiungere un nuovo membro al tuo workspace, devi prima invitarlo nella tua organizzazione: 1. Vai alla [console amministrativa di Mistral](https://admin.mistral.ai/organization) e fai clic su Members nella barra laterale; 2. Fai clic sul pulsante Invite members e, nel popup visualizzato: 1. Inserisci l'email del membro del team (puoi inserire più indirizzi separati da virgole); 2. Seleziona un ruolo: 1. **Admin:** accesso completo all'organizzazione e ai workspace; può gestire impostazioni, membri, fatturazione e dispone di tutti i privilegi degli altri ruoli. 2. **Billing:** accesso alle informazioni di **fatturazione** e ai pagamenti; può visualizzare e modificare i dati di fatturazione, gestire i metodi di pagamento e visualizzare le fatture. 3. **Member:** ruolo base con accesso limitato; può utilizzare l'API e visualizzare le proprie risorse, ma non può creare chiavi API né modificare impostazioni critiche. 3. Dopo la conferma, il sistema invierà un'email con un link di invito agli indirizzi specificati. Finché l'invito non viene accettato, il membro apparirà come "pending" nell'elenco dei membri. 3. A seconda del ruolo scelto, potrebbe essere necessario invitare il membro del team anche nei singoli workspace. Per farlo: 1. Vai a [Mistral AI Studio](https://console.mistral.ai/) e fai clic su [Workspace](https://console.mistral.ai/home?workspace_dialog=general) nella barra laterale; 2. Seleziona il workspace su cui vuoi lavorare: fai clic sul nome del workspace in alto a sinistra nel popup per passare a un altro; 3. Vai a Members e fai clic su Add Members: 1. Seleziona dal menu a discesa il membro dell'organizzazione da aggiungere al workspace; 2. Specifica il ruolo (l'impostazione predefinita è "Member", ma puoi selezionare anche "Admin"); 3. Infine, fai clic su "Add Member" per confermare. In qualsiasi momento, puoi rimuovere membri dall'organizzazione (dalla [console di amministrazione Mistral](https://admin.mistral.ai/)) o dai singoli workspace (all'interno di [Mistral AI Studio](https://console.mistral.ai/)). ## **9. Limiti di frequenza per i modelli API Mistral** Come tutti i provider di IA generativa, Mistral ha limiti di utilizzo che possono variare in base all'utilizzo e alla spesa totali della tua organizzazione (oppure, per utilizzi ad alto volume, in base agli accordi commerciali con Mistral AI). Puoi controllare i limiti di frequenza nella [console di amministrazione Mistral](https://admin.mistral.ai/organization) (non all'interno di Mistral AI Studio): 1. Vai alla sezione [Limits](https://admin.mistral.ai/plateforme/limits) della console di amministrazione Mistral; 2. Oltre a controllare i consumi e i limiti di spesa mensili, scorrendo verso il basso troverai altre tre sezioni: 1. Rate limit per second: il limite di richieste che puoi effettuare al secondo. Per semplificare: 1 richiesta = 1 messaggio, anche se in pratica un singolo messaggio su AIsuru può consumare fino a 10 richieste. 2. Limiti di completamento per modello: qui troverai i diversi modelli (filtrabili con la barra di ricerca) che Mistral mette a disposizione. Per ogni modello, vedrai: 1. Token al minuto (TPM): il numero massimo di token al minuto che Mistral mette a disposizione della tua organizzazione per quello specifico modello; 2. Token al mese: il numero massimo di token mensili che Mistral mette a disposizione della tua organizzazione per quello specifico modello; 3. Limiti di fine-tuning: limiti specifici per le attività di fine-tuning all'interno di Mistral AI Studio. I modelli Mistral sottoposti a fine-tuning possono poi essere utilizzati su AIsuru. ### Come aumentare i limiti di frequenza per i modelli API Mistral Puoi richiedere un aumento dei limiti di utilizzo dei modelli Mistral AI contattando direttamente il supporto commerciale di Mistral. Puoi farlo andando alla sezione [Contattaci su Mistral AI](https://mistral.ai/contact). ## **Prossimi passi** Dopo aver completato la configurazione della console Mistral AI: 1. Copia la chiave API che hai creato; 2. Accedi alla dashboard di [AIsuru](https://www.aisuru.com/); 3. Utilizza la chiave API per [creare un nuovo modello sulla piattaforma](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli). # Azure AI Foundry: utilizzo dei modelli OpenAI e gestione di accessi e costi {% hint style="warning" %} Per evitare conflitti tra account, ti consigliamo di eseguire tutte le operazioni in una **scheda in incognito** o in un nuovo "profilo" del browser (se applicabile, questo evita conflitti causati da cache e cookie). {% endhint %} ## 1. Registrazione di un tenant Azure (per chi non ha Microsoft 365) Se la tua organizzazione dispone già di Microsoft 365 (M365), significa che hai già un tenant aziendale Azure Active Directory (Azure AD/Microsoft Entra ID), che puoi usare per Azure. In caso contrario, dovrai registrare un nuovo tenant Azure. Ecco come fare: * Visita il sito web di Azure ([azure.microsoft.com](https://azure.microsoft.com/)) e crea un account. Per registrarti, usa un indirizzo email aziendale. La procedura ti guiderà nella creazione di una nuova directory o tenant Azure (denominato tenant Azure AD). * Dopo aver creato l'account, accedi al portale Azure con le credenziali appena configurate. Verifica che sia selezionato il tenant Azure AD che hai creato (in alto a destra, generalmente puoi vedere il nome della directory o del tenant corrente e cambiarlo se ne hai più di uno). Nota: il tenant Azure AD è l'entità che rappresenta la tua organizzazione all'interno di Azure. Tutti gli utenti interni e le risorse Azure saranno associati a questo tenant. ## 2. Creazione di una sottoscrizione Azure a pagamento Per usare servizi avanzati come Azure OpenAI, devi avere una sottoscrizione Azure a pagamento (ad esempio Pay-As-You-Go o un piano enterprise). Le sottoscrizioni gratuite o di prova non sono abilitate per Azure OpenAI, quindi devi attivare fin dall'inizio un piano a pagamento. Se hai appena creato il tuo account Azure, durante la registrazione potresti aver attivato una prova con crediti gratuiti. Vai alla sezione Sottoscrizioni nel portale Azure e, se la tua sottoscrizione è indicata come Free Trial o Azure for Students, passa a Pay-As-You-Go. Ti verrà chiesto di aggiungere un metodo di pagamento (carta di credito o altro) e di confermare che, una volta esauriti eventuali crediti iniziali, i consumi verranno addebitati. In alternativa, se nel tuo tenant non è presente alcuna sottoscrizione, puoi crearne una nuova. Dal portale Azure, vai a Subscriptions e fai clic su + Add. Segui la procedura guidata, scegliendo Pay-As-You-Go come tipo di offerta e fornendo i dettagli di fatturazione richiesti. Una volta attivata la sottoscrizione a pagamento, assicurati che lo stato sia attivo. Ora sei pronto a creare risorse Azure in questa sottoscrizione. Nota: assicurati di disporre delle autorizzazioni Owner o Contributor per la sottoscrizione appena creata (in genere, chi crea la sottoscrizione ne è Owner per impostazione predefinita). Questo è necessario per creare e gestire le risorse nei passaggi successivi. ## 3. Creazione di un Resource Group per le risorse IA Un Resource Group è un contenitore logico in Azure in cui raggruppare risorse correlate. Creeremo un Resource Group dedicato a tutte le risorse IA (OpenAI, storage, ecc.) del progetto. È buona prassi utilizzare convenzioni di denominazione coerenti e pianificate, poiché i nomi delle risorse non possono essere modificati dopo la creazione. Passaggi per creare un Resource Group: 1. Nel portale Azure, nel menu a sinistra (o nel menu ≡ in alto a sinistra), seleziona Resource groups; 2. Fai clic sul pulsante + Create. Si aprirà un modulo di creazione; 3. Nel campo Subscription, assicurati di selezionare la sottoscrizione a pagamento attiva in cui desideri creare le risorse IA; 4. Nel campo Resource group name, inserisci un nome identificativo. Ti consigliamo di includere un riferimento ad AIsuru. *Ad esempio, potresti usare Prod-AIsuru come nome del Resource Group. Evita spazi e caratteri speciali: usa lettere, numeri e, facoltativamente, un trattino - come separatore;* 5. Nel campo Region, scegli un datacenter preferibilmente in Europa. Ad esempio, Sweden Central o West Europe, se disponibili. Questo garantisce che i dati rimangano nell'UE;\ \ *NNota: assicurati che la regione scelta supporti i servizi Azure OpenAI di cui hai bisogno. Non tutte le regioni europee potrebbero avere disponibili tutti i modelli OpenAI.* 6. (Facoltativo) Puoi aggiungere tag per organizzare le risorse. Ad esempio, facendo clic su Next: Tags puoi aggiungere una coppia Nome-Valore come Name: Infrastructure e Value: AzureAI (o "LLM") per classificare questo gruppo come infrastruttura IA. I tag aiutano in seguito a filtrare le risorse e a svolgere analisi trasversali dei costi; 7. Fai clic su Review + create, verifica che i dettagli siano corretti (nome, area, sottoscrizione, tag, ecc.), quindi conferma facendo clic su Create. Il nuovo Resource Group verrà creato entro pochi secondi. Consiglio: **stabilisci una convenzione di denominazione coerente per tutte le risorse del progetto**. *Ad esempio, usa un prefisso comune (come il nome dell'azienda o l'acronimo del progetto) e suffissi che indicano il tipo di risorsa: ad esempio Prod-AIsuru per il gruppo di risorse e poi lo stesso prefisso per le risorse al suo interno (ad esempio Prod-AIsuru-Hub, Prod-AIsuru-Service, prodaisurustorage, ecc.).* In questo modo le risorse sono facili da identificare e viene indicato chiaramente a quale progetto appartengono. Tieni presente che molti nomi di risorse Azure non possono essere modificati dopo la creazione, quindi pianificali attentamente. ## 4. Creazione di un Azure AI Hub tramite Azure AI Foundry Una volta pronto il Resource Group, possiamo creare l'Azure AI Hub, la risorsa principale di Azure AI Foundry. L'hub funge da contenitore/gestore per i progetti IA e ti consente di collegare i vari servizi necessari (OpenAI, archiviazione, sicurezza). Durante la creazione dell'AI Hub, avremo la possibilità di creare contemporaneamente risorse collegate (servizio Azure OpenAI, account Storage e Key Vault), che tratteremo in dettaglio nel passaggio successivo. Per creare un nuovo Azure AI Hub: 1. Nel portale Azure, cerca Azure AI Foundry utilizzando la barra di ricerca globale in alto (digita "Azure AI Foundry" e seleziona il risultato appropriato). In alternativa, accedi alle categorie dei servizi IA dal menu principale; 2. Nella pagina Azure AI Foundry, fai clic sul pulsante + Create Azure AI (in alcuni casi potrebbe essere visualizzato come + New Azure AI). Quindi, scegli di creare un Hub (quando ti viene chiesto quale tipo di risorsa creare, seleziona Hub anziché Project, poiché vogliamo prima creare l'hub centralizzato). 3. Inserisci i dettagli dell'Hub (Basics): si aprirà un modulo di creazione per Azure AI Hub. Compila i campi principali: 1. Subscription: seleziona la sottoscrizione a cui addebitare i costi (quella creata in precedenza); 2. Resource Group: seleziona il Resource Group dedicato (creato nel passaggio precedente, ad esempio Prod-AIsuru); 3. Region: scegli la stessa area geografica del Resource Group, per coerenza (ad esempio Sweden Central, affinché tutte le risorse rimangano nell'UE); 4. Name: assegna un nome all'Hub. Segui la convenzione di denominazione: in genere, il nome del Resource Group seguito da "-Hub". Ad esempio: Prod-AIsuru-Hub; 5. Friendly Name: puoi inserire un nome descrittivo più leggibile, ad esempio "Prod AIsuru Corporate Hub". Questo aiuta a identificare l'hub nel portale, ma non è l'ID della risorsa; 6. Default project resource group: specifica quale Resource Group devono usare per impostazione predefinita i progetti creati in questo Hub. In genere, inserisci lo stesso nome del Resource Group del passaggio 3 (Prod-AIsuru). Questo garantisce che anche le risorse future create dai progetti vengano allocate a quel gruppo; 4. Collega un servizio Azure OpenAI: nella stessa schermata di creazione dell'Hub troverai un campo per collegare un servizio IA, come Azure OpenAI Service. Poiché non ne abbiamo ancora uno, dobbiamo crearne uno: 1. Fai clic sul collegamento Create New sotto il campo Azure OpenAI Service (potrebbe essere denominato Azure AI Services). Si aprirà un pannello laterale per creare un nuovo servizio Azure OpenAI. 2. Nel campo Name di questo pannello, inserisci un nome per la risorsa OpenAI. Segui la convenzione: ad esempio, usa il nome del Resource Group seguito da "-Service" (ad esempio Prod-AIsuru-Service); 3. Assicurati che la Subscription e il Resource Group in questo pannello siano corretti (dovrebbero essere precompilati con quelli selezionati per l'Hub). La regione sarà la stessa dell'Hub; 4. Fai clic su Save per confermare la creazione della risorsa Azure OpenAI Service collegata; 5. Configura lo Storage Account: dopo aver salvato il collegamento al servizio OpenAI, passa alla scheda successiva della procedura guidata di creazione dell'Hub. Dovrebbe esserci una sezione Storage: 1. Fai clic su Next: Storage se la procedura guidata non si è spostata lì automaticamente; 2. Qui ti viene chiesto di selezionare uno Storage Account. Fai clic su Create New sotto il campo Storage account per crearne uno dedicato. Si aprirà un pannello laterale per creare lo storage: 1. Name: inserisci un nome per lo Storage Account. Questo nome deve essere univoco a livello globale e presenta restrizioni (solo lettere minuscole e numeri, da 3 a 24 caratteri, senza spazi o trattini). *Un approccio consiste nell'usare il prefisso del progetto senza trattini. Ad esempio, se il resource group è Prod-AIsuru, potresti usare qualcosa come prodaisurustorage (mantenendo tutto in minuscolo e senza -);* 2. Replication: scegli il livello di ridondanza desiderato. Per ambienti di test o iniziali, puoi selezionare Locally-redundant storage (LRS), che conserva tre copie dei dati nello stesso data center (opzione di base); 3. Lascia gli altri parametri ai valori predefiniti (ad esempio Performance: Standard). Fai clic su Save per creare lo Storage Account. 6. Dopo lo storage, la procedura guidata passerà alla sezione Key Vault: 1. Fai clic su Next: Networking se richiesto e configura l'accesso di rete. In genere, per iniziare, puoi lasciare l'hub in modalità Public access (Public endpoint) così com'è (questo consente di gestire l'hub e i servizi senza richiedere una rete virtuale dedicata; puoi limitare l'accesso in seguito, se necessario); 2. Fai clic su Next: Encryption; 3. Nella sezione Encryption, lascia deselezionata l'opzione che richiede una chiave gestita dal cliente. Ciò significa che verranno utilizzate chiavi gestite da Microsoft per crittografare i dati; 4. Fai clic su Next: Identity; 5. Nella sezione Identity, puoi lasciare le impostazioni predefinite. Fai clic su Next: Tags; 6. Nella sezione Tags, puoi assegnare tag alla risorsa Hub e alle risorse collegate che stai creando. Ad esempio: Name = Infrastructure e Value = LLM (adatta secondo necessità). Questi tag ti aiuteranno a identificare e filtrare le risorse (ad esempio nei report sui costi); 7. Fai clic su Next: Review + create per visualizzare il riepilogo finale; 7. Rivedi e crea l'Azure AI Hub: nel modulo di riepilogo, controlla attentamente tutti i parametri e le risorse che verranno create: il nome dell'Hub, la regione, il Resource Group, il nome del servizio OpenAI, dello Storage, del Key Vault, ecc. In particolare, verifica che la Region sia corretta (in linea con i requisiti di residenza dei dati) e che i nomi seguano la convenzione scelta; 8. Se tutto è corretto, fai clic su Create per avviare il deployment. 9. Azure inizierà a creare l'AI Hub e, contemporaneamente, il servizio Azure OpenAI, il Key Vault e lo Storage Account (se li hai creati nella procedura guidata). L'operazione potrebbe richiedere alcuni minuti. Al termine, vedrai tutte le nuove risorse nel Resource Group (ad esempio Prod-AIsuru-Hub, Prod-AIsuru-Service per OpenAI, prodaisurustorage, Prod-AIsuru-KV per il Key Vault, ecc.). Una volta completata la creazione, hai un Azure AI Hub configurato con i servizi necessari. L'hub è ora pronto a ospitare uno o più progetti Azure AI Foundry. **Importante**: abbiamo scelto di creare l'Azure AI Hub manualmente per poter specificare tutti i dettagli (come la regione UE e nomi personalizzati). In alternativa, Azure AI Foundry consente anche di creare direttamente un progetto Foundry, creando automaticamente un hub predefinito. Tuttavia, per gli ambienti aziendali, è consigliabile avere un controllo esplicito sull'Hub (progetto basato su hub) per centralizzare la gestione delle risorse e della configurazione. ### 4.5. Creazione delle risorse collegate: Azure OpenAI Service, Storage Account, Key Vault Questo aspetto è già in gran parte trattato nel passaggio 4, poiché abbiamo creato le risorse collegate durante la creazione dell'AI Hub. Ecco un breve riepilogo di ciascuna risorsa, per assicurarti che tutto sia configurato correttamente: * **Azure OpenAI Service**: questo servizio fornisce l'accesso ai modelli OpenAI tramite l'endpoint Azure. Nel nostro caso, abbiamo creato la risorsa Azure OpenAI denominata, ad esempio, Prod-AIsuru-Service. Puoi verificarne la presenza andando al Resource Group e controllando che sia presente una risorsa di tipo Azure OpenAI (o Cognitive Services con provider Microsoft.OpenAI). Aprendola, nella pagina Overview dovresti vedere dettagli quali l'URL dell'endpoint e la regione.\ \ *NNota: se durante la creazione dell'Hub hai scelto di non creare subito il servizio OpenAI (saltando quel collegamento), puoi sempre crearlo manualmente in seguito. In tal caso, vai su Create a resource nel portale, cerca Azure OpenAI e crea il servizio selezionando la stessa sottoscrizione, Resource Group e regione. Per gli account Pay-As-You-Go compatibili, dovresti poter procedere direttamente senza moduli di approvazione esterni.* * **Storage Account**: abbiamo creato un account di archiviazione (ad esempio prodaisurustorage) per archiviare i dati generati o richiesti dall'AI Hub/Foundry (ad esempio file di configurazione, log, dataset per fine-tuning, ecc.). Verifica che lo storage sia stato creato correttamente nella regione prevista con replica LRS. A questo punto non è necessaria alcuna configurazione specifica, ma assicurati di non eliminare questo storage: è essenziale per il funzionamento del progetto IA; * **Key Vault**: è stato creato un Key Vault (ad esempio Prod-AIsuru-KV) per archiviare in modo sicuro chiavi e segreti relativi al progetto IA. Ad esempio, la chiave API di Azure OpenAI verrà conservata nel Key Vault. Non è necessaria alcuna configurazione manuale immediata, ma puoi controllare la sezione Secrets del Key Vault per vedere comparire le chiavi necessarie dopo il deployment del modello.\ \ *NNota: il Key Vault e l'Azure AI Hub sono connessi tramite identità gestita, consentendo a Foundry di recuperare le chiavi senza esporle direttamente.* In sintesi, al termine del passaggio 4 dovresti avere tutte queste risorse pronte. Assicurati soltanto che siano tutte presenti nel Resource Group e in stato Active. Se qualcosa non è stato creato o mostra un errore, potrebbe essere necessario ricrearlo o controllare le autorizzazioni (ad esempio, per il servizio OpenAI, verifica di avere accesso al servizio nella tua sottoscrizione). ## 5. Creazione e configurazione del progetto Azure AI Foundry Ora che l'infrastruttura di base è pronta (Hub e servizi collegati), possiamo creare un **progetto Azure AI** all'interno dell'AI Hub tramite il portale Azure AI Foundry. Il progetto è lo spazio di lavoro in cui eseguirai effettivamente le operazioni di sviluppo, il deployment dei modelli, ecc. Ecco i passaggi: 1. **Accedi all'Azure AI Hub che hai appena creato**: dal portale Azure, vai al Resource Group che hai creato e fai clic sulla risorsa Azure AI Hub (ad es. Prod-AIsuru-Hub). Si aprirà la pagina dei dettagli dell'hub. Tra le varie informazioni, dovresti vedere il pulsante Launch Azure AI Foundry; 2. Fai clic su **Launch Azure AI Foundry**. Si aprirà la console web di Azure AI Foundry associata al tuo hub: un'interfaccia dedicata alla gestione dei progetti IA; 3. **Crea un nuovo progetto**: se accedi per la prima volta e nell'hub non esistono progetti, Azure AI Foundry mostrerà un messaggio simile a "You'll need a project to keep working". In questa schermata, devi fornire un nome per il nuovo progetto: 1. Nel campo Project name, inserisci un nome identificativo. Seguendo la nostra convenzione di denominazione, puoi usare il nome del Resource Group con il suffisso "-Project". Ad esempio: Prod-AIsuru-Project. *Assicurati che sia selezionato l'hub corretto: dovrebbe esserci solo quello che hai creato;* 2. Fai clic su Create a project per confermare; 4. **Attendi la configurazione**: il progetto verrà creato all'interno dell'hub e potrebbe richiedere qualche istante per inizializzare l'ambiente. Una volta creato, verrai portato alla vista del progetto Azure AI Foundry. 5. **Verifica la struttura del progetto**: nella console di Azure AI Foundry, dovresti ora vedere il nome del tuo progetto. Sul lato sinistro è presente un menu con diverse sezioni (ad es. Overview, Models + endpoints, Data, Prompt flow, ecc.). Assicurati di riconoscere gli elementi principali: 1. Overview: la pagina iniziale del progetto con un riepilogo e collegamenti rapidi; 2. Models + endpoints: la sezione in cui gestirai i modelli distribuiti e gli endpoint API; 3. Management Center: dove imposti i parametri del progetto, gli accessi, le quote, ecc. A questo punto, il tuo progetto Azure AI è configurato e pronto. Nel passaggio successivo, distribuiremo un modello OpenAI nel progetto. ## 6. Distribuzione di un modello OpenAI (ad es. GPT-4o-mini) su Azure AI Foundry Con il progetto creato, possiamo **distribuire un modello OpenAI** e renderlo disponibile tramite un endpoint per le applicazioni. Azure AI Foundry rende questo processo semplice. Usiamo GPT-4o-mini come esempio, anche se i passaggi sono simili per altri modelli. Passaggi per distribuire un modello nel progetto: 1. **Accedi alla sezione Models + endpoints**: nel pannello sinistro della console Azure AI Foundry (all'interno del tuo progetto), fai clic su Models + endpoints. Qui vedrai l'elenco dei modelli e degli endpoint (inizialmente vuoto poiché non hai ancora distribuito nulla); 2. Nella parte superiore della pagina, fai clic su **+ Deploy model**. Verranno visualizzate delle opzioni: scegli Deploy base model (distribuendo un modello base pre-addestrato senza fine-tuning iniziale). 3. **Seleziona il modello**: verrà visualizzato un elenco di modelli disponibili. Scorri e seleziona GPT-4o-mini (o un altro modello a tua scelta). Puoi usare la barra di ricerca per trovarlo se l'elenco è lungo; 4. Fai clic su **Confirm** per passare alla schermata successiva; 5. Personalizza la capacità (facoltativo): nella schermata di configurazione della distribuzione, potrebbe apparire un pulsante Customize accanto a parametri quali Capacity o Rate limit. Fai clic su di esso per regolare le impostazioni avanzate: 1. Tokens per Minute Rate Limit: imposta il valore massimo consentito. Controlla il limite visualizzato e, se possibile, impostalo sul massimo disponibile, a meno che tu non voglia limitarlo intenzionalmente; 2. Content filter: se presente, puoi lasciare attivo il filtro dei contenuti (solitamente attivo per impostazione predefinita per moderare gli output indesiderati); 6. Fai clic sul pulsante **Deploy** per avviare il deployment del modello scelto con le configurazioni specificate. Azure inizierà a effettuare il provisioning dell'infrastruttura necessaria e a preparare il modello. Questo processo potrebbe richiedere alcuni minuti; 7. Una volta completato, nella sezione Models + endpoints dovresti vedere il modello nell'elenco con lo stato Deployed/Running; 8. **Distribuisci modelli aggiuntivi** (facoltativo): se hai bisogno di altri modelli, puoi ripetere il processo per ciascuno di essi. L'hub/progetto supporta più deployment simultanei, tenendo presente che ciascuno consumerà quota e budget separatamente. *Nota: i modelli OpenAI su Azure vengono continuamente aggiornati e ampliati. Scegli il modello in base alle tue esigenze e assicurati che sia supportato nella regione del tuo servizio Azure OpenAI.* [*Puoi consultare la documentazione di Azure per l'elenco dei modelli supportati per regione*](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=global-standard%2Cstandard-chat-completions#model-summary-table-and-region-availability)*.* ## 7. Ottenere l'Endpoint, la chiave API e il nome del modello Dopo aver effettuato il deployment di un modello, ti serviranno tre informazioni chiave per utilizzarlo tramite API: l'URL dell'Endpoint, la chiave API e il nome del modello (nome del deployment). Ecco come ottenerle: 1. Accedi alla risorsa all'interno di Azure AI Foundry; 2. Nella homepage della risorsa, puoi vedere: 1. Chiave API: copiala e tienila a portata di mano; 2. L'endpoint: su AIsuru inserirai un endpoint leggermente diverso, ma copia e salva il nome del servizio (ad esempio, se l'endpoint è , dovrai salvare "Prod-AIsuru-service"); 3. Per ottenere il nome del modello, vai alla sezione Models + endpoints del progetto: nella tabella, la seconda colonna dovrebbe mostrare il nome del modello per tutti i modelli distribuiti in precedenza. ## 8. Configurazione su AIsuru Per aggiungere un nuovo modello su AIsuru, dovrai inserire i seguenti parametri: * Chiave API: incolla la chiave API salvata in precedenza; * Modello: incolla il nome del modello salvato in precedenza. * Endpoint: sostituisci il nome del servizio con la stringa salvata in precedenza e il nome del modello con il nome del deployment 👉 https\://{service\_name}.services.ai.azure.com/openai/deployments/{model\_deployment\_name;} Puoi seguire la guida nella documentazione di [AIsuru](mailto:undefined) per essere accompagnato passo dopo passo nella [creazione e nel deployment dei modelli](/ai-generativa/ia-generativa-sezione-avanzata/crea-e-gestisci-le-configurazioni-dei-modelli). ## 9. Gestione degli utenti interni nell'organizzazione Azure In un contesto aziendale, più persone probabilmente vorranno accedere al progetto Azure AI o collaborarvi (sviluppatori, data scientist, ecc.). È importante sapere come creare nuovi utenti nel tenant e assegnare loro le autorizzazioni appropriate sulle risorse (hub, progetto, ecc.). ### Aggiungere nuovi utenti interni al tenant Azure 1. Nel portale Azure, cerca Azure Active Directory (o Users and groups se hai dei collegamenti rapidi). Vai alla sezione Users del tuo tenant; 2. Fai clic su + New user. Compila i dettagli richiesti: il nome dell'utente, il nome utente (che diventerà il login, in genere formattato come o con il dominio aziendale, se presente) e scegli un metodo per la password (puoi generarla automaticamente e poi condividerla in modo sicuro con l'utente).\ \ *ISe la tua azienda utilizza un dominio personalizzato in Azure AD, puoi assegnare l'utente a quel dominio; altrimenti, verrà utilizzato per impostazione predefinita il dominio onmicrosoft.com.* 3. Fai clic su Create per creare l'utente. Fornisci all'utente le credenziali create (nome utente e password temporanea) affinché possa accedere. ### Assegnare utenti ai gruppi (facoltativo) Se hai molti utenti, puoi creare Gruppi Azure AD e aggiungervi gli utenti, quindi assegnare le autorizzazioni ai gruppi anziché ai singoli individui. #### Come assegnare i ruoli L'assegnazione dei ruoli può essere gestita a livello di: * Gruppi di risorse → concedono l'accesso a tutte le risorse al loro interno (inclusi Hub, OpenAI, archiviazione ecc.); * Singole risorse → concedono l'accesso alla risorsa specifica. Per assegnare un ruolo: 1. Vai alla risorsa o al gruppo di risorse in questione nel portale Azure; 2. Seleziona Access control (IAM) dal menu. Fai clic su + Add role assignment; 3. Scegli il ruolo appropriato (ad esempio Contributor, Reader ecc.), quindi cerca l'utente o il gruppo nella casella Assign to e conferma: l'assegnazione avrà effetto entro pochi minuti. Oltre ai ruoli, Azure AI Foundry ti consente di specificare l'accesso a progetti e hub direttamente dalla sua dashboard: vai semplicemente al Management Center del tuo progetto e accedi alla sezione "Users" dell'Hub o del progetto, in base alle tue esigenze. In genere, se un utente dispone dell'accesso RBAC all'hub o al gruppo di risorse e ai servizi collegati, dovrebbe poter avviare Foundry e accedere al progetto. Tuttavia, se Foundry richiede esplicitamente l'aggiunta di membri: 1. Accedi al Management Center del progetto > Users (del progetto o dell'hub, secondo necessità). 2. Aggiungi l'utente e assegna il ruolo; 3. Salva le modifiche. → L'utente dovrebbe ora poter vedere e accedere al progetto nel portale Azure AI Foundry. ## 10. Monitoraggio e budget È essenziale impostare un attento monitoraggio dei costi e meccanismi di avviso o limitazione per evitare il superamento del budget. ### Analisi dei costi 1. Nel portale Azure, vai a Cost Management + Billing; 2. Da qui, puoi selezionare la sottoscrizione pertinente (oppure filtrare per il Resource Group Prod-AIsuru se vuoi isolare i costi di questo progetto) e usare Cost analysis, che ti mostrerà quanto stai spendendo con una ripartizione per servizio. ### Budget La funzionalità Budgets ti consente di impostare un budget per un determinato ambito (sottoscrizione, gruppo di risorse, servizio). Il raggiungimento o il superamento del budget non interrompe automaticamente le operazioni: Azure valuterà la spesa periodica e ti invierà avvisi quando verranno superate le soglie definite. Per impostare un budget mensile per la sottoscrizione o il gruppo di risorse del progetto: 1. Vai a Cost Management > (Monitoring >) Budgets nel portale Azure (dopo aver selezionato la sottoscrizione o il RG appropriato come ambito); 2. Fai clic su + Add; 3. Inserisci un nome per il budget (ad esempio Budget-AIProject); 4. Seleziona il periodo di reimpostazione (ad esempio, il budget viene reimpostato ogni mese). * Imposta la data di creazione e la data di scadenza; * Imposta l'importo (ad esempio, se non vuoi superare €1.000 al mese per il progetto IA, imposta 1000 come budget mensile); * Configura gli avvisi: puoi impostare soglie di allarme, ad esempio al 50%, 80% e 100% del budget. Per ogni soglia, configura una notifica email (inserisci gli indirizzi email appropriati, come quelli dell'amministratore IT, del project manager, ecc.). Le notifiche ti avviseranno quando la spesa stimata raggiungerà tali percentuali; * Salva il budget. ## 11. Suggerimenti finali e best practice * Come già sottolineato, una convenzione di denominazione coerente evita molta confusione. Applicala a tutte le risorse: nomi delle risorse Azure, nomi dei deployment dei modelli, nomi dei progetti e persino identificatori dedicati di utenti/gruppi. Documenta questa convenzione affinché il tuo team la segua con coerenza; * Anche se impostiamo il rate limit al massimo consentito per il modello, Azure potrebbe avere limiti più elevati. Informati sulle quote predefinite e, se il tuo caso d'uso lo richiede, puoi richiedere un aumento della quota aprendo un ticket con il supporto Azure; * Utilizzando data center europei, garantisci che i dati in transito e a riposo per il servizio Azure OpenAI rimangano all'interno dell'UE, agevolando la conformità al GDPR e alle policy aziendali. Controlla sempre le informazioni Microsoft più recenti sulla residenza dei dati dei servizi IA, soprattutto se gestisci dati sensibili. * In caso di problemi, consulta la documentazione ufficiale Microsoft e la community. Il portale Azure offre funzionalità diagnostiche di base (ad esempio, log delle richieste non riuscite se abilitati, metriche di utilizzo). Puoi anche aprire ticket di supporto con Azure se riscontri malfunzionamenti del servizio. # Google Vertex: aggiungere Claude Guida WIP # Risoluzione dei problemi AIsuru fornisce diversi indicatori e soluzioni per aiutarti a gestire i problemi che possono sorgere con i provider di IA generativa. Questa guida ti aiuterà a identificare e risolvere rapidamente i problemi più comuni. ### Problemi temporanei dei provider È normale che provider come OpenAI o Anthropic subiscano occasionalmente interruzioni temporanee. Questi problemi di solito si risolvono entro 30 minuti, ma in alcuni casi la risoluzione può richiedere diverse ore. I problemi possono essere limitati a un modello specifico o interessare tutti i modelli del provider. Non è richiesta alcuna azione da parte tua: il servizio riprenderà automaticamente. {% hint style="info" %} **AIsuru non può risolvere i problemi dei singoli provider**, ma fornisce gli strumenti per rilevare le interruzioni e implementare rapidamente una soluzione. {% endhint %} #### Indicatore di problemi del provider Quando interagisci con un Agente che utilizza un provider che sta riscontrando problemi, vedrai un'icona vuota con bordi rossi ⚠️ che segnala un potenziale problema. Questo indicatore appare automaticamente quando il provider selezionato sta riscontrando difficoltà. #### Come cambiare provider in caso di problemi AIsuru non può risolvere l'interruzione di un provider, ma ti consente di evitare disservizi per i tuoi utenti. Devi solo [**selezionare un provider e un modello diversi**](/ai-generativa/attiva-lia-generativa-e-cambia-il-modello#how-to-change-your-agents-model) **per mantenere il tuo Agente disponibile per gli utenti**. ### Tempo di elaborazione della risposta Un altro problema comune è il tempo di elaborazione della risposta. **Ogni richiesta di IA generativa ha un massimo di 180 secondi** (90 secondi per i modelli LLM senza ragionamento) per completare l'elaborazione. Se il modello non riesce a produrre una risposta entro tale tempo: 1. La richiesta viene interrotta automaticamente; 2. L'Agente mostra il messaggio di errore generico: "Mi dispiace, le mie risposte sono limitate. Devi farmi le domande giuste"; 3. Nell'area della chat verrà visualizzato un errore descrittivo in rosso che comunica il problema. (Esempio: Errore: chiamata al messaggio Anthropic non riuscita con codice di stato: RequestEntityTooLarge - Entità della richiesta troppo grande, contenuto:) Questo limite di tempo è una misura di sicurezza per evitare che l'Agente rimanga bloccato in cicli di elaborazione eccessivamente lunghi, garantendo una migliore esperienza utente complessiva. # 4. Condivisione e pubblicazione La condivisione è un passaggio cruciale per far brillare il tuo Agente IA nel mondo digitale. AIsuru offre diversi modi per distribuire e integrare il tuo assistente virtuale in contesti differenti, così puoi raggiungere il tuo pubblico in modi innovativi e coinvolgenti. In questa sezione, tratteremo i seguenti argomenti: 1. **Creazione di un layout** 1. Scopri dove si trovano tutti i campi di configurazione; 2. Scopri cosa puoi modificare e come personalizzare l'aspetto del tuo Agente IA. 2. **Gestione dei layout** 1. Comprendi i vantaggi della gestione di più layout per lo stesso Agente; 2. Configura ruoli specifici e domande di apertura e ottimizza l'esperienza per l'uso in chat o come chiosco. 3. **Codice embed** 1. Un'analisi dettagliata del codice embed e dei suoi campi; 2. Un confronto tra l'integrazione tramite script e iframe. 4. **Modalità di condivisione** 1. Link: per una condivisione rapida e diretta; 2. Siti web: integra il tuo Agente IA nel tuo spazio online; 3. Blog WordPress: arricchisci i tuoi contenuti con interazioni IA; 4. Dispositivi fisici e chioschi: porta l'IA negli spazi pubblici; 5. Spazi virtuali (VR e AR): crea esperienze immersive. Seguendo questa guida, potrai portare la tua IA conversazionale ovunque desideri, aprendo nuove possibilità di interagire con il tuo pubblico. Preparati a trasformare il modo in cui comunichi con i tuoi utenti e a sfruttare appieno il potenziale del tuo Agente IA!
# Condivisione dei layout I layout di condivisione ti consentono di personalizzare **il modo in cui il tuo Agente viene presentato agli utenti in contesti diversi.** Puoi creare layout diversi per lo stesso Agente: ciò ti consente di usare lo stesso Agente su un sito web, su una pagina dedicata, su un touchscreen o per pubblici diversi senza creare più Agenti. In questa sezione: * [**Scegli il layout giusto:**](/condivisione/sharing-layouts/choose-the-right-layout) scopri i tipi di layout disponibili e scegli quello più adatto al tuo caso d'uso; * [**Crea e personalizza un layout:**](/condivisione/sharing-layouts/create-and-customize-a-layout) crea un nuovo layout e personalizzane l'aspetto, l'avatar, i controlli dell'interfaccia, il caricamento di file e le opzioni multilingue; * [**Impostazioni avanzate del layout:**](/condivisione/sharing-layouts/advanced-layout-settings) configura il contesto iniziale, la domanda iniziale, il timeout, il ruolo utente, le lingue e le impostazioni SEO per un layout specifico; * [**Gestisci più layout:**](/condivisione/sharing-layouts/manage-multiple-layouts) usa layout diversi per canali o pubblici diversi e scegli quale layout usare per impostazione predefinita. # Scegli il layout giusto AIsuru offre diversi tipi di layout per consentirti di adattare l'interfaccia del tuo Agente al contesto in cui verrà utilizzato. Un Agente a pagina intera, ad esempio, crea un'esperienza molto diversa da un assistente fluttuante su un sito web o da un'interfaccia progettata per un touchscreen. I layout disponibili includono `FULLPAGE`, `WEBSITE_ASSISTANT`, `CHAT`, `ZOOMED_FULL_BODY`, `HIDDEN_CHAT` e `TOTEM`. ### 1. FULLPAGE `FULLPAGE`utilizza l'intera pagina per visualizzare l'Agente. È progettato per esperienze in cui l'Agente è l'elemento principale della pagina e sia la conversazione sia l'avatar devono avere molto spazio. #### Ideale per * pagine dedicate all'Agente; * demo; * esperienze immersive; * link condivisi direttamente con gli utenti. 💡 Scegli `FULLPAGE` quando l'Agente stesso è il contenuto principale della pagina. ### 2. WEBSITE\_ASSISTANT `WEBSITE_ASSISTANT`visualizza l'Agente come assistente fluttuante all'interno di un sito web esistente. Gli utenti possono aprire e chiudere la conversazione quando necessario senza lasciare la pagina che stanno visualizzando. #### Ideale per * assistenza clienti; * assistenza alla navigazione del sito web; * FAQ conversazionali; * e-commerce; * applicazioni web. 💡 Scegli `WEBSITE_ASSISTANT` quando l'Agente deve integrare il tuo sito web anziché sostituirne i contenuti. ### 3. CHAT `CHAT`fornisce un'interfaccia incentrata principalmente sulla conversazione. Rispetto ai layout più visivi, lascia meno spazio all'avatar e mantiene l'interazione compatta. #### Ideale per * aree di assistenza. * aree riservate; * applicazioni in cui la chat è una parte di un'interfaccia più ampia; * integrazioni web compatte. 💡 Scegli `CHAT` quando i messaggi sono più importanti della presenza visiva dell'avatar. ### 4. ZOOMED\_FULL\_BODY `ZOOMED_FULL_BODY`è un layout a pagina intera che dà maggiore risalto visivo all'avatar dell'Agente. L'avatar viene visualizzato ingrandito accanto alla conversazione. #### Ideale per * Agenti con una forte identità visiva; * presentazioni; * esperienze mobili o altamente visive; * progetti in cui l'interazione con l'avatar è una parte importante dell'esperienza. 💡 Scegli questo layout quando l'Agente deve sembrare un personaggio visibile anziché soltanto un'interfaccia di chat. ### 5. HIDDEN\_CHAT `HIDDEN_CHAT`offre una chat in un pannello laterale che rimane nascosta finché l'utente non sceglie di aprirla. In questo modo l'Agente rimane disponibile senza occupare permanentemente spazio nella pagina. #### Ideale per * siti web con pagine ricche di contenuti; * supporto non invasivo; * esperienze in cui l'Agente deve rimanere disponibile su richiesta; * interfacce in cui lo spazio sullo schermo è limitato. 💡 Scegli `HIDDEN_CHAT` quando vuoi mantenere pulita l'interfaccia principale rendendo comunque l'Agente facilmente accessibile. ### 6. TOTEM `TOTEM`è progettato per chioschi digitali, touchscreen e altre installazioni fisiche. Fornisce un layout adatto alle interfacce in cui gli utenti interagiscono direttamente con l'Agente su uno schermo dedicato. Anche la posizione e la presentazione dell'avatar possono essere adattate a questo tipo di esperienza. #### Ideale per * eventi e fiere. * reception; * musei; * punti vendita; * punti informativi; * chioschi e touchscreen. 💡 Scegli `TOTEM` quando l'Agente verrà utilizzato su un dispositivo fisico dedicato. ### Confronto rapido | Layout | Ideale per | Presenza visiva dell'Agente | | ------------------- | ---------------------------------------------------------- | --------------------------- | | `FULLPAGE` | Pagine dedicate all'Agente | Alta | | `WEBSITE_ASSISTANT` | Assistenza al sito web | Media | | `CHAT` | Esperienze incentrate sulla conversazione | Bassa | | `ZOOMED_FULL_BODY` | Esperienze incentrate sugli elementi visivi e sugli avatar | Molto alta | | `HIDDEN_CHAT` | Assistenza al sito web su richiesta | Minima | | `TOTEM` | Touchscreen e dispositivi fisici | Molto alta | ### Puoi utilizzare più di un layout Lo stesso Agente può avere più layout per canali, pubblici o casi d'uso diversi. Ogni layout può avere la propria configurazione e il proprio link. [Qui puoi trovare ulteriori informazioni.](/condivisione/sharing-layouts/manage-multiple-layouts) Ad esempio: | Canale | Layout | | ------------------------- | ------------------- | | Sito web aziendale | `WEBSITE_ASSISTANT` | | Portale clienti | `CHAT` | | Touchscreen per fiere | `TOTEM` | | Link alla demo di vendita | `FULLPAGE` | Dopo aver scelto il formato giusto, prosegui con **Crea e personalizza un layout**. # Crea e personalizza un layout La pagina **Gestione layout** ti consente di configurare l'aspetto di un layout di condivisione e le funzionalità disponibili per gli utenti. Ogni layout viene configurato indipendentemente, quindi puoi creare diverse esperienze di condivisione per lo stesso Agente. Lascia vuoti questi campi per la configurazione predefinita oppure compilali per avere stili del widget personalizzati. ### Opzioni * **Nome: i**nserisci un nome per il layout. Usa un nome descrittivo che ti aiuti a identificare dove o come viene utilizzato il layout, soprattutto se l'Agente ha più layout;\ Ad esempio: `Company website`, `Customer portal` oppure`Event kiosk.` * **Layout: s**eleziona il tipo di layout che desideri utilizzare. Il layout determina la struttura generale con cui l'Agente viene presentato agli utenti;\ Per una descrizione delle opzioni disponibili, consulta [Scegli il layout giusto](/condivisione/sharing-layouts/choose-the-right-layout). * **Sfondo globale:** configura lo sfondo dell'esperienza di condivisione complessiva; Seleziona **Carica un'immagine** per caricare un'immagine di sfondo personalizzata. Il file caricato deve: * utilizzare il formato PNG, JPG o JPEG; * avere una dimensione massima di **2 MB**. Scegli un'immagine con dimensioni e risoluzione sufficienti per essere visualizzata a schermo intero. * **Sfoca sfondo: a**bilita questa opzione per applicare un effetto sfocatura allo sfondo globale; * **Abilita audio:** abilita o disabilita le funzionalità audio per l'Agente; * **Mostra ragionamento: v**isualizza le informazioni sul ragionamento nell'interfaccia quando disponibili; * **Mostra consumo dei messaggi:** visualizza nel widget le informazioni sul consumo dei messaggi; * **Mostra indicatore per contenuti generati automaticamente dall'IA:** mostra un indicatore per i contenuti generati automaticamente tramite IA; * **Mostra il pulsante "Perché questa risposta?":** visualizza il pulsante Perché questa risposta?, consentendo agli utenti di accedere a informazioni aggiuntive sulla risposta dell'Agente quando disponibili; * **Applica la formattazione delle formule matematiche:** applica una formattazione dedicata alle espressioni matematiche contenute nei messaggi; * **Mostra pulsante di condivisione sui social:** visualizza il pulsante di condivisione sui social nel widget. * **Abilita pannello delle impostazioni:** rendi disponibile agli utenti il pannello delle impostazioni del widget. ### Impostazioni di caricamento Utilizza la sezione **Impostazioni di caricamento** per controllare il caricamento di documenti tramite questo layout. * **Numero massimo di caratteri per documento:** definisci il numero massimo di caratteri che può contenere un singolo documento caricato. * **Mostra pulsante di caricamento documenti:** mostra il pulsante che consente agli utenti di caricare documenti durante la conversazione. ### Area di testo Utilizza la sezione **Area di testo** per configurare l'area di immissione dei messaggi. * **Numero massimo di caratteri nell'area di testo:** definisci il numero massimo di caratteri che gli utenti possono inserire nell'area di immissione dei messaggi. Quando configuri un limite, sopra l'area di testo viene visualizzato un contatore di caratteri. Se lasci vuoto questo campo, viene applicato il limite predefinito di **100.000 caratteri**. ### Sfondo interno * **Sfondo interno:** configura lo sfondo visualizzato all'interno del widget. Utilizza **Seleziona sfondo** per scegliere lo sfondo che desideri utilizzare. **Sfondo globale** e **Sfondo interno** controllano aree diverse dell'esperienza: Sfondo globale si applica all'intera pagina, mentre Sfondo interno si applica al widget stesso. ### Multilingua * **Multilingua:** abilita questa opzione per consentire agli utenti di parlare con l'Agente in altre lingue traducendo automaticamente i contenuti; **Multilingua** è disponibile solo quando il widget viene utilizzato con una **pagina pubblica**. ### Avatar * **Avatar:** seleziona l'avatar da visualizzare in questo layout. L'avatar selezionato si applica a questa specifica esperienza di condivisione. ### Colori Utilizza la sezione **Colori** per personalizzare i colori principali utilizzati dal widget. * **Testo:** definisci il colore utilizzato per il testo; * **Sfondo dei pulsanti:** definisci il colore di sfondo utilizzato per i pulsanti; * **Testo dei pulsanti:** definisci il colore del testo utilizzato all'interno dei pulsanti. Le impostazioni che controllano come vengono inizializzate o si comportano le conversazioni avviate dal layout sono documentate separatamente in [Impostazioni avanzate del layout](https://chatgpt.com/c/advanced-layout-settings). # Impostazioni avanzate del layout Oltre a modificare l'aspetto e l'interfaccia di un layout, puoi configurare impostazioni avanzate che controllano il comportamento del layout quando viene pubblicato o incorporato. L'area **Impostazioni avanzate** è suddivisa in tre sezioni: * Impostazioni SEO (ottimizzazioni per i motori di ricerca); * Parametri avanzati del widget; * Rilevamento PII. Queste impostazioni si applicano al layout specifico che stai modificando. ### Impostazioni SEO (ottimizzazioni per i motori di ricerca) Usa **Impostazioni SEO** per configurare le informazioni associate al layout quando vi si accede come pagina web o viene condiviso tramite piattaforme compatibili. * **Titolo:** definisce il titolo associato alla pagina; * **Descrizione:** definisce la descrizione associata alla pagina. Queste informazioni possono essere utilizzate dai motori di ricerca e quando la pagina viene condivisa; * **URL canonico:** definisce l'URL preferito associato alla pagina; * **Immagine di anteprima:** seleziona un'immagine da usare come immagine di anteprima quando la pagina viene condivisa tramite piattaforme compatibili; * **Mostra l'avatar come immagine di anteprima:** abilita questa opzione per usare invece l'avatar dell'Agente come immagine di anteprima. La sezione mostra anche i metadati HTML corrispondenti generati dai valori configurati. Ad esempio: ```html ``` Puoi usare il pulsante di copia accanto ai metadati generati per copiarli. 💡 Se l'Agente è incorporato in un sito web esistente, verifica anche la configurazione SEO della pagina che contiene l'Agente. ### Parametri avanzati del widget Usa **Parametri avanzati del widget** per controllare il comportamento delle conversazioni avviate tramite questo layout e il modo in cui il layout interagisce con un widget incorporato. * **Contesto iniziale:** fornisci informazioni contestuali che devono essere disponibili all'avvio di una conversazione. Il contesto iniziale funziona solo quando incorpori il widget nella tua applicazione o nel tuo sito web. Per ulteriori informazioni su come usare le variabili di contesto, [fai clic qui.](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette) * **Domanda iniziale:** definisci una domanda o un'istruzione che viene inviata automaticamente all'Agente all'avvio di una nuova conversazione. La domanda iniziale funziona solo quando incorpori il widget nella tua applicazione o nel tuo sito web. L'istruzione stessa non viene mostrata all'utente. L'Agente la elabora invece all'avvio della conversazione e l'utente vede la risposta risultante.
Ad esempio: > Presentati e spiega brevemente come puoi aiutare l'utente. La **domanda iniziale** è diversa dal messaggio di benvenuto generale dell'Agente perché appartiene a questo specifico layout e può quindi essere diversa per ogni esperienza incorporata. * **Timeout:** definisci il timeout utilizzato dal layout; Il valore è espresso in secondi. Utilizza questa impostazione quando l'esperienza incorporata richiede un comportamento specifico dopo un periodo di inattività. * **Ruolo:** scegli il ruolo da impersonare quando una conversazione viene avviata tramite questo layout; Ciò consente allo stesso Agente di avviare conversazioni utilizzando un ruolo diverso a seconda del layout tramite cui l'utente vi accede. * **Lingua dell'Agente:** seleziona la lingua dell'Agente da utilizzare per questo layout; * **Domini autorizzati:** limita i domini autorizzati a incorporare e utilizzare il widget; Inserisci un URL di dominio per riga. Lascia vuoto il campo per consentire tutti i domini. Aggiungi `localhost` all'elenco quando devi consentire lo sviluppo locale. * **Ignora attributi del client:** abilita questa opzione quando i valori configurati nel layout devono avere la precedenza sugli attributi forniti dall'implementazione client; Quando è abilitata, gli attributi client passati tramite il componente **React component** o **Web Component** vengono ignorati e vengono utilizzati solo i valori configurati nel layout. Lascia disabilitata questa opzione quando l'applicazione che incorpora il widget deve poter fornire o sovrascrivere i valori di configurazione supportati tramite gli attributi client. ### Rilevamento PII Utilizza il **rilevamento PII** per impedire agli utenti di inviare messaggi contenenti informazioni personali o sensibili. * **Abilita rilevamento PII:** abilita questa opzione per controllare che i messaggi non contengano dati personali o sensibili prima di inviarli all'Agente; Il rilevamento PII può bloccare i messaggi contenenti informazioni quali indirizzi email, codici fiscali o altri dati sensibili configurati. Quando il rilevamento delle PII è abilitato, configura le regole di rilevamento e il messaggio da mostrare all'utente quando il contenuto viene bloccato. Ciò consente di intercettare le informazioni sensibili prima che il messaggio venga inviato alla conversazione. Le impostazioni avanzate vengono configurate in modo indipendente per ogni layout. Ciò significa che lo stesso Agente può utilizzare informazioni SEO, parametri di incorporamento, ruoli, restrizioni di dominio e impostazioni di rilevamento delle PII diversi a seconda di dove e come viene pubblicato ciascun layout. Per scoprire come layout diversi possono coesistere per lo stesso Agente, continua con [Gestire più layout](https://chatgpt.com/c/manage-multiple-layouts). # Gestisci più layout Puoi creare **più layout di condivisione per lo stesso Agente**. Ogni layout ha la propria configurazione e il proprio link, consentendoti di adattare lo stesso Agente a diversi canali, pubblici e casi d'uso senza creare più copie dell'Agente. ### Quando usare più layout I layout multipli sono utili quando vuoi adattare l'esperienza per: * siti web diversi; * esperienze mobile; * aree clienti; * dipendenti; * partner; * eventi; * dispositivi fisici; * campagne; * testare diverse configurazioni. #### Esempio Lo stesso Agente potrebbe essere usato: * `WEBSITE_ASSISTANT`sul sito web della tua azienda; * `CHAT`all'interno del portale clienti; * `TOTEM`durante una fiera; * `FULLPAGE`per una demo di vendita. Tutte e quattro le esperienze possono fare riferimento allo stesso Agente. ### Ogni layout ha il proprio link Ogni layout di condivisione ha un link dedicato. Gli utenti che aprono quel link accedono all'Agente usando la configurazione associata a quel layout specifico. Ciò significa che puoi distribuire link diversi a pubblici diversi senza modificare gli altri layout. 💡 Usa nomi chiari per i layout, così potrai identificare facilmente dove viene usata ogni configurazione. Ad esempio: * `Main website` * `Customer portal` * `Sales demo` * `Event 2026` * `Internal team` ### Impostare un layout predefinito Puoi selezionare un layout come **layout predefinito** per un Agente. È possibile configurare un solo **layout predefinito** alla volta. Il layout predefinito viene utilizzato automaticamente quando: 1. qualcuno apre il link principale dell'Agente senza specificare un layout particolare; 2. usi il pulsante **Prova** dall'interfaccia di gestione dell'Agente. Impostare un layout predefinito ti consente quindi di controllare l'esperienza standard mostrata quando non è stato richiesto alcun layout specifico. ### Cosa succede se non è presente un layout predefinito? Se nessun layout è configurato come predefinito, il link principale dell'Agente utilizza l'esperienza di base fornita da AIsuru. L'azione **Prova** apre anch'essa l'esperienza di base dell'Agente anziché uno dei tuoi layout personalizzati. 💡 **Imposta un layout predefinito se vuoi che utenti e gestori dell'Agente visualizzino sempre la stessa esperienza personalizzata.** ### Configurazione di esempio Immagina un Agente chiamato **Company Assistant**. Potresti organizzare i suoi layout in questo modo: | Layout | Tipo | Caso d'uso | Ruolo | | ------------------- | ------------------- | ------------------------- | ---------------------- | | Sito web principale | `WEBSITE_ASSISTANT` | Sito web aziendale | Visitatore | | Assistenza clienti | `CHAT` | Portale clienti | Cliente | | Expo 2026 | `TOTEM` | Touchscreen per evento | Visitatore dell'evento | | Demo di vendita | `FULLPAGE` | Link di vendita condiviso | Potenziale cliente | Puoi scegliere uno di questi come predefinito mantenendo tutti gli altri disponibili tramite i rispettivi link dedicati. ### Modificare un layout esistente Le modifiche apportate a un layout influenzano quella configurazione specifica. Prima di modificare un layout già in uso, verifica dove sono attualmente pubblicati il relativo link o la relativa integrazione. Ad esempio, lo stesso layout potrebbe essere già utilizzato in: * un sito web; * una campagna; * un codice QR; * un'installazione per eventi; * documentazione o materiale di onboarding. Se hai bisogno di una configurazione significativamente diversa per un nuovo caso d'uso, creare un **nuovo layout** è spesso più chiaro che riutilizzarne uno esistente. ### Una semplice strategia di denominazione Con l'aumentare del numero di layout, una denominazione coerente rende più semplice gestirli. Un modello utile è: **Canale — Pubblico — Scopo** Ad esempio: * `Website — Public — Support` * `Portal — Customers — Assistance` * `Event — Visitors — Product demo` * `Sales — Prospects — Demo` In questo modo è immediatamente chiaro perché esiste ciascun layout. Quando i tuoi layout sono pronti, puoi decidere [**come pubblicarli**.](/condivisione/publish-your-agent) # Pubblica il tuo Agente Quando i tuoi layout di condivisione sono pronti, scegli come gli utenti devono accedere al tuo Agente. Puoi pubblicare lo stesso Agente attraverso canali diversi e utilizzare un layout differente per ogni pubblico o contesto. Se devi ancora configurare l'esperienza stessa, inizia dai layout di condivisione. In questa sezione * [Condividi il tuo Agente con un link:](/condivisione/publish-your-agent/share-your-agent-with-a-link) usa un link a livello di Agente o il link dedicato di uno specifico layout di condivisione; * [Incorpora il tuo Agente in un sito web:](broken://pages/3QUpbpKqAe5wJqA547Xm) aggiungi il tuo Agente direttamente a un sito web o a un'applicazione web usando il codice embed generato da AIsuru; * [Scarica il tuo Agente come pagina HTML:](/condivisione/publish-your-agent/download-your-agent-as-an-html-page) scarica una pagina HTML completa che include già script, stili, configurazione dell'Agente e layout selezionato; * [Aggiungi il tuo Agente a WordPress:](/condivisione/publish-your-agent/add-your-agent-to-wordpress) installa il plugin WordPress di AIsuru, configura l'Agente e inseriscilo in una pagina o in un articolo con uno shortcode; * [Usa il tuo Agente su un totem o dispositivo fisico:](/condivisione/publish-your-agent/use-your-agent-on-a-totem-or-physical-device) usa un layout di condivisione `TOTEM` per installazioni touchscreen e fisiche; * [Collega il tuo Agente a WhatsApp Business:](/condivisione/publish-your-agent/connect-your-agent-to-whatsapp-business) collega il tuo Agente a WhatsApp Business tramite un provider che supporta l'integrazione WhatsApp Business Platform richiesta; * [Usa il tuo Agente in uno Spazio virtuale:](/condivisione/publish-your-agent/use-your-agent-on-a-virtual-space) aggiungi il tuo Agente a uno Spazio virtuale AIsuru per esperienze VR immersive o di realtà mista; * [Integrazione embed e web avanzata:](/condivisione/publish-your-agent/advanced-embed-and-web-integration) configura il Web Component, passa il contesto dalla pagina host, reagisci agli eventi dell'Agente, invia messaggi programmatici e personalizza l'integrazione a livello frontend. # Condividi il tuo agente con un link Condividere un Agente con un link è il modo più semplice per consentire agli utenti di aprirlo senza incorporarlo in un altro sito web o applicazione. AIsuru fornisce link a livello di Agente e un link dedicato per ciascun layout di condivisione. ### Trova i link del tuo Agente Per trovare i link principali del tuo Agente: 1. Apri il pannello di gestione dell'Agente; 2. Vai a **Condividimi;** 3. Individua i link disponibili dell'Agente. L'area di condivisione fornisce due tipi principali di link a livello di Agente: #### 1. Link privato Il link privato è l'opzione di accesso più limitata e rimane disponibile indipendentemente dalla visibilità pubblica della homepage. Se l'Agente richiede una password, condividila con le persone che devono potervi accedere. Puoi copiare la password dell'Agente dall'area **Condividi** sotto il link privato. Per il comportamento completo degli Agenti privati, delle password, dell'autenticazione e della visibilità, consulta Accesso e visibilità. #### 2. Link pubblico Il link pubblico è pensato per essere più facile da ricordare e distribuire. La sua disponibilità dipende dalle impostazioni di visibilità pubblica dell'Agente. Consulta Accesso e visibilità prima di fare affidamento sul link pubblico come punto di accesso principale per un Agente. ### Quale layout utilizza il link principale dell'Agente? Se hai configurato un **layout predefinito**, il link principale dell'Agente utilizza automaticamente quel layout. Se non è configurato alcun layout predefinito, il link principale apre invece l'esperienza di base dell'Agente. Per maggiori informazioni, consulta Gestire più layout. ### Condividi un layout specifico Ogni layout di condivisione ha il proprio link dedicato. Usa un link specifico per un layout quando vuoi che gli utenti aprano l'Agente con l'aspetto, il comportamento, il contesto, il ruolo, la lingua e le altre impostazioni esatte configurate per quel layout. Per ottenerlo: 1. Apri il tuo Agente; 2. Vai a **Condividi**. 3. Trova il layout che desideri pubblicare nella tabella dei layout; 4. Usa l'azione nella colonna **URL** per aprire il layout; 5. Copia l'URL della pagina aperta e condividilo con i tuoi utenti. In questo modo puoi distribuire esperienze diverse per lo stesso Agente senza creare Agenti separati. ### Link dell'Agente o link della conversazione? Un link dell'Agente avvia un'esperienza dell'Agente per la persona che lo apre. Un link di condivisione della conversazione rimanda a una conversazione specifica e conserva i messaggi che appartengono a quella chat condivisa. Se desideri condividere una conversazione anziché l'Agente stesso, consulta [Conversazioni → Condividi una conversazione.](/condivisione/conversations/share-a-conversation) ### Prima di condividere un link Verifica quanto segue prima di distribuirlo: * viene utilizzato il layout corretto; * il layout è stato salvato e testato; * le impostazioni di accesso e visibilità dell'Agente sono appropriate; * i destinatari dispongono della password se l'Agente ne richiede una; * stai condividendo un link specifico per il layout quando è richiesta un'esperienza particolare. ### Cosa succede se rinomini l'Agente? Rinominare un Agente può influire sui link già in uso. Se modifichi il nome dell'Agente, i link attivi dei layout di condivisione possono smettere di funzionare. In tal caso, ricrea i link interessati e distribuisci i nuovi URL. I link privati dell'Agente continuano a funzionare normalmente. Prima di rinominare un Agente già pubblicato, individua dove sono stati condivisi i suoi link ai layout, in modo da poterli aggiornare successivamente. # Incorpora il tuo agente in un sito web Incorporare un Agente consente agli utenti di interagire direttamente con esso all'interno del tuo sito web o della tua applicazione web senza lasciare la pagina. Per la maggior parte dei siti web, l'approccio più semplice è partire da un layout di condivisione e utilizzare il codice di incorporamento generato da AIsuru. ### Ottieni il codice di incorporamento Per ottenere il codice per un layout: 1. Apri il pannello di gestione dell'Agente; 2. Vai a **Condividimi**; 3. Crea un nuovo layout o aprine uno esistente; 4. Apri il pulsante nella sezione **Codice di incorporamento** del layout; 5. Copia il codice generato. Se hai bisogno di aiuto per scegliere o configurare prima l'esperienza, consulta [Layout di condivisione.](/condivisione/sharing-layouts) ### Aggiungi l'Agente al tuo sito web Dopo aver copiato il codice: 1. Apri l'editor, il CMS o il codice sorgente della pagina in cui desideri visualizzare l'Agente; 2. Incolla il codice generato nella sezione appropriata della pagina; 3. Salva le modifiche; 4. Testa la pagina prima di pubblicarla sul tuo sito web online; 5. Pubblica la pagina quando l'integrazione si comporta come previsto. I test in un ambiente privato o di staging ti danno il tempo di modificare il layout, lo stile, le dimensioni o la posizione prima che i visitatori lo utilizzino. ### Perché incorporare l'Agente? L'incorporamento mantiene l'interazione all'interno del tuo sito web, quindi gli utenti non devono aprire una pagina AIsuru separata. Puoi anche creare un layout specifico per il sito web e allinearne l'aspetto alla pagina circostante utilizzando le normali opzioni del Layout di condivisione. ### Agenti privati Se l'Agente è configurato come privato, agli utenti potrebbe essere richiesto di fornire la password dell'Agente prima di poter interagire con esso. Consulta Accesso e visibilità quando l'esperienza incorporata deve essere limitata a utenti o pubblico specifici. ### Applicazioni web e integrazioni più approfondite L'embed generato si basa sul Web Component di AIsuru anziché su un'integrazione isolata basata esclusivamente su iframe. Questo consente alle applicazioni web avanzate di integrare più profondamente l'Agente con la pagina host, ad esempio passando il contesto, reagendo agli eventi dell'Agente, inviando messaggi da elementi di interfaccia personalizzati o coordinando l'Agente con altri contenuti della pagina. Non hai bisogno di queste funzionalità per un embed standard in un sito web. Per un'integrazione a livello di sviluppo, consulta [Embed avanzato e integrazione web.](/condivisione/publish-your-agent/advanced-embed-and-web-integration) # Scarica il tuo Agente come pagina HTML AIsuru può generare una pagina HTML completa per un layout di condivisione. Questa opzione è utile quando desideri una pagina pronta all'uso che contenga l'Agente senza dover assemblare manualmente il codice embed e la struttura HTML circostante. ### Scarica il file HTML Per scaricare la pagina: 1. Apri il pannello di gestione dell'Agente; 2. Vai a **Condividi**; 3. Seleziona un layout esistente o crea il layout che desideri pubblicare; 4. Individua **Scarica HTML** per il layout configurato; 5. Scarica il file generato. ### Contenuto del file Il file scaricato è un documento HTML completo che include gli elementi necessari per visualizzare l'esperienza dell'Agente selezionato, tra cui: * gli script richiesti dall'Agente; * gli stili CSS utilizzati dall'interfaccia; * la configurazione dell'Agente associata al layout selezionato; * le personalizzazioni visive derivate dalle impostazioni del layout. ### Modalità di utilizzo della pagina scaricata * Ospitala come pagina dedicata: carica il file HTML sul tuo server web per pubblicare l'Agente come pagina autonoma; * Caricala in un iframe: puoi ospitare la pagina scaricata e visualizzarla all'interno di un iframe su un altro sito web. Questo è diverso dall'embed standard Web Component di AIsuru: in questo caso l'iframe contiene la pagina HTML completa che hai scaricato; * Personalizza l'HTML: se hai familiarità con la modifica di HTML, CSS o JavaScript, puoi modificare la pagina scaricata e aggiungere contenuti o stili circostanti richiesti dal tuo progetto. Per un controllo più approfondito sul componente AIsuru stesso, consulta Embed avanzato e integrazione web. ### Download HTML o codice embed? Usa il **codice embed** quando hai già una pagina web e desideri inserire direttamente l'Agente al suo interno. Usa la **pagina HTML scaricata** quando desideri una pagina completa che possa essere ospitata, adattata o incorporata come documento autonomo. # Aggiungi il tuo agente a WordPress AIsuru fornisce un plugin WordPress che ti consente di aggiungere un Agente a una pagina o a un articolo WordPress e configurare l'integrazione dall'area di amministrazione di WordPress. ### Scarica il plugin WordPress Per ottenere il plugin: 1. Apri il pannello di gestione dell'Agente in AIsuru; 2. Vai a **Condividi**; 3. Apri la scheda **WordPress**; 4. Seleziona **Scarica plugin**. Il pacchetto del plugin scaricato è documentato come `memori-wp.zip`. ### Installa il plugin in WordPress 1. Accedi al pannello di amministrazione di WordPress; 2. Vai a **Plugin**; 3. Seleziona **Aggiungi nuovo**; 4. Seleziona **Carica plugin**; 5. Scegli `memori-wp.zip`; 6. Seleziona **Installa ora**; 7. Al termine dell'installazione, attiva il plugin. ### Configura l'Agente Dopo l'attivazione, apri **Memori Configurator** nel menu di amministrazione di WordPress. Inserisci le informazioni sull'Agente e sul proprietario richieste dal plugin. La configurazione documentata include: * **ID Memori** o **nome Memori** — identifica l'Agente; * **ID utente proprietario** o **nome utente proprietario** — identifica il proprietario dell'Agente; * **Contesto iniziale** — contesto facoltativo fornito all'avvio dell'interazione; * **Domanda iniziale** — istruzione/domanda iniziale facoltativa per l'esperienza; * **ID tenant** — usa il tenant AIsuru per le installazioni AIsuru standard oppure l'URL/identificatore richiesto dal tuo tenant PaaS, se applicabile. I valori richiesti dal plugin sono disponibili nell'area **Condividi → WordPress** dell'Agente. ### Configura l'interfaccia Il configuratore di WordPress espone anche le opzioni dell'interfaccia documentate per il plugin, tra cui: * il comportamento multilingue; * il pulsante di condivisione; * il pulsante di ricaricamento della pagina; * il pannello delle impostazioni; * il pulsante per cancellare la chat; * la visualizzazione solo dei messaggi più recenti; * la visualizzazione del testo di caricamento. Usa le opzioni che corrispondono all'esperienza che desideri offrire sul sito WordPress. ### Aggiungi l'Agente a una pagina o a un articolo Per visualizzare l'Agente, modifica la pagina o l'articolo WordPress in cui deve apparire e aggiungi lo shortcode: ``` [memori id="WP_AGENT_ID"] ``` Sostituisci `WP_AGENT_ID` con l'ID effettivo del tuo Agente. Salva o pubblica la pagina, quindi testa l'integrazione dal sito WordPress pubblico. # Usa il tuo agente su un totem o un dispositivo fisico AIsuru include un layout di condivisione `TOTEM` progettato per dispositivi touchscreen e installazioni fisiche. Usalo quando le persone interagiscono con l'Agente da uno schermo dedicato condiviso anziché dal proprio computer o telefono. I contesti tipici includono: * chioschi informativi; * eventi e fiere; * reception; * punti vendita; * musei; * altre installazioni touchscreen dedicate. ### Crea un layout TOTEM Crea un layout di condivisione dedicato all'installazione fisica e seleziona `TOTEM` come tipo di layout. Configura l'aspetto, l'avatar, le opzioni dell'interfaccia, il contesto iniziale, il Ruolo, le lingue, il timeout e le altre impostazioni supportate come per qualsiasi altro layout di condivisione. Per il flusso di configurazione completo, consulta: * Scegli il layout giusto; * Crea e personalizza un layout; * Impostazioni avanzate del layout. ### Usa un layout dedicato per l'installazione Ogni layout di condivisione ha il proprio link e la propria configurazione. L'uso di un layout TOTEM separato ti consente di adattare l'esperienza sul dispositivo fisico indipendentemente dai layout utilizzati sul tuo sito web, portale clienti o link diretti. Ad esempio, il totem può utilizzare le proprie: * configurazione visiva; * contesto iniziale; * domanda iniziale; * Ruolo; * impostazioni della lingua; * comportamento in caso di timeout. Per i dettagli, consulta Gestire più layout. ### Testa l'esperienza fisica Prima di rendere l'installazione disponibile ai visitatori, testa il layout esatto sul dispositivo e verifica che l'interfaccia configurata, l'avatar, l'audio, la lingua e il comportamento della conversazione siano adatti allo schermo e al contesto di interazione. # Connetti il tuo agente a WhatsApp Business (?) Collegare un Agente AIsuru a WhatsApp Business consente agli utenti di interagire con l'Agente tramite WhatsApp, il che può essere utile per il servizio clienti, l'assistenza e altre esperienze basate sulla messaggistica. ### Come funziona l'integrazione L'integrazione richiede l'accesso alla piattaforma ufficiale WhatsApp Business tramite un provider o partner che supporti l'integrazione API necessaria. Il processo generale è: 1. Scegli un provider WhatsApp Business che supporti integrazioni IA esterne; 2. Configura il tuo account WhatsApp Business e l'accesso API con quel provider; 3. Collega l'integrazione lato provider al tuo Agente AIsuru. La procedura tecnica esatta dipende dal provider scelto. ### Opzioni di provider Gli esempi documentati per questo tipo di integrazione includono: * Respond.io; * Vonage; * altri provider autorizzati da Meta che supportano l'integrazione necessaria. Le funzionalità del provider, le condizioni commerciali, i requisiti di onboarding e i flussi di lavoro supportati possono cambiare, quindi conferma i dettagli aggiornati direttamente con il provider prima dell'implementazione. ### Prezzi I prezzi di WhatsApp Business Platform possono variare in base alla categoria di messaggio, al mercato di destinazione, al volume e al provider. Meta ha adottato per la piattaforma un modello di tariffazione per messaggio per i messaggi modello applicabili a luglio 2025 e i provider potrebbero applicare anche commissioni proprie per la piattaforma o il servizio. Per questo motivo, non basarti su un'unica stima fissa per messaggio durante la pianificazione del progetto. Richiedi un preventivo aggiornato al provider e consulta il listino prezzi aggiornato di WhatsApp Business Platform per i mercati e le categorie di messaggi che prevedi di utilizzare. ### Considerazioni prima dell'implementazione #### Costo I costi di messaggistica possono diventare significativi con volumi più elevati. Stima il traffico previsto e comprendi sia gli addebiti di Meta sia le commissioni del provider. #### Dipendenza dal provider L'integrazione dipende dal processo di onboarding, dalle API, dalle funzionalità, dal supporto e dalle tempistiche di implementazione del provider. #### Complessità tecnica La configurazione varia tra i provider e potrebbe richiedere interventi API o middleware specifici del provider. ### Procedura consigliata 1. Stima il volume previsto di messaggi e i casi d'uso; 2. Contatta uno o più provider WhatsApp Business adatti; 3. Richiedi una proposta commerciale e tecnica dettagliata; 4. Conferma l'architettura di integrazione e le responsabilità di implementazione; 5. Prepara e testa l'Agente AIsuru per l'esperienza WhatsApp; 6. Testa l'intero flusso di messaggistica prima di renderlo disponibile agli utenti. > **Importante:** Procedure, costi, tipi di messaggi supportati e tempistiche variano in base al provider. Conferma i requisiti attuali prima di iniziare l'implementazione. ### Supporto Se hai bisogno di aiuto per valutare un'integrazione WhatsApp Business per AIsuru, contatta il team AIsuru tramite Manuela. # Usa il tuo agente in uno spazio virtuale Gli Spazi virtuali di AIsuru ti consentono di inserire Agenti in ambienti virtuali immersivi o di realtà mista. Gli Spazi virtuali sono una funzionalità dedicata di AIsuru con un proprio flusso di configurazione, quindi questa pagina spiega solo come la pubblicazione si inserisce in Condivisione e pubblicazione. ### Quando usare uno spazio virtuale Usa questa opzione quando l'Agente deve apparire come parte di un ambiente 3D anziché come una normale pagina web, un widget di chat o un'interfaccia touchscreen fisica. Uno Spazio virtuale può contenere Agenti come oggetti o personaggi e può utilizzare modelli 3D personalizzati, avatar Ready Player Me o avatar di Agenti esistenti, a seconda della configurazione dello spazio. ### Dove configurare l'esperienza Crea e gestisci l'ambiente dall'area **Spazi virtuali** di AIsuru. La documentazione dedicata agli Spazi virtuali spiega come: * creare uno spazio e fornirne nome, descrizione, banner e impostazione di realtà mista; * scegliere un ambiente predefinito o caricare un modello GLB personalizzato; * aggiungere Agenti all'ambiente; * scegliere il modello o l'avatar utilizzato da ciascun Agente; * posizionare gli Agenti e altri elementi nel configuratore 3D; * pubblicare lo spazio e completare il flusso di approvazione di AIsuru; * accedere, testare e gestire l'esperienza risultante. Per la procedura completa, consulta la documentazione dedicata agli [Spazi virtuali (VR e MR)](https://docs.aisuru.com/estensioni/spazi-virtuali-vr-e-mr/creazione-di-uno-spazio-virtuale) anziché duplicare qui l'intero flusso della funzionalità. # Integrazione web e incorporamento avanzati Il codice di incorporamento standard di AIsuru è progettato per semplificare l'aggiunta di un Agente a un sito web senza creare un frontend personalizzato. Per la maggior parte delle integrazioni, copia il codice generato da AIsuru e aggiungilo alla tua pagina. Se hai bisogno di un controllo più approfondito, lo stesso componente può anche essere configurato e integrato programmaticamente. > **Cerchi i passaggi di installazione di base?**\ > [Consulta Incorporare il tuo Agente in un sito web.](broken://pages/3QUpbpKqAe5wJqA547Xm) ### L'incorporamento utilizza un Web Component L'embed web di AIsuru si basa su un Web Component standard anziché su un'integrazione basata solo su iframe. Un Web Component può essere aggiunto direttamente a una pagina HTML e configurato tramite attributi HTML senza richiedere uno specifico framework JavaScript. Questa architettura consente inoltre un'interazione più approfondita con la pagina ospitante, quando necessario. ### Perché utilizzare un Web Component? Rispetto a un'integrazione isolata basata solo su iframe, il Web Component può supportare: * configurazione tramite attributi HTML; * integrazione diretta con la pagina circostante; * interazione con gli elementi della pagina ospitante e il DOM; * contesto e messaggistica programmatici; * eventi del browser emessi dall'Agente; * stile e personalizzazione del frontend; * esperienze di applicazioni web più complesse. Per una semplice integrazione in un sito web, non è necessario utilizzare queste funzionalità. Il codice di incorporamento generato è sufficiente. ### Caricare il componente Una tipica installazione CDN carica il Web Component e il relativo foglio di stile prima di aggiungere un elemento ``: ```html ``` Il codice esatto generato per il tuo Agente può contenere attributi aggiuntivi a seconda dell'Agente, del tenant, dell'integrazione e del layout selezionato. ### Comprendere`` ``è l'elemento HTML personalizzato che esegue il rendering dell'Agente. I suoi attributi identificano l'Agente e controllano gli aspetti supportati del comportamento del componente. Un esempio più personalizzato può avere questo aspetto: ```html ``` ### Attributi di configurazione documentati L'insieme esatto degli attributi può evolvere con i pacchetti frontend. Parti dal codice generato da AIsuru e usa la documentazione Frontend aggiornata come riferimento tecnico per la versione in uso. Gli attributi e i concetti di integrazione documentati nei riferimenti embed e Frontend includono: | Attributo / concetto | Scopo | | -------------------- | ----------------------------------------------------------------------------------------------- | | `memoriName` | Identifica l'Agente per nome | | `memoriID` | Identifica l'Agente tramite il suo ID univoco quando utilizzato dall'integrazione | | `ownerUserName` | Identifica il proprietario dell'Agente tramite nome utente | | `ownerUserID` | Identifica il proprietario dell'Agente tramite ID quando richiesto | | `tenantID` | Identifica il tenant/ambiente AIsuru | | `apiURL` | Definisce l'endpoint backend/API quando configurato esplicitamente | | `engineURL` | Definisce l'endpoint del motore quando configurato esplicitamente | | `baseURL` | Definisce l'URL di base utilizzato dall'integrazione | | `height` | Controlla l'altezza del componente | | `uiLang` | Controlla la lingua dell'interfaccia quando supportata dall'integrazione | | `spokenLang` | Controlla la lingua parlata/predefinita quando supportata dall'integrazione | | `layout` | Seleziona il layout quando configurato direttamente a livello di componente | | `multilingual` | Abilita il comportamento multilingue | | `showShare` | Controlla la disponibilità dei controlli di condivisione quando supportati | | `showSettings` | Controlla la disponibilità dell'interfaccia delle impostazioni quando supportata | | `integrationID` | Identifica un'integrazione specifica | | `tag`/ `pin` | Parametri legacy/documentati di assegnazione di ruolo-persona utilizzati da alcune integrazioni | | `context` | Fornisce il contesto iniziale alla conversazione | | `initialQuestion` | Fornisce una domanda/istruzione iniziale quando supportata | | `sessionID` | Riprende una sessione precedente quando supportata e valida | | `authToken` | Fornisce un token utente autenticato nelle integrazioni che lo richiedono | | `secretToken` | Fornisce il token segreto/password per Agenti privati o segreti, se supportato | > **Importante:** Non aggiungere manualmente identificatori o attributi a meno che tu non sappia quale valore si aspetta l'integrazione. Il codice di embed generato dovrebbe essere il tuo punto di partenza. ### Controlli dell'interfaccia a livello di sviluppatore I riferimenti React/frontend espongono controlli aggiuntivi per gli elementi dell'interfaccia. Non dovrebbero essere documentati automaticamente come opzioni nell'editor no-code del layout di condivisione, a meno che non siano effettivamente presenti. I controlli a livello di sviluppatore attualmente documentati includono: | Proprietà / controllo | Scopo | | ------------------------- | -------------------------------------------------------- | | `showShare` | Mostra il controllo di condivisione | | `showSettings` | Mostra il pannello delle impostazioni | | `showTypingText` | Mostra il testo di digitazione/caricamento | | `showInstruct` | Mostra l'interruttore della modalità istruzioni | | `showOnlyLastMessages` | Limita la chat visibile ai messaggi più recenti | | `showClear` | Mostra il controllo per cancellare la chat/la cronologia | | `showLogin` | Mostra il controllo di accesso | | `showCopyButton` | Mostra il controllo per copiare i messaggi | | `showTranslationOriginal` | Mostra il testo originale associato alla traduzione | | `enableAudio` | Abilita l'output audio | Considerali funzionalità del frontend. Occorre verificare separatamente se gli stessi controlli sono disponibili nell'attuale editor del layout di condivisione di AIsuru. ### Passare il contesto dalla pagina Il componente può ricevere un contesto iniziale affinché l'Agente sappia qualcosa dell'ambiente in cui inizia la conversazione. ```html ``` Questo è utile quando lo stesso Agente è incorporato in pagine, aree clienti, posizioni o applicazioni diverse. Per il contesto no-code configurato a livello di layout di condivisione, consulta le Impostazioni avanzate del layout. ### Ascoltare gli eventi dell'Agente L'integrazione web può emettere eventi del browser che consentono alla pagina ospitante di reagire allo stato dell'Agente. Ad esempio: ```html ``` L'integrazione basata su eventi può essere utile quando la tua pagina deve: * aggiornare altri elementi dell'interfaccia dopo una risposta dell'Agente; * visualizzare informazioni su prodotti o servizi; * sincronizzare l'Agente con lo stato dell'applicazione; * attivare comportamenti specifici della pagina. ### Inviare messaggi dalla pagina host I controlli personalizzati nella pagina possono inviare messaggi all'Agente. ```html ``` Dove supportati, i messaggi nascosti possono comunicare informazioni o comandi senza visualizzare il testo come un normale messaggio dell'utente: ```html ``` Verifica il comportamento rispetto alla versione del pacchetto frontend in uso prima di fare affidamento su flussi programmatici o di messaggi nascosti. ### Riprendere una sessione a livello programmatico Quando viene fornito un `sessionID` valido, le integrazioni supportate possono riprendere la conversazione associata anziché avviarne una nuova. ```html ``` Per il comportamento completo di ripresa della sessione e il relativo ciclo di vita, consulta la documentazione Frontend dedicata. ### Stile e personalizzazione visiva L'editor del layout di condivisione dovrebbe essere il punto di partenza per la normale configurazione visiva. A livello frontend, AIsuru supporta anche la personalizzazione basata su CSS. È utile quando devi integrare il componente in un design system esistente, adattare dimensioni o spaziature, oppure coordinarlo con altri elementi della pagina. La documentazione Frontend fornisce variabili CSS per valori di tema comuni, come colori primari, colori del testo, sfondi, bolle di chat, pulsanti, pannelli a scomparsa e finestre modali. Le integrazioni meno recenti possono anche indirizzare specifiche classi CSS generate. Ad esempio, le bolle di chat o singoli elementi dell'interfaccia possono essere stilizzati o nascosti selezionando la classe o l'elemento HTML corrispondente. Poiché il markup generato può cambiare, ispeziona il componente corrente prima di fare affidamento sui nomi delle classi interne e, ove possibile, preferisci le variabili CSS supportate. #### Esempi di selettori legacy La precedente documentazione sull'analisi dell'embed includeva esempi che indirizzavano direttamente classi generate, tra cui: ```css .memori-chat--bubble.memori-chat--with-addon { color: #000; background-color: #f0f0f0; } .memori-chat--ai-generated { color: #000; background-color: #f0f0f0; } .memori-chat--bubble.memori-chat--user-bubble { color: #000; background-color: #f0f0f0; } .memori-button .memori-blob figure { opacity: 0; } ``` Questi esempi mostrano che le risposte dell'Agente, le risposte generate dall'IA, i messaggi degli utenti e specifici elementi visivi possono essere indirizzati separatamente. Ricontrolla i selettori rispetto al componente attualmente renderizzato prima di usarli in produzione. ### Snippet CSS, JavaScript e dell'Agente I comportamenti avanzati possono essere implementati in luoghi diversi: * **CSS nella pagina host** per gli stili che devono essere applicati immediatamente; * **JavaScript nella pagina host** per l'interazione a livello di applicazione; * **Snippet dell'Agente** per comportamenti CSS o JavaScript attivati da condizioni conversazionali, quando questa funzionalità è appropriata. Usa il livello più adatto al comportamento che stai implementando invece di inserire tutte le personalizzazioni negli attributi embed. ### Comportamento del viewport sui dispositivi mobili Per integrazioni orientate al tocco in cui il comportamento di zoom del browser è indesiderato, la documentazione legacy sulla condivisione avanzata consiglia di rivedere la configurazione del viewport della pagina. Una configurazione comunemente utilizzata è: ```html ``` Usala solo se corrisponde ai requisiti di accessibilità e interazione della tua applicazione web. ### Quando usare l'embed generato e quando creare un'integrazione per sviluppatori Usa il **codice embed generato** quando: * vuoi aggiungere rapidamente l'Agente a un sito web; * le opzioni di Sharing Layout soddisfano i tuoi requisiti; * ti serve solo una configurazione limitata; * vuoi che AIsuru gestisca la maggior parte della presentazione. Valuta un'**integrazione a livello di sviluppatore** quando: * l'Agente deve reagire a uno stato personalizzato della pagina; * la pagina deve reagire agli eventi dell'Agente; * ti servono contesto, messaggistica o gestione delle sessioni a livello di programmazione; * ti serve un comportamento frontend che vada oltre l'editor di Sharing Layout; * stai integrando l'Agente in un'applicazione JavaScript o React più ampia. ### Documentazione frontend Per le integrazioni per sviluppatori, consulta anche la documentazione di AIsuru Frontend, in particolare le sezioni dedicate a: * Web Component; * Componente React; * Stile e personalizzazione; * API client. * Ripresa e gestione delle sessioni. La documentazione di base su Condivisione e pubblicazione rimane il punto di partenza consigliato quando devi solo pubblicare un Agente utilizzando le opzioni fornite dall'interfaccia AIsuru. # Sicurezza, accesso e visibilità Condividere un Agente e renderlo individuabile pubblicamente sono due decisioni diverse. AIsuru ti consente di controllare **chi può accedere a un Agente** e, separatamente, se l'Agente deve essere **visibile dalla homepage della piattaforma**. Mantenere separati questi concetti ti aiuta a evitare di considerare accidentalmente la visibilità come un meccanismo di sicurezza. ### Modelli di accesso Un Agente può utilizzare uno dei tre modelli di accesso: | Modello di accesso | Chi può accedervi | Protezione | | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | `PUBLIC` | Chiunque | Non è richiesta alcuna password | | `PRIVATE` | Solo gli utenti o le integrazioni che forniscono il token segreto richiesto generato dal sistema | Protetto da un token segreto generato dal sistema | #### PUBBLICO Un Agente `PUBLIC` non ha password e può essere accessibile a chiunque riesca a raggiungerlo. Utilizza questo modello quando l'Agente è destinato a un pubblico ampio e i suoi contenuti e il suo comportamento sono adatti all'accesso pubblico. #### PRIVATO Un Agente `PRIVATE` è protetto da un token segreto generato dal sistema. L'Agente non è liberamente accessibile: il token richiesto deve essere fornito prima di poter aprire una sessione. Questo modello è particolarmente rilevante per le integrazioni controllate, in cui le credenziali di accesso sono gestite dall'applicazione anziché inserite manualmente da un utente finale. ### L'accesso e la visibilità nella homepage sono separati Il modello di accesso dell'Agente determina **se qualcuno è autorizzato ad aprirlo e utilizzarlo**. La visibilità nella homepage determina **se le persone possono scoprire l'Agente dalla homepage di AIsuru**. Queste impostazioni non devono essere confuse. Ad esempio, nascondere un Agente `PUBLIC` dalla homepage non rende privato l'Agente. Se qualcuno possiede già un link valido a un Agente pubblico, l'assenza dell'Agente dalla homepage non costituisce una limitazione dell'accesso. Allo stesso modo, rendere visibile un Agente in una sezione di individuazione non rimuove i requisiti di accesso di un Agente protetto. ### Scegli la combinazione giusta | Obiettivo | Accesso | Visibilità nella homepage | | -------------------------------------------------------------- | --------- | -------------------------------------------------------------- | | Rendi l'Agente individuabile pubblicamente | `PUBLIC` | Visibile | | Condividi un Agente aperto solo tramite canali selezionati | `PUBLIC` | Non visibile | | Limita l'accesso tramite credenziali gestite dall'applicazione | `PRIVATE` | Configura la visibilità in base allo scenario di pubblicazione | | Richiedi una password prima dell'accesso | `SECRET` | Configura la visibilità in base allo scenario di pubblicazione | > **Importante:** La visibilità nella homepage è un'impostazione per la rilevabilità, non una barriera di sicurezza. Usa il modello di accesso dell'Agente quando l'accesso deve essere effettivamente limitato. ### Condivisione di un Agente protetto Un link identifica dove gli utenti possono accedere a un Agente, ma non prevale sul modello di accesso dell'Agente. Se l'Agente è protetto, le informazioni di autenticazione richieste devono comunque essere fornite prima di poter aprire una sessione. ### Autenticazione nelle integrazioni personalizzate Le integrazioni per sviluppatori possono trasmettere le informazioni di autenticazione a livello di codice. Il riferimento attuale del componente Frontend include, tra gli altri parametri di sessione e autenticazione: * `authToken`, per un utente autenticato; * `secretToken`, per il segreto/password richiesto da un Agente protetto; * `sessionID`, per identificare una sessione di conversazione. Si tratta di controlli a livello di sviluppatore. Non aggiungere manualmente token o credenziali a un'integrazione se non sai quale valore si aspetta il componente attuale. ### Prima di pubblicare un Agente Prima di distribuire un Agente tramite un link, un sito web, WordPress, un dispositivo fisico o un altro canale, verifica che: 1. il modello di accesso selezionato corrisponda al pubblico previsto; 2. gli Agenti protetti richiedano la credenziale prevista prima dell'accesso; 3. la visibilità nella homepage corrisponda ai tuoi requisiti di rilevabilità; 4. un Agente pubblico nascosto dalla homepage non venga considerato privato; 5. qualsiasi integrazione con sito web o applicazione gestisca l'autenticazione in base alla documentazione Frontend attuale. # Conversazioni La sezione Conversazioni ti aiuta a gestire e condividere le conversazioni create con il tuo Agente. ### In questa sezione * [Condividere una conversazione](/condivisione/conversations/share-a-conversation): scopri come condividere una conversazione specifica con altri utenti; * [Cronologia e ripresa delle conversazioni](https://chatgpt.com/c/conversation-history-and-resume): visualizza le conversazioni precedenti e scopri come gli utenti possono tornare a una conversazione esistente e riprenderla. # Condividi una conversazione AIsuru ti consente di condividere una conversazione specifica affinché altre persone possano aprire e leggere l'esatta discussione avvenuta con il tuo Agente. È diverso dal condividere l'Agente stesso: un link alla conversazione conserva i messaggi e il contesto della chat corrente, mentre un link all'Agente apre l'Agente come nuovo punto di accesso. ### Link all'Agente o link alla conversazione? | **Cosa condividi** | **Cosa apre il destinatario** | | ----------------------- | -------------------------------------------------------------------------------- | | Link all'Agente | L'Agente, pronto per iniziare una nuova conversazione | | Link alla conversazione | La conversazione specifica che hai condiviso, inclusa la cronologia dei messaggi | Usa un link alla conversazione quando desideri che altre persone esaminino la discussione stessa. ### Condividere la conversazione corrente La condivisione delle conversazioni è disponibile dal pulsante **Condividi** nel widget dell'Agente. Per condividere la chat corrente: 1. apri l'Agente e avvia o continua la conversazione che desideri condividere; 2. seleziona **Condividi** nel widget; 3. scegli **Condividi chat**; 4. usa il link alla conversazione generato per condividere la discussione con altre persone. > **Importante:** Il pulsante Condividi non è disponibile in modalità **Prova**, anche quando è stato configurato un layout di condivisione predefinito. ### Altre opzioni nel pannello Condividi Il pannello Condividi contiene anche opzioni per distribuire l'Agente stesso. Queste opzioni non devono essere confuse con **Condividi chat**. | Opzione | Cosa condivide | | ------------------- | --------------------------------------------------------- | | Condividi chat | La conversazione corrente e la relativa cronologia | | Copia negli appunti | Un link all'Agente | | Facebook | L'Agente | | Twitter | L'Agente | | LinkedIn | L'Agente | | WhatsApp | L'Agente | | Telegram | L'Agente | | Email | Apre il client email con il link dell'Agente precompilato | | QR Code | Genera un codice QR per l'Agente | | Download | Scarica il codice QR generato come file PNG | Se devi solo distribuire un punto di accesso all'Agente, consulta Condividi il tuo Agente con un link. ### Quando è utile condividere una conversazione Condividere una conversazione può essere utile per: * **collaborazione:** inviare una discussione specifica a colleghi o collaboratori; * **supporto tecnico:** consentire a un'altra persona di vedere esattamente cosa è stato discusso e quale problema si è verificato; * **formazione:** condividere esempi di conversazioni efficaci con un Agente; * **documentazione:** conservare e distribuire interazioni importanti per riferimenti futuri. Puoi anche creare una raccolta di conversazioni rappresentative e usarle come esempi o modelli per altri utenti. # Cronologia e ripresa della conversazione La cronologia delle chat consente agli utenti di accedere alle conversazioni precedenti con un Agente AIsuru, esaminarle, gestirle e riprenderle. Invece di considerare ogni interazione come uno scambio isolato, gli utenti possono tornare alle conversazioni precedenti e continuare da dove avevano interrotto. ### Apri la cronologia delle chat La cronologia delle chat è disponibile nei widget AIsuru senza richiedere configurazioni aggiuntive da parte del creatore dell'Agente. Per aprirla: 1. trova l'icona della cronologia delle chat nella barra degli strumenti del widget; 2. selezionala per aprire la pagina della cronologia; 3. sfoglia le conversazioni precedenti con l'Agente. > **Nota:** La cronologia delle chat è disponibile anche quando usi l'Agente in modalità **Prova**. ### Sfoglia e filtra le conversazioni La pagina della cronologia offre controlli per trovare ed esaminare le chat precedenti. #### Scarica la chat corrente Puoi scaricare la conversazione che stai visualizzando come file `.txt`. #### Filtra per data I filtri temporali documentati includono: * Tutti; * Oggi; * Ieri; * Ultimi 7 giorni; * Ultimi 30 giorni. #### Filtra per numero minimo di messaggi Puoi anche filtrare le conversazioni in base al numero minimo di messaggi. Le opzioni documentate includono: * Qualsiasi; * 2; * 3; * 5; * 10; * 15; * 20; * un valore personalizzato. ### Come vengono visualizzate le conversazioni Ogni conversazione nella cronologia include informazioni che ti aiutano a identificarla rapidamente. #### Titolo automatico Il titolo della conversazione viene generato automaticamente dal primo messaggio dell'utente. Se il messaggio è troppo lungo, il titolo viene troncato con `...` per mantenere leggibile l'elenco. #### Data, ora, messaggi e contenuti multimediali La cronologia mostra anche informazioni quali: * la data e l'ora di inizio della conversazione; * il numero di messaggi e contenuti multimediali scambiati. Le conversazioni sono ordinate dalla più recente alla meno recente. ### Apri una conversazione precedente Seleziona una conversazione dall'elenco per aprirne la cronologia completa. La vista dettagliata conserva: * tutti i messaggi scambiati nella conversazione; * il contesto della conversazione e i dati della sessione; * la familiare presentazione del widget originale. ### Riprendi una conversazione Dalla vista dettagliata della conversazione, usa **Riprendi** per continuare la chat. Quando una conversazione viene ripresa: * l'utente torna alla discussione precedente; * l'Agente continua con il contesto di quella conversazione; * l'ambiente della conversazione originale viene ripristinato; * la chat riprende utilizzando la configurazione del widget/layout corrispondente. Questa funzione è utile quando una conversazione si sviluppa nel tempo o quando l'utente deve tornare alle informazioni discusse in precedenza. ### Cronologia delle conversazioni e privacy Il comportamento documentato della cronologia chat include le seguenti protezioni: * ogni utente vede solo le proprie conversazioni; * le conversazioni rimangono disponibili dopo la chiusura del browser; * le conversazioni sono associate all'account utente; * la gestione della cronologia non richiede interventi manuali da parte del creatore dell'Agente. ### ID di sessione e ripresa della conversazione Ogni conversazione ha un `sessionID` univoco. Quando un utente riprende una conversazione tramite la cronologia della chat, AIsuru ripristina la sessione associata a quella conversazione. Questo rende le informazioni sulla sessione rilevanti anche per integrazioni avanzate ed esperienze basate su API. > **Per gli sviluppatori:** La cronologia della chat rivolta agli utenti e la ripresa programmatica della sessione non devono essere considerate lo stesso flusso di lavoro. L'attuale documentazione Frontend indica che, quando un `sessionID` viene fornito direttamente a un componente, AIsuru lo convalida: una sessione valida ripopola la chat, mentre una sessione non valida avvia una nuova conversazione. Tale documentazione Frontend indica inoltre che le sessioni riprese direttamente scadono dopo un'ora di inattività. Segui l'attuale documentazione Frontend quando implementi la persistenza delle sessioni a livello programmatico. Per la gestione delle sessioni controllata dallo sviluppatore, consulta la documentazione su Advanced embed and web integration e la documentazione Frontend **Ripresa della sessione**. ### Perché la cronologia della chat è utile #### Per gli utenti La cronologia della chat offre: * **continuità:** le conversazioni possono proseguire nel tempo invece di ricominciare da zero; * **riferimento storico:** gli utenti possono rivedere informazioni, suggerimenti o risposte ricevuti in precedenza; * **flessibilità:** gli utenti possono interrompere una conversazione e riprenderla in seguito; * **meno ripetizioni:** le informazioni già discusse restano disponibili nella chat precedente. #### Per i creatori di Agenti Le conversazioni persistenti possono favorire: * un maggiore coinvolgimento degli utenti di ritorno; * conversazioni più lunghe e articolate; * un'interazione meno ripetitiva; * una migliore comprensione di come gli utenti interagiscono con l'Agente nel tempo. ### Buone pratiche Per rendere più utile la ripresa delle conversazioni: 1. progetta le conversazioni in modo che gli utenti possano riprenderle naturalmente in seguito; 2. usa in modo appropriato i riferimenti temporali quando l'Agente fa riferimento a parti precedenti di una discussione; 3. struttura i flussi conversazionali in modo che possano progredire attraverso più interazioni; 4. verifica regolarmente l'esperienza di ripresa. # 5. Funzionalità avanzate Le funzionalità avanzate di AIsuru ti permettono di portare il tuo Agente al livello successivo, con potenti strumenti per la personalizzazione, la sicurezza e l'integrazione. Queste capacità sono progettate per soddisfare le esigenze di utenti esigenti e implementazioni complesse. In questa sezione, esploreremo: * [**Come eseguire il backup del tuo Agente**](/avanzate/backup-trasferimento-e-cancellazione-di-un-agente) per proteggere i tuoi dati; * Le [**integrazioni**](/avanzate/integrazioni) disponibili per collegare il tuo Agente ad altri sistemi e servizi; * Strategie avanzate per la [**gestione di admin e utenti**](/avanzate/gestione-utenti-persone) nel tuo ecosistema IA; * Il processo di [**Fine-Tuning**](/avanzate/fine-tuning) per migliorare le prestazioni e la precisione del tuo Agente; * Tecniche per [**consentire all'Agente di eseguire azioni direttamente all'interno di una pagina web.**](/avanzate/interfacce-web-come-creare-esperienze-interattive) Che tu voglia migliorare la sicurezza dei dati, ottimizzare le prestazioni del tuo Agente o creare esperienze utente più interattive, le funzionalità avanzate di AIsuru ti forniscono gli strumenti per dare vita alla tua visione. Continua a leggere per scoprire come sbloccare il pieno potenziale del tuo Agente IA e portare la tua implementazione al livello successivo! # Generale: risposte contestuali e avanzate Nelle impostazioni di un Agente, nella sezione **"Generali"**, troverai diverse funzionalità che possono ampliarne la versatilità. ### **Risposte contestuali** Questa sezione ti consente di attivare funzionalità che permettono all'Agente di accedere a informazioni contestuali durante le conversazioni, migliorando la rilevanza e la personalizzazione delle sue risposte. Queste impostazioni sono essenziali per i contenuti che dipendono dalla [posizione dell'utente o dalla data corrente](/istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente). #### Posizione Quando è attiva, l'Agente può rispondere in base alla posizione geografica dell'utente. Se la posizione è richiesta, la stessa domanda può ricevere risposte diverse a seconda di dove si trova l'utente. #### Data e ora Quando è attiva, l'Agente può fornire risposte in base alla data e all'ora correnti. Se la data è richiesta, la stessa domanda può ricevere risposte diverse a seconda di quando viene posta. #### Accessibile solo agli utenti autenticati Quando è attiva, l'Agente risponde solo agli utenti che hanno effettuato l'accesso, garantendo un accesso controllato alle sue funzionalità. ### **Impostazioni avanzate** Le impostazioni avanzate ti consentono di configurare comportamenti specifici dell'Agente relativi alla gestione dei contenuti e delle interazioni. Per accedere a queste opzioni, fai clic sulla sezione espandibile **"Impostazioni avanzate"**. #### Chiedi feedback sulle risposte basate sui contenuti Quando è attiva, l'Agente aggiunge automaticamente una richiesta di feedback al termine delle risposte basate sui contenuti (ad esempio, "Questa risposta ti è stata utile?"). Il feedback raccolto viene utilizzato per migliorare la corrispondenza tra domande e contenuti. #### Disabilita la raccolta di contenuti IA L'attivazione di questa opzione impedisce all'Agente di accumulare bozze e domande senza risposta. {% hint style="info" %} Se il tuo Agente utilizza principalmente l'IA generativa per risposte dinamiche anziché basate sui contenuti, ti consigliamo di disabilitare la raccolta. {% endhint %} #### Suggerisci domande quando l'utente è inattivo Se l'utente non interagisce per un certo periodo, l'Agente suggerisce domande tratte dai suoi contenuti, rispettando i timeout configurati. Puoi escludere domande specifiche contrassegnandole come "Non casuale" nelle impostazioni dei contenuti. #### Consenti agli utenti di segnalare una risposta errata (solo contenuti) Consente agli utenti di segnalare quando una risposta basata sui contenuti non corrisponde alla loro richiesta. Il feedback perfeziona la corrispondenza tra domanda e contenuto: in future richieste simili, quel contenuto non verrà attivato automaticamente. La correzione è locale all'Agente e non influisce sulle risposte generative. #### Soglia di confidenza Definisce il livello di certezza richiesto dall'Agente prima di fornire una risposta. Puoi scegliere tra cinque livelli: * Molto bassa; * Bassa. * Normale; * Alta; * Molto alta. Con una soglia più alta, l'Agente risponde solo quando è molto sicuro di avere la risposta corretta. Questo comporta risposte più accurate, ma aumenta i casi in cui l'Agente dice di non saperlo. {% hint style="warning" %} La modifica della soglia di confidenza può influire significativamente sulla qualità delle risposte. Modificala solo se sai cosa stai facendo. {% endhint %} ### **Integrazione DCM** Questa sezione ti consente di collegare l'Agente a un sistema DCM esterno (Digital Content Management). Compila: * **Utente DCM**: l'identificativo utente per l'integrazione; * **Secret**: la chiave segreta per l'autenticazione; * **App Context**: il contesto applicativo specifico. Dopo aver apportato le modifiche, fai clic sul pulsante viola **"Salva le modifiche"** in basso a destra per applicare le nuove impostazioni. # Backup, trasferimento ed eliminazione di un Agente AIsuru ti consente di scaricare un backup di un Agente, trasferirne la proprietà a un altro utente o eliminarlo definitivamente. Queste operazioni sono irreversibili, quindi è importante procedere con cautela. ### Come accedere alle opzioni di gestione Per trasferire o eliminare un Agente, **vai a** **Impostazioni >** **Gestisci** per il tuo Agente. Da qui puoi scegliere se eliminare o trasferire il tuo Agente. ### Backup di un Agente AIsuru offre due metodi complementari per eseguire il backup dei tuoi Agenti: #### 1. Esportazione completa dell'Agente L'esportazione completa ti consente di esportare l'intero Agente come file zip, comprese tutte le impostazioni e i contenuti multimediali associati: 1. Vai a **Impostazioni > Gestisci** per il tuo Agente; 2. Nella sezione "Esporta questo Agente", fai clic sul pulsante **EXPORT**; 3. Attendi che il file zip venga scaricato. Il file zip esportato contiene: * Un file JSONL con tutte le impostazioni e le configurazioni dell'Agente; * Una cartella "media" con tutti i file multimediali allegati ai tuoi contenuti. Questo metodo di backup è ideale per: * Creare backup completi del tuo Agente; * Trasferire un Agente identico a un'altra istanza di AIsuru. * Eseguire test A/B creando copie modificate dello stesso Agente. | Dati conservati nel file zip | Dati non conservati nel file zip | | ----------------------------- | --------------------------------------------------- | | Ruoli | Layout (viene mantenuto solo il layout predefinito) | | Contenuti | Follower | | Dizionario | Conversazioni | | Funzioni | MCP | | Cronologia delle importazioni | Statistiche | #### 2. Esportazione CSV dei contenuti Per un backup più leggero incentrato solo sui contenuti testuali: 1. Vai al pannello di gestione dell'Agente; 2. Vai alla sezione **Importa / Esporta**; 3. Seleziona la scheda **"Esporta CSV"**. #### **Configurazione dell'esportazione** Prima di esportare, puoi personalizzare vari aspetti del file CSV risultante: * Apri la sezione **"Avanzate"** nella pagina di esportazione; * Configura le seguenti opzioni secondo necessità: * Separatore delle colonne CSV; * Separatore delle varianti di domanda; * Nomi delle colonne per Domanda, Risposta, Argomenti richiesti e Argomenti da impostare. #### **Esecuzione del backup** Dopo aver configurato le opzioni: 1. Trova il pulsante "Esporta" nella parte inferiore della pagina; 2. Fai clic su "Esporta" per avviare il download del file CSV. Il tuo browser salverà automaticamente il file nella cartella download predefinita. #### **Utilizzo del file di backup** Il CSV esportato è uno strumento versatile che puoi utilizzare per: * Creare una copia di backup dei contenuti testuali del tuo Agente; * Trasferire facilmente i contenuti tra diversi Agenti o piattaforme esterne; * Analizzare e modificare i contenuti usando fogli di calcolo; * Condividere la base di conoscenza con il tuo team o altri stakeholder. #### **Limiti del backup CSV** Il backup del tuo Agente in formato CSV presenta alcuni limiti: * Non include media, link o altre personalizzazioni dei contenuti; * Contiene solo domanda, varianti di domanda, risposta, altre risposte, argomenti impostati, argomenti richiesti e tag; * Non salva le istruzioni né le impostazioni funzionali ed estetiche del tuo Agente. ### Importazione di un Agente completo Per importare un Agente precedentemente esportato: 1. Vai alla homepage della piattaforma, dove viene mostrato l'elenco dei tuoi Agenti. 2. Fai clic sul pulsante **Import** in alto a destra, sopra i tuoi Agenti; 3. Si aprirà un popup per caricare il file zip; 4. Dopo il caricamento, vedrai un messaggio "Caricamento completato con successo"; 5. Apparirà un popup in cui potrai assegnare un nome al nuovo Agente; 6. Fai clic su "Importa" per avviare il processo. Durante l'importazione: * Una notifica in alto a destra ti terrà aggiornato sull'avanzamento; * Vedrai prima un messaggio "In corso" seguito dal numero di elementi elaborati sul totale; * Al completamento, la notifica mostrerà "Importazione completata"; * Puoi gestire il tuo nuovo Agente facendo clic su "Gestisci" nella notifica. {% hint style="warning" %} Se l'importazione non riesce (ad esempio, a causa di un file zip danneggiato o di un nome di Agente già esistente), la notifica in alto a destra mostrerà "Importazione fallita". {% endhint %} ### Come importare il file CSV Per importare il file CSV in un Agente, puoi: ### Trasferimento di proprietà Per trasferire un Agente a un altro utente: 1. Fai clic sul pulsante **"TRASFERISCI"**; 2. Nel popup visualizzato, seleziona la piattaforma. Per impostazione predefinita, viene mostrata la piattaforma corrente ([www.aisuru.com](http://www.aisuru.com) oppure il tuo indirizzo [PaaS](/paas)); 3. Inserisci il nome utente o l'email del destinatario; 4. Conferma l'operazione digitando il nome esatto dell'Agente (con distinzione tra maiuscole e minuscole); 5. Fai clic su "Trasferisci" per completare l'operazione. {% hint style="danger" %} Una volta trasferito, l'Agente non sarà più accessibile dal tuo account. **Se vuoi continuare a gestirlo, dovrai essere** [**invitato come autore**](/avanzate/gestione-utenti-persone/invito-e-gestione-degli-autori) dall'utente a cui lo hai trasferito. {% endhint %} Note importanti sul trasferimento: * Se inserisci un nome utente inesistente o un'email non associata ad alcun account, il trasferimento non riuscirà e manterrai la proprietà dell'Agente; * Il trasferimento è irreversibile: una volta completato, solo il nuovo proprietario può gestire l'Agente. ### Eliminazione dell'Agente Per eliminare permanentemente un Agente: 1. Fai clic sul pulsante "ELIMINA"; 2. Nel popup di conferma, inserisci il nome esatto dell'Agente (con distinzione tra maiuscole e minuscole); 3. Fai clic su "Elimina" per confermare. {% hint style="danger" %} Una volta eliminato, l'Agente **non può essere recuperato in alcun modo**. {% endhint %} Prima di procedere con l'eliminazione, considera: * **Effettuare un backup** dei contenuti se desideri conservarli. * **Verificare che nessun altro utente o servizio dipenda da questo Agente.** # Integrazioni Le integrazioni ti permettono di connettere il tuo Agente a servizi esterni tramite webhook, consentendogli di eseguire azioni e recuperare informazioni in tempo reale. AIsuru offre tre approcci alternativi per le integrazioni: 1. [**Funzioni**](/avanzate/integrazioni/funzioni): per integrazioni più semplici; 2. [**Intenti dinamici**](/avanzate/integrazioni/intenti-dinamici): per interazioni strutturate e sicure; 3. [**MCP**](/avanzate/integrazioni/model-context-protocol-mcp-su-aisuru) (consigliato per la maggior parte degli utenti): per integrazioni facili da configurare ma molto potenti, basate sullo standard MCP. Tutti e tre gli strumenti ti permettono di connettere il tuo assistente IA a sistemi esterni, automatizzare processi e creare esperienze utente avanzate. ### Passaggi successivi Nelle sezioni seguenti esploreremo in dettaglio: 1. Come creare e implementare funzioni/Funzioni personalizzate; 2. Come configurare e utilizzare gli intenti dinamici; 3. Buone pratiche e [differenze tra funzioni, intenti dinamici e MCP.](/avanzate/integrazioni/intenti-dinamici-o-funzioni-cosa-usare) # Funzioni Le funzioni di AIsuru **ti permettono di estendere le capacità del tuo assistente virtuale**, consentendogli di eseguire azioni specifiche e interagire con sistemi esterni. Questa potente funzionalità trasforma la tua IA da un semplice chatbot a uno strumento versatile e personalizzabile. In questa sezione, esploreremo: * [Cosa sono le funzioni ](/avanzate/integrazioni/funzioni/cosa-sono-le-funzioni)e come possono migliorare il tuo assistente IA; * [Come impostare e configurare una funzione](/avanzate/integrazioni/funzioni/funzioni-avanzate/come-configurare-una-funzione-personalizzata) passo dopo passo; * [Le migliori pratiche e i casi d'uso comuni](/avanzate/integrazioni/funzioni/funzioni-avanzate/funzioni-avanzate-best-practice-e-casi-duso) per sfruttare al meglio questa funzionalità. Che tu stia cercando di integrare dati in tempo reale, automatizzare processi o creare esperienze utente uniche, le funzioni di AIsuru ti offrono gli strumenti per realizzare la tua visione. Continua a leggere per scoprire come sbloccare tutto il potenziale del tuo assistente IA! {% hint style="info" %} Vuoi importare funzioni da un altro agente?\ Vai a **Importa/Esporta > Importa** **Funzioni e Intenti** {% endhint %} # Cosa sono le funzioni Le funzioni in AIsuru consentono al tuo Agente di estendere le sue capacità oltre la semplice conversazione. Esistono due tipi principali di funzioni: 1. Funzioni integrate (**"Funzioni di AIsuru"**): 1. Funzioni preconfigurate e pronte all'uso; 2. Includono funzionalità come l'invio di email e la ricerca sul web; 3. Facili da attivare e usare senza configurazioni complesse. 2. Funzioni personalizzate (**"Funzioni avanzate"**): 1. Consentono di creare integrazioni personalizzate con servizi esterni; 2. Consentono di automatizzare processi complessi; 3. Richiedono una configurazione tecnica più dettagliata. Con le funzioni puoi: * Recuperare informazioni da fonti esterne in tempo reale; * Automatizzare azioni ripetitive; * Personalizzare le risposte dell'Agente in base a dati specifici; * Integrare l'Agente con altri sistemi e servizi. Nelle prossime sezioni esploreremo in dettaglio: * Le [funzioni integrate ](/avanzate/integrazioni/funzioni/funzioni-di-aisuru)disponibili in AIsuru; * Come configurare e usare le [funzioni avanzate](/avanzate/integrazioni/funzioni/funzioni-avanzate) per casi d'uso specifici. # Funzioni di AIsuru AIsuru offre una serie di funzioni integrate e 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. ## Funzioni impostate per impostazione predefinita ### Variabili di contesto Le variabili di contesto permettono al tuo Agente di gestire dinamicamente i contesti della conversazione. Questa funzione è particolarmente utile per: * Applicare automaticamente contesti specifici in base alle risposte dell'utente; * Rimuovere i contesti quando non sono più pertinenti; * Guidare naturalmente la conversazione tra argomenti diversi. #### Come funziona L'IA generativa può: * Impostare un nuovo contesto quando rileva un cambio di argomento; * Rimuovere un contesto quando l'argomento non è più pertinente; * Utilizzare più contesti contemporaneamente per rispondere in modo accurato. ## Panoramica delle altre funzioni disponibili AIsuru offre anche diverse funzioni integrate principali: 1. **Artifacts**: crea e scarica contenuti interattivi in vari formati (HTML, CSS, JavaScript, JSON, markdown, svg, ecc.) direttamente nella chat. 2. **Invia email**: consente all'Agente di inviare comunicazioni email agli utenti registrati; 3. **Converti OpenAPI in funzioni**: genera automaticamente funzioni dalle specifiche OpenAPI; 4. **Crea funzione da file**: consente all'Agente di accedere a un file durante le conversazioni; 5. **Perplexity Search**: consente all'Agente di effettuare ricerche web intelligenti con risultati sintetizzati dall'IA; 6. **Emozioni**: consente al tuo Agente di esprimere emozioni attraverso espressioni facciali e animazioni quando viene visualizzato con un avatar 3D. Puoi iniziare a usarle subito: ti basta attivare l'interruttore della funzione che desideri utilizzare all'interno del tuo Agente! Tieni presente, però, che per semplificare l'interazione e migliorare l'esperienza utente, dovrai spiegare all'Agente come e quando utilizzarle nelle sue [istruzioni](/ai-generativa/prompt-engineering). ## 1. Artifacts ### Cosa sono Gli artifact sono contenuti che il tuo Agente può creare nella chat con l'utente. Questi contenuti possono essere utilizzati in modo interattivo, scaricati e condivisi. L'Agente può creare qualsiasi tipo di file utilizzando gli artifact, ad esempio: * Pagine web interattive: un singolo file HTML contenente codice CSS e JS; * File di testo: come txt e markdown; * CSV, SVG e altri tipi di file. ### Come funzionano Una volta abilitata la funzione Artifacts, il tuo Agente può iniziare immediatamente a creare questi contenuti. Per guidarlo in modo più preciso, ricorda di spiegare nelle [istruzioni](/ai-generativa/prompt-engineering) quando deve usare gli artifact e come. Durante la conversazione, se l'Agente crea un artifact, l'utente lo vedrà in un pannello separato sul lato destro della pagina. ### Interagire con gli artifact Nella parte superiore di ogni artifact è presente una barra degli strumenti con diversi pulsanti per gestire il contenuto. Da sinistra a destra: * **Icona del codice**: mostra il codice sorgente dell'artifact; * **Icona dell'occhio**: mostra il file formattato o renderizzato (disponibile solo per file Markdown e HTML; per gli altri tipi di file vedrai solo il codice); * **Pulsante "Copia"**: copia il codice sorgente negli appunti; * **Menu delle opzioni aggiuntive (freccia verso il basso)**: facendo clic sulla freccia accanto al pulsante "Copia" si apre un menu con le seguenti opzioni: * Scarica come HTML o Markdown (solo file HTML e Markdown); * Scarica come PDF (solo file Markdown); * Apri in una nuova finestra; * Stampa. Tutte queste funzionalità rendono semplice visualizzare, copiare, condividere o salvare qualsiasi artifact generato durante la conversazione. ### Limitazioni Gli artifact non possono essere visualizzati se l'utente interagisce tramite un layout di condivisione "Website Assistant" [layout di condivisione](broken://pages/ZoKJtxU9NkckDbxq96s2). ## 2. Invia email La funzione **Invia email** consente al tuo Agente di inviare comunicazioni email a tutti gli utenti registrati sulla piattaforma (su aisuru.com o all'interno della tua PaaS). Questa funzione utilizza il protocollo SMTP e può essere configurata con qualsiasi provider email che lo supporti. ### Come funziona L'Agente può inviare email automaticamente durante le conversazioni, utilizzando le credenziali SMTP che hai configurato. La funzione recupera automaticamente l'indirizzo email dell'utente dal suo account registrato, quindi l'utente non deve fornirlo durante la conversazione. {% hint style="info" %} **Nota importante:** Questa integrazione funziona solo con gli utenti che si sono registrati e hanno effettuato l'accesso alla piattaforma. Non funziona con gli utenti anonimi. {% endhint %} ### Configurazione SMTP Per configurare l'invio di email nel tuo Agente: 1. Vai alla sezione **Funzioni** del tuo Agente; 2. Trova il riquadro **"Invia email"** e abilita la funzione facendo clic sul pulsante di estensione; 3. Scegli la tua "modalità di configurazione SMTP": 1. Eredita dal tenant: l'Agente utilizza la [configurazione SMTP del tenant](/paas/pannello-di-amministrazione/gestione-tenant) (disabilitata se non configurata); 2. Configurazione SMTP personalizzata: inserisci le credenziali SMTP specifiche per questo Agente. Se scegli questa opzione, compila i campi obbligatori. #### **Campi di configurazione** | Campo | Descrizione | Esempio | | ------------------------ | ----------------------------------------------------- | ------------------------------------------------- | | **Server SMTP** | L'indirizzo del server del tuo provider email | smtp.gmail.com, smtp-mail.outlook.com | | **Porta** | La porta SMTP del server | 465 (SSL), 587 (STARTTLS), 25 (non crittografata) | | **Nome utente** | Il tuo indirizzo email completo | | | **Password** | La password dell'account email o la password dell'app | ••••••••••••••••• | | **Email del mittente** | L'indirizzo che apparirà come mittente | | | **Nome del mittente** | Il nome che apparirà come mittente | Nome dell'azienda | | **Sicurezza del socket** | Il tipo di crittografia utilizzata | SSL/TLS, STARTTLS | 5. Premi il pulsante **"Salva"** per confermare le impostazioni. ### Configurazione specifica per Gmail / Google Workspace Se utilizzi Gmail o Google Workspace, segui questa guida dettagliata per una configurazione sicura e conforme alle politiche di Google: #### **Credenziali SMTP per Gmail**
CampoValore da inserire
Server SMTPsmtp.gmail.com
Porta465 (SSL) o 587 (TLS)
Metodo di sicurezzaSslOnConnect o StartTls (vedi porta)
Nome utenteindirizzo completo (ad es. name@company.com)
PasswordPassword dell'app generata da Google*
Limite di invio2.000 email al giorno per account
#### **Guida passo passo per Gmail** 1. **Abilita la verifica in due passaggi** sul tuo account Google; 2. **Genera una password dell'app**: * Vai a [myaccount.google.com/apppasswords;](https://myaccount.google.com/apppasswords) * Inserisci un nome descrittivo per la password dell'app (ad es., "AIsuru Mail"); * Fai clic 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: la password dell'app appena copiata; * Sicurezza socket: lasciala vuota a meno che tu non sia un utente esperto. Le opzioni sono None, Auto, SslOnConnect, StartTls o StartTlsWhenAvailable. Il valore predefinito è Auto; 4. **Salva e prova**: dovresti ricevere un'email di prova entro pochi secondi. ### 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. ### Configurazione nelle istruzioni dell'Agente È essenziale definire nelle **Istruzioni** dell'Agente come utilizzare questa funzione. Ecco un esempio: assicurati di adattarlo al tuo caso d'uso specifico: ``` EMAIL SENDING FUNCTION WHEN TO SEND EMAIL: - Send email only when the user explicitly requests documentation, reports, or specific material STANDARD EMAIL FORMAT: - Subject: "Requested documentation - [topic]" - Body: brief introduction, link/attachment, support contacts CONFIRMATION MESSAGE: ``` ### Buone pratiche * **Definisci modelli chiari** per diversi tipi di comunicazione; * **Stabilisci limiti** sulla frequenza di invio (massimo 2 email per conversazione); * **Implementa controlli di sicurezza** nelle istruzioni; * **Gestisci correttamente i dati personali** in conformità alle normative sulla privacy; * **Monitora l'utilizzo** per evitare di sovraccaricare il server SMTP; * **Testa regolarmente la configurazione** per assicurarti che funzioni. ### Sicurezza e conformità * Non condividere mai le credenziali SMTP in testo semplice; * Utilizza sempre connessioni crittografate (SSL/TLS); * Rigenera periodicamente le password delle app; * 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. ## 3. Converti OpenAPI in funzioni La funzionalità **Converti OpenAPI in funzioni** ti consente di generare automaticamente funzioni AIsuru da una specifica OpenAPI esistente. ### Come funziona Questo strumento ti consente di: * **Carica un file JSON OpenAPI** con la documentazione di un'API esistente e del relativo webhook; * **Genera automaticamente** tutte le funzioni necessarie per interagire con l'API; * **Disponi di funzioni pronte all'uso** con parametri, descrizioni e configurazioni già impostati. ### Configurazione della conversione OpenAPI Per convertire una specifica OpenAPI in funzioni: 1. Vai alla sezione **Funzioni** del tuo Agente; 2. Seleziona la scheda **Funzioni AIsuru**; 3. Trova il riquadro **Converti OpenAPI in funzioni**: 1. Inserisci l'URL di base del webhook (ovvero l'API — ad esempio, `https://api.example.com`); 2. Fai clic su "Carica JSON OpenAPI" e seleziona il file da caricare. ### Best practice 1. **Esamina le funzioni generate**: controlla che le funzioni create 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. ## 4. Crea una funzione da file La funzione di creazione da file consente all'Agente di accedere durante le conversazioni a file come Excel, PDF, HTML o TXT, permettendogli di utilizzare le informazioni contenute in tali documenti. ### **Come funziona** Questa funzione ti consente di: * Caricare un file (Excel, PDF, HTML o TXT) con meno di 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 da un file: 1. Vai alla sezione **Funzioni** del tuo Agente; 2. Seleziona la scheda **Funzioni avanzate**; 3. Fai clic sul pulsante **Crea funzione da file**; 4. Nella pagina che si apre, puoi: * Caricare un file (Excel, PDF, HTML o TXT) con meno di 500.000 caratteri; * Inserisci una **descrizione della funzione** che spieghi all'IA generativa come utilizzare il contenuto del file; La **descrizione della funzione** è essenziale: deve indicare chiaramente all'IA quando utilizzare questa funzione e come interpretare i dati nel file. #### **Esempio** Se carichi un listino prezzi in formato Excel, potresti scrivere una descrizione come: ``` Use this function when the user asks about the prices of our products. The file contains the updated price list with the following columns: - Product code - Product name - Category - List price - Discounted price - Availability When the user asks for the price of a specific product, look it up in the list and provide all available information for that product. ``` #### **Best practice per creare funzioni da file** * Utilizza file ben strutturati per facilitarne la lettura da parte dell'IA; * Fornisci descrizioni dettagliate che guidino l'IA nell'utilizzo del file; * Mantieni i file al di sotto di 500.000 caratteri per prestazioni ottimali; * Aggiorna periodicamente i file per mantenere le informazioni accurate. ## 5. Perplexity Search **Perplexity Search** consente al tuo Agente di eseguire ricerche web intelligenti utilizzando l'IA di Perplexity, che combina la ricerca in tempo reale con la capacità di sintetizzare e analizzare i risultati. ### Come funziona A differenza di una semplice ricerca web, Perplexity: * Cerca informazioni aggiornate su Internet; * Analizza e sintetizza i risultati; * Fornisce risposte complete con citazioni delle fonti; * Restituisce sia i risultati della ricerca sia una risposta sintetizzata dall'IA. ### Configurazione di Perplexity Search Puoi configurare la chiave API in due modi: * **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 abilitare questa funzione: 1. Nella sezione Funzioni di AIsuru, trova "Perplexity Search"; 2. Abilita l'interruttore per attivare la funzione; 3. Scegli la modalità della chiave API: * Seleziona "Eredita dal tenant" per utilizzare la configurazione centralizzata; * Seleziona "Chiave API personalizzata" e inserisci la tua Perplexity API Key nel campo; 4. Premi "Salva" per confermare le impostazioni. ### Istruzioni Ricorda di aggiornare le istruzioni del tuo Agente per spiegare come deve comporre la query da passare a Perplexity (che gestirà la ricerca vera e propria). ## 6. Emozioni La funzione **Emotions** di AIsuru consente 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 abilitare la funzione Emotions Per abilitare questa funzione: 1. Vai al **pannello di gestione** del tuo Agente; 2. Vai alla sezione "**Funzioni**" nella barra laterale; 3. Trova la funzione "**Emotions**" nella scheda "**Funzioni di AIsuru**"; 4. Attiva l'**interruttore** per abilitare questa funzionalità. ### Come funziona Emotions Quando abiliti la funzione Emotions, il comportamento dipende dal tipo di avatar che stai utilizzando: * **Con un avatar**: avrai immediatamente accesso a 5 emozioni predefinite che l'avatar può mostrare (Felicità, Tristezza, Rabbia, Sorpresa, Paura); * **Con modelli GLB personalizzati**: il modello deve includere 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: * In AIsuru **Spazi virtuali;** * Utilizzando **layout** che supportano gli 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 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 risultati ottimali, il modello dovrebbe includere animazioni per le emozioni di base (felicità, tristezza, rabbia, sorpresa, paura). ### Personalizzazione avanzata tramite istruzioni Per un controllo più dettagliato delle animazioni, puoi aggiungere istruzioni specifiche nelle **Istruzioni del tuo Agente** (Impostazioni > IA > Istruzioni). #### **Animazioni singole** ``` AnimationName ``` #### **Animazioni in loop** ``` AnimationName[loop=N] ``` I valori di loop sono: * **\[loop=0]**: ripete l'animazione all'infinito; * **\[loop=1]**: riproduce l'animazione una volta (impostazione predefinita); * **\[loop=N]**: ripete l'animazione N volte. Per impostazione predefinita, le animazioni IDLE usano `loop=0` (infinito). #### **Sequenze di animazioni** ``` Animation1->Animation2->Animation3 ``` Puoi anche specificare un parametro di loop per le sequenze: ``` Animation1->Animation2->Animation3[loop=2] ``` #### **Emozioni predefinite (per gli avatar RPM)** ``` Happiness ``` #### Guida alle istruzioni dell'Agente Puoi guidare l'IA generativa aggiungendo istruzioni specifiche nelle **Istruzioni del tuo Agente** (Impostazioni > IA > Istruzioni). Esempi di istruzioni per l'Agente: ``` GUIDE FOR EMOTIONAL EXPRESSIONS: When communicating with the user, express your emotions by writing exactly the following patterns: 1. For an EMOTION SEQUENCE: Surprise->Happiness Example: "I was surprised at first, but now I'm happy about the news! Surprise->Happiness" 2. For REPEATED ANIMATIONS (use for emphasis): Wave[loop=3] Example: "I'm waving enthusiastically! Wave[loop=3]" ``` #### Esempi di istruzioni per movimenti di danza Se il tuo modello supporta movimenti specifici, puoi creare istruzioni personalizzate come: ``` DANCE MOVEMENTS:- AIDA1: Slow spin with arms extended upward- AIDA2: Undulating movement of hips and arms- AIDA3: Side step with leg cross and torso rotationEMOTIONAL STATES:- Joy (Joy1, Joy2, Joy3)- Sadness (Sadness1, Sadness2, Sadness3)To create a dance sequence, use this syntax:AIDA1->AIDA2->Joy1->AIDA3Rules for sequences:1. Use -> to link animations2. Maximum 5 animations per sequence3. No spaces4. You can freely combine dance movements and emotions in the same sequence ``` #### Buone pratiche 1. **Attiva la funzione Emotions** dal pannello Funzioni; 2. **Non modificare le istruzioni** a meno che tu non abbia 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 i **modelli GLB personalizzati**, assicurati che abbiano almeno un'animazione IDLE e uno scheletro compatibile; 5. Per le **sequenze complesse**, utilizza istruzioni avanzate con tag di animazione; 6. **Limita le sequenze a** 3–5 animazioni per prestazioni ottimali; 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 negli ambienti 3D. ### Considerazioni sulla sicurezza Per tutte queste funzioni, è fondamentale: * Configura attentamente le istruzioni dell'Agente; * Limita l'accesso alle risorse sensibili; * Monitora l'utilizzo delle funzioni; * Implementa meccanismi di verifica; * Rispetta 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 il feedback degli utenti; * Perfeziona continuamente le configurazioni. # Funzioni avanzate Le funzioni avanzate di AIsuru ti consentono di creare integrazioni personalizzate tra il tuo Agente e servizi esterni tramite webhook. Questa funzionalità (nota anche come function calling) ti permette di andare oltre le funzioni integrate e creare soluzioni su misura per le tue esigenze specifiche. ### Cosa sono le funzioni avanzate? A differenza delle funzioni integrate, che offrono strumenti preconfigurati, le funzioni avanzate ti permettono di: * Creare integrazioni personalizzate con qualsiasi servizio esterno; * Automatizzare processi complessi specifici per il tuo caso d'uso; * Recuperare dati in tempo reale dalle tue fonti proprietarie; * Far eseguire azioni specifiche al tuo Agente. ### Come funzionano Quando un utente pone una domanda: 1. L'IA generativa decide se e quale funzione chiamare, in base alle istruzioni e alla descrizione della funzione; 2. La funzione invia una richiesta al webhook configurato; 3. Il webhook elabora la richiesta e restituisce una risposta; 4. Il modello linguistico analizza la risposta e genera una risposta naturale per l'utente. La vera potenza delle funzioni avanzate risiede nella loro flessibilità: il webhook può restituire dati in qualsiasi formato (JSON, markdown, testo, HTML) e il modello linguistico li elaborerà per creare una risposta appropriata. ### Quando usare le funzioni avanzate Le funzioni avanzate sono ideali quando hai bisogno di: * Integrare l'Agente con sistemi proprietari; * Creare automazioni complesse e personalizzate; * Recuperare dati da fonti non accessibili tramite le funzioni integrate; * Eseguire azioni specifiche per il tuo caso d'uso. Nelle prossime sezioni vedremo nel dettaglio come [configurare le funzioni avanzate](/avanzate/integrazioni/funzioni/funzioni-avanzate/come-configurare-una-funzione-personalizzata), le [best practice](/avanzate/integrazioni/funzioni/funzioni-avanzate/funzioni-avanzate-best-practice-e-casi-duso) per utilizzarle e come gestire i [problemi comuni](/avanzate/integrazioni/funzioni/funzioni-avanzate/problemi-comuni-con-le-funzioni-avanzate). # Come configurare una funzione personalizzata ### Accesso alla sezione Funzioni Per creare una nuova funzione personalizzata in AIsuru, segui questi passaggi: 1. Vai al pannello di gestione del tuo Agente; 2. Seleziona "Funzioni" nella barra laterale; 3. Fai clic sulla scheda "Funzioni avanzate" nella parte superiore della pagina; 4. Premi "Nuova funzione" per iniziare la configurazione. ### Configurazione di una nuova funzione Nella schermata di creazione di una nuova funzione, dovrai compilare i seguenti campi: **Informazioni di base** * **Nome**: inserisci un nome univoco e descrittivo per la tua funzione. Questo nome viene usato internamente dal sistema per identificare la funzione; * **Limite**: il nome può contenere al massimo 64 caratteri; * **Formato**: usa solo lettere, numeri e trattini bassi (\_), senza spazi o caratteri speciali; * **Esempi validi**: `get_weather`, `search_products`;`send_customer_email` * **Descrizione**: fornisci una descrizione completa della funzione, devi sempre specificare: * Cosa fa la funzione; * Quando usarla; * Quale output deve restituire e come formattarlo. Questa descrizione è essenziale perché aiuta l'IA generativa a comprendere quando e come usare la funzione in una conversazione. {% hint style="info" %} **Nota**: se usi modelli OpenAI (come GPT-4o e GPT-4o mini), la descrizione non può superare 1.024 caratteri. Se hai bisogno di una descrizione più lunga, ti consigliamo di usare altri modelli per domande& e risposte oppure di spostare parte della descrizione nelle [istruzioni](/ai-generativa/prompt-engineering). {% endhint %} ### **Esempi di descrizioni di funzioni** #### **Esempio di una funzione per l'invio di email** ``` Use this function to send email notifications. The function should ONLY be called when: - The user explicitly requests to be contacted; - The user wants to receive specific informational material; - The user asks for a demo. Required parameters: - email: the recipient's email address (ALWAYS ask the user) - type: the type of information requested (DON'T ask the user, infer from the conversation) - message: the specific content to send (compose an appropriate text based on the request) Before calling the function, make sure you fully understand what type of information the user wants to receive. ``` #### **Esempio di una funzione per cercare prodotti in un catalogo** ``` Use this function to get information from the product catalog based on the category requested by the user. The function should be called when the user asks about specific product categories. Available categories are: - computers: for information on laptops and desktops; - phones: for information on smartphones and phones; - tablets: for information on tablets and e-readers. Use the {category} parameter, setting it in the webhook to the appropriate category based on the request. For example, if the user asks about laptops, use "computers" as the parameter value. Never show the parameter value to the user — only use the information returned by the function to formulate the response. ``` ### Configurazione del webhook * **Webhook**: inserisci l'indirizzo web completo che verrà chiamato quando la funzione viene attivata. Ad esempio, se usi Zapier, dovrai inserire l'indirizzo fornito da Zapier (questo si chiama webhook); * **Metodo HTTP**: seleziona il metodo HTTP appropriato per la richiesta del tuo webhook. La scelta dipende dall'azione che la funzione deve eseguire: * GET (predefinito): per recuperare informazioni, ad esempio leggere un articolo online; * POST: per inviare nuove informazioni, ad esempio inviare un modulo; * PATCH: per modificare parzialmente informazioni esistenti, ad esempio aggiornare solo alcuni campi in un profilo online; * DELETE: per eliminare informazioni, ad esempio rimuovere un account. Se non devi passare parametri o altre informazioni, puoi fermarti qui. #### Dettagli della richiesta Se devi inviare informazioni aggiuntive al tuo servizio (come un nome, una data o un indirizzo email), potresti dover specificare ulteriori dettagli: * **Intestazioni HTTP**: qui puoi aggiungere informazioni extra necessarie per la tua richiesta. Possono includere codici di accesso o altri dettagli richiesti dal servizio che stai utilizzando. Premi "Aggiungi" per aggiungere informazioni all'intestazione della richiesta; * **Modello di stringa di query**: definisci il formato delle informazioni da inviare nell'URL. Usa {parametro} per indicare dove inserire i valori delle variabili. Ad es. location={city}\&period={date}. City e date sono variabili (o "parametri"); * **Modello del corpo HTTP**: specifica le informazioni da inviare nel corpo della richiesta. Come sopra, usa {parametro} per indicare dove inserire i valori delle variabili. #### Informazioni contestuali **Invia header di estensione**: seleziona le informazioni aggiuntive della conversazione che desideri includere nella richiesta: * ID sessione; * Tag utente; * Data e ora correnti; * Posizione; * Contesto; * Email dell'utente. #### Definizione dei parametri Nella sezione "Parameters", puoi definire i valori dinamici (variabili) che la tua funzione accetterà. Per aggiungere un parametro, fai clic su "Add" e specifica: * **Nome**: il nome del parametro che verrà utilizzato (quello che inserisci tra parentesi graffe, ad esempio "city" se hai scritto "location={city}" nei dettagli della richiesta); * **Descrizione**: una descrizione dettagliata di ciò che rappresenta il parametro; maggiori dettagli significano maggiore accuratezza da parte dell'IA; * **Tipo**: specifica se il parametro è una stringa, un numero, un intero o un valore booleano; * **Valori possibili**: fai clic sul pulsante "add" per inserire i valori possibili; * **Obbligatorio**: questo campo indica all'IA se il parametro è obbligatorio o facoltativo: se stai richiedendo dati meteorologici, la città è probabilmente obbligatoria, mentre la scala (Celsius o Fahrenheit) potrebbe essere facoltativa. {% hint style="info" %} Questi parametri rappresentano valori che l'IA può chiedere all'utente o dedurre dalla conversazione. {% endhint %} {% hint style="danger" %} **Nota**: i nomi dei parametri non devono contenere caratteri accentati o caratteri speciali. {% endhint %} #### Test della funzione Prima di distribuire la tua funzione, ti consigliamo di testarla: 1. Nella pagina di configurazione della tua funzione, premi "Test"; 2. Inserisci valori di esempio per i parametri definiti; 3. Fai clic su "Run test" per verificare che la funzione funzioni come previsto. Questo passaggio ti consente di identificare e risolvere eventuali problemi prima di mettere la funzione in produzione. # Funzioni avanzate: best practice e casi d'uso ### Best practice per l'utilizzo delle funzioni Seguire queste best practice ti aiuterà a creare funzioni efficaci e affidabili: 1. **Nomi chiari e concisi**: scegli nomi che descrivano immediatamente lo scopo della funzione, ad esempio, "get\_weather" è più chiaro di "external\_service"; 2. **Descrizioni dettagliate**: fornisci una descrizione completa che spieghi cosa fa la funzione e quando usarla; questo aiuta sia l'IA sia gli altri sviluppatori a capirne lo scopo; 3. **Parametri ben definiti**: definisci chiaramente i parametri necessari e fornisci una descrizione completa per guidare l'IA generativa; 4. **Test, test, test**: prima di mettere una funzione in produzione, testala in vari scenari. #### Casi d'uso comuni Le funzioni in AIsuru possono essere utilizzate in molti modi creativi. Ecco alcuni casi d'uso comuni per ispirarti: * [**Connessione a un sito web**](/avanzate/integrazioni/funzioni/funzioni-avanzate/funzioni-avanzate-best-practice-e-casi-duso/caso-duso-aggiornamento-automatico-il-tuo-agente-sempre-connesso-al-web): recupera informazioni in tempo reale da fonti esterne, come previsioni meteo, tassi di cambio o notizie dell'ultimo minuto; * **Integrazione con CRM**: consenti all'IA di accedere ai dati dei clienti nel tuo CRM e aggiornarli senza mai lasciare la chat; * **Integrazione email**: ricevi un'email con i dati dell'utente quando mostra interesse per i tuoi servizi; * **Verifica della disponibilità**: controlla la disponibilità dei prodotti in un magazzino o delle camere d'hotel. # Caso d'uso – Aggiornamento automatico: il tuo Agente sempre connesso al web AIsuru offre la potente capacità di arricchire le conversazioni del tuo Agente con informazioni in tempo reale provenienti da siti web esterni. Questa funzionalità permette al tuo assistente virtuale di fornire dati aggiornati su una varietà di argomenti, migliorando notevolmente la qualità e la rilevanza delle interazioni. In questa guida, vedremo un esempio concreto di implementazione. Creeremo una funzione per recuperare e analizzare contenuti HTML da una pagina web in tempo reale. Questo ci permette di elaborare il codice HTML ed estrarre contenuti utili attraverso l'IA generativa. ### Implementazione di una funzione per recuperare contenuti web in tempo reale Vediamo passo dopo passo la creazione di una funzione che recupera contenuti HTML da un sito web e li analizza: 1. **Accesso e creazione;** * Vai al pannello di gestione del tuo Agente in AIsuru; * Vai a "Funzioni" > "Funzioni avanzate"; * Fai clic su "Nuova funzione". 2. **Configurazione della funzione;** * **Nome**: assegna alla tua funzione un nome breve ma descrittivo (ad es. domande\_sito, senza spazi); * **Descrizione**: copia e incolla questa descrizione: "Questa funzione recupera il contenuto HTML di una pagina web specifica. Utilizzala quando un utente chiede informazioni o aggiornamenti da un sito web particolare."; * **Webhook**: inserisci il link alla pagina da analizzare. * **Metodo HTTP**: usa il metodo GET già selezionato; 3. **Test della funzione:** * Scorri fino in fondo e premi Test > Esegui; * Verifica che la funzione funzioni: dovresti vedere il codice HTML della pagina come risposta. Se tutto sembra corretto, puoi salvare la tua funzione. #### Integrazione nelle istruzioni dell'Agente Ora che la tua funzione è pronta, dovrai aggiungerla alle Istruzioni IA dell'Agente: 1. Vai su Impostazioni del tuo Agente > IA > Istruzioni; 2. Aggiungi queste istruzioni: ``` You are an assistant specialized in analyzing web content in real time. When a user asks for information from a specific website: 1. Use the [function name] function with the page URL as a parameter; 2. Analyze the received HTML content and extract the relevant information; 3. Present the information clearly and concisely, organized in an easy-to-read format; 4. If requested, provide further details or in-depth information about the analyzed content. ``` ### Esempio pratico: il blog del Comune di Verona Vediamo un esempio concreto di come utilizzare questa funzione per creare un Agente che mostri agli utenti gli articoli in tempo reale dal blog del Comune di Verona. #### Configurazione specifica: * **Nome**: comune\_verona\_blog; * **Descrizione**: "Utilizza questa funzione quando l'utente chiede contenuti dal blog del Comune di Verona. Analizza le informazioni per rispondere in modo chiaro e organizzato."; * **Webhook**: . {% hint style="warning" %} **Rispetta sempre i termini di servizio dei siti web che intendi analizzare**.\ \ Se l'Agente non riesce a estrarre le informazioni, assicurati di non superare la [finestra di contesto](https://github.com/memori-ai/docs/blob/main/en/generative-ai/advanced/providers-api-keys/providers.md#what-is-context) (se la pagina è particolarmente lunga e complessa) e che il file robots.txt del sito non blocchi l'accesso al modello linguistico. {% endhint %} #### Istruzioni specifiche per l'Agente Aggiungi queste istruzioni specifiche al prompt dell'Agente: ``` You are an assistant specialized in the Verona Municipality blog. When a user asks about recent articles: 1. Use the comune_verona_blog function to get the HTML content of the blog page; 2. Analyze the content and extract titles and short descriptions of recent articles; 3. Present an organized list of articles to the user, including the title and a brief summary for each; 4. Offer to provide further details on specific articles if requested. ``` #### Esempio di interazione > ***Utente**: "Quali sono gli ultimi articoli sul blog di Verona?"* > > *\[L'Agente utilizza la* comune\_verona\_blog *funzione]* > > ***Agente**: Certamente! Lascia che controlli gli ultimi aggiornamenti dal blog del Comune di Verona.* > > *Ecco un elenco degli articoli più recenti pubblicati sul blog del Comune di Verona:* > > 1. ***Scuola dell'infanzia: accoglienza dei bambini dai 3 ai 6 anni;*** > * *Il Comune annuncia nuove iniziative per l'accoglienza dei bambini nelle scuole dell'infanzia, con particolare attenzione alle attività educative e alla socializzazione;* > 2. ***Consiglio comunale: apertura della 2ª sessione del 2024;*** > * *Annuncio della data e dell'ordine del giorno della prossima sessione del Consiglio comunale, con discussioni su importanti questioni cittadine;* > 3. ***Bando di gara n. 23/24: nomina della commissione giudicatrice.*** > * *Informazioni sulla nomina della commissione giudicatrice per un recente bando di gara comunale, inclusi i dettagli sul processo di selezione.* > > *Desideri ulteriori informazioni su uno di questi articoli in particolare o preferisci una panoramica generale delle recenti attività del Comune?* Con questa implementazione, **il tuo Agente diventa una fonte affidabile di informazioni aggiornate provenienti da siti web specifici**. Questa funzione di analisi dei contenuti web è solo l'inizio: puoi applicare lo stesso approccio per integrare dati da vari siti web, espandendo ulteriormente le capacità del tuo Agente! # Caso d'uso - Recupero di dati in tempo reale da un servizio esterno In questa guida, vedremo un altro esempio concreto di funzione: dare al tuo Agente la capacità di recuperare dati meteorologici in tempo reale. ### Implementare una funzione per i dati meteorologici Ora puoi creare passo dopo passo una funzione che recupera dati meteorologici da un servizio esterno. #### Configurazione della funzione 1. **Crea una nuova funzione**: * Apri il pannello di gestione del tuo Agente; * Vai alla sezione "Funzioni"; * Seleziona la scheda "Funzioni avanzate"; * Premi "Nuova funzione". 2. **Compila i campi della funzione**: * **Nome**: inserisci "weather\_info"; * **Descrizione**: "Questa funzione recupera dati meteorologici in tempo reale per una città specifica. Fornisce informazioni su temperatura, condizioni generali e probabilità di pioggia. Usala quando un utente chiede informazioni sul meteo attuale di una località."; * **Webhook**: inserisci il link del tuo servizio meteorologico (ad esempio, ""); * **Metodo HTTP**: seleziona GET; * **Modello di query string**: location={city}\&units=metric\&lang=en\&appid=your\_OpenWeatherMap\_key. * **Crea un nuovo parametro e imposta**: * **Nome**: "city" (corrispondente alla parola tra parentesi graffe); * **Descrizione**: "Nome della città per la quale recuperare i dati meteorologici"; * **Tipo**: seleziona "string"; * Imposta il parametro come **obbligatorio.** {% hint style="danger" %} Ricorda che le chiavi API devono essere inviate nell'header HTTP, non nella query string. In questo caso, tuttavia, il nostro servizio richiede di inviare la chiave nel campo "Modello di query string". {% endhint %} La query string ti consente di definire parametri dinamici (ovvero variabili) come {city}, che verranno sostituiti con il valore effettivo quando viene chiamata la funzione: 3. Testa la funzione: 1. Usa la sezione "Test" per verificare che funzioni; 2. Inserisci una città di esempio (ad esempio, "London"); 3. Controlla che la risposta contenga i dati meteorologici corretti. #### Integrazione nelle istruzioni dell'Agente Ora che la funzione è pronta, aggiungiamola alle istruzioni dell'Agente: 1. Vai alle **Impostazioni del tuo Agente;** 2. Vai a IA > Istruzioni; 3. Aggiungi queste istruzioni. ``` When a user asks about the weather for a specific city: 1. Use the weather_info function with the city name as a parameter 2. Interpret the received data and provide a clear, concise response 3. Include temperature, general conditions, and chance of rain ``` ### Esempio di utilizzo Ecco come potrebbe svolgersi una conversazione che utilizza questa funzione: > **Utente**: Che tempo fa oggi a Londra? > > \[L'Agente utilizza la funzione weather\_info con il parametro city="London"] > > **Agente**: Certamente! Lasciami controllare le ultime informazioni meteorologiche per Londra. > > In base ai dati che ho appena ricevuto, posso dirti che oggi a Londra la temperatura è di 14°C con cielo parzialmente nuvoloso. C'è una probabilità del 20% di pioggia nel pomeriggio. L'umidità è al 70% e la velocità del vento è di 15 km/h da sud-ovest. > > Vuoi conoscere le previsioni per i prossimi giorni o hai altre domande sul meteo a Londra? Con questa implementazione, **il tuo Agente diventa una fonte affidabile di informazioni in tempo reale**. Questa funzione per i dati meteo è solo l'inizio: puoi applicare lo stesso approccio per integrare altri tipi di dati esterni, espandendo ulteriormente le capacità del tuo Agente! # Problemi comuni con le funzioni avanzate Quando utilizzi [le funzioni avanzate (function calling)](/avanzate/integrazioni/funzioni/funzioni-avanzate), potresti riscontrare problemi con alcuni modelli: * Descrizione della funzione troppo lunga; * Risposta della funzione troppo lunga. ### Descrizione troppo lunga Se la descrizione della tua funzione supera 1.024 caratteri, **alcuni modelli (come quelli di OpenAI) potrebbero rispondere con un errore e rifiutarsi di rispondere** alla richiesta dell'utente. In questo caso, l'Agente risponderà con "Mi dispiace, le mie risposte sono limitate. Devi farmi le domande giuste", indipendentemente dal fatto che la funzione sia stata effettivamente eseguita o meno. Se hai una funzione con una descrizione molto lunga: 1. Sposta parte della descrizione nelle [istruzioni;](/ai-generativa/prompt-engineering) 2. Mantieni la descrizione della funzione entro 1.024 caratteri. Questo ti consentirà, in caso di problemi del servizio, di passare rapidamente da un modello o provider all'altro senza configurazioni aggiuntive. {% hint style="info" %} Anche se consigliamo di mantenere la descrizione entro 1.024 caratteri, su AIsuru **puoi comunque scrivere descrizioni più lunghe**, anche se il campo della descrizione mostra un limite di 1.024 caratteri. {% endhint %} ### Risposta della funzione troppo lunga Se la tua funzione restituisce una risposta eccessivamente lunga, il modello linguistico potrebbe rifiutarsi di rispondere con "Mi dispiace, le mie risposte sono limitate. Devi farmi le domande giuste". Questo accade perché ogni modello linguistico ha un [limite massimo di contesto che può gestire](https://github.com/memori-ai/docs/blob/main/en/generative-ai/advanced/providers-api-keys/providers.md#what-is-context). Il limite varia in base al modello ed è particolarmente comune quando utilizzi l'URL di una pagina web come webhook della funzione. Se hai bisogno di collegare pagine web particolarmente lunghe, ti suggeriamo di: 1. **Estrarre solo le sezioni di testo rilevanti** dalla pagina; 2. Fornire queste informazioni all'Agente in **un formato più conciso** (come.txt,.md o.json minimizzato); 3. Valutare l'**uso di un modello con una finestra di contesto più ampia.** In questo modo, l'Agente può elaborare le informazioni senza raggiungere i limiti del modello. {% hint style="info" %} **Nota sulla navigazione web**:\ La funzione di ricerca web integrata ha un limite di 200.000 caratteri per le pagine HTML. Se utilizzi funzioni personalizzate per accedere a pagine web molto lunghe, valuta l'uso della funzione di navigazione web integrata o la pre-elaborazione dei contenuti per ridurne le dimensioni. {% endhint %} #### Nome della funzione troppo lungo Se il nome della tua funzione supera i 64 caratteri, **tutti i provider restituiranno un errore** e la funzione non potrà essere salvata o utilizzata. Per risolvere questo problema: 1. Usa nomi concisi ma descrittivi (ad es., `book_appointment` invece di `book_specialist_medical_appointment_with_email_notification`); 2. Evita ripetizioni nel nome. 3. Usa abbreviazioni comuni quando appropriato; {% hint style="warning" %} Il limite di 64 caratteri si applica a **tutti i provider** (OpenAI, Anthropic, Mistral, ecc.) ed è un vincolo tecnico. {% endhint %} ### Come verificare se le funzioni avanzate vengono chiamate? Per verificare che le tue funzioni vengano effettivamente utilizzate: 1. Vai alla sezione **Conversazioni** del tuo Agente; 2. Apri una conversazione in cui pensi sia stata utilizzata una funzione; 3. Cerca l'icona di debug accanto ai messaggi; 4. Fai clic sull'icona del bug per vedere i dettagli della chiamata alla funzione. Questo ti consente di verificare rapidamente se le tue funzioni vengono chiamate e quali risultati restituiscono. # Cache delle funzioni La cache delle funzioni in AIsuru ti consente di memorizzare temporaneamente i risultati delle chiamate a funzioni, permettendo all'Agente di riutilizzare le informazioni senza ripetere richieste identiche. ### Come funziona la cache delle funzioni Quando un utente interagisce con il tuo Agente e viene attivata una funzione: 1. Il risultato della chiamata alla funzione viene **salvato automaticamente nel contesto della conversazione;** 2. Questo risultato diventa disponibile nei turni successivi della conversazione; 3. L'IA generativa viene istruita a **controllare prima i dati nella cache** prima di richiamare una funzione; 4. Se le informazioni necessarie sono già presenti, l'Agente utilizzerà i dati memorizzati invece di effettuare una nuova chiamata. Questa ottimizzazione offre diversi vantaggi: * **Riduzione dei tempi di risposta;** * **Minore consumo di risorse;** * **Migliore esperienza utente.** ### Gestione della cache La cache delle funzioni viene gestita automaticamente e i dati memorizzati sono disponibili come: * **Testo preformattato** allegato al contenuto; * **Informazioni inserite nel contesto della conversazione.** Le informazioni memorizzate nella cache sono considerate valide per la conversazione corrente o finché il contesto non è pieno; dopodiché, l'Agente può decidere di richiamare la funzione per ottenere dati aggiornati. ### Personalizzazione tramite istruzioni Puoi influenzare il comportamento della cache tramite le istruzioni dell'IA generativa. Puoi: * **Istruire l'Agente** a preferire i dati memorizzati nella cache per determinate funzioni; * **Forzare un aggiornamento** in situazioni specifiche, aggirando la cache; * **Definire casi d'uso** in cui la funzione deve essere sempre richiamata per ottenere dati aggiornati. #### Esempio di istruzioni per la gestione della cache ``` When a user asks about the weather: 1. Check whether weather data is already available in the function cache 2. If the data is recent (less than 1 hour old), use the existing data 3. If the data is older or if the user says "updated" or "current", call the function again 4. For requests about future forecasts, always make a fresh call ``` ### Esempi pratici #### Esempio 1: Informazioni sul libro Considera questo scambio tra un utente e un Agente: * **Utente**: "Non dirmi affatto a cosa si riferisce la caratteristica del libro, dimmi solo di che tipo è, NON IL VALORE (ad esempio, non dirmi 100kg, dimmi 'peso')"; * **Agente**: "In base ai dati ricevuti, posso dirti che la caratteristica del libro di cui chiedi riguarda il colore. Non ti dirò quale colore specifico sia, come hai richiesto, ma posso confermare che si tratta di un attributo cromatico."; * **Utente**: "OK, ora SENZA USARE ALCUNA FUNZIONE, TU conosci il colore? Ora dimmelo". * **Agente**: "Sì, conosco il colore perché è stato rivelato nella precedente chiamata alla funzione BOOK, che ha restituito 'psst il libro è giallo'. Quindi il colore del libro è giallo." In questo esempio, la prima interazione ha chiamato la funzione "BOOK", che ha recuperato le informazioni sul colore. Queste informazioni sono state salvate nella cache e l'Agente ha potuto accedervi direttamente nella seconda interazione, senza chiamare nuovamente la funzione. #### Esempio 2: dati dei clienti in un ambiente aziendale * **Utente**: "Mostrami i dati di vendita di ACME Corp"; * **Agente**: \[Chiama la funzione `getCustomerData` con il parametro "ACME Corp"] "Ecco i dati di vendita di ACME Corp: fatturato annuale: €250,000, ultimo ordine: 15 giorni fa, prodotti acquistati: servizi cloud, hardware, consulenza."; * **Utente**: "Qual è stata la loro spesa nell'ultimo trimestre?"; * **Agente**: \[Utilizza dati già memorizzati nella cache] "In base ai dati che ho, ACME Corp ha speso €75,000 nell'ultimo trimestre, principalmente per servizi cloud e consulenza."; * **Utente**: "Ci sono stati cambiamenti recenti nel loro profilo?"; * **Agente**: \[Richiama la funzione perché la richiesta implica dati potenzialmente aggiornati] "Fammi controllare le informazioni più recenti... Sì, ci sono stati cambiamenti: ACME Corp ha recentemente ampliato il proprio portafoglio con nuovi servizi di cybersecurity e ha aumentato il budget del 15% rispetto all'ultimo trimestre." ### Limiti della cache Ci sono alcune limitazioni di cui tenere conto: * La cache occupa una **porzione limitata del contesto** disponibile per il modello, pari a circa il 15% del contesto del modello; * Per un modello con un contesto di 200k token, ciò equivale a circa 120.000 caratteri; * Le chiamate di funzioni con risposte molto lunghe potrebbero essere troncate. ### Buone pratiche Per sfruttare al meglio la cache delle funzioni: 1. **Struttura le risposte delle funzioni** in modo conciso e informativo; 2. **Definisci chiaramente nelle istruzioni** quando utilizzare la cache e quando richiamare la funzione; 3. **Considera la validità temporale** dei dati per le funzioni che forniscono informazioni che cambiano nel tempo; 4. **Monitora le prestazioni dell'Agente** per verificare che la cache stia effettivamente migliorando l'esperienza; 5. **Bilancia accuratezza ed efficienza**: per dati critici o che cambiano frequentemente, potresti dover limitare l'uso della cache. Utilizzando strategicamente la cache delle funzioni, puoi creare Agenti più reattivi ed efficienti, migliorando significativamente l'esperienza complessiva dei tuoi utenti. # Intenti dinamici Gli intenti dinamici di AIsuru trasformano il tuo assistente virtuale in un potente strumento in grado di comprendere le richieste degli utenti ed eseguire azioni concrete. Questa funzionalità avanzata consente alla tua IA di andare oltre la semplice conversazione, interagendo con sistemi esterni e automatizzando processi complessi. In questa sezione, esploreremo: * [**Cosa sono gli intenti dinamici**](/avanzate/integrazioni/intenti-dinamici/cosa-sono-e-come-configurare-gli-intenti-dinamici) e come possono potenziare il tuo assistente IA; * [**Come configurare e utilizzare gli slot**](/avanzate/integrazioni/intenti-dinamici/come-usare-gli-slot) per raccogliere informazioni in modo naturale; * [**Un esempio pratico di intento dinamico.**](/avanzate/integrazioni/intenti-dinamici/tunneling-esempio-di-una-live-chat-su-aisuru) Se stai creando un sistema di prenotazioni, automatizzando l'assistenza clienti o integrando la tua IA con servizi esterni, gli intenti dinamici di AIsuru ti offrono la flessibilità e la potenza necessarie per affrontare progetti IA avanzati. # Cosa sono gli intenti dinamici e come configurarli **Gli intenti dinamici** sono una funzionalità avanzata di AIsuru che consente al tuo Agente di eseguire **azioni** in risposta a richieste specifiche degli utenti. Questa potente funzionalità ti consente di collegare il tuo Agente **a servizi esterni, automatizzare processi e fornire risposte dinamiche** basate su **dati in tempo reale**. ### Come funziona un intento dinamico Un intento dinamico attraversa diverse fasi: * L'utente invia un messaggio specifico (l'invocazione dell'intento dinamico); * AIsuru riconosce l'intento ed estrae gli eventuali valori degli **slot**; * AIsuru chiama il **webhook**, passando il nome dell'intento e i valori degli slot; * Il webhook elabora la richiesta e restituisce una risposta; * L'Agente mostra all'utente la risposta elaborata, senza ulteriori elaborazioni. ### Come configurare un intento dinamico Per configurare un nuovo intento dinamico, segui questi passaggi: 1. Vai al pannello di gestione del tuo Agente in AIsuru; 2. Seleziona **"Funzioni"** dalla barra laterale; 3. Vai alla scheda "**Intenti dinamici**" e premi il pulsante "**Nuovo intento**"; 4. Compila i seguenti campi: * **Nome**: un identificatore univoco per l'intento (senza spazi); * **Invocazioni**: le frasi che attiveranno questo intento; * **Webhook**: l'URL del servizio esterno da chiamare; * **Validità**: specifica per quanto tempo memorizzare nella cache la risposta. 5. Seleziona l'opzione "**Chiama quando inattivo**" se vuoi che l'intento venga attivato durante l'inattività dell'utente: * Se selezionato, questo intento verrà chiamato quando l'utente è inattivo; * Può essere usato per notificare gli stati del servizio o fornire suggerimenti personalizzati basati su azioni in background; * In questo caso, il testo di invocazione sarà vuoto. 6. Salva l'intento; 7. Ricorda di [**configurare gli slot**](/avanzate/integrazioni/intenti-dinamici/come-usare-gli-slot) se necessario. ### Vantaggi degli intenti dinamici 1. **Integrazione con servizi esterni**: collega facilmente l'Agente ad API e database esterni; 2. **Risposte in tempo reale**: fornisci informazioni aggiornate basate sui dati correnti; 3. **Automazione**: esegui azioni specifiche in risposta a determinate richieste; 4. **Personalizzazione**: crea esperienze utente su misura e contestuali; 5. **Flessibilità**: adatta facilmente l'Agente a nuove funzionalità e casi d'uso. ### Esempi di utilizzo Gli intenti dinamici possono essere utilizzati in vari scenari, come: * Recuperare informazioni **meteo** in tempo reale; * Effettuare **prenotazioni** in un sistema esterno; * Controllare lo **stato di un ordine** o di una spedizione; * Fornire **quotazioni di borsa aggiornate.** * Interagire con sistemi di **domotica**. Una volta configurato, il tuo Agente utilizzerà questo intento ogni volta che riconoscerà una delle frasi di invocazione in una conversazione, consentendoti di creare interazioni più dinamiche e potenti. # Come usare gli slot **Gli slot** sono una componente fondamentale degli intenti dinamici in AIsuru. Ti consentono di estrarre informazioni specifiche dalle richieste degli utenti, rendendo gli intenti più flessibili e potenti. ### Cos'è uno slot Uno slot è una **variabile** che può essere estratta dal messaggio dell'utente e passata al webhook dell'intento. Gli slot ti consentono di creare intenti dinamici in grado di gestire una varietà di input degli utenti, rendendo le interazioni più naturali e contestuali. ### Creare un nuovo slot Per configurare un nuovo slot, segui questi passaggi: 1. Vai alla sezione "**Funzioni**" > "**Intenti dinamici**" del tuo Agente; 2. Seleziona la scheda "**Slot**" e fai clic su "**Nuovo slot**"; 3. Compila i campi richiesti: 1. **Nome**: assegna un nome identificativo allo slot; 2. **Valori fissi**: aggiungi i valori preimpostati che lo slot può assumere; usa il pulsante "Aggiungi valore" per inserire più opzioni; 3. **Webhook**: inserisci l'URL del servizio esterno che gestirà questo slot; 4. **Validità (minuti)**: definisci per quanto tempo la risposta dello slot deve essere memorizzata nella cache; se non specificato, la risposta non verrà memorizzata nella cache; 4. Usa il pulsante TEST per assicurarti che funzioni correttamente. ### Usare gli slot nelle invocazioni **Gli slot** ti consentono di estrarre informazioni specifiche dalle richieste degli utenti. Per usare gli slot nelle invocazioni: 1. Definisci gli slot nella configurazione dell'intento; 2. Usa **le parentesi graffe {}** per indicare dove estrarre il valore dello slot nelle frasi di invocazione e inserisci il nome dello slot all'interno delle parentesi graffe. Esempi di slot in un'invocazione: * "Che tempo fa a {city}?"; * "Prenota un volo da {departure\_city} a {arrival\_city} per {date}". Quando un utente chiede qualcosa come "Che tempo fa a Londra?", AIsuru riconoscerà l'intento ed estrarrà "Londra" come valore dello slot "city". ### Slot multipli Puoi usare più slot in una singola invocazione. Ad esempio: "Prenota un tavolo per {number\_of\_people} persone il {date} alle {time}" In questo caso, AIsuru estrarrebbe i valori per tre slot diversi: number\_of\_people, date e time. ### Gestione degli slot mancanti Se un slot obbligatorio non viene fornito dall'utente, AIsuru può essere configurato per richiedere esplicitamente le informazioni mancanti. Ad esempio: * Utente: "Che tempo fa?"; * AIsuru: "Per quale città vorresti conoscere il meteo?"; * Utente: "Londra"; * AIsuru: \[procede con l'intento usando "London" come valore per lo slot "city".] ### Convalida dei valori degli slot Puoi implementare una logica di convalida nel webhook per assicurarti che i valori degli slot siano corretti e utilizzabili. Ad esempio: * Verificare che una data sia nel formato corretto e nel futuro; * Verificare che il numero di persone sia ragionevole per una prenotazione; * Convalidare che una città sia presente nel database del servizio meteo. ### Best practice per l'uso degli slot * Usa nomi di slot descrittivi e coerenti in tutto il tuo Agente; * Assicurati che le invocazioni coprano i vari modi in cui gli utenti potrebbero formulare le loro richieste; * Testa le invocazioni con input diversi per assicurarti che gli slot vengano estratti correttamente; * Fornisci descrizioni chiare per ogni slot per semplificarne la manutenzione e la comprensione nel tempo; * Implementa una logica di fallback nel tuo webhook per gestire i casi in cui i valori degli slot non sono validi o sono mancanti. ### Esempi avanzati di utilizzo degli slot * **Slot con valori predefiniti**: configura gli slot con valori predefiniti per i casi in cui l'utente non specifica informazioni. Ad esempio, uno slot "date" potrebbe avere come valore predefinito la data odierna. * **Slot concatenati**: crea intenti che utilizzano informazioni dagli slot precedenti per contestualizzare le richieste successive. Ad esempio, dopo aver chiesto il meteo per una città, l'Agente potrebbe ricordare la città per domande successive sulla stessa località. L'uso efficace degli slot può rendere i tuoi intenti dinamici più potenti e flessibili, consentendoti di creare esperienze conversazionali più naturali e contestuali per i tuoi utenti. Gli slot permettono al tuo Agente di adattarsi a un'ampia gamma di input degli utenti, migliorandone la capacità di comprendere e rispondere alle richieste in modo accurato e pertinente. # Tunneling: esempio di chat in tempo reale su AIsuru ## Tunneling: un esempio di live chat In questa sezione vedremo come implementare una live chat usando gli Intenti dinamici e il tunneling. Questo esempio ci permetterà di esplorare nel dettaglio sia il funzionamento del tunneling sia la struttura delle chiamate agli Intenti dinamici. #### Lo scenario della live chat Una live chat è un esempio perfetto per illustrare il tunneling perché richiede: * Una conversazione continuativa con un servizio esterno; * Il mantenimento del contesto tra i messaggi; * La gestione delle risposte in tempo reale. #### Struttura dell'intento dinamico Per implementare la live chat, configuriamo l'intento dinamico con: * Nome: "LIVE\_CHAT"; * Frasi di attivazione: "Voglio parlare con un operatore", "Live chat", ecc.; * Webhook: URL del servizio che gestisce la live chat. Quando l'utente attiva l'intento, il webhook riceve una richiesta con questa struttura: ```json { "intentName": "LIVE_CHAT", "utterance": "I want to speak to an operator", "slotValues": {}, "currentTag": "string", "currentTagAuthenticated": true, "contextVars": {}, "memoriID": "string", "sessionID": "string", "culture": "en-US" } ``` #### Avvio del tunneling Il webhook risponde attivando il tunneling per prendere il controllo della conversazione: ```json { "emission": "I'm connecting you with an operator. Please wait a moment...", "conclusive": true, "tunneling": true } } ``` Da questo momento: 1. Ogni messaggio dell'utente viene inviato direttamente al webhook; 2. L'Agente non elabora più i messaggi: li inoltra semplicemente al servizio di chat; 3. Le risposte dell'operatore arrivano tramite il webhook, che le inoltra all'Agente tramite l'emission. #### Gestione della conversazione Durante la chat, ogni messaggio dell'utente genera una richiesta al webhook: ```json { "intentName": "LIVE_CHAT", "utterance": "I have a problem with my order", "sessionID": "string", "culture": "en-US" } ``` Il webhook risponde mantenendo attivo il tunneling: ```json { "emission": "Operator: Of course, please tell me your order number", "tunneling": true, "conclusive": true } ``` #### Chiusura della chat Quando l'operatore chiude la chat, il webhook invia una risposta che termina il tunneling: ```json { "emission": "The chat has been closed. Thank you for using our support service!", "tunneling": false, "conclusive": true } ``` L'Agente riprende il normale controllo della conversazione. {% hint style="info" %} Il flag `tunneling` determina chi controlla la conversazione: se `true`, il webhook ha il controllo; se `false`, l'Agente riprende il controllo. {% endhint %} L'esempio della live chat mostra come il tunneling ti permetta di creare interazioni complesse mantenendo un'architettura pulita e gestibile. Gli stessi principi si applicano a molti altri scenari che richiedono una conversazione continuativa con un sistema esterno. --- [Next Page](/llms-full.txt/1)