Richiamo dell'estensione da un passo

Per richiamare un'estensione personalizzata da un'azione:

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

2. Facoltativo Nel campo L'assistente dice, immettere un messaggio da mostrare al cliente prima che venga richiamata l'estensione (ad esempio, Please wait while I retrieve your account balance...).

   L'output di questo passo 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 di continuare con la chiamata all'interno.

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

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

4. Fare clic su Utilizza un'estensione.

5. Nella finestra Impostazione estensione, specificare le seguenti informazioni:

   • Nel campo Estensione, seleziona l'estensione che vuoi chiamare.

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

6. Specificare i valori per ciascuno dei parametri di immissione richiesti. Un parametro è un valore di input inviato a un'operazione, come l'ID di un record cliente che si desidera richiamare o la collocazione da utilizzare per una previsione meteo.

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

   

   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, consultare Variabili compatibili per i parametri.

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

7. Se si desidera specificare un valore per i parametri facoltativi, fare clic su Parametri facoltativi. È quindi possibile ripetere questo processo per ogni parametro facoltativo che si desidera utilizzare.

8. Fai clic su Apply. (Se il pulsante Applica non è disponibile, verificare di aver specificato i valori per tutti i parametri richiesti.)

La sezione And then dell'editor dei passi mostra ora una panoramica della chiamata all'estensione:

Se è necessario apportare delle modifiche, fare clic su Modifica estensione per riaprire la finestra Impostazione estensione.

Accesso ai dati di risposta dell'estensione

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

È possibile accedere a queste variabili nello stesso modo in cui si accede ad altre variabili azione. È possibile farvi riferimento nel testo Assistant dice, 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 vengono visualizzate nell'elenco di variabili disponibili, suddivise in categorie sotto il nome dell'estensione e il passo da cui è stata richiamata:

Ogni chiamata a un'estensione crea un insieme separato di variabili di risposta. Se l'azione richiama la stessa estensione più volte da passi differenti, assicurarsi di selezionare le variabili dal passo corretto.

Ogni variabile rappresenta un valore dal corpo della risposta. Per facilitare l'accesso a questi valori, i dati vengono estratti da oggetti complessi nidificati e associati a 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, questo passo dell'azione utilizza un'espressione per controllare la proprietà availability in una risposta di estensione:

Se una variabile di risposta contiene un array, è possibile scrivere un'espressione che utilizzi metodi array per accedere agli elementi dell'array. Ad esempio, potresti utilizzare il metodo contains() in una condizione di passo per verificare se l'array contiene un particolare valore o il metodo join() per formattare i dati dall'array come stringa che puoi includere in una risposta dell'assistente. Per ulteriori informazioni sui metodi array, consultare Metodi array.

Verifica riuscita o non riuscita

Potresti volere che il tuo assistente sia in grado di gestire gli errori che si verificano durante la chiamata di un'estensione personalizzata. Puoi farlo controllando la variabile di risposta Ran successfully restituita insieme alla risposta dalla chiamata all'estensione. Questa variabile è un valore booleano (true o false).

Se definisci le condizioni del passo che controllano la variabile Ran successfully, puoi creare dei passi che consentono al tuo assistente di rispondere in modo diverso a seconda se la chiamata all'estensione ha avuto esito positivo. (Per ulteriori informazioni sulle condizioni del passo, consultare Condizioni del passo.)

Il seguente esempio mostra una condizione di fase che verifica la presenza di un errore da un'estensione nel passo 3. Utilizzando questa condizione, è possibile creare un passo che indica al cliente che si è verificato un errore e forse offre di connettersi a un agent per ulteriore assistenza.

Condizionamento sullo stato HTTP

Oltre alla variabile Ran successfully, si potrebbe anche creare una condizione di passo basata sullo stato HTTP della risposta. In questo modo, è possibile creare passi che gestiscono la situazione in maniera diversa a seconda della causa dell'errore. Ad esempio, se la chiamata non è riuscita a causa di un errore di timeout ( HTTP status 408), si potrebbe voler riprovare la chiamata.

Esistono molti codici di stato HTTP possibili e diversi metodi utilizzano codici di stato diversi per indicare vari tipi di successo o fallimento. Per condizionare lo stato HTTP, è necessario conoscere i codici di stato HTTP restituiti dal 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 passo basata sul codice di stato HTTP, procedere come segue:

1. Per il valore che si desidera verificare, fare clic su Espressione.

2. Nel campo dell'espressione, immettere il simbolo del dollaro ($) per visualizzare l'elenco delle variabili disponibili.

3. Selezionare qualsiasi variabile che sia un valore di risposta dall'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 è stata selezionata una variabile di risposta denominata 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. Dovresti essere lasciato con 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, consultare Scrittura di espressioni.

6. Completare l'espressione aggiungendo un operatore e un valore di confronto, in modo che l'espressione venga valutata come valore booleano (true/false). Ad esempio, la seguente espressione verifica lo stato HTTP 408, 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 nella pagina Anteprima, che mostra solo ciò che vedrebbe un cliente. Invece, utilizzare la funzione di anteprima che fa parte della pagina Azioni, che fornisce l'accesso a ulteriori informazioni.

2. Interagire con l'assistente come farebbe un cliente.

3. Ogni volta che viene richiamata un'estensione, il pannello di anteprima mostra un messaggio che consente di accedere a informazioni dettagliate:

   Fare clic su Ispeziona per visualizzare i dettagli relativi alla chiamata all'estensione.

   È anche possibile fare clic sull' 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 richiamata.
   Condizione	Il codice di stato HTTP della risposta. Questo codice consente di determinare se il servizio esterno sta restituendo un errore.
   Parametri di Richiesta	I parametri di input inviati all'API del sistema come parte della richiesta.
   Proprietà della risposta	I valori di tutte le proprietà incluse nella risposta dell'API di sistema. Questi sono i valori associati alle variabili azione dopo il completamento della chiamata all'estensione.

   Nelle tabelle Parametri della richiesta e Proprietà della risposta, i nomi proprietà lunghi 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 in Controllo estensione se si desidera visualizzare i dati di richiesta e risposta non elaborati:

   • La richiesta viene mostrata come un comando cURL, che è possibile eseguire da un prompt dei comandi o importare in uno strumento come Postman. Per motivi di sicurezza, il contenuto di qualsiasi intestazione Authorization non è incluso.
   • La risposta viene mostrata come i dati JSON completi restituiti dall'API del sistema.

Debug degli errori per la ricerca conversazionale o le azioni basate sulle abilità

Se le chiamate alla ricerca conversazionale o alle azioni basate sulle abilità non vanno a buon fine, è possibile eseguire il debug del problema consultando le informazioni dettagliate su ciò che viene inviato e restituito dall'API del sistema.

L'ispettore di ricerca conversazionale viene visualizzato solo quando la ricerca conversazionale è abilitata nell'integrazione di ricerca. Se si utilizza l'integrazione di ricerca del servizio personalizzato, è necessario utilizzare solo la ricerca lato server quando si configura l'integrazione di ricerca. La ricerca lato client non è supportata nell'ispettore di ricerca conversazionale.

Per visualizzare le informazioni dettagliate per analizzare il problema, utilizzare l'Inspector nel riquadro Anteprima:

1. Andare alla pagina Azioni o, nell'editor delle azioni, fare clic su Anteprima per aprire il riquadro Anteprima.

   Non è possibile accedere all'Inspector dall'anteprima dell'Assistente nella pagina Anteprima. Invece, utilizzare la funzione di anteprima che fa parte della pagina Azioni, che fornisce l'accesso a ulteriori informazioni.

2. Interagire con l'assistente come farebbe un cliente.

3. Ogni volta che viene chiamato un interno, il riquadro di anteprima mostra un messaggio per accedere alle informazioni dettagliate: È anche possibile fare clic sull'icona per mostrare o nascondere il controllo estensione. Fare clic su Ispeziona nel riquadro di anteprima per visualizzare le informazioni su una particolare chiamata all'integrazione di ricerca.

4. Utilizzare la scheda Panoramica per individuare i motivi del fallimento delle chiamate alla ricerca conversazionale.

   Prima di conoscere i campi visualizzati nella scheda Panoramica, è necessario comprendere le due fasi dell'estensione di ricerca.

   • Fase di recupero

     Rappresenta la fase di ricerca iniziale in cui viene chiamato un motore di ricerca di documenti esterno per recuperare l'insieme iniziale di risultati.

   • Fase di generazione delle risposte

     Rappresenta la fase in cui i dati vengono recuperati durante la fase di recupero e vengono inviati a un LLM per generare una risposta leggibile per l'utente.

   La scheda Panoramica dell'Inspector mostra le seguenti informazioni sulla chiamata all'integrazione di ricerca.

   Opzione di debug	Descrizione
   Estensione	Il nome dell'estensione, come specificato nelle impostazioni dell'estensione.
   Indice	Il nome dell'indice Elasticsearch usato dalla ricerca, visibile solo quando l'estensione della ricerca è configurata per usare Elasticsearch.
   Id progetto	L'ID del progetto utilizzato da IBM Watson® Discovery durante la fase di recupero della ricerca. Questo campo è visibile solo quando si configura l'estensione di ricerca per utilizzare IBM Watson® Discovery.
   Query	La query utilizzata dal sistema per avviare la ricerca sul motore dei documentiElasticsearch, IBM Watson® Discovery o servizio personalizzato lato server). Il valore di questo campo riflette la query riscritta dal sistema.
   Domanda originale	La query attraverso la quale l'utente ha avviato la ricerca. Questo campo è visibile solo quando il sistema riscrive la query quando è abilitata la ricerca conversazionale multigiro.
   Filtro risultati personalizzato	Mostra il filtro dei risultati personalizzato, se fornito dal trigger di ricerca, che ha attivato la ricerca conversazionale. Questo campo potrebbe non comparire sempre nelle risposte.
   Tipo di LLM	L'LLM che è stato chiamato durante la fase di generazione delle risposte. Questo valore è watsonx.ai. Per saperne di più sulla configurazione di LLM nell'Assistente, vedere Base LLM.
   Modello	Il modello utilizzato dal LLM di base durante la fase di generazione delle risposte della ricerca.
   Motivo della chiusura del flusso	Indica il motivo per cui il flusso è terminato o è stato chiuso, con un valore corrispondente nell'interfaccia utente. Questo campo è visibile solo quando si attiva lo streaming nella Web Chat.
   Conteggio dei token di ingresso LLM	Fornisce il numero di token nella richiesta che è stata inviata al LLM nella fase di generazione della risposta della ricerca.
   Conteggio dei token generati da LLM	Fornisce il numero di token nella risposta con cui il LLM risponde, nella fase di generazione della risposta della ricerca.
   Risposta IDK	Questo campo è visibile solo quando la risposta alla ricerca si risolve in una risposta IDK (I don't know).
   Motivo IDK	Il motivo per cui una risposta di ricerca è stata risolta dal sistema con una risposta IDK (I don't know) viene mostrato con il valore corrispondente.
   Frase di apertura del grilletto IDK	Il campo mostra la frase di apertura standard rilevata che ha innescato una risposta IDK (non so), visibile solo quando il motivo IDK è dovuto a questa frase.
   Frase di innesco IDK	Il campo visualizza la frase di attivazione rilevata che ha causato una risposta IDK (non so), visibile solo quando il motivo IDK è dovuto a questa frase.
   Tempo totale di ritorno	Il tempo totale impiegato dal sistema per completare l'esecuzione della ricerca conversazionale.
   Tempo di ricerca	Il tempo impiegato dal sistema per chiamare il motore di ricerca e recuperare i risultati nella fase di recupero della ricerca.
   Tempo di generazione delle risposte	Il tempo impiegato dal sistema per completare la fase di generazione delle risposte della ricerca.
   Soglia di fiducia	Un valore numerico che rappresenta la soglia di fiducia della ricerca, nota anche come Tendenza a dire "non so" nella configurazione di Assistant.
   Estrattività	Il punteggio riflette la quantità di risposte citate direttamente dalle fonti. Un punteggio più alto indica una citazione più diretta, mentre un punteggio più basso indica una riformulazione della fonte o la mancanza di supporto alla fonte.
   Fiducia nel recupero	Il valore di confidenza indica quanto il sistema è sicuro dei risultati della ricerca. Se è al di sotto della soglia, il sistema risponde con IDK e il motivo Recupero affidabilità troppo basso.
   Fiducia nella risposta	Il valore di confidenza indica la certezza del sistema rispetto alla risposta generata. Se è inferiore alla soglia, il sistema risponde con IDK e il motivo Response confidence too low.

Riconfigurazione di un'estensione mancante

Un'estensione potrebbe diventare non disponibile se qualcuno la rimuove dall'assistente nella pagina Integrazioni o se l'azione viene esportata e quindi importata in un'altra assistente in cui l'estensione richiesta non è configurata. Se ciò si verifica, qualsiasi passo di azione che richiama l'estensione diventa non valido.

Per risolvere il problema, procedere come segue:

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

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

3. Nell'editor delle azioni, modificare il passo dell'azione che richiama l'estensione e verificare se la chiamata all'interno è configurata correttamente. Se watsonx Assistant riconosce l'estensione richiesta, la configurazione dell'estensione viene ripristinata automaticamente.

   Se vedi il messaggio Extension not fully configured, significa che watsonx Assistant non ha trovato l'estensione richiesta. Fare clic su Modifica estensione.

4. Nella finestra Impostazione estensione, selezionare l'estensione che si desidera chiamare.

   Se watsonx Assistant riconosce un'estensione disponibile che è stata creata utilizzando lo stesso documento OpenAPI, viene visualizzato 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. Fai clic su Apply.

7. Se è stata selezionata un'estensione non identica a quella utilizzata per creare l'azione, potrebbe essere necessario modificare le fasi successive che accedono alle proprietà di risposta dell'estensione. Controllare eventuali passi successivi che fanno riferimento alle proprietà della risposta e accertarsi che i riferimenti siano ancora validi e corretti.