Partager via

Utiliser un chatbot classique comme compétence dans un bot Bot Framework

Nonte

Cet article s’applique aux chatbots classiques uniquement. Cette fonctionnalité n’est pas disponible dans la nouvelle expérience Copilot Studio.

Lorsque vous ajoutez un chatbot classique en tant que compétence avec un bot Bot Framework, le bot Bot Framework détermine si quelque chose que dit l’utilisateur correspond aux phrases déclencheurs du chatbot classique. S’il y a correspondance, le bot Bot Framework passe la conversation au chatbot classique. Le chatbot classique extrait toutes les entités et déclenche la rubrique correspondante.

Vous pouvez également transmettre une variable à un sujet de compétence Copilot Studio comme entrée à partir de Bot Framework Composer et utiliser les sorties qu’il renvoie.

Important

Vous devez disposer d’une licence Copilot Studio d’essai ou complète pour utiliser les chatbots classiques comme compétences. Cette capacité n’est pas disponible avec la licence Teams Copilot Studio.

Pour configurer votre chatbot classique en tant que compétence :

  1. Ajoutez le bot Bot Framework à la liste d’autorisation pour le chatbot classique.

  2. Téléchargez le manifeste de compétence pour le chatbot classique.

  3. Utilisez le manifeste de compétence téléchargé dans Bot Framework Composer pour créer une connexion entre les bots.

  4. Utilisez l’émulateur Bot Framework pour confirmer que le bot fonctionne en tant que compétence.

Conditions préalables

Ajouter votre bot Bot Framework à la liste d’autorisation pour votre chatbot classique

Ajoutez l’ID d’application du bot Bot Framework à la liste d’autorisation du chatbot classique que vous souhaitez utiliser comme compétence. Les bots doivent être dans le même locataire.

  1. Dans Bot Framework Composer, ouvrez le bot qui utilisera la compétence. Sélectionnez Configurer, puis Ressources de développement. Copiez l’ID dans ID d’application Microsoft.

  2. Dans Copilot Studio, ouvrez le chatbot classique que vous souhaitez utiliser comme compétence.

  3. Dans le menu de navigation, accédez à Paramètres et sélectionnez Sécurité. Sélectionnez ensuite Liste d’autorisation.

  4. Sélectionnez Ajouter un appelant autorisé.

  5. Collez l’ID d’application de votre bot Bot Framework et sélectionnez Suivant.

    Avertissement

    Un chatbot classique ne peut pas agir comme une compétence pour d’autres chatbots classiques. Si vous essayez d’ajouter un ID d’application appartenant à un bot Power Virtual Agent à la liste d’autorisation, vous obtenez une erreur. Vous ne pouvez ajouter un ID d’application qu’à un bot Bot Framework.

    Copilot Studio valide l’ID d’application du bot Bot Framework et confirme qu’il appartient à un bot déployé dans le même locataire.

  6. (Facultatif) Ajoutez un Nom d’affichage pour le bot que vous avez ajouté à la liste d’autorisation.

  7. Sélectionnez Enregistrer.

Le bot Bot Framework s’affiche par son nom d’affichage si vous en avez saisi un, ou par son ID d’application si vous n’avez pas saisi de nom d’affichage. Pour le supprimer ou le modifier à tout moment, sélectionnez l’icône à droite du nom complet ou de l’ID d’application du bot.

Note

Les bots Bot Framework ajoutés à la liste d’autorisation ne sont pas exportés dans le cadre du contenu du bot.

Téléchargez le manifeste de compétence chatbot classique pour votre chatbot classique

Les bots Bot Framework peuvent utiliser un manifeste de compétence Copilot Studio pour configurer une connexion au chatbot classique qui a produit le manifeste.

Tous les chatbots classiques ont des manifestes de compétence. Un manifeste de fichier est un fichier JSON qui inclut le nom, l’interface et les phrases déclencheurs de la compétence.

Un bot Bot Framework peut utiliser un manifeste de compétence pour savoir quand déclencher le chatbot classique (par exemple, en réponse à quelque chose qu’un utilisateur lui dit).

Les manifestes de compétence Copilot Studio suivent la version 2.2 du schéma de manifeste de compétence Bot Framework et se composent des fichiers intents.lu et manifest.json.

Un bot Bot Framework peut décider si un chatbot classique doit gérer la demande de l’utilisateur, en fonction des données du manifeste. Il transmet au chatbot classique tout ce que l’utilisateur a dit. Ensuite, le chatbot classique met en correspondance ce que l’utilisateur a dit avec une rubrique Copilot Studio, extrait toutes les entités nécessaires au remplissage des emplacements et déclenche la rubrique Copilot Studio.

Les manifestes de compétence Copilot Studio sont automatiquement générés et mis à jour. Un chatbot classique a deux manifestes de compétence :

  • Manifeste de test : permet au bot Bot Framework de se connecter à la version de test de votre chatbot classique. Utilisez le manifeste de test pour valider les modifications apportées à votre compétence avant de la publier.

    • Le manifeste de test est immédiatement disponible pour chaque chatbot classique nouvellement créé.
    • Il est automatiquement mis à jour pour prendre en compte les modifications chaque fois que vous enregistrez votre chatbot classique.

  • Manifeste publié : permet au bot Bot Framework de se connecter à la version publiée de votre chatbot classique.

    • Le manifeste publié n’est disponible que pour les chatbots classiques qui ont été publiés au moins une fois.
    • Il est automatiquement mis à jour pour prendre en compte les modifications chaque fois que vous publiez votre agent.

Nonte

Le Manifeste publié n’est pas disponible pour les chatbots classiques qui n’ont jamais été publiés.

Pour générer le Manifeste publié de votre bot, publiez votre chatbot classique.

Les deux manifestes de compétence se trouvent dans le volet Gérer la liste d’autorisations.

Les manifestes de compétences sont également affichés sur la page Détails du copilote. Dans le menu de navigation, sélectionnez Paramètres, puis Détails. La page Détails affiche d’autres métadonnées telles que ID d’environnement, ID du locataire et ID d’application du bot.

Pour télécharger un manifeste, sélectionnez-le. Il est téléchargé en tant que fichier .zip intitulé _<nom du bot>manifest pour le Manifeste publié, ou <nom du bot>test__manifest pour le Manifeste de test.

Nonte

Le manifeste de compétence n’inclut pas les rubriques système ni les boîtes de dialogue Composer ajoutées à un chatbot classique. Seules les rubriques créées par les auteurs du copilote et les déclencheurs d’intention Composer ajoutés par les auteurs au bot sont incluses.

Se connecter à une compétence Copilot Studio dans Composer

Utilisez les manifestes de compétence de bot Copilot Studio pour créer une connexion de compétence dans votre bot Bot Framework dans Composer.

  1. Dans un projet Bot Framework Composer, sélectionnez + Ajouter, puis Se connecter à une compétence.

  2. Recherchez et sélectionnez une archive de manifeste.zip Copilot Studio, puis sélectionnez Suivant.

  3. Sélectionnez les rubriques ou intentions dans votre chatbot classique que vous souhaitez ajouter à votre bot Bot Framework, puis sélectionnez Suivant.

  4. Examinez et modifiez les phrases déclencheurs pour votre chatbot classique, puis sélectionnez Suivant.

  5. Veillez à ce que Utiliser Orchestrator pour les projets multi-bots est sélectionné, puis sélectionnez Continuer.

  6. Vérifiez que la compétence Copilot Studio est correctement ajoutée à votre bot Bot Framework et qu’un nouveau déclencheur avec le nom de votre chatbot classique apparaît dans le projet dans Composer.

Localiser la rubrique dans le manifeste des compétences

Utilisez un événement pour déclencher un sujet Copilot Studio dans la compétence. Pour appeler un sujet spécifique depuis Composer, reportez-vous au sujet par le nom de l’événement associé dans le manifeste de compétence.

  1. Sélectionnez l’action Connecter à une compétence.

  2. Sous Nom de la boîte de dialogue de compétence, sélectionnez Afficher le manifeste des compétences.

  3. Recherchez des activités dans le manifeste. Cette propriété contient des propriétés imbriquées représentant les rubriques disponibles dans votre chatbot classique.

  4. Recherchez la rubrique que vous voulez appeler et recherchez sa propriété name. Quand la compétence Copilot Studio reçoit un événement avec ce nom, elle déclenche la rubrique.

    Dans cet exemple, le nom de l’activité de l’événement est dispatchTo_new_topic_87609dabd86049f7bc6507c6f7263aba_33d.

Appeler un sujet de compétence Copilot Studio

Plutôt que d’appeler directement n’importe quel sujet de compétence Copilot Studio, au lieu de vous fier à ce qu’un utilisateur dit pour le déclencher. Vous pouvez appeler directement uniquement les sujets Copilot Studio répertoriés dans le manifeste de compétence.

  1. Dans le canevas de création de Composer, sélectionnez Ajouter, puis sélectionnez Accéder aux ressources externes, puis sélectionnez Se connecter à une compétence.

  2. Dans la liste Nom de la boîte de dialogue de compétence, sélectionnez votre chatbot classique.

  3. Recherchez le nom de l’activité de l’événement pour la rubrique du chatbot classique à appeler. Copiez la valeur, en omettant les guillemets, et enregistrez-la pour l’utiliser dans les étapes suivantes.

  4. Sélectionnez Fermer.

  5. Dans la section Activité, sélectionnez Afficher le code.

  6. Tapez ou collez le code suivant. Remplacez TOPIC_ACTIVITY_NAME par le nom de l’activité d’événement de votre sujet. Assurez-vous qu’il n’y a pas de guillemets dans la propriété name.

    [Activity
    type = event
    name = TOPIC_ACTIVITY_NAME
]

Transmettre une variable d’entrée à un sujet de compétence Copilot Studio

Bot Framework Composer peut transmettre une variable à un sujet de compétence Copilot Studio en tant qu’entrée. Pour savoir comment créer des rubriques Copilot Studio qui acceptent des variables d’entrée, voir Utiliser des variables.

Si vous disposez d’un sujet Copilot Studio qui peut recevoir une variable d’entrée répertoriée dans votre manifeste de compétences, vous pouvez lui transmettre une variable Composer.

  1. Dans le canevas de création de Composer, sélectionnez Ajouter, puis sélectionnez Accéder aux ressources externes, puis sélectionnez Se connecter à une compétence.

  2. Dans la liste Nom de la boîte de dialogue de compétence, sélectionnez votre chatbot classique.

  3. Recherchez le nom de l’activité de l’événement pour la rubrique du chatbot classique à appeler. Copiez la valeur, en omettant les guillemets, et enregistrez-la pour l’utiliser dans les étapes suivantes.

  4. Recherchez la propriété value du sujet. La propriété value contient une propriété $ref. Copiez la valeur (sans guillemets) et enregistrez-la pour l’utiliser à l’étape suivante.

    Avertissement

    Si un sujet Copilot Studio n’a pas d’entrées, il ne contiendra pas de propriété value.

  5. Recherchez la propriété definitions, puis recherchez une propriété imbriquée qui correspond à la valeur $ref que vous avez trouvée à l’étape précédente. Notez les noms et les types des entrées du sujet Copilot Studio. Vous les utiliserez dans les étapes suivantes.

  6. Sélectionnez Fermer.

  7. Sous la section Activité, sélectionnez Afficher le code.

  8. Tapez ou collez le code suivant. Remplacez ces valeurs :

    1. Remplacez TOPIC_ACTIVITY_NAME par le nom de l’activité d’événement de votre sujet.
    2. Remplacez PVA_INPUT_VARIABLE par une variable d’entrée de votre sujet.
    3. Remplacez COMPOSER_INPUT_VARIABLE par une variable Composer qui fournira une valeur.
    [Activity
    Type = event
    Name = TOPIC_ACTIVITY_NAME
    Value = ${addProperty(json("{}"), 'PVA_INPUT_VARIABLE', COMPOSER_INPUT_VARIABLE)}
]

    Dans cet exemple, la variable Composer dialog.storeLocation fournit une valeur à la variable d’entrée pva_StoreLocation dans la rubrique du chatbot classique dispatchTo_new_topic_127cdcdbbb4a480ea113c5101f309089_21a34f16.

Recevoir une variable de sortie d’un sujet de compétence Copilot Studio

Il est possible de recevoir des sorties d’un sujet de compétence Copilot Studio dans Composer. Pour savoir comment créer des rubriques Copilot Studio qui renvoient des sorties, voir Utiliser des variables.

  1. Dans le canevas de création de Composer, sélectionnez Ajouter, puis sélectionnez Accéder aux ressources externes, puis sélectionnez Se connecter à une compétence.

  2. Dans la liste Nom de la boîte de dialogue de compétence, sélectionnez votre chatbot classique.

  3. Recherchez le nom de l’activité de l’événement pour la rubrique de votre chatbot classique à appeler. Copiez la valeur, en omettant les guillemets, et enregistrez-la pour l’utiliser dans les étapes suivantes.

  4. Recherchez la propriété resultValue du sujet. La propriété resultValue contiendra une propriété $ref. Copiez la valeur (sans guillemets) et enregistrez-la pour l’utiliser à l’étape suivante.

    Avertissement

    Si un sujet Copilot Studio n’a pas de sorties, il ne contiendra pas de propriété resultValue.

  5. Recherchez la propriété definitions, puis recherchez une propriété imbriquée qui correspond à la valeur $ref que vous avez trouvée à l’étape précédente. Notez les noms et les types des variables de sortie du sujet Copilot Studio. Vous les utiliserez dans les étapes suivantes.

    Dans cet exemple, la rubrique Copilot Studio renvoie deux sorties de type Chaîne, pva_State et pva_Item.

  6. Sélectionnez Fermer.

  7. Dans la section Activité, sélectionnez Afficher le code.

  8. Tapez ou collez le code suivant. Remplacez TOPIC_ACTIVITY_NAME par le nom de l’activité d’événement de votre sujet. Assurez-vous qu’il n’y a pas de guillemets dans la propriété name.

    [Activity
    type = event
    name = TOPIC_ACTIVITY_NAME
]

  9. Sous la zone du code, définissez Propriété sur une variable Composer pour recevoir et stocker les valeurs de sortie d’un sujet de compétence Copilot Studio.

  10. Dans le canevas de création de Composer, sélectionnez Ajouter, puis sélectionnez Gérer les propriétés, puis sélectionnez Définir les propriétés.

  11. Définissez Propriété sur la valeur Composer qui doit stocker la valeur extraite. Définissez ensuite Valeur sur la variable Composer dans laquelle vous avez stocké les sorties de sujet.

    Dans cet exemple, les valeurs de sortie de dialog.skillResult.pvaState et dialog.skillResult.pvaItem sont extraites dans de nouvelles variables Composer dialog.State et dialog.Item.

Tester votre chatbot classique en tant que compétence avec un bot Bot Framework

Utilisez l’émulateur Bot Framework pour tester que votre bot Bot Framework appelle correctement un chatbot classique en tant que compétence.

Important

Votre bot Bot Framework doit être ajouté à la liste d’autorisation du chatbot classique pour que la connexion de compétence fonctionne.

Mettre à jour un bot Bot Framework à plusieurs locataires en un bot à locataire unique

L’illustration suivante montre le scénario dans lequel un bot Bot Framework basé sur le SDK Bot Framework appelle un chatbot classique pour l’utiliser comme compétence.

Illustration montrant les interactions entre un bot Bot Framework et un chatbot classique.

Le bot Bot Framework et le chatbot classique ont tous deux un enregistrement d’application Microsoft Entra ID, qui est référencé par les instances du bot Azure. Ces enregistrements d’application Microsoft Entra ID ont été créés en tant que multilocataire. Le bot Bot Framework demande un jeton à partir du locataire Bot Framework et utilise ce jeton pour s’authentifier dans Copilot Studio à l’aide d’Azure Bot Service. Copilot Studio utilise le même mécanisme pour contacter le bot Bot Framework.

L’enregistrement d’application du chatbot Copilot Studio est maintenant créé en tant que locataire unique ; par conséquent, cette communication ne fonctionne plus. Microsoft Entra ID refuse de créer des jetons pour les enregistrements d’application à locataire unique qui ne se trouvent pas dans le même locataire.

En outre, Copilot Studio valide le jeton entrant et rejette les demandes imprévues des locataires, comme l’ID de locataire dans lequel l’enregistrement d’application du chatbot traditionnel a été créé.

Pour résoudre ce problème, il existe deux solutions possibles.

Chatbots classiques dans le même locataire que le bot Bot Framework

Dans les scénarios où le chatbot Copilot Studio est déjà déployé dans le même locataire que le bot Bot Framework et n’est utilisé que par ce bot, mettez à jour le bot vers une configuration à locataire unique, puis redéployez votre bot Bot Framework. Pour plus d’informations sur la configuration d’un bot Bot Framework pour un locataire unique, consultez Approvisionner et publier un bot.

Le chatbot Copilot Studio ne peut pas être mis à jour vers un locataire unique

Dans les scénarios où le chatbot Copilot Studio est déjà déployé dans le même locataire que le bot Bot Framework, mais que le bot ne peut pas être mis à jour vers un locataire unique, vous devez mettre à jour le code dans le bot Bot Framework pour créer le jeton afin de communiquer avec le chatbot Copilot Studio. Le jeton doit être créé pour le locataire dans lequel le chatbot Copilot Studio a également été créé. En outre, la réponse doit être acceptée, ce qui nécessite probablement que vous suiviez les étapes décrites dans Convertir une compétence existante de multilocataire à locataire unique.

En savoir plus