Delen via

Een dialoogvenster gebruiken om een vaardigheid te gebruiken

  • Artikel

VAN TOEPASSING OP: SDK v4

In dit artikel wordt beschreven hoe u een vaardigheidsdialoogvenster binnen een vaardigheidsconsumer kunt gebruiken. Het vaardigheidsdialoogvenster plaatst activiteiten van de bovenliggende bot in de vaardigheidsbot en retourneert de vaardigheidsreacties voor de gebruiker. De vaardigheidsbot die door deze consument wordt geopend, kan zowel bericht- als gebeurtenisactiviteiten verwerken. Zie hoe u dialoogvensters in een vaardigheid in een vaardigheid kunt gebruiken voor een voorbeeldmanifest en informatie over het implementeren van de vaardigheid.

Zie hoe u een vaardigheidsgebruiker implementeert voor informatie over het gebruik van een vaardigheidsbot buiten dialoogvensters.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Vereisten

Over dit voorbeeld

Het skills skillDialog-voorbeeld bevat projecten voor twee bots:

  • De hoofdmap van het dialoogvenster, dat gebruikmaakt van een vaardigheidsdialoogvensterklasse om een vaardigheid te gebruiken.
  • De dialoogvenster-vaardigheidsbot, die een dialoogvenster gebruikt voor het afhandelen van activiteiten die afkomstig zijn van gebruikers van vaardigheden.

Dit artikel is gericht op het gebruik van een vaardigheidsdialoogvenster in een hoofdbot om de vaardigheid te beheren, berichten en gebeurtenisactiviteiten te verzenden en de vaardigheid te annuleren.

Zie hoe u een vaardigheidsconsumer implementeert voor informatie over andere aspecten van het maken van een vaardigheidsconsumer.

Zie hoe u dialoogvensters in een vaardigheidsbot kunt gebruiken voor informatie over de bot met dialoogvensters.

Resources

Voor geïmplementeerde bots vereist bot-naar-bot-verificatie dat elke deelnemende bot een geldige identiteit heeft. U kunt echter lokaal vaardigheden en vaardigheidsgebruikers testen met de Bot Framework Emulator zonder identiteitsgegevens.

Toepassingsconfiguratie

  1. Voeg eventueel de identiteitsgegevens van de hoofdbot toe aan het configuratiebestand.
  2. Voeg het hosteindpunt voor vaardigheden (de service- of callback-URL) toe waaraan de vaardigheden moeten reageren op de vaardigheidsgebruiker.
  3. Voeg een vermelding toe voor elke vaardigheid die de consument gaat gebruiken. Elke vermelding omvat:
    • Een id die de consument gebruikt om elke vaardigheid te identificeren.
    • Optioneel, de app of client-id van de vaardigheidsbot.
    • Het berichteindpunt van de vaardigheid.

Notitie

Als de gebruiker van de vaardigheid of vaardigheid een identiteit aangeeft, moeten beide identiteiten worden opgegeven.

DialogRootBot\appsettings.json

Voeg eventueel de identiteitsgegevens van de hoofdbot toe en voeg de app- of client-id voor de bot met echovaardigheden toe aan de BotFrameworkSkills matrix.

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

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

Dialoogvensterlogica

Het hoofddialoogvenster van de bot bevat een dialoogvenster voor vaardigheden voor elke vaardigheid die door deze bot wordt gebruikt. Het vaardigheidsdialoogvenster beheert de vaardigheid via de verschillende vaardigheidsgerelateerde objecten, zoals de vaardigheidsclient en de id-objecten van de vaardigheidsgespreks-id. Het hoofddialoogvenster laat ook zien hoe u de vaardigheid (via het vaardigheidsdialoogvenster) annuleert op basis van gebruikersinvoer.

De vaardigheid die deze bot gebruikt, ondersteunt een aantal verschillende functies. Het kan een vlucht boeken of het weer voor een stad krijgen. Als er bovendien een bericht wordt ontvangen buiten een van deze contexten en een LUIS-recognizer is geconfigureerd, wordt geprobeerd de intentie van de gebruiker te interpreteren.

Notitie

Language Understanding (LUIS) wordt op 1 oktober 2025 buiten gebruik gesteld. Vanaf 1 april 2023 kunt u geen nieuwe LUIS-resources maken. Er is nu een nieuwere versie van taalkennis beschikbaar als onderdeel van Azure AI Language.

Conversational Language Understanding (CLU), een functie van Azure AI Language, is de bijgewerkte versie van LUIS. Zie Natuurlijke taalkennis voor meer informatie over ondersteuning voor taalkennis in de Bot Framework SDK.

Het vaardigheidsmanifest (C#, JavaScript, Java, Python) beschrijft de acties die de vaardigheid kan uitvoeren, de invoer- en uitvoerparameters en de eindpunten van de vaardigheid. Opmerking: de vaardigheid kan een gebeurtenis 'BookFlight' of 'GetWeather' afhandelen. Het kan ook berichten verwerken.

Het hoofddialoogvenster bevat code voor:

Het hoofddialoogvenster wordt overgenomen van de klasse van het onderdeeldialoogvenster . Zie voor meer informatie over onderdeeldialoogvensters hoe u de complexiteit van dialoogvensters beheert.

Het hoofddialoogvenster initialiseren

Het hoofddialoogvenster bevat dialoogvensters (voor het beheren van de gespreksstroom buiten de vaardigheid) en een dialoogvenster voor vaardigheden (voor het beheren van de vaardigheden). De waterval bevat de volgende stappen, die in de volgende secties gedetailleerder worden beschreven.

  1. Vraag de gebruiker om de vaardigheid te selecteren die moet worden gebruikt. (De hoofdbot verbruikt één vaardigheid.)
  2. Vraag de gebruiker om de actie te selecteren die voor die vaardigheid moet worden gebruikt. (De vaardigheidsbot definieert drie acties.)
  3. Start de gekozen vaardigheid met een initiële activiteit op basis van de gekozen actie.
  4. Zodra de vaardigheid is voltooid, worden de resultaten weergegeven, indien van toepassing. Start vervolgens de waterval opnieuw op.

DialogRootBot\Dialogs\MainDialog.cs

De MainDialog klasse is afgeleid van ComponentDialog. Naast de gespreksstatus heeft het dialoogvenster de identiteit en verwijzingen van de hoofdbot nodig naar de vaardigheidsgespreks-id factory, de vaardigheids-HTTP-client en de vaardighedenconfiguratieobjecten.

De dialoogvensterconstructor controleert de invoerparameters, voegt dialoogvensters voor vaardigheden toe, voegt prompt- en watervaldialoogvensters toe voor het beheren van de gespreksstroom buiten de vaardigheid en maakt een eigenschapstoegangsfunctie voor het bijhouden van de actieve vaardigheid, indien van toepassing.

De constructor roept AddSkillDialogseen helpermethode aan om een SkillDialog voor elke vaardigheid te maken die is opgenomen in het configuratiebestand, zoals gelezen uit het configuratiebestand in een SkillsConfiguration object.

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

Een vaardigheid selecteren

In de eerste stap vraagt het hoofddialoogvenster de gebruiker om welke vaardigheid ze willen aanroepen en gebruikt de keuzeprompt SkillPrompt om het antwoord op te halen. (Deze bot definieert slechts één vaardigheid.)

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);
}

Een vaardigheidsactie selecteren

In de volgende stap, het hoofddialoogvenster:

  1. Hiermee wordt informatie opgeslagen over de vaardigheid die de gebruiker heeft geselecteerd.
  2. Vraagt de gebruiker om welke vaardigheidsactie ze willen gebruiken en gebruikt de keuzeprompt SkillActionPrompt om het antwoord op te halen.
    • Er wordt een helpermethode gebruikt om een lijst met acties op te halen waaruit u kunt kiezen.
    • De promptvalidator die aan deze prompt is gekoppeld, verzendt standaard een bericht over de vaardigheid als de invoer van de gebruiker niet overeenkomt met een van de opties.

De keuzes in deze bot helpen bij het testen van de acties die voor deze vaardigheid zijn gedefinieerd. Normaal gesproken leest u de opties uit het manifest van de vaardigheid en presenteert u opties aan de gebruiker op basis van die lijst.

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);
}

Een vaardigheid starten

In de volgende stap, het hoofddialoogvenster:

  1. Haalt informatie op over de vaardigheids- en vaardigheidsactiviteit die de gebruiker heeft geselecteerd.
  2. Gebruikt een helpermethode om de activiteit te maken die in eerste instantie naar de vaardigheid moet worden verzonden.
  3. Hiermee maakt u de dialoogvensteropties waarmee u het dialoogvenster vaardigheid wilt starten. Dit omvat de eerste activiteit die moet worden verzonden.
  4. Hiermee wordt de status opgeslagen voordat u de vaardigheid aanroept. (Dit is nodig, omdat het antwoord op vaardigheden kan komen tot een ander exemplaar van de vaardigheidsconsumer.)
  5. Hiermee begint u het vaardigheidsdialoogvenster, waarbij u de vaardigheids-id doorgeeft die moet worden aangeroepen en de opties waarmee u deze wilt aanroepen.

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);
}

Het vaardigheidsresultaat samenvatten

In de laatste stap, het hoofddialoogvenster:

  1. Als de vaardigheid een waarde heeft geretourneerd, geeft u het resultaat weer aan de gebruiker.
  2. Hiermee wist u de actieve vaardigheid uit de dialoogvensterstatus.
  3. Hiermee verwijdert u de actieve vaardigheidseigenschap uit de gespreksstatus.
  4. Start zichzelf opnieuw op (het hoofddialoogvenster).

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);
}

Toestaan dat de gebruiker de vaardigheid annuleert

In het hoofddialoogvenster wordt het standaardgedrag van de dialoogvenstermethode voor doorgaan overschreven, zodat de gebruiker de huidige vaardigheid kan annuleren, indien van toepassing. Binnen de methode:

  • Als er een actieve vaardigheid is en de gebruiker een bericht 'afgebroken' verzendt, annuleert u alle dialoogvensters en zet u het hoofddialoogvenster in de wachtrij om vanaf het begin opnieuw op te starten.
  • Roep vervolgens de basisuitvoering van de dialoogvenstermethode Voor doorgaan aan om door te gaan met het verwerken van de huidige draai.

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);
}

Logica voor activiteitshandler

Omdat vaardigheidslogica voor elke beurt wordt verwerkt door een hoofddialoogvenster, ziet de activiteitshandler er ongeveer hetzelfde uit als voor andere dialoogvensters.

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);
}

Serviceregistratie

De services die nodig zijn om een dialoogvenster voor vaardigheden te gebruiken, zijn hetzelfde als de services die nodig zijn voor een vaardigheidsconsumer in het algemeen. Bekijk hoe u een vaardigheidsconsumer implementeert voor een bespreking van de vereiste services.

De hoofdbot testen

U kunt de vaardigheidsconsumer in de emulator testen alsof het een normale bot is; U moet echter tegelijkertijd zowel de vaardigheid als de vaardigheid van consumentenbots uitvoeren. Zie hoe u dialoogvensters in een vaardigheid gebruikt voor informatie over het configureren van de vaardigheid.

Download en installeer de nieuwste Bot Framework Emulator.

  1. Voer de bot voor dialoogvenstervaardigheden en de hoofdmap van het dialoogvenster lokaal uit op uw computer. Als u instructies nodig hebt, raadpleegt u de voorbeelden README voor C#, JavaScript, Java, Python.
  2. Gebruik de emulator om de bot te testen.
    • Wanneer u voor het eerst deelneemt aan het gesprek, geeft de bot een welkomstbericht weer en wordt u gevraagd welke vaardigheid u wilt bellen. De vaardigheidsbot voor dit voorbeeld heeft slechts één vaardigheid.
    • Selecteer DialogSkillBot.
  3. Vervolgens vraagt de bot u om een actie voor de vaardigheid te kiezen. Kies 'BookFlight'.
    1. Beantwoord de aanwijzingen.
    2. De vaardigheid is voltooid en de hoofdbot geeft de reserveringsgegevens weer voordat u opnieuw wordt gevraagd om de vaardigheid die u wilt aanroepen.
  4. Selecteer DialogSkillBot opnieuw en 'BookFlight'.
    1. Beantwoord de eerste prompt en voer vervolgens 'afbreken' in om de vaardigheid te onderbreken.
    2. De hoofdbot annuleert de vaardigheid en vraagt om de vaardigheid die u wilt aanroepen.

Meer informatie over foutopsporing

Omdat verkeer tussen vaardigheden en vaardigheidsgebruikers wordt geverifieerd, zijn er extra stappen bij het opsporen van fouten in dergelijke bots.

Anders kunt u fouten opsporen in een vaardigheidsconsumer of vaardigheid, net zoals bij het opsporen van fouten in andere bots. Zie Fouten opsporen in een bot en fouten opsporen met de Bot Framework Emulator voor meer informatie.

Aanvullende informatie

Zie hoe u een vaardigheidsconsumer implementeert voor het implementeren van een vaardigheidsconsumer in het algemeen.