Assistant virtuel pour Microsoft teamsVirtual Assistant for Microsoft Teams

Virtual Assistant est un modèle de source ouverte Microsoft qui vous permet de créer une solution de conversation robuste tout en conservant un contrôle total de l’expérience utilisateur, de la personnalisation de l’organisation et des données nécessaires.Virtual Assistant is a Microsoft open-source template that enables you to create a robust conversational solution while maintaining full control of user experience, organizational branding, and necessary data. Le modèle de base de l’assistant virtuel est le bloc de construction de base qui rassemble les technologies Microsoft nécessaires à la création d’un assistant virtuel, notamment le Kit de développement logiciel (SDK) de robot, le mémorandum d’accord de langue (Luis), QnA Maker, ainsi que les fonctionnalités essentielles, notamment l’enregistrement des compétences, les comptes liés, l’intention de conversation de base pour offrir aux utilisateursThe Virtual Assistant core template is the basic building block that brings together the Microsoft technologies required to build a Virtual Assistant, including the Bot Framework SDK, Language Understanding (LUIS), QnA Maker, as well as essential capabilities including skills registration, linked accounts, basic conversational intent to offer end users a range of seamless interactions and experiences. En outre, les fonctionnalités de modèle incluent des exemples enrichis de compétencesde conversation réutilisables.In addition, the template capabilities include rich examples of reusable conversational skills. Les compétences individuelles peuvent être intégrées dans une solution assistant virtuel pour permettre plusieurs scénarios.Individual skills can be integrated in a Virtual Assistant solution to enable multiple scenarios. À l’aide du kit de développement logiciel (SDK) de robot, les compétences sont présentées sous forme de code source, ce qui vous permet de personnaliser et d’étendre les besoins.Using the Bot Framework SDK, Skills are presented in source code form enabling you to customize and extend as required. Voir What is a bot Framework Skills.See What is a Bot Framework Skill.

Diagramme de vue d’ensemble de l’assistant virtuel

Les activités de message texte sont acheminées vers les compétences associées par le noyau de l’assistant virtuel à l’aide d’un modèle de répartition .Text message activities are routed to associated skills by the Virtual Assistant core using a dispatch model.

Considérations relatives à l’implémentationImplementation considerations

La décision d’ajouter un assistant virtuel peut inclure de nombreux déterminants et diffère pour chaque organisation.The decision to add a Virtual Assistant can include many determinants and differ for each organization. Voici les facteurs qui prennent en charge l’implémentation d’un assistant virtuel pour votre organisation :Here are the factors that support implementing a Virtual Assistant for your organization:

  • Une équipe centrale gère toutes les expériences des employés et offre la possibilité de créer une expérience de l’assistant virtuel et de gérer les mises à jour de l’expérience principale, y compris l’ajout de nouvelles compétences.A central team manages all employee experiences and has the capability to build a Virtual Assistant experience and manage updates to the core experience including the addition of new skills.
  • Il existe plusieurs applications pour les fonctions professionnelles et/ou le nombre devrait augmenter à l’avenir.Multiple applications exist across business functions and/or the number is expected to grow in the future.
  • Les applications existantes sont personnalisables, détenues par l’organisation et peuvent être converties en compétences pour un assistant virtuel.Existing applications are customizable, owned by the organization, and can be converted into skills for a Virtual Assistant.
  • L’équipe centrale employés-expériences peut influencer les personnalisations apportées aux applications existantes et fournir les instructions nécessaires pour intégrer les applications existantes en tant que compétences dans l’expérience de l’assistant virtuelThe central employee-experiences team is able to influence customizations to existing apps and provide necessary guidance for integrating existing applications as skills in Virtual Assistant experience

L’équipe centrale gère l’Assistant et les compétences de Team Function Teams.

Créer un assistant virtuel centré sur teamsCreate a Teams-focused Virtual Assistant

Microsoft a publié un modèle Visual Studio pour créer des assistants virtuels et des compétences.Microsoft has published a Visual Studio template for building Virtual Assistants and skills. Avec le modèle Visual Studio, vous pouvez créer un assistant virtuel, alimenté par une expérience basée sur le texte avec prise en charge de cartes riches limitées avec des actions.With the Visual Studio template, you can create a Virtual Assistant, powered by a text-based experience with support for limited rich cards with actions. Nous avons amélioré le modèle de base Visual Studio pour inclure les fonctionnalités de la plateforme Microsoft teams et les expériences de l’application Power Great Teams.We have enhanced the Visual Studio base template to include Microsoft Teams platform capabilities and power great Teams app experiences. Quelques-unes des fonctionnalités incluent la prise en charge de cartes adaptatives riches, de modules de tâches, d’équipes/de conversations de groupes et d’extensions de messagerie.A few of the capabilities include support for rich adaptive cards, task modules, teams/group chats and messaging extensions. Voir aussi Tutorial : étendre votre assistant virtuel à Microsoft teams.See also, Tutorial: Extend Your Virtual Assistant to Microsoft Teams.

Diagramme de haut niveau d’une solution d’assistant virtuel

Ajouter des cartes adaptatives à votre assistant virtuelAdd adaptive cards to your Virtual Assistant

Pour distribuer les demandes correctement, votre assistant virtuel doit identifier le modèle LUIS correct et les compétences correspondantes associées.To dispatch requests properly, your Virtual Assistant needs to identify the correct LUIS model and corresponding skill associated with it. Toutefois, le mécanisme de répartition ne peut pas être utilisé pour les activités d’action de carte étant donné que le modèle LUIS associé à une compétence ne peut pas être formé pour les textes d’action de carte, car il s’agit de mots clés prédéfinis et non d’énoncés d’un utilisateur.However, the dispatching mechanism cannot be used for card action activities since the LUIS model associated with a skill may not be trained for card action texts since these are fixed, pre-defined keywords, not utterances from a user.

Nous avons résolu cela en incorporant des informations sur les compétences dans la charge utile d’action de la carte.We have resolved this by embedding skill information in the card action payload. Toutes les compétences doivent être incorporées skillId dans le value champ des actions de carte.Every skill should embed skillId in the value field of card actions. Il s’agit de la meilleure façon de vous assurer que chaque activité d’action de carte véhicule les informations de compétences pertinentes et que l’assistant virtuel peut utiliser ces informations pour la distribution.This is the best way to ensure that each card action activity carries the relevant skill information and Virtual Assistant can utilize this information for dispatching.

Vous trouverez ci-dessous un exemple de données d’action de carte.Below is a card action data sample. En fournissant skillId dans le constructeur, nous nous assurons que les informations sur les compétences sont toujours présentes dans les actions de carte.By providing skillId in the constructor we ensure that skill information is always present in card actions.

    public class CardActionData
    {
        public CardActionData(string skillId)
        {
            this.SkillId = skillId;
        }

        [JsonProperty("skillId")]
        public string SkillId { get; set; }
    }

    ...
    var button = new CardAction
    {
        Type = ActionTypes.MessageBack,
        Title = "Card action button",
        Text = "card action button text",
        Value = new CardActionData(<SkillId>),
    };

Ensuite, nous introduisons SkillCardActionData la classe dans le modèle de l’assistant virtuel pour extraire skillId de la charge utile de la carte.Next, we introduce SkillCardActionData class in the Virtual Assistant template to extract skillId from the card action payload.

    // Skill Card action data should contain skillId parameter
    // This class is used to deserialize it and get skillId 
    public class SkillCardActionData
    {
        /// <summary>
        /// Gets the ID of the skil that should handle this card
        /// </summary>
        [JsonProperty("skillId")]
        public string SkillId { get; set; }
    }

Vous trouverez ci-dessous un extrait de code pour extraire skillId des données d’action de carte.Below is a code snippet to extract skillId from card action data. Nous l’avons implémentée en tant que méthode d’extension dans la classe Activity .We implemented it as an extension method in the Activity class.

    public static class ActivityExtensions
    {
        // Fetches skillId from CardAction data if present
        public static string GetSkillId(this Activity activity)
        {
            string skillId = string.Empty;

            try
            {
                if (activity.Type.Equals(ActivityTypes.Message) && activity.Value != null)
                {
                    var data = JsonConvert.DeserializeObject<SkillCardActionData>(activity.Value.ToString());
                    skillId = data.SkillId;
                }
                else if (activity.Type.Equals(ActivityTypes.Invoke) && activity.Value != null)
                {
                    var data = JsonConvert.DeserializeObject<SkillCardActionData>(JObject.Parse(activity.Value.ToString()).SelectToken("data").ToString());
                    skillId = data.SkillId;
                }
            }
            catch
            {
                // If not able to retrive skillId, empty skillId should be returned
            }

            return skillId;
        }
    }

Gérer les interruptions de manière appropriéeHandle interruptions gracefully

L’assistant virtuel peut gérer les interruptions lorsqu’un utilisateur tente d’appeler une compétence alors qu’une autre compétence est actuellement active.Virtual Assistant can handle interruptions in cases where a user tries to invoke a skill while another skill is currently active. Nous avons introduit TeamsSkillDialog et TeamsSwitchSkillDialog , en se basant sur les SkillDialog et SwitchSkillDialogde l’infrastructure bot, pour permettre aux utilisateurs de changer une expérience de compétences à partir d’actions de carte.we have introduced TeamsSkillDialog and TeamsSwitchSkillDialog, based on Bot Framework's SkillDialog and SwitchSkillDialog, to enable users to switch a skill experience from card actions. Pour gérer cette demande, l’assistant virtuel invite l’utilisateur à indiquer un message de confirmation pour faire basculer les compétences.To handle this request the Virtual Assistant prompts the user with a confirmation message to switch skills.

Invite de confirmation lors du basculement vers une nouvelle qualification

Gestion des demandes de module de tâcheHandling task module requests

Pour ajouter des fonctionnalités de module de tâches à un assistant virtuel, deux méthodes supplémentaires sont incluses dans le gestionnaire d’activités de l’Assistant Virtual : OnTeamsTaskModuleFetchAsync et OnTeamsTaskModuleSubmitAsync .To add task module capabilities to a Virtual Assistant, two additional methods are included in the Virtual Assistant activity handler: OnTeamsTaskModuleFetchAsync and OnTeamsTaskModuleSubmitAsync. Ces méthodes écoutent les activités liées au module de tâche à partir de l’assistant virtuel, identifient les compétences associées à la demande et transfèrent la demande à la compétence identifiée.These methods listen to task module-related activities from Virtual Assistant, identify the skill associated with the request, and forward the request to the identified skill.

Le transfert des demandes est réalisé via la méthode SkillHttpClient PostActivityAsync .Request forwarding is done via the SkillHttpClient, PostActivityAsync method. Elle renvoie la réponse telle qu’elle InvokeResponse est analysée et convertie en TaskModuleResponse .It returns the response as InvokeResponse which is parsed and converted to TaskModuleResponse .

    public static TaskModuleResponse GetTaskModuleRespose(this InvokeResponse invokeResponse)
    {
        if (invokeResponse.Body != null)
        {
            return new TaskModuleResponse()
            {
                Task = GetTask(invokeResponse.Body),
            };
        }

        return null;
    }

    private static TaskModuleResponseBase GetTask(object invokeResponseBody)
        {
            JObject resposeBody = (JObject)JToken.FromObject(invokeResponseBody);
            var task = resposeBody.GetValue("task");
            var taskType = task.SelectToken("type").ToString();

            return taskType switch
            {
                "continue" => new TaskModuleContinueResponse()
                {
                    Type = taskType,
                    Value = task.SelectToken("value").ToObject<TaskModuleTaskInfo>(),
                },
                "message" => new TaskModuleMessageResponse()
                {
                    Type = taskType,
                    Value = task.SelectToken("value").ToString(),
                },
                _ => null,
            };
        }

Une approche similaire est suivie pour les réponses de module de tâche et de distribution d’action de carte.A similar approach is followed for card action dispatching and task module responses. Les données d’action d’extraction et d’envoi du module tâches sont mises à jour pour inclure skillId .Task module fetch and submit action data is updated to include skillId. GetSkillIdLa méthode d’extension d’activité extrait skillId de la charge utile, qui fournit des détails sur les compétences qui doivent être appelées.Activity Extension method GetSkillId extracts skillId from the payload which provides details about the skill that needs to be invoked.

Vous trouverez ci-dessous un extrait de code pour OnTeamsTaskModuleFetchAsync et des OnTeamsTaskModuleSubmitAsync méthodes.Below is a code snippet for OnTeamsTaskModuleFetchAsync and OnTeamsTaskModuleSubmitAsync methods.

    // Invoked when a "task/fetch" event is received to invoke task module.
    protected override async Task<TaskModuleResponse> OnTeamsTaskModuleFetchAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
    {
        try
        {
            string skillId = (turnContext.Activity as Activity).GetSkillId();
            var skill = _skillsConfig.Skills.Where(s => s.Value.AppId == skillId).First().Value;

            // Forward request to correct skill
            var invokeResponse = await _skillHttpClient.PostActivityAsync(this._appId, skill, _skillsConfig.SkillHostEndpoint, turnContext.Activity as Activity, cancellationToken);

            return invokeResponse.GetTaskModuleRespose();
        }
        catch (Exception exception)
        {
            await turnContext.SendActivityAsync(_templateEngine.GenerateActivityForLocale("ErrorMessage"));
            _telemetryClient.TrackException(exception);

            return null;
        }
    }

    // Invoked when a 'task/submit' invoke activity is received for task module submit actions.
    protected override async Task<TaskModuleResponse> OnTeamsTaskModuleSubmitAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
    {
        try
        {
            string skillId = (turnContext.Activity as Activity).GetSkillId();
            var skill = _skillsConfig.Skills.Where(s => s.Value.AppId == skillId).First().Value;

            // Forward request to correct skill
            var invokeResponse = await _skillHttpClient.PostActivityAsync(this._appId, skill, _skillsConfig.SkillHostEndpoint, turnContext.Activity as Activity, cancellationToken).ConfigureAwait(false);

            return invokeResponse.GetTaskModuleRespose();
        }
        catch (Exception exception)
        {
            await turnContext.SendActivityAsync(_templateEngine.GenerateActivityForLocale("ErrorMessage"));
            _telemetryClient.TrackException(exception);

            return null;
        }
    }

De plus, tous les domaines de compétences doivent être inclus dans la validDomains section du fichier manifeste de l’assistant virtuel afin que les modules de tâches appelés via un rendu de compétences soient correctement affichés.Additionally, all skill domains must be included in the validDomains section in Virtual Assistant's manifest file so that task modules invoked via a skill render properly.

Gestion des étendues d’applications collaborativesHandling collaborative app scopes

Les applications teams peuvent exister dans plusieurs étendues, y compris la conversation de 1:1, la conversation de groupe et les canaux.Teams apps can exist in multiple scopes including 1:1 chat, group chat, and channels. Le modèle de l’assistant virtuel principal est conçu pour les conversations de 1:1.The core Virtual Assistant template is designed for 1:1 chats. Dans le cadre de l’Assistant Virtual expérience d’intégration, l’assistant virtuel invite les utilisateurs à fournir un nom et gère l’état de l’utilisateur.As part of the onboarding experience Virtual Assistant prompts users for name and maintains user state. Étant donné que cette expérience d’intégration n’est pas adaptée aux étendues de conversation de groupe/canal, elle a été supprimée.Since that onboarding experience is not suited for group chat/channel scopes it has been removed.

Les compétences doivent gérer les activités dans plusieurs étendues (1:1 chat, conversation de groupe et conversation de canal).Skills should handle activities in multiple scopes (1:1 chat, group chat, and channel conversation). Si l’une de ces étendues n’est pas prise en charge, les compétences doivent répondre avec un message approprié.If any of these scopes are not supported, skills should respond with an appropriate message.

Les fonctions de traitement suivantes ont été ajoutées à Virtual Assistant Core :The following processing functions have been added to Virtual Assistant core:

  • L’assistant virtuel peut être appelé sans aucun message texte provenant d’une conversation ou d’un canal de groupe.Virtual Assistant can be invoked without any text message from a group chat or channel.
  • Les articulations sont nettoyées (autrement dit, supprimez les @mention nécessaires du bot) avant d’envoyer le message au module de répartition.Articulations are cleaned (i.e., remove the necessary @mention of the bot) before sending the message to the dispatch module.
    if (innerDc.Context.Activity.Conversation?.IsGroup == true)
    {
        // Remove bot atmentions for teams/groupchat scope
        innerDc.Context.Activity.RemoveRecipientMention();

        // If bot is invoked without any text, reply with FirstPromptMessage
        if (string.IsNullOrWhiteSpace(innerDc.Context.Activity.Text))
        {
            await innerDc.Context.SendActivityAsync(_templateEngine.GenerateActivityForLocale("FirstPromptMessage"));
            return EndOfTurn;
        }
    }

Gestion des extensions de messagerieHandling messaging extensions

Les commandes pour une extension de messagerie sont déclarées dans le fichier manifeste de votre application.The commands for a messaging extension are declared in your app manifest file. L’interface utilisateur de l’extension de messagerie est gérée par ces commandes.The messaging extension user interface is powered by those commands. Pour qu’un assistant virtuel alimente une commande d’extension de messagerie (en tant que compétence attachée), le propre manifeste d’un assistant virtuel doit contenir ces commandes.For a Virtual Assistant to power a messaging extension command (as an attached skill), a Virtual Assistant's own manifest must contain those commands. Les commandes du manifeste d’une compétence individuelle doivent également être ajoutées au manifeste de l’assistant virtuel.The commands from an individual skill's manifest should be added to the Virtual Assistant's manifest as well. L’ID de commande fournit des informations sur une compétence associée en ajoutant l’ID de l’application de la compétence via un séparateur ( : ).The command ID provides information about an associated skill by appending the skill's app ID via a separator (:).

Vous trouverez ci-dessous un extrait du fichier manifeste d’une compétence.Below is a snippet from a skill's manifest file.

 "composeExtensions": [
    {
        "botId": "<Skil_App_Id>",
        "commands": [
            {
                "id": "searchQuery",
                "context": [ "compose", "commandBox" ],
                "description": "Test command to run query",
    ....

Et, ci-dessous, l’extrait de code du fichier de manifeste de l’assistant virtuel correspondant.And, below is the corresponding Virtual Assistant manifest file code snippet.

 "composeExtensions": [
    {
        "botId": "<VA_App_Id>",
        "commands": [
            {
                "id": "searchQuery:<skill_id>",
                "context": [ "compose", "commandBox" ],
                "description": "Test command to run query",
    ....

Une fois que les commandes sont appelées par un utilisateur, l’assistant virtuel peut identifier une compétence associée en analysant l’ID de commande, mettre à jour l’activité en supprimant le suffixe supplémentaire ( :<skill_id> ) de l’ID de commande et le transférer à la compétence correspondante.Once the commands are invoked by a user, the Virtual Assistant can identify an associated skill by parsing the command ID, update the activity by removing the extra suffix (:<skill_id>) from the command ID, and forward it to the corresponding skill. Le code d’une compétence n’a pas besoin de gérer le suffixe supplémentaire, de sorte que les conflits entre les ID de commande entre les compétences sont évités.The code for a skill doesn't need to handle the extra suffix, thus, conflicts between command IDs across skills are avoided. Avec cette approche, toutes les commandes de recherche et d’action d’une compétence dans tous les contextes (« composition », « commandBox » et « message ») peuvent être gérées par un assistant virtuel.With this approach, all the search and action commands of a skill within all contexts ("compose", "commandBox" and "message") can be powered by a Virtual Assistant.

    const string MessagingExtensionCommandIdSeparator = ":";

    // Invoked when a 'composeExtension/submitAction' invoke activity is received for a messaging extension action command
    protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
    {
        return await ForwardMessagingExtensionActionCommandActivityToSkill(turnContext, action, cancellationToken);
    }

    // Forwards invoke activity to right skill for messaging extension action commands.
    private async Task<MessagingExtensionActionResponse> ForwardMessagingExtensionActionCommandActivityToSkill(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
    {
        var skillId = ExtractSkillIdFromMessagingExtensionActionCommand(turnContext, action);
        var skill = _skillsConfig.Skills.Where(s => s.Value.AppId == skillId).First().Value;
        var invokeResponse = await _skillHttpClient.PostActivityAsync(this._appId, skill, _skillsConfig.SkillHostEndpoint, turnContext.Activity as Activity, cancellationToken).ConfigureAwait(false);

        return invokeResponse.GetMessagingExtensionActionResponse();
    }

    // Extracts skill Id from messaging extension command and updates activity value
    private string ExtractSkillIdFromMessagingExtensionActionCommand(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action)
    {
        var commandArray = action.CommandId.Split(MessagingExtensionCommandIdSeparator);
        var skillId = commandArray.Last();

        // Update activity value by removing skill id before forwarding to the skill.
        var activityValue = JsonConvert.DeserializeObject<MessagingExtensionAction>(turnContext.Activity.Value.ToString());
        activityValue.CommandId = string.Join(MessagingExtensionCommandIdSeparator, commandArray, 0 commandArray.Length - 1);
        turnContext.Activity.Value = activityValue;

        return skillId;
    }

Certaines activités d’extension de messagerie n’incluent pas l’ID de commande.Some messaging extension activities do not include the command ID. Par exemple, composeExtension/selectItem contient uniquement la valeur de l’action appeler le TAP.For example, composeExtension/selectItem contains only the value of the invoke tap action. Pour identifier la compétence associée, skillId est joint à chaque fiche d’article tout en formant une réponse à OnTeamsMessagingExtensionQueryAsync .To identify the associated skill, skillId is attached to each item card while forming a response for OnTeamsMessagingExtensionQueryAsync. (Cette méthode est similaire à celle permettant d' Ajouter des cartes adaptatives à votre assistant virtuel.(This is similar to the approach for adding adaptive cards to your Virtual Assistant.

    // Invoked when a 'composeExtension/selectItem' invoke activity is received for compose extension query command.
    protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
    {
        var data = JsonConvert.DeserializeObject<SkillCardActionData>(query.ToString());
        var skill = _skillsConfig.Skills.Where(s => s.Value.AppId == data.SkillId).First().Value;
        var invokeResponse = await _skillHttpClient.PostActivityAsync(this._appId, skill, _skillsConfig.SkillHostEndpoint, turnContext.Activity as Activity, cancellationToken).ConfigureAwait(false);

        return invokeResponse.GetMessagingExtensionResponse();
    }

Exemple : convertir le modèle d’application livre-a-Room en habiletés de l’assistant virtuelExample: Convert the Book-a-room app template to a Virtual Assistant skill

Book-a-room est un robot Microsoft teams qui permet aux utilisateurs de trouver et de réserver rapidement une salle de réunion pour 30 (par défaut), 60 ou 90 minutes à compter de l’heure actuelle.Book-a-room is a Microsoft Teams bot that lets users quickly find and reserve a meeting room for 30 (default), 60, or 90 minutes starting from the current time. Les étendues de bot livre-a-room aux conversations personnelles ou 1:1.The Book-a-room bot scopes to personal or 1:1 conversations.

Assistant virtuel avec une compétence « réserver une salle »

Les éléments suivants sont les modifications Delta introduites pour les convertir en une compétence qui peut être associée à un assistant virtuel.Followings are the delta changes introduced to convert it to a skill which can be attached to a Virtual Assistant. Des instructions similaires peuvent être suivies pour convertir tout robot v4 existant en compétences.Similar guidelines can be followed to convert any existing v4 bot to a skill.

Manifeste de compétencesSkill manifest

Un manifeste de compétences est un fichier JSON qui expose un point de terminaison de messagerie, un ID, un nom et d’autres métadonnées pertinentes (ce manifeste est différent du manifeste utilisé pour chargement une application dans Microsoft Teams) un assistant virtuel requiert un chemin d’accès à ce fichier comme entrée pour joindre une compétence.A skill manifest is a JSON file that exposes a skill's messaging endpoint, id, name, and other relevant metadata (this manifest is different than the manifest used for sideloading an app in Microsoft Teams) A Virtual Assistant requires a path to this file as an input to attach a skill. Nous avons ajouté le manifeste suivant au dossier Wwwroot du bot.We have added the following manifest to the bot's wwwroot folder.

botskills connect --remoteManifest "<url to skill's manifest>" ..
{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.1.preview-0.json",
  "$id": "microsoft_teams_apps_bookaroom",
  "name": "microsoft-teams-apps-bookaroom",
  "description": "microsoft-teams-apps-bookaroom description",
  "publisherName": "Your Company",
  "version": "1.1",
  "iconUrl": "<icon url>",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "privacyUrl": "<privacy url>",
  "endpoints": [
    {
      "name": "production",
      "protocol": "BotFrameworkV3",
      "description": "Production endpoint for the skill",
      "endpointUrl": "<endpoint url>",
      "msAppId": "skill app id"
    }
  ],
  "dispatchModels": {
    "languages": {
      "en-us": [
        {
          "id": "microsoft-teams-apps-bookaroom-en",
          "name": "microsoft-teams-apps-bookaroom LU (English)",
          "contentType": "application/lu",
          "url": "file://book-a-meeting.lu",
          "description": "English language model for the skill"
        }
      ]
    }
  },
  "activities": {
    "message": {
      "type": "message",
      "description": "Receives the users utterance and attempts to resolve it using the skill's LU models"
    }
  }
}

Intégration de LUISLUIS Integration

Le modèle de répartition de l’assistant virtuel est basé sur les modèles LUIS des compétences attachées.Virtual Assistant's dispatch model is built on top of attached skills' LUIS models. Le modèle de répartition identifie l’intention pour chaque activité de texte et Découvre les compétences associées.The dispatch model identifies the intent for every text activity and finds out skill associated with it.

L’assistant virtuel nécessite le modèle LUIS de compétences (au .lu format) en tant qu’entrée lors de l’attachement d’une compétence.Virtual Assistant requires skill's LUIS model (in .lu format) as an input while attaching a skill. Le format JSON LUIS peut être converti en .lu format à l’aide de l’outil botframework-CLI.LUIS json can be converted to .lu format using botframework-cli tool.

botskills connect --remoteManifest "<url to skill's manifest>" --luisFolder "<path to the folder containing your Skill's .lu files>" --languages "en-us" --cs
npm i -g @microsoft/botframework-cli
bf luis:convert --in <pathToLUIS.json> --out <pathToLuFile>

Book-a-room bot dispose de deux commandes principales pour les utilisateurs :Book-a-room bot has two main commands for users:

  • Book room
  • Manage Favorites

Nous avons créé un modèle LUIS qui comprenne ces deux commandes.We have built a LUIS model understanding these two commands. Les secrets correspondants doivent être renseignés cognitivemodels.json .Corresponding secrets need to be populated in cognitivemodels.json. Vous trouverez ici le fichier JSON Luis correspondant, ainsi que l' .lu apparence du fichier correspondant.The corresponding LUIS JSON file can be found here and this is how the corresponding .lu file looks like.

> ! Automatically generated by [LUDown CLI](https://github.com/Microsoft/botbuilder-tools/tree/master/Ludown), Tue Mar 31 2020 17:30:32 GMT+0530 (India Standard Time)

> ! Source LUIS JSON file: book-a-meeting.json

> ! Source QnA TSV file: Not Specified

> ! Source QnA Alterations file: Not Specified


> # Intent definitions

## BOOK ROOM
- book a room
- book room
- please book a room
- reserve a room
- i want to book a room
- i want to book a room please
- get me a room please
- get me a room


## MANAGE FAVORITES
- manage favorites
- manage favorite
- please manage my favorite rooms
- manage my favorite rooms please
- manage my favorite rooms
- i want to manage my favorite rooms

## None


> # Entity definitions


> # PREBUILT Entity definitions


> # Phrase list definitions


> # List entities

> # RegEx entities

Dans le cadre de cette approche, les commandes émises par un utilisateur vers un assistant virtuel lié à book room ou manage favorites peuvent être identifiées en tant que commandes associées à un bot livre-a-room et sont transmises à cette compétence.With this approach, any command issues by a user to Virtual Assistant related to book room or manage favorites can be identified as a command associated with Book-a-room bot and is forwarded to this skill. En revanche, livre-a-room main bot doit utiliser le modèle LUIS pour comprendre ces commandes s’ils ne sont pas tapés tels quels (par exemple : I want to manage my favorite rooms ).On the other hand, Book-a-room room bot needs to use LUIS model to understand these commands if they are not typed as is (for example: I want to manage my favorite rooms).

Prise en charge de plusieurs languesMulti-Language support

Pour cet exemple, nous avons créé uniquement un modèle LUIS avec une culture en anglais.For this example, we have only created a LUIS model with English culture. Vous pouvez créer des modèles LUIS correspondant à d’autres langages et ajouter une entrée à cognitivemodels.json .You can create LUIS models corresponding to other languages and add entry to cognitivemodels.json.

{
  "defaultLocale": "en-us",
  "languageModels": {
    "en-us": {
      "luisAppId": "",
      "luisApiKey": "",
      "luisApiHost": ""
    },
    "<your_language_culture>": {
      "luisAppId": "",
      "luisApiKey": "",
      "luisApiHost": ""
    }
  }
}

En parallèle, ajoutez le .lu fichier correspondant dans le chemin d’accès luisFolder.In parallel, add corresponding .lu file in luisFolder path. La structure de dossiers doit être la suivante :Folder structure should be as follows:

| - luisFolder

        | - en-us

                | - book-a-meeting.lu

        | - your_language_culture

                | - book-a-meeting.lu

Mettez à jour la commande botskills comme suit pour modifier le languages paramètre :Update botskills command as follows to modify languages parameter:

botskills connect --remoteManifest "<url to skill's manifest>" --luisFolder "<path to luisFolder>" --languages "en-us, your_language_culture" --cs

L’assistant virtuel utilise SetLocaleMiddleware pour identifier les paramètres régionaux en cours et appeler le modèle de répartition correspondant.Virtual Assistant uses SetLocaleMiddleware to identify current locale and invoke corresponding dispatch model. (L’activité de l’infrastructure bot a un champ de paramètres régionaux utilisé par ce middleware.) Nous vous recommandons également d’utiliser le même pour vos compétences.(Bot framework activity has locale field which is used by this middleware.) We recommend to use the same for your skill as well. Book-a-room bot n’utilise pas ce middleware et obtient à la place des paramètres régionaux de l' entité clientInfode l’activité de l’infrastructure bot.Book-a-room bot does not use this middleware and instead gets locale from Bot framework activity's clientInfo entity.

Validation de revendicationClaim validation

Nous avons ajouté claimsValidator pour restreindre les appelants à la compétence.We have added claimsValidator to restrict callers to the skill. Pour permettre à un assistant virtuel d’appeler cette qualification, renseignez le AllowedCallers tableau à appsettings l’aide de l’ID d’application de cet assistant virtuel particulier.To allow a Virtual Assistant to call this skill, populate AllowedCallers array from appsettings with that particular Virtual Assistant's app ID.

"AllowedCallers": [ "<caller_VA1_appId>", "<caller_VA2_appId>" ],

Le tableau des appelants autorisés peut restreindre les compétences auxquelles les consommateurs peuvent accéder.The allowed callers array can restrict which skill consumers can access the skill. Ajoutez une entrée unique * à ce tableau pour accepter les appels de tous les consommateurs de compétences.Add single entry * to this array, to accept calls from any skill consumer.

"AllowedCallers": [ "*" ],

Vous trouverez iciune documentation détaillée sur l’ajout de la validation des revendications à une compétence.Detailed documentation for adding claims validation to a skill can be found here.

Limitation de l’actualisation de la carteCard refresh limitation

L’activité de mise à jour (actualisation de carte) n’est pas encore prise en charge via l’assistant virtuel (problème GitHub).Updating activity (card refresh) is not supported yet via Virtual Assistant (github issue). Par conséquent, nous avons remplacé tous les appels d’actualisation de carte ( UpdateActivityAsync ) par la publication de nouveaux appels de carte ( SendActivityAsync ).Hence, we have replaced all card refresh calls (UpdateActivityAsync) with posting new card calls(SendActivityAsync).

Actions de carte et flux de module de tâchesCard actions and task module flows

Pour transférer les activités d’une action de carte ou d’un module de tâche à une compétence associée, la compétence doit être incorporée skillId .To forward card action or task module activities to an associated skill, the skill needs to embed skillId to it. Action de la carte de robot de livre-a-room, le module de tâche FETCH and Submit action Payloads est modifié pour contenir skillId comme paramètre.Book-a-room bot card action, task module fetch and submit action payloads are modified to contain skillId as a parameter.

Pour plus d’informations, reportez-vous à cette section à partir de cette documentation.For more information refer this section from this documentation.

Gérer les activités à partir de la conversation de groupe ou de l’étendue de canalHandle activities from group chat or channel scope

Book-a-room bot est conçu pour les conversations privées (personnelles/1:1 étendue) uniquement.Book-a-room bot is designed for private chats (personal/1:1 scope) only. Étant donné que l’assistant virtuel personnalisé prend en charge la conversation de groupe et les étendues de canal, l’assistant virtuel peut être appelé à partir de ces étendues et, par conséquent, le bot livre-a-Room peut obtenir des activités pour le même.Since we have customized Virtual Assistant to support group chat and channel scopes, the Virtual Assistant might be invoked from these scopes and thus, Book-a-room bot might get activities for the same. Par conséquent, le bot de livre-a-Room est personnalisé pour gérer ces activités.Hence Book-a-room bot is customized to handle those activities. La vérification a été placée dans les OnMessageActivityAsync méthodes du gestionnaire d’activité livre-a-room.The check has been put in OnMessageActivityAsync methods of Book-a-room bot's activity handler.

    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Check if activities are from groupchat/ teams scope. This might happen when the bot is consumed by Virtual Assistant.
        if (turnContext.Activity.Conversation.IsGroup == true)
        {
            await ShowNotSupportedInGroupChatCardAsync(turnContext).ConfigureAwait(false);
        }
        else
        {
            ...
        }
    }

Vous pouvez également tirer parti des compétences existantes du référentiel de solutions de robots ou créer une nouvelle compétence entièrement complète.You can also leverage existing skills from Bot Framework Solutions repository or create a new skill altogether from scratch. Vous trouverez des didacticiels pour les versions ultérieures ici.Tutorials for the later can be found here. Reportez-vous à la documentation pour l’assistant virtuel et l’architecture des compétences.Please refer to documentation for Virtual Assistant and skills architecture.

Exemple de code pour commencerSample code to get started

Limitations connues de l’assistant virtuelVirtual Assistant known limitations

  • EndOfConversation.EndOfConversation. Une compétence doit envoyer une endOfConversation activité lorsqu’elle termine une conversation.A skill should send an endOfConversation activity when it finishes a conversation. Cette activité est basée sur cette activité, un assistant virtuel met fin au contexte avec cette compétence particulière et revient dans le contexte de l’assistant virtuel (racine).basis this activity, a Virtual Assistant ends context with that particular skill and gets back into Virtual Assistant's (root) context. Pour un bot livre-a-room, il n’existe pas d’État clair où la conversation peut être terminée.For Book-a-room bot, there is no clear state where conversation can be ended. Par conséquent, nous n’avons pas envoyé endOfConversation de livre-a-room bot et lorsque l’utilisateur souhaite revenir au contexte racine, il peut simplement le faire par start over Command.Hence we have not sent endOfConversation from Book-a-room bot and when user wants to go back to root context they can simply do that by start over command.
  • Actualisationde la carte.Card refresh. L’actualisation de la carte n’est pas encore prise en charge par l’assistant virtuel.Card refreshes is not yet supported through Virtual Assistant.
  • Extensions de messagerie:Messaging extensions.:
    • À l’heure actuelle, un assistant virtuel peut prendre en charge un maximum de dix commandes pour les extensions de messagerie.Currently, a Virtual Assistant can support a maximum of ten commands for messaging extensions.
    • La configuration des extensions de messagerie n’est pas limitée aux commandes individuelles, mais pour l’intégralité de l’extension.Configuration of messaging extensions is not scoped to individual commands but for the entire extension itself. Cela limite la configuration de chaque compétence par le biais de l’assistant virtuel.This limits configuration for each individual skill through Virtual Assistant.
    • Les ID de commande des extensions de messagerie ont une longueur maximale de 64 caractères et 37 caractères seront utilisés pour incorporer des informations sur les compétences.Messaging extensions command IDs have a maximum length of 64 characters and 37 characters will be used for embedding skill information. Par conséquent, les contraintes mises à jour pour l’ID de commande sont limitées à 27 caractères.Thus, updated constraints for command ID are limited to 27 characters.