Use a Power Virtual Agents bot as a skill

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

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

Important

You must have a trial or full Power Virtual Agents license to use Power Virtual Agents bots as skills. This capability isn't available with the Teams Power Virtual Agents license.

To set up your Power Virtual Agents bot as a skill:

  1. Add the Bot Framework bot to the allowlist for the Power Virtual Agents bot.
  2. Download the skill manifest for the Power Virtual Agents bot.
  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

Add your Bot Framework bot to the allowlist for your Power Virtual Agents bot

Add the Bot Framework bot's app ID to the allowlist for the Power Virtual Agents bot 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.

    Screenshot highlighting where to find a Bot Framework bot's app ID.

  2. In Power Virtual Agents, open the bot you want to use as a skill.

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

    Screenshot highlighting the Allowlist tile on the Security page.

  4. Select Add allowed caller.

    Screenshot highlighting the Add allowed caller button at the top of the Manage allowlist panel.

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

    Screenshot highlighting where to enter the Bot Framework bot's app ID.

    Caution

    A Power Virtual Agents bot can't act as a skill for other Power Virtual Agents bots. 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.

    Power Virtual Agents 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.

    Screenshot showing where to add a display name for the bot on 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.

Screenshot of the Manage allowlist panel showing the edit and delete icons for an allowed bot.

Note

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

Download the bot skill manifest for your Power Virtual Agents bot

Bot Framework bots can use a Power Virtual Agents skill manifest to configure a connection to the bot that produced the manifest.

All Power Virtual Agents bots 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 Power Virtual Agents bot (for example, in response to something a user says to it).

Power Virtual Agents 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 a Power Virtual Agents bot should handle the user's request, based on the manifest data. It passes to the bot everything the user said. Then, the Power Virtual Agents bot matches what the user said to a Power Virtual Agents topic, extracts any entities that are needed for slot-filling, and triggers the Power Virtual Agents topic.

Power Virtual Agents skill manifests are automatically generated and updated. A Power Virtual Agents bot has two skill manifests:

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

    • The test manifest is immediately available for every newly created Power Virtual Agents bot.
    • It's automatically updated to reflect changes every time you save your bot.
  • Published manifest: Allows the Bot Framework bot to connect to the published version of your Power Virtual Agents bot.

    • The published manifest is only available for Power Virtual Agents bots that have been published at least once.
    • It's automatically updated to reflect changes every time you publish your bot.

Note

The Published manifest isn't available for Power Virtual Agents bots that have never been published.

To generate your bot's Published manifest, publish your Power Virtual Agents bot.

Both skill manifests are shown on the Manage allowlist panel.

Screenshot of the Manage allowlist panel showing the Power Virtual Agents bot manifests.

The skill manifests are also shown on the bot'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.

Screenshot of the Details page highlighting where to download the Power Virtual Agents bot manifests.

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.

Screenshot showing the two Power Virtual Agents manifests after they've been downloaded.

Note

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

Connect to a Power Virtual Agents skill in Composer

Use Power Virtual Agents 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.

    Screenshot of Bot Framework Composer showing how to connect a Bot Framework bot to a skill.

  2. Browse to and select a Power Virtual Agents manifest .zip archive, and then select Next.

    Screenshot of Composer showing where to select a Power Virtual Agents skill zipped archive.

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

    Screenshot of Composer showing the selection of Power Virtual Agents topics.

  4. Review and edit the trigger phrases for your Power Virtual Agents bot, and then select Next.

    Screenshot of Composer showing where to edit trigger phrases for selected topics.

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

    Screenshot of Composer showing Orchestrator turned on.

  6. Verify that the Power Virtual Agents skill is added to your Bot Framework bot correctly, and that a new trigger with your Power Virtual Agents bot's name appears in the project in Composer.

    Screenshot of Composer after the Power Virtual Agents skill has been added.

Locate the topic in the skill manifest

Use an event to trigger a Power Virtual Agents 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.

    Screenshot of Composer highlighting where to show the skill manifest.

  3. Find activities in the manifest. This property contains nested properties that represent the topics available in your Power Virtual Agents bot.

    Screenshot of a skill manifest highlighting the activities property.

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

    In the following example, the event activity name is dispatchTo_new_topic_87609dabd86049f7bc6507c6f7263aba_33d.

    Screenshot highlighting the Power Virtual Agents topic name in the manifest.

Call a Power Virtual Agents skill topic

Instead of relying on what a user says to trigger a Power Virtual Agents skill topic, you can call it directly. You can only directly call Power Virtual Agents 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.

    Screenshot of Composer highlighting how to connect to a skill.

  2. In the Skill Dialog Name list, select your Power Virtual Agents bot.

    Screenshot highlighting where to select your Power Virtual Agents bot.

  3. Find the event activity's name for the Power Virtual Agents bot 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.

    Screenshot highlighting where to 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
    ]
    

    Screenshot highlighting where to add the Activity event code with the Power Virtual Agents topic name.

Pass an input variable to a Power Virtual Agents skill topic

Bot Framework Composer can pass a variable to a Power Virtual Agents skill topic as an input. To learn how to create Power Virtual Agents topics that accept input variables, see Passing variables between topics.

If a Power Virtual Agents 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.

    Screenshot of Composer highlighting how to connect to a skill.

  2. In the Skill Dialog Name list, select your Power Virtual Agents bot.

    Screenshot highlighting where to select your Power Virtual Agents bot.

  3. Find the event activity's name for the Power Virtual Agents bot 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 Power Virtual Agents topic doesn't have inputs, it won't have a value property.

    Screenshot of a skill manifest highlighting the 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 Power Virtual Agents topic's inputs. You'll use them in the next steps.

    Screenshot of a skill manifest highlighting where to find input variables for a Power Virtual Agents topic.

  6. Select Close.

  7. Under the Activity section, select Show code.

    Screenshot highlighting where to 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 the following the example, the Composer variable dialog.storeLocation provides a value to the input variable pva_StoreLocation in the Power Virtual Agents bot topic dispatchTo_new_topic_127cdcdbbb4a480ea113c5101f309089_21a34f16.

    Screenshot highlighting where to add the Activity event code with a Power Virtual Agents input value.

Receive an output variable from a Power Virtual Agents skill topic

It's possible to receive outputs from a Power Virtual Agents skill topic in Composer. To learn how to create Power Virtual Agents topics that return outputs, see Passing variables between topics.

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

    Screenshot of Composer highlighting how to connect to a skill.

  2. In the Skill Dialog Name list, select your Power Virtual Agents bot.

    Screenshot highlighting where to select your Power Virtual Agents bot.

  3. Find the event activity's name for your Power Virtual Agents bot 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 Power Virtual Agents topic doesn't have outputs, it won't have a resultValue property.

    Screenshot of a skill manifest highlighting the resultValue property for a Power Virtual Agents topic.

  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 Power Virtual Agents topic's output variables. You'll use them in the next steps.

    In the following example, the Power Virtual Agents topic returns two outputs of type String, pva_State and pva_Item.

    Screenshot of a skill manifest highlighting where to find output variables for a Power Virtual Agents topic.

  6. Select Close.

  7. In the Activity section, select Show code.

    Screenshot highlighting where to 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
    ]
    

    Screenshot highlighting where to add the Activity event code with a Power Virtual Agents topic name.

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

    Screenshot highlighting where to set the Property field to dialog.skillResult.

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

    Screenshot highlighting where to 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 the following example, the output values from dialog.skillResult.pvaState and dialog.skillResult.pvaItem are extracted into new Composer variables dialog.State and dialog.Item.

    Screenshot highlighting the output values saved into dialog.State and dialog.Item in the Composer Set properties window.

Test your Power Virtual Agents bot as a skill with a Bot Framework bot

Use the Bot Framework Emulator to test that your Bot Framework bot is properly calling a Power Virtual Agents bot as a skill.

Important

Your Bot Framework bot must be added to the Power Virtual Agents bot's allowlist for the skill connection to work.

Learn More