Exercice - Créer un agent déclaratif avec un plug-in d’API
L’extension d’un agent déclaratif avec des actions lui permet de récupérer et de mettre à jour des données stockées dans des systèmes externes en temps réel. À l’aide de plug-ins d’API, vous pouvez vous connecter à des systèmes externes via leurs API pour récupérer et mettre à jour les informations.
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-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 et une API anonyme s’exécutant sur Azure Functions. L’agent déclaratif est identique à un agent déclaratif nouvellement créé à l’aide du Kit de ressources Microsoft 365 Agents. L’API appartient à un restaurant italien fictif et vous permet de parcourir le menu du jour et de passer des commandes.
Examiner la définition de l’API
Tout d’abord, examinez la définition de l’API du restaurant italien.
Dans Visual Studio Code :
Dans la vue Explorer, ouvrez le fichier appPackage/apiSpecificationFile/ristorante.yml. Le fichier est une spécification OpenAPI qui décrit l’API du restaurant italien.
Recherchez la propriété servers.url
servers: - url: http://localhost:7071/api description: Il Ristorante API serverNotez qu’il pointe vers une URL locale qui correspond à l’URL standard lors de l’exécution Azure Functions localement.
Recherchez la propriété paths , qui contient deux opérations : /dishes pour récupérer le menu du jour et /orders pour passer une commande.
Importante
Notez que chaque opération contient la propriété operationId qui identifie de manière unique l’opération dans la spécification de l’API. Copilot exige que chaque opération ait un ID unique afin qu’elle sache quelle API elle doit appeler pour des invites utilisateur spécifiques.
Examiner l’implémentation de l’API
Examinez ensuite l’exemple d’API que vous utilisez dans cet exercice.
Dans Visual Studio Code :
Dans la vue Explorer, ouvrez le fichier src/data.json. Le fichier contient un élément de menu fictif pour notre restaurant italien. Chaque plat se compose de :
- nom
- description
- lien vers une image,
- prix
- dans quel cours il est servi,
- type (plat ou boisson),
- éventuellement une liste d’allergènes
Dans cet exercice, les API utilisent ce fichier comme source de données.
Ensuite, développez le dossier src/functions . Notez deux fichiers nommés dishes.ts et placeOrder.ts. Ces fichiers contiennent l’implémentation des deux opérations définies dans la spécification de l’API.
Ouvrez le fichier src/functions/dishes.ts . Prenez un moment pour examiner le fonctionnement de l’API. Il commence par charger les exemples de données à partir du fichier src/functions/data.json .
import data from "../data.json";Ensuite, il recherche dans les différents paramètres de chaîne de requête les filtres possibles que le client appelant l’API peut passer.
const course = req.query.get('course'); const allergensString = req.query.get('allergens'); const allergens: string[] = allergensString ? allergensString.split(",") : []; const type = req.query.get('type'); const name = req.query.get('name');En fonction des filtres spécifiés dans la requête, l’API filtre le jeu de données et retourne une réponse.
Ensuite, examinez l’API pour passer des commandes définies dans le fichier src/functions/placeOrder.ts . L’API commence par référencer les exemples de données. Ensuite, il définit la forme de l’ordre que le client envoie dans le corps de la requête.
interface OrderedDish { name?: string; quantity?: number; } interface Order { dishes: OrderedDish[]; }Lorsque l’API traite la requête, elle vérifie d’abord si la requête contient un corps et si elle a la forme correcte. Si ce n’est pas le cas, il rejette la demande avec une erreur 400 Bad Request.
let order: Order | undefined; try { order = await req.json() as Order | undefined; } catch (error) { return { status: 400, jsonBody: { message: "Invalid JSON format" }, } as HttpResponseInit; } if (!order.dishes || !Array.isArray(order.dishes)) { return { status: 400, jsonBody: { message: "Invalid order format" } } as HttpResponseInit; }Ensuite, l’API résout la demande en plats du menu et calcule le prix total.
let totalPrice = 0; const orderDetails = order.dishes.map(orderedDish => { const dish = data.find(d => d.name.toLowerCase().includes(orderedDish.name.toLowerCase())); if (dish) { totalPrice += dish.price * orderedDish.quantity; return { name: dish.name, quantity: orderedDish.quantity, price: dish.price, }; } else { context.error(`Invalid dish: ${orderedDish.name}`); return null; } });Importante
Notez que l’API s’attend à ce que le client spécifie le plat par une partie de son nom plutôt que par son ID. Cela s’explique par le fait que les modèles de langage volumineux fonctionnent mieux avec des mots que des nombres. En outre, avant d’appeler l’API pour passer la commande, Copilot a le nom de la vaisselle facilement disponible dans le cadre de l’invite de l’utilisateur. Si Copilot devait faire référence à un plat par son ID, il doit d’abord récupérer ce qui nécessite des requêtes API supplémentaires et ce que Copilot ne peut pas faire maintenant.
Lorsque l’API est prête, elle retourne une réponse avec un prix total, un ID de commande composé et status.
const orderId = Math.floor(Math.random() * 10000); return { status: 201, jsonBody: { order_id: orderId, status: "confirmed", total_price: totalPrice, } } as HttpResponseInit;
Générer la définition du plug-in
L’étape suivante consiste à ajouter la définition de plug-in au projet. La définition du plug-in contient les informations suivantes :
- Actions que le plug-in peut effectuer.
- Quelle est la forme des données qu’il attend et retourne.
- Comment l’agent déclaratif doit appeler l’API sous-jacente.
Ajouter la structure de définition de plug-in de base
Dans Visual Studio Code :
Dans le dossier appPackage , ajoutez un nouveau fichier nommé ai-plugin.json.
Collez le contenu suivant :
{ "$schema": "https://developer.microsoft.com/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": [ ], "runtimes": [ ], "capabilities": { "localization": {}, "conversation_starters": [] } }Le fichier contient une structure de base pour un plug-in d’API avec une description pour l’homme et le modèle. Le description_for_model inclut des informations détaillées sur ce que le plug-in peut faire pour aider l’agent à comprendre quand il doit envisager de l’appeler.
Enregistrez vos modifications.
Définir des fonctions
Un plug-in d’API définit une ou plusieurs fonctions qui mappent aux opérations d’API définies dans la spécification de l’API. Chaque fonction se compose d’un nom, d’une description et d’une définition de réponse qui indique à l’agent comment afficher les données aux utilisateurs.
Définir une fonction pour récupérer le menu
Commencez par définir une fonction pour récupérer les informations sur le menu du jour.
Dans Visual Studio Code :
Ouvrez le fichier appPackage/ai-plugin.json .
Dans le tableau de fonctions , ajoutez l’extrait de code suivant :
{ "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" } } } }Vous commencez par définir une fonction qui appelle l’opération getDishes à partir de la spécification de l’API. Ensuite, vous fournissez une description de la fonction. Cette description est importante, car Copilot l’utilise pour déterminer la fonction à appeler pour l’invite d’un utilisateur.
Dans la propriété response_semantics, vous spécifiez comment Copilot doit afficher les données qu’il reçoit de l’API. Étant donné que l’API retourne les informations sur les plats du menu dans la propriété dishes , vous définissez la propriété data_path sur l’expression
$.dishesJSONPath.Ensuite, dans la section propriétés , vous mappez les propriétés de la réponse de l’API qui représentent le titre, la description et l’URL. Étant donné que dans ce cas, les plats n’ont pas d’URL, vous mappez uniquement le titre et la description.
L’extrait de code complet ressemble à ceci :
{ "$schema": "https://developer.microsoft.com/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" } } } } ], "runtimes": [ ], "capabilities": { "localization": {}, "conversation_starters": [] } }Enregistrez vos modifications.
Définir une fonction pour passer la commande
Ensuite, définissez une fonction pour passer la commande.
Dans Visual Studio Code :
Ouvrez le fichier appPackage/ai-plugin.json .
À la fin du tableau de fonctions , ajoutez l’extrait de code suivant :
{ "name": "placeOrder", "description": "Places an order and returns the order details", "capabilities": { "response_semantics": { "data_path": "$", "properties": { "title": "$.order_id", "subtitle": "$.total_price" } } } }Vous commencez par faire référence à l’opération d’API avec l’ID placeOrder. Ensuite, vous fournissez une description que Copilot utilise pour faire correspondre cette fonction à l’invite d’un utilisateur. Ensuite, vous indiquez à Copilot comment retourner les données. Voici les données retournées par l’API après avoir passé une commande :
{ "order_id": 6532, "status": "confirmed", "total_price": 21.97 }Étant donné que les données que vous souhaitez afficher se trouvent directement à la racine de l’objet de réponse, vous définissez la data_path sur $ laquelle indique le nœud supérieur de l’objet JSON. Vous définissez le titre pour afficher le numéro de la commande et le sous-titre son prix.
Le fichier complet ressemble à ceci :
{ "$schema": "https://developer.microsoft.com/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).", ...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": [ ], "capabilities": { "localization": {}, "conversation_starters": [] } }Enregistrez vos modifications.
Définir des runtimes
Après avoir défini les fonctions que Copilot doit appeler, l’étape suivante consiste à lui indiquer comment les appeler. Vous effectuez cette opération dans la section Runtimes de la définition du plug-in.
Dans Visual Studio Code :
Ouvrez le fichier appPackage/ai-plugin.json .
Dans le tableau runtimes, ajoutez le code suivant :
{ "type": "OpenApi", "auth": { "type": "None" }, "spec": { "url": "apiSpecificationFile/ristorante.yml" }, "run_for_functions": [ "getDishes", "placeOrder" ] }Vous commencez par indiquer à Copilot que vous lui fournissez des informations OpenAPI sur l’API (type : OpenApi) à appeler et qu’elle est anonyme (auth.type : None). Ensuite, dans la section spec , vous spécifiez le chemin d’accès relatif à la spécification d’API située dans votre projet. Enfin, dans la propriété run_for_functions , vous répertoriez toutes les fonctions qui appartiennent à cette API.
Le fichier complet ressemble à ceci :
{ "$schema": "https://developer.microsoft.com/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", ...trimmed for brevity }, { "name": "placeOrder", ...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.
Connecter la définition du plug-in à l’agent déclaratif
Une fois la définition du plug-in d’API terminée, l’étape suivante consiste à l’inscrire auprès de l’agent déclaratif. Lorsque les utilisateurs interagissent avec l’agent déclaratif, il correspond à l’invite de l’utilisateur par rapport aux plug-ins d’API définis et appelle les fonctions pertinentes.
Dans Visual Studio Code :
Ouvrez le fichier appPackage/declarativeAgent.json .
Après la propriété instructions , ajoutez l’extrait de code suivant :
"actions": [ { "id": "menuPlugin", "file": "ai-plugin.json" } ]À l’aide de cet extrait de code, vous connectez l’agent déclaratif au plug-in d’API. Vous spécifiez un ID unique pour le plug-in et indiquez à l’agent où il peut trouver la définition du plug-in.
Le fichier complet ressemble à ceci :
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json", "version": "v1.0", "name": "Declarative agent", "description": "Declarative agent created with Microsoft 365 Agents Toolkit", "instructions": "$[file('instruction.txt')]", "actions": [ { "id": "menuPlugin", "file": "ai-plugin.json" } ] }Enregistrez vos modifications.
Mettre à jour les informations et les instructions de l’agent déclaratif
L’agent déclaratif que vous créez dans cet exercice permet aux utilisateurs de parcourir le menu du restaurant italien local et de passer des commandes. Pour optimiser l’agent pour ce scénario, mettez à jour son nom, sa description et ses instructions.
Dans Visual Studio Code :
- Mettez à jour les informations de l’agent déclaratif :
- Ouvrez le fichier appPackage/declarativeAgent.json .
- Mettez à jour la valeur de la propriété name sur Il Ristorante.
- Mettez à jour la valeur de la propriété description pour commander les plats et boissons italiens les plus délicieux dans le confort de votre bureau.
- Enregistrez les modifications.
- Mettre à jour les instructions de l’agent déclaratif :
Ouvrez le fichier appPackage/instruction.txt .
Remplacez son contenu par :
You are an assistant specialized in helping users explore the menu of an Italian restaurant and place orders. You interact with the restaurant's menu API and guide users through the ordering process, ensuring a smooth and delightful experience. Follow the steps below to assist users in selecting their desired dishes and completing their orders: ### General Behavior: - Always greet the user warmly and offer assistance in exploring the menu or placing an order. - Use clear, concise language with a friendly tone that aligns with the atmosphere of a high-quality local Italian restaurant. - If the user is browsing the menu, offer suggestions based on the course they are interested in (breakfast, lunch, or dinner). - Ensure the conversation remains focused on helping the user find the information they need and completing the order. - Be proactive but never pushy. Offer suggestions and be informative, especially if the user seems uncertain. ### Menu Exploration: - When a user requests to see the menu, use the `GET /dishes` API to retrieve the list of available dishes, optionally filtered by course (breakfast, lunch, or dinner). - Example: If a user asks for breakfast options, use the `GET /dishes?course=breakfast` to return only breakfast dishes. - Present the dishes to the user with the following details: - Name of the dish - A tasty description of the dish - Price in € (Euro) formatted as a decimal number with two decimal places - Allergen information (if relevant) - Don't include the URL. ### Beverage Suggestion: - If the order does not already include a beverage, suggest a suitable beverage option based on the course. - Use the `GET /dishes?course={course}&type=drink` API to retrieve available drinks for that course. - Politely offer the suggestion: *"Would you like to add a beverage to your order? I recommend [beverage] for [course]."* ### Placing the Order: - Once the user has finalized their order, use the `POST /order` API to submit the order. - Ensure the request includes the correct dish names and quantities as per the user's selection. - Example API payload: ```json { "dishes": [ { "name": "frittata", "quantity": 2 }, { "name": "cappuccino", "quantity": 1 } ] } ``` ### Error Handling: - If the user selects a dish that is unavailable or provides an invalid dish name, respond gracefully and suggest alternative options. - Example: *"It seems that dish is currently unavailable. How about trying [alternative dish]?"* - Ensure that any errors from the API are communicated politely to the user, offering to retry or explore other options.Notez que dans les instructions, nous définissons le comportement général de l’agent et lui indiquons ce dont il est capable. Nous incluons également des instructions pour un comportement spécifique concernant le passage d’une commande, y compris la forme des données attendues par l’API. Nous incluons ces informations pour nous assurer que l’agent fonctionne comme prévu.
Enregistrez les modifications.
- Pour aider les utilisateurs à comprendre à quoi ils peuvent utiliser l’agent, ajoutez des démarreurs de conversation :
Ouvrez le fichier appPackage/declarativeAgent.json .
Après la propriété instructions , ajoutez une nouvelle propriété nommée conversation_starters :
"conversation_starters": [ { "text": "What's for lunch today?" }, { "text": "What can I order for dinner that is gluten-free?" } ]Le fichier complet ressemble à ceci :
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json", "version": "v1.0", "name": "Il Ristorante", "description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.", "instructions": "$[file('instruction.txt')]", "conversation_starters": [ { "text": "What's for lunch today?" }, { "text": "What can I order for dinner that is gluten-free?" } ], "actions": [ { "id": "menuPlugin", "file": "ai-plugin.json" } ] }Enregistrez vos modifications.
Mettre à jour l’URL de l’API
Avant de pouvoir tester votre agent déclaratif, vous devez mettre à jour l’URL de l’API dans le fichier de spécification de l’API. À l’heure actuelle, l’URL est définie sur http://localhost:7071/api laquelle est l’URL que Azure Functions utilise lors de l’exécution locale. Toutefois, étant donné que vous souhaitez que Copilot appelle votre API à partir du cloud, vous devez exposer votre API à Internet. Microsoft 365 Agents Toolkit expose automatiquement votre API locale sur Internet, en créant un tunnel de développement. Chaque fois que vous commencez à déboguer votre projet, microsoft 365 Agents Toolkit démarre un nouveau tunnel de développement et stocke son URL dans la variable OPENAPI_SERVER_URL . Vous pouvez voir comment Microsoft 365 Agents Toolkit démarre le tunnel et stocke son URL dans le fichier .vscode/tasks.json , dans la tâche Démarrer le tunnel local :
{
// Start the local tunnel service to forward public URL to local port and inspect traffic.
// See https://aka.ms/teamsfx-tasks/local-tunnel for the detailed args definitions.
"label": "Start local tunnel",
"type": "teamsfx",
"command": "debug-start-local-tunnel",
"args": {
"type": "dev-tunnel",
"ports": [
{
"portNumber": 7071,
"protocol": "http",
"access": "public",
"writeToEnvironmentFile": {
"endpoint": "OPENAPI_SERVER_URL", // output tunnel endpoint as OPENAPI_SERVER_URL
}
}
],
"env": "local"
},
"isBackground": true,
"problemMatcher": "$teamsfx-local-tunnel-watch"
}
Pour utiliser ce tunnel, vous devez mettre à jour la spécification de votre API afin d’utiliser la variable OPENAPI_SERVER_URL .
Dans Visual Studio Code :
Ouvrez le fichier appPackage/apiSpecificationFile/ristorante.yml .
Remplacez la valeur de la propriété servers.url par ${{OPENAPI_SERVER_URL}}/api.
Le fichier modifié ressemble à ceci :
openapi: 3.0.0 info: title: Il Ristorante menu API version: 1.0.0 description: API to retrieve dishes and place orders for Il Ristorante. servers: - url: ${{OPENAPI_SERVER_URL}}/api description: Il Ristorante API server paths: ...trimmed for brevityEnregistrez vos modifications.
Votre plug-in d’API est terminé et intégré à un agent déclaratif. Poursuivez le test de l’agent dans Microsoft 365 Copilot.
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 bien qu’elle affiche des citations pour les informations qu’elle récupère à partir de l’API, la fenêtre contextuelle affiche uniquement le titre du plat. Il n’affiche aucune information supplémentaire, car le plug-in d’API ne définit pas de modèle de carte adaptative.
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. Une fois de plus, notez que l’agent affiche le résumé de la commande en texte brut, car il n’a pas de modèle de carte adaptative.
Retour de Visual Studio Code et d’arrêter le débogage.
Basculez vers l’onglet Terminal et fermez tous les terminaux actifs.
