Sdílet prostřednictvím

Využití dovednosti pomocí dialogového okna

  • Článek

PLATÍ PRO: SDK v4

Tento článek ukazuje, jak používat dialog dovedností v rámci příjemce dovedností. Dialog dovedností publikuje aktivity z nadřazeného robota do robota dovedností a vrací odpovědi na dovednosti uživateli. Kvalifikovaný robot, ke tomuto příjemci, může zpracovávat aktivity zpráv i událostí. Ukázkový manifest dovednosti a informace o implementaci dovednosti najdete v tématu použití dialogů v rámci dovednosti.

Informace o používání robota dovedností mimo dialogy najdete v tématu implementace dovednosti konzumenta.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Při vytváření nových robotů zvažte použití aplikace Microsoft Copilot Studio a přečtěte si o výběru správného řešení copilotu.

Další informace najdete v tématu Budoucnost vytváření robotů.

Požadavky

O této ukázce

Ukázka dovednostíDialog dovedností zahrnuje projekty pro dva roboty:

  • The dialog root bot, which uses a skill dialog class to consume a skill.
  • Robot dovedností dialogového okna, který používá dialogové okno pro zpracování aktivit pocházejících od příjemců dovedností.

Tento článek se zaměřuje na to, jak používat třídu dialogových oken dovedností v kořenovém robotovi ke správě dovednosti, k odesílání zpráv a aktivit událostí a ke zrušení dovednosti.

Informace o dalších aspektech vytváření příjemce dovedností najdete v tématu Implementace dovednosti spotřebitele.

Informace o robotovi dovedností dialogového okna najdete v tématu použití dialogových oken v rámci dovednosti.

Zdroje informací

U nasazených robotů vyžaduje ověřování robota k robotovi platnou identitu každého zúčastněného robota. Pomocí bot Framework Emulatoru ale můžete testovat dovednosti a uživatele dovedností místně bez informací o identitě.

Konfigurace aplikací

  1. Volitelně můžete do konfiguračního souboru přidat informace o identitě kořenového robota.
  2. Přidejte koncový bod hostitele dovedností (adresu URL služby nebo zpětného volání), do kterého by měly dovednosti odpovídat příjemci dovedností.
  3. Přidejte položku pro každou dovednost, která bude spotřebitel dovedností používat. Každá položka zahrnuje:
    • ID, které příjemce dovednosti použije k identifikaci jednotlivých dovedností.
    • Volitelně je možné, že aplikace robota dovednosti nebo ID klienta.
    • Koncový bod zasílání zpráv dovednosti.

Poznámka:

Pokud dovednost nebo příjemce dovednosti specifikuje identitu, musí být oba.

DialogRootBot\appsettings.json

Volitelně můžete přidat informace o identitě kořenového robota a přidat do pole aplikaci nebo ID klienta robota dovednosti odezvy BotFrameworkSkills .

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

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

Logika dialogového okna

Hlavní dialog robota obsahuje dialog dovedností pro každou dovednost, kterou tento robot využívá. Dialog dovedností spravuje dovednost prostřednictvím různých objektů souvisejících s dovednostmi, jako je klient dovedností a objekty objektu pro vytváření ID konverzace dovedností. Hlavní dialog také ukazuje, jak zrušit dovednost (prostřednictvím dialogového okna dovednosti) na základě uživatelského vstupu.

Dovednosti, které tento robot používá, podporuje několik různých funkcí. Může si rezervovat let nebo získat počasí pro město. Pokud navíc obdrží zprávu mimo některý z těchto kontextů a nakonfiguruje se rozpoznávání LUIS, pokusí se interpretovat záměr uživatele.

Poznámka:

Služba Language Understanding (LUIS) bude vyřazena 1. října 2025. Od 1. dubna 2023 nebudete moct vytvářet nové prostředky LUIS. Novější verze language understanding je teď dostupná jako součást jazyka Azure AI.

Konverzační jazyk understanding (CLU), funkce jazyka Azure AI, je aktualizovaná verze služby LUIS. Další informace o podpoře porozumění jazyku v sadě SDK služby Bot Framework najdete v tématu Principy přirozeného jazyka.

Manifest dovednosti (C#, JavaScript, Java, Python) popisuje akce, které může dovednost provádět, její vstupní a výstupní parametry a koncové body dovednosti. Nezapomeňte, že dovednost dokáže zpracovat událost "BookFlight" nebo "GetWeather". Může také zpracovávat zprávy.

Hlavní dialog obsahuje kód pro:

Hlavní dialogové okno dědí z třídy dialogového okna komponenty. Další informace o dialogových oknech komponent najdete v tématu správa složitosti dialogového okna.

Inicializace hlavního dialogového okna

Hlavní dialog obsahuje dialogy (pro správu toku konverzací mimo dovednost) a dialog dovedností (pro správu dovedností). Vodopád obsahuje následující kroky, které jsou podrobněji popsány v následujících několika částech.

  1. Vyzvat uživatele, aby vybral dovednost, která se má použít. (Kořenový robot využívá jednu dovednost.)
  2. Vyzvat uživatele, aby pro tuto dovednost vybral akci, kterou chcete použít. (Robot dovedností definuje tři akce.)
  3. Zahajte zvolenou dovednost počáteční aktivitou na základě zvolené akce.
  4. Jakmile se dovednost dokončí, zobrazte výsledky( pokud existuje). Pak restartujte vodopád.

DialogRootBot\Dialogs\MainDialog.cs

Třída MainDialog je odvozena z ComponentDialog. Kromě stavu konverzace potřebuje dialog identitu kořenového robota a odkazy na továrnu ID konverzace dovedností, klienta HTTP dovednosti a objekty konfigurace dovedností.

Konstruktor dialogového okna zkontroluje své vstupní parametry, přidá dialogy dovedností, přidá dialogy výzvy a vodopády pro správu toku konverzace mimo dovednost a vytvoří přístup k vlastnosti pro sledování aktivní dovednosti, pokud existuje.

Konstruktor volá AddSkillDialogspomocnou metodu, která vytvoří SkillDialog pro každou dovednost, která je součástí konfiguračního souboru, jak je přečteno z konfiguračního souboru do objektu 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));
    }
}

Vyberte dovednost

V prvním kroku hlavní dialog vyzve uživatele, pro kterou dovednost chce volat, a pomocí výzvy "SkillPrompt" dostane odpověď. (Tento robot definuje pouze jednu dovednost.)

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

Výběr akce dovednosti

V dalším kroku hlavní dialogové okno:

  1. Uloží informace o dovednostech, které uživatel vybral.
  2. Vyzve uživatele, pro kterou akci dovednosti chce použít, a pomocí výzvy "SkillActionPrompt" dostane odpověď.
    • Používá pomocnou metodu k získání seznamu akcí, ze které si můžete vybrat.
    • Validátor výzvy přidružený k této výzvě ve výchozím nastavení odešle dovednost zprávy, pokud vstup uživatele neodpovídá jedné z možností.

Volby zahrnuté v tomto robotovi pomáhají testovat akce definované pro tuto dovednost. Častěji byste si přečetli možnosti z manifestu dovednosti a představili uživatelům možnosti na základě tohoto seznamu.

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

Zahajte dovednost

V dalším kroku hlavní dialogové okno:

  1. Načte informace o dovednostech a dovednostech, které uživatel vybral.
  2. Používá pomocnou metodu k vytvoření aktivity pro počáteční odeslání dovednosti.
  3. Vytvoří možnosti dialogového okna, pomocí kterého se má spustit dialog dovedností. To zahrnuje počáteční aktivitu, která se má odeslat.
  4. Uloží stav před voláním dovednosti. (To je nezbytné, protože reakce na dovednosti může přijít na jinou instanci příjemce dovedností.)
  5. Spustí dialogové okno dovednosti a předá ID dovednosti pro volání a možnosti, se kterými se má volat.

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

Shrnutí výsledku dovednosti

V posledním kroku hlavní dialogové okno:

  1. Pokud dovednost vrátila hodnotu, zobrazte uživateli výsledek.
  2. Vymaže aktivní dovednost ze stavu dialogového okna.
  3. Odebere vlastnost aktivní dovednosti ze stavu konverzace.
  4. Restartuje se sám (hlavní dialogové okno).

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

Povolit uživateli zrušit dovednost

Hlavní dialog přepíše výchozí chování metody při pokračování dialogového okna , aby uživatel mohl zrušit aktuální dovednost, pokud existuje. V rámci metody:

  • Pokud je aktivní dovednost a uživatel odešle zprávu o přerušení, zrušte všechna dialogová okna a zařadíte hlavní dialog do fronty, aby se restartoval od začátku.
  • Potom zavolejte základní implementaci metody při pokračování dialogového okna pokračovat ve zpracování aktuálního turnu.

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

Logika obslužné rutiny aktivity

Vzhledem k tomu, že logika dovedností pro každé otáčení je zpracována hlavním dialogem, obslužná rutina aktivity vypadá podobně jako u jiných ukázek dialogů.

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

Registrace služby

Služby potřebné k používání dialogu dovedností jsou stejné jako služby potřebné pro spotřebitele dovedností obecně. Podívejte se , jak implementovat příjemce dovedností pro diskuzi o požadovaných službách.

Testování kořenového robota

Uživatele dovednosti můžete otestovat v emulátoru, jako by šlo o normálního robota. Musíte však současně spouštět dovednosti i roboty uživatelů. Podívejte se , jak používat dialogy v rámci dovednosti , kde najdete informace o konfiguraci dovednosti.

Stáhněte a nainstalujte nejnovější bot Framework Emulator.

  1. Spusťte robota dovednosti dialogového okna a kořenového robota dialogového okna místně na svém počítači. Pokud potřebujete pokyny, projděte si ukázku README pro C#, JavaScript, Java, Python.
  2. K otestování robota použijte emulátor.
    • Když se k konverzaci poprvé připojíte, robot zobrazí uvítací zprávu a zeptá se, jakou dovednost byste chtěli volat. Robot dovedností pro tuto ukázku má jen jednu dovednost.
    • Vyberte DialogSkillBot.
  3. Pak vás robot požádá o výběr akce pro dovednost. Zvolte "BookFlight".
    1. Odpovězte na výzvy.
    2. Dovednost se dokončí a kořenový robot před opětovnou výzvou k zadání dovednosti, kterou chcete volat, zobrazí podrobnosti o rezervaci.
  4. Znovu vyberte DialogSkillBot a BookFlight.
    1. Odpovězte na první výzvu a pak zadejte "přerušit" a přerušte dovednost.
    2. Kořenový robot zruší dovednosti a vyzve k zadání dovednosti, kterou chcete zavolat.

Další informace o ladění

Vzhledem k tomu, že se ověřuje provoz mezi dovednostmi a uživateli dovedností, při ladění takových robotů existují další kroky.

  • Dovednost konzument a všechny dovednosti, které využívá, přímo nebo nepřímo, musí být spuštěné.
  • Pokud jsou roboti spuštěni místně a pokud některý z robotů má ID a heslo aplikace, musí mít všichni roboti platné ID a hesla.
  • Pokud jsou roboti všichni nasazeni, podívejte se , jak ladit robota z libovolného kanálu pomocí devtunnelu.
  • Pokud některé roboty běží místně a některé se nasadí, podívejte se , jak ladit dovednosti nebo příjemce dovedností.

Jinak můžete ladit dovednost uživatele nebo dovednosti podobně jako ostatní roboty. Další informace naleznete v tématu Ladění robota a ladění pomocí bot Framework Emulator.

Další informace

Podívejte se , jak implementovat příjemce dovedností, jak obecně implementovat dovednost spotřebitele.