Partager via

Transfert de copilote

  • Article

Remarque

Les transfert Copilot sont des liens profonds fournis par un plug-in qui transfèrent le contexte de conversation, ce qui permet aux utilisateurs de passer en toute transparence de leur conversation avec Copilot pour Microsoft 365 vers votre service de bot. Vous pouvez améliorer votre plug-in d’extension de message Copilot pour transmettre une conversation à votre copilot de moteur personnalisé afin de gérer des scénarios où des connaissances ou des actions spécialisées sont requises, telles que des requêtes de support informatique complexes, des demandes détaillées sur les produits ou une gestion interactive des commandes.

Dans le graphique suivant, un utilisateur recherche de l’aide sur les problèmes techniques à l’aide de Copilot et reçoit les résultats du jeu de données d’entreprise. L’utilisateur trouve les informations disponibles insuffisantes et souhaite poursuivre l’interaction avec un plug-in de bot Contoso. Lorsque l’utilisateur sélectionne le bot Contoso, une nouvelle conversation démarre et la conversation continue dans le bot Contoso. Ce passage transparent de Copilot au bot Contoso, sans perdre le contexte de conversation, est appelé un transfert de copilote.

Le gif montre le transfert de conversation entre le copilote pour Microsoft 365 et le bot de conversation Contoso.

Fonctionnement du transfert de copilote

Un copilote de moteur personnalisé envoie un lien profond avec un jeton de continuation à Copilot pour Microsoft 365. Le paramètre de requête de lien profond avec un jeton de continuation garantit que toutes les informations de vos paramètres d’appel de plug-in sont référencées. Lorsque l’utilisateur sélectionne le lien profond, Copilot envoie un appel d’appel au bot avec le jeton de continuation, puis le bot reprend la conversation en fonction du contexte. Ce processus permet une transition transparente de Copilot pour Microsoft 365 à votre copilote moteur personnalisé, en conservant la continuité et le contexte de la conversation, ce qui optimise l’expérience utilisateur.

Capture d’écran montrant le flux de transfert entre l’utilisateur, Copilot, le plug-in, Teams et le bot.

Vous devez créer une URL de lien profond avec un continuation paramètre de requête pour le bouton d’action et affecter un jeton de continuation au paramètre pour faciliter le processus de transfert. Lorsque l’utilisateur sélectionne le bouton d’action, Microsoft Teams lit le jeton de continuation à partir de l’URL et lance un appel d’appel au bot. Le bot ou le plug-in utilise le jeton de continuation pour créer une réponse, qui est ensuite affichée à l’utilisateur dans la fenêtre de conversation du plug-in.

Activer le transfert de copilote

Pour activer le transfert de copilote dans Teams, procédez comme suit :

  1. Configurer une URL de lien profond : créez un lien profond vers une conversation et ajoutez et 28:<botId>continuationToken au format de lien profond. Le format de lien profond doit être https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}.

    Exemple :

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

    La Action.OpenUrl propriété permet à l’utilisateur de transmettre la conversation à un bot. Lorsqu’un utilisateur sélectionne le bouton d’action, le lien profond est activé et ouvre une nouvelle fenêtre de conversation avec le bot. Le bot reçoit un appel d’appel avec une charge utile, qui contient le jeton de continuation de l’URL et utilise le jeton pour conserver le contexte de la conversation.

    Exemple de charge utile

    { 
 "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" 
}

    Le handoff/action type d’appel permet au bot de transférer le contrôle de la conversation à un autre service ou de lancer une action spécifique qui nécessite un traitement supplémentaire. Lorsque le bot reçoit l’activité handoff/action d’appel, il utilise le jeton de continuation pour rechercher toutes les informations nécessaires pour poursuivre la conversation en toute transparence. Cela implique la récupération de l’historique des conversations, des préférences utilisateur ou de tout autre contexte nécessaire pour fournir une expérience cohérente.

  2. Gérer le type d’appel : dans le code de votre bot, gérez l’appel à l’aide handoff/action du onInvokeActivity gestionnaire . Dans le code de votre bot, gérez l’appel handoff/action à l’aide du onInvokeActivity gestionnaire . Vous devez remplacer la onInvokeActivity méthode pour gérer l’appel d’appel. Si l’appel d’appel réussit, le bot doit retourner un code d’état HTTP de 200. En cas d’erreur, le bot doit répondre avec un code d’état HTTP approprié dans la plage de 400 ou 500. Si l’utilisateur reçoit une erreur, il doit attendre et réessayer pendant que les erreurs sont enregistrées dans le service principal.

    Remarque

    N’envoyez aucune charge utile avec cette réponse, car elle ne s’affiche pas dans la fenêtre de conversation. Les réponses basées sur le jeton de continuation doivent être envoyées séparément à l’utilisateur.

    Voici un exemple de gestion de l’appel d’appel dans le searchApp.ts fichier :

             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
         }

    Lorsque le bot reçoit l’appel d’appel, context.activity.value.continuation contient le continuationToken qui a été défini dans l’URL de lien profond. Si l’application n’est pas installée pendant le transfert, l’utilisateur est redirigé vers teams Store pour installer l’application.

Meilleures pratiques

  • Le bot doit avertir les utilisateurs lorsqu’ils sont dirigés vers la conversation du bot après avoir sélectionné le bouton d’action, car il n’y a aucune indication visuelle. Cela permet de gérer les attentes, car il peut y avoir un délai avant que le bot retourne une réponse en raison de la latence du réseau et du temps de traitement. Par exemple, le bot peut envoyer une série d’activités pour tenir l’utilisateur informé de la progression :

    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!`,
  }
]);

  • Nous vous recommandons de gérer le cycle de vie du jeton de continuation pour vous assurer qu’il expire après une période raisonnable et de gérer les scénarios où l’utilisateur rejoue la demande de jeton de continuation. Par exemple, si le même jeton apparaît, indiquez à l’utilisateur qu’il doit démarrer une nouvelle conversation avec le bot, car le transfert de copilote ne peut pas continuer.

Exemples de code

Exemple de nom Description Node.js
Extension de message d’inventaire Northwind Cet exemple est une extension de message Teams qui fonctionne comme un plug-in pour Microsoft 365 Copilot. Il propose le transfert de copilote et permet aux utilisateurs de passer de Copilot pour Microsoft 365 à Northwind Database. View