Implement a skill consumer

APPLIES TO: SDK v4

You can use skills to extend another bot. A skill is a bot that can perform a set of tasks for another bot and uses a manifest to describe its interface. A root bot is a user-facing bot that can invoke one or more skills. A root bot is a type of skill consumer.

• A skill consumer must use claims validation to manage which skills can access it.
• A skill consumer can use multiple skills.
• Developers who don't have access to the skill's source code can use the information in the skill's manifest to design their skill consumer.

This article demonstrates how to implement a skill consumer that uses the echo skill to echo the user's input. For a sample skill manifest and information about implementing the echo skill, see how to implement a skill.

For information about using a skill dialog to consume a skill, see how to use a dialog to consume a skill.

Some types of skill consumers are not able to use some types of skill bots. The following table describes which combinations are supported.

	Multi-tenant skill	Single-tenant skill	User-assigned managed identity skill
Multi-tenant consumer	Supported	Not supported	Not supported
Single-tenant consumer	Not supported	Supported if both apps belong to same tenant	Supported if both apps belong to same tenant
User-assigned managed identity consumer	Not supported	Supported if both apps belong to same tenant	Supported if both apps belong to same tenant

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.
• Optionally, an Azure subscription. If you don't have one, create a free account before you begin.
• A copy of the skills simple bot-to-bot sample in C#, JavaScript, Java, or Python.

Note

Starting with version 4.11, you don't need an app ID and password to test a skill consumer locally in the Bot Framework Emulator. An Azure subscription is still required to deploy your consumer to Azure or to consume a deployed skill.

About this sample

The skills simple bot-to-bot sample includes projects for two bots:

• The echo skill bot, which implements the skill.
• The simple root bot, which implements a root bot that consumes the skill.

This article focuses on the root bot, which includes support logic in its bot and adapter objects and includes objects used to exchange activities with a skill. These include:

• A skill client, used to send activities to a skill.
• A skill handler, used to receive activities from a skill.
• A skill conversation ID factory, used by the skill client and handler to translate between the user-root conversation reference and the root-skill conversation reference.

C#

JavaScript

Java

Python

For information about the echo skill bot, see how to Implement a skill.

Resources

For deployed bots, bot-to-bot authentication requires that each participating bot has valid identity information. However, you can test multi-tenant skills and skill consumers locally with the Emulator without an app ID and password.

Application configuration

1. Optionally, add the root bot's identity information to its config file. If either the skill or skill consumer provides identity information, both must.
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's app or client ID.
   • The skill's messaging endpoint.

Note

If either the skill or skill consumer provides identity information, both must.

C#

SimpleRootBot\appsettings.json

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/",
  "BotFrameworkSkills": [
    {
      "Id": "EchoSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

JavaScript

echo-skill-bot/.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=EchoSkillBot
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=EchoSkillBot
BotFrameworkSkills[0].AppId= "Add the App ID for the skill here"
BotFrameworkSkills[0].SkillEndpoint=http://localhost:39783/api/messages

Python

simple_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": "EchoSkillBot",
        "app_id": "",
        "skill_endpoint": "http://localhost:39783/api/messages",
    },
]

# Callers to only those specified, '*' allows any caller.

Skills configuration

This sample reads information for each skill in the configuration file into a collection of skill objects.

C#

SimpleRootBot\SkillsConfiguration.cs

public class SkillsConfiguration
{
    public SkillsConfiguration(IConfiguration configuration)
    {
        var section = configuration?.GetSection("BotFrameworkSkills");
        var skills = section?.Get<BotFrameworkSkill[]>();
        if (skills != null)
        {
            foreach (var skill in skills)
            {
                Skills.Add(skill.Id, skill);
            }
        }

        var skillHostEndpoint = configuration?.GetValue<string>(nameof(SkillHostEndpoint));
        if (!string.IsNullOrWhiteSpace(skillHostEndpoint))
        {
            SkillHostEndpoint = new Uri(skillHostEndpoint);
        }
    }

    public Uri SkillHostEndpoint { get; }

    public Dictionary<string, BotFrameworkSkill> Skills { get; } = new Dictionary<string, BotFrameworkSkill>();
}

JavaScript

simple-root-bot/skillsConfiguration.js

class SkillsConfiguration {
    constructor() {
        this.skillsData = {};

        // Note: we only have one skill in this sample but we could load more if needed.
        const botFrameworkSkill = {
            id: process.env.SkillId,
            appId: process.env.SkillAppId,
            skillEndpoint: process.env.SkillEndpoint
        };

        this.skillsData[botFrameworkSkill.id] = botFrameworkSkill;

        this.skillHostEndpointValue = process.env.SkillHostEndpoint;
        if (!this.skillHostEndpointValue) {
            throw new Error('[SkillsConfiguration]: Missing configuration parameter. SkillHostEndpoint is required');
        }
    }

    get skills() {
        return this.skillsData;
    }

    get skillHostEndpoint() {
        return this.skillHostEndpointValue;
    }
}

Java

DialogRootBot\SkillsConfiguration.java

public class SkillsConfiguration {

    private URI skillHostEndpoint;

    private Map<String, BotFrameworkSkill> skills = new HashMap<String, BotFrameworkSkill>();

    public SkillsConfiguration(Configuration configuration) {

        boolean noMoreEntries = false;
        int indexCount = 0;
        while (!noMoreEntries) {
            String botID = configuration.getProperty(String.format("BotFrameworkSkills[%d].Id", indexCount));
            String botAppId = configuration.getProperty(String.format("BotFrameworkSkills[%d].AppId", indexCount));
            String skillEndPoint =
                configuration.getProperty(String.format("BotFrameworkSkills[%d].SkillEndpoint", indexCount));
            if (
                StringUtils.isNotBlank(botID) && StringUtils.isNotBlank(botAppId)
                    && StringUtils.isNotBlank(skillEndPoint)
            ) {
                BotFrameworkSkill newSkill = new BotFrameworkSkill();
                newSkill.setId(botID);
                newSkill.setAppId(botAppId);
                try {
                    newSkill.setSkillEndpoint(new URI(skillEndPoint));
                } catch (URISyntaxException e) {
                    e.printStackTrace();
                }
                skills.put(botID, newSkill);
                indexCount++;
            } else {
                noMoreEntries = true;
            }
        }

        String skillHost = configuration.getProperty("SkillhostEndpoint");
        if (!StringUtils.isEmpty(skillHost)) {
            try {
                skillHostEndpoint = new URI(skillHost);
            } catch (URISyntaxException e) {
                e.printStackTrace();
            }
        }
    }

    /**
     * @return the SkillHostEndpoint value as a Uri.
     */
    public URI getSkillHostEndpoint() {
        return this.skillHostEndpoint;
    }

    /**
     * @return the Skills value as a Dictionary<String, BotFrameworkSkill>.
     */
    public Map<String, BotFrameworkSkill> getSkills() {
        return this.skills;
    }

}

Python

simple-root-bot/config.py

SKILLS: Dict[str, BotFrameworkSkill] = {
    skill["id"]: BotFrameworkSkill(**skill) for skill in DefaultConfig.SKILLS
}

Conversation ID factory

This creates the conversation ID for use with the skill and can recover the original user conversation ID from the skill conversation ID.

The conversation ID factory for this sample supports a simple scenario where:

• The root bot is designed to consume one specific skill.
• The root bot has only one active conversation with a skill at a time.

C#

The SDK provides a SkillConversationIdFactory class that can be used across any skill without requiring the source code to be replicated. The conversation ID factory is configured in Startup.cs.

JavaScript

The SDK provides a SkillConversationIdFactory class that can be used across any skill without requiring the source code to be replicated. The conversation ID factory is configured in index.js.

Java

Java has implemented the SkillConversationIdFactory class as an SDK class that can be used across any skill without requiring the source code to be replicated. The code for SkillConversationIdFactory can be found in the botbuilder package source code [botbuilder Java SDK code].

Python

simple-root-bot/skill_conversation_id_factory.py

class SkillConversationIdFactory(ConversationIdFactoryBase):
    def __init__(self, storage: Storage):
        if not storage:
            raise TypeError("storage can't be None")

        self._storage = storage

    async def create_skill_conversation_id(
        self,
        options_or_conversation_reference: Union[
            SkillConversationIdFactoryOptions, ConversationReference
        ],
    ) -> str:
        if not options_or_conversation_reference:
            raise TypeError("Need options or conversation reference")

        if not isinstance(
            options_or_conversation_reference, SkillConversationIdFactoryOptions
        ):
            raise TypeError(
                "This SkillConversationIdFactory can only handle SkillConversationIdFactoryOptions"
            )

        options = options_or_conversation_reference

        # Create the storage key based on the SkillConversationIdFactoryOptions.
        conversation_reference = TurnContext.get_conversation_reference(
            options.activity
        )
        skill_conversation_id = (
            f"{conversation_reference.conversation.id}"
            f"-{options.bot_framework_skill.id}"
            f"-{conversation_reference.channel_id}"
            f"-skillconvo"
        )

        # Create the SkillConversationReference instance.
        skill_conversation_reference = SkillConversationReference(
            conversation_reference=conversation_reference,
            oauth_scope=options.from_bot_oauth_scope,
        )

        # Store the SkillConversationReference using the skill_conversation_id as a key.
        skill_conversation_info = {skill_conversation_id: skill_conversation_reference}
        await self._storage.write(skill_conversation_info)

        # Return the generated skill_conversation_id (that will be also used as the conversation ID to call the skill).
        return skill_conversation_id

    async def get_conversation_reference(
        self, skill_conversation_id: str
    ) -> Union[SkillConversationReference, ConversationReference]:
        if not skill_conversation_id:
            raise TypeError("skill_conversation_id can't be None")

        # Get the SkillConversationReference from storage for the given skill_conversation_id.
        skill_conversation_info = await self._storage.read([skill_conversation_id])

        return skill_conversation_info.get(skill_conversation_id)

    async def delete_conversation_reference(self, skill_conversation_id: str):
        await self._storage.delete([skill_conversation_id])

To support more complex scenarios, design your conversation ID factory so that:

• The create skill conversation ID method gets or generates the appropriate skill conversation ID.
• The get conversation reference method gets the correct user conversation.

Skill client and skill handler

The skill consumer uses a skill client to forward activities to the skill. The client uses the skills configuration information and conversation ID factory to do so.

The skill consumer uses a skill handler to receive activities from a skill. The handler uses the conversation ID factory, the authentication configuration, and a credential provider to do so, and also has dependencies on the root bot's adapter and activity handler

C#

SimpleRootBot\Startup.cs

services.AddSingleton<IBotFrameworkHttpAdapter>(sp => sp.GetService<CloudAdapter>());
services.AddSingleton<BotAdapter>(sp => sp.GetService<CloudAdapter>());

JavaScript

simple-root-bot/index.js

// Create the conversationIdFactory
const conversationIdFactory = new SkillConversationIdFactory(new MemoryStorage());

// Create the skill client.
const skillClient = botFrameworkAuthentication.createBotFrameworkClient();

const handler = new CloudSkillHandler(adapter, (context) => bot.run(context), conversationIdFactory, botFrameworkAuthentication);

Java

DialogRootBot\application.java

@Bean
public SkillHttpClient getSkillHttpClient(
    CredentialProvider credentialProvider,
    SkillConversationIdFactoryBase conversationIdFactory,
    ChannelProvider channelProvider
) {
    return new SkillHttpClient(credentialProvider, conversationIdFactory, channelProvider);
}

@Bean
public SkillConversationIdFactoryBase getSkillConversationIdFactoryBase() {
    return new SkillConversationIdFactory(getStorage());
}

@Bean public ChannelServiceHandler getChannelServiceHandler(
    BotAdapter botAdapter,
    Bot bot,
    SkillConversationIdFactoryBase conversationIdFactory,
    CredentialProvider credentialProvider,
    AuthenticationConfiguration authConfig,
    ChannelProvider channelProvider
) {
    return new SkillHandler(
        botAdapter,
        bot,
        conversationIdFactory,
        credentialProvider,
        authConfig,
        channelProvider);
}

Python

simple-root-bot/app.py

CREDENTIAL_PROVIDER = SimpleCredentialProvider(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
CLIENT = SkillHttpClient(CREDENTIAL_PROVIDER, ID_FACTORY)

    ADAPTER, BOT, ID_FACTORY, CREDENTIAL_PROVIDER, AUTH_CONFIG
)

HTTP traffic from the skill will come into the service URL endpoint that the skill consumer advertises to the skill. Use a language-specific endpoint handler to forward traffic to the skill handler.

The default skill handler:

• If an app ID and password are present, uses an authentication configuration object to perform both bot-to-bot authentication and claims validation.
• Uses the conversation ID factory to translate from the consumer-skill conversation back to the root-user conversation.
• Generates a proactive message so that the skill consumer can reestablish a root-user turn context and forward activities to the user.

Activity handler logic

Of note, the skill consumer logic should:

• Remember whether there are any active skills and forward activities to them as appropriate.
• Notice when a user makes a request that should be forwarded to a skill, and start the skill.
• Look for an endOfConversation activity from any active skill, to notice when it completes.
• If appropriate, add logic to let the user or skill consumer cancel a skill that has not completed yet.
• Save state before making the call to a skill, as any response may come back to a different instance of the skill consumer.

C#

SimpleRootBot\Bots\RootBot.cs

The root bot has dependencies on conversation state, the skills information, the skill client, and the general configuration. ASP.NET provides these objects through dependency injection. The root bot also defines a conversation state property accessor to track which skill is active.

public static readonly string ActiveSkillPropertyName = $"{typeof(RootBot).FullName}.ActiveSkillProperty";
private readonly IStatePropertyAccessor<BotFrameworkSkill> _activeSkillProperty;
private readonly string _botId;
private readonly ConversationState _conversationState;
private readonly BotFrameworkAuthentication _auth;
private readonly SkillConversationIdFactoryBase _conversationIdFactory;
private readonly SkillsConfiguration _skillsConfig;
private readonly BotFrameworkSkill _targetSkill;

public RootBot(BotFrameworkAuthentication auth, ConversationState conversationState, SkillsConfiguration skillsConfig, SkillConversationIdFactoryBase conversationIdFactory, IConfiguration configuration)
{
    _auth = auth ?? throw new ArgumentNullException(nameof(auth));
    _conversationState = conversationState ?? throw new ArgumentNullException(nameof(conversationState));
    _skillsConfig = skillsConfig ?? throw new ArgumentNullException(nameof(skillsConfig));
    _conversationIdFactory = conversationIdFactory ?? throw new ArgumentNullException(nameof(conversationIdFactory));

    if (configuration == null)
    {
        throw new ArgumentNullException(nameof(configuration));
    }

    _botId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;

    // We use a single skill in this example.
    var targetSkillId = "EchoSkillBot";
    _skillsConfig.Skills.TryGetValue(targetSkillId, out _targetSkill);

    // Create state property to track the active skill
    _activeSkillProperty = conversationState.CreateProperty<BotFrameworkSkill>(ActiveSkillPropertyName);
}

This sample has a helper method for forwarding activities to a skill. It saves conversation state before invoking the skill, and it checks whether the HTTP request was successful.

private async Task SendToSkill(ITurnContext turnContext, BotFrameworkSkill targetSkill, CancellationToken cancellationToken)
{
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
    await _conversationState.SaveChangesAsync(turnContext, force: true, cancellationToken: cancellationToken);

    // Create a conversationId to interact with the skill and send the activity
    var options = new SkillConversationIdFactoryOptions
    {
        FromBotOAuthScope = turnContext.TurnState.Get<string>(BotAdapter.OAuthScopeKey),
        FromBotId = _botId,
        Activity = turnContext.Activity,
        BotFrameworkSkill = targetSkill
    };
    var skillConversationId = await _conversationIdFactory.CreateSkillConversationIdAsync(options, cancellationToken);

    using var client = _auth.CreateBotFrameworkClient();

    // route the activity to the skill
    var response = await client.PostActivityAsync(_botId, targetSkill.AppId, targetSkill.SkillEndpoint, _skillsConfig.SkillHostEndpoint, skillConversationId, turnContext.Activity, cancellationToken);

    // Check response status
    if (!(response.Status >= 200 && response.Status <= 299))
    {
        throw new HttpRequestException($"Error invoking the skill id: \"{targetSkill.Id}\" at \"{targetSkill.SkillEndpoint}\" (status is {response.Status}). \r\n {response.Body}");
    }
}

Of note, the root bot includes logic for forwarding activities to the skill, starting the skill at the user's request, and stopping the skill when the skill completes.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Text.Contains("skill"))
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Got it, connecting you to the skill..."), cancellationToken);

        // Save active skill in state
        await _activeSkillProperty.SetAsync(turnContext, _targetSkill, cancellationToken);

        // Send the activity to the skill
        await SendToSkill(turnContext, _targetSkill, cancellationToken);
        return;
    }

    // just respond
    await turnContext.SendActivityAsync(MessageFactory.Text("Me no nothin'. Say \"skill\" and I'll patch you through"), cancellationToken);

    // Save conversation state
    await _conversationState.SaveChangesAsync(turnContext, force: true, cancellationToken: cancellationToken);
}

protected override async Task OnEndOfConversationActivityAsync(ITurnContext<IEndOfConversationActivity> turnContext, CancellationToken cancellationToken)
{
    // forget skill invocation
    await _activeSkillProperty.DeleteAsync(turnContext, cancellationToken);

    // Show status message, text and value returned by the skill
    var eocActivityMessage = $"Received {ActivityTypes.EndOfConversation}.\n\nCode: {turnContext.Activity.Code}";
    if (!string.IsNullOrWhiteSpace(turnContext.Activity.Text))
    {
        eocActivityMessage += $"\n\nText: {turnContext.Activity.Text}";
    }

    if ((turnContext.Activity as Activity)?.Value != null)
    {
        eocActivityMessage += $"\n\nValue: {JsonConvert.SerializeObject((turnContext.Activity as Activity)?.Value)}";
    }

    await turnContext.SendActivityAsync(MessageFactory.Text(eocActivityMessage), cancellationToken);

    // We are back at the root
    await turnContext.SendActivityAsync(MessageFactory.Text("Back in the root bot. Say \"skill\" and I'll patch you through"), cancellationToken);

    // Save conversation state
    await _conversationState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);
}

JavaScript

simple-root-bot/rootBot.js

The root bot has dependencies on conversation state, the skills information, and the skill client. The root bot also defines a conversation state property accessor to track which skill is active.

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

    this.conversationState = conversationState;
    this.skillsConfig = skillsConfig;
    this.skillClient = skillClient;
    this.conversationIdFactory = conversationIdFactory;

// Create state property to track the active skill
this.activeSkillProperty = this.conversationState.createProperty(RootBot.ActiveSkillPropertyName);

This sample has a helper method for forwarding activities to a skill. It saves conversation state before invoking the skill, and it checks whether the HTTP request was successful.

async sendToSkill(context, targetSkill) {
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
    await this.conversationState.saveChanges(context, true);

    // Create a conversationId to interact with the skill and send the activity
    const skillConversationId = await this.conversationIdFactory.createSkillConversationIdWithOptions({
        fromBotOAuthScope: context.turnState.get(context.adapter.OAuthScopeKey),
        fromBotId: this.botId,
        activity: context.activity,
        botFrameworkSkill: this.targetSkill
    });

    // route the activity to the skill
    const response = await this.skillClient.postActivity(this.botId, targetSkill.appId, targetSkill.skillEndpoint, this.skillsConfig.skillHostEndpoint, skillConversationId, context.activity);

    // Check response status
    if (!(response.status >= 200 && response.status <= 299)) {
        throw new Error(`[RootBot]: Error invoking the skill id: "${ targetSkill.id }" at "${ targetSkill.skillEndpoint }" (status is ${ response.status }). \r\n ${ response.body }`);
    }
}

Of note, the root bot includes logic for forwarding activities to the skill, starting the skill at the user's request, and stopping the skill when the skill completes.

// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (context, next) => {
    if (context.activity.text.toLowerCase() === 'skill') {
        await context.sendActivity('Got it, connecting you to the skill...');

        // Set active skill
        await this.activeSkillProperty.set(context, this.targetSkill);

        // Send the activity to the skill
        await this.sendToSkill(context, this.targetSkill);
    } else {
        await context.sendActivity("Me no nothin'. Say 'skill' and I'll patch you through");
    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

// Handle EndOfConversation returned by the skill.
this.onEndOfConversation(async (context, next) => {
    // Stop forwarding activities to Skill.
    await this.activeSkillProperty.set(context, undefined);

    // Show status message, text and value returned by the skill
    let eocActivityMessage = `Received ${ ActivityTypes.EndOfConversation }.\n\nCode: ${ context.activity.code }`;
    if (context.activity.text) {
        eocActivityMessage += `\n\nText: ${ context.activity.text }`;
    }

    if (context.activity.value) {
        eocActivityMessage += `\n\nValue: ${ context.activity.value }`;
    }

    await context.sendActivity(eocActivityMessage);

    // We are back at the root
    await context.sendActivity('Back in the root bot. Say \'skill\' and I\'ll patch you through');

    // Save conversation state
    await this.conversationState.saveChanges(context, true);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

DialogRootBot\RootBot.java

The root bot has dependencies on conversation state, the skills information, the skill client, and the general configuration. ASP.NET provides these objects through dependency injection. The root bot also defines a conversation state property accessor to track which skill is active.

public static final String ActiveSkillPropertyName = "com.microsoft.bot.sample.simplerootbot.ActiveSkillProperty";
private StatePropertyAccessor<BotFrameworkSkill> activeSkillProperty;
private String botId;
private ConversationState conversationState;
private SkillHttpClient skillClient;
private SkillsConfiguration skillsConfig;
private BotFrameworkSkill targetSkill;

public RootBot(
    ConversationState conversationState,
    SkillsConfiguration skillsConfig,
    SkillHttpClient skillClient,
    Configuration configuration
) {
    if (conversationState == null) {
        throw new  IllegalArgumentException("conversationState cannot be null.");
    }

    if (skillsConfig == null) {
        throw new  IllegalArgumentException("skillsConfig cannot be null.");
    }

    if (skillClient == null) {
        throw new  IllegalArgumentException("skillsClient cannot be null.");
    }

    if (configuration == null) {
        throw new  IllegalArgumentException("configuration cannot be null.");
    }


    this.conversationState = conversationState;
    this.skillsConfig = skillsConfig;
    this.skillClient = skillClient;

    botId = configuration.getProperty(MicrosoftAppCredentials.MICROSOFTAPPID);

    if (StringUtils.isEmpty(botId)) {
        throw new IllegalArgumentException(String.format("%s instanceof not set in configuration",
                                                         MicrosoftAppCredentials.MICROSOFTAPPID));
    }

    // We use a single skill in this example.
    String targetSkillId = "EchoSkillBot";
    if (!skillsConfig.getSkills().containsKey(targetSkillId)) {
        throw new IllegalArgumentException(
            String.format("Skill with ID \"%s\" not found in configuration", targetSkillId)
        );
    } else {
        targetSkill = (BotFrameworkSkill) skillsConfig.getSkills().get(targetSkillId);
    }

    // Create state property to track the active skill
    activeSkillProperty = conversationState.createProperty(ActiveSkillPropertyName);
}

This sample has a helper method for forwarding activities to a skill. It saves conversation state before invoking the skill, and it checks whether the HTTP request was successful.

private CompletableFuture<Void> sendToSkill(TurnContext turnContext, BotFrameworkSkill targetSkill) {
    // NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    // will have access to current accurate state.
     return conversationState.saveChanges(turnContext, true)
     .thenAccept(result -> {
        // route the activity to the skill
        skillClient.postActivity(botId,
                                targetSkill,
                                skillsConfig.getSkillHostEndpoint(),
                                turnContext.getActivity(),
                                Object.class)
        .thenApply(response -> {
        // Check response status
        if (!(response.getStatus() >= 200 && response.getStatus() <= 299)) {
                throw new RuntimeException(
                    String.format(
                        "Error invoking the skill id: \"%s\" at \"%s\" (status instanceof %s). \r\n %s",
                        targetSkill.getId(),
                        targetSkill.getSkillEndpoint(),
                        response.getStatus(),
                        response.getBody()));
            }
            return CompletableFuture.completedFuture(null);
        });
     });
}

Of note, the root bot includes logic for forwarding activities to the skill, starting the skill at the user's request, and stopping the skill when the skill completes.

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    if (turnContext.getActivity().getText().contains("skill")) {
        return turnContext.sendActivity(MessageFactory.text("Got it, connecting you to the skill..."))
        .thenCompose(result -> {
            activeSkillProperty.set(turnContext, targetSkill);
            // Send the activity to the skill
            return sendToSkill(turnContext, targetSkill);
        });
    }

    // just respond
     return turnContext.sendActivity(
         MessageFactory.text("Me no nothin'. Say \"skill\" and I'll patch you through"))
     .thenCompose(result -> conversationState.saveChanges(turnContext, true));
}

@Override
protected CompletableFuture<Void> onEndOfConversationActivity(TurnContext turnContext) {
    // forget skill invocation
     return activeSkillProperty.delete(turnContext).thenAccept(result -> {
        // Show status message, text and value returned by the skill
        String eocActivityMessage = String.format("Received %s.\n\nCode: %s",
                                                   ActivityTypes.END_OF_CONVERSATION,
                                                   turnContext.getActivity().getCode());

        if (!StringUtils.isEmpty(turnContext.getActivity().getText())) {
            eocActivityMessage += String.format("\n\nText: %s", turnContext.getActivity().getText());
        }

        if (turnContext.getActivity() != null && turnContext.getActivity().getValue() != null) {
            eocActivityMessage += String.format("\n\nValue: %s", turnContext.getActivity().getValue());
        }

        turnContext.sendActivity(MessageFactory.text(eocActivityMessage)).thenCompose(sendResult ->{
            // We are back at the root
            return turnContext.sendActivity(
            MessageFactory.text("Back in the root bot. Say \"skill\" and I'll patch you through"))
            .thenCompose(secondSendResult-> conversationState.saveChanges(turnContext));
        });
     });
}

Python

simple-root-bot/bots/root_bot.py

The root bot has dependencies on conversation state, the skills information, the skill client, and the general configuration. The root bot also defines a conversation state property accessor to track which skill is active.

def __init__(
    self,
    conversation_state: ConversationState,
    skills_config: SkillConfiguration,
    skill_client: SkillHttpClient,
    config: DefaultConfig,
):
    self._bot_id = config.APP_ID
    self._skill_client = skill_client
    self._skills_config = skills_config
    self._conversation_state = conversation_state
    self._active_skill_property = conversation_state.create_property(
        ACTIVE_SKILL_PROPERTY_NAME
    )

This sample has a helper method for forwarding activities to a skill. It saves conversation state before invoking the skill, and it checks whether the HTTP request was successful.

async def __send_to_skill(
    self, turn_context: TurnContext, target_skill: BotFrameworkSkill
):
    # NOTE: Always SaveChanges() before calling a skill so that any activity generated by the skill
    # will have access to current accurate state.
    await self._conversation_state.save_changes(turn_context, force=True)

    # route the activity to the skill
    await self._skill_client.post_activity_to_skill(
        self._bot_id,
        target_skill,
        self._skills_config.SKILL_HOST_ENDPOINT,
        turn_context.activity,
    )

Of note, the root bot includes logic for forwarding activities to the skill, starting the skill at the user's request, and stopping the skill when the skill completes.

async def on_message_activity(self, turn_context: TurnContext):
    if "skill" in turn_context.activity.text:
        # Begin forwarding Activities to the skill
        await turn_context.send_activity(
            MessageFactory.text("Got it, connecting you to the skill...")
        )

        skill = self._skills_config.SKILLS[TARGET_SKILL_ID]
        # Save active skill in state
        await self._active_skill_property.set(turn_context, skill)

        # Send the activity to the skill
        await self.__send_to_skill(turn_context, skill)
    else:
        # just respond
        await turn_context.send_activity(
            MessageFactory.text(
                "Me no nothin'. Say \"skill\" and I'll patch you through"
            )
        )

async def on_end_of_conversation_activity(self, turn_context: TurnContext):
    # forget skill invocation
    await self._active_skill_property.delete(turn_context)

    eoc_activity_message = f"Received {ActivityTypes.end_of_conversation}.\n\nCode: {turn_context.activity.code}"
    if turn_context.activity.text:
        eoc_activity_message = (
            eoc_activity_message + f"\n\nText: {turn_context.activity.text}"
        )

    if turn_context.activity.value:
        eoc_activity_message = (
            eoc_activity_message + f"\n\nValue: {turn_context.activity.value}"
        )

    await turn_context.send_activity(eoc_activity_message)

    # We are back
    await turn_context.send_activity(
        MessageFactory.text(
            'Back in the root bot. Say "skill" and I\'ll patch you through'
        )
    )

    await self._conversation_state.save_changes(turn_context, force=True)

On turn error handler

When an error occurs, the adapter clears conversation state to reset the conversation with the user and avoid persisting an error state.

It's a good practice to send an end of conversation activity to any active skill before clearing conversation state in the skill consumer. This lets the skill release any resources associated with the consumer-skill conversation before the skill consumer releases the conversation.

C#

SimpleRootBot\AdapterWithErrorHandler.cs

In this sample, the turn error logic is split up among a few helper methods.

private async Task HandleTurnError(ITurnContext turnContext, Exception exception)
{
    // Log any leaked exception from the application.
    // NOTE: In production environment, you should consider logging this to
    // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
    // to add telemetry capture to your bot.
    _logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

    await SendErrorMessageAsync(turnContext, exception);
    await EndSkillConversationAsync(turnContext);
    await ClearConversationStateAsync(turnContext);
}

private async Task SendErrorMessageAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        // Send a trace activity, which will be displayed in the Bot Framework Emulator
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.ToString(), "https://www.botframework.com/schemas/error", "TurnError");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendErrorMessageAsync : {ex}");
    }
}

private async Task EndSkillConversationAsync(ITurnContext turnContext)
{
    if (_skillsConfig == null)
    {
        return;
    }

    try
    {
        // Inform the active skill that the conversation is ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName is set by the RooBot while messages are being
        // forwarded to a Skill.
        var activeSkill = await _conversationState.CreateProperty<BotFrameworkSkill>(RootBot.ActiveSkillPropertyName).GetAsync(turnContext, () => null);
        if (activeSkill != null)
        {
            var botId = _configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;

            var endOfConversation = Activity.CreateEndOfConversationActivity();
            endOfConversation.Code = "RootSkillError";
            endOfConversation.ApplyConversationReference(turnContext.Activity.GetConversationReference(), true);

            await _conversationState.SaveChangesAsync(turnContext, true);

            using var client = _auth.CreateBotFrameworkClient();

            await client.PostActivityAsync(botId, activeSkill.AppId, activeSkill.SkillEndpoint, _skillsConfig.SkillHostEndpoint, endOfConversation.Conversation.Id, (Activity)endOfConversation, CancellationToken.None);
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught on attempting to send EndOfConversation : {ex}");
    }
}

private async Task ClearConversationStateAsync(ITurnContext turnContext)
{
    try
    {
        // Delete the conversationState for the current conversation to prevent the
        // bot from getting stuck in a error-loop caused by being in a bad state.
        // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
        await _conversationState.DeleteAsync(turnContext);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught on attempting to Delete ConversationState : {ex}");
    }
}

JavaScript

simple-root-bot/index.js

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to the console log, instead of to app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    await sendErrorMessage(context, error);
    await endSkillConversation(context);
    await clearConversationState(context);
};

async function sendErrorMessage(context, error) {
    try {
        // Send a message to the user.
        let onTurnErrorMessage = 'The bot encountered an error or bug.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.IgnoringInput);

        onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
        await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);

        // Send a trace activity, which will be displayed in Bot Framework Emulator.
        await context.sendTraceActivity(
            'OnTurnError Trace',
            `${ error }`,
            'https://www.botframework.com/schemas/error',
            'TurnError'
        );
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught in sendErrorMessage: ${ err }`);
    }
}

async function endSkillConversation(context) {
    try {
        // Inform the active skill that the conversation is ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName is set by the RooBot while messages are being
        // forwarded to a Skill.
        const activeSkill = await conversationState.createProperty(RootBot.ActiveSkillPropertyName).get(context);
        if (activeSkill) {
            const botId = process.env.MicrosoftAppId;

            let endOfConversation = {
                type: ActivityTypes.EndOfConversation,
                code: 'RootSkillError'
            };
            endOfConversation = TurnContext.applyConversationReference(
                endOfConversation, TurnContext.getConversationReference(context.activity), true);

            await conversationState.saveChanges(context, true);
            await skillClient.postActivity(botId, activeSkill.appId, activeSkill.skillEndpoint, skillsConfig.skillHostEndpoint, endOfConversation.conversation.id, endOfConversation);
        }
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught on attempting to send EndOfConversation : ${ err }`);
    }
}

async function clearConversationState(context) {
    try {
        // Delete the conversationState for the current conversation to prevent the
        // bot from getting stuck in a error-loop caused by being in a bad state.
        // ConversationState should be thought of as similar to "cookie-state" in a Web page.
        await conversationState.delete(context);
    } catch (err) {
        console.error(`\n [onTurnError] Exception caught on attempting to Delete ConversationState : ${ err }`);
    }
}

Java

DialogRootBot\SkillAdapterWithErrorHandler.java

In this sample the turn error logic is split up among a few helper methods.

private class SkillAdapterErrorHandler implements OnTurnErrorHandler {

    @Override
    public CompletableFuture<Void> invoke(TurnContext turnContext, Throwable exception) {
        return sendErrorMessage(turnContext, exception).thenAccept(result -> {
            endSkillConversation(turnContext);
        }).thenAccept(endResult -> {
            clearConversationState(turnContext);
        });
    }

    private CompletableFuture<Void> sendErrorMessage(TurnContext turnContext, Throwable exception) {
        try {
            // Send a message to the user.
            String errorMessageText = "The bot encountered an error or bug.";
            Activity errorMessage =
                MessageFactory.text(errorMessageText, errorMessageText, InputHints.IGNORING_INPUT);
            return turnContext.sendActivity(errorMessage).thenAccept(result -> {
                String secondLineMessageText = "To continue to run this bot, please fix the bot source code.";
                Activity secondErrorMessage =
                    MessageFactory.text(secondLineMessageText, secondLineMessageText, InputHints.EXPECTING_INPUT);
                turnContext.sendActivity(secondErrorMessage)
                    .thenApply(
                        sendResult -> {
                            // Send a trace activity, which will be displayed in the Bot Framework Emulator.
                            // Note: we return the entire exception in the value property to help the
                            // developer;
                            // this should not be done in production.
                            return TurnContext.traceActivity(
                                turnContext,
                                String.format("OnTurnError Trace %s", exception.toString())
                            );
                        }
                    );
            }).thenApply(finalResult -> null);

        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

    private CompletableFuture<Void> endSkillConversation(TurnContext turnContext) {
        if (skillHttpClient == null || skillsConfiguration == null) {
            return CompletableFuture.completedFuture(null);
        }

        // Inform the active skill that the conversation instanceof ended so that it has
        // a chance to clean up.
        // Note: ActiveSkillPropertyName instanceof set by the RooBot while messages are
        // being
        StatePropertyAccessor<BotFrameworkSkill> skillAccessor =
            conversationState.createProperty(RootBot.ActiveSkillPropertyName);
        // forwarded to a Skill.
        return skillAccessor.get(turnContext, () -> null).thenApply(activeSkill -> {
            if (activeSkill != null) {
                String botId = configuration.getProperty(MicrosoftAppCredentials.MICROSOFTAPPID);

                Activity endOfConversation = Activity.createEndOfConversationActivity();
                endOfConversation.setCode(EndOfConversationCodes.ROOT_SKILL_ERROR);
                endOfConversation
                    .applyConversationReference(turnContext.getActivity().getConversationReference(), true);

                return conversationState.saveChanges(turnContext, true).thenCompose(saveResult -> {
                    return skillHttpClient.postActivity(
                        botId,
                        activeSkill,
                        skillsConfiguration.getSkillHostEndpoint(),
                        endOfConversation,
                        Object.class
                    );

                });
            }
            return CompletableFuture.completedFuture(null);
        }).thenApply(result -> null);
    }

    private CompletableFuture<Void> clearConversationState(TurnContext turnContext) {
        try {
            return conversationState.delete(turnContext);
        } catch (Exception ex) {
            return Async.completeExceptionally(ex);
        }
    }

}

Python

simple-root-bot/adapter_with_error_handler.py

    # This check writes out errors to console log
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()
    await self._send_error_message(turn_context, error)
    await self._end_skill_conversation(turn_context, error)
    await self._clear_conversation_state(turn_context)

async def _send_error_message(self, turn_context: TurnContext, error: Exception):
    if not self._skill_client or not self._skill_config:
        return
    try:
        # Send a message to the user.
        error_message_text = "The skill encountered an error or bug."
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        error_message_text = (
            "To continue to run this bot, please fix the bot source code."
        )
        error_message = MessageFactory.text(
            error_message_text, error_message_text, InputHints.ignoring_input
        )
        await turn_context.send_activity(error_message)

        # Send a trace activity, which will be displayed in Bot Framework Emulator.
        await turn_context.send_trace_activity(
            label="TurnError",
            name="on_turn_error Trace",
            value=f"{error}",
            value_type="https://www.botframework.com/schemas/error",
        )
    except Exception as exception:
        print(
            f"\n Exception caught on _send_error_message : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

async def _end_skill_conversation(
    self, turn_context: TurnContext, error: Exception
):
    if not self._skill_client or not self._skill_config:
        return

    try:
        # Inform the active skill that the conversation is ended so that it has a chance to clean up.
        # Note: the root bot manages the ActiveSkillPropertyName, which has a value while the root bot
        # has an active conversation with a skill.
        active_skill = await self._conversation_state.create_property(
            ACTIVE_SKILL_PROPERTY_NAME
        ).get(turn_context)

        if active_skill:
            bot_id = self._config.APP_ID
            end_of_conversation = Activity(type=ActivityTypes.end_of_conversation)
            end_of_conversation.code = "RootSkillError"
            TurnContext.apply_conversation_reference(
                end_of_conversation,
                TurnContext.get_conversation_reference(turn_context.activity),
                True,
            )

            await self._conversation_state.save_changes(turn_context, True)
            await self._skill_client.post_activity_to_skill(
                bot_id,
                active_skill,
                self._skill_config.SKILL_HOST_ENDPOINT,
                end_of_conversation,
            )
    except Exception as exception:
        print(
            f"\n Exception caught on _end_skill_conversation : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

async def _clear_conversation_state(self, turn_context: TurnContext):
    try:
        # Delete the conversationState for the current conversation to prevent the
        # bot from getting stuck in a error-loop caused by being in a bad state.
        # ConversationState should be thought of as similar to "cookie-state" for a Web page.
        await self._conversation_state.delete(turn_context)
    except Exception as exception:
        print(
            f"\n Exception caught on _clear_conversation_state : {exception}",
            file=sys.stderr,
        )
        traceback.print_exc()

Skills endpoint

The bot defines an endpoint that forwards incoming skill activities to the root bot's skill handler.

C#

SimpleRootBot\Controllers\SkillController.cs

[ApiController]
[Route("api/skills")]
public class SkillController : ChannelServiceController
{
    public SkillController(ChannelServiceHandlerBase handler)
        : base(handler)
    {
    }
}

JavaScript

simple-root-bot/index.js

const handler = new CloudSkillHandler(adapter, (context) => bot.run(context), conversationIdFactory, botFrameworkAuthentication);
const skillEndpoint = new ChannelServiceRoutes(handler);
skillEndpoint.register(server, '/api/skills');

Java

DialogRootBot\Controllers\SkillController.java

@RestController
@RequestMapping(value = {"/api/skills"})
public class SkillController extends ChannelServiceController {

    public SkillController(ChannelServiceHandler handler) {
        super(handler);
    }
}

Python

simple-root-bot/app.py

APP.router.add_post("/api/messages", messages)

Service registration

Include an authentication configuration object with any claims validation, plus all the additional objects. This sample uses the same authentication configuration logic for validating activities from both users and skills.

C#

SimpleRootBot\Startup.cs

// Register the skills configuration class
services.AddSingleton<SkillsConfiguration>();

// Register AuthConfiguration to enable custom claim validation.
services.AddSingleton(sp =>
{
    var allowedSkills = sp.GetService<SkillsConfiguration>().Skills.Values.Select(s => s.AppId).ToList();

    var claimsValidator = new AllowedSkillsClaimsValidator(allowedSkills);

    // If TenantId is specified in config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
    // The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
    var validTokenIssuers = new List<string>();
    var tenantId = sp.GetService<IConfiguration>().GetSection(MicrosoftAppCredentials.MicrosoftAppTenantIdKey)?.Value;

    if (!string.IsNullOrWhiteSpace(tenantId))
    {
        // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
        // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidTokenIssuerUrlTemplateV2, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1, tenantId));
        validTokenIssuers.Add(string.Format(CultureInfo.InvariantCulture, AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2, tenantId));
    }

    return new AuthenticationConfiguration
    {
        ClaimsValidator = claimsValidator,
        ValidTokenIssuers = validTokenIssuers
    };
});

JavaScript

simple-root-bot/index.js

// Load skills configuration
const skillsConfig = new SkillsConfiguration();

const allowedSkills = Object.values(skillsConfig.skills).map(skill => skill.appId);

const claimsValidators = allowedCallersClaimsValidator(allowedSkills);

// If the MicrosoftAppTenantId is specified in the environment config, add the tenant as a valid JWT token issuer for Bot to Skill conversation.
// The token issuer for MSI and single tenant scenarios will be the tenant where the bot is registered.
let validTokenIssuers = [];
const { MicrosoftAppTenantId } = process.env;

if (MicrosoftAppTenantId) {
    // For SingleTenant/MSI auth, the JWT tokens will be issued from the bot's home tenant.
    // Therefore, these issuers need to be added to the list of valid token issuers for authenticating activity requests.
    validTokenIssuers = [
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV1 }${ MicrosoftAppTenantId }/`,
        `${ AuthenticationConstants.ValidGovernmentTokenIssuerUrlTemplateV2 }${ MicrosoftAppTenantId }/v2.0/`
    ];
}

// Define our authentication configuration.
const authConfig = new AuthenticationConfiguration([], claimsValidators, validTokenIssuers);

const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: process.env.MicrosoftAppId,
    MicrosoftAppPassword: process.env.MicrosoftAppPassword,
    MicrosoftAppType: process.env.MicrosoftAppType,
    MicrosoftAppTenantId: process.env.MicrosoftAppTenantId
});

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env, credentialsFactory, authConfig);

Java

DialogRootBot\Application.java

/**
 * This class extends the BotDependencyConfiguration which provides the default
 * implementations for a Bot application.  The Application class should
 * override methods in order to provide custom implementations.
 */
public class Application extends BotDependencyConfiguration {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    /**
     * Returns the Bot for this application.
     *
     * <p>
     *     The @Component annotation could be used on the Bot class instead of this method
     *     with the @Bean annotation.
     * </p>
     *
     * @return The Bot implementation for this application.
     */
    @Bean
    public Bot getBot(
        ConversationState conversationState,
        SkillsConfiguration skillsConfig,
        SkillHttpClient skillClient,
        Configuration configuration
    ) {
        return new RootBot(conversationState, skillsConfig, skillClient, configuration);
    }

    @Override
    public AuthenticationConfiguration getAuthenticationConfiguration(Configuration configuration) {
        AuthenticationConfiguration authenticationConfiguration = new AuthenticationConfiguration();
        authenticationConfiguration.setClaimsValidator(
            new AllowedSkillsClaimsValidator(getSkillsConfiguration(configuration)));
        return authenticationConfiguration;
    }

    /**
     * Returns a custom Adapter that provides error handling.
     *
     * @param configuration The Configuration object to use.
     * @return An error handling BotFrameworkHttpAdapter.
     */
    @Override
    public BotFrameworkHttpAdapter getBotFrameworkHttpAdaptor(Configuration configuration) {
        return new SkillAdapterWithErrorHandler(
                                configuration,
                                getConversationState(new MemoryStorage()),
                                getSkillHttpClient(
                                    getCredentialProvider(configuration),
                                    getSkillConversationIdFactoryBase(),
                                    getChannelProvider(configuration)),
                                getSkillsConfiguration(configuration));
    }

    @Bean
    public SkillsConfiguration getSkillsConfiguration(Configuration configuration) {
        return new SkillsConfiguration(configuration);
    }

    @Bean
    public SkillHttpClient getSkillHttpClient(
        CredentialProvider credentialProvider,
        SkillConversationIdFactoryBase conversationIdFactory,
        ChannelProvider channelProvider
    ) {
        return new SkillHttpClient(credentialProvider, conversationIdFactory, channelProvider);
    }

    @Bean
    public SkillConversationIdFactoryBase getSkillConversationIdFactoryBase() {
        return new SkillConversationIdFactory(getStorage());
    }

    @Bean public ChannelServiceHandler getChannelServiceHandler(
        BotAdapter botAdapter,
        Bot bot,
        SkillConversationIdFactoryBase conversationIdFactory,
        CredentialProvider credentialProvider,
        AuthenticationConfiguration authConfig,
        ChannelProvider channelProvider
    ) {
        return new SkillHandler(
            botAdapter,
            bot,
            conversationIdFactory,
            credentialProvider,
            authConfig,
            channelProvider);
    }
}

Python

simple-root-bot/app.py

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
SETTINGS = ConfigurationBotFrameworkAuthentication(
    CONFIG,
    auth_configuration=AUTH_CONFIG,
)

STORAGE = MemoryStorage()
CONVERSATION_STATE = ConversationState(STORAGE)

ID_FACTORY = SkillConversationIdFactory(STORAGE)
CREDENTIAL_PROVIDER = SimpleCredentialProvider(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
CLIENT = SkillHttpClient(CREDENTIAL_PROVIDER, ID_FACTORY)

ADAPTER = AdapterWithErrorHandler(
    SETTINGS, CONFIG, CONVERSATION_STATE, CLIENT, SKILL_CONFIG
)

# Create the Bot
BOT = RootBot(CONVERSATION_STATE, SKILL_CONFIG, CLIENT, CONFIG)

SKILL_HANDLER = SkillHandler(
    ADAPTER, BOT, ID_FACTORY, CREDENTIAL_PROVIDER, AUTH_CONFIG
)


# Listen for incoming requests on /api/messages
async def messages(req: Request) -> Response:
    # Main bot message handler.
    if "application/json" in req.headers["Content-Type"]:
        body = await req.json()
    else:
        return Response(status=HTTPStatus.UNSUPPORTED_MEDIA_TYPE)

    activity = Activity().deserialize(body)
    auth_header = req.headers["Authorization"] if "Authorization" in req.headers else ""

    invoke_response = await ADAPTER.process_activity(auth_header, activity, BOT.on_turn)
    if invoke_response:
        return json_response(data=invoke_response.body, status=invoke_response.status)
    return Response(status=HTTPStatus.OK)

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 implement a skill for information on how to configure the skill.

Download and install the latest Bot Framework Emulator

1. Run the echo skill bot and simple root bot locally on your machine. If you need instructions, refer to the README file for the C#, JavaScript, Java, or Python sample.
2. Use the Emulator to test the bot as shown below. When you send an end or stop message to the skill, the skill sends to the root bot an endOfConversation activity, in addition to the reply message. The endOfConversation activity's code property indicates that the skill completed successfully.

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

Here are some things to consider when implementing a more complex root bot.

To allow the user to cancel a multi-step skill

The root bot should check the user's message before forwarding it to the active skill. If the user wants to cancel the current process, the root bot can send an endOfConversation activity to the skill, instead of forwarding the message.

To exchange data between the root and skill bots

To send parameters to the skill, the skill consumer can set the value property on messages it sends to the skill. To receive return values from the skill, the skill consumer should check the value property when the skill sends an endOfConversation activity.

To use multiple skills

• If a skill is active, the root bot needs to determine which skill is active and forward the user's message to the correct skill.
• If no skill is active, the root bot needs to determine which skill to start, if any, based on bot state and the user's input.
• If you want to allow the user to switch between multiple concurrent skills, the root bot needs to determine which of the active skills the user is intending to interact with before forwarding the user's message.

To use a delivery mode of expect replies

To use the expect replies delivery mode:

• Clone the activity from the turn context.
• Set the delivery mode property of the new activity to "ExpectReplies" before sending the activity from root bot to skill.
• Read expected replies from the invoke response body returned from the request response.
• Process each activity, either within the root bot or by sending it on to the channel that initiated the original request.

Expect replies can be useful in situations in which the bot that replies to an activity needs to be the same instance of the bot that received the activity.