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

Készség felhasználása párbeszédpanel használatával

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Ez a cikk bemutatja, hogyan használhat készség-párbeszédpanelt egy készségfelhasználón belül. A képesség párbeszédpanel a szülőrobottól a képességrobotig közzéteszi a tevékenységeket, és visszaadja a képességre adott válaszokat a felhasználónak. A fogyasztó által elért képességrobot képes kezelni az üzenet- és eseménytevékenységeket is. A készségjegyzék mintájáért és a képesség megvalósításával kapcsolatos információkért tekintse meg, hogyan használhat párbeszédpaneleket egy adott képességen belül.

A készségrobot párbeszédpaneleken kívüli használatáról további információt a képességfelhasználók implementálásával kapcsolatban talál.

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.

Új robotépítéshez fontolja meg a Power Virtual Agents használatát, és olvassa el a megfelelő csevegőrobot-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

A skillDialog minta két robot projektjeit tartalmazza:

  • A párbeszédpanel gyökérrobotja, amely egy készség-párbeszédpanel-osztály használatával használ fel egy készséget.
  • A párbeszédpanel készségrobotja, amely egy párbeszédpanelt használ a készségfelhasználóktól érkező tevékenységek kezeléséhez.

Ez a cikk azt ismerteti, hogyan használhatja a képesség párbeszédpanel-osztályát egy gyökérrobotban a képesség kezeléséhez, az üzenet- és eseménytevékenységek küldéséhez és a képesség megszakításához.

A készségfelhasználók létrehozásának egyéb aspektusairól további információt a képességfelhasználók implementálásával kapcsolatban talál.

A párbeszédpanel-képességrobottal kapcsolatos információkért tekintse meg, hogyan használhat párbeszédpaneleket egy adott képességen belül.

Források

Az üzembe helyezett robotok esetében a robotok között történő hitelesítéshez minden résztvevő robotnak érvényes identitással kell rendelkeznie. A Bot Framework Emulator segítségével azonban identitásadatok nélkül helyileg tesztelheti a készségeket és a készségfelhasználókat.

Alkalmazáskonfiguráció

  1. Szükség esetén adja hozzá a gyökérrobot identitásadatait a konfigurációs fájlhoz.
  2. Adja hozzá a képességgazda végpontját (a szolgáltatás vagy visszahívási URL-címet), amelyre a készségeknek válaszolniuk kell a képességfelhasználónak.
  3. Adjon hozzá egy bejegyzést minden olyan képességhez, amelyet a készségfelhasználó használni fog. Minden bejegyzés a következőket tartalmazza:
    • Egy azonosító, amellyel a készségfelhasználó azonosítja az egyes képességeket.
    • A képességrobot alkalmazásának vagy ügyfélazonosítójának megadása kötelező.
    • A képesség üzenetkezelési végpontja.

Feljegyzés

Ha a képesség- vagy képességfelhasználó identitást határoz meg, mindkettőnek meg kell lennie.

DialogRootBot\appsettings.json

Szükség esetén adja hozzá a gyökérrobot identitásadatait, és adja hozzá az echo skill robot alkalmazás- vagy ügyfélazonosítóját a BotFrameworkSkills tömbhöz.

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

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

Párbeszédpanel-logika

A robot fő párbeszédpanelje egy készség párbeszédpanelt tartalmaz minden olyan képességhez, amit a robot használ. A készség párbeszédpanel a készséget a különböző képességekkel kapcsolatos objektumokon keresztül kezeli, például a képességügyfélen és a készség-beszélgetési azonosító gyári objektumain keresztül. A fő párbeszédpanel azt is bemutatja, hogyan lehet megszakítani a készséget (a képesség párbeszédpanelen keresztül) a felhasználói bemenet alapján.

A robot által használt képesség számos különböző funkciót támogat. Lefoglalhat egy repülőt, vagy lekérheti a város időjárását. Ezenkívül, ha a rendszer ezen környezeteken kívül kap egy üzenetet, és egy LUIS-felismerő van konfigurálva, megpróbálja értelmezni a felhasználó szándékát.

Feljegyzés

A Language Understanding (LUIS) 2025. október 1-jén megszűnik. 2023. április 1-től nem hozhat létre új LUIS-erőforrásokat. Az Azure AI Language részeként már elérhető a nyelvértés újabb verziója.

Az Azure AI Language egyik funkciója, a beszélgetési nyelv megértése (CLU) a LUIS frissített verziója. További információ a Bot Framework SDK nyelvfelismerési támogatásáról: Természetes nyelvfelismerés.

A képességjegyzék (C#, JavaScript, Java, Python) a képesség által végrehajtható műveleteket, a bemeneti és kimeneti paramétereket, valamint a képesség végpontjait ismerteti. A képesség képes kezelni a "BookFlight" vagy a "GetWeather" eseményt. Üzeneteket is képes kezelni.

A fő párbeszédpanel a következő kódot tartalmazza:

A fő párbeszédpanel az összetevő párbeszédpanel-osztályától öröklődik. Az összetevők párbeszédpaneljeiről további információt a párbeszédpanelek összetettségének kezelésével kapcsolatban talál.

A fő párbeszédpanel inicializálása

A fő párbeszédpanel párbeszédpaneleket tartalmaz (a beszélgetési folyamat képességen kívüli kezelésére) és egy készség párbeszédpanelt (a készségek kezelésére). A vízesés a következő lépéseket tartalmazza, a következő néhány szakaszban részletesebben bemutatva.

  1. Kérje meg a felhasználót, hogy válassza ki a használni kívánt képességet. (A gyökérrobot egyetlen képességet használ fel.)
  2. Kérje meg a felhasználót, hogy válassza ki az adott képességhez használni kívánt műveletet. (A képességrobot három műveletet határoz meg.)
  3. Indítsa el a kiválasztott képességet egy kezdeti tevékenységgel a választott művelet alapján.
  4. Ha a képesség befejeződött, jelenítse meg az eredményeket, ha vannak ilyenek. Ezután indítsa újra a vízesést.

DialogRootBot\Dialogs\MainDialog.cs

Az MainDialog osztály a következőből ComponentDialogszármazik: . A beszélgetési állapot mellett a párbeszédpanelnek szüksége van a gyökérrobot identitására, valamint a skill conversation ID factoryra, a skill HTTP-ügyfélre és a képességkonfigurációs objektumokra.

A párbeszédpanel-konstruktor ellenőrzi a bemeneti paramétereket, készség-párbeszédpaneleket ad hozzá, parancssori és vízesés párbeszédpaneleket ad hozzá a beszélgetési folyamat képességen kívüli kezeléséhez, és létrehoz egy tulajdonság-kiegészítőt az aktív készség nyomon követéséhez, ha van ilyen.

A konstruktor egy segédmetódust hív AddSkillDialogsmeg, hogy hozzon létre egy-egy SkillDialog olyan képességet, amely a konfigurációs fájlban található, a konfigurációs fájlból egy SkillsConfiguration objektumba olvasva.

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

Képesség kiválasztása

Az első lépésben a fő párbeszédpanel megkérdezi a felhasználót, hogy melyik készséget szeretné meghívni, és a "SkillPrompt" választási kérdés használatával kapja meg a választ. (Ez a robot csak egy készséget határoz meg.)

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

Készségművelet kiválasztása

A következő lépésben a fő párbeszédpanel:

  1. A felhasználó által kiválasztott képesség adatainak mentése.
  2. Kéri a felhasználót, hogy melyik készségműveletet szeretné használni, és a "SkillActionPrompt" választási kérdés használatával kapja meg a választ.
    • Segédmetódussal lekéri a választható műveletek listáját.
    • A parancssorhoz társított parancssori érvényesítő alapértelmezés szerint üzenetet küld a képességnek, ha a felhasználó bemenete nem egyezik az egyik lehetőséggel.

A robotban szereplő lehetőségek segítenek tesztelni az ehhez a képességhez definiált műveleteket. Jellemzőbb, hogy elolvassa a képességek jegyzékéből származó beállításokat, és a lista alapján bemutatja a beállításokat a felhasználónak.

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

Képesség indítása

A következő lépésben a fő párbeszédpanel:

  1. Beolvassa a felhasználó által kiválasztott képesség- és képességtevékenységre vonatkozó információkat.
  2. Segédmetódussal hozza létre azt a tevékenységet, amelyet először elküld a képességnek.
  3. Létrehozza azokat a párbeszédpanel-beállításokat, amelyekkel elindíthatja a készség párbeszédpanelt. Ebbe beletartozik a küldendő kezdeti tevékenység is.
  4. A képesség meghívása előtt menti az állapotot. (Erre azért van szükség, mert előfordulhat, hogy a képesség válasza a képességfelhasználó egy másik példányára érkezik.)
  5. Elindítja a készség párbeszédpanelt, és adja meg a meghívni kívánt képességazonosítót, valamint azokat a beállításokat, amelyekkel meghívhatja.

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

A képesség eredményének összegzése

Az utolsó lépésben a fő párbeszédpanel:

  1. Ha a képesség visszaadott egy értéket, jelenítse meg az eredményt a felhasználónak.
  2. Törli az aktív készséget a párbeszédpanel állapotából.
  3. Eltávolítja az aktív képesség tulajdonságot a beszélgetési állapotból.
  4. Újraindul (a fő párbeszédpanel).

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

A képesség megszakításának engedélyezése a felhasználó számára

A fő párbeszédpanel felülbírálja a bekapcsolva párbeszédpanel alapértelmezett viselkedését, hogy a felhasználó megszakíthassa az aktuális készséget, ha van ilyen. A metóduson belül:

  • Ha van aktív képesség, és a felhasználó "megszakítás" üzenetet küld, törölje az összes párbeszédpanelt, és a fő párbeszédpanelt az elejétől kezdve indítsa újra.
  • Ezután hívja meg az on continue dialog metódus alap implementációját az aktuális sor feldolgozásának folytatásához.

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

Tevékenységkezelő logika

Mivel az egyes fordulók készséglogikáját egy fő párbeszédpanel kezeli, a tevékenységkezelő ugyanúgy néz ki, mint más párbeszédpanel-minták esetében.

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

Szolgáltatásregisztráció

A készségpanel használatához szükséges szolgáltatások megegyeznek a készségfelhasználók általános szolgáltatásaival. Megtudhatja, hogyan valósíthat meg készségfelhasználót a szükséges szolgáltatások megvitatásához.

A gyökérrobot tesztelése

Tesztelheti a készségfelhasználót az Emulátorban, mintha normál robot lenne; azonban egyszerre kell futtatnia a készség- és készségfelhasználó robotokat is. Megtudhatja, hogyan használhat párbeszédpaneleket egy képességen belül a képesség konfigurálásáról.

Töltse le és telepítse a legújabb Bot Framework Emulatort.

  1. Futtassa a párbeszédpanel-képességrobotot és a párbeszédpanel gyökérrobotját helyileg a számítógépen. Ha útmutatásra van szüksége, tekintse meg a C#, JavaScript, Java, Python mintául README szolgáló példákat.
  2. Az Emulator használatával tesztelje a robotot.
    • Amikor először csatlakozik a beszélgetéshez, a robot üdvözlő üzenetet jelenít meg, és megkérdezi, hogy milyen készséget szeretne meghívni. A minta készségrobotja csak egy képességgel rendelkezik.
    • Válassza a DialogSkillBot lehetőséget.
  3. Ezután a robot arra kéri, hogy válasszon egy műveletet a képességhez. Válassza a "BookFlight" lehetőséget.
    1. Válaszoljon a kérdésekre.
    2. A képesség befejeződik, és a gyökérrobot megjeleníti a foglalás részleteit, mielőtt újra rákérdez a meghívni kívánt képességre.
  4. Válassza ismét a DialogSkillBot és a "BookFlight" lehetőséget.
    1. Válaszoljon az első kérdésre, majd a szakítás megszakításához írja be a "megszakítást".
    2. A gyökérrobot megszakítja a képességet, és kéri a meghívni kívánt készséget.

További információ a hibakeresésről

Mivel a készségek és a készségfelhasználók közötti forgalom hitelesítése megtörtént, az ilyen robotok hibakereséséhez további lépések is szükségesek.

Ellenkező esetben ugyanúgy hibakeresést végezhet egy képességfelhasználón vagy képességen, mint más robotok. További információ: Robot hibakeresése és hibakeresés a Bot Framework Emulator használatával.

További információk

Megtudhatja, hogyan valósíthat meg készségfelhasználót a képességfelhasználók általános implementálásához.