Connect to a remote skill with Composer

APPLIES TO: Composer v1.x and v2.x

You can build a user-facing bot and extend it by calling conversational logic in a separate skill bot. This article describes how to connect a root bot running locally to an already deployed skill. The local root bot uses an Azure Bot resource and ngrok to provide an endpoint in the cloud that forwards to a local endpoint on your machine.

Your user-facing bot is referred to as either a root bot or a skill consumer. The bot your bot consumes is referred to as a skill bot or skill.

To develop and test a local root bot that accesses a deployed skill:

• The root bot must expose a skills endpoint, distinct from its messaging endpoint.
  • The user's channel sends activities to the root bot's messaging endpoint, and the root bot forwards these to the skill.
  • The skill sends activities to the root bot's skills endpoint, and the root bot forwards the skill's replies to the user.
  • The manually configured skills endpoint is used by your root bot only when it's running locally. When it's running remotely, the skills endpoint connects directly to your deployed bot.
• The deployed skill bot must provide a skill manifest that describes its capabilities.
  • The skill developer can provide the manifest online or as a compressed file.
  • When Composer exports a skill, it creates the skill manifest file and publishes it for you.

If you don't have a skill yet or you're looking for how to create a remote skill with Composer, read the Export a skill article.

Important

Connecting to a skill in Composer is a technical process that involves many steps such as setting up Composer and configuring Azure resources. A high level of technical proficiency is necessary to execute this process.

Prerequisites

• A subscription to Microsoft Azure.
• A remote skill and access to its skill manifest.
• A basic bot built with Composer.
• A good understanding of skills.
• ngrok installed.

Choose a remote skill for your root bot to consume

If you don't yet have a local root bot and a remote skill:

1. Create the root bot or skill bot described in how to Create and test a local skill.
2. Follow how to Publish a skill to Azure to prepare the remote skill.

These two articles describe the root bot and skill used as an example in this article. The bots are named RootBot and EchoSkill, respectively.

Connect to the remote skill

Composer v2.x

Provision resources for your root bot

To access a remote skill, your root bot needs a valid app ID and password. If you've published your root bot before, you can skip this step.

1. Go to the Publish page.
   1. Select the Publishing profile tab.
   2. Select the root bot in the bot list.
   3. Select Add new.
2. On the Create a publishing profile page:
   1. Enter a name for the profile.
   2. Select Publish bot to Azure for the Publishing target.
   3. Then, select Next.
3. Follow the steps to create the resources. For more information, see how to Publish a bot to Azure.
4. When Composer displays a provision success message, your resources are ready.

Configure the root bot

To retrieve the root bot's app ID and password:

1. Go to the Configure page.
2. Select the root bot and select the Development resources tab.
3. Scroll to the bottom of the pane and select Retrieve App ID.
   1. On the Retrieve App ID from publishing profile page, select the profile to use and select Save App ID.
   2. Copy the root bot's app ID for the next step.

Composer will apply these credentials when starting your root locally.

Update the skill's allowed callers list and republish the skill

The remote skill won't allow the root bot to consume it, unless the root bot's app ID is added to the skill's allowed callers list.

If another group maintains the skill, request that they add your bot to the skill's allowed callers list. Then wait for their confirmation before continuing.

Otherwise, follow these steps to update the skill's allowed callers list yourself.

1. Go to the Configure page.
   1. Select the skill bot and select the Skill configuration tab.
   2. Select Add new caller and enter the root bot's app ID.
2. Go to the Publish page.
   1. Select the Publish tab.
   2. Select the skill bot.
   3. Select the skill's publishing profile to use.
   4. Near the top-left of the pane, select Publish selected bots.
   5. On the Publish page, optionally enter a publishing comment, and then select Okay.
   6. Composer re-publishes your skill with the updated information, which can take a few minutes.
   7. Copy the skill manifest URL for the skill bot. The URL is needed when you add the remote skill to the project.

Remove the local skill

To avoid confusion, if your root bot is currently using a local version of your remote skill, remove the local skill from the root bot's project. Composer won't delete any files, and you can continue to maintain and publish the skill from its own project.

1. Go to the Create page and select More options next to the local skill. Then select Remove this skill from project.

   

2. When Composer shows a warning about removing the local skill from the project, select Yes to continue. You'll update your root bot to access the remote version of the skill in the next step.

Add the remote skill

To add the remote version of the skill that you published earlier:

1. Go to the Create page. At the top of the bot explorer, select + Add , then Connect to a skill.

   

2. On the Add a skill page, enter the skill manifest URL for your remote skill and select Next.

   • This URL can be either a remote manifest file or a local copy of the compressed manifests folder for the skill.
   • If you get a Manifest URL can not be accessed error, check whether your skill is published and its manifest URL is entered correctly.
   • If Composer can access the URL, it displays information from the manifest.

3. Select Done to add the remote skill to your root bot.

4. Composer adds an entry for the remote skill to the bot explorer.

   

Update the root bot to reference the remote skill

To update the root bot to access the remote skill:

1. Go to the Create page.
2. Select the trigger in your root bot that contains the Connect to a skill action and select the Connect to a skill action.
   • In this article, this is the echo trigger in the RootBot dialog.
3. In the properties pane for the action:
   1. For Skill Dialog Name, select the remote skill.
   2. For Skill Endpoint, select the endpoint you want to access. If your skill has just one endpoint, the endpoint is selected by default.

Now your root bot will access the remote skill, using the information in the skill's manifest.

Composer v1.x

Create an Azure bot resource

If you don't already have a Bot Channels Registration resource you want to use for your root bot, create one:

1. Open the Azure portal and select + Create a resource on top of the menu.
2. Enter Bot Channels Registration in the search box and select Enter.
3. Select Create from the pop-up window and then fill in the creation form to create your Bot Channels Registration. The registration used in this article has a bot handle of "LocalRootBot".

Get the App ID and password

If you don't already have a record of the Bot Channels Registration resource app ID and secret, record both values. If you don't have a copy of your secret, you'll need to create a new secret.

1. In the Azure portal, go to the Bot Channels Registration for your root bot.

2. Select Configuration in the Settings group from the left pane.

3. The App ID is displayed in the Microsoft App ID (Manage) section.

   

4. To create a new secret, select Manage from Microsoft App ID (Manage). The portal will open a Certificates & secrets pane.

5. Select New client secret. Enter some description in the Description field (this is optional) and select an expiration time from the Expires list. Select Add.

   

6. Copy the value from the Value field of the displayed table. This is the generated password of your Bot Channels Registration.

   

For more information about creating a Bot Channels Registration, refer to the Register a bot with Azure Bot Service article.

Create a root bot in Composer

You can create a new bot or use an existing one to use as a root bot with which to call the skill. After adding the remote skill to your project, you can add an action to your root bot to call the skill. The root bot in this article is named "LocalRootBot".

1. Add the remote skill to your project:

   1. At the top of the Navigation pane, select Add (+), then Connect a remote skill.

      

   2. Enter the URL for the remote skill manifest. Composer will validate the URL and populate the Skill Endpoint list.

   3. Select the skill endpoint the root bot should use to call the remote skill, and then select Confirm. A skill must advertise at least one end point; however, it can expose more. The manifest should describe which features are available for each endpoint.

      

      You'll then see the remote skill added in the Navigation pane.

      

Now the remote skill has been added to your bot project!

Forward replies from the remote skill to your local bot

Use ngrok to create a public URL to use as base URL for the skill endpoint.

The local root bot needs to provide the remote skill with a skill endpoint that the skill can send replies to. This skill endpoint needs to be in the cloud, since the remote skill is.

1. Select Start bot from the toolbar. Once the bot's runtime has started, the Local bot runtime manager opens.

   1. In Local bot runtime manager, hover over Test in Emulator to see the local messaging endpoint for your root bot.

   2. Note the port number that your root bot is using. For example, if the messaging endpoint is http://localhost:3980/api/messages, then the port number is 3980.

      

2. Use ngrok to create a public URL.

   1. Open a terminal and navigate to the folder that contains your ngrok executable file.

      Tip

      If you don't have ngrok installed, follow instructions to install ngrok.

   2. Run ngrok with the following command to create a new tunnel, the port specified is the same port your consumer bot is running on:

      OSX

      ./ngrok http 3984 --host-header=localhost
      

      Windows

      "ngrok.exe" http 3984 --host-header=localhost
      

   3. Save the httpsentry generated by ngrok. You'll use this when you update the root bot configuration settings in Azure. (The public URL expires after a set amount of time, so you may need to regenerate the public URL if you need it for more than an hour.)

      

Connect to the remote skill

1. From the Navigation pane, select the trigger in the root bot that you'll use to call the remote skill.

2. Add the Access external resources > Connect to a skill action to the trigger.

   

3. In the Properties pane on the right side, set the following properties:

   1. For Skill Dialog Name, select the remote skill you want to connect to.

   2. For Skill Endpoint, select the endpoint to call.

      

   3. Set Activity processed to false; this will cause the root bot to forward the user activity for the turn to the skill.

   4. If the skill might return a value, you can provide a memory path to save the value in the action's Property field. For example, you could set Property to dialog.result.

   Tip

   To send a different activity to the skill, set Activity processed to true, and use the Activity field to provide the activity to send to the skill.

Update the root bot configuration

1. Select Project Settings from the Composer menu, then select the consumer bot in the Navigation pane.

2. In the consumer bot's configuration:

   1. In the Skill Host Endpoint field, update and enter the public URL generated by ngrok and add /api/skills to the URL. (See Forward replies from the remote skill to your local bot section for how to use ngrok.) The skill host endpoint should look similar to https://<identifier>.ngrok.io/api/skills, where <identifier> is a unique identifier.

      Important

      Without /api/skills as part of your skill host endpoint, your consumer bot will generate HTTP 500 status codes when trying to connect to your remote skill.

   2. Update the App ID / Password fields with the values from the Bot Channels Registration resource you created in the Get the App ID and password section.

      

3. Still on the Project Settings page, toggle Advanced Settings View (json). Update the allowedCallers property of the skillConfiguration settings.

    "skillConfiguration": {
      "isSkill": true,
      "allowedCallers": []
    },
   

   Property	Description	Type	Example value
   allowedCallers	The msAppIds of all the bots it connects to. Set to "*" to allow all callers.	array	"123-34-456", "234-45-567"

Your local root bot is now configured to connect to the remote skill!

Test your root bot in the Emulator

You can now test your local root bot's ability to connect to the remote skill.

Composer v2.x

With a local root bot and a remote skill, the skill is running in the cloud and your root bot is running on your machine. For the two to communicate, you need to configure a URL for your root bot that the skill can access from the cloud.

Start the local root bot

The first time you start a bot that connects to a remote skill, Composer displays the ngrok command to use to create a forwarding endpoint.

1. Select Start bot to start the root bot.
   • If Composer displays the ngrok command to use. Copy the command for a later step. Then, close the pop-up window.
   • Otherwise, Composer displays the Local bot runtime manager.
     1. Hover over Test in Emulator.
     2. Copy the port number for the root bot. For example, if the messaging endpoint is http://localhost:3980/api/messages, the port number is 3980. You need this to create the forwarding endpoint.

Create a forwarding URL

1. Open a command prompt or terminal.

2. If ngrok isn't in your path, change to the directory that contains ngrok.exe.

3. Run the command you copied from Composer earlier. It should look similar to this, where <port-number> is the port number for your root bot.

   ngrok.exe http <port-number> --host-header=localhost
   

4. ngrok creates a forwarding URL in the cloud that directs to the port on which your local bot is hosted.

5. Copy the https URL from ngrok and leave the command running.

   • The forwarding URL expires when the ngrok session expires or when you end the ngrok process.

Update the skill host endpoint

1. In Composer, go to the Configure page.

2. Select your root bot

3. Select the Skill configuration tab.

4. Under Call skills, change the Skill host endpoint URL to use the forwarding URL as its base, instead of the localhost port.

   For example, if your local port is 3980 and your forwarding URL is https://37bab15eb6e2.ngrok.io, then you would change http://localhost:3980/api/skills to https://37bab15eb6e2.ngrok.io/api/skills.

Your root bot will use this URL to receive responses from the skill bot.

Start the root bot and open it in Emulator

1. Restart your root bot from Composer.

2. From the Local bot runtime manager, select Test in Emulator.

3. Composer opens your root bot in the Bot Framework Emulator.

4. Enter text in the Emulator and see the response.

   

Composer v1.x

1. Select Start bot in the upper-right corner of the screen. This launches the bot's runtime.

   

   Once the bot's runtime has started, the Local bot runtime manager will open.

2. In the Local bot runtime manager window, select Test in Emulator to test the bot-to-bot connection.

3. Enter text in the Emulator and see the response.

   

Additional information

A skill's manifest can include dispatch and language model information. This information describes the intents and questions the skill is designed to respond to. It can also provide language models for multiple locales.

• When you publish your skill, Composer can add dispatch and language model information to the skill's manifest. It uses the language models from the skill bot to do so.
• When you create a bot that consumes a skill, Composer can use the skill's manifest to generate triggers in the root bot to invoke the skill.

For more information, see About skills in Composer and reuse of conversation logic between bots.

Next steps

For information about developing and publishing skills in Composer, see how to Create and test a local skill and Publish a skill to Azure.