Use a dialog to consume a skill

APPLIES TO: SDK v4

This article demonstrates how to use a skill dialog within a skill consumer. The skill dialog posts activities from the parent bot to the skill bot and returns the skill responses to the user. The skill bot accessed by this consumer can handle both message and event activities. For a sample skill manifest and information about implementing the skill, see how to use dialogs within a skill.

For information about using a skill bot outside of dialogs, see how to implement a skill consumer.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Microsoft Copilot Studio and read about choosing the right copilot solution.

For more information, see The future of bot building.

Prerequisites

• Knowledge of bot basics, how skills bots work, and how to implement a skill consumer.
• Optionally, an Azure subscription. If you don't have one, create a free account before you begin.
• A copy of the skills skillDialog sample in C#, JavaScript, Java or Python.

About this sample

The skills skillDialog sample includes projects for two bots:

• The dialog root bot, which uses a skill dialog class to consume a skill.
• The dialog skill bot, which uses a dialog to handle activities coming from skill consumers.

This article focuses on how to use a skill dialog class in a root bot to manage the skill, to send message and event activities and to cancel the skill.

For information about other aspects of creating a skill consumer, see how to implement a skill consumer.

C#

JavaScript

Java

Python

For information about the dialog skill bot, see how to use dialogs within a skill.

Resources

For deployed bots, bot-to-bot authentication requires that each participating bot has a valid identity. However, you can test skills and skill consumers locally with the Bot Framework Emulator without identity information.

Application configuration

1. Optionally, add the root bot's identity information to the config file.
2. Add the skill host endpoint (the service or callback URL) to which the skills should reply to the skill consumer.
3. Add an entry for each skill the skill consumer will use. Each entry includes:
   • An ID the skill consumer will use to identify each skill.
   • Optionally, the skill bot's app or client ID.
   • The skill's messaging endpoint.

Note

If either the skill or skill consumer specifies an identity, both must.

C#

DialogRootBot\appsettings.json

Optionally, add the root bot's identity information and add the app or client ID for the echo skill bot to the BotFrameworkSkills array.

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

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

JavaScript

dialogRootBot/.env

Optionally, add the root bot's identity information and add the app or client ID for the echo skill bot.

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
SkillHostEndpoint=http://localhost:3978/api/skills/

SkillId=DialogSkillBot
SkillAppId=
SkillEndpoint=http://localhost:39783/api/messages

Java

DialogRootBot\application.properties

Optionally, add the root bot's app ID and password and add the app ID for the echo skill bot to the BotFrameworkSkills array.

MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
SkillhostEndpoint=http://localhost:3978/api/skills/
#replicate these three entries, incrementing the index value [0] for each successive Skill that is added.
BotFrameworkSkills[0].Id=DialogSkillBot
BotFrameworkSkills[0].AppId=
BotFrameworkSkills[0].SkillEndpoint=http://localhost:39783/api/messages

Python

dialog-root-bot/config.py

Optionally, add the root bot's app ID and password and add the app ID for the echo skill bot.

APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
SKILL_HOST_ENDPOINT = "http://localhost:3978/api/skills"
SKILLS = [
    {
        "id": "DialogSkillBot",
        "app_id": "",
        "skill_endpoint": "http://localhost:39783/api/messages",
    },
]

Dialog logic

The bot's main dialog includes a skill dialog for each skill this bot consumes. The skill dialog manages the skill through the various skill-related objects for you, such as the skill client and the skill conversation ID factory objects. The main dialog also demonstrates how to cancel the skill (through the skill dialog) based on user input.

The skill this bot uses supports a couple different features. It can book a flight or get the weather for a city. In addition, if it receives a message outside either of these contexts and a LUIS recognizer is configured, it attempts to interpret the user's intent.

Note

Language Understanding (LUIS) will be retired on 1 October 2025. Beginning 1 April 2023, you won't be able to create new LUIS resources. A newer version of language understanding is now available as part of Azure AI Language.

Conversational language understanding (CLU), a feature of Azure AI Language, is the updated version of LUIS. For more information about language understanding support in the Bot Framework SDK, see Natural language understanding.

The skill manifest (C#, JavaScript, Java, Python) describes the actions the skill can perform, its input and output parameters, and the skill's endpoints. Of note, the skill can handle a "BookFlight" or "GetWeather" event. It can also handle messages.

The main dialog includes code to:

• Initialize the main dialog
• Select a skill
• Select a skill action
• Start a skill
• Summarize the skill result
• Allow the user to cancel the skill

The main dialog inherits from the component dialog class. For more about component dialogs, see how to manage dialog complexity.

Initialize the main dialog

The main dialog includes dialogs (for managing conversation flow outside the skill) and a skill dialog (for managing the skills). The waterfall includes the following steps, described in more detail in the next few sections.

1. Prompt the user to select the skill to use. (The root bot consumes one skill.)
2. Prompt the user to select the action to use for that skill. (The skill bot defines three actions.)
3. Start the chosen skill with an initial activity based on the chosen action.
4. Once the skill completes, display the results, if any. Then, restart the waterfall.

C#

DialogRootBot\Dialogs\MainDialog.cs

The MainDialog class derives from ComponentDialog. In addition to conversation state, the dialog needs the root bot's identity and references to the skill conversation ID factory, the skill HTTP client, and the skills configuration objects.

The dialog constructor checks its input parameters, adds skill dialogs, adds prompt and waterfall dialogs for managing conversation flow outside the skill, and creates a property accessor for tracking the active skill, if any.

The constructor calls AddSkillDialogs, a helper method, to create a SkillDialog for each skill that is included in the configuration file, as read from the configuration file into a SkillsConfiguration object.

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

The MainDialog class derives from ComponentDialog. In addition to conversation state, the dialog needs the root bot's identity and references to the skill conversation ID factory, the skill HTTP client, and the skills configuration objects. The code retrieves the bot's identity from the user environment.

The dialog constructor checks its input parameters, adds skills dialogs, adds prompt and waterfall dialogs for managing conversation flow outside the skill, and creates a property accessor for tracking the active skill, if any.

The constructor calls addSkillDialogs, a helper method, to create a SkillDialog for each skill that is included in the configuration file, as read from the configuration file into a SkillsConfiguration object.

async addSkillDialogs(conversationState, conversationIdFactory, skillClient, skillsConfig, botId) {
    Object.keys(skillsConfig.skills).forEach((skillId) => {
        const skillInfo = skillsConfig.skills[skillId];

        const skillOptions = {
            botId: process.env.MicrosoftAppId,
            conversationIdFactory,
            conversationState,
            skill: skillInfo,
            skillHostEndpoint: process.env.SkillHostEndpoint,
            skillClient
        };

        // Add a SkillDialog for the selected skill.
        this.addDialog(new SkillDialog(skillOptions, skillInfo.id));
    });
}

Java

DialogRootBot\dialogs\MainDialog.java

The MainDialog class derives from ComponentDialog. In addition to conversation state, the dialog needs the root bot's app ID and references to the skill conversation ID factory, the skill HTTP client, and the skills configuration objects.

The dialog constructor checks its input parameters, adds skills dialogs, adds prompt and waterfall dialogs for managing conversation flow outside the skill, and creates a property accessor for tracking the active skill, if any.

The constructor calls addSkillDialogs, a helper method, to create a SkillDialog for each skill that is included in the configuration file, as read from the configuration file into a SkillsConfiguration object.

private void addSkillDialogs(
    ConversationState conversationState,
    SkillConversationIdFactoryBase conversationIdFactory,
    SkillHttpClient skillClient,
    SkillsConfiguration skillsConfig,
    String botId
) {
    for (BotFrameworkSkill skillInfo : _skillsConfig.getSkills().values()) {
        // Create the dialog options.
        SkillDialogOptions skillDialogOptions = new SkillDialogOptions();
        skillDialogOptions.setBotId(botId);
        skillDialogOptions.setConversationIdFactory(conversationIdFactory);
        skillDialogOptions.setSkillClient(skillClient);
        skillDialogOptions.setSkillHostEndpoint(skillsConfig.getSkillHostEndpoint());
        skillDialogOptions.setConversationState(conversationState);
        skillDialogOptions.setSkill(skillInfo);
        // Add a SkillDialog for the selected skill.
        addDialog(new SkillDialog(skillDialogOptions, skillInfo.getId()));
    }
}

Python

dialog-root-bot/dialogs/main_dialog.py

The MainDialog class derives from ComponentDialog. In addition to conversation state, the dialog needs the root bot's app ID and references to the skill conversation ID factory, the skill HTTP client, and the skills configuration objects.

The dialog constructor checks its input parameters, adds skills dialogs, adds prompt and waterfall dialogs for managing conversation flow outside the skill, and creates a property accessor for tracking the active skill, if any.

The constructor calls AddSkillDialogs, a helper method, to create a SkillDialog for each skill that is included in the configuration file, as read from the configuration file into a SkillConfiguration object.

def _add_skill_dialogs(
    self,
    conversation_state: ConversationState,
    conversation_id_factory: ConversationIdFactoryBase,
    skill_client: SkillHttpClient,
    skills_config: SkillConfiguration,
    bot_id: str,
):
    """
    Helper method that creates and adds SkillDialog instances for the configured skills.
    """

    for _, skill_info in skills_config.SKILLS.items():
        # Create the dialog options.
        skill_dialog_options = SkillDialogOptions(
            bot_id=bot_id,
            conversation_id_factory=conversation_id_factory,
            skill_client=skill_client,
            skill_host_endpoint=skills_config.SKILL_HOST_ENDPOINT,
            conversation_state=conversation_state,
            skill=skill_info,
        )

        # Add a SkillDialog for the selected skill.
        self.add_dialog(SkillDialog(skill_dialog_options, skill_info.id))

Select a skill

In its first step, the main dialog prompts the user for which skill they'd like to call, and uses the "SkillPrompt" choice prompt to get the answer. (This bot defines only one skill.)

C#

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

/**
 * Render a prompt to select the skill to call.
 */
async selectSkillStep(stepContext) {
    // Create the PromptOptions from the skill configuration which contains the list of configured skills.
    const messageText = stepContext.options && stepContext.options.text ? stepContext.options.text : 'What skill would you like to call?';
    const repromptMessageText = 'That was not a valid choice, please select a valid skill.';
    const options = {
        prompt: MessageFactory.text(messageText, messageText, InputHints.ExpectingInput),
        retryPrompt: MessageFactory.text(repromptMessageText, repromptMessageText, InputHints.ExpectingInput),
        choices: Object.keys(this.skillsConfig.skills)
    };

    // Prompt the user to select a skill.
    return await stepContext.prompt(SKILL_PROMPT, options);
}

Java

DialogRootBot\Dialogs\MainDialog.java

public CompletableFuture<DialogTurnResult> selectSkillStep(WaterfallStepContext stepContext) {
    String messageText = "What skill would you like to call?";
    // Create the PromptOptions from the skill configuration which contain the list
    // of configured skills.
    if (stepContext.getOptions() != null) {
        messageText = stepContext.getOptions().toString();
    }
    String repromptMessageText = "That was not a valid choice, please select a valid skill.";
    PromptOptions options = new PromptOptions();
    options.setPrompt(MessageFactory.text(messageText, messageText, InputHints.EXPECTING_INPUT));
    options
        .setRetryPrompt(MessageFactory.text(repromptMessageText, repromptMessageText, InputHints.EXPECTING_INPUT));

    List<Choice> choicesList = new ArrayList<Choice>();
    for (BotFrameworkSkill skill : _skillsConfig.getSkills().values()) {
        choicesList.add(new Choice(skill.getId()));
    }
    options.setChoices(choicesList);

    // Prompt the user to select a skill.
    return stepContext.prompt("SkillPrompt", options);
}

Python

dialog-root-bot/dialogs/main_dialog.py

async def _select_skill_action_step(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    """
    Render a prompt to select the action for the skill.
    """

    # Get the skill info based on the selected skill.
    selected_skill_id = step_context.result.value
    selected_skill = self._skills_config.SKILLS.get(selected_skill_id)

    # Remember the skill selected by the user.
    step_context.values[self._selected_skill_key] = selected_skill

    # Create the PromptOptions with the actions supported by the selected skill.
    message_text = (
        f"Select an action # to send to **{selected_skill.id}** or just type in a message "
        f"and it will be forwarded to the skill"
    )
    options = PromptOptions(
        prompt=MessageFactory.text(
            message_text, message_text, InputHints.expecting_input
        ),
        choices=self._get_skill_actions(selected_skill),
    )

    # Prompt the user to select a skill action.
    return await step_context.prompt("SkillActionPrompt", options)

Select a skill action

In the next step, the main dialog:

1. Saves information about the skill the user selected.
2. Prompts the user for which skill action they'd like to use, and uses the "SkillActionPrompt" choice prompt to get the answer.
   • It uses a helper method to get a list of actions to choose from.
   • The prompt validator associated with this prompt will default to sending the skill a message if the user's input doesn't match one of the choices.

The choices included in this bot help test the actions defined for this skill. More typically, you would read the options from the skill's manifest, and present options to the user based on that list.

C#

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

/**
 * Render a prompt to select the action for the skill.
 */
async selectSkillActionStep(stepContext) {
    // Get the skill info based on the selected skill.
    const selectedSkillId = stepContext.result.value;
    const selectedSkill = this.skillsConfig.skills[selectedSkillId];

    // Remember the skill selected by the user.
    stepContext.values[this.selectedSkillKey] = selectedSkill;

    // Create the PromptOptions with the actions supported by the selected skill.
    const messageText = `Select an action # to send to **${ selectedSkill.id }** or just type in a message and it will be forwarded to the skill`;
    const options = {
        prompt: MessageFactory.text(messageText, messageText, InputHints.ExpectingInput),
        choices: this.getSkillActions(selectedSkill)
    };

    // Prompt the user to select a skill action.
    return await stepContext.prompt(SKILL_ACTION_PROMPT, options);
}

/**
 * Helper method to create Choice elements for the actions supported by the skill.
 */
getSkillActions(skill) {
    // Note: The bot would probably render this by reading the skill manifest.
    // We are just using hardcoded skill actions here for simplicity.
    const choices = [];
    switch (skill.id) {
        case 'DialogSkillBot':
            choices.push({ value: SKILL_ACTION_BOOK_FLIGHT });
            choices.push({ value: SKILL_ACTION_BOOK_FLIGHT_WITH_INPUT_PARAMETERS });
            choices.push({ value: SKILL_ACTION_GET_WEATHER });
            break;
    }

    return choices;
}

/**
 * This validator defaults to Message if the user doesn't select an existing option.
 */
async skillActionPromptValidator(promptContext) {
    if (!promptContext.recognized.succeeded) {
        promptContext.recognized.value = { value: SKILL_ACTION_MESSAGE };
    }

    return true;
}

Java

DialogRootBot\Dialogs\MainDialog.java

public CompletableFuture<DialogTurnResult> selectSkillActionStep(WaterfallStepContext stepContext) {
    // Get the skill info super. on the selected skill.
    String selectedSkillId = ((FoundChoice) stepContext.getResult()).getValue();
    BotFrameworkSkill selectedSkill = _skillsConfig.getSkills()
        .values()
        .stream()
        .filter(x -> x.getId().equals(selectedSkillId))
        .findFirst()
        .get();

    // Remember the skill selected by the user.
    stepContext.getValues().put(_selectedSkillKey, selectedSkill);

    // Create the PromptOptions with the actions supported by the selected skill.
    String messageText = String.format(
        "Select an action # to send to **%n** or just type in a " + "message and it will be forwarded to the skill",
        selectedSkill.getId()
    );
    PromptOptions options = new PromptOptions();
    options.setPrompt(MessageFactory.text(messageText, messageText, InputHints.EXPECTING_INPUT));
    options.setChoices(getSkillActions(selectedSkill));

    // Prompt the user to select a skill action.
    return stepContext.prompt("SkillActionPrompt", options);
}

private List<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.

    List<Choice> choices = new ArrayList<Choice>();
    switch (skill.getId()) {
        case "DialogSkillBot":
            choices.add(new Choice(SkillActionBookFlight));
            choices.add(new Choice(SkillActionBookFlightWithInputParameters));
            choices.add(new Choice(SkillActionGetWeather));
            break;
    }

    return choices;
}

addDialog(new ChoicePrompt("SkillActionPrompt", (promptContext) -> {
    if (!promptContext.getRecognized().getSucceeded()) {
        // Assume the user wants to send a message if an item in the list is not
        // selected.
        FoundChoice foundChoice = new FoundChoice();
        foundChoice.setValue(SkillActionMessage);
        promptContext.getRecognized().setValue(foundChoice);
    }
    return CompletableFuture.completedFuture(true);
}, ""));

Python

dialog-root-bot/dialogs/main_dialog.py

async def _select_skill_action_step(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    """
    Render a prompt to select the action for the skill.
    """

    # Get the skill info based on the selected skill.
    selected_skill_id = step_context.result.value
    selected_skill = self._skills_config.SKILLS.get(selected_skill_id)

    # Remember the skill selected by the user.
    step_context.values[self._selected_skill_key] = selected_skill

    # Create the PromptOptions with the actions supported by the selected skill.
    message_text = (
        f"Select an action # to send to **{selected_skill.id}** or just type in a message "
        f"and it will be forwarded to the skill"
    )
    options = PromptOptions(
        prompt=MessageFactory.text(
            message_text, message_text, InputHints.expecting_input
        ),
        choices=self._get_skill_actions(selected_skill),
    )

    # Prompt the user to select a skill action.
    return await step_context.prompt("SkillActionPrompt", options)

def _get_skill_actions(self, skill: BotFrameworkSkill) -> List[Choice]:
    """
    Helper method to create Choice elements for the actions supported by the skill.
    """

    # Note: the bot would probably render this by reading the skill manifest.
    # We are just using hardcoded skill actions here for simplicity.

    choices = []
    if skill.id == "DialogSkillBot":
        choices.append(Choice(self._skill_action_book_flight))
        choices.append(Choice(self._skill_action_book_flight_with_input_parameters))
        choices.append(Choice(self._skill_action_get_weather))

    return choices

async def _skill_action_prompt_validator(
    self, prompt_context: PromptValidatorContext
) -> bool:
    """
    This validator defaults to Message if the user doesn't select an existing option.
    """

    if not prompt_context.recognized.succeeded:
        # Assume the user wants to send a message if an item in the list is not selected.
        prompt_context.recognized.value = FoundChoice(
            self._skill_action_message, None, None
        )

    return True

Start a skill

In the next step, the main dialog:

1. Retrieves information about the skill and skill activity the user selected.
2. Uses a helper method to create the activity to initially send to the skill.
3. Creates the dialog options with which to start the skill dialog. This includes the initial activity to send.
4. Saves state before calling the skill. (This is necessary, as the skill response might come to a different instance of the skill consumer.)
5. Begins the skill dialog, passing in the skill ID to call and the options with which to call it.

C#

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

/**
 * Starts the SkillDialog based on the user's selections.
 */
async callSkillActionStep(stepContext) {
    const selectedSkill = stepContext.values[this.selectedSkillKey];

    let skillActivity;
    switch (selectedSkill.id) {
        case 'DialogSkillBot':
            skillActivity = this.createDialogSkillBotActivity(stepContext.result.value, stepContext.context);
            break;
        // We can add other case statements here if we support more than one skill.
        default:
            throw new Error(`Unknown target skill id: ${ selectedSkill.id }`);
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    const skillDialogArgs = { activity: skillActivity };

    // Save active skill in state.
    await this.activeSkillProperty.set(stepContext.context, selectedSkill);

    // Start the skillDialog instance with the arguments.
    return await stepContext.beginDialog(selectedSkill.id, skillDialogArgs);
}

Java

DialogRootBot\Dialogs\MainDialog.java

public CompletableFuture<DialogTurnResult> callSkillActionStep(WaterfallStepContext stepContext) {
    BotFrameworkSkill selectedSkill = (BotFrameworkSkill) stepContext.getValues().get(_selectedSkillKey);

    Activity skillActivity;
    switch (selectedSkill.getId()) {
        case "DialogSkillBot":
            skillActivity = createDialogSkillBotActivity(
                ((FoundChoice) stepContext.getResult()).getValue(),
                stepContext.getContext()
            );
            break;

        // We can add other case statements here if we support more than one skill.
        default:
            throw new RuntimeException(String.format("Unknown target skill id: %s.", selectedSkill.getId()));
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    BeginSkillDialogOptions skillDialogArgs = new BeginSkillDialogOptions();
    skillDialogArgs.setActivity(skillActivity);

    // Save active skill in state.
    activeSkillProperty.set(stepContext.getContext(), selectedSkill);

    // Start the skillDialog instance with the arguments.
    return stepContext.beginDialog(selectedSkill.getId(), skillDialogArgs);
}

Python

dialog-root-bot/dialogs/main_dialog.py

async def _call_skill_action_step(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    """
    Starts the SkillDialog based on the user's selections.
    """

    selected_skill: BotFrameworkSkill = step_context.values[
        self._selected_skill_key
    ]

    if selected_skill.id == "DialogSkillBot":
        skill_activity = self._create_dialog_skill_bot_activity(
            step_context.result.value, step_context.context
        )
    else:
        raise Exception(f"Unknown target skill id: {selected_skill.id}.")

    # Create the BeginSkillDialogOptions and assign the activity to send.
    skill_dialog_args = BeginSkillDialogOptions(skill_activity)

    # Save active skill in state.
    await self._active_skill_property.set(step_context.context, selected_skill)

    # Start the skillDialog instance with the arguments.
    return await step_context.begin_dialog(selected_skill.id, skill_dialog_args)

Summarize the skill result

In the last step, the main dialog:

1. If the skill returned a value, display the result to the user.
2. Clears the active skill from dialog state.
3. Removes the active skill property from conversation state.
4. Restarts itself (the main dialog).

C#

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

/**
 * The SkillDialog has ended, render the results (if any) and restart MainDialog.
 */
async finalStep(stepContext) {
    const activeSkill = await this.activeSkillProperty.get(stepContext.context, () => null);

    // Check if the skill returned any results and display them.
    if (stepContext.result != null) {
        let message = `Skill "${ activeSkill.id }" invocation complete.`;
        message += `\nResult: ${ JSON.stringify(stepContext.result, null, 2) }`;
        await stepContext.context.sendActivity(message, message, InputHints.IgnoringInput);
    }

    // Clear the skill selected by the user.
    stepContext.values[this.selectedSkillKey] = null;

    // Clear active skill in state.
    await this.activeSkillProperty.delete(stepContext.context);

    // Restart the main dialog with a different message the second time around.
    return await stepContext.replaceDialog(this.initialDialogId, { text: `Done with "${ activeSkill.id }". \n\n What skill would you like to call?` });
}

Java

DialogRootBot\Dialogs\MainDialog.java

public CompletableFuture<DialogTurnResult> finalStep(WaterfallStepContext stepContext) {
    return activeSkillProperty.get(stepContext.getContext(), () -> null).thenCompose(activeSkill -> {
        if (stepContext.getResult() != null) {
            String jsonResult = "";
            try {
                jsonResult =
                    new JacksonAdapter().serialize(stepContext.getResult()).replace("{", "").replace("}", "");
            } catch (IOException e) {
                e.printStackTrace();
            }
            String message =
                String.format("Skill \"%s\" invocation complete. Result: %s", activeSkill.getId(), jsonResult);
            stepContext.getContext().sendActivity(MessageFactory.text(message, message, InputHints.IGNORING_INPUT));
        }

        // Clear the skill selected by the user.
        stepContext.getValues().put(_selectedSkillKey, null);

        // Clear active skill in state.
        activeSkillProperty.delete(stepContext.getContext());

        // Restart the main dialog with a different message the second time around.
        return stepContext.replaceDialog(
            getInitialDialogId(),
            String.format("Done with \"%s\". \n\n What skill would you like to call?", activeSkill.getId())
        );
    });
    // Check if the skill returned any results and display them.
}

Python

dialog-root-bot/dialogs/main_dialog.py

async def _final_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    """
    The SkillDialog has ended, render the results (if any) and restart MainDialog.
    """

    active_skill = await self._active_skill_property.get(step_context.context)

    if step_context.result:
        message = f"Skill {active_skill.id} invocation complete."
        message += f" Result: {step_context.result}"
        await step_context.context.send_activity(
            MessageFactory.text(message, input_hint=InputHints.ignoring_input)
        )

    # Clear the skill selected by the user.
    step_context.values[self._selected_skill_key] = None

    # Clear active skill in state.
    await self._active_skill_property.delete(step_context.context)

    # Restart the main dialog with a different message the second time around
    return await step_context.replace_dialog(
        self.initial_dialog_id,
        f'Done with "{active_skill.id}". \n\n What skill would you like to call?',
    )

Allow the user to cancel the skill

The main dialog overrides the default behavior of the on continue dialog method to allow the user to cancel the current skill, if any. Within the method:

• If there's an active skill and the user sends an "abort" message, cancel all dialogs and queue the main dialog to restart from the beginning.
• Then, call the base implementation of the on continue dialog method to continue processing the current turn.

C#

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

JavaScript

dialogRootBot/dialogs/mainDialog.js

async onContinueDialog(innerDc) {
    const activeSkill = await this.activeSkillProperty.get(innerDc.context, () => null);
    const activity = innerDc.context.activity;
    if (activeSkill != null && activity.type === ActivityTypes.Message && activity.text.toLowerCase() === 'abort') {
        // 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.cancelAllDialogs();
        return await innerDc.replaceDialog(this.initialDialogId, { text: 'Canceled! \n\n What skill would you like to call?' });
    }

    return await super.onContinueDialog(innerDc);
}

Java

DialogRootBot\Dialogs\MainDialog.java

// 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.
return innerDc.cancelAllDialogs()
    .thenCompose(
        result -> innerDc
            .replaceDialog(getInitialDialogId(), "Canceled! \n\n What skill would you like to call?")
    );

Python

dialog-root-bot/dialogs/main_dialog.py

async def on_continue_dialog(self, inner_dc: DialogContext) -> DialogTurnResult:
    # This is an example on how to cancel a SkillDialog that is currently in progress from the parent bot.
    active_skill = await self._active_skill_property.get(inner_dc.context)
    activity = inner_dc.context.activity

    if (
        active_skill
        and activity.type == ActivityTypes.message
        and "abort" in activity.text
    ):
        # 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 inner_dc.cancel_all_dialogs()
        return await inner_dc.replace_dialog(self.initial_dialog_id)

    return await super().on_continue_dialog(inner_dc)

Activity handler logic

Since skill logic for each turn is handled by a main dialog, the activity handler looks much like it would for other dialog samples.

C#

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

JavaScript

dialogRootBot/bots/rootBot.js

class RootBot extends ActivityHandler {

constructor(conversationState, dialog) {
    super();
    if (!conversationState) throw new Error('[RootBot]: Missing parameter. conversationState is required');
    if (!dialog) throw new Error('[RootBot]: Missing parameter. dialog is required');

    this.conversationState = conversationState;
    this.dialog = dialog;

    this.onTurn(async (turnContext, next) => {
        if (turnContext.activity.type !== ActivityTypes.ConversationUpdate) {
            // Run the Dialog with the activity.
            await runDialog(this.dialog, turnContext, this.conversationState.createProperty('DialogState'));
        }

        await next();
    });

/**
 * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
 */
async run(context) {
    await super.run(context);

    // Save any state changes. The load happened during the execution of the Dialog.
    await this.conversationState.saveChanges(context, false);
}

Java

DialogRootBot\Bots\RootBot.java

public class RootBot<T extends Dialog> extends ActivityHandler {

public RootBot(ConversationState conversationState, T mainDialog) {
    this.conversationState = conversationState;
    this.mainDialog = mainDialog;
}

@Override
public CompletableFuture<Void> onTurn(TurnContext turnContext) {
    return handleTurn(turnContext).thenCompose(result -> conversationState.saveChanges(turnContext, false));
}

private CompletableFuture<Void> handleTurn(TurnContext turnContext) {
    if (!turnContext.getActivity().getType().equals(ActivityTypes.CONVERSATION_UPDATE)) {
        // Run the Dialog with the Activity.
        return Dialog.run(mainDialog, turnContext, conversationState.createProperty("DialogState"));
    } else {
        // Let the super.class handle the activity.
        return super.onTurn(turnContext);
    }
}

Python

dialog-root-bot/bots/root_bot.py

class RootBot(ActivityHandler):
    def __init__(
        self, conversation_state: ConversationState, main_dialog: Dialog,
    ):
        self._conversation_state = conversation_state
        self._main_dialog = main_dialog

    async def on_turn(self, turn_context: TurnContext):
        if turn_context.activity.type != ActivityTypes.conversation_update:
            # Run the Dialog with the Activity.
            await DialogExtensions.run_dialog(
                self._main_dialog,
                turn_context,
                self._conversation_state.create_property("DialogState"),
            )
        else:
            # Let the base class handle the activity.
            await super().on_turn(turn_context)

        # Save any state changes that might have occurred during the turn.
        await self._conversation_state.save_changes(turn_context)

Service registration

The services needed to use a skill dialog are the same as those needed for a skill consumer in general. See how to implement a skill consumer for a discussion of the required services.

Test the root bot

You can test the skill consumer in the Emulator as if it were a normal bot; however, you need to run both the skill and skill consumer bots at the same time. See how to use dialogs within a skill for information on how to configure the skill.

Download and install the latest Bot Framework Emulator.

1. Run the dialog skill bot and dialog root bot locally on your machine. If you need instructions, refer to the sample's README for C#, JavaScript, Java, Python.
2. Use the Emulator to test the bot.
   • When you first join the conversation, the bot displays a welcome message and asks you what skill you would like to call. The skill bot for this sample has just one skill.
   • Select DialogSkillBot.
3. Then, the bot asks you to choose an action for the skill. Choose "BookFlight".
   1. Answer the prompts.
   2. The skill completes, and the root bot displays the booking details before prompting again for the skill you'd like to call.
4. Select DialogSkillBot again and "BookFlight".
   1. Answer the first prompt, then enter "abort" to interrupt the skill.
   2. The root bot cancels the skill and prompts for the skill you'd like to call.

More about debugging

Since traffic between skills and skill consumers is authenticated, there are extra steps when debugging such bots.

• The skill consumer and all the skills it consumes, directly or indirectly, must be running.
• If the bots are running locally and if any of the bots has an app ID and password, then all bots must have valid IDs and passwords.
• If the bots are all deployed, see how to Debug a bot from any channel using devtunnel.
• If some of the bots are running locally and some are deployed, then see how to Debug a skill or skill consumer.

Otherwise, you can debug a skill consumer or skill much like you debug other bots. For more information, see Debugging a bot and Debug with the Bot Framework Emulator.

Additional information

See how to implement a skill consumer for how to implement a skill consumer in general.