Virtueller Assistent für Microsoft TeamsVirtual Assistant for Microsoft Teams

Virtueller Assistent ist eine Open-Source-Vorlage von Microsoft, mit der Sie eine stabile Unterhaltungslösung erstellen und gleichzeitig die vollständige Kontrolle über die Benutzerfreundlichkeit, das Branding der Organisation und die erforderlichen Daten erhalten können.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. Die Virtual Assistant Core-Vorlage ist der grundlegende Baustein, der die zum Erstellen eines virtuellen Assistenten erforderlichen Microsoft-Technologien zusammenbringt, einschließlich des bot-Framework-SDK, des Sprachverständnisses (Luis), QnA Makersowie der wesentlichen Funktionen, einschließlich der Fertigstellung von Qualifikationen, verknüpfter Konten, grundlegender Unterhaltungs Absicht, Endbenutzern eine Reihe nahtloser Interaktionen und Erlebnisse anzubietenThe 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. Darüber hinaus umfassen die Vorlagen Funktionen umfangreiche Beispiele für wieder verwendbare Konversations Fertigkeiten.In addition, the template capabilities include rich examples of reusable conversational skills. Einzelne Fertigkeiten können in eine virtuelle Assistenten Lösung integriert werden, um mehrere Szenarien zu ermöglichen.Individual skills can be integrated in a Virtual Assistant solution to enable multiple scenarios. Mithilfe des bot Framework-SDK werden Fertigkeiten in der Quell Code Form angezeigt, sodass Sie nach Bedarf anpassen und erweitern können.Using the Bot Framework SDK, Skills are presented in source code form enabling you to customize and extend as required. Siehe Was ist ein bot-Framework-Fertigkeit.See What is a Bot Framework Skill.

Virtueller Assistent – Übersichtsdiagramm

Text Nachrichten Aktivitäten werden durch den virtuellen Assistenten Kern mithilfe eines Dispatch -Modells an die zugehörigen Fertigkeiten weitergeleitet.Text message activities are routed to associated skills by the Virtual Assistant core using a dispatch model.

Überlegungen zur ImplementierungImplementation considerations

Die Entscheidung zum Hinzufügen eines virtuellen Assistenten kann viele Determinanten enthalten und für jede Organisation unterschiedlich sein.The decision to add a Virtual Assistant can include many determinants and differ for each organization. Hier sind die Faktoren, die die Implementierung eines virtuellen Assistenten für Ihre Organisation unterstützen:Here are the factors that support implementing a Virtual Assistant for your organization:

  • Ein zentrales Team verwaltet alle Mitarbeiter Erfahrungen und verfügt über die Möglichkeit, eine virtuelle Assistenten Erfahrung zu erstellen und Updates für die Kern Erfahrung einschließlich der Hinzufügung neuer Fertigkeiten zu verwalten.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.
  • Mehrere Anwendungen sind in Geschäftsfunktionen vorhanden und/oder die Anzahl wird in Zukunft voraussichtlich zunehmen.Multiple applications exist across business functions and/or the number is expected to grow in the future.
  • Vorhandene Anwendungen sind anpassbar, im Besitz der Organisation und können in Fertigkeiten für einen virtuellen Assistenten umgewandelt werden.Existing applications are customizable, owned by the organization, and can be converted into skills for a Virtual Assistant.
  • Das zentrale Team für Mitarbeiter-Erlebnisse kann Anpassungen an vorhandenen apps beeinflussen und erforderliche Anleitungen für die Integration vorhandener Anwendungen als Kompetenzen in der Erfahrung virtueller Assistenten bereitstellen.The 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

Das zentrale Team verwaltet den Assistenten, und die Business Function Teams tragen Fähigkeiten ein.

Erstellen eines Teams-fokussierten virtuellen AssistentenCreate a Teams-focused Virtual Assistant

Microsoft hat eine Visual Studio Vorlage zum Erstellen virtueller Assistenten und Fertigkeiten veröffentlicht.Microsoft has published a Visual Studio template for building Virtual Assistants and skills. Mit der Visual Studio Vorlage können Sie einen virtuellen Assistenten erstellen, der von einer textbasierten Oberfläche mit Unterstützung für beschränkte Rich-Karten mit Aktionen angetrieben wird.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. Wir haben die Visual Studio Basisvorlage erweitert, um Microsoft Teams-Plattformfunktionen und leistungsstarke Teams-App-Erlebnisse einzubeziehen.We have enhanced the Visual Studio base template to include Microsoft Teams platform capabilities and power great Teams app experiences. Einige der Funktionen umfassen Unterstützung für umfangreiche Adaptive Karten, Aufgaben Module, Teams/Gruppenchats und Messaging Erweiterungen.A few of the capabilities include support for rich adaptive cards, task modules, teams/group chats and messaging extensions. Siehe auch, Lernprogramm: Erweitern des virtuellen Assistenten auf Microsoft Teams.See also, Tutorial: Extend Your Virtual Assistant to Microsoft Teams.

High-Level-Diagramm einer Virtual Assistant-Lösung

Hinzufügen von adaptiven Karten zu Ihrem virtuellen AssistentenAdd adaptive cards to your Virtual Assistant

Um Anforderungen ordnungsgemäß zu versenden, muss Ihr virtueller Assistent das richtige Luis-Modell und die dazugehörige Fähigkeit identifizieren.To dispatch requests properly, your Virtual Assistant needs to identify the correct LUIS model and corresponding skill associated with it. Der Dispatching-Mechanismus kann jedoch nicht für Karten Aktionsaktivitäten verwendet werden, da das Luis-Modell, das einer Fertigkeit zugeordnet ist, möglicherweise nicht für Karten Aktions Texte ausgebildet wird, da es sich um feste, vordefinierte Schlüsselwörter und nicht um Äußerungen eines Benutzers handelt.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.

Wir haben dies durch das Einbetten von Fertigkeits Informationen in die Nutzlast der Karten Aktion gelöst.We have resolved this by embedding skill information in the card action payload. Jede Fertigkeit sollte skillId in das value Feld der Karten Aktionen einbetten.Every skill should embed skillId in the value field of card actions. Dies ist die beste Möglichkeit, um sicherzustellen, dass jede Karten Aktions Aktivität die entsprechenden skillinformationen enthält und der virtuelle Assistent diese Informationen für die Versendung nutzen kann.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.

Unten sehen Sie ein Beispiel für eine Karten Aktionsdaten.Below is a card action data sample. Durch die Bereitstellung skillId im Konstruktor stellen wir sicher, dass Fertigkeits Informationen immer in Karten Aktionen vorhanden sind.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>),
    };

Als nächstes führen wir SkillCardActionData eine Klasse in der Vorlage virtuelles Assistenten ein, um skillId die Nutzlast der Karten Aktion zu extrahieren.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; }
    }

Unten finden Sie einen Codeausschnitt, der skillId aus Karten Aktionsdaten extrahiert werden kann.Below is a code snippet to extract skillId from card action data. Wir haben Sie als Erweiterungsmethode in der Activity -Klasse implementiert.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;
        }
    }

Ordnungsgemäße Behandlung von UnterbrechungenHandle interruptions gracefully

Der virtuelle Assistent kann Unterbrechungen in Fällen behandeln, in denen ein Benutzer versucht, eine Fertigkeit aufzurufen, während eine andere Fertigkeit derzeit aktiv ist.Virtual Assistant can handle interruptions in cases where a user tries to invoke a skill while another skill is currently active. Wir haben TeamsSkillDialog und TeamsSwitchSkillDialog basierend auf den SkillDialog und SwitchSkillDialogvon bot Frameworks eingeführt, um Benutzern die Möglichkeit zu geben, eine Fertigkeits Erfahrung aus Karten Aktionen zu wechseln.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. Zur Behandlung dieser Anforderung fordert der virtuelle Assistent den Benutzer mit einer Bestätigungsmeldung auf, um die Fertigkeiten zu wechseln.To handle this request the Virtual Assistant prompts the user with a confirmation message to switch skills.

Bestätigungsaufforderung beim Wechsel zu einer neuen Fertigkeit

Verarbeiten von Aufgabenmodul AnforderungenHandling task module requests

Um einem virtuellen Assistenten Aufgabenmodul Funktionen hinzuzufügen, werden zwei zusätzliche Methoden in den Aktivitäts Handler des virtuellen Assistenten aufgenommen: OnTeamsTaskModuleFetchAsync und OnTeamsTaskModuleSubmitAsync .To add task module capabilities to a Virtual Assistant, two additional methods are included in the Virtual Assistant activity handler: OnTeamsTaskModuleFetchAsync and OnTeamsTaskModuleSubmitAsync. Diese Methoden hören Aufgabenmodul bezogene Aktivitäten vom virtuellen Assistenten, identifizieren die mit der Anforderung verknüpfte Fähigkeit und leiten die Anforderung an die erkannte Fertigkeit weiter.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.

Die Anforderungs Weiterleitung erfolgt über SkillHttpClientdie SkillHttpClient PostActivityAsync -Methode.Request forwarding is done via the SkillHttpClient, PostActivityAsync method. Es gibt die Antwort zurück, die InvokeResponse analysiert und in konvertiert wird 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,
            };
        }

Ein ähnlicher Ansatz wird für Karten Aktionen und Aufgabenmodul Antworten befolgt.A similar approach is followed for card action dispatching and task module responses. Die Daten des Aufgabenmoduls "fetch" und "Submit Action" werden in include aktualisiert skillId .Task module fetch and submit action data is updated to include skillId. Die Aktivitäts Erweiterungsmethode GetSkillId extrahiert skillId die Nutzlast, die Details zu der Fertigkeit enthält, die aufgerufen werden muss.Activity Extension method GetSkillId extracts skillId from the payload which provides details about the skill that needs to be invoked.

Unten finden Sie einen Codeausschnitt für OnTeamsTaskModuleFetchAsync und- OnTeamsTaskModuleSubmitAsync Methoden.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;
        }
    }

Darüber hinaus müssen alle Fertigkeits Domänen in dem validDomains Abschnitt in der Manifestdatei des virtuellen Assistenten enthalten sein, damit Aufgaben Module, die über eine Fertigkeit aufgerufen werden, ordnungsgemäß gerendert werden.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.

Behandeln kollaborativer App-BereicheHandling collaborative app scopes

Microsoft Teams-Apps können in mehreren Bereichen vorhanden sein, darunter 1:1 Chat, Gruppenchat und Kanäle.Teams apps can exist in multiple scopes including 1:1 chat, group chat, and channels. Die Vorlage Core Virtual Assistant wurde für 1:1-Chats entwickelt.The core Virtual Assistant template is designed for 1:1 chats. Im Rahmen der Onboarding-Erfahrung wird der virtuelle Assistent aufgefordert, Benutzer nach Namen zu benennen und den Benutzerstatus zu verwalten.As part of the onboarding experience Virtual Assistant prompts users for name and maintains user state. Da diese Onboarding-Erfahrung nicht für Gruppenchats/Kanalbereiche geeignet ist, wurde sie entfernt.Since that onboarding experience is not suited for group chat/channel scopes it has been removed.

Skills sollten Aktivitäten in mehreren Bereichen behandeln (1:1 Chat, Gruppenchat und Kanal Unterhaltung).Skills should handle activities in multiple scopes (1:1 chat, group chat, and channel conversation). Wenn einer dieser Bereiche nicht unterstützt wird, sollten Fähigkeiten mit einer entsprechenden Nachricht reagieren.If any of these scopes are not supported, skills should respond with an appropriate message.

Die folgenden Verarbeitungsfunktionen wurden dem virtuellen Assistenten Kern hinzugefügt:The following processing functions have been added to Virtual Assistant core:

  • Virtueller Assistent kann ohne Textnachricht aus einem Gruppenchat oder-Kanal aufgerufen werden.Virtual Assistant can be invoked without any text message from a group chat or channel.
  • Artikulationen werden bereinigt (d. h., entfernen Sie die erforderlichen @mention des bot), bevor Sie die Nachricht an das Dispatch-Modul senden.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;
        }
    }

Behandeln von Messaging ErweiterungenHandling messaging extensions

Die Befehle für eine Messaging Erweiterung werden in Ihrer APP-Manifestdatei deklariert.The commands for a messaging extension are declared in your app manifest file. Die Benutzeroberfläche der Messaging Erweiterung wird von diesen Befehlen angetrieben.The messaging extension user interface is powered by those commands. Damit ein virtueller Assistent einen Messaging Erweiterungs Befehl (als angefügte Fertigkeit) macht, muss ein eigenes Manifest eines virtuellen Assistenten diese Befehle enthalten.For a Virtual Assistant to power a messaging extension command (as an attached skill), a Virtual Assistant's own manifest must contain those commands. Die Befehle aus dem Manifest eines einzelnen Skills sollten ebenfalls dem Manifest des virtuellen Assistenten hinzugefügt werden.The commands from an individual skill's manifest should be added to the Virtual Assistant's manifest as well. Die Befehls-ID stellt Informationen zu einer zugeordneten Fertigkeit bereit, indem die APP-ID der Fertigkeit über ein Trennzeichen () angehängt wird : .The command ID provides information about an associated skill by appending the skill's app ID via a separator (:).

Unten sehen Sie einen Ausschnitt aus der Manifestdatei eines Skills.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",
    ....

Und, unten ist der entsprechende virtuelle Assistent Manifest Datei Codeausschnitt.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",
    ....

Sobald die Befehle von einem Benutzer aufgerufen wurden, kann der virtuelle Assistent eine zugeordnete Fertigkeit identifizieren, indem er die Befehls-ID analysiert, die Aktivität aktualisiert, indem das zusätzliche Suffix ( :<skill_id> ) aus der Befehls-ID entfernt und an die entsprechende Fertigkeit weitergeleitet wird.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. Der Code für eine Fertigkeit muss das zusätzliche Suffix nicht verarbeiten, daher werden Konflikte zwischen Befehls-IDs zwischen den einzelnen Fertigkeiten vermieden.The code for a skill doesn't need to handle the extra suffix, thus, conflicts between command IDs across skills are avoided. Bei diesem Ansatz können alle Such-und Aktionsbefehle einer Fertigkeit in allen Kontexten ("Verfassen", "commandbox" und "Message") von einem virtuellen Assistenten betrieben werden.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;
    }

Einige Messaging Erweiterungsaktivitäten enthalten nicht die Befehls-ID.Some messaging extension activities do not include the command ID. Enthält beispielsweise composeExtension/selectItem nur den Wert der Invoke-Tap-Aktion.For example, composeExtension/selectItem contains only the value of the invoke tap action. Um die zugehörige Fertigkeit zu identifizieren, skillId wird an jede Element Karte angehängt, während eine Antwort für gebildet wird OnTeamsMessagingExtensionQueryAsync .To identify the associated skill, skillId is attached to each item card while forming a response for OnTeamsMessagingExtensionQueryAsync. (Dies ähnelt dem Ansatz für das Hinzufügen von adaptiven Karten zu Ihrem virtuellen Assistenten.(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();
    }

Beispiel: Konvertieren der Vorlage "book-a-room app" in eine virtuelle Assistenten FähigkeitExample: Convert the Book-a-room app template to a Virtual Assistant skill

Book-a-room ist ein Microsoft Teams-bot , mit dem Benutzer einen Besprechungsraum für 30 (Standard), 60 oder 90 Minuten ab der aktuellen Uhrzeit schnell finden und reservieren können.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. Die book-a-room-bot-Bereiche für persönliche oder 1:1-Unterhaltungen.The Book-a-room bot scopes to personal or 1:1 conversations.

Virtueller Assistent mit einem "book a Room"-Skill

Es folgen die Delta-Änderungen, die eingeführt wurden, um Sie in eine Fertigkeit umzuwandeln, die an einen virtuellen Assistenten angefügt werden kann.Followings are the delta changes introduced to convert it to a skill which can be attached to a Virtual Assistant. Ähnliche Richtlinien können befolgt werden, um einen vorhandenen V4-bot in eine Fertigkeit zu konvertieren.Similar guidelines can be followed to convert any existing v4 bot to a skill.

Fertigkeits ManifestSkill manifest

Ein Fertigkeits Manifest ist eine JSON-Datei, die den Messaging Endpunkt, die ID, den Namen und andere relevante Metadaten eines Skills verfügbar macht (dieses Manifest unterscheidet sich von dem Manifest, das für Sideloading einer APP in Microsoft Teams verwendet wird) ein virtueller Assistent benötigt einen Pfad zu dieser Datei als Eingabe zum Anfügen einer Fertigkeit.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. Wir haben dem WWWRoot-Ordner des bot das folgende Manifest hinzugefügt.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-IntegrationLUIS Integration

Das Dispatch-Modell des virtuellen Assistenten basiert auf den Luis-Modellen von Attached Skills.Virtual Assistant's dispatch model is built on top of attached skills' LUIS models. Das Dispatch-Modell identifiziert die Absicht für jede Text Aktivität und ermittelt die damit verbundene Fähigkeit.The dispatch model identifies the intent for every text activity and finds out skill associated with it.

Virtueller Assistent erfordert das Luis-Modell des Skills (im .lu Format) als Eingabe beim Anfügen einer Fertigkeit.Virtual Assistant requires skill's LUIS model (in .lu format) as an input while attaching a skill. Luis JSON kann .lu mit dem botframework-CLI-Tool in ein Format konvertiert werden.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>

Der book-a-room-bot verfügt über zwei Hauptbefehle für Benutzer:Book-a-room bot has two main commands for users:

  • Book room
  • Manage Favorites

Wir haben ein Luis-Modell erstellt, das diese beiden Befehle versteht.We have built a LUIS model understanding these two commands. Die entsprechenden Geheimnisse müssen in aufgefüllt werden cognitivemodels.json .Corresponding secrets need to be populated in cognitivemodels.json. Die entsprechende Luis JSON-Datei kann hier gefunden werden und so sieht die entsprechende .lu Datei aus.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

Bei dieser Vorgehensweise werden alle Befehls Probleme eines Benutzers an den virtuellen Assistenten im Zusammenhang mit book room oder manage favorites können als Befehl identifiziert werden, der dem book-a-room-bot zugeordnet ist und an diese Fertigkeit weitergeleitet werden.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. Auf der anderen Seite muss book-a-room-bot das Luis-Modell verwenden, um diese Befehle zu verstehen, wenn Sie nicht wie folgt eingegeben werden (beispielsweise: 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).

Mehrsprachige UnterstützungMulti-Language support

Für dieses Beispiel haben wir nur ein Luis-Modell mit englischer Kultur erstellt.For this example, we have only created a LUIS model with English culture. Sie können Luis-Modelle erstellen, die anderen Sprachen entsprechen, und den Eintrag hinzufügen 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": ""
    }
  }
}

Fügen Sie gleichzeitig die entsprechende .lu Datei in luisFolder Path hinzu.In parallel, add corresponding .lu file in luisFolder path. Die Ordnerstruktur sollte wie folgt aussehen:Folder structure should be as follows:

| - luisFolder

        | - en-us

                | - book-a-meeting.lu

        | - your_language_culture

                | - book-a-meeting.lu

Aktualisieren Sie den botskills-Befehl wie folgt, um den Parameter zu ändern 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

Virtueller Assistent verwendet SetLocaleMiddleware , um das aktuelle Gebietsschema zu identifizieren und das entsprechende Dispatch-Modell aufzurufen.Virtual Assistant uses SetLocaleMiddleware to identify current locale and invoke corresponding dispatch model. (Bot-Framework-Aktivität hat Gebietsschema Feld, das von dieser Middleware verwendet wird.) Es wird empfohlen, das gleiche auch für ihre Fähigkeit zu verwenden.(Bot framework activity has locale field which is used by this middleware.) We recommend to use the same for your skill as well. Der book-a-room-bot verwendet diese Middleware nicht und ruft stattdessen das Gebietsschema aus der abgeschlossen werden ungültig-Entitätder bot-Framework-Aktivität ab.Book-a-room bot does not use this middleware and instead gets locale from Bot framework activity's clientInfo entity.

AnspruchsüberprüfungClaim validation

Wir haben claimsValidator hinzugefügt, um Anrufer auf die Fertigkeit einzuschränken.We have added claimsValidator to restrict callers to the skill. Um einem virtuellen Assistenten das Aufrufen dieser Fertigkeit zu gestatten, füllen Sie das AllowedCallers array appsettings mit der APP-ID dieses bestimmten virtuellen Assistenten auf.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>" ],

Das zulässige callers-Array kann einschränken, welche Fähigkeit Verbraucher auf die Fertigkeit zugreifen können.The allowed callers array can restrict which skill consumers can access the skill. Fügen Sie diesem Array einen einzelnen Eintrag hinzu * , um Anrufe von beliebigen Skill-Consumern zu akzeptieren.Add single entry * to this array, to accept calls from any skill consumer.

"AllowedCallers": [ "*" ],

Eine ausführliche Dokumentation zum Hinzufügen der Anspruchsüberprüfung zu einer Fertigkeit finden Sie hier.Detailed documentation for adding claims validation to a skill can be found here.

Beschränkung der KartenaktualisierungCard refresh limitation

Die Aktualisierungsaktivität (Kartenaktualisierung) wird noch nicht über den Virtual Assistant (GitHub-Problem) unterstützt.Updating activity (card refresh) is not supported yet via Virtual Assistant (github issue). Daher haben wir alle Karten Aktualisierungsaufrufe ( UpdateActivityAsync ) durch das Veröffentlichen neuer Karten Anrufe ( SendActivityAsync ) ersetzt.Hence, we have replaced all card refresh calls (UpdateActivityAsync) with posting new card calls(SendActivityAsync).

Karten Aktionen und Aufgabenmodul FlüsseCard actions and task module flows

Um Karten Aktionen oder Aufgabenmodul Aktivitäten an eine zugeordnete Fertigkeit weiterzuleiten, muss die Fertigkeit darin eingebettet werden skillId .To forward card action or task module activities to an associated skill, the skill needs to embed skillId to it. Book-a-room-bot-Karten Aktion, Aufgabenmodul-FETCH-und-Submit-Aktions Nutzlasten werden geändert, sodass Sie skillId als Parameter enthalten sind.Book-a-room bot card action, task module fetch and submit action payloads are modified to contain skillId as a parameter.

Weitere Informationen finden Sie in diesem Abschnitt in dieser Dokumentation.For more information refer this section from this documentation.

Behandeln von Aktivitäten im Gruppenchat oder KanalbereichHandle activities from group chat or channel scope

Der book-a-room-bot ist nur für private Chats (persönlich/1:1 Bereich) konzipiert.Book-a-room bot is designed for private chats (personal/1:1 scope) only. Da wir den virtuellen Assistenten für die Unterstützung von Gruppenchats und Kanal Bereichen angepasst haben, kann der virtuelle Assistent aus diesen Bereichen aufgerufen werden, sodass der book-a-room-bot möglicherweise Aktivitäten für dasselbe erhält.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. Daher wird der book-a-room-bot angepasst, um diese Aktivitäten zu verarbeiten.Hence Book-a-room bot is customized to handle those activities. Die Überprüfung wurde in OnMessageActivityAsync Methoden des Aktivitäts Handlers des book-a-room-bot eingeführt.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
        {
            ...
        }
    }

Sie können auch vorhandene Fertigkeiten aus dem Repository von bot-Framework-Lösungen nutzen oder ganz neu eine neue Fertigkeit erstellen.You can also leverage existing skills from Bot Framework Solutions repository or create a new skill altogether from scratch. Lernprogramme für die spätere Version finden Sie hier.Tutorials for the later can be found here. Weitere Informationen finden Sie in der Dokumentation für Virtual Assistant and Skills Architecture.Please refer to documentation for Virtual Assistant and skills architecture.

Beispielcode für erste SchritteSample code to get started

Bekannte Einschränkungen für den virtuellen AssistentenVirtual Assistant known limitations

  • EndOfConversation.EndOfConversation. Eine Fertigkeit sollte eine Aktivität senden, endOfConversation Wenn Sie eine Unterhaltung beendet.A skill should send an endOfConversation activity when it finishes a conversation. basierend auf dieser Aktivität beendet ein virtueller Assistent den Kontext mit dieser speziellen Fertigkeit und wird wieder in den (Stamm-) Kontext des virtuellen Assistenten eingefügt.basis this activity, a Virtual Assistant ends context with that particular skill and gets back into Virtual Assistant's (root) context. Für einen book-a-room-bot gibt es keinen eindeutigen Zustand, in dem die Unterhaltung beendet werden kann.For Book-a-room bot, there is no clear state where conversation can be ended. Daher haben wir nicht endOfConversation von book-a-room-bot gesendet und wenn der Benutzer zum Stammkontext zurückkehren möchte, kann er dies einfach per start over Befehl tun.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.
  • Kartenaktualisierung.Card refresh. Kartenaktualisierungen werden noch nicht über den virtuellen Assistenten unterstützt.Card refreshes is not yet supported through Virtual Assistant.
  • Messaging Erweiterungen.:Messaging extensions.:
    • Derzeit kann ein virtueller Assistent maximal zehn Befehle für Messaging Erweiterungen unterstützen.Currently, a Virtual Assistant can support a maximum of ten commands for messaging extensions.
    • Die Konfiguration von Messaging Erweiterungen ist nicht auf einzelne Befehle, sondern auf die gesamte Erweiterung selbst beschränkt.Configuration of messaging extensions is not scoped to individual commands but for the entire extension itself. Dadurch wird die Konfiguration für jede einzelne Fertigkeit mithilfe des virtuellen Assistenten eingeschränkt.This limits configuration for each individual skill through Virtual Assistant.
    • Befehls-IDs für Messaging Erweiterungen weisen eine maximale Länge von 64 Zeichen auf, und 37 Zeichen werden für das Einbetten von Fertigkeits Informationen verwendet.Messaging extensions command IDs have a maximum length of 64 characters and 37 characters will be used for embedding skill information. Daher sind aktualisierte Einschränkungen für die Befehls-ID auf 27 Zeichen beschränkt.Thus, updated constraints for command ID are limited to 27 characters.