Chiamare un'estensione personalizzata

Un'estensione è un'integrazione con un servizio esterno. Chiamando un'estensione da un'azione, l'assistente AI può inviare richieste al servizio esterno e ricevere dati di risposta da utilizzare nella conversazione.

Ad esempio, si può usare un'estensione per interagire con un sistema di ticketing o di gestione delle relazioni con i clienti (CRM), oppure per recuperare dati in tempo reale come i tassi ipotecari o le condizioni meteorologiche. I dati di risposta dell'estensione sono quindi disponibili come variabili di azione, che l'assistente AI può utilizzare nella conversazione.

Per informazioni su come creare un'estensione personalizzata, vedere Creazione di un'estensione personalizzata.

Chiamare l'estensione da un passo

Per chiamare un'estensione personalizzata da un'azione:

  1. Nell'editor delle azioni, creare o aprire il passo da cui si vuole chiamare l'estensione.

  2. Facoltativo: nel campo " Assistant says", digitare un messaggio da mostrare al cliente prima che venga chiamato l'interno (ad esempio, " Please wait while I retrieve your account balance...).

    L'output di questo passaggio viene inviato al canale con la variabile di contesto globale 'skip_user_input impostata su 'true. Questa variabile indica al canale di visualizzare il messaggio, ma non di richiedere una risposta al cliente. Invece, il canale invia un messaggio vuoto, consentendo all'assistente AI di procedere con la chiamata all'interno.

    Tutte le integrazioni di canale integrate (come la chat web) rispettano la variabile di contesto 'skip_user_input. Se si utilizza l'API per sviluppare un client personalizzato, è responsabilità dell'utente includere il controllo logico di questa variabile. Per ulteriori informazioni, vedere Elaborazione dell'input dell'utente.

  3. Nell'editor dei passi, fare clic su E poi.

  4. Fare clic su Usa un'estensione.

  5. Nella finestra di impostazione dell'estensione, specificare le seguenti informazioni:

    • Nel campo Estensione, selezionare l'interno da chiamare.

    • Nel campo Operazione, selezionare l'operazione che si desidera eseguire. (Un'operazione è un metodo o una funzione supportata dall'estensione)

  6. Specificare i valori per ciascuno dei parametri di ingresso richiesti. Un parametro è un valore di input inviato a un'operazione, come l'ID di un record cliente che si desidera recuperare o la località da utilizzare per le previsioni del tempo.

    Per assegnare un valore a un parametro, fare clic sul campo di immissione del valore. È quindi possibile selezionare dall'elenco delle variabili disponibili o scrivere un'espressione per specificare il valore.

    Impostazione del valore di un parametro

    Ogni parametro ha un tipo di dati (come numero o stringa). La variabile selezionata deve essere compatibile con il tipo di dati del parametro; per ulteriori informazioni, vedere Variabili compatibili per i parametri.

    È necessario specificare i valori di tutti i parametri richiesti prima di poter procedere.

  7. Se si desidera specificare un valore per i parametri opzionali, fare clic su Parametri opzionali. È possibile ripetere questa procedura per ogni parametro opzionale che si desidera utilizzare.

  8. Fare clic su Applica. (Se il pulsante Applica non è disponibile, verificare che siano stati specificati i valori di tutti i parametri richiesti)

La sezione E poi dell'editor dei passi mostra ora una panoramica della chiamata all'interno:

Panoramica della chiamata configurata all'interno

Se è necessario apportare modifiche, fare clic su " Modifica dell'estensione per riaprire la finestra " Configurazione dell'estensione.

Variabili compatibili per i parametri

Per passare un valore di parametro di ingresso per un'operazione, è necessario selezionare una variabile di azione o di sessione compatibile.

Una variabile di azione contiene un valore basato sulla risposta del cliente in una fase precedente. Una variabile di sessione può avere un valore basato sulla risposta del cliente o un valore definito da un'espressione. (Per ulteriori informazioni sulle variabili di azione e sulle variabili di sessione, vedere Uso delle variabili per gestire le informazioni di conversazione)

Quando si assegna un valore a un parametro, la variabile scelta deve essere compatibile con il tipo di dati del parametro. (Ad esempio, a un parametro numero deve essere assegnato un valore numerico e non un testo)

La tabella seguente mostra i possibili tipi di risposta del cliente e il tipo di dati del parametro compatibile con ciascuno di essi.

Tipi di risposta compatibili per i parametri
Tipo di risposta del cliente Tipi di dati compatibili Note
opzioni string Un'opzione selezionata viene sempre trattata come una stringa, anche se si tratta di un valore numerico.
numero number
integer		 Un numero in virgola mobile passato come valore del parametro 'integer potrebbe causare un errore, a seconda del comportamento dell'API REST.
data string Le date sono rese come 'YYYY-MM-DD.
ora string Gli orari sono resi come " HH:MM:SS in formato 24 ore, convertito nel fuso orario dell'utente.
Valuta number
integer
Percentuale number
integer		 Un valore percentuale viene passato come un numero intero (quindi " 75% diventa " 75).
Testo libero string
Regex string

Array

Oltre ai tipi di risposta del cliente supportati, una variabile può contenere anche un valore di array. Se si desidera passare un parametro di tipo array a un'operazione, è necessario creare una variabile di sessione array:

  1. Creare una nuova variabile di sessione, utilizzando Imposta valori variabili nell'editor dei passi o dalla pagina Variabili > Create dall'utente. (Per ulteriori informazioni su come creare una variabile di sessione, vedere Creazione di una variabile di sessione)

  2. Nel campo Tipo, selezionare Qualsiasi.

  3. Nel campo Valore iniziale, fare clic sulla levetta Usa espressione per attivarla. Immettere un'espressione che definisce un valore di matrice (ad esempio '["New York", "London", "Tokyo"], '[123, 456, 789] o '[]).

Poiché questa variabile contiene un valore di array, le azioni possono utilizzare espressioni con metodi di array per accedere o modificare i valori dell'array. Ad esempio, si potrebbe voler creare una variabile che inizialmente contenga un array vuoto ([]) e poi utilizzare il metodo " add() per costruire un elenco un elemento alla volta. Per ulteriori informazioni sui metodi di matrice che si possono usare nelle espressioni, vedere Metodi di matrice.

È ora possibile selezionare questa variabile come valore per un parametro che richiede una matrice.

Accesso ai dati di risposta dell'estensione

Dopo aver chiamato un'estensione, i valori dei dati di risposta vengono memorizzati in speciali variabili di azione a cui è possibile accedere nei passaggi successivi.

Si può accedere a queste variabili nello stesso modo in cui si accede alle altre variabili di azione. Si può fare riferimento al testo dell'Assistente, valutarlo come parte di una condizione di passo o assegnarlo a una variabile di sessione, in modo che altre azioni possano accedervi. Le variabili di risposta sono visualizzate nell'elenco delle variabili disponibili, classificate in base al nome dell'estensione e al passo da cui è stata richiamata:

Riferimento a una variabile di risposta

Ogni chiamata a un interno crea una serie separata di variabili di risposta. Se l'azione richiama lo stesso interno più volte da passi diversi, assicurarsi di selezionare le variabili dal passo corretto.

Ogni variabile rappresenta un valore del corpo della risposta. Per facilitare l'accesso a questi valori, i dati vengono estratti da oggetti complessi e annidati e mappati su singole variabili di risposta. Il nome di ciascuna variabile riflette la sua posizione all'interno del corpo della risposta (ad esempio, " body.name o " body.customer.address.zipcode).

Ad esempio, questa fase d'azione utilizza un'espressione per controllare la proprietà 'availability in una risposta dell'estensione:

Variabile di estensione in condizione di passo

Se una variabile di risposta contiene un array, è possibile scrivere un'espressione che utilizza i metodi dell'array per accedere agli elementi dell'array. Ad esempio, si può usare il metodo 'contains() in una condizione di passo per verificare se l'array contiene un particolare valore, oppure il metodo 'join() per formattare i dati dell'array come una stringa da includere nella risposta dell'assistente AI. Per ulteriori informazioni sui metodi di matrice, vedere Metodi di matrice.

Verifica del successo o del fallimento

Si potrebbe desiderare che l'assistente AI sia in grado di gestire gli errori che si verificano quando si chiama un'estensione personalizzata. È possibile farlo controllando la variabile di risposta 'Ran successfully che viene restituita insieme alla risposta della chiamata all'interno. Questa variabile è un valore booleano (true o " false).

Se si definiscono condizioni di passaggio che controllano la variabile " Ran successfully, è possibile creare passaggi che consentono all'assistente AI di rispondere in modo diverso a seconda che la chiamata all'interno sia andata a buon fine. (Per ulteriori informazioni sulle condizioni di passaggio, vedere Condizioni di passaggio)

L'esempio seguente mostra una condizione di passo che controlla se un'estensione è fallita nel passo 3. Utilizzando questa condizione, è possibile creare un passaggio che informi il cliente che si è verificato un errore e che magari offra la possibilità di collegarsi a un agente per ottenere maggiore assistenza.

Controllo delle condizioni al passo per il fallimento dell'estensione

Condizionamento in base allo stato dell HTTP

Oltre alla variabile " Ran successfully ", potresti anche voler creare una condizione di passaggio basata sullo stato " HTTP " della risposta. In questo modo, è possibile creare passaggi che gestiscono la situazione in modo diverso a seconda della causa del guasto. Ad esempio, se la chiamata non è andata a buon fine a causa di un errore di timeout ( HTTP, stato 408), potrebbe essere opportuno riprovare.

Esistono molti possibili codici di stato dell' HTTP, e metodi diversi utilizzano codici di stato diversi per indicare vari tipi di successo o fallimento. Per condizionare lo stato dell' HTTP, è necessario sapere quali codici di stato dell' HTTP e restituisce il servizio esterno e in quali circostanze. Questi codici di stato sono tipicamente specificati nel documento " OpenAPI " che descrive l'API esterna.

Per creare una condizione di passaggio basata sul codice di stato dell' HTTP, procedere come segue:

  1. Per il valore da testare, fare clic su Espressione.

  2. Nel campo dell'espressione, digitare un segno di dollaro ($) per visualizzare l'elenco delle variabili disponibili.

  3. Selezionare qualsiasi variabile che sia un valore di risposta dell'estensione. (Non importa quale variabile si seleziona, purché sia una variabile di risposta dell'estensione).

    L'espressione viene aggiornata automaticamente per mostrare un riferimento alla variabile selezionata, nel formato '${step_xxx_result_y.body.variablename}. Ad esempio, se si è selezionata una variabile di risposta chiamata 'body.id, il riferimento potrebbe essere '${step_596_result_1.body.id}.

  4. All'interno delle parentesi graffe, ({}), modificare questo riferimento per rimuovere '.body.variablename. Dovrebbe rimanere qualcosa come '${step_596_result_1}.

  5. Dopo la parentesi graffa di chiusura (}), aggiungere " .status. Il riferimento risultante identifica il codice di stato restituito dalla chiamata all'interno (ad esempio, " ${step_596_result_1}.status).

    Per ulteriori informazioni sulla scrittura di espressioni, vedere Scrittura di espressioni.

  6. Completate l'espressione aggiungendo un operatore e un valore di confronto, in modo che l'espressione sia valutata come un valore booleano (vero/falso). Ad esempio, l'espressione seguente verifica lo stato 408 dell' HTTP, che indica un errore di timeout:

    ${step_549_result_1}.status==408

Errori di debug per l'estensione personalizzata

Se le chiamate a un'estensione non vanno a buon fine, è possibile eseguire il debug del problema visualizzando informazioni dettagliate su ciò che viene inviato e restituito dall'API del sistema. Per farlo, si può utilizzare l'Inspector nel riquadro Anteprima:

  1. Passare alla pagina Azioni o all'editor delle azioni e fare clic su Anteprima per aprire il riquadro Anteprima.

    Non è possibile accedere all'Inspector dall'anteprima dell'assistente AI nella pagina Anteprima, che mostra solo ciò che vedrebbe un cliente. Utilizzate invece la funzione di anteprima che fa parte della pagina Azioni, che consente di accedere a informazioni aggiuntive.

  2. Interagite con il vostro assistente AI come farebbe un cliente.

  3. Ogni volta che si chiama un'estensione, il riquadro di anteprima mostra un messaggio che consente di accedere a informazioni dettagliate:

    Fare clic su Ispeziona per visualizzare i dettagli della chiamata all'interno.

    È inoltre possibile fare clic sull'icona " Icona dell'ispettore delle estensioni " per mostrare o nascondere l'Ispettore. Tuttavia, è necessario fare clic su Ispeziona nel riquadro di anteprima per visualizzare le informazioni su una particolare chiamata a un interno.

    La scheda Panoramica dell'Inspector mostra le seguenti informazioni su una chiamata a un interno:

    Opzione di debug Descrizione
    Estensione Il nome dell'estensione, come specificato nelle impostazioni dell'estensione.
    Operazione L'operazione che è stata chiamata.
    Stato Il codice di stato " HTTP " dalla risposta. Questo codice può aiutare a determinare se il servizio esterno restituisce un errore.
    Parametri di Richiesta I parametri di input inviati all'API del sistema come parte della richiesta.
    Proprietà risposta I valori di tutte le proprietà incluse nella risposta dell'API di sistema. Questi sono i valori che vengono mappati nelle variabili di azione al termine della chiamata all'interno.

    Nelle tabelle dei parametri della richiesta e delle proprietà della risposta, i nomi lunghi delle proprietà potrebbero essere troncati per mostrare solo l'ultima parte del percorso JSON. Per visualizzare il percorso completo e il nome della proprietà, passare il puntatore del mouse sul nome della proprietà nella tabella.

  4. Fare clic sulla scheda Avanzate nell'ispettore dell'estensione se si desidera visualizzare i dati grezzi di richiesta e risposta:

    • La richiesta viene mostrata come un comando cURL, che può essere eseguito dal prompt dei comandi o importato in uno strumento come Postman. (Per motivi di sicurezza, il contenuto dell'intestazione " Authorization non viene incluso)
    • La risposta viene mostrata come i dati JSON completi restituiti dall'API del sistema.

Riconfigurazione di un'estensione mancante

Un'estensione potrebbe diventare non disponibile se qualcuno la rimuove dall'assistente AI nella pagina delle integrazioni, oppure se l'azione viene esportata e poi importata in un assistente AI diverso in cui l'estensione richiesta non è configurata. In questo caso, qualsiasi azione che richiama l'estensione non è più valida.

Per risolvere il problema, procedere come segue:

  1. Se necessario, ricreare l'estensione utilizzando la stessa specifica OpenAPI usata in precedenza. (Per ulteriori informazioni, vedere Creazione di un'estensione personalizzata)

  2. Assicurarsi che l'estensione sia stata aggiunta all'assistente AI. (Per ulteriori informazioni, vedere Aggiunta di un'estensione all'assistente)

  3. Nell'editor delle azioni, modificare la fase dell'azione che chiama l'interno e verificare se la chiamata all'interno è configurata correttamente. Se l'assistente AI riconosce l'estensione richiesta, la configurazione dell'estensione viene ripristinata automaticamente.

    Se viene visualizzato il messaggio 'Extension not fully configured, significa che AI assistant builder non ha trovato l'estensione richiesta. Fare clic su Modifica estensione.

  4. Nella finestra 'Configurazione dell'estensione, selezionare l'interno che si desidera chiamare.

    Se il costruttore dell'assistente AI riconosce un'estensione disponibile che è stata costruita utilizzando lo stesso documento OpenAPI, appare un messaggio che suggerisce di selezionare questa estensione. Tuttavia, è possibile selezionare qualsiasi estensione disponibile.

  5. Verificare che i valori corretti siano specificati nei campi Operazione e Parametri.

  6. Fare clic su Applica.

  7. Se si è selezionata un'estensione non identica a quella usata per costruire l'azione, potrebbe essere necessario modificare i passaggi successivi che accedono alle proprietà di risposta dell'estensione. Controllare tutti i passaggi successivi che fanno riferimento alle proprietà della risposta e verificare che i riferimenti siano ancora validi e corretti.