Copilot mobilen und benutzerdefinierten Apps hinzufügen

  • Artikel

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 einer benutzerdefinierten App verbinden, damit die Benutzenden der App direkt aus Ihrer App heraus mit dem Copiloten 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 Copiloten mit einer webbasierten App ist relativ einfach, da ein Codeschnipsel in Ihre App kopiert werden muss. Sowohl webbasierte Apps als auch native oder benutzerdefinierte Apps erfordern jedoch noch beträchtliche Entwicklerkenntnisse, um den Copiloten vollständig in Ihre App zu integrieren. Beide Verfahren werden in diesem Artikel beschrieben.

Anforderungen

Ihren Copiloten mit einer webbasierten App verbinden

  1. In Copilot Studio wählen Sie im Navigationsmenü unter Einstellungen die Option Kanäle.

  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.

    Copiloten zur webbasierten Anwendung hinzufügen.

Ihren Copiloten mit einer nativen oder benutzerdefinierten App verbinden

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 Sie eine Verbindung zu Azure Bot Service-Kanälen herstellen möchten, können Ihre Entwickler unter Befolgen der Anweisungen hier weitere Informationen erhalten Ihren Bot mit Azure Bot Service-Kanälen verbinden.

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:

Referenzen

Die Anweisungen in diesem Dokument beziehen sich auf folgendes Quellmaterial:

Copilot Studio-Copilot-Parameter abrufen

Um eine Verbindung zu dem Copiloten herzustellen, den Sie erstellt haben, müssen Sie den Namen und den Token-Endpunkt Ihres Copiloten abrufen, um ihn zu identifizieren.

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

    Rufen Sie den Namen des Copiloten ab.

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

  3. Wählen Sie mobile App.

    Kanal „Mobile App“.

  4. Wählen Sie neben Token-EndpunktKopieren aus. Sie benötigen diesen Endpunk für den Schritt Direct Line-Token erhalten.

    Rufen Sie die Copilot-Parameter ab.

Direct Line-Token erhalten

Um ein Gespräch mit Ihrem Copiloten 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 Anforderung erfolgreich ist, wird ein Direct Line-Token, eine Ablaufzeit und eine „conversationId“ für den angeforderten Copiloten zurückgegeben. Beispiel:

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

Beispielcodebeispiel

Das folgende Beispiel verwendet Beispiele aus dem Beispielcode für den Konnektor, um ein Direct Line-Token für einen Copilot Studio-Copiloten abzurufen.

/// <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-Anforderung, die wir zuvor gesehen haben.

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

Verwenden von Direct Line zur Konversation mit dem Copiloten

Nach dem Abrufen des Direct Line-Tokens sind Sie bereit, ein Gespräch mit Ihrem Copilot Studio-Copiloten über Direct Line zu 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 Konnektor-Beispielcode, um eine Unterhaltung zu beginnen und Nachrichten von einem Copilot Studio-Copiloten 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 Antwort des Copiloten mit derselben token und conversationId ab. Die abgerufen Direct Line-Antwortaktivitäten enthalten sowohl Benutzer- als auch Copilot-Nachrichten. Sie können Antwortaktivitäten nach dem Namen Ihres Copiloten filtern, um nur die Antwortnachricht des Copiloten 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 ein langes Gespräch mit dem Copiloten 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 der Konversationsnutzdaten vom Copiloten

Nach dem Starten einer Konversation mit dem Copiloten verwendet die Konversations-JSON-Nutzlast die standardmäßige Microsoft Bot Framework Direct Line-Aktivität. 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 Copilot das Begrüßungssystemthema automatisch senden soll, wenn ein Benutzender eine Konversation startet, können Sie eine Aktivität mit Type=event und Name=startConversation senden.