Riutilizzare le variabili tra gli argomenti

  • Articolo

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

Le variabili memorizzano le risposte dei tuoi clienti alle domande del tuo copilota. Ad esempio, puoi salvare il nome di un cliente in una variabile chiamata UserName. Il copilota può quindi rivolgersi al cliente per nome mentre la conversazione continua.

Per impostazione predefinita, il valore di una variabile può essere usato solo nell'argomento in cui viene creata la variabile. Tuttavia, è possibile riutilizzare lo stesso valore tra gli argomenti. Ad esempio, un argomento Benvenuto chiede il nome e l'indirizzo e-mail del cliente. Nell'argomento Prenotazione dell'appuntamento, vuoi che il copilota ricordi ciò che il cliente ha inserito e non lo chieda di nuovo.

Un modo per riutilizzare una variabile è passare la variabile tra argomenti. L'altro modo è creare la variabile globale nell'ambito, ed è ciò che illustra questo articolo. Le variabili globali sono chiamate così perché sono disponibili in tutti gli argomenti dell'intero copilota.

Le variabili del copilota si applicano durante una singola sessione utente. Specifica quali variabili devono essere trattate come variabili copilota per distinguerle dalle variabili a livello di argomento.

Creare una variabile globale

Puoi creare una variabile globale modificando l'ambito di una variabile di argomento.

  1. Crea una variabile o utilizza il riquadro Variabili per aprire una variabile esistente.

  2. Sul riquadro Proprietà variabili, seleziona Globale (qualsiasi argomento può accedere).

    Al nome della variabile verrà assegnato il prefisso Global. per differenziarla dalle variabili a livello di argomento. Ad esempio, la variabile UserName viene visualizzata come Global.UserName.

    Screenshot che mostra il riquadro Proprietà delle variabili, con la sezione Impostazioni globali evidenziata.

  3. Salva l'argomento.

    Il nome di una variabile globale deve essere univoco in tutti gli argomenti. In caso di conflitto, dovrai rinominare la variabile prima di salvare l'argomento.

Usare variabili globali

Quando componi un messaggio del copilota in un nodo Messaggio o un nodo Domanda, seleziona l'icona {x} per visualizzare le variabili che sono disponibili per l'argomento. Le variabili globali vengono visualizzate nella scheda Personalizzato, insieme a tutte le variabili argomento. Le variabili sono elencate in ordine alfabetico.

Screenshot che mostra la selezione di una variabile globale.

Trovare tutti gli argomenti utilizzando una variabile globale

Puoi scoprire dove una variabile globale è definita e quali altri argomenti la stanno utilizzando. Questo può essere utile se stai lavorando su un nuovo copilota o se hai più variabili e una ramificazione complessa di argomenti.

  1. Seleziona una variabile globale nell'area del contenuto o apri il riquadro Variabili e seleziona una variabile globale.

  2. Nel riquadro Proprietà variabili, in sezione Riferimento, seleziona uno degli argomenti in cui viene utilizzata la variabile per passare direttamente a quell'argomento e a quel nodo.

    Screenshot che mostra l'elenco degli argomenti utilizzati da una variabile nel riquadro delle proprietà della variabile.

Ciclo di vita delle variabili globali

Per impostazione predefinita, il valore di una variabile globale persiste finché la sessione non termina. Il nodo Cancella valori variabili reimposta i valori delle variabili globali e viene utilizzato nel sistema Reimposta conversazione argomento. Quel argomento può essere attivato tramite reindirizzamento o quando l'utente digita una frase trigger come "Ricomincia". In tal caso, tutte le variabili globali vengono ripristinate.

Imposta il valore di una variabile globale da origini esterne

Se vuoi assicurarti che il copilota inizi una conversazione con un contesto, puoi inizializzare una variabile globale con un'origine esterna. Supponiamo che il tuo sito richieda agli utenti di accedere. Poiché il tuo copilota conosce già il nome di un utente, può salutare i clienti per nome prima che inizino a digitare la prima domanda.

  1. Seleziona una variabile globale.

  2. Nel riquadro Proprietà variabili, seleziona Le origini esterne possono impostare valori.

Imposta variabili globali in un copilota integrato

Se stai integrando il tuo copilota in una semplice pagina Web, puoi aggiungere variabili e le relative definizioni all'URL del copilota. Oppure, se desideri un po' più di controllo, puoi utilizzare un blocco di codice <script> per chiamare e utilizzare variabili a livello di codice.

Il nome della variabile nella stringa di query dell'URL deve corrispondere a quello della variabile globale, senza il prefisso Global.. Ad esempio, una variabile globale Global.UserName sarebbe indicata come UserName nella query.

Gli esempi che seguono forniscono una dichiarazione semplice per le variabili. In uno scenario di produzione, puoi passare come parametro di query o definizione di variabile un'altra variabile che ha già memorizzato il nome dell'utente (ad esempio, se disponi del nome utente da uno script di accesso).

Aggiungi le variabili e le loro definizioni all'URL del copilota come parametri della stringa di query (nel formato di botURL?variableName1=variableDefinition1&variableName2=variableDefinition2).

Ad esempio:

Il nome del parametro non fa distinzione tra maiuscole e minuscole. username=Renata funziona anche in questo esempio.

Aggiungere variabili globali a un canvas personalizzato

Puoi anche aggiungere la variabile a un canvas personalizzato.

  1. Nella sezione <script> della pagina in cui hai il tuo copilota, definisci le variabili come segue, sostituendo variableName1 per il nome della variabile senza il prefisso Global. e variableDefinition1 per la definizione. Separa più variabili con le virgole (,).

       const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
     if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
       dispatch({
          type: "WEB_CHAT/SEND_EVENT",
          payload: {
            name: "pvaSetContext",
            value: {
               "variableName1": "variableDefinition1",
               "variableName2": "variableDefinition2"
            }
          },
        });
      }
        return next(action);
    });

  2. Nella sezione <script>, chiama store quando incorpori il copilota, come nell'esempio seguente dove store viene chiamato appena sopra la chiamata di styleOptions (dovrai sostituire BOT_ID con l'ID del copilota):

    const BOT_ID = "12345-5678";
const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

fetch(theURL)
    .then(response => response.json())
    .then(conversationInfo => {
        window.WebChat.renderWebChat(
            {
                directLine: window.WebChat.createDirectLine({
                    token: conversationInfo.token,
                }),
                store,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })
    .catch(err => console.error("An error occurred: " + err));