Veröffentlichen Sie ein Agent in mobilen oder benutzerdefinierten Apps

Sie können Ihr Agent per Verbinden in eine benutzerdefinierte App umwandeln, sodass die Benutzer der App direkt aus Ihrer App heraus mit Agent interagieren können.

In den meisten Fällen handelt es sich bei Ihrer benutzerdefinierten App um eine App für mobile Geräte, die entweder eine webbasierte App oder eine native App oder ein Adapter für andere Dienste ist, die Ihr Unternehmen benötigt.

Es gibt verschiedene Verfahren zum Herstellen einer Verbindung zu Ihrer mobilen App, je nachdem, ob es sich bei Ihrer App um eine webbasierte App oder eine native App handelt.

Das Verbinden Ihres Agent mit einer webbasierten App ist relativ unkompliziert, da Sie dazu den Code Ausschnitt in Ihre App kopieren müssen. Allerdings erfordern sowohl webbasierte Apps als auch native oder benutzerdefinierte Apps immer noch erhebliches Entwickler-Know-how, um Agent vollständig in Ihre App zu integrieren. Beide Verfahren werden in diesem Artikel beschrieben.

Anforderungen

• .NET Core SDK Version 2.1.
• Nuget-Paket Microsoft.Bot.Connector.DirectLine.
• Ein Agent wurde erstellt in Copilot Studio , das Sie zu Ihrer App Verbinden hinzufügen möchten.

Verbinden Ihr Agent in eine webbasierte App

1. Wählen Sie im Navigationsmenü in Copilot Studio die Option Kanäle aus.

2. Wählen Sie die Kachel mobile App aus, um das Konfigurationsfenster zu öffnen.

3. Kopieren Sie den Code unter dem Abschnitt Webbasierte Apps und stellen Sie es Ihren App-Entwicklern zur Verfügung, um es Ihrer webbasierten App hinzuzufügen.

   

Verbinden Ihr Agent in eine native oder benutzerdefinierte App

Trinkgeld

Während in diesem Abschnitt beschrieben wird, wie eine Verbindung zu einer mobilen App hergestellt wird, kann der gleiche Vorgang für benutzerdefinierte oder native Apps angewendet werden, z. B. für IoT-Apps (Internet of Things).

Wenn Ihr Ziel darin besteht, Kanäle von Verbinden in Azure Bot Service umzuwandeln, können Ihre Entwickler neben den Anweisungen hier auch unter Ein Agent in Azure Bot Service-Kanälen veröffentlichen weitere Informationen erhalten.

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.

Codebeispiele

In diesem Dokument verwendete Codefragmente stammen von:

• Connector-Beispielcode

Referenzen

Die Anweisungen in diesem Dokument beziehen sich auf folgendes Quellmaterial:

• Bot Framework Direct Line API
• Direct Line-Authentifizierung
• Bei Übergabe verfügbare Kontextvariablen
• Microsoft Bot Framework-Aktivität

Rufen Sie Ihre Copilot Studio Agent-Parameter ab

Um Verbinden zu dem von Ihnen erstellten Agent hinzuzufügen, müssen Sie den Namen und das Token Agent Ihres Agent abrufen, um es zu identifizieren.

1. Navigieren Sie in Copilot Studio zur Übersichtsseite Ihres Agent und kopieren Sie den Namen Ihres Agent.

2. Wählen Sie Kanäle>Mobile App aus.

3. Wählen Sie auf der Seite Mobile App neben Tokenendpunkt die Option Kopieren aus. Sie benötigen diesen Endpunk für den Schritt Direct Line-Token erhalten.

   

Direct Line-Token erhalten

Um eine Unterhaltung mit Ihrem Agent zu beginnen, benötigen Sie ein Direct Line Token. Dieses Token kann durch eine GET-Anforderung an den im Copilot Studio-Bildschirm angegebenen Endpunkt bezogen werden. Dieses Token muss dann als Header für nachfolgende Aufrufe der Directline-API verwendet werden.

Beispiel:

GET <BOT TOKEN ENDPOINT>

Wenn die Anfrage erfolgreich ist, werden ein Direct Line Token, eine Ablaufzeit und eine Konversations-ID für das angeforderte Agent zurückgegeben. Beispiel:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Beispielcodebeispiel

Das folgende Beispiel verwendet Beispiele aus dem Connector-Beispielcode , um ein Direct Line Token für ein Copilot Studio Agent zu erhalten.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Das Antwortobjekt ist mit der GET-Anforderung identisch, die wir zuvor gesehen haben.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Verwenden Sie Direct Line , um mit Agent zu kommunizieren

Nachdem Sie das Direct Line Token abgerufen haben, können Sie eine Unterhaltung mit Ihrem Copilot Studio Agent mit Direct Line führen. Um eine Unterhaltung zu beginnen und Nachrichten zu senden und zu empfangen, folgen Sie den Anweisungen unter Bot Framework Direct Line-API.

Das folgende Beispiel verwendet Beispiele aus dem Connector-Beispielcode , um eine Konversation zu starten und Nachrichten von einem Copilot Studio Agent zu senden und zu empfangen.

1. Initialisieren Sie eine DirectLineClient-Instanz mit dem Direct Line-Token und beginnen Sie ein Gespräch:

      // 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. Einmal gestartet, kann jedes Gespräch mithilfe der Kombination von token und conversationtId identifiziert und verbunden werden. Senden Sie eine Benutzernachricht an eine vorhandene Konversation:

      // Use the retrieved token to create a DirectLineClient instance
      // Use the conversationId from above step
      // endConversationMessage is your predefined message indicating that user wants to quit the chat
      while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
      {
          using (var directLineClient = new DirectLineClient(token))
          {
              // Send user message using directlineClient
              // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
              await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
              {
                  Type = ActivityTypes.Message,
                  From = new ChannelAccount { Id = "userId", Name = "userName" },
                  Text = inputMessage,
                  TextFormat = "plain",
                  Locale = "en-Us",
              });
          }
      }
   

3. Rufen Sie die Agent's Antwort mit demselben token und conversationId ab. Die abgerufenen Direct Line Antwort-Aktivitäten enthalten sowohl Nachrichten des Benutzers als auch von Agent. Sie können Antwort-Aktivitäten nach Ihrem Agent-Namen filtern, um nur die Agent's Antwort-Nachricht zu erhalten.

      // Use the same token to create a directLineClient
      using (var directLineClient = new DirectLineClient(token))
      {
          // To get the first response set string watermark = null
          // More information about watermark is available at
          // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0
   
          // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
          ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);
   
          // update watermark from response
          watermark = response?.Watermark;
   
          // response contains set of Activity from both user and bot
          // To display bot response only, filter Activity.From.Name equals to your bot name
          List<Activity> botResponses = response?.Activities?.Where(x =>
                    x.Type == ActivityTypes.Message &&
                      string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();
   
          // Display botResponses
      }
   

Direct Line-Token aktualisieren

Sie müssen möglicherweise Code zum Aktualisieren des Direct Line Tokens hinzufügen, wenn Ihre Anwendung eine längere Konversation mit Agent führt. Das Token läuft ab, kann jedoch vor Ablauf aktualisiert werden. Weitere Informationen finden Sie unter Direct Line-Authentifizierung.

Das folgende Beispiel verwendet Beispiele aus dem Connector-Beispielcode, um das Token für eine bestehende Copilot Studio-Unterhaltung zu aktualisieren:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analysieren Sie die Konversationsnutzlast von Agent

Nachdem Sie eine Konversation mit Agent gestartet haben, verwendet die JSON-Nutzlast der Konversation die Standardaktivität Microsoft Bot Framework Direct Line . Weitere Informationen finden Sie unter Bot Framework Direct Line-API.

Übergabe-Aktivität handhaben

Wenn Ihre Anwendung an einen Live-Agent-Anbieter übergeben werden muss, müssen Sie die Übergabeaktivität ausführen. Die Die Übergabe-Aktivität wird gesendet, wenn der Knoten „Übertragen an Agent“ getroffen wird. Weitere Informationen finden Sie unter Informationen zur Nutzlast der Übergabe-Aktivität.

Eine Willkommensnachricht auslösen

Wenn Ihr Agent die Begrüßung Systemthema automatisch senden soll, wenn ein Benutzer eine Konversation beginnt, können Sie eine Aktivität mit Type=event und Name=startConversation senden.