Azure Bot Service-Kanälen einen Copilot Studio-Copilot hinzufügen

Wichtig

Power Virtual Agents-Fähigkeiten und -Funktionen sind jetzt Teil von Microsoft Copilot Studio nach erheblichen Investitionen in generative KI und verbesserte Integrationen in Microsoft Copilot.

Einige Artikel und Screenshots beziehen sich möglicherweise auf Power Virtual Agents während wir Dokumentation und Schulungsinhalte aktualisieren.

Sie können Ihren Copiloten mit vorhandenen Azure Bot Service-Kanälen verbinden. Dies kann hilfreich sein, wenn Sie Ihren Copiloten mit Endbenutzern auf Azure Bot Service-Kanälen verbinden möchten.

Das Hinzufügen Ihres Copiloten zu Azure Bot Service-Kanälen erfordert beträchtliche Entwicklerkenntnisse. Dieser Artikel wurde für IT-Administratoren oder Entwickler geschrieben, die Erfahrung in der Entwicklung und dem Schreiben von Code haben.

Trinkgeld

Sie müssen diesem Dokument nicht folgen, um Ihren Copilot Studio-Copiloten zu Ihrer Webseite, Facebook, oder Microsoft Teams hinzuzufügen. Wenn Sie eine Verbindung zu einer benutzerdefinierten webbasierten oder nativen App herstellen möchten, erfahren Ihre Entwickler mehr unter Copilot mobilen oder benutzerdefinierten Apps hinzufügen.

Wichtig

Anweisungen in diesem Abschnitt erfordern Softwareentwicklung von Ihnen oder Ihren Entwicklern. Es richtet sich an erfahrene IT-Experten wie IT-Administratoren oder -Entwickler, die ein solides Verständnis für Entwicklertools, Dienstprogramme und IDEs haben.

Voraussetzungen

• Ein Azure Bot Service-Abonnement.
• Ein Azure Bot Service-Bot mit v4 SDK.
• .NET Core SDK Version 2.1.
• Nuget-Paket Microsoft.Bot.Connector.DirectLine.
• Ein in Copilot Studio erstellter Copilot, mit dem Sie eine Verbindung zu einem Azure Bot Service-Kanal herstellen möchten.
• Verbinden Sie Ihren Copiloten mit mobilen und benutzerdefinierten Apps.

Codebeispiele

In diesem Dokument verwendete Codefragmente stammen von Relay-Bot-Beispielcode.

Referenzen

Die Anweisungen in diesem Dokument beziehen sich auf Folgendes:

• Stellen Sie Ihren Bot in Azure bereit enthält Anweisungen zum Bereitstellen des Azure Bot Service-Bots.
• Azure Bot Service-Kanäle, um eine Verbindung zu einem von Azure Bot Service unterstützten Kanal herzustellen.
• Azure Bot Service-Debugging mit dem Emulator für Anweisungen zum Debuggen des Azure Bot Service-Bots.

Einen vorhandenen Azure Bot Service-Bot erstellen oder verwenden

Sie benötigen einen Azure Bot Service-Bot, der Unterhaltungen zwischen Ihrem Copilot Studio-Copiloten und Azure Bot Service-Kanälen weitergeben kann.

Der Relay-Bot-Beispielcode ist ein guter Ausgangspunkt, wenn Sie keinen vorhandenen Azure Bot Service-Bot haben. Er wird erstellt aus Microsoft Bot Framework-Bot-Beispielcode, der kompiliert und für den Azure Bot Service bereitgestellt werden kann. Der Beispielcode soll als Ausgangspunkt und nicht direkt in der Produktion verwendet werden. Sie müssen Code und Optimierung hinzufügen, um Ihren Geschäftsanforderungen zu entsprechen.

Wenn Sie bereits einen Azure Bot Service-Bot haben, müssen Sie einen Copilot Studio Connector und Code zum Verwalten von Konversationssitzungen hinzufügen. Anschließend können Sie den Bot für den Azure Bot Service bereitstellen und mit dem Azure-Portal eine Verbindung zu Kanälen herstellen.

Copilot Studio-Copilot-Parameter abrufen

Um eine Verbindung zu dem Copiloten herzustellen, den Sie mithilfe von Copilot Studio erstellt haben, müssen Sie den Namen und den Token-Endpunkt Ihres Copiloten abrufen.

1. Kopieren Sie den Namen Ihres Copiloten in Copilot Studio.

   

2. Wählen Sie im Navigationsmenü unter Einstellungen die Option Kanäle.

3. Wählen Sie den Kanal aus, mit dem Sie eine Verbindung herstellen möchten. Dieses Szenario verwendet Slack als Beispiel.

   

4. Um den Token Endpunkt Wert zu kopieren und zu speichern wählen Sie Kopieren. Sie benötigen Ihren Endpunkt, um Ihren Copiloten mit dem Azure Bot Service-Kanal zu verbinden.

   

Unterhaltungssitzungen über Ihren Copilot Studio-Copiloten verwalten

Es können mehrere Unterhaltungen zwischen den Azure Bot Service-Kanälen und der Direct Line-Verbindung mit Ihrem Copilot Studio-Copiloten stattfinden.

Ihr Azure Bot Service-Bot muss die Unterhaltung vom Azure Bot Service-Kanal zuordnen und an die Direct Line-Unterhaltung mit dem Copilot Studio-Copiloten weiterleiten und umgekehrt.

Beispielcodebeispiel

Das folgende Beispiel verwendet Beispiele aus dem Relay-Bot-Beispielcode.

1. Starten Sie bei jedem neuen Start der Konversation mit einem externen Azure Bot Service-Kanal eine Copilot Studio-Copilot-Konversation. Anweisungen zum Starten einer neuen Unterhaltung mit dem Bot finden Sie unter Direct Line-Token erhalten und Verwenden von Direct Line zur Kommunikation mit dem Copiloten.

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       httpRequest.RequestUri = uriBuilder.Uri;
       using (var response = await s_httpClient.SendAsync(httpRequest))
       {
           var responseString = await response.Content.ReadAsStringAsync();
           string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
       }
   }
   
   /// <summary>
   /// class for serialization/deserialization DirectLineToken
   /// </summary>
   public class DirectLineToken
   {
       public string Token { get; set; }
   }
   

    // Use the retrieved token to create a DirectLineClient instance
    using (var directLineClient = new DirectLineClient(token))
    {
        var conversation = await directLineClient.Conversations.StartConversationAsync();
        string conversationtId = conversation.ConversationId;
    }
   

2. Um mehrere Sitzungen zu verwalten, müssen Sie eine Zuordnung der externen Azure Bot Service-Kanalkonversationen zu den entsprechenden Copilot Studio-Copilot-Konversationen beibehalten. Eine Copilot Studio-Copilot-Konversation kann mit zwei Eigenschaften identifiziert und verbunden werden: ConversationtId und Token.

   Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
   

   Um den Konversationslebenszyklus zu verwalten, aktualisieren Sie die Direct Line-Tokens oder im Leerlauf befindliche Konversationen bereinigen. Weitere Informationen zur Token-Aktualisierung finden Sie unter Direct Line-Tokens aktualisieren. Eine Copilot Studio-Copilot-Konversation zur Unterstützung dieser ist wie folgt definiert:

   /// <summary>
   /// Data model class for Copilot Studio copilot conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio copilot conversation ID retrieved from step 1
   
       public string Token { get; set; } // The DirectLine token retrieved from step 1
   
       public string WaterMark { get; set; } // Identify turn in a conversation
   
       public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
   
       public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
   }
   

3. Wenn eine neue Copilot Studio-Copilot-Konversation beginnt, fügen Sie ein Schlüsselwertpaar (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) zur Zuordnungstabelle hinzu.

   // After new Copilot Studio copilot conversation starts
   ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
     {
       Token = token,
       ConversationtId = conversationId,
       WaterMark = null,
       LastConversationUpdateTime = DateTime.Now,
       LastTokenRefreshTime = DateTime.Now,
     }; 
   

4. Um mit einer vorhandenen Konversation fortzufahren, rufen Sie nach Erhalt einer neuen externen Azure Bot Service-Kanalnachricht die vorhandene Konversation aus der Zuordnungstabelle ab und leiten Sie die externe Unterhaltungsaktivität an Ihren Copilot Studio-Copiloten weiter, und erhalten eine Antwort.

   Das folgende Beispiel zeigt die Weiterleitung von Konversationen durch Überschreiben der Methode ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio copilot and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve copilot conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio copilot conversation
       ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
               currentConversation : /*await StartBotConversationAsync(externalCID)*/;
   
       // Create DirectLine client with the token associated to current conversation
       DirectLineClient client = new DirectLineClient(currentConversation.Token);
   
       // Send user message using directlineClient
       await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
       {
         Type = DirectLineActivityTypes.Message,
         From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
         Text = turnContext.Activity.Text,
         TextFormat = turnContext.Activity.TextFormat,
         Locale = turnContext.Activity.Locale,
       });
   
       // Update LastConversationUpdateTime for session management
       currentConversation.LastConversationUpdateTime = DateTime.Now;
   }  
   

5. Unter Verwenden von Direct Line zur Konversation mit dem Copiloten finden Sie Informationen darüber, wie man eine Antwort vom Copilot Studio-Copiloten erhält. Wenn die Antwort des Copilot Studio-Copilots empfangen wird, siehe Unterhaltungsnutzdaten vom Copiloten analysieren, um zu erfahren, wie die Antwort auf die externe Azure Bot Service-Kanalantwort analysiert werden sollte

Ein Beispiel für das Parsen von Antworten finden Sie in der Relay-Bot-Beispielcode ResponseConverter.cs.

Für Azure Bot Service bereitstellen

Nachdem Sie Ihren Azure Bot Service-Relay-Bot bereit haben, müssen Sie den Bot für Ihren Azure Bot Service bereitstellen.

Azure Bot Service-Kanäle einrichten

Sie können die Kanäle einrichten, zu denen Sie eine Verbindung herstellen möchten, indem Sie sich beim Azure-Portal anmelden und die Azure Bot Service-Ressourcengruppe auswählen, für die Sie die Bereitstellung durchgeführt haben. Sehen Sie sich die spezifischen Anweisungen für jeden Kanal unter Azure Bot Service-Kanäle an.