Utiliser un dialogue pour consommer une compétence

  • Article

S'APPLIQUE À : SDK v4

Cet article explique comment utiliser un dialogue de compétence dans un consommateur de compétences. Le dialogue de compétence publie les activités du bot parent pour le bot de compétences et renvoie les réponses de compétence à l’utilisateur. Le bot de compétences auquel ce consommateur accède peut gérer à les fois les activités de messages et d’événements. Pour obtenir un exemple de manifeste de compétence et des informations sur l’implémentation de la compétence, découvrez comment utiliser des dialogues dans une compétence.

Pour plus d’informations sur l’utilisation d’un bot de compétences en dehors des dialogues, découvrez comment implémenter un consommateur de compétences.

Remarque

Les kits SDK JavaScript, C# et Python Bot Framework continueront d’être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d'utiliser Power Virtual Agents et découvrez comment choisir la solution de chatbot appropriée.

Pour plus d’informations, consultez Les futures versions de bot.

Prérequis

À propos de cet exemple

L’exemple de compétences skillDialog inclut des projets pour deux bots :

  • Le bot racine du dialogue, qui utilise une classe de dialogue de compétence pour consommer une compétence.
  • Le bot de compétences du dialogue, qui utilise un dialogue pour gérer les activités provenant des consommateurs de compétences.

Cet article se concentre sur l’utilisation d’une classe de dialogue de compétence dans un bot racine pour gérer la compétence, envoyer des messages et des activités d’événements ainsi que pour annuler la compétence.

Pour plus d’informations sur d’autres aspects de la création d’un consommateur de compétence, découvrez comment implémenter un consommateur de compétences.

Pour plus d’informations sur le bot de compétences du dialogue, découvrez comment utiliser des dialogues dans une compétence.

Ressources

Pour les bots déployés, l'authentification entre bots exige que chaque bot participant ait une identité valide. Toutefois, vous pouvez tester les compétences et les consommateurs de compétences localement avec Bot Framework Emulator sans informations d'identité.

Configuration de l’application

  1. Si vous le souhaitez, ajoutez les informations d'identité du bot racine au fichier config.
  2. Ajoutez le point de terminaison de l'hôte des compétences (le service ou l'URL de rappel) auquel les compétences doivent répondre au consommateur de compétences.
  3. Ajoutez une entrée pour chaque compétence que le consommateur de compétences utilisera. Chaque entrée comprend :
    • Un ID que le consommateur de compétences utilisera pour identifier chaque compétence.
    • Si vous le souhaitez, l'application ou l'ID de client du bot de compétences.
    • Le point de terminaison de messagerie de la compétence.

Remarque

Si la compétence ou le consommateur de compétences spécifie une identité, les deux doivent être indiqués.

DialogRootBot\appsettings.json

Si vous le souhaitez, ajoutez les informations d'identité du bot racine et ajoutez l'application ou l'ID client du bot de compétence echo au tableau BotFrameworkSkills.

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",

  "SkillHostEndpoint": "http://localhost:3978/api/skills/",
  "BotFrameworkSkills": [
    {
      "Id": "DialogSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

Logique de dialogue

Le dialogue principal du bot inclut un dialogue de compétence pour chaque compétence consommée par ce bot. Le dialogue de compétence gère pour vous la compétences dans les différents objets liés aux compétences, tels que les objets client de compétence et fabrique d’ID de conversation de compétence. Le dialogue principal montre également comment annuler la compétence (via le dialogue de compétence) en fonction de l’entrée de l’utilisateur.

La compétence utilisée par ce bot prend en charge plusieurs fonctionnalités différentes. Elle peut réserver un vol ou donner la météo d’une ville. Par ailleurs, si elle reçoit un message en dehors de l’un de ces contextes et qu’un module de reconnaissance LUIS est configuré, elle tente d’interpréter l’intention de l’utilisateur.

Remarque

Compréhension du langage (LUIS) sera mis hors service le 1er octobre 2025. À compter du 1er avril 2023, vous ne pourrez pas créer de nouvelles ressources LUIS. Une version plus récente de Compréhension du langage est désormais disponible dans le cadre d'Azure AI Language.

Compréhension du langage courant (CLU), une fonctionnalité d’Azure AI Language, est la version mise à jour de LUIS. Pour plus d'informations sur la prise en charge de compréhension du langage dans le kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Le manifeste de compétence (C#, JavaScript, Java, Python) décrit les actions que la compétence peut effectuer, ses paramètres d'entrée et de sortie, ainsi que ses points de terminaison. Notez que la compétence peut gérer un événement « BookFlight » ou « GetWeather ». Elle peut également gérer des messages.

Le dialogue principal inclut un code permettant d’effectuer les opérations suivantes :

Le dialogue principal hérite de la classe du dialogue du composant. Pour plus d’informations sur les dialogues de composants, découvrez comment gérer la complexité des dialogues.

Initialiser le dialogue principal

Le dialogue principal inclut des dialogues (pour la gestion du flux de conversation en dehors de la compétence) et un dialogue de compétence (pour la gestion des compétences). La cascade inclut les étapes suivantes, qui sont décrites plus en détail dans les sections suivantes.

  1. Inviter l’utilisateur à sélectionner la compétence à utiliser. (Le bot racine consomme une compétence.)
  2. Inviter l’utilisateur à sélectionner l’action à utiliser pour cette compétence. (Le bot de compétences définit trois actions.)
  3. Démarrer la compétence choisie avec une activité initiale basée sur cette action choisie.
  4. Une fois la compétence terminée, affichez les résultats, le cas échéant. Ensuite, redémarrez la cascade.

DialogRootBot\Dialogs\MainDialog.cs

La classe MainDialog est dérivée de ComponentDialog. En plus de l'état de la conversation, le dialogue a besoin de l'identité du bot racine et des références à la fabrique d'ID de conversation des compétences, au client HTTP des compétences et aux objets de configuration des compétences.

Le constructeur de dialogue vérifie ses paramètres d'entrée, ajoute des dialogues de compétence, des dialogues d'invite et de cascade pour gérer le flux de conversation en dehors de la compétence. Il crée également un accesseur de propriété pour le suivi de la compétence active, le cas échéant.

Le constructeur appelle AddSkillDialogs, une méthode d’assistance, pour créer une SkillDialog pour chaque compétence incluse dans le fichier de configuration, comme lu à partir du fichier de configuration dans un objet SkillsConfiguration.

// Helper method that creates and adds SkillDialog instances for the configured skills.
private void AddSkillDialogs(ConversationState conversationState, SkillConversationIdFactoryBase conversationIdFactory, SkillsConfiguration skillsConfig, string botId)
{
    foreach (var skillInfo in _skillsConfig.Skills.Values)
    {
        // Create the dialog options.
        var skillDialogOptions = new SkillDialogOptions
        {
            BotId = botId,
            ConversationIdFactory = conversationIdFactory,
            SkillClient = _auth.CreateBotFrameworkClient(),
            SkillHostEndpoint = skillsConfig.SkillHostEndpoint,
            ConversationState = conversationState,
            Skill = skillInfo
        };

        // Add a SkillDialog for the selected skill.
        AddDialog(new SkillDialog(skillDialogOptions, skillInfo.Id));
    }
}

Sélectionner une compétence

Lors de cette première étape, le dialogue principal demande à l'utilisateur quelle compétence il souhaite appeler et utilise l'invite de choix « SkillPrompt » pour obtenir la réponse. (Ce bot ne définit qu’une compétence.)

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the skill to call.
private async Task<DialogTurnResult> SelectSkillStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Create the PromptOptions from the skill configuration which contain the list of configured skills.
    var messageText = stepContext.Options?.ToString() ?? "What skill would you like to call?";
    var repromptMessageText = "That was not a valid choice, please select a valid skill.";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        RetryPrompt = MessageFactory.Text(repromptMessageText, repromptMessageText, InputHints.ExpectingInput),
        Choices = _skillsConfig.Skills.Select(skill => new Choice(skill.Value.Id)).ToList()
    };

    // Prompt the user to select a skill.
    return await stepContext.PromptAsync("SkillPrompt", options, cancellationToken);
}

Sélectionner une action de compétence

À l’étape suivante, le dialogue principal :

  1. enregistre les informations relatives à la compétence sélectionnée par l’utilisateur ;
  2. demande à l’utilisateur quelle action de compétence il souhaite utiliser et utilise l’invite de choix « SkillActionPrompt » pour obtenir la réponse.
    • Elle utilise une méthode d’assistance pour obtenir une liste d’actions parmi lesquelles choisir.
    • Par défaut, le validateur d’invite associé à cette invite envoie un message à la compétence si l’entrée de l’utilisateur ne correspond pas à l’un des choix.

Les choix inclus dans ce bot aident à tester les actions définies pour cette compétence. Plus généralement, vous devez lire les options du manifeste de la compétence et présenter à l’utilisateur les options basées sur cette liste.

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the action for the skill.
private async Task<DialogTurnResult> SelectSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Get the skill info based on the selected skill.
    var selectedSkillId = ((FoundChoice)stepContext.Result).Value;
    var selectedSkill = _skillsConfig.Skills.FirstOrDefault(s => s.Value.Id == selectedSkillId).Value;

    // Remember the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = selectedSkill;

    // Create the PromptOptions with the actions supported by the selected skill.
    var messageText = $"Select an action # to send to **{selectedSkill.Id}** or just type in a message and it will be forwarded to the skill";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        Choices = GetSkillActions(selectedSkill)
    };

    // Prompt the user to select a skill action.
    return await stepContext.PromptAsync("SkillActionPrompt", options, cancellationToken);
}
// Helper method to create Choice elements for the actions supported by the skill.
private IList<Choice> GetSkillActions(BotFrameworkSkill skill)
{
    // Note: the bot would probably render this by reading the skill manifest.
    // We are just using hardcoded skill actions here for simplicity.

    var choices = new List<Choice>();
    switch (skill.Id)
    {
        case "DialogSkillBot":
            choices.Add(new Choice(SkillActionBookFlight));
            choices.Add(new Choice(SkillActionBookFlightWithInputParameters));
            choices.Add(new Choice(SkillActionGetWeather));
            break;
    }

    return choices;
}
// This validator defaults to Message if the user doesn't select an existing option.
private Task<bool> SkillActionPromptValidator(PromptValidatorContext<FoundChoice> promptContext, CancellationToken cancellationToken)
{
    if (!promptContext.Recognized.Succeeded)
    {
        // Assume the user wants to send a message if an item in the list is not selected.
        promptContext.Recognized.Value = new FoundChoice { Value = SkillActionMessage };
    }

    return Task.FromResult(true);
}

Démarrer une compétence

À l’étape suivante, le dialogue principal :

  1. Récupère des informations sur la compétence et l’activité de compétence sélectionnées par l’utilisateur.
  2. Utilise une méthode d’assistance pour créer l’activité à envoyer initialement à la compétence.
  3. Crée les options de dialogue avec lesquelles démarrer le dialogue de compétence. Ceci inclut l’activité initiale à envoyer.
  4. Enregistre l’état avant d’appeler la compétence. (Cela est nécessaire, car la réponse de la compétence peut arriver à une instance différente du consommateur de compétences.)
  5. Démarre le dialogue de compétence, en passant à l’ID de compétence à appeler et aux options avec lesquelles l’appeler.

DialogRootBot\Dialogs\MainDialog.cs

// Starts the SkillDialog based on the user's selections.
private async Task<DialogTurnResult> CallSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var selectedSkill = (BotFrameworkSkill)stepContext.Values[_selectedSkillKey];

    Activity skillActivity;
    switch (selectedSkill.Id)
    {
        case "DialogSkillBot":
            skillActivity = CreateDialogSkillBotActivity(((FoundChoice)stepContext.Result).Value, stepContext.Context);
            break;

        // We can add other case statements here if we support more than one skill.
        default:
            throw new Exception($"Unknown target skill id: {selectedSkill.Id}.");
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    var skillDialogArgs = new BeginSkillDialogOptions { Activity = skillActivity };

    // Save active skill in state.
    await _activeSkillProperty.SetAsync(stepContext.Context, selectedSkill, cancellationToken);

    // Start the skillDialog instance with the arguments. 
    return await stepContext.BeginDialogAsync(selectedSkill.Id, skillDialogArgs, cancellationToken);
}

Résumer le résultat de la compétence

Lors de la dernière étape, le dialogue principal :

  1. Si la compétence a retourné une valeur, affichez le résultat à l’intention de l’utilisateur.
  2. Efface la compétence active de l’état du dialogue.
  3. Supprime la propriété de compétence active de l’état de la conversation.
  4. Redémarre lui-même (le dialogue principal).

DialogRootBot\Dialogs\MainDialog.cs

// The SkillDialog has ended, render the results (if any) and restart MainDialog.
private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activeSkill = await _activeSkillProperty.GetAsync(stepContext.Context, () => null, cancellationToken);

    // Check if the skill returned any results and display them.
    if (stepContext.Result != null)
    {
        var message = $"Skill \"{activeSkill.Id}\" invocation complete.";
        message += $" Result: {JsonConvert.SerializeObject(stepContext.Result)}";
        await stepContext.Context.SendActivityAsync(MessageFactory.Text(message, message, inputHint: InputHints.IgnoringInput), cancellationToken: cancellationToken);
    }

    // Clear the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = null;

    // Clear active skill in state.
    await _activeSkillProperty.DeleteAsync(stepContext.Context, cancellationToken);

    // Restart the main dialog with a different message the second time around.
    return await stepContext.ReplaceDialogAsync(InitialDialogId, $"Done with \"{activeSkill.Id}\". \n\n What skill would you like to call?", cancellationToken);
}

Autoriser l’utilisateur à annuler la compétence

Le dialogue principal remplace le comportement par défaut de la méthode du dialogue en continu pour permettre à l’utilisateur d’annuler la compétence actuelle, le cas échéant. Dans la méthode suivante :

  • s'il existe une compétence active et que l'utilisateur envoie un message « abandonner », annulez tous les dialogues et mettez le dialogue principal en file d'attente pour reprendre à partir du début.
  • Ensuite, appelez l’implémentation de base sur la méthode continuer le dialogue pour continuer le traitement du tour en cours.

DialogRootBot\Dialogs\MainDialog.cs

protected override async Task<DialogTurnResult> OnContinueDialogAsync(DialogContext innerDc, CancellationToken cancellationToken = default)
{
    // This is an example on how to cancel a SkillDialog that is currently in progress from the parent bot.
    var activeSkill = await _activeSkillProperty.GetAsync(innerDc.Context, () => null, cancellationToken);
    var activity = innerDc.Context.Activity;
    if (activeSkill != null && activity.Type == ActivityTypes.Message && activity.Text.Equals("abort", StringComparison.OrdinalIgnoreCase))
    {
        // Cancel all dialogs when the user says abort.
        // The SkillDialog automatically sends an EndOfConversation message to the skill to let the
        // skill know that it needs to end its current dialogs, too.
        await innerDc.CancelAllDialogsAsync(cancellationToken);
        return await innerDc.ReplaceDialogAsync(InitialDialogId, "Canceled! \n\n What skill would you like to call?", cancellationToken);
    }

    return await base.OnContinueDialogAsync(innerDc, cancellationToken);
}

Logique du gestionnaire d’activités

La logique de compétence pour chaque tour étant gérée par un dialogue principal, le gestionnaire d’activité ressemble plus à ce qu’il serait pour d’autres exemples de dialogues.

DialogRootBot\Bots\RootBot.cs

public class RootBot<T> : ActivityHandler
    where T : Dialog

private readonly ConversationState _conversationState;
private readonly Dialog _mainDialog;

public RootBot(ConversationState conversationState, T mainDialog)
{
    _conversationState = conversationState;
    _mainDialog = mainDialog;
}

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    if (turnContext.Activity.Type != ActivityTypes.ConversationUpdate)
    {
        // Run the Dialog with the Activity.
        await _mainDialog.RunAsync(turnContext, _conversationState.CreateProperty<DialogState>("DialogState"), cancellationToken);
    }
    else
    {
        // Let the base class handle the activity.
        await base.OnTurnAsync(turnContext, cancellationToken);
    }

    // Save any state changes that might have occurred during the turn.
    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
}

Inscription du service

Les services nécessaires pour utiliser un dialogue de compétence sont les mêmes que ceux nécessaires pour un consommateur de compétences en général. Découvrez comment implémenter un consommateur de compétences pour une discussion des services requis.

Tester le bot racine

Vous pouvez tester le consommateur de compétences dans l’émulateur comme s’il s’agissait d’un bot normal. Toutefois, vous devez exécuter les bots de compétences et de consommateurs de compétences en même temps. Pour plus d’informations sur la configuration de la compétence, découvrez comment implémenter des dialogues dans une compétence.

Téléchargez et installez la dernière version du Bot Framework Emulator.

  1. Exécutez le bot de compétences du dialogue et le bot racine du dialogue localement sur votre ordinateur. Si vous avez besoin d'instructions, consultez README de l'exemple pour C#, JavaScript, Java, Python.
  2. Utiliser l’émulateur pour tester le bot.
    • Lorsque vous joignez la conversation pour la première fois, le bot affiche un message de bienvenue et vous demande quelles compétences vous souhaitez appeler. Le bot de compétences pour cet exemple n’a qu’une compétence.
    • Sélectionnez DialogSkillBot.
  3. Ensuite, le bot vous demande de choisir une action pour la compétence. Choisissez « BookFlight ».
    1. Répondez aux invites.
    2. La compétence se termine, et le bot racine affiche les détails de la réservation avant de vous demander à nouveau quelle compétence que vous souhaitez appeler.
  4. Sélectionnez de nouveau DialogSkillBot et « BookFlight ».
    1. Répondez à la première invite, puis entrez « Abandonner » pour interrompre la compétence.
    2. Le bot racine annule la compétence et vous invite à entrer la compétence que vous souhaitez appeler.

Plus d'informations sur le débogage

Étant donné que le trafic entre les compétences et les consommateurs de compétences est authentifié, des étapes supplémentaires sont nécessaires pour déboguer ces bots.

Dans le cas contraire, vous pouvez déboguer un consommateur de compétences ou une compétence comme vous déboguez d'autres bots. Pour plus d'informations, consultez Débogage d'un bot et Débogage avec Bot Framework Emulator.

Informations supplémentaires

Découvrez comment implémenter un consommateur de compétences en général.