Skills

Articolo
10/20/2024

Healthcare agent service enables you to extend your bot using Bot Framework Skills.

A skill is a bot that can perform a set of tasks for another bot. A skill consumer is a bot that can call one or more skills. In this way you can create a single user-facing bot and extend it with one or more skills. The user interacts directly with the skill consumer, and the skill consumer delegates some of its conversational logic to the skill.

Expose healthcare agent service as a Skill

The healthcare agent service allows you to develop your bot and then expose it to be consumed by various other skill consumers. When your healthcare agent service is used as a skill all the back-and-forth messages between a user and the consumer bot are routed to the skill, such that the messages are accounted to the skill’s usage and billing. For this reason only user with Admin access right can expose the healthcare agent service as a skill or modify configurations that affect the allowed consumers bots.

The healthcare agent service can be triggered as a skill using one of the following activities:

Message activity – the skill receives the user's utterance, and using the Language Model concept triggers the relevant scenario logic in response.
Invoke activity – the skill receives the scenario_id to invoke and object of scenario arguments. The skill invokes the specific scenario using the provided arguments. List of supported scenarios and their arguments are available in the skill manifest.

Upon the conversation completing or conversation timeout, the skill sends an endOfConversation activity, so that the skill consumer knows when to stop forwarding activities to the skill.

Open the healthcare agent service Management portal, sign in to your account as an administrator and navigate to Integration >> Skills. Here you should turn on the Expose Skill switch.

$Screen shot of the On\Off switch$
Then populate the details of your skill properties, that will be added to the skill manifest.

Name: Add a name for your skill.
Description: Add a description for your skill (optional).
Publisher Name: Add the name of the skill publisher.

Provide the values and press 'Save'. You can modify these values also later from the Skill Properties section.

Skill Manifest

A skill manifest is a JSON file that describes the actions a skill can perform, its input and output parameters, and the skill's endpoints. The manifest contains the information a developer needs to access the skill from another bot. For more details, see Bot Framework's documentation on How to write a v2.1 skill manifest.

When you expose the healthcare agent service as a skill, a manifest is created describing your skill. healthcare agent service skill supports message actions, that contains the user's utterance, and invoke actions, that contains the scenario ID and arguments. hence the skill manifest contains one message activity and a set of invoke activities as the number of active scenarios the skill has:

    {
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json",
    "$id": <SKILL_ID>,
    "name": <SKILL_NAME>,
    "version": "1.0",
    "description": <SKILL_DESCRIPTION>,
    "publisherName": <PUBLISHER_NAME>,
    "tags": [],
    "endpoints": [
        {
            "name": "default",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for healthcare agent service Skill " + <SKILL_NAME>,
            "endpointUrl": "https://bot-api-us.healthbot.microsoft.com/bot/dynabot/" + <BOT_ID> + "/skill/consume",
            "msAppId": <BOT_MS_APP_ID>
        }
        ],
    "activities":
        {
            "message":
            {
                "type":"message",
                "description":"Receives the user's' utterance and attempts to resolve it using the skill's LU models"
            }
            <SCENARIO_NAME>: {
                "type": "invoke",
                "name": "TriggerScenario",
                "description": <SCENARIO_DESCRIPTION>,
                "value": {
                    "type": "object",
                    "properties": {
                        "scenario_id": {
                            "type": {
                                "enum": [
                                    <SCENARIO_ID>:                             ]
                            },
                            "title": "Scenario ID"
                        },
                        "args": {
                            "type": "object",
                            "title": "Scenario Arguments"
                        }
                    }
                }
            }
        }
    }

You can access the manifest from its provided URL:

Skill manifest

Skill Consumers

Healthcare agent service skill implements access restrictions, such that you can restrict access to the skill to specific skill consumers. Upon exposing your healthcare agent service as a skill the restrict option is enabled by default, such that request from any skill consumer will be rejected. Restrict all skill consumers

To allow request from skill consumer you can choose one of the two options:

Allow access to selected skill consumer, by enabling the restrict switch and adding the skills consumer's MS-App IDs to the allowed consumers list:
Allow access to any skill consumer, by disabling the restrict switch.

Consume Skills

The healthcare agent service enables you to extend your bot using Bot Framework skills - either other Bot Framework skills or healthcare agent service specific skills. You can trigger a skill from within healthcare agent service Scenario Editor using the Invoke Skill scenario element.

To trigger a skill, it must be registered first. Navigate to Integration >> Skills >> Consume skills tab and add a skill under the Registered skills section.

You'll be prompted to provide the skill manifest URL and then press the Fetch skill manifest button which will automatically populate the skill properties. When all done press the Create button.

When navigating to your scenarios, you can now invoke the skill using the Invoke Skill scenario element by selecting it from the Existing skills list:

Invoke existing skill

Invoke Skill element support 4 activity types:

Message – must include the Utterance to send to the skill. Utterance can also receive JavaScript expression in case a scenario variable needs to be used
Invoke – must include the activity Name and Value as specified in the consumed skill manifest. For Example, when invoking a scenario of another healthcare agent service as skill the Name will be TriggerScenario and Value will get an object with scenario_id and args as parameters:
Event - must include the activity Name and Value as specified in the consumed skill manifest.
OtherActivities – must include activity Type that must be one of the other Bot Framework activity types, and other properties if needed: