Exercice - Retourner des réponses enrichies avec des cartes adaptatives
Commençons par créer des modèles de carte adaptative pour que l’agent affiche les données dans ses réponses. Pour générer le modèle carte adaptative, vous utilisez les extensions d’aperçu de carte adaptative Visual Studio Code pour afficher facilement un aperçu de votre travail directement dans Visual Studio Code. L’utilisation de l’extension nous permet de créer un modèle de carte adaptative, avec des références à des données. Au moment de l’exécution, l’agent remplit l’espace réservé avec les données qu’il récupère à partir de l’API.
Télécharger le projet de démarrage
Commencez par télécharger l’exemple de projet. Dans un navigateur web :
Accédez à la page https://github.com/microsoft/learn-declarative-agent-api-plugin-adaptive-cards-typescript.
Si vous avez un compte GitHub :
Sélectionnez la liste déroulante Utiliser ce modèle et, dans le menu, choisissez Créer un référentiel.
Dans la liste des propriétaires disponibles, choisissez votre compte.
Nommez le dépôt da-ristorante-api.
Confirmez la création du dépôt à l’aide du bouton Créer un référentiel .
Attendez que GitHub crée le dépôt. Ensuite, copiez l’URL du dépôt.
Ouvrez une ligne de commande.
Dans une ligne de commande, remplacez le répertoire de travail par l’emplacement où vous souhaitez stocker le projet sur votre disque.
Clonez le référentiel à l’aide de la commande suivante :
git clone https://github.com/your-user/your-repo.Ouvrez le dossier cloné dans Visual Studio Code.
Si vous n’avez pas de compte GitHub :
Téléchargez le contenu du dépôt sous la forme d’un fichier ZIP.
Extrayez le contenu du fichier ZIP sur votre disque.
Ouvrez le dossier dans Visual Studio Code.
L’exemple de projet est un projet Microsoft 365 Agents Toolkit qui inclut un agent déclaratif avec une action générée avec un plug-in d’API. Le plug-in d’API se connecte à une API anonyme s’exécutant sur Azure Functions également incluse dans le projet. L’API appartient à un restaurant italien fictif et vous permet de parcourir le menu du jour et de passer des commandes.
Créer une carte adaptative pour un plat
Tout d’abord, créez une carte adaptative qui affiche des informations sur un seul plat.
Dans Visual Studio Code :
Dans la vue Explorer, créez un dossier nommé cartes.
Dans le dossier cartes , créez un fichier nommé dish.json. Collez le contenu suivant qui représente une carte adaptative vide :
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [] }Avant de continuer, créez un fichier de données pour la carte adaptative :
Ouvrez la palette de commandes en appuyant sur Ctrl+P (CMD+P sur macOS) sur le clavier. Tapez
>Adaptivepour rechercher les commandes liées à l’utilisation des cartes adaptatives.
Dans la liste, choisissez Carte adaptative : nouveau fichier de données. Visual Studio Code crée un fichier nommé dish.data.json.
Remplacez son contenu par une donnée qui représente un plat :
{ "id": 4, "name": "Caprese Salad", "description": "Juicy vine-ripened tomatoes, fresh mozzarella, and fragrant basil leaves, drizzled with extra virgin olive oil and a touch of balsamic.", "image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/caprese_salad.jpeg", "price": 10.5, "allergens": [ "dairy" ], "course": "lunch", "type": "dish" }Save your changes
Retour au fichier dish.json.
Dans l’objectif, sélectionnez Aperçu de la carte adaptative.
Visual Studio Code ouvre un aperçu du carte sur le côté. Lorsque vous modifiez le carte, vos modifications sont immédiatement visibles sur le côté.
Au tableau de corps , ajoutez un élément Container avec une référence à l’URL d’image stockée dans la propriété image_url .
{ "type": "Container", "items": [ { "type": "Image", "url": "${image_url}", "size": "large" } ] }Notez que la préversion carte se met automatiquement à jour pour afficher votre carte :
Ajouter des références à d’autres propriétés de plat. Le carte complet se présente comme suit :
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "Image", "url": "${image_url}", "size": "large" }, { "type": "TextBlock", "text": "${name}", "weight": "Bolder" }, { "type": "TextBlock", "text": "${description}", "wrap": true }, { "type": "TextBlock", "text": "Allergens: ${if(count(allergens) > 0, join(allergens, ', '), 'none')}", "weight": "Lighter" }, { "type": "TextBlock", "text": "**Price:** €${formatNumber(price, 2)}", "weight": "Lighter", "spacing": "None" } ] } ] }
Notez que pour afficher les allergènes, vous utilisez une fonction pour joindre les allergènes dans une chaîne. Si un plat n’a pas d’allergènes, vous n’en affichez aucun. Pour vous assurer que les prix sont correctement mis en forme, vous utilisez la fonction formatNumber qui nous permet de spécifier le nombre de décimales à afficher sur le carte.
Créer une carte adaptative pour le résumé de la commande
L’exemple d’API permet aux utilisateurs de parcourir le menu et de passer une commande. Créons une carte adaptative qui affiche le résumé de la commande.
Dans Visual Studio Code :
Dans le dossier cartes , créez un fichier nommé order.json. Collez le contenu suivant qui représente une carte adaptative vide :
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [] }Créez un fichier de données pour la carte adaptative :
Ouvrez la palette de commandes en appuyant sur Ctrl+P (CMD+P sur macOS) sur le clavier. Tapez
>Adaptivepour rechercher les commandes liées à l’utilisation des cartes adaptatives.
Dans la liste, choisissez Carte adaptative : nouveau fichier de données. Visual Studio Code crée un fichier nommé order.data.json.
Remplacez son contenu par une donnée qui représente le résumé de la commande :
{ "order_id": 6210, "status": "confirmed", "total_price": 25.48 }Save your changes
Retour au fichier order.json.
Dans l’objectif, sélectionnez Aperçu de la carte adaptative.
Ensuite, remplacez le contenu du fichier order.json par le code suivant :
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "TextBlock", "text": "Order Confirmation 🤌", "size": "Large", "weight": "Bolder", "horizontalAlignment": "Center" }, { "type": "Container", "items": [ { "type": "TextBlock", "text": "Your order has been successfully placed!", "weight": "Bolder", "spacing": "Small" }, { "type": "FactSet", "facts": [ { "title": "Order ID:", "value": "${order_id} " }, { "title": "Status:", "value": "${status}" }, { "title": "Total Price:", "value": "€${formatNumber(total_price, 2)}" } ] } ] } ] }Comme dans la section précédente, vous mappez chaque élément du carte à une propriété de données.
Importante
Notez l’espace de fin après ${order_id}. Cela est intentionnel, en raison d’un problème connu avec le rendu des numéros de cartes adaptatives. Pour le tester, supprimez l’espace et vérifiez que le nombre disparaît de l’aperçu.
Restaurez l’espace de fin afin que votre carte s’affiche correctement et enregistrez vos modifications.
Mettre à jour la définition du plug-in d’API
La dernière étape consiste à mettre à jour la définition du plug-in d’API avec des cartes adaptatives que Copilot doit utiliser pour afficher les données de l’API aux utilisateurs.
Ajouter une carte adaptative pour afficher un plat
Dans Visual Studio Code :
Ouvrez le fichier cartes/dish.json et copiez son contenu.
Ouvrez le fichier appPackage/ai-plugin.json .
À la propriété functions.getDishes.capabilities.response_semantics , ajoutez une nouvelle propriété nommée static_template et définissez son contenu sur la carte adaptative.
L’extrait de code complet ressemble à ceci :
{ "$schema": "https://aka.ms/json-schemas/copilot/plugin/v2.1/schema.json", "schema_version": "v2.1", "namespace": "ilristorante", "name_for_human": "Il Ristorante", "description_for_human": "See the today's menu and place orders", "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders", "functions": [ { "name": "getDishes", "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).", "capabilities": { "response_semantics": { "data_path": "$.dishes", "properties": { "title": "$.name", "subtitle": "$.description" }, "static_template": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ ...trimmed for brevity ] } } } }, { "name": "placeOrder", "description": "Places an order and returns the order details", "capabilities": { "response_semantics": { "data_path": "$", "properties": { "title": "$.order_id", "subtitle": "$.total_price" } } } } ], "runtimes": [ { "type": "OpenApi", "auth": { "type": "None" }, "spec": { "url": "apiSpecificationFile/ristorante.yml" }, "run_for_functions": [ "getDishes", "placeOrder" ] } ], "capabilities": { "localization": {}, "conversation_starters": [] } }Enregistrez vos modifications.
Ajouter un modèle de carte adaptative pour afficher le résumé de la commande
Dans Visual Studio Code :
Ouvrez le fichier cartes/order.json et copiez son contenu.
Ouvrez le fichier appPackage/ai-plugin.json .
À la propriété functions.placeOrder.capabilities.response_semantics , ajoutez une nouvelle propriété nommée static_template et définissez son contenu sur la carte adaptative.
Le fichier complet ressemble à ceci :
{ "$schema": "https://aka.ms/json-schemas/copilot/plugin/v2.1/schema.json", "schema_version": "v2.1", "namespace": "ilristorante", "name_for_human": "Il Ristorante", "description_for_human": "See the today's menu and place orders", "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders", "functions": [ { "name": "getDishes", "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).", "capabilities": { "response_semantics": { "data_path": "$.dishes", "properties": { "title": "$.name", "subtitle": "$.description" }, "static_template": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ ...trimmed for brevity ] } } } }, { "name": "placeOrder", "description": "Places an order and returns the order details", "capabilities": { "response_semantics": { "data_path": "$", "properties": { "title": "$.order_id", "subtitle": "$.total_price" }, "static_template": { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ ...trimmed for brevity ] } } } } ], "runtimes": [ { "type": "OpenApi", "auth": { "type": "None" }, "spec": { "url": "apiSpecificationFile/ristorante.yml" }, "run_for_functions": [ "getDishes", "placeOrder" ] } ], "capabilities": { "localization": {}, "conversation_starters": [] } }Enregistrez vos modifications.
Tester l’agent déclaratif avec le plug-in API dans Microsoft 365 Copilot
La dernière étape consiste à tester l’agent déclaratif avec le plug-in d’API dans Microsoft 365 Copilot.
Dans Visual Studio Code :
Dans la barre d’activités, choisissez Microsoft 365 Agents Toolkit.
Dans la section Comptes, vérifiez que vous êtes connecté à votre locataire Microsoft 365 avec Microsoft 365 Copilot.
Dans la barre d’activité, choisissez Exécuter et déboguer.
Sélectionnez la configuration Déboguer dans Copilot et démarrez le débogage à l’aide du bouton Démarrer le débogage .
Visual Studio Code génère et déploie votre projet sur votre locataire Microsoft 365 et ouvre une nouvelle fenêtre de navigateur web.
Dans le navigateur web :
Lorsque vous y êtes invité, connectez-vous avec le compte qui appartient à votre locataire Microsoft 365 avec Microsoft 365 Copilot.
Dans la barre latérale, sélectionnez Il Ristorante.
Choisissez l’entrée de conversation Qu’est-ce que c’est pour le déjeuner aujourd’hui ? et envoyez l’invite.
Lorsque vous y êtes invité, examinez les données que l’agent envoie à l’API et confirmez à l’aide du bouton Autoriser une seule fois .
Attendez que l’agent réponde. Notez que la fenêtre contextuelle d’une citation inclut désormais votre carte adaptative personnalisée avec des informations supplémentaires de l’API.
Passez une commande en tapant dans la zone de texte de l’invite : 1x spaghetti, 1x iced tea et envoyez l’invite.
Examinez les données que l’agent envoie à l’API et continuez à utiliser le bouton Confirmer .
Attendez que l’agent passe la commande et retourne le résumé de la commande. Notez que, comme l’API retourne un seul élément, l’agent le restitue à l’aide d’une carte adaptative et inclut le carte directement dans sa réponse.
Retour de Visual Studio Code et d’arrêter le débogage.
Basculez vers l’onglet Terminal et fermez tous les terminaux actifs.
