Einen Agenten für mobile oder benutzerdefinierte Apps veröffentlichen

Sie können Ihren Agent mit einer benutzerdefinierten App verbinden, damit die Benutzer der App direkt aus Ihrer App heraus mit dem Agent interagieren können.

In den meisten Fällen handelt es sich bei Ihrer benutzerdefinierten App um eine app für mobile Geräte, bei der es sich um eine webbasierte oder eine systemeigene App handelt. Es kann auch ein Adapter für andere Dienste sein, die Ihr Unternehmen benötigt.

Es gibt unterschiedliche Verfahren zum Herstellen einer Verbindung mit Ihrer mobilen App, je nachdem, ob es sich bei Ihrer App um eine webbasierte App oder um eine systemeigene App handelt.

Das Verbinden Ihres Agents mit einer webbasierten App ist relativ einfach, da ein Code Ausschnitt in Ihre App kopiert werden muss. Sowohl webbasierte Apps als auch native oder benutzerdefinierte Apps erfordern jedoch noch beträchtliche Entwicklerkenntnisse, um den Agent vollständig in Ihre App zu integrieren. In diesem Artikel werden beide Verfahren beschrieben.

Voraussetzungen

• .NET Core SDK Version 2.1.
• NuGet-Paket "Microsoft.Bot.Connector.DirectLine".
• Ein in Copilot Studio erstellter Agent, mit dem Sie eine Verbindung zu Ihrer App herstellen möchten.

Ihren Agent mit einer webbasierten App verbinden

1. Wählen Sie im Navigationsmenü in Copilot Studio 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.

   

Ihren Agent mit einer nativen oder benutzerdefinierten App verbinden

Wenn Sie eine Verbindung mit Azure Bot Service Kanälen herstellen möchten, lesen Sie Publish an agent to Azure Bot Service channels.

Verweise

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

Die Parameter Ihres Copilot Studio Agenten abrufen

Um eine Verbindung mit dem erstellten Agent herzustellen, rufen Sie den Namen und den Tokenendpunkt Ihres Agents ab, um ihn zu identifizieren.

1. Wechseln Sie in Copilot Studio zur Seite Overview Ihres Agents, und kopieren Sie den Namen Ihres Agenten.

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 abrufen.

   

Direct Line-Token abrufen

Um eine Unterhaltung mit Ihrem Agenten zu beginnen, benötigen Sie ein Direct Line-Token. Rufen Sie dieses Token ab, indem Sie eine GET-Anforderung an den Endpunkt senden, der auf dem bildschirm Copilot Studio angezeigt wird. Verwenden Sie dieses Token als Header für die nächsten Aufrufe der Direktleitungs-API.

Beispiel:

GET <BOT TOKEN ENDPOINT>

Wenn die Anforderung erfolgreich ist, gibt der Endpunkt ein Direct Line-Token, die Ablaufzeit und eine conversationId für den angeforderten Agent zurück.

Beispiel:

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

Beispiel für Direct Line-Tokencode abrufen

Im folgenden Beispiel wird ein Direct Line-Token für einen Copilot Studio-Agenten abgerufen.

/// <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 dasselbe wie die GET-Anfrage, die Sie zuvor gesehen haben.

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

Direct Line verwenden, um mit dem Agenten zu kommunizieren

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

Im folgenden Beispiel wird eine Unterhaltung gestartet und Nachrichten von einem Copilot Studio-Agent gesendet und 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. Sobald Sie gestartet haben, können Sie jede Unterhaltung durch die Kombination von token und conversationtId identifizieren und verbinden. 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 Antwort des Agents mithilfe derselben token und conversationId ab. Die abgerufenen Direct Line-Antwortaktivitäten enthalten sowohl Nachrichten des Benutzenden als auch des Agenten. Sie können Antwortaktivitäten nach dem Namen Ihres Agents filtern, um nur die Antwortnachricht des Agents 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

Möglicherweise müssen Sie Code hinzufügen, um das Direct Line-Token zu aktualisieren, wenn Ihre Anwendung eine lange Unterhaltung mit dem Agenten führt. Das Token läuft ab, kann jedoch aktualisiert werden, bevor es abläuft. Weitere Informationen finden Sie unter Direct Line Authentication.

Im folgenden Beispiel wird das Token einer vorhandenen Unterhaltung in Copilot Studio aktualisiert.

  // 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

Analyse der Gesprächsdaten vom Agenten

Nachdem Sie eine Unterhaltung mit dem Agenten begonnen haben, verwenden die Unterhaltungs-JSON-Nutzdaten die Standard-Direct Line-Aktivität des Microsoft Bot Framework. 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 Übergabeaktivität wird gesendet, wenn der Knoten "An Agent übertragen " erreicht wird. Weitere Informationen finden Sie unter Informationen zur Nutzlast der Übergabe-Aktivität.

Eine Willkommensnachricht auslösen

Damit Ihr Agent das Thema "Grußsystem" automatisch sendet, wenn ein Benutzer eine Unterhaltung startet, senden Sie eine Aktivität mit Type=event und Name=startConversation.