Configuration de l'assistant

L'exemple d'application que nous créons implémente plusieurs fonctions simples pour illustrer comment une application client interagit avec watsonx Assistant. Le code d'application collecte les entrées et les envoie à un assistant, qui envoie les réponses que l'application affiche à l'utilisateur.

Pour essayer cet exemple vous-même, vous devez d'abord configurer l'assistant d'exemple simple auquel le client se connecte:

1. Téléchargez le fichier JSONdes actions.
2. Créez un assistant.
3. Dans le nouvel assistant, ouvrez les paramètres d'action globale. Accédez à l'onglet Télécharger / Télécharger et importez les actions à partir du fichier que vous avez téléchargé.

Les exemples d'actions incluent une action Greet customer qui demande le nom du client et des actions simples pour la prise et l'annulation de rendez-vous.

Obtenir des informations sur le service

Pour accéder aux API REST watsonx Assistant, votre application doit pouvoir s'authentifier auprès de IBM Cloud® et se connecter à l'assistant dans l'environnement où elle est déployée. Vous devez copier les informations d'identification du service et l'identifiant de l'environnement et les coller dans le code de votre application. Vous avez également besoin de l'adresse URL pour l'emplacement de votre instance de service (par exemple, https://api.us-south.assistant.watson.cloud.ibm.com).

Pour trouver ces informations:

1. Accédez à la page Environnements et choisissez l'environnement auquel vous souhaitez vous connecter.

2. Cliquez sur l'icône Paramètres L'icône permet d'ouvrir les paramètres de l'environnement.

3. Sélectionnez Détails API pour afficher les détails de l'environnement, notamment l' URL l'instance de service et l'ID de l'environnement. Pour trouver la clé d'API, suivez le lien dans la section Données d'identification du service.

Communication avec le service watsonx Assistant

Interagir avec le service watsonx Assistant à partir de votre application client est simple. Nous commençons par un exemple qui se connecte au service, envoie un seul message vide et affiche la sortie sur la 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'])

La première étape consiste à créer un objet de service, une sorte d'enveloppe pour le service watsonx Assistant.

Vous utilisez l'objet de service pour l'envoi de l'entrée et la réception de la sortie du service. Lorsque vous créez l'objet de service, vous spécifiez la clé d'API pour l'authentification et la version de l'API watsonx Assistant que vous utilisez.

Dans cet exmple Node.js, l'objet de service est une instance de AssistantV2, stockée dans la variable assistant. Les SDK Watson pour d'autres langues fournissent des mécanismes équivalents pour l'instanciation d'un objet de service.

Dans cet exemple Python, l'objet de service est une instance de watson_developer_cloud.AssistantV2, stockée dans la variable assistant. Les SDK Watson pour d'autres langues fournissent des mécanismes équivalents pour l'instanciation d'un objet de service.

Après avoir créé l'objet de service, nous l'utilisons pour envoyer un message à l'assistant, en utilisant la méthode sans état message. Dans cet exemple, le message est vide ; nous voulons déclencher l'action Greet customer pour démarrer la conversation, de sorte que nous n'avons pas besoin de texte d'entrée. Nous imprimons ensuite les réponses textuelles renvoyées dans le tableau generic dans la sortie renvoyée.

Utilisez la commande node <filename.js> pour exécuter l'exemple d'application.

Utilisez la commande python3 <filename.py> pour exécuter l'exemple d'application.

Note : Assurez-vous d'installer le site Watson SDK for Node.js en utilisant npm install ibm-watson.

Note : Assurez-vous d'installer le SDK Watson pour Python en utilisant pip install --upgrade ibm-watson ou easy_install --upgrade ibm-watson.

En supposant que tout fonctionne comme prévu, l'assistant renvoie la sortie de l'assistant, que l'application imprime ensuite dans la console :

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

Cette sortie nous indique que nous avons communiqué avec l'assistant et que nous avons reçu le message d'accueil spécifié par l'action Greet customer. Mais nous n'avons pas encore de moyen de répondre à la question de l'assistant.

Traitement de l'entrée utilisateur

Pour pouvoir traiter les entrées utilisateur, nous devons ajouter une interface utilisateur à notre application client. Pour cet exemple, nous gardons les choses simples et utilisons l'entrée et la sortie standard. Vous pouvez utiliser le module prompt-sync Node.js. (Vous pouvez installer prompt-sync en utilisant npm install prompt-sync.) Vous pouvez utiliser la fonction 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
        }

Avec cette version, l'application débute comme précédemment, en envoyant un message vide à l'assistant pour démarrer la conversation.

La fonction processResult() affiche le texte des réponses reçues de l'assistant. Elle demande ensuite la série d'entrées utilisateur suivante.

Il affiche ensuite le texte des réponses reçues de l'assistant et vous invite à saisir la prochaine série d'entrées utilisateur.

L'exemple recherche la variable contextuelle globale skip_user_input et invite l'utilisateur à entrer des données uniquement si cette variable n'est pas définie sur true True. La variable skip_user_input est définie par l'assistant dans certaines situations où aucune entrée utilisateur n'est nécessaire (par exemple, si l'assistant a appelé un service externe mais attend toujours le résultat). Il est recommandé de toujours effectuer cette vérification avant de demander une entrée utilisateur.

Comme nous avons besoin d'un moyen de mettre fin à la conversation, l'application client surveille également la commande littérale quit pour indiquer que le programme doit se fermer.

Mais, il y a quelque chose qui ne va pas :

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'assistant commence avec le bon message d'accueil, mais il ne comprend pas quand vous lui dites votre nom. Et si vous lui dites que vous voulez prendre un rendez-vous, l'action correcte est déclenchée ; mais là encore, elle ne comprend pas quand vous répondez à la question de suivi.

La raison en est que nous utilisons la méthode message sans état, ce qui signifie qu'il incombe à notre application cliente de maintenir les informations d'état pour la conversation. Comme nous ne faisons encore rien pour maintenir l'état, l'assistant considère chaque entrée de l'utilisateur comme le premier tour d'une nouvelle conversation. Comme il n'a aucun souvenir de poser une question, il tente d'interpréter votre réponse comme une nouvelle question ou demande.

Gestion de l'état

Les informations relatives à l'état de votre conversation sont gérées en utilisant le contexte. Le contexte est un objet qui est transmis entre votre application et l'assistant, stockant des informations qui peuvent être conservées et mises à jour au fur et à mesure de la conversation. Étant donné que nous utilisons la méthode message sans état, l'assistant ne stocke pas le contexte, il est donc de la responsabilité de notre application client de le maintenir à partir d'un moment de la conversation vers le suivant.

Le contexte comprend un identifiant de session pour chaque conversation et un compteur qui est incrémenté à chaque tour de la conversation. L'assistant met à jour le contexte et le renvoie avec chaque réponse. Mais notre version précédente de l'exemple n'a pas préservé le contexte, de sorte que ces mises à jour ont été perdues, et chaque série de commentaires semble être le début d'une nouvelle conversation. Nous pouvons y remédier en sauvegardant le contexte et en le renvoyant à l'assistant à chaque fois.

Outre le maintien de notre place dans la conversation, le contexte peut contenir des variables d'action qui stockent d'autres données que vous souhaitez transmettre entre votre application et l'assistant. Par exemple, vous pouvez inclure des données persistantes que vous souhaitez conserver tout au long de la conversation (comme le nom ou le numéro de compte d'un client) ou toute autre donnée que vous souhaitez suivre (comme le contenu d'un panier ou les préférences de l'utilisateur).

// 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
        }

Le seul changement par rapport à l'exemple précédent est que nous stockons maintenant le contexte reçu de l'assistant dans une variable appelée context, et que nous le renvoyons avec la prochaine série d'entrées de l'utilisateur :

Le seul changement par rapport à l'exemple précédent est que nous stockons maintenant le contexte reçu de l'assistant dans une variable appelée context, et que nous le renvoyons avec la prochaine série d'entrées de l'utilisateur :

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

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

Cela permet de garantir que le contexte est préservé d'un échange à l'autre, et par conséquent, le service watsonx Assistant ne considère plus que chaque échange est le premier :

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!

Réussite ! L'application utilise désormais le service watsonx Assistant pour comprendre l'entrée en langage naturel et affiche les réponses appropriées.

Cet exemple simple illustre comment générer une application client personnalisée pour communiquer avec l'assistant. Une application réelle utilise une interface utilisateur plus sophistiquée et peut s'intégrer à d'autres applications telles qu'une base de données client ou d'autres systèmes métier. Il devrait également envoyer davantage de données à l'assistant, par exemple un identifiant permettant d'identifier chaque utilisateur. Mais, les principes de base relatifs à la façon dont l'application interagit avec le service watsonx Assistant restent les mêmes.

Y compris la clarification des questions

Lorsque votre assistant constate que plus d'une action peut répondre à la demande d'un client, il peut automatiquement demander une clarification. Pour plus d'informations, voir Demande de clarification des questions.

Pour inclure des questions de clarification dans votre client personnalisé, vous devez:

• Afficher les options de suggestion de clarification renvoyées par l'API message
• Appelez l'API message lors de la prochaine session avec un contenu qui correspond à l'option de suggestion qu'un client a choisie pour répondre à la question de clarification. Si vous n'implémentez pas l'appel, l'apprentissage automatique et l'utilisation de demandes non reconnues pour obtenir des recommandations d'action ne fonctionnent pas correctement.

Chaque suggestion de clarification comprend:

• Un libellé qui peut être affiché pour le client
• Valeur qui spécifie l'entrée envoyée à l'assistant si l'utilisateur choisit la suggestion correspondante

Pour implémenter des suggestions de clarification dans votre demande:

1. Utilisez l'objet value.input de la suggestion sélectionnée comme prochain cycle d'entrée de message, plutôt que de générer un nouvel objet d'entrée. L'assistant répond ensuite en déclenchant l'action associée à l'option de suggestion à démarrer.

2. Vérifiez que vous l'avez implémenté correctement à l'aide de votre client personnalisé à l'aide de la page Analyser. Entrez une entrée qui déclenche une clarification, puis cliquez sur l'option Aucun des éléments ci-dessus. Lorsque vous affichez la demande dans Conversations, vérifiez que la demande de l'utilisateur qui a initié la clarification est marquée avec Non reconnu, ce qui indique que votre client envoie correctement l'entrée de clarification à votre assistant.

Utilisation de l'interface de programmation d'exécution v1

L'utilisation de l'API v2 est la méthode recommandée pour créer une application client d'exécution qui communique avec le service watsonx Assistant. Toutefois, certaines applications plus anciennes peuvent toujours utiliser l'interface de programmation d'exécution v1, qui inclut une méthode similaire pour l'envoi de messages à l'espace de travail dans une compétence de dialogue. Si votre application utilise l'API d'exécution v1, elle communique directement avec l'espace de travail, sans passer par les capacités d'orchestration des compétences et de gestion de l'état de l'assistant.

Pour plus d'informations sur la méthode et le contexte v1 /message, voir la référence API v1.