Copilot-Übergabe

Artikel
10/16/2024

Hinweis

Copilot-Übergabe ist nur in der öffentlichen Entwicklervorschau verfügbar.
Copilot-Übergabe wird nur in Einzelchats mit Bot unterstützt.

Copilot-Übergaben sind über Plug-Ins bereitgestellte Deep-Links, die den Chatkontext übernehmen und es Benutzern ermöglichen, ihren Chat mit Microsoft 365 Copilot nahtlos zu Ihrem Botdienst zu übertragen. Sie können Ihr Copilot-Nachrichtenerweiterungs-Plug-In erweitern, um eine Unterhaltung an Ihren benutzerdefinierten Engine-Agent zu übergeben, um Szenarien zu verarbeiten, in denen spezielle Kenntnisse oder Aktionen erforderlich sind, z. B. komplexe IT-Supportanfragen, detaillierte Produktanfragen oder interaktive Auftragsverwaltung.

In der folgenden Grafik sucht ein Benutzer mithilfe von Microsoft 365 Copilot nach Hilfe zu technischen Problemen und erhält Ergebnisse aus dem Unternehmensdataset. Der Benutzer findet die verfügbaren Informationen unzureichend und möchte die Interaktion mit einem Contoso-Bot-Plug-In fortsetzen. Wenn der Benutzer den Contoso-Bot auswählt, wird ein neuer Chat gestartet, und die Unterhaltung wird im Contoso-Bot fortgesetzt. Dieser nahtlose Wechsel von Microsoft 365 Copilot zum Contoso-Bot ohne Verlust des Konversationskontexts wird als Copilot-Übergabe bezeichnet.

Die grafische Darstellung zeigt die Übergabe der Unterhaltung zwischen Microsoft 365 Copilot und dem Contoso-Chatbot.

Funktionsweise der Copilot-Übergabe

Ein benutzerdefinierter Engine-Agent sendet einen Deep Link mit einem Fortsetzungstoken an Microsoft 365 Copilot. Der Deep Link-Abfrageparameter mit einem Fortsetzungstoken stellt sicher, dass auf alle Informationen aus Ihren Plug-In-Aufrufparametern verwiesen wird. Wenn der Benutzer den Deep Link auswählt, sendet Microsoft 365 Copilot einen Aufruf an den Bot mit dem Fortsetzungstoken, und der Bot setzt die Konversation dann basierend auf dem Kontext fort. Dieser Prozess ermöglicht einen nahtlosen Übergang von Microsoft 365 Copilot zu Ihrem benutzerdefinierten Engine-Agent, wobei die Kontinuität und der Kontext der Konversation beibehalten werden, wodurch die Benutzerfreundlichkeit optimiert wird.

Sie müssen eine Deep Link-URL mit einem continuation Abfrageparameter für die Aktionsschaltfläche erstellen und dem Parameter ein Fortsetzungstoken zuweisen, um den Übergabeprozess zu vereinfachen. Wenn der Benutzer die Aktionsschaltfläche auswählt, liest Microsoft Teams das Fortsetzungstoken aus der URL und initiiert einen Aufruf an den Bot. Der Bot oder das Plug-In verwendet das Fortsetzungstoken, um eine Antwort zu erstellen, die dem Benutzer dann im Plug-In-Chatfenster angezeigt wird.

Copilot-Übergabe aktivieren

Führen Sie die folgenden Schritte aus, um die Copilot-Übergabe in Teams zu aktivieren:

Konfigurieren einer Deep Link-URL: Erstellen Sie einen Deep-Link zu einem Chat , und fügen Sie und 28:<botId>continuationToken dem Deep Link-Format hinzu. Das Deep Link-Format muss sein https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}.

Beispiel:

{ 
"type": "Action.OpenUrl", 
"title": "Handoff to Bot", 
"url": "https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}" 
}

Die Action.OpenUrl -Eigenschaft ermöglicht es dem Benutzer, die Konversation an einen Bot zu übergeben. Wenn ein Benutzer die Aktionsschaltfläche auswählt, wird der Deep-Link aktiviert und ein neues Chatfenster mit dem Bot geöffnet. Der Bot empfängt einen Aufruf mit einer Nutzlast, die das Fortsetzungstoken aus der URL enthält und das Token verwendet, um den Kontext der Konversation beizubehalten.

Beispielnutzlast

{ 
 "name": "handoff/action", 
 "type": "invoke", 
 "timestamp": "2024-04-15T19:50:32.945Z", 
 "localTimestamp": "2024-04-15T19:50:32.945Z", 
 "id": "f:00000000-0000-0000-0000-000000000000",
 "channelId": "msteams", 
 "serviceUrl": "https://smba.trafficmanager.net/amer/", 
 "from": { 
     "id": "29:1jzORtjcfpYTLQDR9O4TyLz9LDwHskubQN1Ljc-aFO4L8dnZatjFpSw1PCGa-Mm-Jo4uLp67Lvekcjq2hkPoxdA", 
     "aadObjectId": "00000000-0000-0000-0000-000000000000" 
 }, 
 "conversation": { 
     "conversationType": "personal", 
     "tenantId": "00000000-0000-0000-0000-000000000000",
     "id": "a:13tOiSzRqeub3zaqoTHKpvOkk8Y1zFxk-g8WKdAUM2tjhTBFMt4RSuL8YWi7uwFNBmbxsyzYYktJEyfimYXYiEoplQ34aJs1y8trDb7EIcG09xOjSUieHVzFZ2b8tkagZ" 
 }, 
 "recipient": { 
     "id": "28:00000000-0000-0000-0000-000000000000", 
     "name": "NorthwindProducts" 
 }, 
 "entities": [ 
     { 
         "locale": "en-US", 
         "country": "US", 
         "platform": "Android", 
         "timezone": "America/Chicago", 
         "type": "clientInfo" 
     } 
 ], 
 "channelData": { 
     "tenant": { 
         "id": "00000000-0000-0000-0000-000000000000" 
     }, 
     "source": { 
         "name": "message" 
     }, 
     "legacy": { 
         "replyToId": "1:1_qLAAGcfze29QAWxzicc7gvR3vuNAlKvth08vavxYYs" 
     } 
 }, 
 "replyToId": "1713210583687", 
 "value": { 
     "continuation": "test-continuation-token" 
 }, 
 "locale": "en-US", 
 "localTimezone": "America/Chicago", 
 "rawTimestamp": "2024-04-15T19:50:32.945Z", 
 "rawLocalTimestamp": "2024-04-15T14:50:32.945-05:00", 
 "callerId": "urn:botframework:azure" 
}

Der handoff/action Aufruftyp ermöglicht es dem Bot, die Steuerung der Konversation an einen anderen Dienst zu übertragen oder eine bestimmte Aktion zu initiieren, die eine weitere Verarbeitung erfordert. Wenn der Bot die handoff/action Aufrufaktivität empfängt, verwendet er das Fortsetzungstoken, um alle erforderlichen Informationen nachzuschlagen, um die Konversation nahtlos fortzusetzen. Dies umfasst das Abrufen des Konversationsverlaufs, der Benutzereinstellungen oder eines anderen Kontexts, der für eine konsistente Erfahrung erforderlich ist.

Behandeln des Aufruftyps: Verwalten Sie in Ihrem Botcode den handoff/action Aufruf mithilfe des onInvokeActivity Handlers. Sie müssen die onInvokeActivity -Methode überschreiben, um den Aufruf zu verarbeiten. Wenn der Aufruf erfolgreich ist, muss der Bot den HTTP-status Code 200 zurückgeben. Wenn ein Fehler auftritt, muss der Bot mit einem geeigneten HTTP-status Code im Bereich von 400 oder 500- antworten. Wenn der Benutzer einen Fehler erhält, muss er warten und erneut versuchen, während die Fehler im Back-End-Dienst protokolliert werden.

Hinweis

Senden Sie keine Nutzlast mit dieser Antwort, da sie nicht im Chatfenster gerendert wird. Die Antworten, die auf dem Fortsetzungstoken basieren, müssen separat an den Benutzer gesendet werden.

Hier sehen Sie ein Beispiel für die Behandlung des Aufrufs in searchApp.ts der Datei:
```
         case "handoff/action": {
           // TODO: Save the continuation token and use it to process final response to user later
          return {status: 200}; // return just the http status
         }
```
Wenn der Bot den Aufruf empfängt, context.activity.value.continuation enthält die , die continuationToken in der Deep Link-URL festgelegt wurde. Wenn die App während der Übergabe nicht installiert wird, wird der Benutzer zum Teams Store umgeleitet, um die App zu installieren.

Bewährte Methoden

Der Bot muss Benutzer benachrichtigen, wenn sie nach dem Auswählen der Aktionsschaltfläche zum Botchat weitergeleitet werden, da es keine visuellen Hinweise gibt. Dies hilft bei der Verwaltung der Erwartungen, da es aufgrund von Netzwerklatenz und Verarbeitungszeit möglicherweise zu einer Verzögerung kommt, bevor der Bot eine Antwort zurückgibt. Für instance kann der Bot eine Reihe von Aktivitäten senden, um den Benutzer über den Fortschritt auf dem Laufenden zu halten:
```
await context.sendActivities([
  {
    type: ActivityTypes.Message,
    text: "Continuing conversation from copilot...",
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 1000 },
  {
    type: ActivityTypes.Message,
    text: `Fetching more details using the continuation token passed: ${continuationToken}`,
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 4000 },
  {
    type: ActivityTypes.Message,
    text: `Handoff successful!`,
  }
]);
```
Es wird empfohlen, den Lebenszyklus des Fortsetzungstokens zu verwalten, um sicherzustellen, dass es nach einem angemessenen Zeitraum abläuft, und Szenarien zu behandeln, in denen der Benutzer die Anforderung für das Fortsetzungstoken wiedergibt. Wenn beispielsweise das gleiche Token angezeigt wird, teilen Sie dem Benutzer mit, dass er eine neue Konversation mit dem Bot beginnen muss, da die Übergabe von copilot nicht fortgesetzt werden kann.

Codebeispiele

Beispielname	Beschreibung	Node.js
Northwind-Bestandsnachrichtenerweiterung	Dieses Beispiel ist eine Teams-Nachrichtenerweiterung, die als Plug-In für Microsoft 365 Copilot funktioniert. Es verfügt über copilot-Übergabe und ermöglicht Benutzern den Übergang ihres Chats von Microsoft 365 Copilot zu Northwind Database.	View

Freigeben über

Copilot-Übergabe

Funktionsweise der Copilot-Übergabe

Copilot-Übergabe aktivieren

Bewährte Methoden

Codebeispiele

Zusätzliche Ressourcen