Виртуальный помощник для Microsoft TeamsVirtual Assistant for Microsoft Teams

Virtual Assistant — это шаблон Microsoft Open-Source, который позволяет создавать надежное диалоговое решение, обеспечивая полный контроль над возможностями взаимодействия с пользователем, фирменной символикой и необходимыми данными.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. Основной шаблон основного помощника — это базовый Стандартный блок, который объединяет технологии Майкрософт, необходимые для создания виртуального помощника, включая пакет SDK для ленты, язык (Луис), КНА Maker, а также важные возможности, включая регистрацию навыков, связанные учетные записи, базовую цепочку для конечных пользователей.The 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. Кроме того, вы также включаете в себя обширные примеры полезных навыковдля общения.In addition, the template capabilities include rich examples of reusable conversational skills. Отдельные навыки можно интегрировать в решение Virtual Assistant для поддержки нескольких сценариев.Individual skills can be integrated in a Virtual Assistant solution to enable multiple scenarios. С помощью пакета SDK для ленты, навыки представлены в форме исходного кода, что позволяет настраивать и расширять их по мере необходимости.Using the Bot Framework SDK, Skills are presented in source code form enabling you to customize and extend as required. Узнайте , что такое навык в виде Bot-Framework.See What is a Bot Framework Skill.

Схема обзора Virtual Assistant

Текстовые действия с сообщениями направляются на связанные навыки ядром виртуального помощника с помощью модели отправки .Text message activities are routed to associated skills by the Virtual Assistant core using a dispatch model.

Рекомендации по реализацииImplementation considerations

Решение о добавлении виртуального помощника может включать множество детерминантс и различаться для каждой организации.The decision to add a Virtual Assistant can include many determinants and differ for each organization. Ниже приведены факторы, которые поддерживают реализацию виртуального помощника для вашей организации.Here are the factors that support implementing a Virtual Assistant for your organization:

  • Централизованная команда управляет всеми сотрудниками отдела и имеет возможность создавать интерфейс виртуального помощника и управлять обновлениями для основного интерфейса, включая добавление новых навыков.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.
  • Несколько приложений существуют в бизнес-функциях и/или их число в будущем должно увеличиться.Multiple applications exist across business functions and/or the number is expected to grow in the future.
  • Существующие приложения могут настраиваться, принадлежать Организации и могут быть преобразованы в навыки виртуального помощника.Existing applications are customizable, owned by the organization, and can be converted into skills for a Virtual Assistant.
  • Центральная группа сотрудников может влиять на настройки существующих приложений и предоставлять необходимые рекомендации по интеграции существующих приложений в качестве навыков в интерфейсе Virtual AssistantThe 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

Центральная группа поддерживает помощника, а бизнес-функции Teams — навыки

Создание виртуального помощника, ориентированного на TeamsCreate a Teams-focused Virtual Assistant

Корпорация Майкрософт опубликовала шаблон Visual Studio для создания виртуальных помощников и навыков.Microsoft has published a Visual Studio template for building Virtual Assistants and skills. С помощью шаблона Visual Studio вы можете создать виртуальный помощник, на основе текстового интерфейса с поддержкой ограниченных карт с действиями.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. Мы добавили расширенный шаблон Visual Studio, чтобы включить возможности платформы Microsoft Teams и мощные возможности для работы с приложениями в Teams.We have enhanced the Visual Studio base template to include Microsoft Teams platform capabilities and power great Teams app experiences. Некоторые возможности включают поддержку расширенных адаптивных карт, модулей задач, команд и групповых чатов и расширений обмена сообщениями.A few of the capabilities include support for rich adaptive cards, task modules, teams/group chats and messaging extensions. Кроме того, в этой статье рассказывается о том, как расширить свой виртуальный помощник до Microsoft Teams.See also, Tutorial: Extend Your Virtual Assistant to Microsoft Teams.

Высокоуровневая схема решения Virtual Assistant

Добавление адаптивных карт для виртуального помощникаAdd adaptive cards to your Virtual Assistant

Чтобы правильно обработать запросы, ваш виртуальный помощник должен определить правильную модель Луис и соответствующий навык, связанный с ней.To dispatch requests properly, your Virtual Assistant needs to identify the correct LUIS model and corresponding skill associated with it. Тем не менее, механизм диспетчеризации невозможно использовать для действий с карточками, так как модель Луис, связанная с навыком, может не быть обучена для текстов действий карты, так как они являются фиксированными, предопределенными ключевыми словами, а не уттеранцес от пользователя.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.

Мы разрешали эту проблему, внедрив сведения о навыках в полезные данные действий карты.We have resolved this by embedding skill information in the card action payload. Каждый навык должен внедряться skillId в value поле действия с карточками.Every skill should embed skillId in the value field of card actions. Это лучший способ гарантировать, что каждое действие действия с картой несет соответствующую информацию о навыках, и виртуальный помощник сможет использовать эту информацию для диспетчеризации.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.

Ниже приведен пример данных действия карты.Below is a card action data sample. Предоставляя skillId конструктор, вы гарантируете, что сведения о навыках всегда присутствуют в действиях карточки.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>),
    };

Далее мы рассмотрим SkillCardActionData класс в шаблоне Virtual Assistant, чтобы извлечь skillId из полезных данных действия карточки.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; }
    }

Ниже приведен фрагмент кода, который необходимо извлечь skillId из данных действий карты.Below is a code snippet to extract skillId from card action data. Мы реализовали его в качестве метода расширения в классе 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;
        }
    }

Мягкое прерывание обработки прерыванийHandle interruptions gracefully

Виртуальный помощник может обрабатывать прерывания в тех случаях, когда пользователь пытается вызвать навык, пока в данный момент активен другой навык.Virtual Assistant can handle interruptions in cases where a user tries to invoke a skill while another skill is currently active. Мы предоставили TeamsSkillDialog и TeamsSwitchSkillDialog , на основе скиллдиалог и свитчскиллдиалог, чтобы позволить пользователям переключать навыки из действий карты.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. Чтобы обработать этот запрос, виртуальный помощник запросит у пользователя сообщение с подтверждением, чтобы переключить навыки.To handle this request the Virtual Assistant prompts the user with a confirmation message to switch skills.

Запрос подтверждения при переключении на новый навык

Обработка запросов модулей задачHandling task module requests

Чтобы добавить возможности модуля задач для виртуального помощника, в обработчик действий виртуального помощника включены два дополнительных метода: OnTeamsTaskModuleFetchAsync и OnTeamsTaskModuleSubmitAsync .To add task module capabilities to a Virtual Assistant, two additional methods are included in the Virtual Assistant activity handler: OnTeamsTaskModuleFetchAsync and OnTeamsTaskModuleSubmitAsync. Эти методы прослушивают действия, связанные с модулем задач, от виртуального помощника, идентифицируют навык, связанный с запросом, и пересылают запрос определенному навыку.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.

Пересылка запросов выполняется с помощью SkillHttpClientметода скиллхттпклиент PostActivityAsync .Request forwarding is done via the SkillHttpClient, PostActivityAsync method. Он возвращает ответ, InvokeResponse который анализируется и преобразуется в 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,
            };
        }

Аналогичный подход используется для диспетчеризации действий карты и ответа модуля задач.A similar approach is followed for card action dispatching and task module responses. Данные действий при получении и отсылке модуля задачи обновляются, чтобы включить их skillId .Task module fetch and submit action data is updated to include skillId. Метод расширения действия GetSkillId извлекает skillId данные из полезных данных, которые предоставляют сведения о навыках, которые необходимо вызвать.Activity Extension method GetSkillId extracts skillId from the payload which provides details about the skill that needs to be invoked.

Ниже приведен фрагмент кода для OnTeamsTaskModuleFetchAsync методов и OnTeamsTaskModuleSubmitAsync .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;
        }
    }

Кроме того, все домены навыков должны быть включены в validDomains раздел файла манифеста виртуального помощника, чтобы модули задач, вызываемые с помощью навыка, правильно отрисовывается.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.

Обработка областей приложений для сотрудничестваHandling collaborative app scopes

Приложения Teams могут существовать в нескольких областях, в том числе чат 1:1, групповой чат и каналы.Teams apps can exist in multiple scopes including 1:1 chat, group chat, and channels. Шаблон основного виртуального помощника предназначен для 1:1 сеансов.The core Virtual Assistant template is designed for 1:1 chats. В процессе входящей миграции виртуальный помощник запрашивает у пользователей имя и сохраняет состояние пользователя.As part of the onboarding experience Virtual Assistant prompts users for name and maintains user state. Так как этот процесс входящей миграции не подходит для областей группового чата и каналов, он был удален.Since that onboarding experience is not suited for group chat/channel scopes it has been removed.

Навыки должны обрабатывать действия в нескольких областях (1:1 чат, группового чата и беседы каналов).Skills should handle activities in multiple scopes (1:1 chat, group chat, and channel conversation). Если какая – либо из этих областей не поддерживается, навыки должны отреагировать на соответствующее сообщение.If any of these scopes are not supported, skills should respond with an appropriate message.

В ядро виртуального помощника добавлены следующие функции обработки:The following processing functions have been added to Virtual Assistant core:

  • Виртуальный помощник может вызываться без текстового сообщения из группового чата или канала.Virtual Assistant can be invoked without any text message from a group chat or channel.
  • Артикулатионс очищаются (то есть удалите необходимое @mention ленты) перед отправкой сообщения в модуль диспетчеризации.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;
        }
    }

Обработка расширений обмена сообщениямиHandling messaging extensions

Команды для расширения обмена сообщениями объявляются в файле манифеста приложения.The commands for a messaging extension are declared in your app manifest file. Пользовательский интерфейс расширения обмена сообщениями питается от этих команд.The messaging extension user interface is powered by those commands. Чтобы виртуальный помощник по работе с командой расширения системы обмена сообщениями (в качестве присоединенного навыка), собственный манифест виртуального помощника должен содержать эти команды.For a Virtual Assistant to power a messaging extension command (as an attached skill), a Virtual Assistant's own manifest must contain those commands. Команды из манифеста отдельного навыка также необходимо добавить в манифест виртуального помощника.The commands from an individual skill's manifest should be added to the Virtual Assistant's manifest as well. КОД команды предоставляет сведения о связанном навыке, добавляя идентификатор приложения для навыка с помощью разделителя ( : ).The command ID provides information about an associated skill by appending the skill's app ID via a separator (:).

Ниже приведен фрагмент файла манифеста для навыка.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",
    ....

А ниже — соответствующий фрагмент кода файла манифеста виртуального помощника.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",
    ....

Когда пользователь вызывает команды, виртуальный помощник может определить связанный навык путем синтаксического анализа идентификатора команды, обновить действие, удалив лишний суффикс ( :<skill_id> ) из идентификатора команды и переслать его соответствующему навыку.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. Коду для квалификации не требуется обрабатывать дополнительный суффикс, поэтому не следует использовать конфликты между идентификаторами команд в навыках.The code for a skill doesn't need to handle the extra suffix, thus, conflicts between command IDs across skills are avoided. Благодаря этому подходу все команды поиска и действий навыка в рамках всех контекстов ("создание", "Коммандбокс" и "сообщение") могут быть включены виртуальным помощником.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;
    }

Некоторые действия по расширению системы обмена сообщениями не включают идентификатор команды.Some messaging extension activities do not include the command ID. Например, composeExtension/selectItem содержит только значение действия Invoke TAP.For example, composeExtension/selectItem contains only the value of the invoke tap action. Чтобы определить связанный навык, skillId прикрепляется к каждой карточке товара при создании ответа на OnTeamsMessagingExtensionQueryAsync .To identify the associated skill, skillId is attached to each item card while forming a response for OnTeamsMessagingExtensionQueryAsync. (Это аналогично способу добавления адаптивных карт для виртуального помощника.(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();
    }

Пример: преобразование шаблона приложения "книга — комната" в навык виртуального помощникаExample: Convert the Book-a-room app template to a Virtual Assistant skill

Book-a-комната — это робот Microsoft Teams , который позволяет пользователям быстро находить и зарезервировать комнату для собраний в течение 30 (по умолчанию), 60 или 90 минут, начиная с текущего времени.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. Области Bot "книга — комната" для личных или 1:1 бесед.The Book-a-room bot scopes to personal or 1:1 conversations.

Виртуальный помощник с навыком "книга" в помещении

Ниже приведены изменения, внесенные в разницу для преобразования в навык, который можно присоединить к виртуальному помощнику.Followings are the delta changes introduced to convert it to a skill which can be attached to a Virtual Assistant. Аналогичные инструкции можно выполнить, чтобы преобразовать любой существующий робот v4 в навык.Similar guidelines can be followed to convert any existing v4 bot to a skill.

Манифест навыкаSkill manifest

Манифест навыка это JSON-файл, который предоставляет конечную точку обмена сообщениями, идентификатор, имя и другие релевантные метаданные (этот манифест отличается от манифеста, используемого для неопубликованного приложения в Microsoft Teams). виртуальному помощнику требуется путь к этому файлу в качестве входных данных для присоединения навыка.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. Мы добавили следующий манифест в папку wwwroot для ленты.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"
    }
  }
}

Интеграция ЛуисLUIS Integration

Модель диспетчеризации виртуального помощника построена на основе моделей Луис присоединенных навыков.Virtual Assistant's dispatch model is built on top of attached skills' LUIS models. Модель диспетчеризации определяет цель для каждого текстового действия и находит навык, связанный с ним.The dispatch model identifies the intent for every text activity and finds out skill associated with it.

Виртуальному помощнику необходимо, чтобы в качестве входных данных в качестве входного навыка была модель Луис (в .lu формате).Virtual Assistant requires skill's LUIS model (in .lu format) as an input while attaching a skill. Луис JSON можно преобразовать в .lu Формат с помощью средства ботфрамеворк – 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>

В книге поробота a для комнаты две основные команды для пользователей:Book-a-room bot has two main commands for users:

  • Book room
  • Manage Favorites

Мы создали модель Луис, которая понимает эти две команды.We have built a LUIS model understanding these two commands. Соответствующие секреты должны быть заполнены cognitivemodels.json .Corresponding secrets need to be populated in cognitivemodels.json. Соответствующий JSON-файл Луис можно найти здесь , и именно так .lu выглядит соответствующий файл.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

При использовании этого подхода любая команда, связанная с пользователем book room или manage favorites может быть идентифицирована как команда, связанная с программой-роботом Book-a-Room и Переадресованная этому навыку.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. С другой стороны, для этого необходимо использовать модель Луис для изучения этих команд, если они не типизированы как есть (например: 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).

Поддержка нескольких языковMulti-Language support

В этом примере мы создали только модель Луис с английским языком и региональными параметрами.For this example, we have only created a LUIS model with English culture. Вы можете создавать модели Луис, соответствующие другим языкам, и добавлять записи в 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": ""
    }
  }
}

Параллельно добавьте соответствующий .lu файл в путь луисфолдер.In parallel, add corresponding .lu file in luisFolder path. Структура папок должна выглядеть следующим образом:Folder structure should be as follows:

| - luisFolder

        | - en-us

                | - book-a-meeting.lu

        | - your_language_culture

                | - book-a-meeting.lu

Чтобы изменить параметр, выполните команду Update ботскиллс следующим образом languages .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

Виртуальный помощник использует SetLocaleMiddleware для определения текущего языкового стандарта и вызова соответствующей модели отправки.Virtual Assistant uses SetLocaleMiddleware to identify current locale and invoke corresponding dispatch model. (Действие "Bot Framework" имеет поле языкового стандарта, которое используется этим промежуточным по.) Мы рекомендуем использовать те же сведения, что и для вашего навыка.(Bot framework activity has locale field which is used by this middleware.) We recommend to use the same for your skill as well. Books — Bot для начала работы не использует это промежуточное по и вместо этого задается языковой стандарт для объекта клиентинфодействия Bot Framework.Book-a-room bot does not use this middleware and instead gets locale from Bot framework activity's clientInfo entity.

Проверка утвержденияClaim validation

Мы добавили клаимсвалидатор , чтобы ограничить абоненты навыком.We have added claimsValidator to restrict callers to the skill. Чтобы разрешить виртуальному помощнику вызывать этот навык, заполните AllowedCallers массив appsettings с помощью идентификатора приложения конкретного виртуального помощника.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>" ],

Допустимый массив абонентов может ограничивать круг пользователей, которые могут получить доступ к навыку.The allowed callers array can restrict which skill consumers can access the skill. Добавьте * к этому массиву одну запись, чтобы принимать звонки от любого потребителя опыта.Add single entry * to this array, to accept calls from any skill consumer.

"AllowedCallers": [ "*" ],

Здесь вы найдетеподробную документацию по добавлению проверки утверждений для навыка.Detailed documentation for adding claims validation to a skill can be found here.

Ограничение на обновление картыCard refresh limitation

Действия по обновлению (обновление карты) пока не поддерживаются виртуальным помощником (Ошибка GitHub).Updating activity (card refresh) is not supported yet via Virtual Assistant (github issue). Таким образом, мы заменили все вызовы обновления карт ( UpdateActivityAsync ) с учетом вызовов новых карточек ( SendActivityAsync ).Hence, we have replaced all card refresh calls (UpdateActivityAsync) with posting new card calls(SendActivityAsync).

Потоки действий карты и модуля задачCard actions and task module flows

Для пересылки карточки действий или действий модуля задач в связанный навык необходимо внедрить skillId их в этот навык.To forward card action or task module activities to an associated skill, the skill needs to embed skillId to it. Действие "книга" — действие с картой "подача", "модуль задач" и "действия по отсылке" изменяются в skillId соответствии с параметром.Book-a-room bot card action, task module fetch and submit action payloads are modified to contain skillId as a parameter.

Для получения дополнительных сведений обратитесь к этому разделу из этой документации.For more information refer this section from this documentation.

Обработка действий из области группового чата или каналаHandle activities from group chat or channel scope

Почтовые роботы, предназначенные только для частных чатов (персональный/1:1 область).Book-a-room bot is designed for private chats (personal/1:1 scope) only. Так как у нас есть настроенный виртуальный помощник для поддержки областей группового чата и каналов, виртуальный помощник может вызываться из этих областей и, таким образом, может получить действия из книги "робот".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. Таким образом, для обработки этих действий настроен заказ ленты a-комната.Hence Book-a-room bot is customized to handle those activities. Проверка включена в OnMessageActivityAsync методы обработчика активности для ленты "книга — комната".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
        {
            ...
        }
    }

Вы также можете использовать существующие навыки из репозитория решений для Bot или создать новый навык с нуля.You can also leverage existing skills from Bot Framework Solutions repository or create a new skill altogether from scratch. Учебные пособия для более поздних версий можно найти здесь.Tutorials for the later can be found here. Ознакомьтесь с документацией по архитектуре виртуального помощника и навыков.Please refer to documentation for Virtual Assistant and skills architecture.

Пример кода, чтобы приступить к работеSample code to get started

Известные ограничения виртуального помощникаVirtual Assistant known limitations

  • Ендофконверсатион.EndOfConversation. Навык должен отправить endOfConversation действие при завершении беседы.A skill should send an endOfConversation activity when it finishes a conversation. на основе этого действия виртуальный помощник заканчивает контекст с определенным навыком и возвращается в контекст виртуального помощника (корневого).basis this activity, a Virtual Assistant ends context with that particular skill and gets back into Virtual Assistant's (root) context. Для ленты "книга — комната" нет четкого состояния, в котором можно завершить беседу.For Book-a-room bot, there is no clear state where conversation can be ended. Поэтому мы не отправили endOfConversation с ленты Books — a Room, а когда пользователь хочет вернуться к корневому контексту, он может просто сделать это с помощью start over команды.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.
  • Обновление карточки.Card refresh. Обновления карт пока не поддерживаются виртуальным помощником.Card refreshes is not yet supported through Virtual Assistant.
  • Расширения для обмена сообщениями:Messaging extensions.:
    • В настоящее время виртуальный помощник может поддерживать не более десяти команд для расширений системы обмена сообщениями.Currently, a Virtual Assistant can support a maximum of ten commands for messaging extensions.
    • Конфигурация расширений обмена сообщениями не ограничена отдельными командами, но для всего расширения.Configuration of messaging extensions is not scoped to individual commands but for the entire extension itself. Это ограничит конфигурацию каждого отдельного навыка с помощью виртуального помощника.This limits configuration for each individual skill through Virtual Assistant.
    • Длина идентификаторов команд расширений обмена сообщениями не должна превышать 64 символов , а для внедрения сведений о навыках будет использоваться 37 символов.Messaging extensions command IDs have a maximum length of 64 characters and 37 characters will be used for embedding skill information. Таким образом, в обновленных ограничениях для идентификатора команды можно добавить не более 27 символов.Thus, updated constraints for command ID are limited to 27 characters.