Udostępnij za pośrednictwem

Używanie okna dialogowego do korzystania z umiejętności

  • Artykuł

DOTYCZY: ZESTAW SDK w wersji 4

W tym artykule pokazano, jak używać okna dialogowego umiejętności w użytkowniku umiejętności. Okno dialogowe umiejętności publikuje działania bota nadrzędnego do bota umiejętności i zwraca odpowiedzi umiejętności użytkownikowi. Bot umiejętności, do którego uzyskuje dostęp ten użytkownik, może obsługiwać zarówno działania komunikatów, jak i zdarzeń. Aby uzyskać przykładowy manifest umiejętności i informacje na temat implementowania umiejętności, zobacz, jak używać okien dialogowych w ramach umiejętności.

Aby uzyskać informacje o korzystaniu z bota umiejętności poza oknami dialogowymi, zobacz, jak zaimplementować konsumenta umiejętności.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowych botów rozważ użycie programu Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilot.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

Informacje o tym przykładzie

Przykład umiejętnościDialog zawiera projekty dla dwóch botów:

  • Bot główny okna dialogowego, który używa klasy okna dialogowego umiejętności do korzystania z umiejętności.
  • Bot umiejętności okna dialogowego, który używa okna dialogowego do obsługi działań pochodzących od użytkowników umiejętności.

Ten artykuł koncentruje się na sposobie używania klasy okna dialogowego umiejętności w botze głównym do zarządzania umiejętnościami, wysyłania wiadomości i działań zdarzeń oraz anulowania umiejętności.

Aby uzyskać informacje o innych aspektach tworzenia konsumenta umiejętności, zobacz, jak zaimplementować konsumenta umiejętności.

Aby uzyskać informacje na temat bota umiejętności dialogowych, zobacz, jak używać okien dialogowych w ramach umiejętności.

Zasoby

W przypadku wdrożonych botów uwierzytelnianie bot-to-bot wymaga, aby każdy uczestniczący bot miał prawidłową tożsamość. Możesz jednak testować umiejętności i umiejętności użytkowników lokalnie za pomocą emulatora bot framework bez informacji o tożsamości.

Konfiguracja aplikacji

  1. Opcjonalnie dodaj informacje o tożsamości głównego bota do pliku konfiguracji.
  2. Dodaj punkt końcowy hosta umiejętności (adres URL usługi lub wywołania zwrotnego), do którego umiejętności powinny odpowiadać użytkownik umiejętności.
  3. Dodaj wpis dla każdej umiejętności, której będzie używać użytkownik umiejętności. Każdy wpis obejmuje:
    • Identyfikator używany przez konsumenta umiejętności do identyfikowania każdej umiejętności.
    • Opcjonalnie aplikacja bota umiejętności lub identyfikator klienta.
    • Punkt końcowy obsługi komunikatów umiejętności.

Uwaga

Jeśli użytkownik umiejętności lub umiejętności określa tożsamość, oba muszą.

DialogRootBot\appsettings.json

Opcjonalnie dodaj informacje o tożsamości głównego bota i dodaj do tablicy identyfikator aplikacji lub klienta bota BotFrameworkSkills umiejętności echa.

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

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

Logika okna dialogowego

Główne okno dialogowe bota zawiera okno dialogowe umiejętności dla każdej umiejętności używanej przez bota. Okno dialogowe umiejętności zarządza umiejętnościami za pomocą różnych obiektów związanych z umiejętnościami, takich jak klient umiejętności i obiekty fabryki identyfikatorów konwersacji umiejętności. Główne okno dialogowe pokazuje również, jak anulować umiejętności (za pośrednictwem okna dialogowego umiejętności) na podstawie danych wejściowych użytkownika.

Umiejętność, której używa ten bot, obsługuje kilka różnych funkcji. Może zarezerwować lot lub uzyskać pogodę dla miasta. Ponadto, jeśli otrzyma komunikat poza jednym z tych kontekstów i skonfigurowano rozpoznawanie usługi LUIS, próbuje zinterpretować intencję użytkownika.

Uwaga

Usługa Language Understanding (LUIS) zostanie wycofana 1 października 2025 r. Od 1 kwietnia 2023 r. nie będzie można tworzyć nowych zasobów usługi LUIS. Nowsza wersja interpretacji języka jest teraz dostępna w ramach języka sztucznej inteligencji platformy Azure.

Język konwersacyjny (CLU), funkcja języka AI platformy Azure, to zaktualizowana wersja usługi LUIS. Aby uzyskać więcej informacji na temat obsługi języka w zestawie SDK platformy Bot Framework, zobacz Opis języka naturalnego.

Manifest umiejętności (C#, JavaScript, Java, Python) opisuje akcje, które mogą wykonywać umiejętności, jego parametry wejściowe i wyjściowe oraz punkty końcowe umiejętności. Należy pamiętać, że umiejętności mogą obsługiwać wydarzenie "BookFlight" lub "GetWeather". Może również obsługiwać komunikaty.

Główne okno dialogowe zawiera kod umożliwiający:

Główne okno dialogowe dziedziczy z klasy okna dialogowego składnika. Aby uzyskać więcej informacji o oknach dialogowych składników, zobacz jak zarządzać złożonością okna dialogowego.

Inicjowanie głównego okna dialogowego

Główne okno dialogowe zawiera okna dialogowe (do zarządzania przepływem konwersacji poza umiejętnościami) i okno dialogowe umiejętności (do zarządzania umiejętnościami). Kaskadowy zawiera następujące kroki, opisane bardziej szczegółowo w kilku następnych sekcjach.

  1. Monituj użytkownika o wybranie umiejętności do użycia. (Bot główny korzysta z jednej umiejętności).
  2. Monituj użytkownika o wybranie akcji do użycia dla tej umiejętności. (Bot umiejętności definiuje trzy akcje).
  3. Rozpocznij wybraną umiejętność z początkowym działaniem na podstawie wybranej akcji.
  4. Po ukończeniu umiejętności wyświetl wyniki, jeśli istnieją. Następnie ponownie uruchom kaskadę.

DialogRootBot\Dialogs\MainDialog.cs

Klasa MainDialog pochodzi z klasy ComponentDialog. Oprócz stanu konwersacji okno dialogowe wymaga tożsamości i odwołań bota głównego do fabryki identyfikatorów konwersacji umiejętności, klienta HTTP umiejętności i obiektów konfiguracji umiejętności.

Konstruktor okna dialogowego sprawdza parametry wejściowe, dodaje okna dialogowe umiejętności, dodaje okna dialogowe monitów i kaskadowych do zarządzania przepływem konwersacji poza umiejętnością i tworzy metodę dostępu właściwości do śledzenia aktywnych umiejętności, jeśli istnieją.

Konstruktor wywołuje AddSkillDialogsmetodę pomocnika , aby utworzyć SkillDialog dla każdej umiejętności zawartej w pliku konfiguracji, zgodnie z odczytem SkillsConfiguration z pliku konfiguracji do obiektu.

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

Wybierz umiejętność

W pierwszym kroku główne okno dialogowe monituje użytkownika, do którego umiejętności chcesz wywołać, i używa monitu wyboru "SkillPrompt", aby uzyskać odpowiedź. (Ten bot definiuje tylko jedną umiejętność).

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

Wybieranie akcji umiejętności

W następnym kroku główne okno dialogowe:

  1. Zapisuje informacje o umiejętności wybranej przez użytkownika.
  2. Monituje użytkownika o akcję umiejętności, której chcesz użyć, i używa monitu wyboru "SkillActionPrompt", aby uzyskać odpowiedź.
    • Używa metody pomocniczej, aby uzyskać listę akcji do wyboru.
    • Moduł sprawdzania poprawności monitu skojarzony z tym monitem domyślnie wyśle do umiejętności komunikat, jeśli dane wejściowe użytkownika nie pasują do jednej z opcji.

Opcje zawarte w tym botze ułatwiają testowanie akcji zdefiniowanych dla tej umiejętności. Zazwyczaj można odczytać opcje z manifestu umiejętności i przedstawić użytkownikowi opcje na podstawie tej listy.

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

Rozpoczynanie umiejętności

W następnym kroku główne okno dialogowe:

  1. Pobiera informacje o umiejętności i aktywności umiejętności wybranej przez użytkownika.
  2. Używa metody pomocniczej, aby utworzyć działanie do początkowego wysłania do umiejętności.
  3. Tworzy opcje okna dialogowego, za pomocą których należy uruchomić okno dialogowe umiejętności. Obejmuje to początkowe działanie do wysłania.
  4. Zapisuje stan przed wywołaniem umiejętności. (Jest to konieczne, ponieważ odpowiedź na umiejętności może przyjść do innego wystąpienia konsumenta umiejętności).
  5. Rozpoczyna okno dialogowe umiejętności, przekazując identyfikator umiejętności do wywołania i opcje, za pomocą których ma być wywoływana.

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

Podsumowanie wyniku umiejętności

W ostatnim kroku główne okno dialogowe:

  1. Jeśli umiejętność zwróciła wartość, wyświetl wynik użytkownikowi.
  2. Czyści aktywną umiejętność ze stanu okna dialogowego.
  3. Usuwa właściwość aktywnej umiejętności ze stanu konwersacji.
  4. Uruchamia się ponownie (główne okno dialogowe).

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

Zezwalanie użytkownikowi na anulowanie umiejętności

Główne okno dialogowe zastępuje domyślne zachowanie metody w oknie dialogowym kontynuuj, aby umożliwić użytkownikowi anulowanie bieżącej umiejętności, jeśli istnieje. W ramach metody:

  • Jeśli istnieje aktywna umiejętność, a użytkownik wysyła komunikat "przerwania", anuluj wszystkie okna dialogowe i dodaj do kolejki główne okno dialogowe, aby ponownie uruchomić się od początku.
  • Następnie wywołaj podstawową implementację metody w oknie dialogowym on continue, aby kontynuować przetwarzanie bieżącego kolei.

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 obsługi działań

Ponieważ logika umiejętności dla każdego kolei jest obsługiwana przez główne okno dialogowe, procedura obsługi działań wygląda podobnie jak w przypadku innych przykładów okien dialogowych.

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

Rejestracja usługi

Usługi potrzebne do korzystania z okna dialogowego umiejętności są takie same, jak w przypadku konsumenta umiejętności. Zobacz, jak zaimplementować konsumenta umiejętności, aby zapoznać się z omówieniem wymaganych usług.

Testowanie bota głównego

Możesz przetestować użytkownika umiejętności w emulatorze tak, jakby był to normalny bot; należy jednak jednocześnie uruchamiać boty konsumpcyjne umiejętności i umiejętności. Zobacz, jak używać okien dialogowych w ramach umiejętności , aby uzyskać informacje na temat konfigurowania umiejętności.

Pobierz i zainstaluj najnowszą wersję programu Bot Framework Emulator.

  1. Uruchom bota umiejętności okna dialogowego i lokalnego bota głównego okna dialogowego na maszynie. Jeśli potrzebujesz instrukcji, zapoznaj się z przykładami README dla języków C#, JavaScript, Java, Python.
  2. Użyj emulatora, aby przetestować bota.
    • Po pierwszym dołączeniu do konwersacji bot wyświetla wiadomość powitalną i o umiejętności, które chcesz wywołać. Bot umiejętności dla tego przykładu ma tylko jedną umiejętność.
    • Wybierz pozycję DialogSkillBot.
  3. Następnie bot prosi o wybranie akcji dotyczącej umiejętności. Wybierz pozycję "BookFlight".
    1. Odpowiedz na monity.
    2. Umiejętności zostaną ukończone, a bot główny wyświetli szczegóły rezerwacji przed ponownym wyświetleniem monitu o umiejętności, które chcesz wywołać.
  4. Ponownie wybierz pozycję DialogSkillBot i "BookFlight".
    1. Odpowiedz na pierwszy monit, a następnie wprowadź "abort", aby przerwać umiejętności.
    2. Bot główny anuluje umiejętności i monituje o umiejętności, które chcesz wywołać.

Więcej informacji o debugowaniu

Ponieważ ruch między umiejętnościami i użytkownikami umiejętności jest uwierzytelniany, podczas debugowania takich botów są wykonywane dodatkowe kroki.

  • Użytkownik umiejętności i wszystkie umiejętności, których używa, bezpośrednio lub pośrednio, muszą być uruchomione.
  • Jeśli boty działają lokalnie i jeśli którykolwiek z botów ma identyfikator aplikacji i hasło, wszystkie boty muszą mieć prawidłowe identyfikatory i hasła.
  • Jeśli wszystkie boty są wdrożone, zobacz, jak debugować bota z dowolnego kanału przy użyciu metodyki devtunnel.
  • Jeśli niektóre boty działają lokalnie, a niektóre są wdrażane, zobacz, jak debugować umiejętności lub umiejętności użytkownika.

W przeciwnym razie możesz debugować użytkownika umiejętności lub umiejętności podobne do debugowania innych botów. Aby uzyskać więcej informacji, zobacz Debugowanie bota i Debugowanie za pomocą emulatora platformy Bot Framework.

Dodatkowe informacje

Zobacz, jak zaimplementować konsumenta umiejętności, aby dowiedzieć się, jak zaimplementować konsumenta umiejętności w ogóle.