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.


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.


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

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.

    Use **More options** > **Remove this skill from project** menu item to remove the local skill.

  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.

    Add menu for connecting to an existing remote 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.

    Entry in the root bot project for the added remote skill.

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.

Test your root bot in the Emulator

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

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, then you would change http://localhost:3980/api/skills to

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.

    Example interaction with the local root bot accessing the remote skill.

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.