Dela via

Använda en dialogruta för att använda en färdighet

  • Artikel

GÄLLER FÖR: SDK v4

Den här artikeln visar hur du använder en kunskapsdialogruta inom en kunskapskonsument. Kunskapsdialogrutan publicerar aktiviteter från den överordnade roboten till kunskapsroboten och returnerar kunskapssvaren till användaren. Kunskapsroboten som nås av den här konsumenten kan hantera både meddelande- och händelseaktiviteter. Ett exempel på ett kunskapsmanifest och information om hur du implementerar färdigheten finns i hur du använder dialogrutor inom en färdighet.

Information om hur du använder en kunskapsrobot utanför dialogrutor finns i hur du implementerar en kunskapskonsument.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot kan du använda Microsoft Copilot Studio och läsa om hur du väljer rätt copilot-lösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

Om det här exemplet

Exemplet skills skillDialog innehåller projekt för två robotar:

  • Dialogrutans rotrobot, som använder en kunskapsdialogruta för att använda en färdighet.
  • Dialogrutans kunskapsrobot, som använder en dialogruta för att hantera aktiviteter som kommer från kunskapskonsumenter.

Den här artikeln fokuserar på hur du använder en kunskapsdialogruta i en rotrobot för att hantera kunskapen, skicka meddelande- och händelseaktiviteter och avbryta färdigheten.

Information om andra aspekter av att skapa en kunskapskonsument finns i hur du implementerar en kunskapskonsument.

Information om dialogrutans kunskapsrobot finns i hur du använder dialogrutor inom en färdighet.

Resurser

För distribuerade robotar kräver robot-till-robot-autentisering att varje deltagande robot har en giltig identitet. Du kan dock testa kunskaper och kunskapskonsumenter lokalt med Bot Framework-emulatorn utan identitetsinformation.

Tillämpningskonfiguration

  1. Du kan också lägga till rotrobotens identitetsinformation i konfigurationsfilen.
  2. Lägg till den färdighetsvärdslutpunkt (tjänsten eller motringnings-URL:en) som färdigheterna ska svara kunskapskonsumenten på.
  3. Lägg till en post för varje färdighet som kunskapskonsumenten kommer att använda. Varje post innehåller:
    • Ett ID som kunskapskonsumenten använder för att identifiera varje färdighet.
    • Du kan också använda kunskapsrobotens app eller klient-ID.
    • Kunskapens slutpunkt för meddelanden.

Kommentar

Om antingen kunskaps- eller färdighetskonsumenten anger en identitet måste båda två.

DialogRootBot\appsettings.json

Du kan också lägga till rotrobotens identitetsinformation och lägga till appen eller klient-ID:t för ekofärdighetsroboten i matrisen BotFrameworkSkills .

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

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

Dialoglogik

Robotens huvuddialogruta innehåller en kunskapsdialogruta för varje färdighet som roboten använder. Kunskapsdialogrutan hanterar färdigheten genom de olika kunskapsrelaterade objekten åt dig, till exempel kunskapsklienten och kunskapskonversationens ID-fabriksobjekt. Huvuddialogrutan visar också hur du avbryter färdigheten (via kunskapsdialogrutan) baserat på användarindata.

Den kunskap som roboten använder har stöd för ett par olika funktioner. Det kan boka ett flyg eller få vädret för en stad. Om det dessutom tar emot ett meddelande utanför någon av dessa kontexter och en LUIS-identifierare har konfigurerats, försöker den tolka användarens avsikt.

Kommentar

Language Understanding (LUIS) dras tillbaka den 1 oktober 2025. Från och med den 1 april 2023 kan du inte skapa nya LUIS-resurser. En nyare version av språktolkning är nu tillgänglig som en del av Azure AI Language.

Conversational Language Understanding (CLU), en funktion i Azure AI Language, är den uppdaterade versionen av LUIS. Mer information om stöd för språktolkning i Bot Framework SDK finns i Förstå naturligt språk.

Kunskapsmanifestet (C#, JavaScript, Java, Python) beskriver de åtgärder som färdigheten kan utföra, dess indata- och utdataparametrar och färdighetens slutpunkter. Observera att färdigheten kan hantera en "BookFlight" eller "GetWeather"-händelse. Den kan också hantera meddelanden.

Huvuddialogrutan innehåller kod för att:

Huvuddialogrutan ärver från komponentdialogrutans klass. Mer information om komponentdialogrutor finns i hantera dialogkomplexitet.

Initiera huvuddialogrutan

Huvuddialogrutan innehåller dialogrutor (för att hantera konversationsflöden utanför kunskapen) och en kunskapsdialogruta (för att hantera färdigheterna). Vattenfallet innehåller följande steg, som beskrivs mer detaljerat i de kommande avsnitten.

  1. Uppmana användaren att välja den färdighet som ska användas. (Rotroboten använder en färdighet.)
  2. Uppmana användaren att välja den åtgärd som ska användas för den färdigheten. (Kunskapsroboten definierar tre åtgärder.)
  3. Starta den valda färdigheten med en inledande aktivitet baserat på den valda åtgärden.
  4. När kunskapen har slutförts visar du resultatet, om det finns några. Starta sedan om vattenfallet.

DialogRootBot\Dialogs\MainDialog.cs

Klassen MainDialog härleds från ComponentDialog. Förutom konversationstillståndet behöver dialogrutan rotrobotens identitet och referenser till kunskapskonversationens ID-fabrik, kunskaps-HTTP-klienten och konfigurationsobjekten för färdigheter.

Dialogkonstruktorn kontrollerar sina indataparametrar, lägger till kunskapsdialogrutor, lägger till dialogrutor för frågor och vattenfall för att hantera konversationsflöden utanför kunskapen och skapar en egenskapsåtkomst för att spåra den aktiva kompetensen, om någon.

Konstruktorn anropar AddSkillDialogs, en hjälpmetod, för att skapa en SkillDialog för varje färdighet som ingår i konfigurationsfilen, som läst från konfigurationsfilen till ett SkillsConfiguration objekt.

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

Välj en färdighet

I det första steget uppmanar huvuddialogrutan användaren för vilken färdighet de vill anropa och använder "SkillPrompt"-alternativprompten för att få svaret. (Den här roboten definierar bara en färdighet.)

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älj en färdighetsåtgärd

I nästa steg är huvuddialogrutan:

  1. Sparar information om den kompetens som användaren har valt.
  2. Uppmanar användaren för vilken färdighetsåtgärd de vill använda och använder "SkillActionPrompt"-valprompten för att få svaret.
    • Den använder en hjälpmetod för att hämta en lista över åtgärder att välja mellan.
    • Frågeverifieraren som är associerad med den här prompten skickar som standard ett meddelande om användarens indata inte matchar något av alternativen.

De val som ingår i den här roboten hjälper dig att testa de åtgärder som definierats för den här färdigheten. Mer normalt skulle du läsa alternativen från färdighetens manifest och presentera alternativ för användaren baserat på den listan.

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

Starta en färdighet

I nästa steg är huvuddialogrutan:

  1. Hämtar information om den kompetens- och färdighetsaktivitet som användaren har valt.
  2. Använder en hjälpmetod för att skapa aktiviteten som ska skickas till färdigheten.
  3. Skapar de dialogalternativ som du vill starta kunskapsdialogrutan med. Detta inkluderar den första aktiviteten som ska skickas.
  4. Sparar tillstånd innan du anropar färdigheten. (Detta är nödvändigt eftersom kunskapssvaret kan komma till en annan instans av kunskapskonsumenten.)
  5. Börjar kunskapsdialogrutan och skickar in kunskaps-ID:t att anropa och de alternativ som du kan anropa den med.

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

Sammanfatta kunskapsresultatet

I det sista steget, huvuddialogrutan:

  1. Om färdigheten returnerade ett värde visar du resultatet för användaren.
  2. Rensar den aktiva färdigheten från dialogtillståndet.
  3. Tar bort egenskapen aktiv kompetens från konversationstillståndet.
  4. Startar om sig själv (huvuddialogrutan).

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

Tillåt att användaren avbryter färdigheten

Huvuddialogrutan åsidosätter standardbeteendet för on continue-dialogmetoden så att användaren kan avbryta den aktuella kompetensen, om någon. I -metoden:

  • Om det finns en aktiv färdighet och användaren skickar ett "avbryt"-meddelande avbryter du alla dialogrutor och köar huvuddialogrutan för att starta om från början.
  • Anropa sedan basimplementeringen av on continue-dialogmetoden för att fortsätta bearbeta den aktuella svängen.

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

Logik för aktivitetshanterare

Eftersom kunskapslogik för varje tur hanteras av en huvuddialogruta ser aktivitetshanteraren ungefär ut som för andra dialogexempel.

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

Tjänstregistrering

De tjänster som behövs för att använda en kunskapsdialogruta är desamma som de som behövs för en kunskapskonsument i allmänhet. Se hur du implementerar en kunskapskonsument för en diskussion om de tjänster som krävs.

Testa rotroboten

Du kan testa kunskapskonsumenten i emulatorn som om det vore en vanlig robot. Du måste dock köra både kunskaps- och kunskapsrobotarna på samma gång. Se hur du använder dialogrutor inom en färdighet för information om hur du konfigurerar kunskapen.

Ladda ned och installera den senaste Bot Framework-emulatorn.

  1. Kör dialogrutans kunskapsrobot och dialogrotrobot lokalt på datorn. Om du behöver instruktioner kan du läsa exempel README på C#, JavaScript, Java, Python.
  2. Använd emulatorn för att testa roboten.
    • När du först ansluter till konversationen visar roboten ett välkomstmeddelande och frågar dig vilken färdighet du vill ringa. Kunskapsroboten för det här exemplet har bara en färdighet.
    • Välj DialogSkillBot.
  3. Sedan ber roboten dig att välja en åtgärd för färdigheten. Välj "BookFlight".
    1. Svara på anvisningarna.
    2. Kunskapen slutförs och rotroboten visar bokningsinformationen innan du frågar igen om den färdighet du vill anropa.
  4. Välj DialogSkillBot igen och "BookFlight".
    1. Svara på den första uppmaningen och ange sedan "abort" för att avbryta färdigheten.
    2. Rotroboten avbryter kunskapen och frågar efter den färdighet som du vill anropa.

Mer om felsökning

Eftersom trafiken mellan kompetens och kunskapskonsumenter autentiseras finns det extra steg när du felsöker sådana robotar.

Annars kan du felsöka en kunskapskonsument eller färdighet ungefär som du felsöker andra robotar. Mer information finns i Felsöka en robot och felsöka med Bot Framework-emulatorn.

Ytterligare information

Se hur du implementerar en kunskapskonsument för att implementera en kunskapskonsument i allmänhet.