Aura – skill

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for skills development

Description of processes and tools for the development of skills to be subsequently connected to Aura

Introduction

The process for the development of a skill that will be subsequently connected to Aura is different, depending on the type of skill.

In Phase 1, OBs are able to develop skills outside Aura cluster:

Using a technology compatible with Microsoft Bot Framework (Direct Line protocol), for example, with Microsoft composer.
Third-party bots, defined as bots that are not part of the Microsoft ecosystem. The development of external bots with different technologies for their subsequent integration into Aura includes two main stages that must be carried out by constructors:
- The bot development itself, with the preferred technology (Google Assistant, Teneo, etc).
- The development of a third-party adapter, required for the bot to communicate with Aura Root. This adapter must be able to convert requests to be sent to the external bot, and the other way around with answers.

In this framework, there is an available tool that eases the development and subsequent testing of the skill: aura minigroot. The already existing aura minibot works now jointly with aura minigroot.

Access MiniGroot skill connection and Aura Minibot user guide

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura development architecture

Description of the Aura Virtual Assistant development architecture, its operation and main components

Introduction

A bot is an application, particularly an HTTP server, that allows interaction with users in a conversational way. Different means of interaction are available, such as text, cards with images, video or audio and speech.

Users interact with the bot through a given channel, that is the final application used directly by the users. For instance, the bot can be accessible from Facebook, WhatsApp or from any private application, such as My O2 or Mi Movistar. Every message exchanged between the user and the bot is called an activity.

In Aura distributed architecture, the user interacts directly with the root bot, here named aura-groot, and the root bot delegates some of its conversational logic to the skill aura-bot.

Skills and root bot communicate over HTTP using the Bot Framework protocol.

Both aura-bot and aura-groot are separate bots and are published independently.

Main technical components

The key Aura technical components that executes all the functionalities of Aura Virtual Assistant are defined below.

Take into account the mapping between the functional architecture with development architecture:

aura-groot
aura-groot is the main component in charge of handling the assistant. It is responsible for the communication between each channel and its corresponding skill, keeping track of all the communication process, but introducing a minimal interference on it.

Access detailed technical documentation regarding aura-groot component
aura-bot
aura-bot is a skill based on Microsoft Bot Framework that constitutes Aura’s neuronal network. It handles the requests received from aura-groot and interacts with every Aura system or component in order to provide Aura users with the intended answer or requested service.

Access detailed technical documentation regarding aura-bot component

Operational flow

The main stages in tasks in Aura Virtual Assistant conversational process are described below and shown in the following flowchart.

aura-groot adapter receives activities from the user and forwards them to the aura-groot activity handler. (Activities from the user are received at the aura-groot messaging endpoint.)
The aura-groot uses a skill HTTP client to send an activity to the skill. The client gets the consumer-skill conversation information from a skill definition and a skill conversation ID factory. This includes the service URL that the skill will use to reply to the activity.
The aura-bot adapter receives activities from aura-groot and forwards them to the skill’s activity handler. (Activities from the consumer are received at the skill bot’s messaging endpoint).
When aura-bot responds, the aura-groots skill handler receives the activity. It gets the root-user conversation information from the skill conversation ID factory. It then forwards the activity to the aura-groot’s adapter. (Activities from the skill are received at the aura-groot’s skill host endpoint).
The aura-groot adapter sends messages from the skill to the user.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for the connection of a skill to Aura Root

Detailed process for the connection of a skill to Aura Root

Introduction

The process for the connection of a skill to Aura Root is common for the three types of skills defined before.

⚠️ It is only important to take into account that, for third-party bots, constructors must previously develop a third-party adapter to communicate the bot with Aura Root (that is, to make it compatible with Microsoft Bot Framework protocol). After doing that, the connection of the bot with Aura Root follows the same common steps as for other types of skills.

Prerequisites

The following previous tasks are required for the further connection of a skill with Aura Root:

We have a skill already developed and published
There is a channel routed by Aura Root to this skill

1. Register a skill in Aura

In order to activate a skill in Aura, make a POST request to the skills module of aura-configuration-api through the corresponding swagger.

https://<environment>.auracognitive.com/aura-services/v2/configuration/skills

The fields in the request are shown below:

id: Unique identifier of the skill. It can be generated with UUID Generator Tool by OB operator.
name: name of the skill by OB operator.
channels: array of strings including the name of the channel(s) associated with the skill.
appId: Microsoft appId
skillEndpoint: endpoint where the skill is published
external: Boolean value indicating if the skill is deployed in the same environment as aura-groot or not.
- If true, the skill is deployed in a different environment.
- If false or this parameter is not existing, then the skill is deployed in the same environment.

ℹ️ NOTE: Both the id and the name of the skill must be assigned by the OB operator, and they must ensure that they are unique in order to avoid collisions.

Check the following example of a request body:

{
    "id": "544bf5c0-9f31-45e3-9f08-89230315e520",
    "name": "skill-name",
    "channels": [
        "channel-name"
    ],
    "appId": "ms-azure-app-id",
    "skillEndpoint": "http://url-to-skill-bot/api/messages",
    "external": true //Only present if the skill is not in the same environment of Aura Groot
}

2. Make changes available in Aura Groot

In order to update Aura Groot configuration with the modifications carried out, at this stage it is required to restart this component. Depending on the enviroment, there are two possible scenarios.

2.1. Connect to skill in a local environment

In these cases, it only will be neccessary to restart aura-groot component in local enviroment to connect to new skill. The instance can be started using the following command for running aura-groot in local environment: npm start

2.2. Connect to skill in a production environment

In Aura production environments, it will not be necessary to restart the component to update the skills configuration. This connection is done automatically through the config-watcher.

The config-watcher runs periodically (every 5 minutes) and, when it detects that the configuration has been modified in aura-configuration-api, it will automatically restart the pods.

Alternative: Use the /refresh endpoint

⚠️ Use this manual process only if you cannot wait for the automatic execution of the config-watcher

In order to connect the skill in production environment in a manual way (only in the above-mentioned scenario), the /refresh endpoint of aura-groot allows the update of the new configuration without restarting the component.

Two different scenarios can arise here:

Update all configuration parameters

Make a port-forward to both aura-groot pods (one request per pod)

kubectl port-forward aura-groot-#### -n <namespace> 8080:8080

The request to the endpoint with post-forward is shown below:

curl --location --request POST 'localhost:8080/refresh'

Update ONLY skills/channels information

If we only want to update skills and/or channels information, send the parameters in the message body:

    curl --location --request POST 'localhost:8080/refresh' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "changes": ["skills", "channels"] // use "skills" and/or "channels" or neither of them
    }'

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for the connection of a skill to Aura Minigroot

Detailed process for the connection of a skill to Aura Minigroot

Introduction

After the development of a skill, it can be tested easily using a tool created by Aura Global Team: Aura Minigroot.

⚠️ Aura Minigroot works together with the already existing Aura minibot, in fact constituting a unique tool. Both will be provided as docker images and must be installed jointly.

The following sections show the detailed guidelines for the connection of a skill to Aura Minigroot.

Prerequisites

The following previous tasks are required for the further connection of a skill with Aura Minigroot:

There is a skill already developed and running (in this example the skill will be running in localhost)
Aura minibot is already configured and running. You can follow the steps in Aura Minibot user guide.

1. Configure your new skill

To allow aura-groot to redirect activities to a new skill, configure it in:
/mock-configuration/mocks/mock-files/skills-configuration-mock.json.

In this example, we are going to redirect the channel novum-mytelco (you can use a new channel if you want, but you will have to add it to channels-configuration-mock.json):

To do this, the following steps were taken:

Delete the channel novum-mytelco from the first skill (Aura minibot) channels list and add it to our new skill called aura-bot-ext.
Configure the Microsoft appId of our skill, a new skill id (random uuid) and the skillEndpoint.
To access localhost from a docker container, we use host.docker.internal instead localhost.

NOTE: If you use linux, maybe you should also add extra_hosts: "host.docker.internal:host-gateway" to aura-groot in your docker-compose file.

2. User mock configuration

To access this skill, we are going to use anonymous users.

As Aura Minigroot also mocks anonymous users, we need to update the mock data to redirect the mocked anonymous user to our skill setting his channel to 45494a5b-835a-4fff-a813-b3d2be529dbe (the channelId of novum-mytelco):

With this change, all the users not mocked in authentication-mock.json will be redirected to our new skill.

3. Restart the mini-groot

After these changes, you have to restart your Aura Minigroot container to refresh the configurations.

When the container restarts, you should have your new skill working with Aura Minigroot.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Virtual Assistant development architecture and operation

Documents from this point forward contain low-level technical information regarding Aura Virtual Assistant, aimed at technical profiles.

We highly recommend reading these basic Aura Virtual Assistant documents first to have a clear overview of its foundation, benefits and functional behavior:

Introduction

Aura Virtual Assistant architecture is conceived as a multi-bot system based on Microsoft skills architecture.

In this framework, Aura is divided into isolated modules (skill-based bots) that, currently, are independent domain bots able to provide a specific function or capability in a coordinated and efficient manner.

These self-supported skills work with an orchestrator at the top, responsible for connecting channels with bots and managing the conversational flow with the customer.

Mapping functional architecture with development architecture

As explained before, Aura Virtual Assistant documentation contains both:

Low-level technical documents, aimed at not-technical profiles, that describe the functional behavior of our assistant
High-level technical documents, for highly-skilled technical profiles, that include detailed technical information, system architecture and technical processes

In order to ease comprehension for readers, take as a basis the Aura Virtual Assistant functional flowchart and check the mapping between functional and technical components.

Functional component	Technical component
Channel	Channel
Aura Root	Routing module	aura-groot
Channel adapter	aura-bridge
Skill	Skill

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Message exchange between channels and skills

Guidelines for the exchange of messages that allows the communication between a channel and a skill

Introduction

Once a skill is connected to Aura Root, now it is required to establish a communication between a channel and this skill in order to exchange messages between them.

For this purpose, the communication protocol Aura request-response semantic model v3 must be used both by channels and skills to enable them to speak a language Aura can understand using the Direct Line API in order to make a request from a user through the designated channel and receive back the most suitable response from Aura.

Request model v3

Use the root channelData properties of the Aura request semantic model v3 for message exchange from the channel to the skill through aura-groot.

JSON schema for the Aura request semantic model v3
payload property: In the framework of Aura distributed architecture, the payload property includes a specific field (AuraGrooPayload) that allows sending enriched information from aura-groot to the skill.

Response model v3

Use the root channelData properties of the Aura response semantic model v3 for message exchange from the skill to the channel through aura-groot.

JSON schema for the Aura response semantic model v3
Root attachment properties
skillPayload property: In the framework of Aura distributed architecture, this specific property allows sending enriched information from the skill to aura-groot.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Hot swapping processes in Aura distributed architecture

Guidelines to execute modifications in Aura distributed architecture through a hot swapping process

Introduction

Constructors can add, delete of modify a skill through a hot swapping process, without affecting other skills, through the aura-configuration-api.

Through this process, aura-groot can be modified to route to a new skill or delete from its routing tables other skills if constructors do not want to send requests to them.

Guidelines

Add a new skill

Deploy a new skill in your own deployment site.
Prepare your channel:
- (Optional) If your skill is serving a new channel, add the channel to the aura-configuration-api.
- (Optional) If your skill is serving an already existing channel that is not handled by any skill, nothing is needed.
- (Optional) If your skill is serving an already existing channel that is handled by another skill, delete the channel from the current skill configuration aura-configuration-api, launching a PATCH request.
Prepare the POST request to the aura-configuration-api in order to add the skill.
Send the request to the aura-configuration-api to add the skill.
After the request is processed, aura-groot automatically loads the new skill and starts routing requests to it.

Delete an existing skill

Prepare the DELETE request to the aura-configuration-api to delete the skill.
Send the request to the aura-configuration-api to delete the skill.
After the request is processed, aura-groot automatically removes the deleted skill and no longer routes requests to it.
(Optional) If your skill is serving a dedicated channel that is no longer needed, remove the channel from the aura-configuration-api.
At this point, the skill can be undeployed from your deployment site.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Introduction to skills

The current document includes an overview of Aura skills and general information regarding these components.

Moreover, it includes links to low-level technical documentation for highly-skilled technicians.

Introduction

Skills are bots able to perform a specific function or capability in a coordinated and efficient manner designed to handle particular tasks or provide information on a focused topic.

In Aura Virtual Assistant, skills can communicate with Aura Root.

In Aura Virtual Assistant, skills are bots based on Microsoft skills protocol or can be external bots built with any technology available on the market.

In any case, currently they are domain bots, each of them able to manage a different type of request from the user. Therefore, each skill will contain the use cases corresponding to its domain.

Skills can communicate with Aura Root to receive a user’s request and resolve it, to provide the user with the most accurate answer or service and can be trained (each skill will invoke Aura Cognitive Services) and deployed independently.

Types of skills

Within Aura, there are three different types of skills:

Skills developed over Aura cluster

They are proprietary skills that follow Microsoft Bot Framework Direct Line protocol.

Currently, aura-bot is a skill itself.

Skills developed outside Aura cluster with Microsoft-compatible technologies

These skills are developed outside Aura with a technology compatible with Microsoft Bot Framework (Composer, etc.).

Third-party bots, developed with other technologies

They are bots developed with other technologies different from Microsoft ones (Google Assistant, Teneo, etc.).

They require an adapter for its communication with Aura Root.

These third-party adapters are skills that must be developed by the OBs willing to connect their external bots with Aura Root.

Aura Bot as a skill

In the current phase of development of Aura Virtual Assistant, aura-bot is a skill itself but, in general terms, it behaves the same way as in the previous architecture.

Currently, all the existing use cases are placed in aura-bot skill in order to assure backward compatibility, excepting Germany, that has migrated its use cases to an external bot.

Due to the migration of aura-bot component to a skill, certain components have suffered from modifications to be adapted to it and other ones have moved to aura-groot. For example: aura-bot-adapter now extends the Microsoft Bot Framework class cloudAdapter.

Find comprehensive documentation here: Aura Bot as a skill

Skills technical documentation

Are you a highly-skilled technician?
Do you need low-level technical documentation regarding skills?

Access these documents:

Manage skills

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura configuration API skill module

Skill module description for aura-configuration-api

Introduction

The skill module defines services associated with skills management in aura-configuration-api server.

All these services are defined in the skills namespace (/skills).

Servers definition

By default, the servers defined in the swagger include the base path (for v2): /aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/skills/
aura-services/v2/configuration/skills/{skillId}

Endpoints

Path	Method	Description
/skills/	GET	Get all skills information
/skills/	POST	Add a new skill
/skills/{skillId}	GET	Get skill information using skill id
/skills/{skillId}	PUT	Replace skill information associated to skill id
/skills/{skillId}	PATCH	Update some fields of skill information using skill id
/skills/{skillId}	DELETE	Delete skill information using skill id

You can read the complete documentation of each service in the aura-configuration-api swagger file.

Retrieving information from skills

Retrieving only some fields in skill information

It is possible to get only a specific list of fields for skill information, reducing the amount of data transmitted when necessary, using the includeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/skills?includeFields=name,skillEndpoint' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "aura-bot-skill-1",
        "skillEndpoint": "http://localhost:8081/api/messages"
    },
    {
        "id": "71b626d0-099f-4184-8abb-b035d3aa4b16",
        "name": "aura-bot-skill-2",
        "skillEndpoint": "http://localhost:8082/api/messages"
    }
]

Excluding fields in skills information

It is also possible to exclude skills information fields using the excludeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/skills?excludeFields=skillEndpoint,metadata' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "aura-bot-skill-1",
        "apiId": "45494a5b-835a-4fff-a813-b3d2be529asd",
        "channels": ["whatsapp"]
    },
    {
        "id": "71b626d0-099f-4184-8abb-b035d3aa4b16",
        "name": "aura-bot-skill-2",
        "appId": "71b626d0-099f-4184-8abb-b035d3aa4f45",
        "channels": ["novum"]
    }
]

Database

The complete definition of the data model can be found in skills collection section within the administration module.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Manage skills

The following guidelines include the detailed processes required for working with skills in Aura new distributed architecture (Phase 1)

ℹ️ Before facing these documents, The Aura Platform Team highly recommends reading the basic information regarding Aura distributed architecture to have a clear overview of the functional architecture, its benefits and foundations

Introduction

Aura new architecture is conceived as a multi-bot system, based on Microsoft skills architecture, that works with an orchestrator at the top (Aura Root). Currently, skills are independent domain bots able to manage specific experiences (use cases) of the same type.

In this framework, constructors can develop and integrate into Aura different type of skills, as independent modules:

Skills developed over Aura cluster (Microsoft Bot Framework Direct Line protocol).
Skills developed outside Aura cluster with a technology compatible with Microsoft Bot Framework (Composer, etc.).
Third-party bots, developed with other technologies available on the market. These skills will require an adapter for its communication with Aura Root.

In the phase 1 of the architecture implementation, these are the main tasks that must be executed by constructors in order to make the most of Aura:

Develop a skill
Connect a skill to Aura Root
Connect a skill to Aura Minigroot for testing purposes
Message exchange between channels and skills
Hot swapping processes to add or delete a skill

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura request-response semantic model

This section describes the Aura request-response semantic model, which makes it possible for external software components, application and services to speak a language Aura can understand using the Direct Line API

Aura Virtual Assistant component

Introduction

The Direct Line API provides the connectivity between any external software component, service, channel or application and Aura skills.

Anyhow, having a connection means is typically not enough, as a proper understanding and semantics are needed between the communicating parties regarding the data being intercommunicated. In order to improve the communication of Aura with services or channels being integrated into the Microsoft Azure Bot Service and Bot Framework, two concepts come into play:

Activities
Fixed JSON format. This fixed JSON format includes a JSON property called channelData, which channel developers and integrators can use to encode channel-specific data in JSON format and its corresponding semantics.

In this framework, we introduce the so-called Aura Request - Response Semantic Model. This semantic model makes it possible for external software components, application and services to speak a language Aura can understand using the DirectLine API.

Currently, this semantic model is used both for the communication of channels with aura-groot and for the communication of aura-groot with skills in two Aura communication protocols:

Within the Aura Request - Response Semantic Model, two key properties will be fully described throughout these documents:

The general-purpose channel-specific channelData property is the one used by Aura to define the model. When a message is sent from a channel, part of that message is specific to the channel/service and it allows aura-groot and skills to communicate correctly with it.
The payload property can be used by an external component to facilitate the sharing of information between the channels, aura-groot and the skills in order add extra information associated with the channel and, consequently, enrich the request.

Versioning

Aura supports different versions of the Aura Request - Response Semantic Model.

channelData v1

In older Aura Platform releases, the default version was version 1, so some channels did not send the version of the channelData and aura-bot handled their requests as version 1.0.0.

There is an exception: in release Aerosmith, aura-bot included Living Apps handling as a platform feature.

➡️ Access to channelData v1 documentation

channelData v2

Afterwards, version 2 was created to extend the channelData property with new fields, such as actions and status, that with the regular communications with the channels are not needed or, in the case of the actions, are solved by other ad-hoc means.

In Greenday (6.0.1) release, Aura included a WhatsApp connector, the so-named aura-bridge and also channelData version 2 was used to access and to use the extra features of actions and status.

In these Aura Platform releases until Iron Maiden, aura-bot included a lazy definition of the channelData model, so, in fact, it handled almost a different version per channel.

➡️ Access to channelData v2 documentation

channelData v3

From Iron Maiden (7.2.0) onwards, we introduce the so-called channelData normalized version (version 3), an enriched version of channelData with new fields that provide a complete schema definition. This will enforce all channels to use the very same schema to access aura-groot.

➡️ Access to channelData v3 documentation