Megosztás a következőn keresztül:

Speciális beszélgetési folyamat létrehozása ágak és hurkok használatával

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A párbeszédtár használatával összetett beszélgetési folyamatokat hozhat létre. Ez a cikk bemutatja, hogyan kezelheti az elágazó és hurkos összetett beszélgetéseket, és hogyan adhat át argumentumokat a párbeszédpanel különböző részei között.

Feljegyzés

A Bot Framework JavaScript, C# és Python SDK-k továbbra is támogatottak lesznek, a Java SDK-t azonban 2023 novemberében végső hosszú távú támogatással kivonják.

A Java SDK-val létrehozott meglévő robotok továbbra is működni fognak.

Az új robotépítéshez fontolja meg a Microsoft Copilot Studio használatát, és olvassa el a megfelelő copilot-megoldás kiválasztását.

További információ: A robotépítés jövője.

Előfeltételek

A minta ismertetése

Ez a minta egy robotot jelöl, amely feliratkozhat a felhasználókra, hogy akár két vállalatot is áttekinthessenek egy listából. A robot három összetevő párbeszédpanelt használ a beszélgetési folyamat kezeléséhez. Minden összetevő párbeszédpanel tartalmaz egy vízesés párbeszédpanelt, és minden olyan kérést, amely a felhasználói bemenetek gyűjtéséhez szükséges. Ezeket a párbeszédpaneleket részletesebben a következő szakaszok ismertetik. Beszélgetési állapotot használ a párbeszédpanelek kezeléséhez, a felhasználói állapot használatával pedig adatokat ment a felhasználóról, valamint arról, hogy mely vállalatokat szeretné áttekinteni.

A robot a tevékenységkezelőből származik. A mintarobotokhoz hasonlóan üdvözli a felhasználót, párbeszédpanelekkel kezeli a felhasználótól érkező üzeneteket, és menti a felhasználó és a beszélgetés állapotát a forduló vége előtt.

A párbeszédpanelek használatához telepítse a Microsoft.Bot.Builder.Dialogs NuGet csomagot.

C#-minta osztálydiagramja.

A felhasználói profil definiálása

A felhasználói profil a párbeszédpanelek által gyűjtött információkat, a felhasználó nevét, életkorát és a véleményezésre kijelölt vállalatokat tartalmazza.

UserProfile.cs

/// <summary>Contains information about a user.</summary>
public class UserProfile
{
    public string Name { get; set; }

    public int Age { get; set; }

    // The list of companies the user wants to review.
    public List<string> CompaniesToReview { get; set; } = new List<string>();

Párbeszédpanelek létrehozása

Ez a robot három párbeszédpanelt tartalmaz:

  • A fő párbeszédpanel elindítja az általános folyamatot, majd összegzi az összegyűjtött információkat.
  • A legfelső szintű párbeszédpanel összegyűjti a felhasználói adatokat, és elágaztatási logikát tartalmaz a felhasználó életkora alapján.
  • A véleményezés-kiválasztás párbeszédpanel lehetővé teszi a felhasználó számára, hogy iteratív módon válassza ki az áttekintendő vállalatokat. Ehhez hurkolási logikát használ.

A fő párbeszédpanel

A fő párbeszédpanel két lépésből áll:

  1. Indítsa el a legfelső szintű párbeszédpanelt.
  2. Kérje le és összegezze a legfelső szintű párbeszédpanel által gyűjtött felhasználói profilt, mentse az adatokat a felhasználói állapotba, majd jelezze a fő párbeszédpanel végét.

Párbeszédpanelek\MainDialog.cs

private async Task<DialogTurnResult> InitialStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    return await stepContext.BeginDialogAsync(nameof(TopLevelDialog), null, cancellationToken);
}

private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var userInfo = (UserProfile)stepContext.Result;

    string status = "You are signed up to review "
        + (userInfo.CompaniesToReview.Count is 0 ? "no companies" : string.Join(" and ", userInfo.CompaniesToReview))
        + ".";

    await stepContext.Context.SendActivityAsync(status);

    var accessor = _userState.CreateProperty<UserProfile>(nameof(UserProfile));
    await accessor.SetAsync(stepContext.Context, userInfo, cancellationToken);

    return await stepContext.EndDialogAsync(null, cancellationToken);
}

A legfelső szintű párbeszédpanel

A legfelső szintű párbeszédpanel négy lépésből áll:

  1. Kérje meg a felhasználó nevét.
  2. Kérje meg a felhasználó életkorát.
  3. Indítsa el a véleményezési párbeszédpanelt, vagy haladjon tovább a következő lépésre a felhasználó életkora alapján.
  4. Végül köszönjük a felhasználónak a részvételt, és küldje vissza az összegyűjtött információkat.

Az első lépés egy üres felhasználói profilt hoz létre a párbeszédpanel állapotának részeként. A párbeszédpanel üres profillal kezdődik, és a folyamat során információkat ad hozzá a profilhoz. A befejezéskor az utolsó lépés az összegyűjtött adatokat adja vissza.

A harmadik (kijelölés indítása) lépésben a beszélgetési folyamat elágazik a felhasználó életkora alapján.

Párbeszédpanelek\TopLevelDialog.cs

            stepContext.Values[UserInfo] = new UserProfile();

            var promptOptions = new PromptOptions { Prompt = MessageFactory.Text("Please enter your name.") };

            // Ask the user to enter their name.
            return await stepContext.PromptAsync(nameof(TextPrompt), promptOptions, cancellationToken);
        }

        private async Task<DialogTurnResult> AgeStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's name to what they entered in response to the name prompt.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.Name = (string)stepContext.Result;

            var promptOptions = new PromptOptions { Prompt = MessageFactory.Text("Please enter your age.") };

            // Ask the user to enter their age.
            return await stepContext.PromptAsync(nameof(NumberPrompt<int>), promptOptions, cancellationToken);
        }

        private async Task<DialogTurnResult> StartSelectionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's age to what they entered in response to the age prompt.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.Age = (int)stepContext.Result;

            if (userProfile.Age < 25)
            {
                // If they are too young, skip the review selection dialog, and pass an empty list to the next step.
                await stepContext.Context.SendActivityAsync(
                    MessageFactory.Text("You must be 25 or older to participate."),
                    cancellationToken);
                return await stepContext.NextAsync(new List<string>(), cancellationToken);
            }
            else
            {
                // Otherwise, start the review selection dialog.
                return await stepContext.BeginDialogAsync(nameof(ReviewSelectionDialog), null, cancellationToken);
            }
        }

        private async Task<DialogTurnResult> AcknowledgementStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
        {
            // Set the user's company selection to what they entered in the review-selection dialog.
            var userProfile = (UserProfile)stepContext.Values[UserInfo];
            userProfile.CompaniesToReview = stepContext.Result as List<string> ?? new List<string>();

            // Thank them for participating.
            await stepContext.Context.SendActivityAsync(
                MessageFactory.Text($"Thanks for participating, {((UserProfile)stepContext.Values[UserInfo]).Name}."),
                cancellationToken);

            // Exit the dialog, returning the collected user information.
            return await stepContext.EndDialogAsync(stepContext.Values[UserInfo], cancellationToken);
        }
    }
}

A véleményezés-kijelölés párbeszédpanel

A véleményezés-kiválasztás párbeszédpanel két lépésből áll:

  1. Kérje meg a felhasználót, hogy válasszon ki egy vállalatot, amely áttekintésre vagy done befejezésre van kijelölve.
    • Ha a párbeszédpanel bármilyen kezdeti információval indult el, az információ a vízeséslépés-környezet Beállítás tulajdonságán keresztül érhető el. A véleményezés-kiválasztás párbeszédpanel újraindulhat, és ezzel lehetővé teszi a felhasználó számára, hogy több vállalatot válasszon a véleményezéshez.
    • Ha a felhasználó már kiválasztott egy áttekintendő vállalatot, a rendszer eltávolítja a vállalatot a rendelkezésre álló lehetőségek közül.
    • A rendszer hozzáad egy done választási lehetőséget, amely lehetővé teszi a felhasználó számára, hogy korán kilépjen a hurokból.
  2. Szükség szerint ismételje meg ezt a párbeszédpanelt vagy kilépést.
    • Ha a felhasználó egy vállalatot választott felülvizsgálatra, vegye fel a listára.
    • Ha a felhasználó két vállalatot választott, vagy a kilépés mellett döntött, zárja be a párbeszédpanelt, és adja vissza az összegyűjtött listát.
    • Ellenkező esetben indítsa újra a párbeszédpanelt, és inicializálja azt a lista tartalmával.

Párbeszédpanelek\ReviewSelectionDialog.cs

private async Task<DialogTurnResult> SelectionStepAsync(
    WaterfallStepContext stepContext,
    CancellationToken cancellationToken)
{
    // Continue using the same selection list, if any, from the previous iteration of this dialog.
    var list = stepContext.Options as List<string> ?? new List<string>();
    stepContext.Values[CompaniesSelected] = list;

    // Create a prompt message.
    string message;
    if (list.Count is 0)
    {
        message = $"Please choose a company to review, or `{DoneOption}` to finish.";
    }
    else
    {
        message = $"You have selected **{list[0]}**. You can review an additional company, " +
            $"or choose `{DoneOption}` to finish.";
    }

    // Create the list of options to choose from.
    var options = _companyOptions.ToList();
    options.Add(DoneOption);
    if (list.Count > 0)
    {
        options.Remove(list[0]);
    }

    var promptOptions = new PromptOptions
    {
        Prompt = MessageFactory.Text(message),
        RetryPrompt = MessageFactory.Text("Please choose an option from the list."),
        Choices = ChoiceFactory.ToChoices(options),
    };

    // Prompt the user for a choice.
    return await stepContext.PromptAsync(nameof(ChoicePrompt), promptOptions, cancellationToken);
}

private async Task<DialogTurnResult> LoopStepAsync(
    WaterfallStepContext stepContext,
    CancellationToken cancellationToken)
{
    // Retrieve their selection list, the choice they made, and whether they chose to finish.
    var list = stepContext.Values[CompaniesSelected] as List<string>;
    var choice = (FoundChoice)stepContext.Result;
    var done = choice.Value == DoneOption;

    if (!done)
    {
        // If they chose a company, add it to the list.
        list.Add(choice.Value);
    }

    if (done || list.Count >= 2)
    {
        // If they're done, exit and return their list.
        return await stepContext.EndDialogAsync(list, cancellationToken);
    }
    else
    {
        // Otherwise, repeat this dialog, passing in the list from this iteration.
        return await stepContext.ReplaceDialogAsync(InitialDialogId, list, cancellationToken);
    }
}

A párbeszédpanelek futtatása

A párbeszédpanel-robotosztály kibővíti a tevékenységkezelőt, és tartalmazza a párbeszédpanelek futtatásának logikáját. A párbeszédpanel és az üdvözlőrobot-osztály kibővíti a párbeszédpanel-robotot, hogy egy felhasználót is üdvözöljön, amikor csatlakoznak a beszélgetéshez.

A robot fordulási kezelője megismétli a három párbeszédpanel által meghatározott beszélgetési folyamatot. Amikor üzenetet kap a felhasználótól:

  1. A fő párbeszédpanelt futtatja.
    • Ha a párbeszédpanel-verem üres, ez elindítja a fő párbeszédpanelt.
    • Ellenkező esetben a párbeszédpanelek még a folyamat közepén vannak, és ez folytatja az aktív párbeszédpanelt.
  2. Menti az állapotot, így a felhasználó, a beszélgetés és a párbeszédpanel állapotának minden frissítése megmarad.

Robotok\DialogBot.cs

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
{
    await base.OnTurnAsync(turnContext, cancellationToken);

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

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Message Activity.");

    // Run the Dialog with the new message Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

Szolgáltatások regisztrálása a robothoz

Szükség szerint hozzon létre és regisztráljon szolgáltatásokat:

  • A robot alapvető szolgáltatásai: egy adapter és a robot implementálása.
  • Az állapot kezelésére szolgáló szolgáltatások: tárolás, felhasználói állapot és beszélgetési állapot.
  • A robot által használt gyökér párbeszédpanel.

Startup.cs

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient().AddControllers().AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.MaxDepth = HttpHelper.BotMessageSerializerSettings.MaxDepth;
    });

    // Create the Bot Framework Authentication to be used with the Bot Adapter.
    services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

    // Create the Bot Adapter with error handling enabled.
    services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

    // Create the storage we'll be using for User and Conversation state. (Memory is great for testing purposes.)
    services.AddSingleton<IStorage, MemoryStorage>();

    // Create the User state. (Used in this bot's Dialog implementation.)
    services.AddSingleton<UserState>();

Feljegyzés

A memóriatároló csak tesztelési célokra használható, és nem éles használatra szolgál. Mindenképpen használjon állandó típusú tárolót egy éles robothoz.

A robot tesztelése

  1. Ha még nem tette meg, telepítse a Bot Framework Emulatort.

  2. Futtassa a mintát helyileg a számítógépen.

  3. Indítsa el az Emulátort, csatlakozzon a robothoz, és küldjön üzeneteket az alábbiak szerint.

    Példaátirat az összetett párbeszédpanel-robottal folytatott beszélgetésből.

További erőforrások

A párbeszédpanelek implementálásával kapcsolatos bevezetésért tekintse meg a szekvenciális beszélgetési folyamat implementálását, amely egyetlen vízesés párbeszédpanelt és néhány kérdést tesz fel a felhasználónak.

A Párbeszédpanelek kódtár a kérések alapvető érvényesítését tartalmazza. Egyéni érvényesítést is hozzáadhat. További információ: Felhasználói bevitel összegyűjtése párbeszédpanel használatával.

Ha egyszerűsíteni szeretné a párbeszédpanel-kódot, és több robotot szeretne használni, a párbeszédpanelek egyes részeit külön osztályként határozhatja meg. További információkért tekintse meg az újrafelhasználási párbeszédpaneleket.

Következő lépések

Párbeszédpanelek újrafelhasználása