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

Note

This article includes information applicable to Copilot Studio classic chatbots only. This feature is not available in the new Copilot Studio experience.

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.

Important

You must have a trial or full Copilot Studio license to use classic chatbots as skills. This capability isn't available with the Teams Copilot Studio license.

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'll 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've added to the allowlist.

7. Select Save.

The Bot Framework bot is shown 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.

Note

Bot Framework bots added to the allowlist aren't exported as part of the bot content.

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. These are JSON files that include a 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 may decide at 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 have been published at least once.
  • It's automatically updated to reflect changes every time you publish your agent.

Note

The Published manifest isn't available for classic chatbots that have never been published.

To generate your bot's Published manifest, publish your classic chatbot.

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.

Note

The skill manifest doesn't include system topics and Composer dialogs that are added to a classic chatbot. Only topics that were created by copilot authors and Composer intent triggers that authors add to the bot are included.

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.

Important

Your Bot Framework bot must be added to the classic chatbot's allowlist for the skill connection to work.

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