Cerca nella conversazione
Conferma
Aggiungi come variante di domanda.svg){kind=icon}
Modifica
Elimina
* **Condividi l'Agente con chi vuoi**!
{% hint style="info" %}
**Se l'Agente è privato agli utenti sarà richiesta la password**. Non è mai possibile accedere ad un Agente protetto senza inserire la password, anche se questo è mostrato in homepage
{% endhint %}
# Video riassuntivo
Qui sotto puoi trovare un video che mostra come fare tutto quello che hai visto in meno di 6 minuti 👇
{% embed url="https://www.youtube.com/watch?v=PWgOG62pl4g" %}
Come creare la tua IA da un documento in meno d 6 minuti con [aisuru.com](https://www.aisuru.com/)
{% endembed %}
# Gestione account
La gestione del tuo account ti permette di controllare le tue impostazioni personali, preferenze di notifica e dati di accesso.
### Accesso alle impostazioni account
Per gestire il tuo account, hai due opzioni:
1. Seleziona 
**Account** dalla barra laterale;
2. Clicca sul tuo nome utente in alto a destra, poi seleziona "Account".
### Scheda principale "Account"
Nella scheda "Account", trovi tre sottosezioni 👇
#### Crediti
Premendo sul pulsante "Acquista crediti", puoi **acquistare crediti per la piattaforma**. Puoi approfondire il [funzionamento e il consumo di crediti](../analisi-ottimizzazione/consumi/) accedendo alla sezione dedicata ai consumi.
#### **Impostazioni Account e Privacy**
All'interno di 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 privacy policy (obbligatorio alla registrazione e non modificabile);
* visualizzare tramite il tasto "apri" l'informativa sul uso dei cookie;
* **accettare i termini di Pensiero Profondo** per la personalizzazione dell'esperienza (facoltativo).
Per salvare le modifiche alle informazioni del profilo, clicca sul pulsante "**Salva le modifiche**".
#### **Autenticazione con codice OTP**
Tramite questa sezione potrai generare un codice OTP per accedere velocemente al tuo account, viene richiesto se viene effettuato l'accesso su un dispositivo VR.
Potrai generare il codice premendo sul tato "Genera codice".
#### Eliminazione account
Per eliminare il tuo account premi sul tasto rosso  Elimina.
Se non ricordi la password di un Agente segreto, [contatta il team di AIsuru](../risorse-aggiuntive/link-utili-e-supporto.md) per procedere alla cancellazione. Una volta rimossi tutti i Agente segreti, potrai procedere con l'eliminazione dell'account
{% hint style="danger" %}
**L'eliminazione dell'account è un'operazione irreversibile** che comporta la perdita di tutti i dati, inclusi Agenti e contenuti.
{% endhint %}
### Avatar
All'interno della scheda "Avatar" puoi:
* **Visualizzare la tua immagine profilo** corrente;
* Modificare l'immagine attraverso il pulsante .svg){kind=icon}
**Modifica**;
* Rimuovere l'immagine con 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 nessuna;
* Numero minimo di messaggi prima della notifica (1, 3, 5, 10).
Premi su "Salva" per salvare le modifiche: d'ora in poi **queste preferenze saranno applicate automaticamente ai nuovi Agenti che creerai**. Puoi anche scegliere di applicare queste impostazioni a tutti gli Agenti esistenti di cui sei proprietario attivando l'opzione "Applica a tutti gli agenti".
In base alle impostazioni scelte, potresti ricevere mail periodiche dal tuo Agente con un riassunto delle domande fatte al tuo Agente e un file di testo contenente le conversazioni tenute con gli utenti.
# 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 vari 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**](come-istruire-un-agente-panoramica-dei-metodi.md) usando diversi metodi;
* **Come utilizzare il** [**dizionario**](dizionario.md) per migliorare la comprensione dell'Agente;
* Come sfruttare le **funzionalità avanzate**, come gli [snippet di codice](istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md), [l'inserimento di codice HTML nei messaggi](istruzione-sezione-avanzata/html-messaggi.md) e la [personalizzazione delle risposte in base a ruoli, date e luoghi specifici](istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente.md).
# Come istruire un Agente: panoramica dei metodi
Istruire il tuo Agente è fondamentale per garantire risposte accurate e pertinenti. AIsuru mette a disposizione diversi strumenti per arricchire la base di conoscenza del tuo assistente, adattandosi alle tue esigenze specifiche:
* [**Istruiscimi**](istruiscimi-insegna-nuove-informazioni-allagente-chiacchierando.md) -> è una sezione in cui puoi istruire la tua IA semplicemente conversando;
* [**Contenuti**](contenuti/) -> insegna all'IA come deve rispondere a domande specifiche o su certi temi.
* [**Importazione di documenti**](importazione-di-documenti/) -> insegna conoscenza specifica al tuo Agente importando documenti testuali;
Vediamo questi metodi nel dettaglio!
# Istruiscimi: insegna nuove informazioni all'Agente chiacchierando
"Istruiscimi" è una potente funzionalità di AIsuru che semplifica l'istruzione del tuo Agente: potrai insegnargli ciò che vuoi con una conversazione naturale.
Questo metodo intuitivo ti consente di [creare contenuti](contenuti/creazione-manuale-dei-contenuti.md) semplicemente chiacchierando con l'IA, rendendo il processo di apprendimento rapido ed efficace.
### Come accedere alla sezione Istruiscimi
Per iniziare a utilizzare questa funzione:
1. Accedi al **pannello di gestione del tuo Agente**;
2. Seleziona 
**Istruiscimi** nella barra laterale;
3. **Inizia a conversare con l'Agente** come se stessi insegnando a un nuovo collega.
Il sistema analizzerà automaticamente la conversazione, creando nuovi contenuti basati sulle informazioni che fornisci.
### Best practice
Per ottenere i migliori risultati:
1. **Sii chiaro e conciso** nelle spiegazioni;
2. Se vuoi "forzare l'apprendimento", **chiedi di aggiungere uno specifico elemento ai contenuti**.
### Considerazioni importanti
Quando utilizzi Istruiscimi, tieni presente:
* La **coerenza** delle informazioni fornite in sessioni diverse è fondamentale;
* È consigliabile **verificare i contenuti creati** automaticamente per garantire la massima accuratezza;
* Per informazioni molto tecniche o strutturate, potrebbe essere più efficace utilizzare l'importazione diretta di documenti.
# Contenuti
**I contenuti sono il cuore del tuo Agente** su AIsuru. Questa sezione ti guiderà attraverso il processo di creazione, gestione e ottimizzazione dei contenuti per garantire che il tuo assistente virtuale fornisca risposte accurate, pertinenti e personalizzate.
In questa sezione, esploreremo:
1. [**Creazione manuale dei contenuti**](creazione-manuale-dei-contenuti.md): come strutturare e inserire le informazioni di base per il tuo assistente.
2. [**Validazione e correzione dei contenuti**](validazione-e-correzione-dei-contenuti.md): tecniche per garantire l'accuratezza e la coerenza delle informazioni fornite.
3. [**Modifica e aggiornamento dei contenuti**](modifica-e-aggiornamento-dei-contenuti.md): come mantenere i tuoi contenuti sempre aggiornati e rilevanti.
Che tu stia costruendo un assistente per il servizio clienti, un tutor virtuale o un compagno di conversazione, questa guida ti fornirà le competenze necessarie per creare contenuti di qualità che arricchiranno l'esperienza dei tuoi utenti.
Preparati a dare vita al tuo assistente AI con contenuti coinvolgenti e informativi! 🧠💬
# Cosa sono i contenuti e perché sono importanti
AIsuru ti permette di arricchire la base di conoscenza del tuo Agente con informazioni precise e personalizzate attraverso i contenuti. Questa funzionalità è essenziale per costruire un'IA conversazionale veramente su misura per le tue esigenze.
### Cosa sono i contenuti?
I "contenuti" sono **coppie di domande e risposte che l'Agente sfrutta per rispondere all'utente**. Avere più contenuti aumenta l'accuratezza e la precisione del tuo Agente.
### Perché sono così importanti?
Quando un utente fa una domanda al tuo Agente, questo sfrutterà tutti gli strumenti in suo possesso per rispondere alla domanda:
1. **Prima di tutto i contenuti**: se la domanda dell'utente è molto simile ad una domanda già presente nei contenuti, allora AIsuru risponderà con la risposta che già è salvata all'interno dei contenuti;
2. **Se AIsuru, però, non trova un contenuto che possa rispondere, passerà i contenuti più rilevanti all'IA generativa**, che risponderà sulla base di: [istruzioni](../../ai-generativa/prompt-engineering/), [contenuti](./) rilevanti e [funzioni](../../avanzate/integrazioni/funzioni/)[ (avanzato)](../../avanzate/integrazioni/funzioni/).
-> Creare e mantenere i contenuti è fondamentale per **aumentare la qualità delle risposte** del tuo Agente.
### Soglia di confidenza per i contenuti
La **soglia di confidenza** è un parametro che determina quanto l'Agente deve 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 parzialmente simili alla domanda dell'utente
* **Soglia alta**: l'Agente risponderà solo quando è molto sicuro che il contenuto sia pertinente alla richiesta
**Quando modificarla:**
* **Aumenta la soglia** se noti che l'Agente fornisce risposte poco pertinenti o sbagliate
* **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 seleziona il livello desiderato tra: Molto bassa, Bassa, Normale, Alta, Molto alta
{% hint style="info" %}
**ATTENZIONE**:\
Modificare la soglia di confidenza può influenzare significativamente la qualità delle risposte. Si consiglia di testare accuratamente l'Agente dopo ogni modifica e di procedere gradualmente.
{% endhint %}
# Creazione manuale dei contenuti
Ora che abbiamo visto cosa sono i contenuti e perché sono utili, vediamo come possiamo crearli. Per cominciare, andiamo a vedere la struttura di un contenuto, che campi ha e a cosa servono.
### Struttura di un contenuto
Un contenuto in AIsuru è organizzato in sezioni chiaramente identificabili nell'interfaccia. Non preoccuparti, nelle prossime pagine le esploreremo tutte.
* **Domanda** (testo, obbligatorio): la domanda principale che attiverà questo contenuto;
* **Varianti domanda** (testo multiplo): altre formulazioni della stessa domanda per migliorare il riconoscimento;
* **Risposte** (testo, obbligatorio): risposta principale e eventuali risposte alternative;
* **Assegnato a** (menu a tendina): controlla chi può vedere il contenuto ("Pubblico" o ruoli specifici);
* **Domanda conclusiva** (checkbox): evita domande di follow-up dopo la risposta;
* **Non casuale** (checkbox): esclude la domanda dai suggerimenti durante l'inattività;
* **Domanda di aiuto** (checkbox): il contenuto viene usato come supporto in caso di difficoltà;
* **Luogo e data** (pulsanti): limita la visibilità per area geografica o periodo temporale;
* **Media** (area upload): spazio per allegare immagini, video o PDF;
* **Link** (area inserimento): aggiunge URL esterni alla risposta;
* **Avanzate** (sezioni espandibili): suggerimenti, tag, contesto, snippet di codice, timeout e integrazione DCM.
### Come creare un contenuto semplice
1. Accedi al pannello di gestione del tuo Agente;
2. Premi su 
**Contenuti** nella barra laterale**;**
3. Clicca sul tasto 
**Nuovo contenuto**;
4. Compila i campi richiesti:
1. **Domanda** -> inserisci la domanda a cui l'Agente dovrà rispondere;
2. **Risposta** -> inserisci la risposta che l'Agente dovrà dare (fornisci tutte le informazioni necessarie).
✅ Fine! Premi sul tasto "Conferma" in basso a destra per salvare il tuo contenuto.
### Altre impostazioni
Ci sono altre impostazioni che potrebbero tornarti utili in diversi scenari. Vediamole!
#### Varianti di domanda
In questa sezione, che trovi sotto la domanda, puoi aggiungere delle varianti di domanda, ovvero:
* **Altre formulazioni della stessa domanda** -> "come si chiama il cane?" come domanda e "qual è il nome del cane?" come variante;
* **Altre domande che hanno la stessa risposta** -> "Dove devo andare per rifare la carta di identità?" e "Dove devo andare per rifare la carta di identità a Roma?" come variante di domanda.
{% hint style="info" %}
Le varianti di domanda servono ad **aiutare AIsuru a trovare più facilmente il contenuto più rilevante** per rispondere.
{% endhint %}
Non ti vengono in mente varianti di domanda? Lasciati aiutare da AIsuru: premi sul tasto  **Suggerisci varianti**: AIsuru aggiungerà varianti di domanda sulla base della risposta del contenuto (che deve essere presente).
#### Altre risposte
In questa sezione, che trovi subito sotto la "Risposta", puoi aggiungere delle risposte alternative per una stessa domanda.
Questa funzionalità ti permette di avere delle "varianti di risposta" per ogni domanda. Facciamo un esempio:
* Domanda: "Qual è la capitale dell'Italia?";
* Risposta: "Roma";
* Altra risposta: "La capitale dell'Italia è Roma";
* Altra risposta: "La capitale è Roma".
Se un utente chiede al tuo Agente "Qual è la capitale dell'Italia" potrà ricevere una tra le seguenti risposte: "Roma", "La capitale dell'Italia è Roma" o "La capitale è Roma".
{% hint style="info" %}
Aggiungi altre risposte se sfrutti poco l'IA generativa ma vuoi comunque r**idurre la ripetitività e aumentare la naturalezza delle interazioni** del tuo Agente.
{% endhint %}
Come per le varianti di domanda, anche per le altre risposte puoi lasciarti suggerire dall'IA: in questo caso, premendo sul tasto  **Suggerisci risposta**, AIsuru genererà una risposta sulla base della domanda (che dovrà essere presente).
#### Media e link
Puoi aggiungere media e link ai tuoi contenuti:
* Media -> immagini, video e documenti PDF;
* Link -> inserisci il link e personalizza il nome della pagina.
{% hint style="info" %}
I media e i link arricchiscono le risposte dell'Agente, permettendogli di mostrare immagini o fornire risorse aggiuntive durante la conversazione.
{% endhint %}
-> se un utente chiede "Qual è la capitale italiana?", AIsuru risponderà "Roma" (o una sua variante) e allegherà l'immagine che hai aggiunto alla risposta.
È possibile che il modello linguistico decida di mostrare o meno media e link quando risponde alle domande dell'utente. Puoi cambiare questo settaggio nelle [altre impostazioni dell'AI generativa](../../ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa.md).
#### Altri campi
Sotto il campo "Assegnato a", troverai tre opzioni importanti che influenzano il comportamento del contenuto:
1. **Domanda conclusiva**: quando attivata, la risposta a questa domanda non sarà seguita da ulteriori domande (come "C'è altro che vuoi sapere?"). Questa opzione è utile per contenuti che forniscono una risposta completa e non richiedono follow-up.
2. **Non casuale**: se selezionata, questa opzione impedisce che la domanda venga proposta casualmente quando l'utente rimane inattivo per troppo tempo. Questo è utile per contenuti che potrebbero non essere appropriati come suggerimenti casuali.
3. **Domanda di aiuto**: attivando questa opzione, il contenuto di questa domanda può essere utilizzato come aiuto per l'utente nel caso non riesca a formulare una domanda corretta più volte di seguito. Questo può migliorare l'esperienza utente fornendo supporto quando necessario.
{% hint style="info" %}
Se vuoi permettere al tuo Agente fare domande "casuali" agli utenti, puoi attivare l'interruttore "Suggerisci domande se l'utente resta inattivo" nella Impostazioni > Generali > Impostazioni avanzate. Per approfondire, leggi [come utilizzare il timeout](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout.md).
{% endhint %}
#### Impostazioni avanzate
Per le impostazioni più complesse puoi andare alla pagina dedicata alla [personalizzazione dei contenuti](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/): qui scoprirai come personalizzare le risposte in base al ruolo, alla data o al luogo dell'utente, come eseguire [snippet di codice](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md), e molto altro!
# Validazione e correzione dei contenuti
AIsuru ti offre un potente strumento per migliorare continuamente la conoscenza del tuo Agente attraverso la validazione e la correzione dei contenuti generati dall'IA.
### Perché è importante validare le risposte?
Validare le risposte permette al tuo Agente di avere **una base di conoscenza più ampia e ricca**: i contenuti validati entreranno a far parte della conoscenza del tuo Agente!
Aggiungere nuovi contenuti o [varianti di domanda](creazione-manuale-dei-contenuti.md#varianti-di-domanda) permette al tuo Agente di **trovare più facilmente la risposta alle domande dei tuoi utenti** migliorandone l'esperienza.
### Dove si validano le risposte?
1. Accedi al pannello di gestione del tuo Agente;
2. Nella barra laterale, premi su **Contenuti**;
3. Clicca sul menu "**Generate da IA**".
### Cosa posso fare?
Nella tabella, troverai tutte le domande poste dagli utenti a cui ha risposto l'IA generativa. Qui trovi diversi pulsanti:
| Pulsante | Descrizione | Quando usarlo |
|---|---|---|
| Cerca nella conversazione | Apre la conversazione in cui è stata posta la domanda | Per capire meglio in che contesto è stata fatta una certa domanda |
| Conferma | Validerà la domanda e la risposta fornita dall'IA generativa | Se tutte le informazioni sono corrette: domanda, risposta, argomenti necessari e assegnazione ad un ruolo specifico |
| Aggiungi come variante di domanda | Aggiunge la domanda di un utente come variante di domanda di un contenuto già esistente | Se già hai un contenuto che risponde alla domanda dell'utente, ma l'Agente ha risposto male |
| Modifica | Apre una scheda da cui potrai modificare il contenuto al 100% prima di validarlo | Se vuoi modificare la domanda, la risposta o aggiungere personalizzazioni varie al contenuto prima di validarlo |
| Elimina | Cancella il contenuto dalla tabella | Quando non c'è una risposta corretta ad una specifica domanda o quando la domanda è poco utile |
**Contenuti** (nella barra laterale);
3. Digita le parole chiave nella **barra di ricerca** che trovi in alto nella pagina dei contenuti;
4. (Opzionale) premi sul pulsante 
**Filtri** per accedere a **opzioni di filtro avanzate**: i filtri presenti servono a cercare i contenuti a cui puoi accedere con:
1. [Contesti](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md) richiesti;
2. Contesti impostati;
3. [Una data specifica](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente.md);
4. Tag;
5. Ruoli.
Tutti i contenuti sono organizzati in una tabella che puoi riordinare come preferisci - ti basta cliccare sul titolo della colonna che ti interessa.
Le colonne mostrano:
* **Domanda / Titolo**: la domanda principale che attiva questo contenuto;
* **Occorrenze**: quante volte l'Agente ha usato questo contenuto per rispondere agli utenti (non tiene conto delle risposte generate da IA);
* **Risposta**: cosa risponderà l'Agente quando riconosce questa domanda;
* **Proprietà**: una o più icone ti informeranno se il tuo contenuto è conclusivo o non casuale, e se ha media, link o testi preformattati;
* **Creato il**: quando è stato creato il contenuto. Se clicchi sull'icona 
vicino alla data, potrai vedere:
* Chi ha creato il contenuto e quando;
* Se qualcuno lo ha modificato, chi è stato e quando l'ha fatto.
* **Azioni**: i pulsanti per modificare, duplicare o eliminare il contenuto.
In basso a destra, troverai anche un selettore utile a decidere quanti contenuti vuoi vedere in ogni pagina (di default è 10).
{% hint style="info" %}
Se i contenuti sono stati [importati da un documento](../importazione-di-documenti/) vedrai una colonna aggiuntiva "[**Tag**](../importazione-di-documenti/importare-documenti-testuali.md#tag)".
{% endhint %}
### Modifica dei contenuti
Per modificare un contenuto esistente:
1. Nella tabella dei contenuti, **individua il contenuto che desideri modificare**;
2. Clicca sul **tasto di** **modifica** (colonna "Azioni" a destra), in corrispondenza del tuo contenuto;
3. Si aprirà una scheda di modifica identica a quella di creazione dei contenuti; qui potrai modificare tutti i campi presenti: domanda, varianti di domanda, risposta, altre risposte, ecc;
4. Dopo aver apportato le modifiche desiderate, clicca su "**Conferma**" in basso a destra per salvare.
Ricorda che puoi utilizzare il tasto "Espandi" nelle risposte per visualizzare il testo completo prima di decidere se modificare un contenuto.
### Duplicazione dei contenuti
Per duplicare un contenuto, utilizza l'apposito tasto 
nella colonna "Azioni".
### Eliminazione dei contenuti
Per eliminare un singolo contenuto, clicca sull'icona del **cestino rosso**  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)**" con il numero di elementi selezionati -> **premici sopra per eliminare i contenuti selezionati.**
### Quanti contenuti dovrebbe avere il tuo Agente?
Definire un numero di contenuti ideale è molto complesso e varia in base a molti fattori. Un Agente potrebbe concentrarsi più sui contenuti, sulle istruzioni o sulle funzioni per rispondere alle domande dell'utente. In generale, consigliamo agli utenti meno esperti di tenere il numero di contenuti inferiore a 10.000.
### Importazione / Esportazione (per utenti avanzati)
Se devi gestire grandi volumi di contenuti:
1. Accedi alla sezione 
**Import / Export** dalla barra laterale;
2. Segui le istruzioni relative al [backup dell'Agente](../../avanzate/backup-trasferimento-e-cancellazione-di-un-agente.md) per sapere come importare / esportare file CSV.
{% hint style="danger" %}
L'utilizzo corretto delle funzioni di importazione/esportazione richiede una buona 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 quando 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 della comunicazione.
#### 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 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 frequenti.
**Assistenza dell'IA generativa**: Se non trova una corrispondenza perfetta, seleziona i contenuti più simili e li passa all'IA generativa, che formula una risposta personalizzata utilizzando le informazioni più pertinenti.
### Tecnologia NLP proprietaria
Questo processo è alimentato dal **Natural Language Processing (NLP) proprietario di AIsuru**, che offre:
* **Comprensione semantica**: Va oltre la semplice corrispondenza di parole chiave, comprendendo il significato reale delle domande
* **Flessibilità linguistica**: Riconosce domande formulate in modi diversi ma con lo stesso significato
* **Supporto multilingue**: Funziona efficacemente in diverse lingue
* **Apprendimento continuo**: Migliora costantemente la precisione della ricerca
### Vantaggi per i tuoi utenti
Questo sistema avanzato garantisce:
* **Risposte precise**: Trova sempre l'informazione più pertinente
* **Esperienza naturale**: Gli utenti possono porre domande con le loro parole
* **Velocità di risposta**: Processo ottimizzato per prestazioni rapide
* **Coerenza**: Mantiene la qualità delle risposte anche con volumi elevati di contenuti
### Consigli per ottimizzare i contenuti
Per sfruttare al meglio questo sistema:
1. **Varia le domande**: Crea diverse varianti per lo stesso argomento
2. **Usa linguaggio naturale**: Scrivi come parlano realmente i tuoi utenti
3. **Copri sinonimi**: Includi termini alternativi per gli stessi concetti
4. **Testa regolarmente**: Verifica che le risposte siano pertinenti nelle conversazioni reali
Il sistema di ricerca semantica di AIsuru rappresenta il cuore tecnologico che rende i tuoi Agenti veramente intelligenti e utili per gli utenti.
# Importazione di documenti
L'importazione di documenti in AIsuru è un processo fondamentale per arricchire la conoscenza del tuo assistente virtuale. Questa funzionalità ti permette di trasformare rapidamente documenti esistenti in una base di conoscenza interattiva e interrogabile.
In questa sezione, esploreremo:
* Come [importare efficacemente documenti testuali](importare-documenti-testuali.md) in vari formati;
* [Strategie per gestire le immagini](gestione-delle-immagini-nei-documenti.md) presenti nei documenti.
Che tu stia creando un assistente per il supporto tecnico, un tool 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 costruire una base di conoscenza robusta. Continua a leggere per scoprire come trasformare i tuoi documenti in una risorsa dinamica e interattiva per il tuo assistente IA! 📚🤖
# 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. Questo processo trasforma i tuoi documenti in una serie di domande e risposte, creando una base di conoscenza interattiva e interrogabile.
Vediamo come funziona nel dettaglio!
### Il processo di importazione
1. **Caricamento del documento**: carichi il tuo documento nella sezione Import / Export del tuo Agente;
2. **Analisi e suddivisione**: AIsuru analizza il contenuto del documento e lo divide in paragrafi distinti;
3. **Generazione di domande e risposte** ([contenuti](../contenuti/)): per ogni paragrafo, AIsuru sfrutta l'IA generativa per generare una o più coppie di domande e risposte. Il numero di contenuti varia in base al documento e alla [granularità impostata](importare-documenti-testuali.md). I contenuti vengono creati nella lingua dell'Agente, cioè quella impostata in fase di creazione dell'Agente.
### Vantaggi dell'importazione di documenti
* **Risparmio di tempo**: trasformi rapidamente grandi quantità di informazioni in conoscenza utilizzabile dal tuo Agente;
* **Coerenza**: le risposte generate sono basate direttamente sui tuoi documenti, garantendo accuratezza e coerenza;
* **Flessibilità**: puoi importare diversi tipi di documenti per coprire una vasta gamma di argomenti.
### Limitazioni da considerare
Mentre l'importazione di documenti è uno strumento potente, è importante essere consapevoli di alcune limitazioni:
* **Gestione delle immagini e dei video**: al momento, AIsuru non è in grado di interpretare o elaborare le immagini e i video contenuti nei documenti; l'importazione si concentra esclusivamente sul testo;
* **Tipi di file supportati**: AIsuru supporta principalmente l'importazione di file testuali più o meno semplici. Altri formati (ad esempio, JSON) potrebbero richiedere un approccio diverso come l'utilizzo di [funzioni](../../avanzate/integrazioni/funzioni/) o [MCP](../../avanzate/integrazioni/model-context-protocol-mcp-su-aisuru/mcp-cosa-sono-e-come-si-utilizzano.md);
* **PDF con contenuto non selezionabile**: se carichi un PDF che contiene principalmente immagini o testo non selezionabile (come scansioni di documenti), AIsuru non sarà in grado di estrarre e 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. Combinandola con altre tecniche di insegnamento come la conversazione diretta e la creazione manuale di contenuti, potrai creare un assistente IA veramente completo e informato.
# Importare documenti testuali
AIsuru permette 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, creando domande e risposte pertinenti a partire dal contenuto dei tuoi documenti.
### Documenti supportati
I **formati supportati** sono: PDF (.pdf), file di testo (.txt); Microsoft Word (.doc, .docx), Apple Pages (.pages). OpenDocument (.odt), Rich Text Format (.rtf), HTML (.html).
**AIsuru supporta la tecnologia OCR**, ma per un risultato ottimale consigliamo di caricare documenti con testo già selezionabile. L'OCR funziona meglio su documenti ben scansionati e con testo chiaro, mentre potrebbe avere difficoltà con documenti di bassa qualità o con formattazioni complesse.
### Importazione di funzionalità da altri Agenti
Oltre all'importazione di documenti, AIsuru ti permette di importare funzionalità complete da altri tuoi Agenti. Attraverso il tab "Importa Funzioni e Intenti" puoi:
* Copiare [**funzioni avanzate**](../../avanzate/integrazioni/funzioni/funzioni-avanzate/) con tutte le loro configurazioni;
* Importare [**intenti dinamici**](../../avanzate/integrazioni/intenti-dinamici/) e i relativi **slot;**
* Trasferire il [**dizionario**](../dizionario.md) **personalizzato;**
Questa funzionalità è particolarmente utile quando vuoi replicare configurazioni complesse tra Agenti simili o creare backup delle tue implementazioni. Per maggiori dettagli, consulta la guida Copia gli intenti dinamici, gli slot e le funzioni da un altro Agente.
### Accesso alla sezione di import
1. **Accedi al pannello di gestione** del tuo Agente;
2. Seleziona **Import / Export** nella barra laterale;
3. Premi sul tasto "**Choose file**" e scegli il documento da importare.
4. Una volta caricato il documento, scorri in basso per vedere un'anteprima del testo estratto e modificare le diverse impostazioni dell'import.
Troverai due sezioni:
1. Opzioni di importazione;
2. Gestione contesto.
### Opzioni di importazione
#### Scelta dei contenuti da importare
Dopo aver caricato il documento potrai selezionare l'opzione:
* **importa solo i nuovi contenuti**: se vengono generate domande simili a quelle già presenti, AIsuru non le importerà;
* **importa tutto**: importa l'intero contenuto del documento, anche se sono già presenti domande simili.
#### Personalizzazione dei contenuti
Puoi scegliere, mettendo la spunta alla casella, se impostare tutti i contenuti come:
* **Conclusivi**: l'AI non chiederà ulteriori informazioni dopo aver risposto;
* **Non casuali**: le domande non verranno suggerite casualmente in caso di inattività dell'utente (per saperne di più, vai alla sezione dedicata al [timeout](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout.md)).
Inoltre, potrai **aggiungere un link a tutte le domande importate** (ad esempio, al file originale, per avere sempre la fonte consultabile).
#### **Altre impostazioni**
Nelle opzioni di importazione, puoi anche modificare la granularità: **questa impostazione permette di generare più o meno domande e risposte per ogni paragrafo**. Puoi impostare una granularità:
* **Bassa:** verranno importati pochi contenuti per paragrafo e ci metterà meno tempo, utile per i testi discorsivi;
* **Media:** l'opzione consigliata, creerà un numero medio di contenuti;
* **Alta:** verranno creati molti contenuti per paragrafo, ci metterà più tempo ma è molto utile per testi densi di informazioni con tanti concetti.
{% hint style="info" %}
Per un risultato migliore, **ti consigliamo di impostare la granularità su high**.
{% endhint %}
Infine, vi sono le **istruzioni per la generazione delle domande**. Questo spazio serve a **guidare l'IA generativa nella creazione di domande**: è cruciale ottenere domande e risposte pertinenti e di qualità.
Nelle istruzioni devi fornire:
* un breve **contesto sul documento**: di cosa parla? per cosa è utile?
* un breve **contesto sull'utente finale**: chi è? Che tipo di domande fa? Con che linguaggio?
* alcune **regole e istruzioni chiare e concise** per generare le domande.
Esempio:
```
Questo documento descrive le politiche aziendali per la sicurezza sul lavoro.
Istruzioni per la generazione delle domande:
- Crea domande che coprano i principali argomenti di sicurezza menzionati nel documento;
- Includi domande su procedure specifiche, equipaggiamento di sicurezza e responsabilità dei dipendenti;
- Genera domande che verifichino la comprensione delle conseguenze del non rispetto delle norme di sicurezza;
- Crea alcune domande di scenario che richiedano l'applicazione delle politiche a situazioni reali.
```
#### Allega fonte (opzionale)
Seleziona questa opzione se desideri includere l'estratto del testo originale come allegato per ogni coppia domanda-risposta generata.
### Gestione contesto
All'interno della sezione di gestione del contesto puoi aggiungere: tag, argomenti impostati e argomenti necessari.
#### Tag
I tag sono come categorie che puoi attribuire ai tuoi contenuti. Se imposti un tag in fase di import di un documento, tutte le domande e risposte generate dal tuo documento saranno taggate con le categorie impostate.
Di default, viene aggiunto un tag che identifica il tuo import: in questo modo, avrai sempre traccia dei contenuti creati dal documento importato.
Puoi rimuovere i contenuti premendo sul cestino rosso  accanto a ciascun tag o puoi premere su "Aggiungi" per aggiungerne uno.
#### Imposta argomenti
Aggiungi il [contesto da impostare](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md#contesto-impostato-e-contesto-necessario) quando l'utente fa specifiche domande.
#### Argomenti necessari
L'utente non avrà accesso alle domande e risposte create con l'import del documento se prima non avrà impostato un certo argomento.
#### **Assegnato a**
I contenuti che verranno estratti dal documento possono essere assegnati ad un [**ruolo specifico**](../istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici.md) o puoi assegnarli al **pubblico.**
### Lancio dell'importazione e Storico import
Una volta settate tutte le impostazioni, puoi lanciare l'importazione cliccando sul tasto **Importa** in basso a sinistra.
Dopo aver fatto partire l'import, avrai accesso ad una nuova scheda nella sezione Import / Export: 
**Storico import**.
Da questa sezione potrai vedere:
* **L'andamento del processo** di importazione che hai lanciato;
* **Gli import passati**.
Per ogni import, potrai vedere:
* Titolo del file;
* Data di inizio e fine del processo;
* Numero di domande importate;
* Se premi sul menu "dati dell'import e configurazioni" vedrai anche:
* Dimensione file;
* Nome file;
* Se i contenuti sono impostati come conclusivi o 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 arricchire la conoscenza del tuo Agente. Sfrutta al massimo questa funzionalità per creare un assistente virtuale informato e capace di fornire risposte accurate e pertinenti ai tuoi utenti.
# Gestione delle immagini nei documenti
Mentre AIsuru non supporta l'importazione diretta di immagini dai documenti, esiste un metodo per integrare le immagini nelle risposte del tuo Agente. Questa funzionalità ti permette di arricchire le interazioni con contenuti visivi, migliorando l'esperienza dell'utente.
### Come integrare le risposte con le immagini
Per includere immagini nelle risposte del tuo Agente in due modi diversi:
1. (Consigliato) **Aggiungi le immagini ai tuoi contenuti**: seleziona i contenuti rilevanti per una certa immagine, modificali e aggiungi l'immagine a ciascun contenuto;
2. (Avanzato) Crea un contenuto per ogni immagine:
1. Domanda -> inserisci un titolo descrittivo per l'immagine;
2. Varianti di domanda -> inserisci le domande per cui vuoi mostrare l'immagine;
3. Risposta -> inserisci una descrizione completa dell'immagine;
4. Media -> carica la tua immagine;
5. Assicurati che la casella "[Disabilita l'estrazione automatica delle immagine dai contenuti](../../ai-generativa/ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa.md#estrazione-automatica-dei-media)" sia disabilitata (Impostazioni del tuo Agente > IA) -> sarà compito del modello linguistico identificare quale immagine mostrare sulla base della descrizione fornita (cioè, della risposta del tuo contenuto).
{% hint style="danger" %}
Se il tuo Agente supera le 150 immagini ti sconsigliamo di utilizzare il secondo metodo.
{% endhint %}
### Consigli per l'uso efficace
* Usa **immagini rilevanti e di alta qualità**;
* **Fornisci descrizioni dettagliate e accurate** per ogni immagine;
* **Testa regolarmente le risposte** dell'Agente per assicurarti che le immagini vengano utilizzate appropriatamente e modifica i contenuti se necessario.
L'integrazione delle immagini nelle risposte del tuo Agente può significativamente migliorare la qualità delle interazioni. Sebbene richieda un po' più di lavoro manuale, i benefici in termini di chiarezza e coinvolgimento dell'utente possono essere sostanziali. Sperimenta con questa funzionalità per trovare il giusto equilibrio tra contenuti testuali e visivi nel tuo Agente AIsuru.
# Dizionario
Il dizionario personalizzato di AIsuru è uno strumento potente che migliora la comprensione del linguaggio del tuo Agente. Questa funzionalità ti permette di definire termini specifici, acronimi e frasi uniche per il tuo Agente.
### Accesso al dizionario
Per accedere al dizionario personalizzato:
1. Accedi al **pannello di gestione** del tuo Agente;
2. Nella barra laterale, clicca su 
**Dizionario**.
### Gestione del dizionario
#### Come aggiungere nuove parole
1. Dalla sezione principale ("Dizionario custom"), premi sul pulsante 
**Nuova parola**;
2. Compila i campi:
1. **Parola** -> inserisci la parola da definire;
2. **Definizione** -> puoi decidere se fornire un sinonimo, una definizione ricorsiva (parola\_da\_definire = parola\_nota - parte\_da\_rimuovere + parte\_da\_aggiungere, ad esempio crederei = farei - fare + credere) o una normale definizione;
3. Clicca su "Conferma" per aggiungere la parola al dizionario.
#### Modificare le voci esistenti
1. Trova la parola che desideri modificare nell'elenco;
2. Clicca sull'icona di **modifica** nella parte destra della tabella;
3. Aggiorna la definizione come necessario;
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 pallino con un numero sopra che indica quante parole mancano di una definizione;
2. Esamina l'elenco delle parole identificate da AIsuru;
3. Per ogni parola rilevante:
1. Premi sul tasto + se vuoi vedere dove è stata usata;
2. Clicca su **Definisci** per definirla -> compila i campi e premi sul tasto Conferma.
### Importazione da un altro Agente
Puoi importare il dizionario da un altro Agente in due modi:
**Metodo 1 - Importazione solo dizionario:**
1. Nella sezione Dizionario, seleziona "**Importa Dizionario**" dal menu;
2. Scegli l'Agente sorgente dal menu a tendina;
3. Clicca su "Import" per trasferire l'intero dizionario.
**Metodo 2 - Importazione completa (NUOVO):**
1. Vai alla sezione "Import/Export";
2. Seleziona il tab "**Importa Funzioni e Intenti**";
3. Scegli l'Agente sorgente e seleziona "Dizionario" tra le opzioni;
4. Puoi importare contemporaneamente anche funzioni, intenti e slot.
{% hint style="info" %}
Questa funzione è particolarmente utile per mantenere la coerenza terminologica tra diversi Agenti.
{% endhint %}
### Vantaggi del dizionario
L'utilizzo del dizionario personalizzato di AIsuru offre numerosi benefici:
* **Migliora la precisione** delle risposte dell'Agente;
* Garantisce una **comprensione uniforme dei termini specifici** dell'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 è **prioritizzare correttamente i contenuti**.
{% endhint %}
Inizia subito a personalizzare il tuo dizionario per sfruttare al massimo le potenzialità del tuo Agente AIsuru!
# Istruzione: sezione avanzata
Le funzionalità avanzate di AIsuru ti permettono di personalizzare e potenziare il tuo Agente, trasformandolo in uno strumento sofisticato e altamente adattabile alle tue esigenze specifiche. Questa sezione ti guiderà attraverso le caratteristiche più avanzate per ottimizzare l'interazione e l'efficacia del tuo assistente virtuale.
In questa sezione, esploreremo:
* [**Personalizzazione dei contenuti**](personalizzazione-dei-contenuti/): come limitare la visibilità di alcuni contenuti solo a specifici utenti, come gestire i [suggerimenti](personalizzazione-dei-contenuti/gestione-dei-suggerimenti.md), i [contesti](personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md), i [testi preformattati](personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md) e il [timeout](personalizzazione-dei-contenuti/utilizzo-del-timeout.md);
* [**Importazione avanzata di documenti**](importazione-avanzata-di-documenti/): come creare una gerarchia dei documenti caricati e come caricare un documenti non supportato;
* [**Messaggio di benvenuto**](messaggio-di-benvenuto.md): come impostare un messaggio di benvenuto;
* [**Risposte predefinite**](risposte-predefinite.md): come configurare risposte automatiche per scenari in cui l'IA non riesce a rispondere;
* [**Mostrare HTML dentro i messaggi**](html-messaggi.md): tecniche per arricchire visivamente le risposte del tuo Agente con elementi HTML.
Che tu stia cercando di 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 necessari per elevare le capacità del tuo assistente IA.
# Personalizzazione dei contenuti
La personalizzazione dei contenuti è una funzionalità chiave che ti permette di creare esperienze su misura con il tuo Agente AIsuru. In questa sezione, esploreremo diversi modi per personalizzare come il tuo Agente interagisce con gli utenti.
In questa sezione, troverai:
1. [**Come attribuire contenuti a Ruoli specifici**: ](come-attribuire-contenuti-a-ruoli-specifici.md)scopri come mostrare contenuti diversi a categorie specifiche di utenti
2. [**Personalizzare le risposte in base a data e luogo dell'utente**:](personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente.md) impara a creare contenuti che sono disponibili solo in determinati luoghi o periodi di tempo
3. [**Gestione dei suggerimenti**: ](gestione-dei-suggerimenti.md)esplora come guidare la conversazione con opzioni predefinite
4. [**Contesto: argomenti ed etichette**: ](contesto-argomenti-ed-etichette.md)approfondisci come gestire il contesto della conversazione attraverso argomenti e etichette
5. [**Gestione dei testi preformattati**: ](gestione-dei-testi-preformattati-snippet-di-codice.md)scopri come integrare ed eseguire snippet di codice per creare interazioni avanzate
6. [**Utilizzo del timeout**:](utilizzo-del-timeout.md) impara come gestire i periodi di inattività degli utenti in modo efficace
Queste funzionalità ti permetteranno di creare un'esperienza personalizzata e contestuale, adattando il comportamento del tuo Agente alle diverse esigenze e situazioni.
# Come attribuire contenuti a Ruoli specifici
La personalizzazione dei contenuti basata sui Ruoli è una delle funzionalità più potenti di AIsuru. Ti permette di creare esperienze su misura per diversi tipi di utenti, garantendo che ciascuno 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 versioni specializzate del tuo Agente per ogni gruppo di utenti.
Per esempio, puoi far sì che il tuo Agente:
* Mostri 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](come-attribuire-contenuti-a-ruoli-specifici.md#cosa-sono-i-ruoli-in-aisuru), potrai attribuirle i 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 desiderata dal menu a tendina (di default, i contenuti sono visibili a tutti con la voce "Pubblico");
4. Salva il contenuto.
💡 Da questo momento, solo gli utenti associati a quel Ruolo potranno vedere quel contenuto specifico.
### Cosa succede agli altri utenti?
Quando un utente senza i permessi necessari fa una domanda relativa a un contenuto riservato, il Agente:
1. Cercherà prima contenuti pubblici simili a cui l'utente ha accesso;
2. Se non trova alternative pertinenti, utilizzerà l'IA generativa per fornire una risposta (passando solamente i contenuti a cui l'utente ha accesso);
3. Non saprà di non avere accesso a specifici contenuti, di conseguenza n**on potrà mai rivelare nulla, nemmeno se tratto in inganno**!
### Suggerimenti per l'uso efficace
* Crea Ruoli per **gruppi di utenti con esigenze informative distintive**;
* Usa **nomi chiari e descrittivi** per facilitare la gestione futura;
* **Rivedi periodicamente le assegnazioni** dei contenuti per mantenerle aggiornate;
* **Testa le risposte** dell'Agente con diversi ruoli per verificare che l'esperienza sia ottimale per tutti.
# Personalizzare le risposte in base a data e luogo dell'utente
AIsuru ti permette di rendere il tuo Agente ancora più intelligente e contestuale, offrendo la possibilità di personalizzare le risposte in base alla data e al luogo dell'utente. Questa funzionalità è particolarmente utile per creare esperienze interattive legate a eventi specifici o luoghi particolari.
### 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 certi contenuti solo in determinati luoghi;
* Puoi rendere disponibili le risposte solo in specifiche date e orari;
* Puoi combinare entrambe le condizioni per una personalizzazione ancora più precisa.
### Impostazione del luogo
Quando crei o modifichi un contenuto, nella sezione "Luogo e data" puoi **cliccare sul campo "Luogo"** per attribuire il tuo contenuto ad un luogo specifico:
1. Inserisci il nome della località o premi su "Usa la mia posizione";
2. Regola il **livello di incertezza** secondo le tue esigenze (da 0 a 100 km);
3. Verifica l'area selezionata sulla mappa.
{% hint style="info" %}
Se vuoi **rimuovere l'attribuzione del contenuto ad un luogo**, premi su  **Elimina** al di sotto della mappa.
{% endhint %}
### Impostazione della data
Nella stessa sezione puoi definire il periodo di validità del contenuto:
1. Premi sul tasto "**Data**" nella sezione "Luogo e data" del tuo contenuto;
2. Specifica l'intervallo temporale con il calendario che si aprirà dopo aver premuto sui campi "Da" e "A"; la data scelta sarà visibile con questo formato: DD/MM/YYYY HH:mm
3. Usa  **Elimina** se vuoi 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 basati sulla 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 limitate;
* **Campagne di marketing**: contenuti legati a lanci di prodotti o iniziative speciali.
🎭 Puoi combinare data e luogo per creare esperienze ancora più mirate e contestuali.
### Suggerimenti per l'uso efficace
1. **Pianifica in anticipo** quali contenuti devono essere disponibili dove e quando;
2. **Testa regolarmente** i contenuti personalizzati per assicurarti che siano visualizzati correttamente nelle date e nei luoghi previsti.
La personalizzazione delle risposte in base a data e luogo è un potente strumento per creare un Agente IA veramente contestuale e dinamico. Sfruttalo per offrire un'esperienza utente unica e sempre rilevante, indipendentemente da dove e quando il tuo Agente viene utilizzato.
# Gestione dei suggerimenti
AIsuru ti offre la possibilità di guidare la conversazione con il tuo Agente attraverso l'uso di suggerimenti. Questa funzionalità ti permette di presentare all'utente una serie di opzioni predefinite sotto forma di pulsanti cliccabili, rendendo l'interazione più fluida e mirata.
### Come funzionano i suggerimenti
Quando aggiungi dei suggerimenti a un contenuto:
1. L'utente vedrà i suggerimenti come **pulsanti interattivi** dopo la risposta dell'Agente;
2. Cliccando su un pulsante, l'utente invia il testo del suggerimento come se lo avesse digitato;
3. L'Agente risponderà in base al contenuto corrispondente al suggerimento selezionato.
💡 Questa funzione è particolarmente utile per **guidare l'utente attraverso processi specifici** o per indirizzare la conversazione verso **argomenti predefiniti**.
### Come aggiungere suggerimenti
Per aggiungere suggerimenti a un contenuto:
1. Vai alla schermata di creazione o modifica del contenuto;
2. Cerca e apri la sezione "Avanzate: suggerimenti" nella sezione "Avanzate";
3. Clicca su 
**Aggiungi** per inserire un nuovo suggerimento;
4. Inserisci il testo che vuoi appaia sul pulsante;
5. Ripeti il processo per aggiungere più suggerimenti e salva le modifiche premendo sul tasto di conferma in basso a destra.
Per cancellare i suggerimenti, premi sul tasto rosso  accanto a ciascun suggerimento.
### Vantaggi dell'uso dei suggerimenti
* **Guida l'utente**: aiuta gli utenti a navigare attraverso opzioni predefinite;
* **Riduce gli errori**: limita le possibilità di input non previsti o mal interpretati;
* **Migliora l'esperienza utente**: rende l'interazione più fluida e intuitiva;
* **Aumenta l'efficienza**: accelera il processo di ottenimento delle informazioni desiderate.
### Esempio di flusso di conversazione
Utente: "Ho un problema con il mio computer."
Agente: "Mi dispiace sentire che hai un problema. 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
* Altro
Utente: \[Clicca 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
### Per un uso efficace dei suggerimenti
1. **Limita il numero di suggerimenti a 2-5** per non sovraccaricare l'utente;
2. Assicurati che ci siano contenuti corrispondenti per ogni suggerimento (o, comunque, che l'[AI generativa](../../../ai-generativa/) sappia 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 a una guida interattiva e efficace. Sfrutta questa funzionalità per creare esperienze conversazionali ricche e mirate, migliorando significativamente l'engagement e la soddisfazione degli utenti.
---
hidden: true
---
# Gestione dei tag
# Contesto: argomenti ed etichette
AIsuru ti permette di creare conversazioni dinamiche e contestuali attraverso l'uso del contesto. Questa funzionalità ti consente di controllare quando determinate domande sono appropriate e come l'Agente dovrebbe interpretare e rispondere alle richieste dell'utente in base al contesto della conversazione.
### Contesto: cos'è e a cosa serve
La gestione del contesto ti permette di definire in quali situazioni specifiche una domanda o una risposta hanno senso.
Il contesto dice ad AIsuru di cosa si sta parlando in un preciso momento e, quindi, è necessario per guidare al meglio la conversazione, accedendo ad alcuni [contenuti](../../contenuti/) e limitando la visibilità degli altri.
#### Argomenti ed etichette
Il contesto in AIsuru può essere gestito attraverso due tipi di elementi:
* **Argomenti** -> sono coppie nome-valore che definiscono un contesto specifico:
* Il nome identifica il tipo di contesto (ANIMALE, OGGETTO, ecc.);
* Il valore specifica il contesto attuale (CANE, SMARTPHONE, ecc.).
Esempio: ANIMALE:CANE
* **Etichette** -> sono contesti semplici:
* Il nome identifica il tema di cui si parla (es. DOMANDE\_GENERICHE);
* Le etichette sono, in realtà, argomenti che hanno "✔️" come valore nascosto.
### Contesto impostato e contesto necessario
Gli argomenti e le etichette possono essere utilizzati in due modi diversi che influenzano come l'Agente gestisce i contenuti:
* **Contesto impostato** ("Imposta argomenti" in piattaforma):
* Indica all'Agente di cosa si sta parlando in questo momento;
* Aiuta l'Agente a prioritizzare i contenuti più rilevanti per il contesto attuale;
* NON limita l'accesso ai contenuti, ma li organizza per rilevanza;
* Esempio:
* Domanda: "Parliamo di cani";
* Risposta: "Ok, parliamo di cani" \[argomento impostato: `ANIMALE:CANE`];
* Dopo questa frase, l'Agente saprà che la conversazione riguarda i cani e potrà fornire risposte più pertinenti.
* **Contesto necessario** ("argomenti necessari" in piattaforma):
* Funziona come un vero e proprio filtro che impedisce all'Agente di accedere ai contenuti finché non viene impostato un certo contesto;
* L'IA può accedere a questi contenuti SOLO quando quel specifico contesto è attivo;
* Se non imposti alcun argomento necessario, l'Agente avrà sempre accesso al tuo contenuto, a prescindere dal contesto impostato;
* Esempio:
* `ANIMALE:CANE`: la domanda è rilevante solo quando si parla di cani;
* `OGGETTO:BACCHETTA`: la domanda è appropriata solo nel contesto di una bacchetta.
La differenza chiave tra i due tipi di contesto è che:
* **Il contesto impostato aiuta l'Agente a capire meglio la conversazione** e a prioritizzare i contenuti più rilevanti;
* **Il contesto necessario impedisce del tutto l'accesso ai contenuti** finché non viene impostato quello specifico contesto.
{% hint style="info" %}
Una volta impostato un certo contesto, anche i contenuti con quel contesto necessario potranno essere passati all'IA generativa per rispondere alle domande degli utenti.
{% endhint %}
### Come gestire il contesto dei tuoi contenuti
#### Aggiungi un contesto
Se vuoi aggiungere un contesto ai tuoi contenuti:
1. Accedi ai **Contenuti** e creane uno o modificane uno esistente;
2. Vai alla sezione "Avanzate: gestione contesto";
3. Scegli se aggiungere un argomento da impostare (sezione "Argomenti impostati") o necessario (sezione "Argomenti necessari");
4. Scegli tra "Nuovo argomento" o "Nuova etichetta" in base alle tue esigenze;
5. Compila nome e valore (se presente) nella scheda che si aprirà;
6. Conferma i dati e salva le modifiche del contenuto.
💡 Puoi anche utilizzare "Suggerisci etichette" per ricevere proposte basate sul contenuto.
#### Annulla un contesto
Per annullare un contesto, aggiungi un argomento con lo stesso nome e **inserisci "-" come valore**.
Esempio: `ANIMALE:-` annullerà il contesto "ANIMALE", che non sarà più impostato e non avrà più alcun valore.
### Esempi pratici
#### Scenario: assistente per un negozio di animali
1. Domanda dell'Agente all'utente: "Che tipo di animale ti interessa?";
2. Utente: "I cani", imposta argomento: `ANIMALE:CANE`;
3. Argomento necessario: Domanda: "Quali sono le esigenze alimentari specifiche?", argomento necessario: `ANIMALE:CANE`;
4. Annullare un contesto: Domanda: "Vorrei parlare di un altro animale", imposta argomento: `ANIMALE:-`.
#### Flusso di conversazione
1. Utente: "Vorrei informazioni sugli animali domestici";
2. Agente: "Certo! Che tipo di animale ti interessa?";
3. Utente: "I cani";
4. Agente: (imposta `ANIMALE:CANE`) "Ottimo! I cani sono animali meravigliosi. Cosa vorresti sapere sui cani?";
5. Utente: "Quali sono le loro esigenze alimentari?";
6. Agente: (verifica `ANIMALE:CANE`, 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 `ANIMALE:-`) "Certamente! 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;
* Possibilità di creare percorsi di dialogo complessi e ramificati;
* Migliore gestione di argomenti multipli all'interno della stessa conversazione.
L'utilizzo efficace di contesti e variabili di contesto può trasformare il tuo Agente in un assistente veramente intelligente e contestuale. Sperimenta con queste funzionalità per creare esperienze di conversazione ricche e dinamiche che si adattano alle esigenze e agli interessi specifici dei tuoi utenti.
# Gestione dei testi preformattati (snippet di codice)
I testi preformattati sono una funzionalità avanzata di AIsuru che permette di integrare ed eseguire codice direttamente nelle conversazioni con il tuo Agente. Questa potente caratteristica 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 testi preformattati
1. Accedi ai **Contenuti** del tuo Agente e crea o modifica un contenuto;
2. Vai alla sezione "**Avanzate: testi preformattati**" e clicca su "+ Nuovo snippet";
3. Nella scheda che si apre:
1. Aggiungi un titolo allo snippet di codice;
2. Inserisci il codice;
3. Decidi se eseguire il codice in pagina attivando la casella "Inserisci in pagina ed esegui questo snippet" (presente solo per alcuni linguaggi). Questa casella ti permette di:
1. Eseguire sempre lo snippet quando l'utente fa esattamente la stessa domanda del tuo contenuto (o una abbastanza simile);
2. Far eseguire lo snippet dall'IA generativa (a discrezione del modello scelto).
{% 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 dei nomi descrittivi e spiega quando utilizzare lo snippet all'interno del prompt.
{% endhint %}
### Linguaggi supportati
Puoi scegliere tra i seguenti linguaggi per il tuo snippet:
| Linguaggio | Mostrare snippet | Eseguire snippet |
| :------------: | :--------------: | :--------------: |
| text | ✅ | ❌ |
| javascript/jsx | ✅ | ✅ |
| typescript/tsx | ✅ | ✅ |
| json | ✅ | ✅ |
| css | ✅ | ✅ |
| html/xml | ✅ | ❌ |
| bash | ✅ | ❌ |
| python | ✅ | ❌ |
| cpp/csharp | ✅ | ❌ |
| php | ✅ | ❌ |
| ruby | ✅ | ❌ |
### Esempi pratici
* Scopo: illuminare una parte della pagina web;
* Titolo: "Evidenzia la descrizione del prodotto";
* Linguaggio: JavaScript;
* Inserisci in pagina ed esegui questo snippet: checkbox attiva.
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 di conversazione:
1. Utente: "Dove trovo la descrizione del prodotto?";
2. Agente:
1. "La descrizione del prodotto si trova sotto al suo titolo, in alto a destra. Per facilitarti, ho reso la descrizione più evidente illuminandola per alcuni secondi".
2. \[Inserisce ed esegue lo snippet 'Evidenzia sezione prodotto']
### Vantaggi dell'uso dei testi preformattati
* Crea interazioni più dinamiche e contestuali;
* Migliora l'esperienza utente con esempi visivi e interattivi;
* Fornisce supporto tecnico immediato e pratico;
* Permette di personalizzare l'interfaccia utente in tempo reale;
* Facilita la dimostrazione di funzionalità del sito o dell'applicazione.
### Combinazione avanzata degli snippet
Gli snippet possono essere combinati strategicamente per creare interazioni più complesse:
#### Esempio: evidenziazione dinamica delle sezioni
Immagina di voler creare un'esperienza guidata dove l'Agente evidenzia diverse parti della pagina durante una conversazione. Puoi configurare:
1. Uno snippet CSS (tramite [domanda iniziale](../../../condivisione/condivisione-sezione-avanzata/domanda-iniziale.md))
```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. Snippet di codice JavaScript (nella stessa domanda iniziale)
```javascript
// Funzione per evidenziare la sezione prodotti
function highlightProductsSection() {
const productsSection = document.querySelector('.products-section');
if (!productsSection) return; // Guard clause
// Aggiungi l'effetto
productsSection.classList.add('highlight-pulse');
// Rimuovi l'effetto dopo 5 secondi usando requestAnimationFrame
const startTime = performance.now();
function removeHighlight(currentTime) {
if (currentTime - startTime >= 5000) {
productsSection.classList.remove('highlight-pulse');
return;
}
requestAnimationFrame(removeHighlight);
}
requestAnimationFrame(removeHighlight);
}
```
3. Snippet di codice JavaScript legato al contenuto con domanda "Dove trovo la sezione prodotti?"
```javascript
// Uso della funzione
highlightProductsSection();
```
In questo modo, quando l'utente avvia la chat:
* Viene iniettato immediatamente lo stile CSS;
* Viene definita la funzione JavaScript per evidenziare la sezione.
Quando l'utente chiederà "Dove trovo la sezione prodotti?", l'Agente scatenerà il terzo snippet - e quindi la funzione che evidenzia la sezione.
Questo approccio è particolarmente utile per:
* Tutorial guidati interattivi;
* Onboarding di nuovi utenti;
* Assistenza nella navigazione di pagine complesse;
* Presentazioni di prodotti o servizi.
### Considerazioni importanti
1. **Sicurezza**: quando usi 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à**: considera che non tutti gli utenti potrebbero vedere gli effetti visivi degli snippet, quindi fornisci sempre descrizioni testuali alternative;
4. **Prestazioni**: evita di sovraccaricare la pagina con troppi snippet eseguibili, che potrebbero rallentare l'esperienza utente.
L'utilizzo intelligente dei testi preformattati può trasformare il tuo Agente in un potente strumento di supporto interattivo. Sperimenta con diversi tipi di snippet per creare un'esperienza utente coinvolgente, informativa e personalizzata, migliorando significativamente l'interazione tra l'utente e il tuo sito web o applicazione.
# Utilizzo del timeout
La funzionalità di timeout in AIsuru ti permette di mantenere attiva e coinvolgente la conversazione con l'utente, anche durante momenti di inattività. Questa caratteristica è particolarmente utile per guidare l'utente verso nuovi argomenti o per mantenere vivo il suo interesse.
### Come funziona il timeout
Quando imposti un timeout per una domanda, AIsuru proporrà automaticamente una nuova domanda all'utente se questo rimane inattivo per un certo periodo di tempo.
{% hint style="success" %}
Il timeout viene scelto casualmente tra un valore minimo e massimo personalizzabili al fine di rendere l'**interazione più naturale e meno prevedibile**.
{% endhint %}
### Come impostare il timeout
1. Accedi ai **Contenuti** del tuo Agente e crea o modifica un contenuto;
2. Vai alla sezione "Avanzate: timeout";
3. Imposta il valore minimo e quello massimo di timeout (espresso in secondi).
Per 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 proporrà automaticamente una nuova domanda e chiederà: "Perché non mi chiedi \[domanda casuale]".
### Vantaggi dell'utilizzo del timeout
* **Mantiene la conversazione attiva**: evita lunghi periodi di silenzio che potrebbero far perdere interesse all'utente;
* **Guida l'utente**: può introdurre nuovi argomenti o suggerire nuove direzioni per la conversazione;
* **Personalizzazione**: 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.
Per questo, su AIsuru puoi:
* Lasciare attivo il **timeout per tutti i contenuti** (comportamento di default) -> l'Agente farà domande casuali all'utente;
* Lasciare attivo il **timeout per alcuni contenuti** -> l'Agente farà domande casuali (prese da un certo gruppo) all'utente;
* **Disattivare del tutto il timeout** -> l'Agente non farà più domande casuali all'utente, anche se non interagisce da diverso tempo.
#### Come attivare il timeout solo per alcuni contenuti
[Imposta i singoli contenuti come "non casuali"](../../contenuti/creazione-manuale-dei-contenuti.md#altri-campi) nella scheda di creazione e modifica dei contenuti o nelle impostazioni dell'importazione di un documento. I contenuti "non casuali" non verranno proposti all'utente.
#### Come suggerire domande se l'utente resta inattivo
1. Accedi alle 
**Impostazioni** del tuo Agente;
2. Nella sezione Generali, apri il pannello delle **Impostazioni avanzate**;
3. Attiva l'interruttore della voce **"Suggerisci domande se l'utente resta 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 fa una domanda casuale -> "Perché non mi chiedi quando è stato costruito il Colosseo?".
4. L'utente preme "Va bene" (l'Agente risponde) o "No grazie".
### Best practice
1. **Equilibrio**: imposta timeout né troppo brevi (per non risultare invadente) né troppo lunghi (per mantenere l'engagement);
2. **Contesto**: adatta i tempi di timeout al contesto della conversazione e alla complessità delle informazioni fornite;
3. **Rilevanza**: assicurati che le domande proposte 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'utilizzo 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 vivo l'interesse dell'utente e guidandolo attraverso tutte le funzionalità e informazioni che il tuo Agente può offrire.
# Importazione avanzata di documenti
In questa sezione esploreremo funzionalità avanzate di AIsuru per gestire casi d'uso più complessi nell'importazione dei documenti. In particolare, vedremo due scenari:
* [**Creare una gerarchia dei documenti**](creare-una-gerarchia-dei-documenti.md)**:** quando hai documenti con diversi livelli di importanza, questa funzionalità ti permette di organizzarli in modo strutturato e gestire le priorità durante l'importazione;
* [**Importare documenti non ufficialmente supportati**](documento-non-supportato.md): se hai bisogno di importare file in formati particolari come Excel, video o altri tipi di file non direttamente supportati, scoprirai come farlo efficacemente.
Queste funzionalità avanzate ti permetteranno di avere un controllo più granulare sul processo di importazione e di 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 sfida significativa, specialmente quando le informazioni possono sovrapporsi o potenzialmente contraddirsi.
AIsuru non supporta ufficialmente la gestione di una gerarchia fra i documenti, ma in questa guida vedremo come utilizzare gli altri strumenti che AIsuru mette a disposizione per ottenere il medesimo risultato.
### Come creare una gerarchia di documenti
#### Import dei documenti
{% tabs %}
{% tab title="Utenti intermedi" %}
1. Vai alla sezione 
**Import / Export** del tuo Agente;
2. [**Carica il documento**](../../importazione-di-documenti/importare-documenti-testuali.md#configurazione-base) e setta le diverse impostazioni;
3. Alla voce "**Istruzioni per la generazione delle domande**" aggiungi questa dicitura: 'Aggiungi "- \[nome documento]" alla fine di ogni domanda'. Ricordati di sostituire \[nome documento] con il nome del tuo documento!
4. **Ripeti l'operazione per tutti i documenti**.
{% endtab %}
{% tab title="Utenti avanzati e programmatori" %}
1. Vai alla sezione **Import / Export** del tuo Agente;
2. [**Carica il documento**](../../importazione-di-documenti/importare-documenti-testuali.md#configurazione-base) e setta le diverse impostazioni (mantieni e segnati l'argomento impostato che "marchia" i contenuti di ciascun file);
3. [**Esporta i contenuti in formato CSV**](/broken/pages/pRiZgAUpWHMo0kttSnsg#esecuzione-del-backup);
4. Aggiungi la dicitura "- \[nome documento]" alla fine di ogni domanda in maniera automatizzata;
5. [**Cancella i contenuti**](../../contenuti/modifica-e-aggiornamento-dei-contenuti.md#eliminazione-dei-contenuti) del tuo Agente;
6. [**Ricarica il file CSV modificato**](/broken/pages/pRiZgAUpWHMo0kttSnsg#come-importare-il-file-csv);
{% endtab %}
{% endtabs %}
#### Modifica le impostazioni relativa all'IA
Ora che hai caricato i documenti, dovrai istruire il tuo Agente a rispettare la tua gerarchia:
1. Accedi alle **Impostazioni** del tuo Agente;
2. Clicca sulla scheda  **IA**;
3. **Abilita l'interruttore dell'IA Generativa** se non è già attivo;
4. **Modifica le istruzioni** spiegando precisamente che priorità assegnare a ciascun documento. Es. "Quando l'utente fa una domanda, rispondi dando maggiore importanza ai contenuti del \[nome documento]. In un secondo momento, considera i contenuti di \[nome documento] e \[nome documento]".
5. Metti la spunta alla voce "**Risponde sempre con IA generativa**".
### Casi d'uso ideali
La gerarchia documentale è particolarmente utile per:
* Gestione di normative e regolamenti;
* Documentazione tecnica stratificata.
* Qualsiasi scenario con fonti informative di diversa autorità o attualità.
### Considerazioni importanti
* Mantieni una **struttura gerarchica semplice, chiara e logica**;
* Documenta attentamente la gerarchia stabilita;
* Aggiorna le priorità quando necessario;
* Verifica periodicamente la coerenza delle risposte.
La creazione di una gerarchia documentale rappresenta un significativo passo avanti nella gestione di informazioni complesse, permettendo al tuo Agente di fornire risposte più accurate e contestualizzate in base all'autorità delle diverse fonti.
# Importare un documento non supportato
AIsuru supporta l'importazione di vari tipi di documenti testuali, ma ci possono essere situazioni in cui desideri importare un formato non supportato ufficialmente. Questa guida ti aiuterà a gestire l'importazione di diversi tipi di file non standard, assicurando che il tuo Agente IA possa accedere e utilizzare efficacemente queste informazioni.
### Procedura generale
Se il formato del tuo documento non è direttamente supportato:
1. **Estrai il testo o le informazioni** dal tuo file;
2. **Incolla le informazioni** che hai estratto ->
1. Nelle [istruzioni](../../../ai-generativa/prompt-engineering/) se vuoi che l'IA sappia sempre tutto (e se il testo utilizza meno di 200.000 caratteri);
2. O nei [contenuti](../../contenuti/) se vuoi separare le informazioni per argomenti ->
1. Domanda -> inserisci una parola chiave;
2. Varianti di domanda -> scrivi specifiche domande per cui quelle informazioni sono utili;
3. Risposta -> inserisci il testo che hai estratto;
3. **Spiega come leggere e come utilizzare i dati** nelle istruzioni del tuo Agente.
### Gestione di formati specifici
Ora che abbiamo visto la procedure generale, vediamo come puoi caricare file di specifici formati.
#### File Excel
I file Excel, ed in generale le tabelle, più semplici possono essere trasformati in formato **markdown** e possono essere inseriti all'interno di un contenuto o delle istruzioni del tuo Agente.
Se, però, il tuo file Excel è più complesso e vuoi una maggiore accuratezza nelle risposte:
1. **Identifica diverse categorie in cui puoi accorpare i dati**;
2. A partire dal tuo Excel, **estrai le informazioni e salvale in diversi file JSON** (uno per categoria) che abbiano una struttura semplice e chiara anche per un essere umano;
3. **Copia il codice dei tuoi file JSON** e incollalo ->
1. Nelle **istruzioni** se il totale non supera i 200.000 caratteri
2. In tanti **contenuti** diversi (uno per categoria, come i file) ->
1. Domanda -> inserisci una parola chiave;
2. Varianti di domanda -> inserisci esempi di domande a cui l'IA dovrebbe rispondere a partire da quelle informazioni;
3. Risposta -> inserisci il codice del tuo file JSON.
3. In tante [**funzioni**](../../../avanzate/integrazioni/funzioni/) diverse (una per categoria, come i file) -> puoi utilizzare anche le funzioni per ospitare i tuoi contenuti. Ti basterà rendere accessibile il tuo file JSON e l'Agente andrà a recuperare le informazioni quando necessario
4. Nelle istruzioni, **spiega all'Agente dove trova le informazioni** (se nelle istruzioni, nei contenuti o nelle funzioni), **come leggere i dati** (la struttura del JSON) **e come li deve utilizzare** 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** (utilizza whisper di OpenAI o sfrutta Sharepoint per i meeting di Teams);
2. Nelle istruzioni **spiega cosa deve fare l'IA, copia la trascrizione e incollala**.
✅ Finito! Ora l'AI saprà rispondere alle domande sul video. La qualità delle risposte dipenderà molto dalla qualità della trascrizione stessa.
Se utilizzi Microsoft SharePoint, puoi anche allegare il link del video (al minuto preciso) ad ogni risposta:
1. **Assicurati di copiare anche il minutaggio** della trascrizione e riportalo nelle istruzioni del tuo Agente;
2. **Copia il link del video**;
3. **Personalizza e aggiungi queste istruzioni**:
```
1. LINK VIDEO:
- Il video si trova qui: `...name.mp4`
2. TRASCRIZIONE:
- La trascrizione precede ogni parte con hh:mm:ss indicando l'ora, il minuto e il secondo preciso in cui qualcosa viene detto.
- Devi ASSOLUTAMENTE tenere conto della trascrizione, del tempo ESATTO e della seguente regola per creare il link al minuto preciso.
3. COMPOSIZIONE DEL LINK AL MINUTO PRECISO:
- Se il minuto indica, per esempio, 5 minuti e 16 secondi, significa `5*60+16 = 316` secondi. Devi quindi aggiungere questa parte variabile al link:
`&nav=%7B%22playbackOptions%22%3A%7B%22startTimeInSeconds%22%3AXXX%7D%7D` dove `XXX` deve essere sostituito con i secondi esatti.
### Esempio:
- Calcolo: `5 minuti e 16 secondi = 5*60+16 = 316 secondi`
- Parte variabile: `&nav=%7B%22playbackOptions%22%3A%7B%22startTimeInSeconds%22%3A316%7D%7D`
- Link completo: `...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 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 in mente le informazioni estratte;
2. In un contenuto -> se vuoi mostrare l'immagine in specifiche occasioni (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](../../contenuti/creazione-manuale-dei-contenuti.md#media-e-link) -> aggiungi la tua immagine.
L'importazione di documenti non supportati richiede un po' più di lavoro manuale, ma permette di integrare una vasta gamma di informazioni nel tuo Agente AI. Scegli il metodo più appropriato in base al tipo di documento e alla struttura delle informazioni che contiene. Ricorda sempre di verificare 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 che lo interrogheranno. Un messaggio di benvenuto può anche indirizzare l'utente verso le domande a cui il tuo Agente può rispondere.
### Come personalizzare il messaggio di benvenuto
Per modificare il messaggio di benvenuto del tuo Agente:
1. Accedi ai **Contenuti** del tuo Agente;
2. Vai alla scheda "Messaggio di benvenuto" ed inserisci il testo che preferisci nella casella di testo.
{% hint style="info" %}
Il messaggio di benvenuto **include il nome della Persona, non il nome dell'Agente**: se vuoi che al cambio del nome si aggiorni anche il messaggio di benvenuto, allora sostituisci il nome della Persona con la scritta {0} all'interno del tuo messaggio di benvenuto. **Contenuti del tuo Agente**;
* Nel menu, seleziona "Risposte predefinite".
Da questa sezione potrai modificare la risposta predefinita di base e aggiungere altre risposte predefinite.
**Risposta predefinita di base**
La risposta predefinita di base è la risposta che il tuo Agente dà normalmente quando incontra qualche errore.
Per cambiarla, modifica il relativo campo di testo e premi sul tasto "Salva" che trovi sulla destra. Se, invece, vuoi riportare il suo valore a quello originale, premi sul tasto "Reset".
#### Risposte predefinite personalizzate
In alcuni casi, puoi mostrare una risposta personalizzata che l'Agente fornirà all'utente al posto della risposta di base.
Per farlo, premi sul tasto **Nuova risposta predefinita** e inserisci la risposta.
Ricorda che è obbligatorio specificare almeno uno tra:
* [Argomento](personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md) necessario;
* [Ruolo](personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici.md) a cui assegnare la risposta;
* [Data o luogo](personalizzazione-dei-contenuti/personalizzare-le-risposte-in-base-a-data-e-luogo-dellutente.md).
All'interno della scheda di creazione della risposta, però, puoi anche:
* Aggiungere [altre risposte](../contenuti/creazione-manuale-dei-contenuti.md#altre-risposte);
* Segnare la [risposta come conclusiva](../contenuti/creazione-manuale-dei-contenuti.md#altri-campi);
* Aggiungere [media e link](../contenuti/creazione-manuale-dei-contenuti.md#media-e-link);
* Avanzate: aggiungere [suggerimenti](personalizzazione-dei-contenuti/gestione-dei-suggerimenti.md), [tag](personalizzazione-dei-contenuti/gestione-dei-tag.md), [contesto](personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md), [testi preformattati](personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md), modificare il [timeout](personalizzazione-dei-contenuti/utilizzo-del-timeout.md) e modificare l'[integrazione DCM](../../estensioni/open-badge.md).
### Utilizzo efficace delle risposte predefinite
Per massimizzare l'efficacia delle tue risposte predefinite:
* Crea risposte chiare e concise che guidino l'utente verso una risoluzione;
* 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 permettono di arricchire le risposte del tuo Agente con HTML e formule matematiche, creando esperienze di conversazione più ricche e interattive.
### Codice HTML all'interno dei messaggi
L'HTML nei messaggi viene interpretato e renderizzato automaticamente quando il messaggio viene visualizzato. Non dovrai attivare alcuna impostazione specifica: basta includere il codice HTML desiderato nella risposta dell'Agente.
#### Come utilizzare l'HTML all'interno del tuo Agente
Per sfruttare questa funzionalità, dovrai semplicemente inserire il codice HTML:
* **Nella** [**risposta del tuo contenuto**](../contenuti/creazione-manuale-dei-contenuti.md#come-creare-un-contenuto-semplice) -> in questo caso, il codice HTML sarà sempre lo stesso (utile, ad esempio, per i form);
* **Nelle** [**istruzioni**](../../ai-generativa/prompt-engineering/) -> ricorda di spiegare all'IA generativa quando e come usare il tuo codice HTML.
Una volta fatto questo, ricordati di testare per assicurarti che il tuo codice sia visualizzato correttamente. Per implementazioni più complesse, ricorda che puoi **puoi aggiungere codice JavaScript e CSS negli** [**snippet di codice eseguibili**](personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md).
#### Esempio: mostra le immagini da un sito web
Ecco un esempio di come istruire l'Agente per mostrare le immagini che trova all'interno di una certa pagina web 👇
{% code fullWidth="false" %}
```
Quando l'utente ti chiede di vedere una foto:
1. Chiama la funzione "album_foto";
2. Leggi i nomi delle foto che ti sono restituiti dalla funzione;
3. Trova la foto che l'utente ha chiesto di vedere e ricorda il path
ed il nome del file (/img/esempio.png)
4. Rispondi includendo il codice HTML che permette all'utente di vedere la foto
Codice HTML per mostrare la foto all'utente:
.svg)
: permette di copiare il testo del messaggio già formattato e renderizzato (solo testo).
* **Copia codice sorgente** 
: permette di copiare il testo originale con tutti i tag HTML o la formattazione Markdown.
Questa funzionalità è particolarmente utile quando:
* Hai bisogno di riutilizzare il codice HTML o Markdown;
* Devi condividere sia la visualizzazione che il codice sorgente di una risposta.
Ad esempio, quando copi una risposta di un Agente contenente 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à, potrai trasformare le conversazioni con il tuo Agente da semplici scambi testuali a esperienze ricche e coinvolgenti per i tuoi utenti.
# Metodi avanzati di istruzione
Oltre ai metodi base (Istruiscimi, Contenuti e Import di documenti), AIsuru offre tre approcci avanzati per istruire il tuo Agente:
* Puoi inserire brevi documenti direttamente nelle [istruzioni del Agente](../../ai-generativa/prompt-engineering/);
* Puoi usare le [funzioni](../../avanzate/integrazioni/funzioni/) per accedere in tempo reale a documenti e dati online.
* Puoi usare gli [MCP](../../avanzate/integrazioni/model-context-protocol-mcp-su-aisuru/mcp-cosa-sono-e-come-si-utilizzano.md) per avere accesso a servizi esterni come database.
**Impostazioni**;
3. All'interno della pagina Impostazioni, premi su 
**IA** per aprire la sezione;
4. **Attiva l'interruttore** accanto alla scritta **"**Abilita le risposte generate da 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 le risposte alle domande degli utenti;
4. Decide quando utilizzare funzioni o intenti dinamici.
2. **Configurazione per import/export**: permette di cambiare il modello che gestisce [l'import dei tuoi documenti testuali](../istruzione-gestione-contenuti-agenti/importazione-di-documenti/importare-documenti-testuali.md);
3. **Configurazione per** [**Pensiero Profondo**](../estensioni/pensiero-profondo/): permette di cambiare il modello che decide cosa ricordare dalle conversazioni con ciascun utente (solo con Pensiero Profondo attivo).
Da questi tre menu a tendina, potrai modificare il modello utilizzato per una certa attività. Già di default, i modelli scelti da AIsuru ti permettono di avere una qualità delle risposte eccellente:
* Configurazione per **domande e risposte**: Anthropic - Claude 4.5 Sonnet;
* Configurazione per **import/export**: OpenAI - GPT 4o Mini;
* Configurazione per **Pensiero Profondo**: Anthropic - Claude 4.5 Sonnet.
Dopo aver attivato l'IA generativa e aver configurato i modelli, potrai:
* Modificare le [**istruzioni**](prompt-engineering/);
* Attivare o disattivare [**Pensiero Profondo**](../estensioni/pensiero-profondo/);
* Settare [**altre impostazioni dell'IA generativa**](ia-generativa-sezione-avanzata/altre-impostazioni-dellia-generativa.md).
{% hint style="info" %}
**Nota**:\
La configurazione per Pensiero Profondo viene utilizzata anche per i Gruppi di Esperti, a meno che non sia stato configurato un modello specifico nelle impostazioni del singolo Gruppo di Esperti.
{% endhint %}
# Istruzioni IA
**Le istruzioni sono il fondamento del comportamento del tuo Agente**. Una configurazione accurata delle istruzioni 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 si modificano le [**istruzioni per l'IA generativa**](istruzioni-ia-cosa-sono-e-come-modificarle.md);
* Come orientarsi nel [**Editor Avanzato del**](editor-avanzato-delle-istruzioni.md)[**le istruzioni**](editor-avanzato-delle-istruzioni.md);
* Come [**creare istruzioni chiare e specifiche** ](come-scrivere-istruzioni-efficaci.md)per guidare il comportamento del tuo Agente;
* [**Esempi reali di istruzioni efficaci**](esempi-di-istruzioni-efficaci.md).
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 sfruttarle per stabilire:
* **Ruolo e competenze** del tuo Agente;
* **Stile delle risposte**;
* **Limitazioni e linee guida comportamentali**.
{% hint style="danger" %}
Non inserire mai informazioni riservate all'interno delle istruzioni dell'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. Accedi al pannello di gestione dell'Agente desiderato;
2. Seleziona 
**Impostazioni** nella barra laterale;
3. All'interno della pagina, accedi alla sezione 
**IA**;
4. Individua il campo "Istruzioni", modifica come preferisci e premi su "Salva le modifiche".
_Nota: Il campo "Istruzioni" può essere espanso premendo su "Espandi" per aprire un editor avanzato del system prompt._
Se vuoi creare istruzioni efficaci, prosegui con il prossimo capitolo 👇
# Editor Avanzato delle istruzioni
Ora che abbiamo compreso l'importanza delle istruzioni del nostro Agente, vediamo nel dettaglio come utilizzare l'editor avanzato.
### Accesso editor avanzato
Per visualizzare l'editor avanzato del tuo Agente, segui questi passaggi:
1. Seleziona **Impostazioni** nella barra laterale del tuo agente;
2. All'interno della pagina, accedi alla sezione **IA**;
3. Individua il campo "Istruzioni", e premi su "Espandi".
### Interfaccia dell'editor avanzato
L'editor avanzato si presenta con 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](./) in formato testo, con evidenziazione della sintassi per facilitare la lettura e l'editing del codice.
### Barra degli strumenti superiore
Nella parte superiore dell'editor trovi:
* **pulsante "Copia"**: permette di copiare negli appunti le istruzioni;
* **pulsante "Annulla" (Ctrl+Z)**: permette di annullare le ultime modifiche;
* **toggle "Salvataggio automatico"**: quando attivo, salva automaticamente le modifiche;
* **menu "Modalità"**: permette di scegliere tra diverse modalità di visualizzazione:
* **"Testo"**: visualizzazione semplice del testo senza formattazione;
* **"Testo (markdown)"**: mostra il testo con la sintassi markdown visibile;
* **"Anteprima (markdown)"**: renderizza il testo formattato secondo le regole markdown;
* **"Vista divisa"**: divide lo schermo mostrando contemporaneamente il codice markdown e la sua anteprima formattata.
* **pulsante "Espandi barra laterale"**: permette di espandere o ridurre il pannello laterale destro.
### Pannello laterale destro - Caratteri
Il pannello "Caratteri" mostra informazioni utili sul tuo testo delle istruzioni:
* **conteggio caratteri**: 0 / 10000;
* **parole**: 0;
* **paragrafi**: 0.
{% hint style="info" %}
Il conteggio di caratteri consigliato per è di 10.000 ma **non viene applicato alcun limite**.\
è possibile scrivere anche istruzioni da 70.000 caratteri.
{% endhint %}
### Pannello laterale destro - Prompt Template
La sezione "Prompt Template" permette di vedere alcune caratteristiche delle proprie 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 è anche disponibile un **pulsante** che permette di aprire un menù con due possibilità:
* **importare** le istruzioni da un altro Agente;
* **esportare** le istruzioni da questo Agente.
### Consigli per un utilizzo efficace
* **Sfrutta il salvataggio automatico:** attiva il toggle "Salvataggio automatico" per evitare di perdere le modifiche durante l'editing;
* **Monitora il conteggio caratteri:** tieni d'occhio il pannello "Caratteri" per assicurarti di 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.
# Come scrivere istruzioni efficaci
Le istruzioni sono come una "guida al comportamento" per il tuo Agente: gli spieghi chi è, cosa deve fare e come deve interagire con gli utenti. **Scrivere delle buone istruzioni è fondamentale** per avere un Agente che risponda in modo preciso e pertinente.
### Cosa insegnare al tuo Agente
Quando scrivi le istruzioni, pensa di dover spiegare a una persona appena assunta questi aspetti:
* **Chi è**: qual è il suo ruolo? È un assistente clienti, un esperto di marketing, un tutor?
* **Con chi parla**: chi sono i suoi utenti? Cosa vogliono ottenere?
* **Cosa sa fare**: quali sono le sue competenze? Di cosa può parlare?
* **Come parlare**: deve essere formale o informale? Tecnico o semplice?
* **Cosa non deve fare**: ci sono argomenti da evitare o informazioni da non condividere?
{% hint style="danger" %}
**ATTENZIONE**: non condividere mai informazioni riservate all'interno delle istruzioni IA. Piuttosto, inserisci queste informazioni all'interno di specifici contenuti [assegnati ad un ruolo](../../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici.md) o con un [contesto necessario](../../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md#argomenti-necessari).
{% endhint %}
### Come scrivere istruzioni efficaci
**Struttura logicamente le tue istruzioni**
* Crea sezioni logiche e ben definite (es. ruolo, competenze, limiti);
* Usa una gerarchia chiara delle informazioni;
* Inserisci esempi concreti per i concetti chiave;
* Mantieni coerenza nella formattazione.
**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 contesto.
#### Domande e risposte
* Definisci il formato atteso delle richieste degli utenti -> domande brevi, pezzi 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 generici;
* Definisci chiaramente i 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 nella scrittura delle istruzioni, utilizza il nostro [**Meta Prompt Engineer**](https://www.aisuru.com/it/memoridev/Meta%20Prompt%20Engineer): ti aiuterà a generare istruzioni appropriate basate sulle tue esigenze specifiche.
### 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 performance.
#### **Ottimizzazione e aggiornamento**
* Aggiorna le istruzioni in base ai feedback;
* Migliora la gestione dei casi limite identificati;
* Documenta le modifiche eseguite.
# Esempi di istruzioni efficaci
Le istruzioni sono fondamentali 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 sai come scrivere le istruzioni:
* **puoi rivolgerti al** [**Meta Prompt Engineer**](https://www.aisuru.com/it/private/4d4bbe49-a089-4639-8e04-d4493d93ef56/c4bc0ec9-6473-4823-8908-5f556d1438b9): raccontagli la tua idea e lasciati guidare dall'Agente;
* **consultare la** [**guida di anthropic**](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) sul prompt engenering.
{% 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**: elenca le caratteristiche chiave che definiscono la personalità e l'approccio di Zephyr;
3. **Responsabilità specifiche**: fornisce un elenco di compiti principali che Zephyr deve svolgere;
4. **Linee guida per l'interazione**: offre istruzioni specifiche su come Zephyr dovrebbe interagire con gli utenti;
5. **Esempio concreto**: fornisce un esempio di previsione per illustrare come Zephyr dovrebbe operare;
6. **Adattabilità**: incoraggia l'adattamento alle preferenze e alla posizione dell'utente;
7. **Struttura chiara**: il testo è organizzato in sezioni logiche e utilizza elenchi puntati per una facile lettura e 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.
| Provider | Modello | Grandezza | Context window (token) |
|---|---|---|---|
| Vertex Anthropic | claude-3-7-sonnet-20250219 | Grande | 200.000 |
| Vertex Anthropic | Claude 4.5 Sonnet | Grande | 200.000 o 1mln |
| Vertex Anthropic | claude-sonnet-4-20250514 | Grande | 200.000 o 1mln |
| Vertex Anthropic | claude-haiku-4-5-20251001 | Piccolo | 200.000 |
| Mistral | mistral-large-2407 | Grande | 128.000 |
| OpenAI | gpt-4o | Grande | 128.000 |
| OpenAI | gpt-4o-mini | Piccolo | 128.000 |
Impostazioni del tuo Agente e clicca su IA per accedere all'apposita sezione. Da qui, puoi:
1. [**Attivare o disattivare l'IA generativa**](../attiva-lia-generativa-e-cambia-il-modello.md#come-attivare-lai-generativa-per-il-tuo-twin);
2. Attivare o disattivare [**Pensiero Profondo**](../../estensioni/pensiero-profondo/);
3. Modificare le [**istruzioni**](../prompt-engineering/);
4. [**Cambiare i modelli IA**](../attiva-lia-generativa-e-cambia-il-modello.md#come-cambiare-il-modello-del-tuo-twin) usati dal tuo Agente.
Oltre a ciò, al di sotto del campo delle istruzioni, puoi trovare due opzioni:
* [Risponde sempre con IA generativa](altre-impostazioni-dellia-generativa.md#risponde-sempre-con-ia-generativa);
* [Estrazione automatica dei media](altre-impostazioni-dellia-generativa.md#estrazione-automatica-dei-media).
All'interno della sezione "Impostazioni del provider" troverai anche:
* [Numero massimo di token](altre-impostazioni-dellia-generativa.md#numero-massimo-di-token);
* [Temperatura](altre-impostazioni-dellia-generativa.md#temperatura).
Vediamole nel dettaglio 👇
#### Risponde sempre con IA generativa
Questa impostazione, se attiva, permette di **rispondere sempre e solo con l'IA generativa**: il tuo Agente non fornirà più le risposte in autonomia, ma le farà formulare al modello scelto (voce "Configurazione per domande e risposte").
**L'Agente condividerà i contenuti più rilevanti con il modello linguistico scelto** e il modello linguistico si occuperà di generare la risposta da dare all'utente. Questo ti permette di mantenere le risposte rilevanti e accurate senza, però, rinunciare alla personalizzazione!
{% hint style="info" %}
**L'IA generativa potrebbe fornire risposte errate**. Assicurati di testare ogni scenario di utilizzo del tuo Agente per assicurarti che continui a rispondere correttamente.
{% endhint %}
#### Disabilita l'estrazione automatica delle immagine dai contenuti
Come visto nella sezione dedicata ai [contenuti](../../istruzione-gestione-contenuti-agenti/contenuti/), puoi aggiungere media e link a specifiche domande e risposte.
Come impostazione predefinita, l'Agente IA è in grado di leggere i titoli delle immagini e dei link associati ai contenuti più rilevanti e potrà mostrarli all'utente anche in caso di risposte generate da IA.
In caso riscontrassi problemi, puoi aggiungere la spunta a questa opzione per disabilitare questo comportamento.
#### Numero massimo di token
Questo parametro controlla la **lunghezza massima di ogni risposta generata dall'IA**.
In piattaforma, puoi selezionare un numero da 256 a 4000 token massimi per ogni risposta generata da IA (il valore predefinito è 512). Se utilizzi un modello che supporta un numero superiore di output token, puoi modificare questo valore via API.
Per convertire approssimativamente i token in caratteri: **1 token ≈ 4 caratteri** per l'italiano.
{% hint style="info" %}
**Non tutti i modelli supportano un numero elevato di output token**. Se utilizzi la tua chiave API, assicurati di controllare il numero massimo di output token.
{% endhint %}
#### Temperatura
La temperatura influenza la creatività delle risposte del tuo Agente. Si tratta di un numero che va 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 a 0**: otterrai più spesso risposte simili. Se, però, cerchi risposte più creative, puoi alzare gradualmente la temperatura.
### Ottimizzazione delle impostazioni
Trovare la configurazione perfetta per il tuo Agente potrebbe richiedere alcune prove. Non esitare a sperimentare con queste impostazioni per raggiungere il giusto equilibrio tra accuratezza, creatività e performance.
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 permette di creare e gestire le configurazioni di accesso ai modelli di linguaggio (LLM) che i tuoi Agenti potranno utilizzare sulla piattaforma. Questa sezione ti guiderà attraverso il processo di creazione e gestione 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. Visualizzerai la lista dei modelli che hai configurato.
### Gestione delle configurazioni esistenti
Nella pagina principale, puoi:
* Filtrare le configurazioni per scopo (Q\&A, Import/Export, Pensiero Profondo);
* Visualizzare i dettagli di ogni configurazione;
* Modificare le configurazioni esistenti;
* Eliminare le configurazioni non più necessarie.
### Creazione di una nuova configurazione
Per configurare un nuovo modello:
1. Clicca sul pulsante **Nuova configurazione**;
2. Compila i campi richiesti:
* **Nome**: assegna un nome identificativo (e univoco) alla configurazione; non utilizzare spazi;
* **Descrizione**: fornisci una breve descrizione della configurazione;
* **Provider**: seleziona il fornitore del modello (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:
* Q\&A: per le conversazioni con gli utenti;
* Import/Export: per le operazioni sui contenuti;
* Pensiero profondo e Gruppo di Esperti: per la memoria delle interazioni passate e la coordinazione tra esperti.
4. Clicca 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 nella scheda **Modelli** delle impostazioni del tuo Agente;
2. Individua il modello che vuoi duplicare nella lista;
3. Clicca sull'icona **Duplica** (quella centrale tra "Modifica" ed "Elimina");
4. Si aprirà un form precompilato con tutti i campi del modello originale.
**Nel form di duplicazione potrai**:
* Modificare il **nome** della configurazione (per default avrà il suffisso `_copy`);
* Modificare qualsiasi campo prima di salvare;
* Clicca su **Conferma** per creare il nuovo modello duplicato.
> **💡 Suggerimento**: \
> La duplicazione è utile quando vuoi creare varianti dello stesso modello con piccole modifiche (es. stesso provider ma location diversa, o stesse credenziali ma funzionalità diverse).
### Impostazioni di visibilità (solo per Admin)
Se hai i permessi di amministratore, nella creazione o modifica di una configurazione troverai anche la sezione **"Impostazioni di visibilità"** con le seguenti opzioni:
* **Visibile agli utenti del tenant**: rendi questa configurazione visibile ed utilizzabile dagli utenti del tenant;
* **Usa come predefinito**: rendi questa configurazione il default per i nuovi Agenti AI creati, ma solo per le categorie che hai selezionato. Esempio:
* Se hai abilitato solo Q\&A, questo modello sarà il predefinito per le conversazioni con gli utenti;
* Se hai abilitato tutte e tre le categorie (Q\&A, Import/Export, Pensiero profondo e Gruppo di Esperti), questo modello sarà il predefinito per tutte e tre.
Anche se imposti un modello come predefinito, il creatore dell'Agente potrà comunque selezionare un modello differente tra quelli disponibili sul tenant durante la creazione e la configurazione.
{% hint style="info" %}
Se hai un [tenant AIsuru separato](../../paas/), tieni a mente che **un modello non visibile ad altri utenti è comunque sempre visibile ed utilizzabile dagli admin del tenant**.
{% endhint %}
### Applicazione massiva della configurazione
Se hai i permessi di amministratore e desideri applicare la stessa configurazione di modello a tutti gli Agenti del tenant, puoi utilizzare la funzionalità **"Applica a tutti"**:
1. **Prerequisiti necessari**:
* Il flag "**Usa come predefinito**" deve essere abilitato
* Il flag "**Visibile agli utenti del tenant**" deve essere abilitato
2. **Come utilizzare la funzione**:
* Dopo aver configurato tutti i parametri del modello
* Clicca sul pulsante **"Applica a tutti"**
* La configurazione verrà automaticamente applicata a tutti gli Agenti esistenti nel tenant
{% hint style="danger" %}
Questa operazione **sovrascriverà le configurazioni di modello esistenti per tutti gli Agenti del tenant**. Assicurati che la configurazione sia corretta prima di procedere. Utilizza questa funzionalità quando vuoi standardizzare l'utilizzo 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 la configurazione;
* Abilita solo gli scopi necessari per ogni modello;
* Rivedi periodicamente le configurazioni per mantenerle aggiornate.
La gestione accurata delle configurazioni ti permette di ottimizzare le prestazioni del tuo Agente, garantendo risposte più precise e pertinenti in base alle tue esigenze specifiche.
# Provider e modelli: come ottenere le chiavi API dai provider
Se hai bisogno di utilizzare provider esterni per i tuoi Agenti AIsuru, questa sezione ti guiderà attraverso il processo di registrazione e configurazione degli account su ciascuna piattaforma. Una corretta gestione dei provider e dei modelli ti permetterà di **mantenere i costi e la disponibilità dei tuoi Agenti** [**AIsuru**](https://www.aisuru.com/) **sempre sotto controllo**!
Qui trovi le guide specifiche per:
* [OpenAI Platform](api-openai-guida-alla-creazione-e-gestione-dellaccount.md);
* [Anthropic Claude Console](claude-console-come-gestire-le-chiavi-api-di-anthropic.md);
* [Mistral AI Studio](mistral-api-come-gestire-i-modelli-ai-studio.md);
* [Azure OpenAI](azure-ai-foundry-come-usare-i-modelli-openai-e-gestire-accessi-e-costi.md) (per i modelli OpenAI).
Ogni guida ti accompagnerà passo passo attraverso i passaggi fondamentali: dalla registrazione dell'account all'inserimento dei dati di fatturazione, dall'aggiunta di metodi di pagamento alla creazione delle 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 dei servizi.
Una volta ottenuta la chiave API dal provider scelto, potrai utilizzarla per [creare un nuovo modello](../crea-e-gestisci-le-configurazioni-dei-modelli.md) in piattaforma e iniziare subito a sfruttare le potenzialità dei 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, impostare i metodi di pagamento, gestire i limiti di spesa e creare le chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/).
## 1. Registrazione sulla piattaforma di 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 (se già hai un account ChatGPT è comunque necessario registrarsi);
3. Inserisci il tuo indirizzo email e crea una password;
4. Verifica il tuo indirizzo email cliccando sul link che riceverai;
5. Completa le informazioni richieste per il tuo profilo.
## 2. OpenAI: configurazione della fatturazione
Dopo aver creato l'account, è necessario impostare correttamente i dati di fatturazione per l'utilizzo 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 i dati tuoi o della tua azienda:
4. Company Name (Nome completo dell'azienda);
5. Billing email (riceverà le fatture);
6. Indirizzo completo;
7. Business tax ID (P. IVA, selezionare IT VAT e scrivere il codice di partita IVA con il prefisso IT incluso).
8. Fai clic su "Save" per confermare le informazioni.
## 3. Come aggiungere un metodo di pagamento per OpenAI
Per utilizzare i servizi OpenAI, è necessario 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 debito. Assicurati che la carta sia abilitata per pagamenti internazionali in USD (la valuta usata da OpenAI) e autorizzata per acquisti online.
## 4. Acquistare crediti su OpenAI
Per iniziare a utilizzare i servizi OpenAI, è necessario 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 con il metodo precedentemente aggiunto.
Nota: I crediti acquistati hanno una validità di un anno e sono non rimborsabili.
### Ricarica automatica
Inoltre, per evitare interruzioni del servizio, puoi impostare la funzione di **ricarica automatica**:
1. Nella sezione "Billing", attiva l'opzione "Auto-recharge";
2. Definisci l'importo da ricaricare automaticamente e la soglia al di sotto della quale la ricarica verrà effettuata.
Questo assicurerà che il tuo account disponga sempre di 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 dei 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 alla voce “Set a Budget Alert” -> l’admin riceverà un avviso al raggiungimento di quella soglia di spesa;
4. Imposta un limite di budget per impostare un tetto di spesa delle API (puoi impostare 2x volte il tuo consumo medio mensile).
5. Premi su Salva.
L'attivazione del limite di budget impedirà automaticamente ulteriori addebiti una volta raggiunta la soglia configurata. Il limite può essere cambiato in qualsiasi momento ed è anche possibile impostare limiti per singoli progetti.
## 6. Creazione di una chiave API OpenAI
Per utilizzare i servizi OpenAI con [AIsuru](https://www.aisuru.com/), è necessario 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. Owned by You;
2. Assegna un nome descrittivo alla chiave (es. "AIsuru");
3. Assegnala ad un “progetto” (project);
4. Permissions -> All.
3. Fai clic su "Create secret key" e **copia immediatamente la chiave API visualizzata** e conservala in un luogo sicuro. Non sarà più possibile visualizzarla successivamente.
Nota: quando si genera la prima chiave API in assoluto sul proprio account, OpenAI richiede una verifica via numero di telefono.
## 7. Gestire i progetti OpenAI
OpenAI permette di organizzare il 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 del punto 6.
Creare progetti separati è utile per:
* Tenere traccia dell'utilizzo per diverse iniziative o dipartimenti;
* Impostare limiti di spesa (o rate limit) specifici per progetto;
* Revocare l'accesso a specifici progetti / clienti senza influire sugli altri.
## 8. Gestione dei membri dell'organizzazione su OpenAI
Per collaborare con altri membri del tuo team all'interno della tua organizzazione OpenAI:
* Accedi alla sezione Membri:
* Dalla dashboard, vai su Settings > Members.
* Aggiungi un nuovo membro:
* Clicca 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 sotto il nome dell'organizzazione ma non può gestire le impostazioni. Un Reader può invitare altri utenti come Reader nell'organizzazione
* Clicca su Send invite per inviare l'invito.
## 9. Limiti di utilizzo (rate limits) e tier con OpenAI
OpenAI impone limiti di utilizzo per garantire un uso equo delle risorse:
* **Limiti per tier**: ogni tier ha specifici limiti di richieste e token per minuto. Puoi visualizzare i dettagli dei limiti per ciascun tier nella [documentazione di OpenAI](https://platform.openai.com/docs/guides/rate-limits/usage-tiers#usage-tiers).
* **Upgrade del tier**: qualora si necessiti di limiti ulteriormente più alti oltre il massimo ottenibile automaticamente – ad esempio per casi d’uso aziendali molto grandi – allora è necessario inoltrare una richiesta di aumento tramite la pagina Usage Limits (cliccando su “Need help?” e compilando il form). Il team OpenAI valuterà la richiesta e potrà eventualmente approvare un tier più elevato.
## Prossimi passi
Dopo aver completato la configurazione del tuo account OpenAI:
1. Copia la chiave API creata;
2. Accedi alla tua dashboard [AIsuru](https://www.aisuru.com/);
3. Utilizza la chiave API per [creare un nuovo modello in piattaforma](../crea-e-gestisci-le-configurazioni-dei-modelli.md)..
# Claude Console: come gestire le chiavi API di Anthropic
Questa guida illustra il processo completo per creare un account Anthropic, impostare i metodi di pagamento, gestire i limiti di spesa e creare le chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/).
## 1. Registrazione di un account Anthropic
Per iniziare a usare la console Claude è necessario creare un account sviluppatore:
1. **Accedi alla pagina di registrazione**: visita la [Console di Claude](https://console.anthropic.com/) e seleziona l'opzione per registrarti. Puoi utilizzare un account Google (Continue with Google) oppure un indirizzo email (Continue with email).
2. **Verifica l'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 l'account. Clicca sul link "Sign in to Claude Console" per procedere (non è richiesta la creazione di una password).
3. **Completa l'onboarding**: dopo aver cliccato il link, verrai reindirizzato a una pagina di onboarding della console di 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. Clicca Continue per avanzare.
4. **Crea un'organizzazione**: successivamente, specifica un nome per la tua organizzazione. Può essere il nome della tua azienda oppure un nome descrittivo (anche il tuo nome, se stai testando la piattaforma). Conferma cliccando su Create Account.
Al termine della registrazione, verrai accolto dalla Console di Claude. Prima di iniziare a utilizzare l'API è importante configurare la sezione di fatturazione della console.
## 2. Claude API Console: inserire i dati di fatturazione
Per assicurare una corretta fatturazione dovrai inserire i dati della tua azienda, inclusa la Partita IVA:
1. Apri i dettagli dell'organizzazione: nella console, clicca su "Settings" (Impostazioni) nella colonna laterale. Si aprirà la sezione delle impostazioni. Dal menu laterale sinistro, seleziona "[Organization](https://console.anthropic.com/settings/organization)" (Organizzazione).
2. Compila le informazioni aziendali: nella pagina dell'organizzazione, inserisci tutti i dati richiesti della tua azienda. In particolare:
1. Nome dell'organizzazione: dovrebbe essere già presente quello inserito in fase di registrazione, ma assicurati che corrisponda al nome legale della tua azienda.
2. Indirizzo aziendale completo: inserisci l'indirizzo di fatturazione dell'azienda (via, città, CAP, paese).
3. Partita IVA: se la tua azienda ha sede in un paese in cui è prevista l'imposta (es. in UE), comparirà un campo opzionale per il Tax or VAT ID. Inserisci qui la Partita IVA aziendale (comprensiva del prefisso nazionale, es. IT12345678901).
3. Salva le modifiche: dopo aver riempito i campi, verifica che siano corretti e clicca sul pulsante per salvare i dettagli dell'organizzazione.
## 3. Aggiungere un metodo di pagamento per le API di Anthropic Claude
Una volta impostati i dati aziendali, dovrai aggiungere un metodo di pagamento per poter effettuare acquisti di crediti:
1. Vai alla sezione Billing: dalle impostazioni, seleziona la voce [Plans & Billing](https://console.anthropic.com/settings/billing) (Piani e fatturazione) nel menu per gestire pagamenti, crediti e fatture.
2. Avvia la procedura di aggiunta carta: nella pagina di Billing, individua l'opzione per aggiungere un metodo di pagamento. Se è la prima configurazione, potresti vedere un pulsante Complete Setup oppure Add Payment Method / Add funds. Cliccalo per iniziare.
3. Inserisci i dati della carta: si aprirà un modulo Stripe dove dovrai inserire i dettagli della tua carta:
1. Numero della carta di credito o di debito;
2. Data di scadenza;
3. Codice CVV/CVC.
Attualmente, non esiste un’opzione per rimuovere una carta salvata direttamente dalla console (è possibile solo sostituirla aggiungendone un’altra).
Anthropic invia la ricevuta di ogni acquisto all’email di fatturazione registrata e rende disponibili le invoice nella sezione Billing > Invoice History.
Nota: Attualmente sono accettate solo carte di credito/debito. Assicurati che la carta sia abilitata per pagamenti internazionali in USD (la valuta usata da Anthropic) e autorizzata per acquisti online. L’utente deve avere permessi Admin o Billing per configurare il pagamento (la guida assume che l’account creatore sia Admin, il che è vero di default).
## 4. Claude Console: primo acquisto di crediti
Anthropic utilizza un sistema di crediti prepagati per l'utilizzo dell'API. Ciò significa che prima di poter utilizzare l'API in modo esteso, devi acquistare crediti da caricare sul tuo account:
1. Accedi alla pagina di Billing: vai di nuovo nella sezione [Plans & Billing](https://console.anthropic.com/settings/billing) della console Anthropic. Nella parte dedicata al Credit balance vedrai il saldo attuale di crediti della tua organizzazione.
2. Aggiungere crediti: clicca sul pulsante "Add funds" (Aggiungi fondi) o "Purchase Credits". Ti verrà richiesto di inserire l'importo in dollari (USD) dei crediti che desideri acquistare. L'importo minimo di ricarica iniziale è pari a 5 USD.
3. Inserisci i dettagli aggiuntivi se richiesti: se è la prima volta che aggiungi fondi, potrebbe comparire una finestra di completamento configurazione. Anthropic potrebbe chiederti ulteriori informazioni prima di consentire l'acquisto di crediti, ad esempio:
1. Confermare il tipo di utilizzo previsto dell'API;
2. I paesi in cui prevedi di utilizzare Claude;
3. Se il tuo uso dell'API coinvolgerà determinati settori regolamentati.
4. Conferma il pagamento dei crediti: verrà quindi richiesta conferma del metodo di pagamento per addebitare l'importo dei crediti. Se è tutto corretto, procedi pure.
5. Verifica il saldo crediti: una volta completata la transazione, la console aggiornerà immediatamente il tuo saldo nella sezione "Credit balance" su [Plans & Billing](https://console.anthropic.com/settings/billing).
### Autoricarica
Nella pagina di Billing è disponibile un'impostazione per l'autoricarica (auto-reload) dei crediti. Puoi attivarla se desideri che i crediti si ricarichino automaticamente quando il saldo scende sotto una soglia che decidi tu.
Per configurare l'auto-reload, clicca su Edit settings nella sezione Billing e definisci:
* Soglia minima di saldo (minimum balance) sotto cui scatta la ricarica automatica.
* Importo di ricarica che verrà acquistato quando si raggiunge quella soglia.
Puoi anche disabilitare l'auto-reload in qualsiasi momento se preferisci gestire manualmente le ricariche per un miglior controllo di spesa. I crediti acquistati hanno solitamente una validità di un anno.
## 5. Come controllare e limitare spesa ed utilizzo delle API di Claude
Per un uso aziendale responsabile, è importante tenere sotto controllo sia la spesa che l'utilizzo dell'API.
### **Monitoraggio dell'utilizzo e dei costi**
La console di Claude fornisce report dettagliati sull'uso dell'API:
* Navigando in Settings > [Usage](https://console.anthropic.com/settings/usage) puoi vedere il consumo di token con la possibilità di filtrare per Workspace, modello AI, chiave API o intervallo temporale;
* Nella pagina Settings > [Cost](https://console.anthropic.com/settings/cost) trovi un report dei costi con gli stessi filtri.
### **Limitare il budget con i crediti**
Il modello prepagato di Anthropic fa sì che tu non possa spendere più di quanto hai caricato in crediti. Se desideri avere un limite di spesa rigido, puoi lasciare disabilitata la ricarica automatica: in questo modo la spesa massima sarà limitata all'importo di crediti che hai acquistato.
Ad ogni modo, a livello di account, è possibile limitare la spesa mensile per le API di Claude: basta andare nella sezione [Limits](https://console.anthropic.com/settings/limits) della console e impostare il limite mensile. Se ne hai già impostato uno, basterà premere sul tasto "Change Limit":
1. Nel popup che si apre, inserisci il valore del limite mensile in dollari americani;
2. Clicca su "Update Limit" per aggiornare il limite o su "Remove Limit" per rimuoverlo completamente.
## 6. Creazione di una chiave API
Per utilizzare i servizi Anthropic con AIsuru, è necessario creare una chiave API:
1. Dalla console Anthropic, vai su Settings > API Keys dal menu laterale;
2. Crea una nuova chiave: nella pagina delle [chiavi API](https://console.anthropic.com/settings/keys), clicca il pulsante Create Key;
3. Assegna Workspace e nome alla chiave: ti verrà chiesto di selezionare:
1. Workspace: se non hai creato workspace aggiuntivi, lascia selezionato Default;
2. Nome della chiave: inserisci un nome descrittivo per la chiave API (es. "AIsuru - \[nome Agente]" o "AIsuru - Produzione");
4. Conferma la creazione e copia la chiave: clicca su Create. La console genererà la chiave API. Questa sarà mostrata solo una volta al momento della creazione: copiala immediatamente e salvala in un luogo sicuro.
## 7. Claude workspaces: cosa sono e come si creano
La console di Anthropic Claude supporta la suddivisione in workspace (spazi di lavoro) per organizzare meglio i progetti e i team all'interno di un'organizzazione:
Al momento della creazione dell'account viene generato un workspace "Default" associato all'organizzazione. Se la tua azienda ha un solo progetto o se stai solo testando l'API, potresti usare semplicemente il workspace predefinito.
### Creare un nuovo workspace Anthropic
Solo gli admin dell'organizzazione possono creare nuovi workspace:
1. Vai in Settings e clicca su "[Workspaces](https://console.anthropic.com/settings/workspaces)" nel menu laterale;
2. Nella pagina degli workspace, clicca sul pulsante "Add Workspace" in alto a destra;
3. Inserisci un nome per il nuovo workspace, ad esempio "Progetto Alpha" o "Team DataScience"; puoi anche selezionare un colore distintivo;
4. Clicca su Create. Il nuovo workspace apparirà nell'elenco.
### Gestire i workspace Claude
* Puoi modificare il nome o il colore di un workspace esistente cliccando sull'icona con i tre puntini "…" accanto al workspace.
* Quando crei una chiave API, devi associarla a un workspace. Le chiavi API sono visibili e gestibili solo dagli utenti con ruolo Developer (o Admin) che hanno accesso a quel workspace.
* Grazie ai workspace, nella sezione Usage/Cost puoi filtrare l'uso e la spesa per singolo workspace.
I Workspaces ti permettono di strutturare l'utilizzo della console Anthropic in modo flessibile: puoi separarli per progetti, team o ambienti, garantendo ordine e controllo.
## Gestire i membri nella Claude Console
Per collaborare con il tuo team all'interno della console Claude accedi alla sezione [Members](https://console.anthropic.com/settings/members) (clicca su Settings > Members): da qui sei in grado di vedere tutti i membri invitati all'interno del team.
Se vuoi invitare nuovi membri
1. Clicca sul tasto "Invite";
2. Inserisci l'indirizzo email del membro del team; puoi inserire un indirizzo email per riga per invitare
3. Assegna un ruolo:
1. User: accesso base all'organizzazione.
2. Developer: può gestire chiavi API e integrazioni.
3. Billing: accesso alle informazioni di fatturazione.
4. Admin: pieno controllo sull'organizzazione e i membri (developer + billing).
4. Clicca su “Send Invites” per inviare l'invito. o gli inviti.
Quando si invita un membro, dopo avergli assegnato un ruolo organizzativo è possibile doverlo aggiungere ai singoli workspace (ad eccezione del default, a cui tutti i membri hanno accesso): developer e user devono essere assegnati come membri di specifici workspace per poter operare su di essi - admin e billing hanno invece accesso a tutti gli spazi di lavoro.
## 9. Rate limits e tier Anthropic Claude API
Ogni organizzazione API della Claude Console ha dei limiti di utilizzo tecnici predefiniti al fine di garantire un uso equo delle risorse:
* Limiti per tier: ogni tier ha specifici limiti di richieste e token per minuto. Puoi visualizzare i limiti attuali del tuo tier nella sezione Settings > [Limits](https://console.anthropic.com/settings/limits) della Claude console.
* Upgrade del tier: puoi visualizzare i dettagli dei requisiti per ciascun tier nella [documentazione di Anthropic](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). Qualora si necessiti di limiti ulteriormente più alti oltre il massimo ottenibile automaticamente – ad esempio per casi d’uso aziendali molto grandi – allora è necessario inoltrare una richiesta di aumento tramite la pagina Limits. Il team Anthropic valuterà la richiesta e potrà eventualmente approvare un tier più elevato.
### Prossimi passi
Dopo aver completato la configurazione della tua console Anthropic:
1. Copia la chiave API creata;
2. Accedi alla tua dashboard [AIsuru](https://www.aisuru.com/);
3. Utilizza la chiave API per [creare un nuovo modello in piattaforma](../crea-e-gestisci-le-configurazioni-dei-modelli.md).
# Mistral API: come gestire i 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 le chiavi API per l'integrazione con [AIsuru](https://www.aisuru.com/).
## **1. Registrazione su Mistral**
Per iniziare a usare Mistral AI Studio, è necessario 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, potrebbe essere richiesta una verifica; controlla la tua posta in arrivo e clicca sul link di conferma che Mistral ti invia per attivare l'account (un codice OTP o un link per effettuare direttamente il sign in);
3. Dopo la verifica, ti potrebbe essere richiesto di inserire alcune informazioni aggiuntive, ad esempio 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 tuo dominio email corrisponde a un’azienda già presente) e un **workspace** iniziale: assegna un **nome alla tua organizzazione** - ad esempio il nome della tua azienda o un nome progetto identificativo. Dopodiché verrà creato automaticamente un workspace predefinito con lo stesso nome (che potrai modificare in seguito se necessario).
Al termine della registrazione verrai indirizzato alla **dashboard di Mistral AI Studio**. Prima di utilizzare l’API, dovremo configurare la sezione di **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, accedi alle **impostazioni** della tua organizzazione;
2. Clicca sul tuo nome o sull’icona **profilo** (in alto a destra) e seleziona **Admin Settings** dal menu: verrai reindirizzato all’**Admin Console** di Mistral (sezione amministrativa);
3. Assicurati di aver selezionato la tua organizzazione (in alto a sinistra) e poi vai alla pagina **Organization Settings;**
4. Nella pagina di impostazioni dell'organizzazione, inserisci i dati della tua azienda. In particolare:
* **Nome dell'organizzazione**: il nome legale della tua azienda (di solito è precompilato con il nome inserito in fase di registrazione, modificalo se necessario);
* **Indirizzo completo**: inserisci l’indirizzo di fatturazione della sede aziendale (via, città, CAP, paese);
* **Partita IVA**: se la tua azienda ha una VAT, dovresti trovare un campo per il **Tax/VAT ID**; inserisci la Partita IVA aziendale **comprensiva del prefisso nazionale** (esempio: IT12345678901 per un'azienda italiana);
5. Verifica che 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 aziendali, dovrai aggiungere un **metodo di pagamento** valido per poter utilizzare i servizi Mistral:
1. Apri l’**Admin Console** di Mistral e, nel menu amministrativo, seleziona **Billing**.
2. **Aggiungi una carta di pagamento:** se è la prima configurazione, vedrai un pulsante **Add payment method** oppure **Complete setup**; cliccalo per iniziare la procedura di aggiunta di un metodo di pagamento;
3. Si aprirà un modulo sicuro in cui inserire i dati della tua carta aziendale:
* Numero della carta di credito o debito;
* Data di scadenza (formato MM/AA);
* Codice CVV/CVC (le 3 o 4 cifre di sicurezza);
4. Completa la procedura confermando i dati inseriti: 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 addebitati 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. Accedi all'[admin console di Mistral](https://admin.mistral.ai/) e premi su [Billing](https://admin.mistral.ai/organization/billing) nella colonna laterale;
2. Alla voce "Auto Recharge" premi sul tasto Update;
3. Abilita la checkbox "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: ricarica il conto di una certa cifra (in Euro);
2. When my balance goes below: effettua la ricarica quando il saldo scende sotto una certa cifra (sempre in Euro);
5. Clicca sul pulsante "Enable auto recharge".
## **4. Attivazione della fatturazione: scelta di un piano**
Mistral offre un modello di utilizzo dell’API basato su **piani a consumo**. Dopo aver aggiunto un metodo di pagamento, è necessario abilitare l'account all'uso dell'API selezionando uno dei piani disponibili.
La piattaforma Mistral AI Studio permette di scegliere se attivare un **piano gratuito** o uno a pagamento pay-as-you-go.
In questo scenario, dopo aver aggiunto la carta di pagamento, procedi così:
1. Vai alla sezione **Limits** dell'[admin console](https://admin.mistral.ai/);
2. Qui puoi scegliere il piano:
1. Experiment (Free) - un piano gratuito con limiti di utilizzo molto restrittivi e condivisione dei dati di utilizzo per il training di nuovi modelli; è ideale per test iniziali;
2. Scale (Pay-as-you-go) - un piano a consumo con limiti più elevati, adatto all'uso in produzione. Richiede di aver fornito i dettagli di pagamento e comporterà addebiti in base all'utilizzo effettivo (per token/modello, secondo il pricing di Mistral).
3. Dopo aver selezionato il piano, potrebbe esserti chiesto di **verificare il tuo numero di telefono**. Inserisci un numero valido e poi il codice OTP ricevuto via SMS per confermare (questo passaggio serve a Mistral per verificare l’affidabilità dell’account prima di sbloccare l’accesso a consumo).
Una volta completati questi passaggi, il tuo account sarà assegnato al piano scelto!
## **5. Come monitorare l'utilizzo e impostare limiti di spesa su Mistral AI Studio**
### **Monitoraggio dei consumi**
Puoi monitorare i consumi a livello di organizzazione e di workspace.
#### **Monitorare i consumi di uno workspace di Mistral AI Studio**
1. Accedi a [Mistral AI Studio](https://console.mistral.ai/) e clicca su "Workspace" nella barra laterale;
2. Assicurati di aver selezionato il workspace corretto (premi sul nome in alto a sinistra nel popup che si è aperto per cambiarlo);
3. Vai alla sezione "Usage" del popup;
4. Seleziona il mese (di default sarà selezionato il mese corrente, puoi selezionare qualsiasi mese a partire dalla data di creazione del workspace);
5. All'interno di questa sezione, puoi controllare:
1. Spesa totale (divisa in diverse categorie: completion, OCR, connectors, fine tuning, audio, ecc.);
2. Il costo giorno per giorno (totale e diviso nelle diverse categorie);
3. Il costo di ogni categoria (per ogni categoria, vedrai solo i modelli effettivamente utilizzati durante il mese, altrimenti vedrai la scritta "No usage in \[mese e anno]").
#### **Monitorare i consumi API dell'organizzazione di Mistral AI Studio**
Puoi vedere le stesse informazioni per l'intera organizzazione - aggregando, quindi, tutti gli workspace. Per farlo:
1. Accedi alla [console admin di Mistral AI](https://admin.mistral.ai/) e poi premi su [Usage](https://admin.mistral.ai/organization/usage) nella barra laterale;
2. Come prima, all'interno di questa pagina potrai selezionare il mese di riferimento e vedere il dettaglio di tutte le spese aggregate in maniera diversa (per categoria, per categoria/giorno e per categoria/modello).
### **Come impostare un limite di spesa**
Puoi impostare un limite di spesa solo a livello di organizzazione, non di workspace. Per impostarlo:
1. Accedi all'[admin console di Mistral AI](https://admin.mistral.ai/) e vai alla sezione [Limits](https://admin.mistral.ai/plateforme/limits);
2. All'interno della prima sezione (Organization limits) attiva il toggle "Monthly API spending limit";
3. Alla voce "Spending limit" inserisci il limite mensile di spesa in Euro e premi sul tasto "Update limit".
Al di sotto della sezione Spending limit troverai anche l'utilizzo del mese corrente rispetto al limite di spesa impostato.
## **6. Creazione di una chiave API**
Per utilizzare i servizi Mistral con AIsuru, è necessario creare una **chiave API** Mistral:
1. Nell’[AI Studio di Mistral](https://console.mistral.ai/home), nella barra laterale, clicca su [**API Keys**](https://console.mistral.ai/home?workspace_dialog=apiKeys): nel popup che si apre, vedrai le chiavi create all'interno del tuo workspace;
2. Per creare una nuova chiave, premi su "Create new key":
1. Inserisci un nome descrittivo (opzionale, ma consigliato);
2. Inserisci una data di scadenza per la tua chiave (opzionale);
3. Conferma tutto premendo su "Create new key";
3. Premi su "Copy key" per copiare la chiave API appena creata e conservala (viene mostrata solo una volta al momento della creazione).
### Come gestire le chiavi API di Mistral AI Studio
Puoi gestire le tue chiavi direttamente dalla pagina relative alle [chiavi API Mistral](https://console.mistral.ai/home?workspace_dialog=apiKeys): al suo interno, infatti, puoi vedere una tabella contenente le chiavi attive e quelle scadute. Per ogni chiave, puoi vedere:
* Nome: il nome descrittivo fornito in fase di creazione della chiave;
* Chiave: le quattro lettere finali della chiave per una rapida identificazione;
* Data di creazione;
* Data di scadenza ("Never" se non impostata per quella chiave).
Se hai molte chiavi, puoi usare la barra di ricerca per ricercarle in base al nome.
### Come cancellare una chiave API Mistral
Se, invece, vuoi cancellare una chiave, ti basterà:
1. Premere sull'icona del cestino (ultima colonna);
2. Premere su Confirm (comparirà al posto del cestino).
## **7. Gestione dei Workspaces (spazi di lavoro)**
Mistral consente di organizzare l’utilizzo in diversi **workspaces** (spazi di lavoro), analogamente ai progetti di altre piattaforme. Ciò è utile per separare attività, team o clienti all’interno della stessa organizzazione, garantendo maggiore controllo e ordine.
Al momento della creazione dell'account viene generata una Organizzazione di default e un workspace associato.
Creando workspaces aggiuntivi, puoi ad esempio separare l’utilizzo per progetti diversi, dipartimenti interni o clienti. Ogni workspace mantiene chiavi API, impostazioni e membri isolati dagli altri, permettendoti di gestire accessi e limiti in modo granulare all’interno della stessa organizzazione.
Nota: è possibile gestire più workspace sotto la stessa organizzazione - ciascuno avrà le proprie impostazioni indipendenti (chiavi API, membri, report di consumi).
{% hint style="success" %}
Se hai un solo progetto, potresti utilizzare soltanto il workspace predefinito.
{% endhint %}
### Creare un nuovo Workspace
Per creare nuovi workspace è necessario accedere, come admin alla [console admin di Mistral](https://admin.mistral.ai/organization/):
1. Clicca su [Workspaces](https://admin.mistral.ai/organization/workspaces) nella colonna laterale (da qui vedi tutti i tuoi workspace) e poi sul pulsante New workspace.
2. Nel menu che si apre:
1. Seleziona un'icona (corrispondente ad un'emoji tra quelle disponibili);
2. Inserisci un nome;
3. Scrivi una breve descrizione (opzionale);
4. Se utile, attiva la checkbox "Add all existing organization members to this workspace";
5. Infine, premi su "Create".
{% hint style="info" %}
Ricorda che puoi solamente 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 all’interno del tuo workspace Mistral e assegnare loro ruoli differenti con permessi adeguati.
Per aggiungere un nuovo membro nel tuo workspace, dovrai prima di tutto invitarlo all'interno della tua organizzazione:
1. Vai alla [console admin di Mistral](https://admin.mistral.ai/organization) e premi su Members nella colonna laterale;
2. Premi sul pulsante Invite members e nel popup che compare:
1. Scrivi l'email del membro del team (puoi anche scrivere più indirizzi separandoli con una virgola);
2. Seleziona il ruolo:
1. **Admin:** accesso completo all’organizzazione e ai workspaces; può gestire impostazioni, membri, fatturazione e ha tutti i privilegi degli altri ruoli.
2. **Billing:** accesso alle informazioni di **fatturazione** e ai pagamenti; può visualizzare ed editare i dati di billing, gestire i metodi di pagamento e vedere le fatture.
3. **Member:** ruolo base con accesso limitato; può utilizzare l’API e vedere le proprie risorse, ma non può creare chiavi API né modificare impostazioni critiche.
3. Dopo aver confermato, il sistema invierà agli indirizzi specificati un’email con il link per accettare l’invito e unirsi al workspace. Fino a quando l’invito non viene accettato, il membro apparirà nello stato "pending" nell’elenco dei membri.
3. In base al ruolo scelto, potrebbe essere necessario invitare il membro del team anche nei singoli workspace. Per farlo:
1. Accedi all'[AI Studio di Mistral](https://console.mistral.ai/) e premi sulla voce [Workspace](https://console.mistral.ai/home?workspace_dialog=general) nella barra laterale;
2. Seleziona il workspace su cui vuoi lavorare: premi sul nome del workspace in alto a sinistra nel popup che si è aperto per cambiarlo;
3. Vai alla voce Members e clicca su Add Members:
1. Seleziona il membro dell'organizzazione da aggiungere al workspace dal menu a tendina;
2. Specifica il ruolo (di default è "Member", ma puoi selezionare anche "Admin");
3. Infine, clicca sul pulsante "Add Member" per confermare.
In qualsiasi momento, puoi rimuovere i singoli membri dall'organizzazione (dall'[admin console di Mistral](https://admin.mistral.ai/)) o dai singoli workspace (all'interno di [Mistral AI Studio](https://console.mistral.ai/)).
## **9. Limiti di utilizzo (rate limits) dei modelli Mistral API**
Come tutti i provider di AI generativa, anche Mistral prevede dei limiti di utilizzo che possono variare in base all'utilizzo e alla spesa totale dell'organizzazione (o, in caso di forte utilizzo, anche in base agli accordi commerciali con Mistral AI).
Puoi controllare i rate limits all'interno dell'[admin console di Mistral](https://admin.mistral.ai/organization) (non dentro Mistral AI Studio):
1. Accedi alla sezione [Limits](https://admin.mistral.ai/plateforme/limits) della console admin di Mistral;
2. Oltre a poter controllare i consumi e il limite di spesa mensile, scendendo più sotto puoi vedere altre tre sezioni:
1. Rate limit per second: è il limite di richieste che puoi fare in un secondo. Per semplificare, possiamo dire che 1 richiesta = 1 messaggio, ma in realtà un messaggio su AIsuru potrebbe consumare fino a 10 richieste.
2. Completion rate limits per model: in questa sezione, trovi i diversi modelli (che puoi filtrare con la barra di ricerca) che Mistral mette a disposizione. Per ogni modello, troverai:
1. Tokens per Minute (TPM): il numero massimo di token al minuto che Mistral mette a disposizione per la tua organizzazione per quello specifico modello.
2. Tokens per Month: il numero massimo di token mensili che Mistral mette a disposizione per la tua organizzazione per quello specifico modello.
3. Fine-tuning limits: sono i limiti specifici per le attività di fine tuning all'interno di Mistral AI Studio. I modelli fine-tuned di Mistral possono, poi, essere utilizzati su AIsuru.
### Come aumentare i rate limits di modelli Mistral API
Puoi chiedere un aumento dei limiti di utilizzo dei modelli Mistral AI contattando direttamente il supporto commerciale di Mistral. Puoi farlo andando nella sezione [Contact us di Mistral AI](https://mistral.ai/contact).
## **Prossimi passi**
Dopo aver completato la configurazione della tua console Mistral AI:
1. Copia la chiave API creata;
2. Accedi alla tua dashboard [AIsuru](https://www.aisuru.com/);
3. Utilizza la chiave API per [creare un nuovo modello in piattaforma](../crea-e-gestisci-le-configurazioni-dei-modelli.md).
# Azure AI Foundry: come usare i modelli OpenAI e gestire accessi e costi
{% hint style="warning" %}
Al fine di evitare conflitti tra account, suggeriamo di eseguire tutte le operazioni da **scheda in incognito** o da un nuovo “profilo” del browser (se applicabile, questo permette di non avere conflitti per cache e cookies).
{% endhint %}
## 1. Registrazione di un Tenant Azure (per chi non ha Microsoft 365)
Se la vostra organizzazione dispone già di Microsoft 365 (M365), significa che esiste già un tenant Azure Active Directory (Azure AD/Microsoft Entra ID) aziendale, e potete utilizzarlo per Azure. In caso contrario, è necessario registrare un nuovo tenant Azure. Ecco come procedere:
* Visitate il sito web di Azure ([azure.microsoft.com](https://azure.microsoft.com/)) e create un account. Utilizzate un indirizzo email aziendale per la registrazione. Il processo vi guiderà nella creazione di un nuovo directory/tenant Azure (denominato tenant Azure AD)
* Dopo aver creato l’account, effettuate l’accesso al portale di Azure con le credenziali appena configurate. Confermate che il tenant Azure AD creato è selezionato (in alto a destra, generalmente potete vedere il nome del directory/tenant corrente ed eventualmente cambiarlo se ne avete più di uno)
Nota: Il tenant Azure AD è l’entità che rappresenta la vostra 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 utilizzare servizi avanzati come Azure OpenAI, è obbligatorio avere una sottoscrizione Azure a pagamento (ad esempio Pay-As-You-Go o un piano enterprise).
Le sottoscrizioni gratuite o trial non sono abilitate all’uso del servizio Azure OpenAI, quindi bisogna attivare un piano a pagamento fin da subito.
Se avete appena creato l’account Azure, durante la registrazione potreste aver attivato una trial con crediti gratuiti. Accedete alla sezione Sottoscrizioni nel portale Azure e, se la vostra sottoscrizione è indicata come Free Trial o Azure for Students, effettuate l’upgrade a Pay-As-You-Go. Vi verrà chiesto di inserire un metodo di pagamento (carta di credito o altri) e accettare che, esauriti eventuali crediti iniziali, i consumi vengano addebitati.
In alternativa, se nel tenant non c’è alcuna sottoscrizione, potete crearne una nuova. Dal portale Azure, andate su Sottoscrizioni e cliccate + Aggiungi (Add). Seguite la procedura guidata scegliendo Pay-As-You-Go come tipo di offerta e fornite i dettagli di fatturazione richiesti.
Una volta attivata la sottoscrizione a pagamento, assicuratevi che lo stato sia attivo. Ora siete pronti a creare risorse Azure su questa sottoscrizione.
Nota: Assicuratevi di avere i permessi Owner/Proprietario o Contributor sulla sottoscrizione appena creata (generalmente, chi crea la sottoscrizione ne è Owner di default). Questo è necessario per poter creare e gestire le risorse nei passi successivi.
## 3. Creazione di un Resource Group per le risorse AI
Un Resource Group (Gruppo di risorse) è un contenitore logico in Azure dove raggruppare le risorse correlate. Creeremo un Resource Group dedicato a tutte le risorse AI (OpenAI, storage, ecc.) del progetto. È buona prassi utilizzare nomi coerenti e pianificati, dato che i nomi delle risorse non possono essere modificati dopo la creazione.
Procedura per creare un Resource Group:
1. Nel portale di Azure, nel menu di sinistra (o nel menu in alto a sinistra ≡), selezionate Resource groups
2. Cliccate sul pulsante + Create. Si aprirà il form di creazione
3. Nel campo Subscription (Sottoscrizione), assicuratevi di selezionare la sottoscrizione a pagamento attiva su cui volete creare le risorse AI
4. Nel campo Resource group name (Nome), inserite un nome identificativo. Consigliamo di includere un riferimento a AIsuru. _Ad esempio, potreste usare Prod-AIsuru come nome del Resource Group. Evitate spazi e caratteri speciali: usate lettere, numeri e eventualmente il trattino - come separatore_
5. Nel campo Region scegliete un datacenter preferibilmente in Europa. Ad esempio, Sweden Central o West Europe se disponibili. Questo garantisce che i dati rimangano all’interno dell’UE\
\
&#xNAN;_Nota: assicuratevi che la regione scelta supporti i servizi Azure OpenAI necessari. Non tutte le regioni europee potrebbero avere tutti i modelli OpenAI disponibili._
6. (Opzionale) Potete aggiungere tag per organizzare le risorse. Ad esempio, cliccando su Next: Tags potreste aggiungere una coppia Nome-Valore come Name: Infrastructure e Value: AzureAI (o “LLM”) per classificare questo gruppo come infrastruttura AI. I tag aiutano in seguito a filtrare le risorse e fare analisi dei costi trasversali
7. Cliccate su Review + create, verificate che i dettagli siano corretti (nome, area, sottoscrizione, tag, ecc.), quindi confermate cliccando Create. Dopo pochi secondi il nuovo Resource Group verrà creato
Consiglio: **stabilite una naming convention coerente per tutte le risorse del progetto**. _Ad esempio, usando un prefisso comune (come il nome dell’azienda o acronimo del progetto) e suffissi che indicano il tipo di risorsa: es. Prod-AIsuru per il resource group, e poi lo stesso prefisso per le risorse all’interno (es: Prod-AIsuru-Hub, Prod-AIsuru-Service, prodaisurustorage, ecc.)._
Questo facilita l’identificazione delle risorse e indica chiaramente a quale progetto appartengono. Ricordate che molti nomi di risorse Azure non possono essere modificati dopo la creazione, quindi pianificateli attentamente.
## 4. Creazione di un Azure AI Hub tramite Azure AI Foundry
Una volta predisposto il Resource Group, procediamo con la creazione dell’Azure AI Hub, ovvero la risorsa principale di Azure AI Foundry. L’hub funge da contenitore/gestore per i progetti AI e consente di collegare i vari servizi (OpenAI, archiviazione, sicurezza) necessari.
Durante la creazione dell’AI Hub, avremo l’opportunità di creare contemporaneamente anche le risorse collegate (servizio Azure OpenAI, account Storage e Key Vault), che affronteremo in dettaglio al punto successivo.
Per creare un nuovo Azure AI Hub:
1. Nel portale di Azure, cercate Azure AI Foundry usando la barra di ricerca globale in alto (digitate “Azure AI Foundry” e selezionate il risultato appropriato). In alternativa, dal menu principale, navigate nelle categorie di servizi AI
2. Nella pagina Azure AI Foundry, cliccate sul pulsante + Create Azure AI(in alcuni casi potrebbe apparire come + New Azure AI). Quindi, scegliete di creare un Hub (quando richiesto il tipo di risorsa da creare, selezionate Hub anziché Project, poiché vogliamo prima creare l’hub centralizzato)
3. Inserire i dettagli dell’Hub (Basics): si aprirà il form di creazione per l’Azure AI Hub. Compilate i campi fondamentali:
1. Subscription: selezionate la sottoscrizione a cui addebitare i costi (quella creata precedentemente)
2. Resource Group: selezionate il Resource Group dedicato (creato al passo precedente, ad es. Prod-AIsuru)
3. Region: scegliete la stessa area geografica scelta per il Resource Group, per coerenza (es. Sweden Central o quella che avete usato, così tutte le risorse rimarranno in EU)
4. Name: date un nome all’Hub. Seguite la convenzione scelta: tipicamente il nome del Resource Group seguito da “-Hub”. Ad esempio: Prod-AIsuru-Hub. (Questo è il nome della risorsa Azure AI Hub che verrà creata)
5. Friendly Name: potete inserire un nome descrittivo più leggibile, ad esempio “Prod AIsuru Hub aziendale”. Questo è utile per riconoscere l’hub nel portale, ma non è l’ID della risorsa
6. Default project resource group: specificate quale Resource Group dovranno usare di default i progetti creati in questo Hub. Solitamente, inserite di nuovo il nome del Resource Group creato al passo 3 (Prod-AIsuru). Questo fa sì che eventuali risorse future create dai progetti (es. container, workspace, ecc.) vengano anch’esse allocate in quel gruppo
4. Collegare un servizio Azure OpenAI: nella stessa schermata di creazione dell’Hub, troverete un campo per collegare un servizio AI, ad esempio Azure OpenAI Service. Poiché non ne abbiamo ancora uno, dobbiamo crearne uno nuovo:
1. Cliccate sul link Create New sotto il campo Azure OpenAI Service (potrebbe essere indicato come Azure AI Services). Si aprirà un pannello laterale per creare un nuovo servizio Azure OpenAI
2. Nel campo Name di questo pannello, inserite un nome per la risorsa OpenAI. Seguite la convenzione: ad esempio usate il nome del Resource Group seguito da “-Service” (es: Prod-AIsuru-Service)
3. Assicuratevi 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. Cliccate Save per confermare la creazione della risorsa Azure OpenAI Service collegata
5. Configurare lo Storage Account: Dopo aver salvato il collegamento del servizio OpenAI, passate alla scheda successiva nella procedura di creazione dell’Hub. Dovrebbe esserci una sezione Storage:
1. Cliccate su Next: Storage se la procedura guidata non ci è già arrivata
2. Qui viene richiesto di selezionare un Storage Account. Cliccate su Create New sotto il campo Storage account per crearne uno dedicato. Si aprirà un pannello laterale per creare lo storage:
1. Name: inserite un nome per lo Storage Account. Questo nome deve essere univoco a livello globale e ha restrizioni (solo lettere minuscole e numeri, lunghezza compresa tra 3 e 24 caratteri, niente spazi o trattini). _Un approccio è usare il prefisso del progetto senza trattini. Ad esempio, se il resource group è Prod-AIsuru, potreste usare qualcosa come prodaisurustorage (o simile, mantenendo tutto minuscolo e senza -)_
2. Replication: scegliete il livello di ridondanza desiderato. Per ambienti di test o iniziali, potete selezionare Locally-redundant storage (LRS), che mantiene tre copie dei dati all’interno dello stesso data center (opzione base)
3. Lasciate eventuali altri parametri ai default (ad es. Performance su Standard). Cliccate Save per creare lo Storage Account
6. Dopo lo storage, la procedura guidata passerà alla sezione Key vault:
1. Cliccate su Next: Networking se richiesto, e configurate l’accesso di rete. In genere, per iniziare, potete lasciare l’hub in modalità Public access (Public endpoint) così com’è (permette all’hub e ai servizi di essere gestiti senza richiedere una rete virtuale dedicata; potete limitare l’accesso in seguito se necessario)
2. Cliccate Next: Encryption
3. Nella sezione Encryption, lasciate deselezionata l’opzione che richiede l’uso di una chiave gestita dal cliente (Customer-managed Key). In questo modo, verranno usate le chiavi gestite da Microsoft per crittografare i dati.
4. Cliccate Next: Identity
5. Nella sezione Identity potete lasciare le impostazioni di default. Cliccate Next: Tags
6. Arrivati alla sezione Tags, avete la possibilità di assegnare tag alla risorsa Hub e alle risorse collegate che state creando. Potete ad esempio utilizzare: Name = Infrastructure e Value = LLM (variabile a seconda delle necessità). Questi tag vi aiuteranno a identificare e filtrare le risorse (ad esempio nei report di costi)
7. Cliccate Next: Review + create per visualizzare il riepilogo finale
7. Rivedere e creare l’Azure AI Hub: Nel form di riepilogo, controllate 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 e del Key Vault, ecc. In particolare verificate che la Region sia corretta (conforme alle vostre esigenze di data residency) e che i nomi rispettino la convenzione scelta
8. Se tutto è corretto, cliccate Create per avviare il deployment
9. Azure inizierà a creare l’AI Hub e, contestualmente, il servizio Azure OpenAI, il Key Vault e lo Storage Account associati (se li avete creati nel wizard). Questa operazione può richiedere qualche minuto. Al termine, vedrete comparire nel Resource Group tutte le nuove risorse (ad esempio: Prod-AIsuru-Hub, Prod-AIsuru-Service per OpenAI, prodaisurustorage, Prod-AIsuru-KV per il Key Vault, ecc.)
Una volta completata la creazione, avete un Azure AI Hub configurato con i servizi necessari. L’hub è ora pronto per ospitare uno o più progetti Azure AI Foundry al suo interno.
**Importante**: Abbiamo scelto di creare l’Azure AI Hub manualmente per poter specificare tutti i dettagli (come regione EU e nomi personalizzati). In alternativa, Azure AI Foundry permette anche di creare un Foundry project direttamente, creando automaticamente un hub predefinito. Tuttavia, per ambienti aziendali è consigliabile avere il controllo esplicito sull’Hub (hub-based project) per centralizzare la gestione delle risorse e configurazioni.
### 4.5. Creazione delle risorse collegate: Azure OpenAI Service, Storage Account, Key Vault
Questo punto è in parte già coperto nel processo del passo 4, poiché durante la creazione dell’AI Hub abbiamo provveduto a creare le risorse collegate. Rivediamo brevemente ciascuna di queste e assicuriamoci che tutto sia configurato correttamente:
* **Azure OpenAI Service**: è il servizio che 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. Potete verificarne la presenza andando nel Resource Group e controllando che vi sia una risorsa di tipo Azure OpenAI (o Cognitive Services con provider Microsoft.OpenAI). Aprendola, nella pagina Panoramica dovreste vedere le informazioni come l’endpoint URL e la regione\
\
&#xNAN;_Nota: Se in fase di creazione dell’Hub aveste deciso di non creare subito il servizio OpenAI (saltando quel collegamento), potete sempre crearlo in un secondo momento manualmente. In tal caso, andate su Create a resource nel portale, cercate Azure OpenAI, e create il servizio selezionando la stessa sottoscrizione, Resource Group e area. Dovreste comunque passare per l’approvazione Microsoft se richiesto, ma attualmente per account Pay-As-You-Go compatibili la creazione è diretta senza form esterni_
* **Storage Account**: abbiamo creato un account di archiviazione (es. prodaisurustorage) per conservare dati generati o richiesti dall’AI Hub/Foundry (ad esempio file di configurazione, log, dataset per fine-tuning, ecc.). Verificate che lo storage sia stato creato correttamente nella regione prevista e con la replica LRS. Non serve configurare nulla di particolare a questo punto, ma assicuratevi di non eliminare questo storage: è fondamentale per il funzionamento del progetto AI
* **Key Vault**: è stato creato un Key Vault (es. Prod-AIsuru-KV) per conservare in sicurezza le chiavi e i segreti legati al progetto AI. Ad esempio, la chiave API dell’Azure OpenAI verrà custodita nel Key Vault. Anche qui, non occorre una configurazione manuale immediata, ma potete controllare nella sezione Secrets del Key Vault che (dopo il deployment del modello) compaiano le chiavi necessarie\
\
&#xNAN;_Nota: Il Key Vault e l’Azure AI Hub sono connessi tramite identità gestita, permettendo al Foundry di recuperare le chiavi senza esporle direttamente._
In sintesi, al termine del passo 4 avrete già tutte queste risorse pronte. Assicuratevi solo che siano tutte presenti nel Resource Group e in stato Attivo. Se qualcosa risultasse non creato o in errore, potrebbe essere necessario ricrearlo o controllare i permessi (ad esempio, per il servizio OpenAI, verificare di avere l’accesso al servizio nella 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 dove effettuerete realmente le operazioni di sviluppo, deployment di modelli, ecc. Ecco i passi da seguire:
1. **Accedere all’Azure AI Hub appena creato**: dal portale Azure, navigate nel Resource Group che avete creato e cliccate sulla risorsa Azure AI Hub (es: Prod-AIsuru-Hub). Si aprirà la pagina di dettaglio dell’hub. In questa pagina dovreste vedere, tra le varie informazioni, il pulsante Launch Azure AI Foundry
2. Cliccate su **Launch Azure AI Foundry**. Questo aprirà la console web specifica di Azure AI Foundry associata al vostro hub. È una sorta di interfaccia dedicata dove gestire i progetti AI
3. **Creare un nuovo progetto**: se è la prima volta che accedete e non esistono progetti nell’hub, Azure AI Foundry vi mostrerà un messaggio del tipo “You’ll need a project to keep working”. In questa schermata, dovete fornire un nome per il nuovo progetto:
1. Nel campo Project name (Nome del progetto) inserite un nome identificativo. Seguendo la nostra convenzione, potete usare il nome del Resource Group con il suffisso “-Project”. Ad esempio: Prod-AIsuru-Project. _Assicuratevi che sia selezionato l’hub corretto, dovrebbe esserci solo quello che avete creato_
2. Cliccate su Create a project per confermare
4. **Attendere la configurazione**: il progetto verrà creato all’interno dell’hub e potrebbe impiegare qualche istante per inizializzare l’ambiente. Una volta creato, verrete indirizzati alla vista del progetto Azure AI Foundry
5. **Verificare la struttura del progetto**: nella console di Azure AI Foundry, dovreste ora vedere il nome del vostro progetto. Sul lato sinistro dell’interfaccia, c’è un menu con diverse sezioni (ad esempio: Overview, Models + endpoints, Data, Prompt flow, etc.). Assicuratevi di riconoscere i principali elementi:
1. Overview: la pagina iniziale del progetto con un riassunto e collegamenti rapidi
2. Models + endpoints: la sezione dove gestirete i modelli deployati e gli endpoint API
3. Management Center: dove impostare parametri di progetto, accessi, quote, ecc.
A questo punto, il vostro progetto Azure AI è configurato e pronto. Nel prossimo passo procederemo al deployment di un modello OpenAI nel progetto.
## 6. Deployment di un modello OpenAI (es. GPT-4o-mini) su Azure AI Foundry
Con il progetto creato, possiamo effettuare il **deployment di un modello OpenAI**, rendendolo disponibile tramite endpoint per le applicazioni. Azure AI Foundry semplifica questo processo con pochi click. Prendiamo ad esempio il modello GPT-4o-mini, ma i passi sono simili per altri modelli. Procedura per effettuare il deployment di un modello nel progetto:
1. **Accedere alla sezione Models + endpoints**: nel pannello di sinistra della console Azure AI Foundry (all’interno del vostro progetto), cliccate su Models + endpoints. Qui vedrete la lista di modelli ed endpoint (inizialmente sarà vuota poiché non avete ancora deployato nulla)
2. In alto nella pagina, cliccate su **+ Deploy model**. Verranno presentate opzioni, scegliete Deploy base model (deploy di un modello base pre-addestrato senza fine-tuning iniziale)
3. **Selezionare il modello**: apparirà un elenco di modelli disponibili. Scorrete e selezionate GPT-4o-mini (o un altro modello a vostra scelta). Potete usare la barra di ricerca per trovarlo se l’elenco è lungo
4. Cliccate **Confirm** per passare alla schermata successiva
5. Personalizzare la capacità (opzionale): nella schermata di configurazione del deployment, potrebbe comparire un pulsante Customize accanto a parametri come la Capacity o il Rate limit. Cliccatelo per regolare le impostazioni avanzate:
1. Tokens per Minute Rate Limit: impostate il valore massimo consentito. verificate il limite mostrato e se possibile impostatelo al massimo disponibile, a meno che non vogliate intenzionalmente limitarlo
2. Content filter: se presente, potete lasciare attivo il filtro contenuti (di solito attivo per default per moderare output indesiderati)
6. Cliccate sul pulsante **Deploy** per avviare il deployment del modello scelto con le configurazioni indicate. Azure inizierà il provisioning dell’infrastruttura necessaria e la preparazione del modello. Questo processo potrebbe richiedere alcuni minuti
7. Una volta terminato, nella sezione Models + endpoints dovreste vedere il modello nell’elenco, con uno stato indicato come Deployed/Running (o “In esecuzione”)
8. **Deployare altri modelli** (facoltativo): Se avete bisogno di più modelli, potete ripetere la procedura per ciascun modello aggiuntivo. L’hub/progetto supporta più deployment contemporaneamente, tenendo presente che ognuno consumerà quote di risorse e budget separatamente
_Nota: I modelli OpenAI su Azure vengono continuamente aggiornati e ampliati. Scegliete il modello in base alle vostre esigenze assicuratevi che sia supportato nella regione del vostro servizio Azure OpenAI._ [_Potete controllare la documentazione Azure per la lista di 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. Reperire Endpoint, Chiave API e Nome del modello
Dopo aver deployato un modello, avrete bisogno di tre informazioni chiave per utilizzare il modello via API: l’Endpoint URL, la Chiave API e il Nome del modello (deployment name).
Ecco come ottenerle:
1. Accede alla risorsa all’interno dell’Azure AI Foundry
2. All’interno dell’homepage della risorsa è possibile vedere:
1. Chiave API: copiatela e tenetela da parte
2. L’endpoint: su AIsuru andrà inserito un endpoint differente, ma copiate e tenete da parte il nome del servizio (es. se l’endpoint è https://Prod-AIsuru-service.openai.azure.com/ allora dovrete salvare “Prod-AIsuru-service”)
3. Per ottenere, invece, il nome modello è necessario accedere alla sezione Models + endpoints del progetto: all’interno della tabella, la seconda colonna dovrebbe indicare il nome modello di tutti i modelli deployati precedentemente
## 8. Rilascio su AIsuru
Per rilasciare un nuovo modello su AIsuru è necessario inserire i seguenti parametri:
* API Key: incollare l’API key salvata precedentemente
* Modello: incollare il nome modello salvato precedentemente
* Endpoint: sostituire il nome del servizio con la stringa salvata al punto precedente e il nome modello con il nome modello salvato 👉 https://{nome\_servizio}.services.ai.azure.com/openai/deployments/{nome\_modello}
È possibile seguire la guida all’interno della documentazione di [AIsuru](https://app.gitbook.com/u/cAjZyYfE1LVsEPlsvlJqalQAVq13) per essere guidati passo-passo nella [creazione e nel rilascio dei modelli](../crea-e-gestisci-le-configurazioni-dei-modelli.md).
## 9. Gestione degli utenti interni all’organizzazione Azure (creazione e organizzazione utenti)
In un contesto aziendale, probabilmente più persone vorranno accedere o collaborare al progetto Azure AI (sviluppatori, data scientist, ecc.). È importante quindi sapere come creare nuovi utenti nel tenant e come assegnare loro i permessi adeguati sulle risorse (hub, progetto, ecc.). Ecco le linee guida.
### Aggiungere nuovi utenti interni nel tenant Azure
1. Nel portale Azure, cercate Azure Active Directory (o Utenti e gruppi se avete scorciatoie). Andate nella sezione Users (Utenti) del vostro tenant
2. Cliccate + New user (Nuovo utente). Compilate i dettagli richiesti: nome dell’utente, nome utente (che diventerà la login, tipicamente formattato come un email user@dominio.onmicrosoft.com o il dominio aziendale se presente), e scegliete un metodo per la password (potete auto-generarla e poi condividerla in modo sicuro con l’utente)\
\
&#xNAN;_Se la vostra azienda usa un dominio personalizzato in Azure AD, potete assegnare l’utente a quel dominio, altrimenti rimarrà sul dominio onmicrosoft.com di default._
3. Cliccate Create per creare l’utente. Fornite all’utente le credenziali create (nome utente e password temporanea) affinché possa accedere.
### Assegnare gli utenti a gruppi (opzionale)
Se avete molti utenti, potete creare Azure AD Groups e inserirvi gli utenti, per poi assegnare permessi ai gruppi invece che ai singoli.
#### Come assegnare ruoli
L'assegnazione dei ruoli può essere gestito a livello di:
* Gruppi di risorse (resource groups)-> consente l'accesso a tutte le risorse al suo interno (inclusi Hub, OpenAI, storage, ecc.)
* Singole risorse (resources) -> consente l'accesso alla specifica risorsa
Per assegnare un ruolo:
1. Andate sulla risorsa o resource group interessato nel portale Azure
2. Selezionate Access control (IAM) dal menu. Cliccate + Add role assignment
3. Scegliete il ruolo adatto (es. Contributor, Reader, ecc.), quindi cercate l’utente o gruppo nella casella Assign to e confermate - l’assegnazione sarà effettiva dopo pochi minuti
Oltre ai ruoli, Azure AI Foundry permette di specificare l’accesso a progetti e hub direttamente dalla sua dashboard: è sufficiente accedere al Management Center del vostro progetto, ed accedere alla sezione “Users” dell’Hub o del progetto, a seconda delle necessità.
In genere, se un utente ha accesso (RBAC) all’hub o al resource group e ai servizi collegati, dovrebbe poter lanciare la Foundry ed accedere al progetto. Se, però, Foundry richiede esplicitamente di aggiungere membri:
1. Accedere al Management Center del progetto > Users (del progetto o dell’hub, a seconda delle necessità)
2. Aggiungere l’utente e assegnare il ruolo
3. Salvate le modifiche
-> L’utente dovrebbe ora vedere il progetto nell’Azure AI Foundry portal e potervi accedere.
## 10. Monitoraggio e budget
È fondamentale impostare un monitoraggio attento dei costi e meccanismi di allerta o limitazione per evitare sforamenti di budget.
### Analisi dei costi
1. Nel portale Azure, recatevi su Cost Management + Billing
2. Da qui, potete selezionare la sottoscrizione interessata (o anche filtrare per Resource Group Prod-AIsuru se volete isolare i costi di questo progetto) e utilizzare Cost analysis (Analisi costi) - che vi mostrerà quanto state spendendo e una ripartizione per servizio
### Budget
La funzionalità Budgets vi consente di impostare un budget per un determinato scope (sottoscrizione, resource group, servizio). il raggiungimento o superamento del budget non comporta l’automatico blocco dell’operatività: Azure valuterà la spesa periodica e vi manderà avvisi al superamento delle soglie definite.
Per impostare un budget mensile per la sottoscrizione o per il resource group del progetto:
1. Andate su Cost Management > (Monitoring >) Budgets nel portale Azure (dopo aver selezionato la sottoscrizione o il RG appropriato come ambito)
2. Cliccate + Add
3. Inserite un nome per il budget (es. Budget-ProgettoAI)
4. Selezionate il reset period (es. il budget si resetta ogni mese)
* Impostate creation date ed expiration date
* Impostate l’amount (ad esempio, se desiderate non superare 1000 € al mese per il progetto AI, impostate 1000 come budget mensile)
* Configurate le alert: potete impostare soglie di allarme, ad esempio al 50%, 80%, 100% del budget. Per ciascuna soglia, impostate che vi invii una notifica email (potete inserire gli indirizzi email opportuni, come quello dell’amministratore IT, project manager, ecc.). Le notifiche vi avviseranno quando la spesa stimata raggiunge quelle percentuali
* Salvate il budget
## 11. Accorgimenti finali e best practices
* Come già sottolineato, una convenzione di nomi consistente salva da tanta confusione. Applicatela a tutte le risorse: es. nomi delle risorse Azure, nomi dei deployment dei modelli, nomi dei progetti, e persino agli identificativi di utenti/gruppi dedicati. Documentate questa convenzione in modo che il team la segua uniformemente.
* Anche se abbiamo impostato il rate limit al massimo consentito per il modello, Azure può avere limiti superiori. Informatevi sulle quote predefinite e, se il vostro caso d’uso lo richiede, potete chiedere un innalzamento di quota aprendo un ticket al supporto Azure.
* Utilizzando data center europei vi assicurate che i dati in transito e a riposo per il servizio Azure OpenAI rimangano in ambito UE, aiutando con la compliance al GDPR e policies aziendali. Verificate sempre le ultime informazioni Microsoft sulla data residency dei servizi AI, specialmente se maneggiate dati sensibili.
* In caso di problemi, consultate la documentazione ufficiale Microsoft e la community. Il portale di Azure offre diagnosi di base (es. log delle richieste fallite se abilitate, metriche di uso). Potete anche aprire ticket al supporto Azure se riscontrate malfunzionamenti del servizio.
---
hidden: true
---
# Google Vertex: come aggiungere Claude
Guida WIP
# Cosa fare in caso di problemi
AIsuru fornisce diversi indicatori e soluzioni per gestire eventuali problemi 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 possano occasionalmente riscontrare problemi temporanei. Solitamente questi problemi si risolvono entro 30 minuti, ma in alcune occasioni la risoluzione può richiedere diverse ore. I problemi possono essere limitati ad un modello specifico o possono impattare tutti i modelli del provider.
Non è necessario alcun intervento da parte tua: il servizio riprenderà automaticamente.
{% hint style="info" %}
**AIsuru non può risolvere i problemi dei singoli provider**, ma fornisce comunque gli strumenti per accorgersi dei disservizi ed implementare rapidamente una soluzione.
{% endhint %}
#### Indicatore di problemi con i provider
Quando interagisci con un Agente che utilizza un provider che sta riscontrando problemi vedrai un'icona vuota con bordi rossi ⚠️ che segnala potenziali problematiche.
Questo indicatore appare automaticamente quando il provider selezionato sta avendo difficoltà.
#### Come cambiare provider in caso di problemi
AIsuru non può risolvere i disservizi dei singoli provider, ma ti permette comunque di evitare disservizi ai tuoi utenti in caso di problemi. Ti basterà, infatti, [**selezionare un diverso provider e modello**](../attiva-lia-generativa-e-cambia-il-modello.md#come-cambiare-il-modello-del-tuo-twin) **per permettere ai tuoi utenti di interagire con il tuo Agente**.
### Tempo di elaborazione della risposta
Un altro problema comune riguarda il tempo di elaborazione delle risposte. **Ogni richiesta all'IA generativa ha un limite massimo di 90 secondi** per completare l'elaborazione. Se il modello non riesce a fornire una risposta entro questo 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".
Questo limite di tempo è una misura di sicurezza per evitare che l'Agente rimanga bloccato in elaborazioni troppo lunghe, garantendo una migliore esperienza utente complessiva.
# 4. Condivisione e pubblicazione
La condivisione è un passo cruciale per far brillare il tuo Agente AI nel mondo digitale. AIsuru offre una varietà di modalità per distribuire e integrare il tuo assistente virtuale in diversi contesti, permettendoti di raggiungere il tuo pubblico in modi innovativi e coinvolgenti.
In questa sezione, esploreremo le seguenti sezioni:
1. **Creazione di un layout**
1. Scopri dove trovare tutti i campi necessari;
2. Impara cosa puoi modificare e come personalizzare l'aspetto del tuo Agente AI.
2. **Gestione dei layout**
1. Comprendi i vantaggi di gestire layout multipli per lo stesso Agente;
2. Configura ruoli specifici e domande iniziali e o ttimizza l'esperienza per chat o totem.
3. **Codice di incorporazione**
1. Analizza in dettaglio il codice di embed e i suoi campi;
2. Confronta l'uso di script vs iframe per l'integrazione.
4. **Modalità di condivisione**
1. Link: per una condivisione rapida e diretta;
2. Siti web: integra l'Agente AI nel tuo spazio online;
3. Blog WordPress: arricchisci i tuoi contenuti con interazioni AI;
4. Dispositivi fisici e totem: porta l'AI negli spazi pubblici;
5. Spazi Virtuali (VR e AR): crea esperienze immersive.
Seguendo questa guida, sarai in grado di portare la tua AI conversazionale ovunque desideri, aprendo nuove possibilità di interazione 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 AI!
, che, se premuto, mostra i contenuti che hanno aiutato AIsuru a rispondere;
4. **Mostra il ragionamento**: se utilizzi un modello con capacità di reasoning puoi decidere di mostrare il ragionamento con l'utente finale durante la conversazione. Per impostazione predefinita, il ragionamento è visibile solo nella scheda "Conversazioni" per chi gestisce l'Agente, poiché può contenere informazioni sensibili o logiche interne;
5. **Condividi**: abilita le opzioni di condivisione direttamente dal widget, permettendo agli utenti di:
* Condividere l'Agente tramite link diretto;
* Condividere la conversazione corrente con un link specifico;
* Utilizzare piattaforme social integrate (Facebook, Twitter, LinkedIn, WhatsApp, Telegram, Email);
* Generare e scaricare QR code per la condivisione.
6. **Caricamento file**: se attivo, l'utente potrà caricare contenuti durante la conversazione cliccando sull'apposito pulsante. Quando attivato, l'utente può scegliere tra:
* **Carica documento**: per file testuali (PDF, DOC, TXT) che verranno analizzati dall'Agente
* **Carica immagine**: per immagini (JPG, PNG, GIF) che verranno analizzate dall'IA per fornire descrizioni o risposte basate sul contenuto visivo
{% hint style="info" %}
**Il caricamento di immagini richiede un modello che supporti la visione artificiale.**
{% endhint %}
#### Multilingua
All'interno del layout è possibile attivare o disattivare il multilingua, la funzionalità di traduzione automatica delle domande e delle risposte.
L'opzione Multilingua è particolarmente importante per:
* **Agenti che utilizzano i contenuti** -> la traduzione automatica permette all'Agente di:
* Tradurre le domande degli utenti nella lingua dei contenuti, migliorando la ricerca delle risposte pertinenti;
* Tradurre le risposte nella lingua dell'utente.
* **Amministratori che devono** [**monitorare le conversazioni**](../analisi-ottimizzazione/analisi-e-ottimizzazione-dellagente/conversazioni.md) -> tutte le conversazioni verranno tradotte nella lingua dell'Agente, indipendentemente da quella usata dall'utente.
Il multilingua supporta: italiano, inglese, tedesco, spagnolo, francese, portoghese, ucraino, russo, polacco, finlandese, greco, arabo, cinese e giapponese.
{% hint style="info" %}
**L'IA generativa può rispondere in qualsiasi lingua** anche senza attivare il multilingua.
{% endhint %}
### Configurazione avanzata del layout
Se sei un utente più esperto, puoi applicare delle personalizzazioni molto più importanti ai tuoi layout. Vediamo le ultime tre sezioni 👇
### Codice di embed
Dopo aver configurato il layout, AIsuru genererà automaticamente un [codice di embed](codice-di-embed.md). Troverai questo codice nella sezione "Codice di embed". Usalo per [condividere il tuo Agente in altri siti web](condividi-i-tuoi-agenti/siti-web-embed.md)!
#### Ottimizzazione SEO (per Google, Bing e tutti i motori di ricerca)
In questa sezione puoi personalizzare:
* Titolo della pagina (_title_);
* Descrizione della pagina (_meta description_);
* URL canonico;
* Immagine di anteprima per social media.
Una volta personalizzati questi elementi, **aggiungi il codice alla tua pagina web**.
#### Parametri avanzati
Nei parametri avanzati puoi personalizzare:
* Il **contesto iniziale** -> se configurato, ogni volta che l'utente comincia una chat sarà impostato uno specifico [contesto](../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/contesto-argomenti-ed-etichette.md);
* La **domanda iniziale**: è nascosta all'utente; se impostata, l'utente vedrà la risposta dell'IA come primo messaggio di benvenuto;
* Il [**timeout**](../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/utilizzo-del-timeout.md) (in secondi);
* Il [**Ruolo**](../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/come-attribuire-contenuti-a-ruoli-specifici.md): chiunque accederà al nostro link sarà automaticamente identificato con il ruolo selezionato;
* **Lingua predefinita** e **lingua dell'interfaccia**.
Ti ricordiamo che **tutte le impostazioni applicate finora saranno valide per questo specifico layout**, che avrà un link specifico.
### Gestione dei layout multipli
La gestione di diversi layout per lo stesso Agente permette di:
* Adattare l'esperienza a diversi canali (web, mobile, totem);
* Personalizzare l'interazione per i vari segmenti di utenti;
* Testare diverse configurazioni per ottimizzare l'engagement.
**Layout predefinito (default)**
Puoi impostare un layout come predefinito selezionando l'apposita casella nella tabella dei layout.
**Importante**:
* **Può esserci solo un layout di default per Agente**
* Il layout predefinito viene utilizzato automaticamente in due casi:
1. Quando qualcuno accede al link principale del tuo Agente senza specificare un layout particolare
2. **Quando usi il tasto "Prova"** nella barra laterale di gestione dell'Agente
Se non imposti nessun layout come default:
* Il link principale mostrerà una versione base dell'Agente
* Il tasto "Prova" aprirà una chat semplice con l'avatar blob predefinito
{% hint style="info" %}
💡 **Consiglio**\
**I**mposta sempre un layout come default per garantire un'esperienza coerente sia per i test che per gli utenti che accedono al tuo Agente.
{% endhint %}
### Consigli per un utilizzo efficace
* **Sfrutta al massimo la personalizzazione visiva** per creare Agenti coinvolgenti e memorabili;
* **Utilizza diversi layout** per testare quale configurazione funziona meglio per il tuo pubblico;
* **Aggiorna regolarmente i tuoi layout** in base ai feedback degli utenti.
La creazione e gestione attenta dei layout **è fondamentale per offrire un'esperienza IA personalizzata e coinvolgente**. Sperimentare con diverse configurazioni ti aiuterà a trovare la combinazione perfetta per massimizzare l'efficacia del tuo Agente IA: esplora tutte le opzioni disponibili per creare un'esperienza utente davvero unica!
# Codice di embed
Il codice di embed di AIsuru è uno strumento potente che ti permette di integrare facilmente il tuo Agente IA in qualsiasi sito web o applicazione. Con questo codice, puoi portare l'intelligenza del tuo assistente virtuale direttamente ai tuoi utenti, ovunque si trovino.
Per portare il tuo Agente al di fuori della piattaforma devi, innanzitutto, ottenere il tuo codice di embed.
### Ottieni il tuo codice di embed
1. Accedi al pannello di gestione del tuo Agente;
2. Naviga alla scheda "**Condividimi**";
3. [Crea un layout](crea-e-gestisci-i-layout-di-condivisione.md) o premi sul tasto di un layout esistente;
4. Vai alla sezione "Codice di embed" del tuo layout;
5. Copia il codice fornito;
6. Inserisci il codice all'interno della tua pagina web.
# Aggiungi l'Agente al tuo spazio virtuale (VR e AR)
AIsuru ti permette di portare il tuo Agente IA in ambienti di Realtà Virtuale (VR) e Realtà Aumentata (AR), creando **esperienze immersive e interattive**. Questa funzionalità apre nuove possibilità per coinvolgere gli utenti in modi innovativi e memorabili.
Se hai già [creato uno spazio virtuale](../estensioni/spazi-virtuali-vr-e-mr/creazione-di-uno-spazio-virtuale.md), non ti resta che [**aggiungere l'Agente seguendo l'apposita guida**](../estensioni/spazi-virtuali-vr-e-mr/aggiungere-agenti-agli-spazi-virtuali.md) nella sezione dedicata agli [Spazi Virtuali](../estensioni/spazi-virtuali-vr-e-mr/).
# Condividi i tuoi Agenti
Hai creato e personalizzato il tuo assistente virtuale con AIsuru, ed è arrivato il momento di condividerlo con il mondo! In questa sezione, esploreremo le diverse modalità offerte da AIsuru per distribuire e integrare il tuo gemello digitale in vari contesti e piattaforme.
Nei prossimi capitoli, scopriremo come puoi:
1. Condividere il tuo Agente [**tramite link**](link.md);
2. [Condividere una chat](../condividi-una-chat-con-il-tuo-agente.md) con il tuo Agente;
3. Incorporare l'Agente nei [**siti web**](siti-web-embed.md);
4. [Scaricare una pagina HTML](scarica-una-pagina-html-con-il-tuo-agente.md) con il tu Agente;
5. Integrare il tuo Agente con un [**blog WordPress**](integra-lagente-con-il-tuo-blog-wordpress.md);
6. Inserire il tuo Agente all'interno di [**totem dispositivi fisici**](totem.md);
7. Aggiungere il tuo Agente in ambienti di [**Realtà Virtuale (VR) e Realtà Aumentata (AR)**](../vr.md)**;**
8. Integra i tuoi agenti [su WhatsApp Business.](integrazione-con-whatsapp-business.md)
{% hint style="info" %}
**Attenzione al cambio nome**: \
Se modifichi il nome del tuo Agente, i link dei layout attivi smetteranno di funzionare. Dovrai creare e ricondividere i nuovi link. I link privati continueranno a funzionare normalmente.
{% endhint %}
Ogni metodo di condivisione offre vantaggi unici e ti permette di raggiungere il tuo pubblico in modi diversi e coinvolgenti. Seguendo questa guida, sarai in grado di portare la tua IA conversazionale ovunque tu desideri, aprendo nuove possibilità di interazione e coinvolgimento con il tuo pubblico. 
per copiarla).
💡 Se hai impostato un [layout di default](../crea-e-gestisci-i-layout-di-condivisione.md#gestione-dei-layout-multipli), link privato e link pubblico seguiranno le sue personalizzazioni.
### Come ottengo il link dei layout personalizzati?
Se vuoi ottenere un link ad un layout personalizzato, dai un'occhiata alla tabella sottostante: sotto la colonna "URL" troverai il **pulsante** 
. Premici sopra per aprire la pagina e copia il link della nuova pagina per condividerlo con chi vuoi!
di un layout esistente;
4. Vai alla sezione "Codice di embed" del tuo layout;
5. Copia il codice fornito.
### Incorporare l'Agente nel tuo sito
Segui questi semplici passaggi per aggiungere il tuo Agente IA al tuo sito web:
1. Apri l'editor o il CMS del tuo sito web;
2. **Incolla il codice** nella sezione della pagina dove desideri che appaia l'Agente;
3. Salva e pubblica le modifiche al tuo sito.
**Assicurati di testare l'integrazione in un ambiente privato prima di pubblicarla** sul tuo sito live. In questo modo, avrai tempo di modificare lo stile o cambiarne la posizione.
### Vantaggi dell'integrazione
Incorporando il tuo Agente IA nel tuo sito web, potrai beneficiare di:
* Integrazione diretta sul tuo sito -> i tuoi utenti non dovranno cambiare pagina e potranno interagire con il tuo Agente direttamente dal tuo sito web;
* Personalizzazione avanzata -> crea un layout ad hoc per il tuo sito web con colori personalizzati per offrire un'esperienza omogenea e coinvolgente ai tuoi visitatori.
**Hai una web app?** Il tuo Agente può interagire direttamente con gli elementi della pagina per mettere in evidenza alcune sezioni o eseguire delle vere e proprie azioni al posto dell'utente. Se vuoi saperne di più, vai alla sezione dedicata agli [snippet di codice](../../istruzione-gestione-contenuti-agenti/istruzione-sezione-avanzata/personalizzazione-dei-contenuti/gestione-dei-testi-preformattati-snippet-di-codice.md) o leggi la [guida dedicata](../../avanzate/interfacce-web-come-creare-esperienze-interattive.md).
# Scarica una pagina HTML con il tuo Agente
AIsuru offre un modo semplice per implementare il tuo Agente su qualsiasi sito web attraverso il download di un file HTML completo. Questa opzione è particolarmente utile quando desideri una soluzione pronta all'uso senza dover configurare manualmente il codice di embed.
### Come scaricare il file HTML
1. Accedi al pannello di gestione del tuo Agente;
2. Naviga alla sezione "Condividimi";
3. Seleziona o crea un layout adatto alle tue esigenze;
4. Una volta configurato il layout, cerca e clicca sul pulsante "Download HTML";
5. Il file HTML verrà scaricato automaticamente sul tuo dispositivo.
#### Cosa contiene il file HTML
Il file scaricato è un documento HTML completo che include:
* Tutti gli script necessari per il funzionamento dell'Agente;
* I fogli di stile CSS per l'aspetto visivo;
* La configurazione completa del tuo Agente con il layout scelto;
* Personalizzazioni di stile basate sulle tue impostazioni.
#### Come utilizzare il file HTML
Hai diverse opzioni per utilizzare questo file:
* **Caricamento diretto**: carica il file sul tuo server web per creare una pagina dedicata al tuo Agente;
* **Integrazione in iframe**: incorpora la pagina all'interno di un iframe nel tuo sito esistente;
* **Personalizzazione ulteriore**: modifica il codice HTML per adattarlo meglio al tuo sito, aggiungendo elementi o stili aggiuntivi.
Questa soluzione offre un approccio "plug-and-play" per integrare rapidamente il tuo Agente in qualsiasi ambiente web, senza necessità di configurazioni complesse o conoscenze tecniche avanzate.
# Integra l'Agente con il tuo blog WordPress
Il plugin WordPress di AIsuru ti permette di integrare facilmente il tuo Agente IA nel tuo blog, offrendo ai lettori un'esperienza interattiva e personalizzata. Questa guida ti mostrerà come installare il plugin e configurare il tuo Agente per migliorare l'engagement del tuo blog.
### Download e installazione del plugin di WordPress
1. Accedi al pannello di gestione del tuo Agente;
2. Vai alla sezione "**Condividimi**";
3. In alto, seleziona la scheda "**WordPress**";
4. Premi sul tasto "Scarica il plugin".
Ora che l'hai scaricato, vediamo come puoi aggiungerlo al tuo sito WordPress:
1. Accedi al pannello di amministrazione di WordPress;
2. Vai alla sezione "Plugin";
3. Premi su "Aggiungi nuovo" e poi "Carica plugin";
4. Seleziona il file scaricato (memori-wp.zip) e clicca su "Installa ora";
5. Infine, clicca su "Attiva plugin".
### Configurazione del plugin
Nel menu di amministrazione WordPress, troverai una nuova voce principale:
1. Accedi alla sezione "**Memori Configurator**";
2. **Inserisci i dati richiesti**:
1. [Memori ID](#user-content-fn-1)[^1] o Memori name: è l'ID o il nome del tuo Agente;
2. [Owner User ID](#user-content-fn-2)[^2] o Owner User Name -> è l'ID o lo username del tuo account;
3. Contesto iniziale (facoltativo);
4. Domanda iniziale (facoltativo): imposta un messaggio di benvenuto che inviti i lettori a interagire con l'Agente;
5. Tenant id (lascia www.aisuru.com, se invece hai un [abbonamento PaaS](../../paas/) inserisci l'URL del tuo tenant).
Trovi tutte queste informazioni nella pagina Condividimi > WordPress del tuo Agente.
3. **Configura le altre impostazioni per l'interfaccia utente**:
1. Multilingua;
2. Pulsante di condivisione;
3. Pulsante per ricaricare la pagina;
4. Pannello impostazioni;
5. Pulsante per cancellare la chat;
6. Mostra solo gli ultimi messaggi;
7. Mostra testo di caricamento.
✅ Perfetto, hai configurato tutto! Adesso dobbiamo solo mostrarlo 👇
### Come si inserisce nel sito?
Per mostrare l'Agente ai tuoi visitatori puoi utilizzare gli **shortcode**:
1. Apri e modifica la pagina o il post dove vuoi inserire l'Agente;
2. Aggiungi lo shortcode: \[memori id="WP\_AGENT\_ID"];
3. Sostituisci "WP\_AGENT\_ID" con l'ID effettivo del tuo Agente.
[^1]: Lo trovi nel pannello di gestione del tuo Twin, alla sezione Dev docs ("Memori (Twin) ID")
[^2]: Lo trovi nel pannello di gestione del tuo Twin, alla sezione Dev docs, dopo aver premuto su "Altri riferimenti" ("ID Utente proprietario")
# Inserisci l'Agente all'interno di totem e dispositivi fisici
AIsuru ti permette di portare il tuo Agente IA nel mondo reale attraverso l'integrazione su dispositivi fisici e totem. Questa funzionalità crea punti di contatto interattivi e coinvolgenti con il tuo pubblico in spazi pubblici ed eventi, offrendo un'esperienza unica e memorabile.
### Preparazione dell'Agente
Preparare il tuo Agente ad un evento pubblico è molto semplice. Dovrai:
1. [**Personalizzare esteticamente l'Agente**](../crea-e-gestisci-i-layout-di-condivisione.md#personalizzazioni-estetiche): scegliendo un avatar accattivante, colori e immagini in linea con il tuo stile comunicativo;
2. **Creare un layout apposito per l'utilizzo su un dispositivo fisico**:
1. Accedi al pannello di gestione del tuo Agente;
2. Naviga alla scheda "Condividimi";
3. [Crea un layout](../crea-e-gestisci-i-layout-di-condivisione.md) o premi sul tasto di un layout esistente;
4. Seleziona "TOTEM" come tipo di layout per migliorare l'interazione con gli schermi touch;
5. Attiva il multilingua se ti aspetti un pubblico internazionale, puoi dare loro la possibilità di conversare in lingue diverse.
### Inserisci l'Agente nel tuo totem
Una volta fatto ciò, puoi:
* [**Utilizzare il link del layout come pagina web**](link.md) da mostrare sul tuo totem;
* [**Integrare l'Agente all'interno di una pagina web**](siti-web-embed.md) esistente che mostrerai sul tuo totem.
A seconda delle tue preferenze, segui una o l'altra guida. Assicurati che il dispositivo abbia una connessione internet stabile per garantire un funzionamento ottimale dell'Agente IA. 🌐
### Casi d'uso
Il tuo Agente IA può essere utilizzato con un totem in vari contesti:
* Fiere ed eventi: per fornire informazioni interattive ai visitatori;
* Musei: come guida virtuale personalizzata;
* Negozi: per assistenza nella ricerca prodotti;
* Ambienti aziendali: come receptionist virtuale.
Integrando il tuo Agente IA su dispositivi fisici e totem, **creerai punti di contatto innovativi e interattivi** con il tuo pubblico. Sperimenta questa funzionalità per offrire esperienze uniche e memorabili! 🤖✨
# Integrazione con WhatsApp Business
L'integrazione del tuo Agente con WhatsApp Business ti permette di offrire supporto automatizzato direttamente sulla piattaforma di messaggistica più utilizzata al mondo. Questa funzionalità è particolarmente utile per aziende che vogliono automatizzare il customer service o fornire assistenza 24/7 ai propri clienti.
### Come funziona l'integrazione
Per integrare un Agente AIsuru con WhatsApp Business è necessario passare attraverso un **WhatsApp Business Service Provider** autorizzato da Meta. Questi partner forniscono l'accesso alle API ufficiali di WhatsApp e gestiscono l'infrastruttura tecnica necessaria.
#### Processo di integrazione
1. **Scegli un partner WhatsApp Business**: seleziona un provider autorizzato che supporti integrazioni con IA esterne;
2. **Configura l'integrazione**: il partner si occuperà di collegare il tuo account WhatsApp Business alle loro API;
3. **Collega il tuo Agente**: una volta configurata la base, potrai integrare il tuo Agente AIsuru attraverso le API del partner.
### Partner consigliati
Alcuni dei provider più affidabili nel settore includono:
* [**Respond.io**](https://respond.io/): partner ufficiale WhatsApp con esperienza consolidata
* **Vonage**: provider con soluzioni complete per comunicazioni business
* Altri partner certificati Meta disponibili nella directory ufficiale
{% hint style="info" %}
💡 Contatta direttamente il partner scelto per una quotazione personalizzata, poiché ogni provider ha i propri prezzi e modalità di integrazione.
{% endhint %}
### Modello di costi
WhatsApp Business utilizza un **modello di pricing basato sulle conversazioni,** facciamo un esempio stimando circa €0,0572 per conversazione.\
\
**Cosa conta come conversazione?**\
Ogni messaggio inviato o ricevuto viene conteggiato separatamente.
#### Esempio pratico
Per una semplice prenotazione al ristorante:
* Cliente: "Vorrei prenotare un tavolo"
* Agente: "Per quante persone e quando?"
* Cliente: "2 persone alle 20:30"
* Agente: "Perfetto, prenotazione confermata"
**Costo totale**: 4 messaggi × €0,0572 = €0,23
### Considerazioni importanti
#### Sfide
* **Costi**: il pricing per conversazione può accumularsi rapidamente con volumi elevati
* **Dipendenza dal partner**: tutto il progetto dipende dai tempi e costi del provider scelto
* **Complessità tecnica**: richiede configurazioni specifiche che variano per ogni partner
### Come procedere
1. **Valuta la fattibilità economica**: calcola il volume di messaggi previsto e i costi associati
2. **Contatta un partner WhatsApp**: richiedi una quotazione dettagliata per l'integrazione
3. **Pianifica l'implementazione**: definisci tempi e modalità con il partner scelto
4. **Configura il tuo Agente**: prepara il tuo Agente AIsuru per l'integrazione
⚠️ **Nota importante**: ogni partner ha procedure, costi e tempi diversi. È essenziale ottenere informazioni specifiche dal provider scelto prima di procedere con il progetto.
### Supporto
Per ulteriori informazioni sull'integrazione WhatsApp Business o per discutere il tuo caso specifico, contatta il nostro team di AIsuru attraverso Manuela.
# Sicurezza, visibilità e condivisione in homepage
AIsuru ti offre diversi livelli di controllo per gestire chi può accedere e utilizzare i tuoi Agenti. Questa sezione ti guiderà attraverso le opzioni di sicurezza, visibilità e condivisione disponibili.
### Livelli di sicurezza
AIsuru offre tre livelli di sicurezza per proteggere i tuoi Agenti:
#### 1. Pubblico
* **Accesso**: chiunque può utilizzare l'Agente senza alcuna password
* **Visibilità**: può essere mostrato in homepage se desiderato
* **Ideale per**: Agenti dimostrativi, contenuti pubblici, assistenti di supporto generale
#### 2. Privato
* **Accesso**: richiede una password per utilizzare l'Agente
* **Password**: impostata durante la creazione e modificabile nelle impostazioni
* **Visibilità**: può essere mostrato in homepage, ma sarà sempre richiesta la password per l'utilizzo
* **Ideale per**: contenuti riservati a un gruppo specifico, informazioni aziendali interne
### Controllo accessi avanzato
#### Accessibile solo ad utenti autenticati
Oltre ai livelli di sicurezza base, puoi attivare l'opzione "Accessibile solo ad utenti autenticati" nelle impostazioni generali dell'Agente.
**Come funziona**
Quando attivi questa opzione:
* **Utenti non registrati**: vedranno un pulsante "LOGIN" invece del normale pulsante di avvio conversazione
* **Applicazione universale**: la restrizione si applica a tutti i metodi di accesso (layout, API, integrazioni web, Gruppi di esperti)
* **Autenticazione obbligatoria**: gli utenti devono effettuare il login per iniziare qualsiasi interazione
**Casi d'uso aziendali**
**Protezione di informazioni sensibili**
* Agenti che gestiscono dati riservati dell'azienda
* Assistenti HR con accesso a informazioni sui dipendenti
* Sistemi di supporto interno con procedure confidenziali
**Controllo dell'accesso ai servizi**
* Agenti dedicati ai clienti premium o abbonati
* Servizi di consulenza riservati ai clienti registrati
* Strumenti di formazione aziendale per dipendenti specifici
{% hint style="info" %}
**Nota**\
**Q**uesta opzione è diversa dalla visibilità "Privata". Mentre la visibilità controlla chi può _vedere_ l'Agente, l'autenticazione obbligatoria controlla chi può _utilizzarlo_, indipendentemente dalla visibilità.
{% endhint %}
### Visibilità in homepage
#### Cos'è e a cosa serve
L'opzione "Mostra in homepage" permette di rendere visibile il tuo Agente direttamente sulla homepage della piattaforma AIsuru (sia su [aisuru.com](https://www.aisuru.com) che sulla tua PaaS).
**Vantaggi della visibilità in homepage:**
* **Maggiore visibilità**: il tuo Agente sarà facilmente scopribile
* **Accessibilità**: i visitatori possono trovare e usare il tuo Agente senza conoscerne il link
* **Promozione**: utile per far conoscere il tuo Agente a un pubblico più ampio
#### Come gestire la visibilità in homepage
1. Accedi al pannello di gestione dell'Agente
2. Vai alla sezione "**Condividimi**"
3. Sotto al tuo link personale troverai l'opzione "Mostra in homepage"
4. Clicca su "Visibile" o "Non visibile" per modificare l'impostazione
#### Sicurezza e visibilità in homepage
🔐 **L'attivazione della visibilità in homepage non compromette la sicurezza**: se hai impostato una password per il tuo Agente, questa sarà sempre richiesta, anche se l'Agente è visibile in homepage.
### Combinazione delle opzioni di sicurezza
Puoi combinare diverse opzioni per ottenere il livello di controllo desiderato:
#### Esempi di configurazioni
**Agente aziendale interno**
* Livello: Privato
* Accessibile solo ad utenti autenticati: ✓
* Mostra in homepage: ✗
**Servizio clienti pubblico**
* Livello: Pubblico
* Accessibile solo ad utenti autenticati: ✗
* Mostra in homepage: ✓
**Consulenza per clienti registrati**
* Livello: Pubblico
* Accessibile solo ad utenti autenticati: ✓
* Mostra in homepage: ✓
### Suggerimenti per la gestione della sicurezza
1. **Durante lo sviluppo**: mantieni l'Agente privato e non visibile in homepage fino al completamento
2. **Per test interni**: usa l'opzione "Accessibile solo ad utenti autenticati" per limitare l'accesso al team
3. **Per servizi pubblici**: bilancia accessibilità e sicurezza in base alle tue esigenze
La corretta configurazione di sicurezza e visibilità è fondamentale per proteggere i tuoi contenuti e offrire la migliore esperienza possibile ai tuoi utenti. Valuta attentamente le tue esigenze e configura le opzioni di conseguenza.
# Condivisione: sezione avanzata
Queste sezioni sono le più avanzate. Non te la senti? Passa direttamente alla sezione [consumi e analytics](../../analisi-ottimizzazione/).
# Domanda iniziale
La funzionalità "Domanda iniziale" di AIsuru permette di configurare un'istruzione o una domanda nascosta che viene inviata automaticamente all'Agente IA all'inizio di ogni nuova conversazione. Questa potente caratteristica consente di personalizzare l'apertura di ogni interazione, stabilendo un contesto specifico o fornendo informazioni importanti fin dall'inizio.
#### Configurazione della domanda iniziale
Per impostare la domanda iniziale, segui questi semplici passaggi:
1. Accedi al pannello di gestione dell'Agente;
2. Naviga alla sezione 
**Condividimi**;
3. Clicca su **Aggiungi layout**;
4. Nelle impostazioni avanzate, trova "Parametri avanzati del widget";
5. Localizza il campo "Domanda iniziale" ed inserisci l'istruzione o la domanda desiderata;
6. Premi su "Salva le modifiche" in basso a destra.
Troverai il campo "Domanda iniziale" all'interno dei "Parametri avanzati del widget". Assicurati di espandere questa sezione se non è immediatamente visibile.
#### Come funziona
La domanda iniziale opera in modo discreto ma efficace:
* L'istruzione viene inviata all'Agente IA all'avvio di ogni nuova conversazione;
* L'utente non vede questa istruzione nella chat;
* Il primo messaggio visibile nella chat sarà la risposta dell'IA a questa istruzione.
#### Configurazione avanzata
Sfrutta al massimo questa funzionalità con queste opzioni avanzate:
1. **Istruzioni personalizzate**:
* Usa formule come "Saluta l'utente e digli \[informazione specifica]";
* Esempio: "Saluta l'utente e digli i ristoranti aperti oggi".
2. **Associazione con contenuti**:
* Associa un contenuto specifico a una parola chiave;
* Esempio: Imposta "Iniziamo!" come domanda iniziale e collegala a un contenuto predefinito;
* Quando l'IA riceve "Iniziamo!", risponderà con il contenuto associato.
3. **Integrazione con altre funzionalità**:
* Combina la domanda iniziale con contenuti predefiniti o risposte automatiche per un'esperienza utente ancora più ricca.
🚀 Suggerimento: Sperimenta con diverse istruzioni per trovare l'approccio migliore per i tuoi utenti!
#### Esempi pratici
Ecco alcune idee per utilizzare efficacemente la domanda iniziale:
* "Saluta l'utente e presenta brevemente le tue principali funzionalità";
* "Iniziamo!" (associato a un contenuto di benvenuto personalizzato);
* "Informa l'utente sugli ultimi aggiornamenti del sistema e chiedi se ha bisogno di assistenza".
#### Considerazioni importanti
Per ottenere i migliori risultati:
* Assicurati che l'istruzione sia chiara e porti a una risposta appropriata come primo messaggio visibile;
* Utilizza questa funzione per stabilire un tono specifico o fornire informazioni cruciali all'inizio di ogni conversazione;
* Ricorda che l'utente non vedrà l'istruzione, quindi la risposta dell'IA dovrebbe essere contestualmente appropriata.
La funzionalità "Domanda iniziale" di AIsuru offre un modo potente e flessibile per personalizzare l'esperienza dei tuoi utenti fin dal primo istante. Sperimentando con diverse istruzioni e contenuti, potrai creare interazioni più coinvolgenti e informative. Non esitare a provare diverse configurazioni per trovare quella che funziona meglio per il tuo caso d'uso specifico!
# Personalizzazione avanzata dell'interfaccia utente
{% hint style="danger" %}
Questa sezione è riservata agli utenti più esperti della piattaforma.
{% endhint %}
L'interfaccia utente del tuo Agente AIsuru è altamente personalizzabile e ti permette di creare un'esperienza su misura per i tuoi utenti.
### Accesso alle opzioni di personalizzazione
Per iniziare a personalizzare l'interfaccia del tuo Agente, segui questi semplici passaggi:
1. Accedi alla piattaforma;
2. Seleziona l'Agente desiderato;
3. Clicca su "Condividimi" nel menu laterale;
4. Individua l'icona 
nei layout creati e cliccaci sopra per aprire il menu di configurazione del widget.
### Configurazione del layout
In questa sezione, puoi definire l'aspetto generale del tuo Agente:
* **Layout**: scegli tra diverse opzioni disponibili:
1. **TOTEM**: Un layout specializzato che richiede configurazioni specifiche per posizionamento messaggi e altri elementi, ideale per installazioni fisiche interattive;
2. **FULLPAGE**: Occupa l'intera pagina web per un'esperienza immersiva dell'utente;
3. **CHAT**: Un'interfaccia classica in stile chat per interazioni testuali;
4. **WEBSITE\_ASSISTANT**: Si presenta come un'icona cliccabile in basso a destra del sito, ideale per assistenza web discreta;
5. **HIDDEN\_CHAT**: Una chat laterale che rimane nascosta fino all'attivazione, progettata per non sovrapporsi con il contenuto principale del sito;
6. **ZOOMED\_FULL\_BODY**: Questo layout mostra l'avatar a schermo intero ed è particolarmente efficace su dispositivi mobili, offrendo un'esperienza simile al TOTEM ma senza richiedere configurazioni complesse di posizionamento.
Nota: **WEBSITE\_ASSISTANT e HIDDEN\_CHAT** sono dei layout disponibili solo attraverso l'icona .
* **Multilingue**: attiva questa opzione per permettere agli utenti di interagire con l'Agente in diverse lingue 🌍;
* **Contesto iniziale**: imposta il contesto di partenza della conversazione;
* **Domanda iniziale**: definisci la prima domanda che l'Agente porrà all'utente;
* **Persona**: seleziona il ruolo che l'utente impersonerà all'inizio dell'interazione.
### Personalizzazione della toolbar
Puoi scegliere quali elementi mostrare nella toolbar del widget:
* Mostra Login;
* **Mostra Condividi**: abilita il pulsante di condivisione che permette agli utenti di:
* Condividere il link dell'Agente su diverse piattaforme social (Facebook, Twitter, LinkedIn, WhatsApp, Telegram);
* **Condividere la chat corrente** con un link specifico alla conversazione in corso;
* Inviare il link tramite email o copiarlo negli appunti;
* Scaricare un QR code per la condivisione rapida.
* Abilita audio;
* Mostra Impostazioni.
### Configurazione delle azioni chat
Personalizza le azioni disponibili durante la conversazione:
* Mostra il tasto cancella chat;
* Mostra solo ultimi messaggi;
* Mostra testo di caricamento;
* Mostra copia messaggio;
* Mostra testo traduzione originale.
### Impostazioni linguistiche
Definisci le preferenze linguistiche per il tuo Agente:
* **Lingua predefinita**: Imposta la lingua con cui l'Agente comunicherà (default: Italiano);
* **Lingua dell'interfaccia**: Scegli la lingua per l'interfaccia utente (default: IT).
### Codice di embed e anteprima
Dopo aver configurato tutte le opzioni, potrai visualizzare e copiare il codice di embed generato. Questo codice ti permetterà di integrare facilmente l'Agente nel tuo sito web o applicazione.
Se il tuo Agente è impostato come privato, agli utenti sarà sempre richiesta la password di accesso. Trovi la password nella sezione Condividimi (sotto il link privato) e nelle Impostazioni dell'Agente.
### Suggerimento tecnico
Per evitare lo zoom automatico su input touch, aggiungi questo meta tag nel `` della tua pagina:
```html
```
La personalizzazione avanzata dell'interfaccia utente ti permette di creare un'esperienza unica e su misura per i tuoi utenti. Sfrutta queste opzioni per adattare il tuo Agente AIsuru alle esigenze specifiche del tuo progetto, migliorando l'engagement e l'efficacia della tua soluzione IA. 🚀
# Analisi del codice di embed
{% hint style="danger" %}
Questa sezione è riservata agli utenti più esperti (come sviluppatori web e non solo).
{% endhint %}
In questa sezione, analizzeremo il [codice di embed](../codice-di-embed.md) degli Agenti di AIsuru. Innanzitutto, il codice di embed non è un \