Configurazione dell'assistente

L'applicazione di esempio che creiamo implementa diverse semplici funzioni per illustrare come un'applicazione client interagisce con watsonx Assistant. Il codice dell'applicazione raccoglie l'input e lo invia a un assistente, che invia all'utente le risposte che l'applicazione mostra.

Per provare questo esempio, devi prima configurare il semplice assistente di esempio a cui si connette il client:

1. Scarica il file JSONdelle azioni.
2. Crea un assistente.
3. Nel nuovo assistente, apri le impostazioni dell'operazione globale. Andare alla scheda Carica / Scarica e importare le azioni dal file scaricato.

Le azioni di esempio includono un'azione Greet customer che richiede il nome del cliente e semplici azioni per effettuare e annullare gli appuntamenti.

Recupero delle informazioni sul servizio

Per accedere alle API REST watsonx Assistant, la tua applicazione deve essere in grado di autenticarsi con IBM Cloud® e connettersi all'assistente nell'ambiente in cui è distribuita. È necessario copiare le credenziali del servizio e l'ID ambiente e incollarli nel codice dell'applicazione. È necessario anche l' URL della posizione dell'istanza del servizio (ad esempio, https://api.us-south.assistant.watson.cloud.ibm.com ).

Per trovare queste informazioni:

1. Andare sulla pagina Ambienti e scegliere l'ambiente a cui si desidera connettersi.

2. Fare clic sull'icona Impostazioni per aprire le impostazioni di ambiente.

3. Selezionare Dettagli API per visualizzare i dettagli dell'ambiente, compresi l' URL dell'istanza del servizio e l'ID dell'ambiente. Per trovare la chiave API, segui il link nella sezione Credenziali del servizio.

Comunicazione con il servizio watsonx Assistant

L'interazione con il servizio watsonx Assistant dalla tua applicazione client è semplice. Iniziamo con un esempio che si connette al servizio, invia un singolo messaggio vuoto e stampa l'output sulla console:

// Example 1: Creates service object, sends initial message, and
// receives response.

const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {
  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type == 'text') {
          console.log(response.text);
        }
      });
    }
  }
}

# Example 1: Creates service object, sends initial message, and
# receives response.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Start conversation with empty message.
result = assistant.message_stateless(
    assistant_id,
).get_result()

# Print responses from actions, if any. Supports only text responses.
if result['output']['generic']:
    for response in result['output']['generic']:
        if response['response_type'] == 'text':
            print(response['text'])

Il primo passo è creare un oggetto del servizio, una sorta di wrapper per il servizio watsonx Assistant.

Utilizzare l'oggetto servizio per inviare input al servizio e ricevere output dal servizio. Quando crei l'oggetto servizio, specifichi la chiave API per l'autenticazione e la versione dell'API watsonx Assistant che stai utilizzando.

In questo esempio Node.js, l'oggetto del servizio è un'istanza di AssistantV2, memorizzata nella variabile assistant. Gli SDK di Watson per altri linguaggi forniscono meccanismi equivalenti per l'istanziazione di un oggetto servizio.

In questo esempio Python, l'oggetto del servizio è un'istanza di watson_developer_cloud.AssistantV2, memorizzata nella variabile assistant. Gli SDK di Watson per altri linguaggi forniscono meccanismi equivalenti per l'istanziazione di un oggetto servizio.

Dopo che hai creato l'oggetto del servizio, lo utilizziamo per inviare un messaggio all'assistente utilizzando il metodo message senza stato. In questo esempio, il messaggio è vuoto; vogliamo attivare l'azione Greet customer per avviare la conversazione, quindi non abbiamo bisogno di alcun testo di input. Quindi, stampiamo tutte le risposte di testo restituite nell'array generic nell'output restituito.

Utilizzate il comando node <filename.js> per eseguire l'applicazione di esempio.

Utilizzate il comando python3 <filename.py> per eseguire l'applicazione di esempio.

Nota: Assicurarsi di installare Watson SDK for Node.js utilizzando npm install ibm-watson.

Nota: Assicurarsi di installare l'SDK Watson per Python utilizzando pip install --upgrade ibm-watson o easy_install --upgrade ibm-watson.

Supponendo che tutto funzioni come previsto, l'assistente restituisce l'output dell'assistente, che l'applicazione stampa nella console:

Welcome to the watsonx Assistant example. What's your name?

Questo output indica che abbiamo comunicato con l'assistente e ricevuto il messaggio di saluto specificato dall'azione Greet customer. Ma non abbiamo ancora un modo di rispondere alla domanda dell'assistente.

Elaborazione dell'input utente

Per poter elaborare l'input utente, dobbiamo aggiungere un'interfaccia utente alla nostra applicazione client. Per questo esempio, manteniamo le cose semplici e usiamo input e output standard. Puoi utilizzare il modulo prompt - sync Node.js. (Si può installare prompt-sync usando npm install prompt-sync) È possibile utilizzare la funzione Python 3 input.

// Example 2: Adds user input.

const prompt = require('prompt-sync')();
const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {

  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type === 'text') {
          console.log(response.text);
        }  
      });
    }
  }

  // Prompt for the next round of input unless skip_user_input is true.
  let newMessageFromUser = '';
  if (result.context.global.system.skip_user_input !== true) {
    newMessageFromUser = prompt('>> ');
  }

  if (newMessageFromUser !== 'quit') {
    newMessageInput = {
      messageType: 'text',
      text: newMessageFromUser,
    }
    sendMessage(newMessageInput);
  }
}

# Example 2: Adds user input.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Initialize with empty value to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }

context = None

# Main input/output loop
while message_input['text'] != 'quit':

    # Send message to assistant.
    result = assistant.message_stateless(
        assistant_id,
        input = message_input,
        context=context
    ).get_result()
    context = response['context']

    # Print responses from actions, if any. Supports only text responses.
    if result['output']['generic']:
        for response in result['output']['generic']:
            if response['response_type'] == 'text':
                print(response['text'])

    # Prompt for the next round of input unless skip_user_input is True.
    if not result['context']['global']['system'].get('skip_user_input', False):
        user_input = input('>> ')
        message_input = {
            'text': user_input
        }

Questa versione dell'applicazione inizia allo stesso modo di prima: inviando un messaggio vuoto all'assistente per avviare la conversazione.

La funzione processResult() visualizza il testo di tutte le risposte ricevute dall'assistente. Richiede quindi il ciclo di input utente successivo.

Visualizza quindi il testo di tutte le risposte ricevute dall'assistente e richiede il successivo round di input dell'utente.

L'esempio verifica la variabile di contesto globale skip_user_input e richiede l'input dell'utente solo se questa variabile non è impostata su true True. La variabile skip_user_input viene impostata dall'assistente in alcune situazioni in cui non è necessario alcun input dell'utente (ad esempio, se l'assistente ha richiamato un servizio esterno ma è ancora in attesa del risultato). Si consiglia di eseguire sempre questo controllo prima di richiedere l'input dell'utente.

Poiché abbiamo bisogno di un metodo per terminare la conversazione, l'app client sta anche controllando il comando letterale quit per indicare che il programma deve uscire.

Ma qualcosa ancora non va bene:

Welcome to the watsonx Assistant example. What's your name?
>> Robert
I'm afraid I don't understand. Please rephrase your question.
>> I want to make an appointment.
What day would you like to come in?
>> Thursday
I'm afraid I don't understand. Please rephrase your question.
>>

L'assistente inizia con il messaggio di saluto corretto, ma non capisce quando gli dici il tuo nome. E se gli dici che vuoi fissare un appuntamento, si attiva l'azione corretta; ma ancora una volta, non capisce quando rispondi alla domanda di follow - up.

Il motivo è che stiamo utilizzando il metodo message senza stato, il che significa che è responsabilità della nostra applicazione client mantenere le informazioni di stato per la conversazione. Poiché non stiamo ancora facendo nulla per mantenere lo stato, l'assistente vede ogni turno di input dell'utente come il primo turno di una nuova conversazione. Poiché non ha memoria di porre una domanda, cerca di interpretare la vostra risposta come una nuova domanda o una nuova richiesta.

Gestione dello stato

Le informazioni sullo stato della conversazione vengono mantenute utilizzando il contesto. Il contesto è un oggetto che viene passato avanti e indietro tra la tua applicazione e l'assistente, memorizzando le informazioni che possono essere conservate e aggiornate man mano che la conversazione procede. Poiché stiamo usando il metodo message senza stato, l'assistente non memorizza il contesto, quindi è responsabilità della nostra applicazione client mantenerlo da un turno della conversazione all'altro.

Il contesto include un ID sessione per ogni conversazione e un contatore che viene incrementato ad ogni turno della conversazione. L'assistente aggiorna il contesto e lo restituisce a ogni risposta. Ma la nostra versione precedente dell'esempio non conservava il contesto, per cui questi aggiornamenti andavano persi e ogni giro di input sembrava essere l'inizio di una nuova conversazione. È possibile risolvere il problema salvando il contesto e inviandolo ogni volta all'assistente.

Oltre a mantenere il nostro posto nella conversazione, il contesto può contenere variabili d'azione che memorizzano altri dati da passare avanti e indietro tra l'applicazione e l'assistente. Ad esempio, è possibile includere dati persistenti che si desidera mantenere durante la conversazione (come il nome di un cliente o il numero di account) o qualsiasi altro dato che si desidera tracciare (come il contenuto di un carrello degli acquisti o le preferenze utente).

// Example 3: Preserves context to maintain state.

const prompt = require('prompt-sync')();
const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
context = {};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput, context) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
      context: context,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {

  let context = result.context;

  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type === 'text') {
          console.log(response.text);
        }  
      });
    }
  }

  // Prompt for the next round of input unless skip_user_input is true.
  let newMessageFromUser = '';
  if (result.context.global.system.skip_user_input !== true) {
    newMessageFromUser = prompt('>> ');
  }

  if (newMessageFromUser !== 'quit') {
    newMessageInput = {
      messageType: 'text',
      text: newMessageFromUser,
    }
    sendMessage(newMessageInput, context);
  }
}

# Example 3: Preserves context to maintain state.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Initialize with empty message to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }
context = {}

# Initialize with empty message to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }
context = {}

# Main input/output loop
while message_input['text'] != 'quit':

    # Send message to assistant.
    result = assistant.message_stateless(
        assistant_id,
        input = message_input,
        context = context
    ).get_result()

    context = result['context']

    # Print responses from actions, if any. Supports only text responses.
    if result['output']['generic']:
        for response in result['output']['generic']:
            if response['response_type'] == 'text':
                print(response['text'])

    # Prompt for the next round of input unless skip_user_input is True.
    if not result['context']['global']['system'].get('skip_user_input', False):
        user_input = input('>> ')
        message_input = {
            'text': user_input
        }

L'unico cambiamento rispetto all'esempio precedente è che ora memorizziamo il contesto ricevuto dall'assistente in una variabile chiamata context e lo inviamo con il prossimo input dell'utente:

L'unico cambiamento rispetto all'esempio precedente è che ora memorizziamo il contesto ricevuto dall'assistente in una variabile chiamata context e lo inviamo con il prossimo input dell'utente:

  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
      context: context,
    })

response = assistant.message_stateless(
    assistant_id,
    input = message_input,
    context = context
).get_result()

Ciò assicura che il contesto venga mantenuto da un turno all'altro e quindi il servizio watsonx Assistant non pensa più che ogni turno sia il primo:

Welcome to the watsonx Assistant example. What's your name?
>> Robert
Hi, Robert! How can I help you?
>> I want to make an appointment.
What day would you like to come in?
>> Next Monday
What time works for you?
>> 10 AM
OK, Robert. You have an appointment for 10:00 AM on Sep 12. See you then!

Operazione riuscita. L'applicazione ora utilizza il servizio watsonx Assistant per comprendere l'input del linguaggio naturale e visualizza le risposte appropriate.

Questo semplice esempio illustra come puoi creare un'app client personalizzata per comunicare con l'assistente. Un'applicazione del mondo reale utilizzerebbe un'interfaccia utente più sofisticata e potrebbe integrarsi con altre applicazioni come un database clienti o altri sistemi aziendali. Dovrebbe inoltre inviare altri dati all'assistente, ad esempio un ID utente per identificare ogni singolo utente. Ma i principi di base su come l'applicazione interagisce con il servizio watsonx Assistant restano uguali.

Incluso il chiarimento delle domande

Quando il tuo assistente rileva che più di un'azione potrebbe soddisfare la richiesta di un cliente, può automaticamente richiedere un chiarimento. Per ulteriori informazioni, vedi Richiesta di chiarimenti.

Per includere domande esplicative nel client personalizzato, è necessario:

• Visualizza le opzioni di suggerimento di chiarimento restituite dall'API message
• Richiama l'API message nel turno successivo con un payload che corrisponde all'opzione di suggerimento che un cliente ha scelto per rispondere alla domanda di chiarimento. Se non implementi la chiamata, autolearning e utilizzando richieste non riconosciute per ottenere consigli sulle azioni non funzionano correttamente.

Ogni suggerimento di chiarimento include:

• Un'etichetta che può essere visualizzata al cliente
• Un valore che specifica l'input che viene inviato all'assistente se l'utente sceglie il suggerimento corrispondente

Per implementare i suggerimenti di chiarimento nella propria applicazione:

1. Utilizzare l'oggetto value.input dal suggerimento selezionato come successivo round di input del messaggio, piuttosto che creare un nuovo oggetto di input. L'assistente risponde attivando l'azione associata all'opzione di suggerimento da avviare.

2. Verifica di aver implementato correttamente questa funzione utilizzando il tuo client personalizzato utilizzando la pagina Analizza. Immettere un input che attiva un chiarimento e fare clic sull'opzione Nessuno dei precedenti. Quando visualizzi la richiesta in Conversazioni, controlla che la richiesta utente che ha avviato il chiarimento sia contrassegnata con Non riconosciuto, che indica che il tuo client sta correttamente inviando l'input di chiarimento al tuo assistente.

Utilizzo dell'API di runtime v1

L'utilizzo dell'API v2 è il metodo consigliato per creare un'applicazione client di runtime che comunica con il servizio watsonx Assistant. Tuttavia, alcune vecchie applicazioni potrebbero ancora utilizzare l'API di runtime v1, che include un metodo simile per inviare messaggi all'area di lavoro all'interno di un'abilità di dialogo. Se l'applicazione utilizza l'API runtime v1, comunica direttamente con l'area di lavoro, bypassando le funzionalità di orchestrazione delle competenze e di gestione dello stato dell'assistente.

Per ulteriori informazioni sul metodo v1 /message e sul contesto, vedere il Riferimento API v1.