About skill consumers

  • Article

APPLIES TO: SDK v4

A skill consumer is a bot that can call one or more skills. With respect to skills, a root bot is a user-facing bot that is also a skill consumer.

From the user's perspective, the root bot is the bot they're interacting with. From the skill's perspective, the skill consumer is the channel over which it communicates with the user. (For more information, see the skills overview.)

As a skill consumer, a root bot includes some additional logic to manage traffic between it and a skill:

  • Configuration information for each skill the root uses.
  • A conversation ID factory that allows the root to switch back and forth between the conversation it's having with the user and the one it's having with a skill.
  • A skill client that can package and forward activities to a skill bot.
  • A skill handler that can receive requests and unpack activities from a skill bot.

Managing skills

Starting and letting a single skill run to completion is managed with a few additions to the skill consumer. More complex scenarios are possible, with multiple skills or conversation threads.

A skill consumer implements at least two HTTP endpoints:

  • A messaging endpoint receives activities from the user or channel. This is the usual messaging endpoint that all bots implement.
  • A skill host endpoint for receiving activities from a skill. This acts as a callback URL, the service URL to which the skill replies. (The skill consumer needs to pair code that receives the HTTP method request from the skill with a skill handler.)

Skill descriptions

For each skill, add a Bot Framework skill object to the skill consumer's configuration file. Each one will have an ID, an app ID, and an endpoint for the skill.

Property Description
ID The ID or key of the skill, specific to the skill consumer.
App ID The appId assigned to the bot resource when the skill was registered on Azure.
Skill endpoint The messaging endpoint for the skill. This is the URL the consumer will use to communicate with the skill.

Skill client and skill handler

The skill consumer uses a skill client to send activities to a skill. The client:

  • Takes an activity to send to the skill, either from a user or generated by the consumer.
  • Sets the service URL on the activity sent to the skill to the consumer's skill host endpoint.
  • Replaces the original conversation reference with one for the consumer-skill conversation.
  • Adds a bot-to-bot authentication token.
  • Sends the updated activity to the skill.

The skill consumer uses a skill handler to receive activities from a skill. The handler:

  • Handles the channel service REST API methods.
  • Enforces authentication and claims validation.
  • Retrieves the original conversation reference.
  • Generates an activity for the consumer's adapter. This activity will either signal that the skill has completed or be an activity to forward to the user.

Manage a skill directly

You need to add logic to your skill consumer to track any active skills. It's up to the consumer as to how it manages skills in general, whether it can maintain multiple active skills in parallel or not, and so on. Specific scenarios to consider include:

  • Initiating a new consumer-skill conversation. (This will be associated with a specific consumer-user conversation.)
    • To pass parameters to a skill, set the value property in the initial activity to the skill.
  • Continuing an existing consumer-skill conversation.
  • Recognizing an endOfConversation activity from the skill as signalling an end of a consumer-skill conversation.
    • To retrieve any return value from a skill, check the activity's value property.
    • To check why the skill is ending, check the activity's code parameter, which could indicate that the skill encountered an error.
  • Cancelling a skill from the consumer by sending an endOfConversation activity to the skill.

See how to implement a skill consumer for a consumer that manages a skill directly.

Manage a skill using a skill dialog

If you're using the dialogs library, you can use a skill dialog to manage a skill. While the skill dialog is the active dialog, it will forward activities to the associated skill.

  • When you create the skill dialog, use the dialog options parameter to provide all the information the dialog needs to manage the skill, such as the consumer's app ID and callback URL, the conversation ID factory to use, the skill's properties, and so on.
    • If you want to manage more than one skill as a dialog, you'll need to create a separate skill dialog for each skill.
    • Often, you'll add the skill dialog to a component dialog.
  • To start the skill dialog, use the dialog context's begin method and provide the skill dialog's ID. Use the options parameter to provide the activity the consumer will send as the first activity to the skill.
  • You can cancel or interrupt the skill dialog as you would any other dialog. See how to handle user interruptions for an example.

See how to use a dialog to consume a skill for a consumer that uses a dialog to manage a skill.

Using a delivery mode of expect replies

Bots and skills use industry-standard REST and JSON over HTTPS for communication. Normal activity processing flow starts when the root bot receives a post from a channel at the its messaging endpoint. The root bot then sends the activity on to the skill for processing. Replies from the skill are posted back to the root bot's skill host endpoint, not the its messaging endpoint. Finally, the replies are processed further or posted back to the channel by the root bot. This normal flow can be altered by changing the delivery mode of the activity sent to the skill. If delivery mode is set to "ExpectReplies", the skill won't post back to the skill host endpoint. Instead, all reply activities are serialized into the body of the response. The root bot then iterates over these activities, processing them similar to how they would have been processed by the skill host endpoint.

For information, see the Delivery mode in the Activity specification.