Einen Copiloten an einen Azure Bot Service-Kanälen veröffentlichen

Artikel
09/27/2024

Sie können Ihren Copiloten zu vorhandenen Azure Bot Service-Kanälen hinzufügen. Dies kann hilfreich sein, wenn Sie Ihren Copiloten zu Endbenutzern auf Azure Bot Service-Kanälen hinzufügen 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.

Tipp

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 Einen Copiloten an mobile oder benutzerdefinierte Apps veröffentlichen.

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.
Veröffentlichen Sie einen Copiloten in mobilen oder benutzerdefinierten Apps.

Codebeispiele

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

Referenzen

Die Anweisungen in diesem Dokument verweisen auf die folgenden Dokumente:

Stellen Sie Ihr Bot in Azure bereit für Anweisungen zum Bereitstellen des Azure Verbinden Bot.
Azure Verbinden-Kanäle zu Verbinden zu jedem vom Azure Bot-Dienst unterstützten Kanal.
Azure Bot Service debuggen mit dem Emulator für Anweisungen zum Debuggen des Azure Bot Service Bot.

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.

Relay-Botdiagramm.

Der Relay-Beispielcode Bot ist ein guter Ausgangspunkt zeigen, wenn Sie noch kein Azure Bot Service Bot. haben. Es basiert auf Microsoft Bot Framework Bot Beispielcode , der kompiliert und in 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 sie Ihren Geschäftsanforderungen anzupassen.

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 Verbinden zum Copiloten zu gelangen, den Sie mit Copilot Studio erstellt haben, müssen Sie den Namen und das Token Endpunkt Ihres Copiloten abrufen.

Kopieren Sie den Namen Ihres Copiloten in Copilot Studio.
Wählen Sie im Navigationsmenü unter Einstellungen die Option Kanäle.
Wählen Sie den Kanal aus, mit dem Sie eine Verbindung herstellen möchten. Dieses Szenario verwendet Slack als Beispiel.
Um den Token Endpunkt Wert zu kopieren und zu speichern wählen Sie Kopieren. Sie benötigen Ihren Endpunkt, um Ihren Copiloten per Verbinden zum Azure Bot Service-Kanal zu schicken.

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 Konversation vom Azure Bot Service-Kanal zur Direct Line Konversation mit dem Copilot Studio Copiloten und umgekehrt zuordnen und weiterleiten.

Beispielcodebeispiel

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

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;
 }

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 der Aktualisierung Direct Line Token wird 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
}

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,
  };

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;
}

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 Verbinden verwenden möchten, indem Sie sich beim Azure-Portal anmelden und die Azure Bot Service-Ressourcengruppe auswählen, in der Sie bereitgestellt haben. Sehen Sie sich die spezifischen Anweisungen für jeden Kanal unter Azure Bot Service-Kanäle an.

Freigeben über