Agenten in mobilen oder benutzerdefinierten Apps veröffentlichen

2025-06-27

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, 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 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. Beide Verfahren werden in diesem Artikel beschrieben.

Anforderungen

.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

Wählen Sie im Navigationsmenü in Copilot Studio Kanäle aus.
Wählen Sie die Kachel mobile App aus, um das Konfigurationsfenster zu öffnen.
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

Tipp

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

Referenzen

Die Anweisungen in diesem Dokument beziehen sich auf folgendes Quellmaterial:

Die Parameter Ihres Copilot Studio Agenten abrufen

Um eine Verbindung zu dem von Ihnen erstellten Agenten aufzubauen, müssen Sie zur Identifizierung den Namen und das Tokenendpunkt des Agenten abrufen.

Navigieren Sie in Copilot Studio zur Seite Übersicht Ihres Agenten und kopieren Sie seinen Namen.
Wählen Sie Kanäle>Mobile App aus.
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. 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, die Ablaufzeit und eine Unterhaltungs-ID für den angeforderten Agenten zurückgegeben.

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 mit der GET-Anforderung identisch, die wir zuvor gesehen haben.

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

Direct Line verwenden, um mit dem Agenten zu kommunizieren

Nach dem Abrufen des Direct Line-Tokens, sind Sie bereit, mit dem Copilot Studio-Agenten eine Unterhaltung mit Direct Line zu 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.

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

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

Rufen Sie die Antwort des Agents mit 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 vor Ablauf aktualisiert werden. Erfahren Sie mehr unter Direct Line-Authentifizierung.

Im folgenden Beispiel wird das Token für eine vorhandene Copilot Studio-Unterhaltung 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

Analysieren der Unterhaltungsdaten vom Agent

Nachdem Sie eine Unterhaltung mit dem Agenten begonnen haben, verwenden die Unterhaltungs-JSON-Nutzdaten die Standard-Direct Line-Aktivität des Microsoft Bot Frameworks. Weitere Informationen 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 das Begrüßungssystemthema automatisch senden soll, wenn ein Benutzer eine Konversation startet, können Sie eine Aktivität mit Type=event und Name=startConversation senden.