Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Note
In diesem Artikel werden Funktionen beschrieben, die in Agents oder Agent-Flows verwendet werden, die von der Standardumgebung unterstützt werden.
Verbinden Sie einen veröffentlichten Copilot Studio-Agenten mit Ihrer mobilen oder benutzerdefinierten App, damit Nutzer mit dem Agenten interagieren können, ohne die App zu verlassen.
Wählen Sie die Integration, die zu Ihrer App passt:
- Web-Embed-Code: Fügen Sie die bereitgestellte Chat-Oberfläche einer webbasierten App hinzu.
- Direct Line: Senden und Empfangen von Aktivitäten programmgesteuert von einer nativen App, einer benutzerdefinierten Weboberfläche oder einem Adapter zu einem anderen Dienst.
Für eine separate SDK-basierte Integration erfahren Sie mehr unter Integrieren von Web- oder nativen Apps mit dem Microsoft 365 Agents SDK.
Prerequisites
- Ein veröffentlichter Copilot Studio-Agent. Weitere Informationen unter Ihren Agent veröffentlichen und bereitstellen
- Für die C#-Beispiele werden ein unterstütztes .NET SDK und die NuGet-Pakete Microsoft.Bot.Connector.DirectLine und Microsoft.Rest.ClientRuntime benötigt. Diese Beispiele verwenden
System.Net.Http.JsonundSystem.Text.Json.Serializationfür die Token-Antwort. - Entwicklungstools, die zu Ihrer App passen. Die .NET-Voraussetzungen gelten nur für die C#-Beispiele, nicht für jede Integration.
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
Tip
In diesem Abschnitt wird zwar beschrieben, wie Sie eine Verbindung mit einer mobilen App herstellen, aber Sie können denselben Prozess auf benutzerdefinierte oder systemeigene Apps wie IoT -Apps (Internet of Things) anwenden.
Um eine Verbindung mit den Azure Bot Service-Kanälen herzustellen, erfahren Sie mehr unter Veröffentlichen eines Agenten auf Azure Bot Service-Kanälen.
Important
Sie benötigen Softwareentwicklungskenntnisse, um die Anweisungen in diesem Abschnitt zu befolgen. Die Anweisungen setzen ein für erfahrene IT-Fachleute angemessenes Maß an Fachwissen voraus, beispielsweise für IT-Administratoren oder Entwickler, die über fundierte Kenntnisse in Bezug auf Entwicklertools, Dienstprogramme und IDEs (integrierte Entwicklungsumgebungen) verfügen.
References
Die Anweisungen in diesem Artikel verwenden die folgenden Verweise:
- 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.
Wechseln Sie in Copilot Studio zur Seite Overview Ihres Agents, und kopieren Sie den Namen Ihres Agenten.
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 ein Gespräch mit Ihrem Agenten zu beginnen, erhalten Sie ein Direct Line-Token, indem Sie eine GET-Anfrage an den Token-Endpunkt senden, den Sie aus Copilot Studio kopiert haben. Dieser Endpunkt ist der Copilot Studio-Token-Endpunkt, nicht der Direct Line-Endpunkttokens/generate. Verwenden Sie das zurückgegebene Token für nachfolgende Direct Line-Anfragen.
Ein Direct Line-Token gewährt Zugriff auf eine Konversation; es handelt sich nicht um ein Endnutzer-Anmeldetoken. Hinterlegen Sie kein Direct Line-Geheimnis im Code des Browsers oder der mobilen App. Erfahren Sie mehr über Direct Line Authentifizierung.
GET <TokenEndpoint>
Wenn die Anfrage erfolgreich ist, gibt der Endpunkt ein Token zurück, dessen Lebensdauer in Sekunden in expires_in angegeben ist, und ein conversationId. Verwenden Sie die zurückgegebene Gültigkeitsdauer, anstatt eine feste Verfallsdauer anzunehmen.
{
"token": "<DirectLineToken>",
"expires_in": 3600,
"conversationId": "<ConversationId>"
}
Beispiel für Direct Line-Tokencode abrufen
Füge deiner Anwendungsklasse die folgende Methode und den Antworttyp hinzu. Import System.Net.Http.Json und System.Text.Json.Serialization.
Die Methode akzeptiert einen HttpClient, der vom Aufrufer verwaltet wird, und gibt eine Fehler zurück, wenn der Endpunkt kein brauchbares Token zurückgibt. HTTP- und JSON-Fehler werden auf den Aufrufer weitergeleitet.
public static async Task<DirectLineToken> GetTokenAsync(
HttpClient httpClient, string tokenEndpoint)
{
var response = await httpClient.GetFromJsonAsync<DirectLineToken>(
tokenEndpoint);
if (response is null || string.IsNullOrWhiteSpace(response.Token))
{
throw new InvalidOperationException(
"The token endpoint returned no Direct Line token.");
}
return response;
}
public sealed class DirectLineToken
{
[JsonPropertyName("token")]
public string Token { get; set; } = string.Empty;
[JsonPropertyName("expires_in")]
public int ExpiresIn { get; set; }
[JsonPropertyName("conversationId")]
public string ConversationId { get; set; } = string.Empty;
}
Direct Line verwenden, um mit dem Agenten zu kommunizieren
Nachdem Sie ein Token abgerufen haben, verwenden Sie Direct Line, um eine Konveration zu starten und Aktivitäten zu senden und zu empfangen. Erfahren Sie mehr in der Bot Framework Direct Line API.
Die folgenden Schnipsel gehören zur gleichen asynchronen Methode in der Anwendungsklasse, die GetTokenAsync enthält. Import Microsoft.Bot.Connector.DirectLine und System.Linq. Ersetzen Sie <TokenEndpoint> und <AgentName> durch die Werte Ihres Agenten und geben Sie anstelle von <UserId>eine app-spezifische Benutzerkennung an.
Hol dir ein Token, initialisiere ein
DirectLineClient, und starte ein Gespräch. Behalten Sie die Client- und Unterhaltungs-ID für die folgenden Vorgänge im Gültigkeitsbereich:using var httpClient = new HttpClient(); var tokenResponse = await GetTokenAsync(httpClient, "<TokenEndpoint>"); using var directLineClient = new DirectLineClient(tokenResponse.Token); var conversation = await directLineClient.Conversations.StartConversationAsync(); string conversationId = conversation.ConversationId; string? watermark = null; string agentName = "<AgentName>";Senden einer Nachricht an diese Unterhaltung:
string inputMessage = "Hello"; await directLineClient.Conversations.PostActivityAsync( conversationId, new Activity { Type = ActivityTypes.Message, From = new ChannelAccount { Id = "<UserId>" }, Text = inputMessage, TextFormat = "plain" });Rufen Sie Aktivitäten ab, indem Sie denselben Client und dieselbe Konversations-ID verwenden. Das Ergebnis kann sowohl Nutzer- als auch Agentenaktivitäten enthalten. Dieses Beispiel zeigt Nachrichtenaktivitäten für den konfigurierten Agentnamen:
var response = await directLineClient.Conversations.GetActivitiesAsync( conversationId, watermark); watermark = response.Watermark ?? watermark; foreach (var activity in response.Activities.Where(activity => activity.Type == ActivityTypes.Message && string.Equals(activity.From?.Name, agentName, StringComparison.Ordinal))) { Console.WriteLine(activity.Text); }Wiederhole die Empfangsoperation, um Aktivitäten zu sammeln, die später eintreffen; eine einzelne Anfrage enthält möglicherweise noch nicht die Antwort des Agenten. Übergebe das neueste Watermark bei jeder Anfrage und behalte den vorherigen Wert bei, falls die Antwort keines liefert. Erfahren Sie mehr unter Aktivitäten vom Bot erhalten.
Der Nachrichtenfilter ist nur zur Anzeige gedacht. Deine App muss andere Aktivitätstypen, einschließlich Übergabe-Events, separat behandeln.
Direct Line-Token aktualisieren
Für ein längeres Gespräch aktualisieren Sie das Token, bevor es abläuft, und verwenden Sie den zurückgegebenen expires_in Wert zur Planung der Aktualisierung. Ein abgelaufenes Token kann nicht aktualisiert werden. Erfahren Sie mehr über Direct Line Authentifizierung.
Im folgenden Beispiel wird das Token einer vorhandenen Unterhaltung in Copilot Studio aktualisiert.
var refreshedTokenResponse =
await directLineClient.Tokens.RefreshTokenAsync();
using var refreshedClient = new DirectLineClient(refreshedTokenResponse.Token);
Verwenden Sie refreshedClient für weitere Operationen mit dem bestehenden conversationId und Wasserzeichen. Entsorgen Sie Clients, wenn Ihre App sie nicht mehr benötigt.
Unterhaltungsnutzdaten vom Agent analysieren
Nachdem Sie eine Unterhaltung mit dem Agenten begonnen haben, verwenden die Unterhaltungs-JSON-Nutzdaten die Standard-Direct Line-Aktivität des Microsoft Bot Framework. Erfahren Sie mehr in der Bot Framework Direct Line API.
Übergabeaktivität handhaben
Wenn Ihre Anwendung an einen Live-Agent-Anbieter übergeben muss, verarbeiten Sie die Übergabeaktivität, die bei Ausführung des Knotens Übertragen an Agent gesendet wird. Um mehr zu erfahren, siehe Beispiel für die Payload einer Übergabenachricht.
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.