Use a classic chatbot as a skill in a Bot Framework bot

When you use a classic chatbot as a skill with a Bot Framework bot, the Bot Framework bot determines if anything the user says matches the classic chatbot's trigger phrases. If there's a match, the Bot Framework bot passes the conversation to the classic chatbot. The classic chatbot extracts any entities and triggers the matching topic.

You can also pass a variable to a Copilot Studio skill topic as an input from Bot Framework Composer and use the outputs it returns.

To set up your classic chatbot as a skill:

1. Add the Bot Framework bot to the allowlist for the classic chatbot.

2. Download the skill manifest for the classic chatbot.

3. Use the downloaded skill manifest in Bot Framework Composer to create a connection between the bots.

4. Use the Bot Framework Emulator to confirm the bot works as a skill.

Prerequisites

• Understand how Bot Framework skills work.
• Understand how to use Bot Framework Composer.
• Understand how to use skills in Bot Framework Composer.
• Get your Bot Framework bot's app ID.

Add your Bot Framework bot to the allowlist for your classic chatbot

Add the Bot Framework bot's app ID to the allowlist for the classic chatbot that you want to use as a skill. The bots must be in the same tenant.

1. In Bot Framework Composer, open the bot that will use the skill. Select Configure, and then select Development resources. Copy the ID in Microsoft App ID.

2. In Copilot Studio, open the classic chatbot you want to use as a skill.

3. In the navigation menu, go to Settings and select Security. Then select Allowlist.

4. Select Add allowed caller.

5. Paste your Bot Framework bot's app ID and select Next.

   Caution

   A classic chatbot can't act as a skill for other classic chatbots. If you try to add an app ID that belongs to a Power Virtual Agent bot to the allowlist, you get an error. You can only add an app ID for a Bot Framework bot.

   Copilot Studio validates the Bot Framework bot's app ID and confirms that it belongs to a bot in the same tenant.

6. (Optional) Add a Display name for the bot you added to the allowlist.

7. Select Save.

The Bot Framework bot appears by its display name if you entered one, or by its app ID if you didn't enter a display name. To delete or edit it at any time, select the icon to the right of the bot's display name or app ID.

Download the classic chatbot skill manifest for your classic chatbot

Bot Framework bots can use a Copilot Studio skill manifest to configure a connection to the classic chatbot that produced the manifest.

All classic chatbots have skill manifests. A skill manifest is a JSON file that includes the skill's name, interface, and trigger phrases.

A Bot Framework bot can use a skill manifest to know when to trigger the classic chatbot (for example, in response to something a user says to it).

Copilot Studio skill manifests follow version 2.2 of the Bot Framework skill manifest schema and consist of intents.lu and manifest.json files.

A Bot Framework bot might decide that a classic chatbot should handle the user's request, based on the manifest data. It passes to the classic chatbot everything the user said. Then, the classic chatbot matches what the user said to a Copilot Studio topic, extracts any entities that are needed for slot filling, and triggers the Copilot Studio topic.

Copilot Studio skill manifests are automatically generated and updated. A classic chatbot has two skill manifests:

• Test manifest: Allows the Bot Framework bot to connect to the test version of your classic chatbot. Use the test manifest to validate changes to your skill before you publish it.

  • The test manifest is immediately available for every newly created classic chatbot.
  • It's automatically updated to reflect changes every time you save your classic chatbot.

• Published manifest: Allows the Bot Framework bot to connect to the published version of your classic chatbot.

  • The published manifest is only available for classic chatbots that were published at least once.
  • It's automatically updated to reflect changes every time you publish your agent.

Both skill manifests are shown on the Manage allowlist panel.

The skill manifests are also shown on the copilot's Details page. In the navigation menu, select Settings, and then select Details. The Details page shows other metadata, including Environment ID, Tenant ID, and Bot app ID.

To download a manifest, select it. It downloads as a .zip file labeled _<bot name>manifest for the Published manifest, or <bot name>test__manifest for the Test manifest.

Connect to a Copilot Studio skill in Composer

Use Copilot Studio skill manifests to create a skill connection in your Bot Framework bot in Composer.

1. In a Bot Framework Composer project, select Add, and then select Connect to a skill.

2. Browse to and select a Copilot Studio manifest .zip archive, and then select Next.

3. Select the topics, or intents, in your classic chatbot that you want to add to your Bot Framework bot, and then select Next.

4. Review and edit the trigger phrases for your classic chatbot, and then select Next.

5. Make sure Use Orchestrator for multi-bot projects is selected, and then select Continue.

6. Verify that the Copilot Studio skill is added to your Bot Framework bot correctly, and that a new trigger with your classic chatbot's name appears in the project in Composer.

Locate the topic in the skill manifest

Use an event to trigger a Copilot Studio topic in the skill. To call a specific topic from Composer, refer to the topic by the name of the associated event in the skill manifest.

1. Select the Connect to a skill action.

2. Under Skill Dialog Name, select Show skill manifest.

3. Find activities in the manifest. This property contains nested properties that represent the topics available in your classic chatbot.

4. Find the topic you want to call and look for its name property. When the Copilot Studio skill receives an event with this name, it triggers the topic.

   In this example, the event activity name is dispatchTo_new_topic_87609dabd86049f7bc6507c6f7263aba_33d.

Call a Copilot Studio skill topic

Instead of relying on what a user says to trigger a Copilot Studio skill topic, you can call it directly. You can only directly call Copilot Studio topics that are listed in the skill manifest.

1. In the Composer authoring canvas, select Add, then select Access external resources, and then select Connect to a skill.

2. In the Skill Dialog Name list, select your classic chatbot.

3. Find the event activity's name for the classic chatbot topic that you want to call. Copy the value, omitting the quotation marks, and save it to use in the next steps.

4. Select Close.

5. In the Activity section, select Show code.

6. Type or paste the following code. Replace TOPIC_ACTIVITY_NAME with your topic's event activity name. Make sure there are no quotation marks in the name property.

   [Activity
       type = event
       name = TOPIC_ACTIVITY_NAME
   ]
   

Pass an input variable to a Copilot Studio skill topic

Bot Framework Composer can pass a variable to a Copilot Studio skill topic as an input. To learn how to create Copilot Studio topics that accept input variables, see Work with variables.

If a Copilot Studio topic that can receive an input variable is listed in your skill manifest, you can pass a Composer variable to it.

1. In the Composer authoring canvas, select Add, then select Access external resources, and then select Connect to a skill.

2. In the Skill Dialog Name list, select your classic chatbot.

3. Find the event activity's name for the classic chatbot topic that you want to call. Copy the value, omitting the quotation marks, and save it to use in the next steps.

4. Find the topic's value property. The value property contains a $ref property. Copy that value and save it to use in the next step.

   Warning

   If a Copilot Studio topic doesn't have inputs, it won't have a value property.

5. Find the definitions property, then look for a nested property that matches the $ref value you found in the previous step. Note the names and types of the Copilot Studio topic's inputs. You'll use them in the next steps.

6. Select Close.

7. Under the Activity section, select Show code.

8. Type or paste the following code. Replace these values:

   1. Replace TOPIC_ACTIVITY_NAME with your topic's event activity name.
   2. Replace PVA_INPUT_VARIABLE with an input variable from your topic.
   3. Replace COMPOSER_INPUT_VARIABLE with a Composer variable that will provide a value.

   [Activity
       Type = event
       Name = TOPIC_ACTIVITY_NAME
       Value = ${addProperty(json("{}"), 'PVA_INPUT_VARIABLE', COMPOSER_INPUT_VARIABLE)}
   ]
   

   In this example, the Composer variable dialog.storeLocation provides a value to the input variable pva_StoreLocation in the classic chatbot topic dispatchTo_new_topic_127cdcdbbb4a480ea113c5101f309089_21a34f16.

Receive an output variable from a Copilot Studio skill topic

It's possible to receive outputs from a Copilot Studio skill topic in Composer. To learn how to create Copilot Studio topics that return outputs, see Work with variables.

1. In the Composer authoring canvas, select Add, then select Access external resources, and then select Connect to a skill.

2. In the Skill Dialog Name list, select your classic chatbot.

3. Find the event activity's name for your classic chatbot topic you want to call. Copy the value, omitting the quotation marks, and save it to use in the next steps.

4. Find the topic's resultValue property. The resultValue property contains a $ref property. Copy that value and save it to use in the next step.

   Warning

   If a Copilot Studio topic doesn't have outputs, it won't have a resultValue property.

5. Find the definitions property, then look for a nested property that matches the $ref value you found in the previous step. Note the names and types of the Copilot Studio topic's output variables. You'll use them in the next steps.

   In this example, the Copilot Studio topic returns two outputs of type String, pva_State and pva_Item.

6. Select Close.

7. In the Activity section, select Show code.

8. Type or paste the following code. Replace TOPIC_ACTIVITY_NAME with your topic's event activity name. Make sure there are no quotation marks in the name property.

   [Activity
       type = event
       name = TOPIC_ACTIVITY_NAME
   ]
   

9. Under the code area, set Property to a Composer variable to receive and store the output values from the Copilot Studio skill topic.

10. In the Composer authoring canvas, select Add, then select Manage properties, and then select Set properties.

11. Set Property to the Composer value that should store the extracted value. Then set Value to the Composer variable you stored the topic's outputs in.

    In this example, the output values from dialog.skillResult.pvaState and dialog.skillResult.pvaItem are extracted into new Composer variables dialog.State and dialog.Item.

Test your classic chatbot as a skill with a Bot Framework bot

Use the Bot Framework Emulator to test that your Bot Framework bot is properly calling a classic chatbot as a skill.

Update a multitenant Bot Framework bot to a single-tenant bot

The following illustration shows the scenario where a Bot Framework bot built on the Bot Framework SDK is calling a classic chatbot, to use it as a skill.

Both the Bot Framework bot and the classic chatbot have a Microsoft Entra ID app registration, which is referenced by the Azure Bot instances. These Microsoft Entra ID app registrations were created as multitenant. The Bot Framework bot requests a token from the Bot Framework tenant, and uses this token to authenticate to Copilot Studio using Azure Bot Service. Copilot Studio uses the same mechanism to contact the Bot Framework bot.

The Copilot Studio chatbot's application registration is now created as a single-tenant, so this communication no longer works. Microsoft Entra ID refuses to create tokens for single-tenant application registrations that aren't in the same tenant.

Additionally, Copilot Studio validates the incoming token and rejects requests from tenants it doesn't expect, such as the tenant ID in which the classic chatbot's application registration was created.

To resolve this issue, there are two possible fixes.

Classic chatbots in the same tenant as the Bot Framework bot

In scenarios where the Copilot Studio chatbot is already deployed in the same tenant as the Bot Framework bot and is only used by this bot, update the bot to a single-tenant configuration, then redeploy your Bot Framework bot. For more information on how to configure a Bot Framework bot for single-tenant, see Provision and publish a bot.

Copilot Studio chatbot that can't be updated to single-tenant

In scenarios where the Copilot Studio chatbot is already deployed in the same tenant as the Bot Framework bot, but the bot can't be updated so single-tenant, you need to update the code in the Bot Framework bot to create the token to communicate with the Copilot Studio chatbot. The token needs to be created for the tenant in which the Copilot Studio chatbot was also created. In addition, the response must be accepted, which probably requires that you follow the steps in Convert an existing skill from multitenant to single-tenant.

Learn More

• Skills overview
• Skills manifest
• Bot Framework Composer documentation
• Skills in Composer
• Connect to a remote skill in Composer
• Test a skill in Emulator