Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Remarque
La fonctionnalité de développement décrite dans cet article est en préversion. Nous vous encourageons à tester cette fonctionnalité, mais elle ne doit pas être utilisée dans un plug-in de production. Voici les limitations de la préversion initiale :
- La fonctionnalité est activée uniquement pour Office sur Windows et Office sur le Web. Nous travaillons actuellement à la prise en charge d’Office sur Mac.
- La fonctionnalité est activée uniquement pour Excel, PowerPoint ou Word. Nous nous efforçons d’apporter une prise en charge à Outlook.
Un plug-in pour un agent déclaratif peut appeler les API dans la bibliothèque JavaScript Office pour effectuer des opérations de lecture et d’écriture sur le contenu et les métadonnées d’un document Office actuellement ouvert dans une application Office. Cette fonctionnalité permet à Copilot d’utiliser des documents Office de manière précise et sans erreur qui nécessiterait autrement un complément Office.
Relation entre les agents Copilot et l’infrastructure de complément Office
Les compléments Office et les plug-ins d’agent déclaratif appellent des API dans la bibliothèque JavaScript Office, et une extension Microsoft 365 qui utilise la bibliothèque peut inclure un plug-in, un complément ou les deux. La meilleure approche dépend des scénarios utilisateur que l’extension doit activer.
- Si l’extension doit fournir des actions simples et rapides qui n’ont pas besoin que des paramètres leur soient passés, incluez uniquement un complément avec des boutons ou menus du ruban personnalisés, appelés commandes de complément.
- Si l’extension a besoin d’une expérience de tableau de bord, si l’utilisateur doit configurer les paramètres, doit afficher des métadonnées sur le contenu du document Office ou a besoin d’une expérience de type page pour toute autre raison, incluez un complément avec un volet Office.
- Si l’extension doit fournir des actions complexes qui nécessitent des paramètres passés au moment de l’exécution ou nécessite une interface en langage naturel, incluez un agent Copilot.
Scénarios
Voici quelques méthodes sélectionnées par lesquelles un agent Copilot qui appelle des API de bibliothèque JavaScript Office améliore la valeur d’une extension Microsoft 365.
Analyse du contenu : Un agent peut être utilisé pour analyser le contenu d’un document, d’une présentation ou d’une feuille de calcul et prendre des mesures en fonction de ce qu’il trouve. Les éléments suivants sont des exemples.
- Un agent analyse une demande de proposition (RFP), puis extrait les réponses aux questions dans l’appel d’offres à partir d’un système principal. L’utilisateur demande simplement à l’agent de « Renseigner les réponses que vous connaissez aux questions ».
- Un agent analyse un document ou une table dans une feuille de calcul à la recherche de contenu qui implique que certaines actions doivent être effectuées, soit dans le document lui-même, soit ailleurs dans les systèmes métier du client. L’utilisateur peut demander à l’agent de « Passer en revue le document à la recherche des éléments que j’ai manqués dans la liste d’audit ».
Insertion approuvée des données : Si vous posez une question à un moteur d’IA classique, il combine les informations qu’il trouve et compose une réponse ; un processus qui peut introduire des imprécisions. Toutefois, un agent Copilot basé sur un complément peut insérer des données inchangées à partir d’une source approuvée. Quelques exemples :
- Prenons l’exemple d’un agent qui permet d’insérer des recherches juridiques dans Word où elles peuvent ensuite être modifiées. Un utilisateur demande à l’agent « Dans quelles circonstances un loueur peut-il rompre unilatéralement un bail d’espace résidentiel dans l’Indiana ? » L’agent extrait ensuite le contenu, inchangé, des précédents et des lois, et l’insère dans le document.
- Prenons l’exemple d’un agent qui gère l’inventaire des ressources numériques. Dans la conversation de l’agent Copilot, un utilisateur demande « Insérer un tableau de nos photos en couleur avec le nom de chacune d’elles, le nombre de téléchargements et sa taille en mégaoctets, triés dans l’ordre de la plupart des téléchargements ». L’agent extrait ensuite ces données, inchangées, à partir du système d’enregistrement et insère le tableau dans une feuille de calcul Excel.
Lorsque l’agent est combiné avec un complément, d’autres scénarios sont activés. L’inclusion d’un agent Microsoft 365 Copilot avec un complément Office offre au moins deux avantages au complément :
- Copilot devient une interface en langage naturel pour les fonctionnalités du complément.
- L’agent peut passer des paramètres au code JavaScript qu’il appelle, ce qui n’est pas possible lorsqu’une commande de fonction dans un complément est appelée à partir d’un bouton ou d’un élément de menu.
L’apprentissage de l’utilisation du complément est un moyen pour un agent d’améliorer un complément. Lorsqu’un utilisateur doit effectuer plusieurs étapes ou tâches avec le complément pour atteindre un objectif, l’interface de conversation de Copilot peut faciliter le processus de prise en main du complément. Prenons l’exemple d’un cabinet d’avocats qui doit avoir une liste de questions auxquelles il faut répondre sur chaque bail qu’il prépare. La création de cette liste de questions peut prendre du temps et demander beaucoup de travail. Toutefois, un agent Copilot peut être invité à produire une première liste brouillon de questions et à les insérer dans un document Word à l’aide de la bibliothèque JavaScript Office.
Créer votre premier plug-in bibliothèque JavaScript Office
Voici les principales étapes de création d’un plug-in d’API pour un agent Copilot qui appelle les API de la bibliothèque JavaScript Office.
- Vérifiez que vous remplissez les conditions préalables
- Créez le projet
- Configurer le manifeste
- Configurer l’agent déclaratif
- Configurer le plug-in
- Créer les fonctions JavaScript
- Copier les fichiers de configuration du projet
- Tester l’agent et le plug-in
- Apporter des modifications à l’agent
Configuration requise
- Conditions requises spécifiées dans Conditions requises pour les options d’extensibilité Copilot
- Visual Studio Code
- Node.js 18, 20, 22 ou 24
- Microsoft 365 Agents Toolkit
Créez le projet
Commencez par créer un agent déclaratif de base.
Ouvrez Visual Studio Code.
Sélectionnez Microsoft 365 Agents Toolkit dans la barre d’activité.
Sélectionnez Créer un agent/une application.
Sélectionnez Agent déclaratif.
Sélectionnez Aucune action pour créer un agent déclaratif de base.
Dans la liste Dossier de l’espace de travail, sélectionnez Dossier par défaut pour stocker le dossier racine de votre projet à l’emplacement par défaut ou accédez à un dossier dans lequel vous souhaitez placer le nouveau projet d’agent.
Entrez
Excel Agentcomme Nom de l’application , puis appuyez sur Entrée.Le projet s’ouvre dans une nouvelle fenêtre Visual Studio Code. Fermez la fenêtre Visual Studio Code d’origine.
Configurer le manifeste
Les étapes suivantes configurent le manifeste.
Ouvrez le fichier manifest.json dans le dossier appPackage .
Vous devez utiliser la préversion du schéma de manifeste. Remplacez donc les
$schemapropriétés etmanifestVersionpar ce qui suit."$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", "manifestVersion": "devPreview",À la racine du manifeste, ajoutez la propriété d’autorisation suivante. Cette propriété donne à votre agent l’autorisation de lire et d’écrire des documents Office.
"authorization": { "permissions": { "resourceSpecific": [ { "name": "Document.ReadWrite.User", "type": "Delegated" } ] } }À la racine du manifeste, ajoutez la propriété extensions suivante. À propos de ce code, notez ce qui suit.
- La
requirements.scopespropriété garantit que l’agent est disponible uniquement dans Excel, et non dans d’autres applications Office. - L’objet dans configure
runtimesle runtime JavaScript utilisé par Office pour exécuter les API de la bibliothèque JavaScript Office appelées par votre agent. - La
code.scriptpropriété spécifie l’URL d’un fichier JavaScript qui contient les fonctions qui appellent les API de la bibliothèque JavaScript Office. Ce même fichier contient un appel de la méthode Office.actions.associate pour mapper la fonction à un ID d’action. Vous créez ce fichier à une étape ultérieure. - La
code.pagepropriété spécifie l’URL d’une page web qui contient une balise incorporée<script>qui charge le fichier qui est une référence dans lacode.pagepropriété . Vous créez ce fichier à une étape ultérieure. - L’objet runtime inclut un
actionstableau qui inclut un objet action - La valeur de la
actions.idpropriété est le même ID d’action que celui passé à l’appel deassociate. - La
actions.typepropriété est définie surexecuteDataFunction, qui est le type qui peut accepter des paramètres lorsqu’elle est appelée par Copilot.
"extensions": [ { "requirements": { "scopes": [ "workbook" ] }, "runtimes": [ { "id": "ContosoAgentRuntime", "type": "general", "code": { "page": "https://localhost:3000/commands.html", "script": "https://localhost:3000/commands.js" }, "lifetime": "short", "actions": [ { "id": "FillColor", "type": "executeDataFunction" } ] } ] } ]- La
La documentation de référence pour le manifeste JSON se trouve dans La référence du schéma de manifeste d’application Microsoft 365.
Configurer l’agent déclaratif
Ouvrez le fichier declarativeAgent.json dans le dossier appPackage .
Remplacez son contenu par le code suivant. À propos de ce JSON, notez les points suivants :
- La
actions.idpropriété dans ce fichier est l’ID collectif de toutes les fonctions dans le fichier spécifié dansactions.file. Il ne doit normalement pas correspondre auextensions.runtimes.actions.iddans le manifeste, qui est l’ID d’une action spécifique. - Vous créez le fichier que vous spécifiez dans la
actions.filepropriété dans une étape suivante.
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json", "version": "v1.5", "name": "Excel Agent", "description": "Agent for working with Excel cells.", "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.", "conversation_starters": [ { "title": "Change cell color", "text": "I want to change the color of cell B2 to orange" } ], "actions": [ { "id": "ExcelActions", "file": "Office-API-local-plugin.json" } ] }- La
La documentation de référence pour les agents déclaratifs se trouve dans Schéma de l’agent déclaratif 1.6 pour Microsoft 365 Copilot.
Configurer le plug-in
Créez un fichier dans le dossier appPackage et attribuez-lui le nom attribué à la
actions.filepropriété dans le fichier declarativeAgent.json : Office-API-local-plugin.json.Collez le contenu suivant dans le fichier. À propos de ce JSON, notez les détails suivants :
- Le fichier de configuration du plug-in d’API spécifie les fonctions du plug-in dans le sens des actions de l’agent, et non les fonctions JavaScript. Il inclut les instructions pour chaque action. Il configure également le runtime pour Copilot. (Vous avez configuré le runtime pour Office dans le manifeste à l’étape précédente.)
- doit
functions.namecorrespondre à laextensions.runtimes.actions.idpropriété dans le manifeste du complément :FillColor. - Le
runtimes.run_for_functionstableau doit inclure la même chaîne oufunctions.nameune chaîne générique qui lui correspond. - La
runtimes.spec.local_endpointpropriété spécifie que la fonction JavaScript associée à laFillColorchaîne est disponible dans la bibliothèque JavaScript Office, plutôt que dans un point de terminaison REST.
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json", "schema_version": "v2.3", "name_for_human": "Excel Agent", "description_for_human": "Excel actions in agent", "namespace": "addInFunction", "functions": [ { "name": "FillColor", "description": "FillColor changes a single cell location to a specific color.", "parameters": { "type": "object", "properties": { "Cell": { "type": "string", "description": "A cell location in the format of A1, B2, etc.", "default": "B2" }, "Color": { "type": "string", "description": "A color in hex format, e.g., #30d5c8", "default": "#30d5c8" } }, "required": [ "Cell", "Color" ] }, "returns": { "type": "string", "description": "A string indicating the result of the action." }, "states": { "reasoning": { "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.", "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format." }, "responding": { "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.", "instructions": "If there is no error present, tell the user the cell location and color that was set." } } } ], "runtimes": [ { "type": "LocalPlugin", "spec": { "local_endpoint": "Microsoft.Office.Addin" }, "run_for_functions": [ "FillColor" ], "auth": { "type": "None" } } ] }
La documentation de référence pour les plug-ins d’API se trouve dans schéma de manifeste de plug-in d’API 2.4 pour Microsoft 365 Copilot.
Créer les fonctions JavaScript
À la racine du projet, créez le dossier nommé src, puis créez un sous-dossier sous-dossier nommé commandes.
Dans le dossier commands , créez un fichier nommé commands.ts et donnez-lui le contenu suivant. Notez les détails suivants sur ce code.
- La
fillColorfonction définit la couleur d’arrière-plan de la cellule spécifiée sur la couleur spécifiée. Il appelle des objets et des méthodes à partir de la bibliothèque JavaScript Office, qui est chargée dans le runtime JavaScript par un fichier que vous créez à une étape ultérieure. - Le premier paramètre de la
associateméthode doit correspondre exactement à laextensions.runtimes.actions.idpropriété dans le manifeste et à lafunctions.namepropriété dans le json des plug-ins d’API. - Le
messageparamètre est un objet passé par le runtime Copilot au runtime JavaScript dans Office. Il s’agit d’un objet qui contient l’adresse de cellule et les paramètres de couleur spécifiés par l’utilisateur dans une invite en langage naturel, par exemple « Définir la cellule C4 en vert ».
async function fillColor(cell, color) { // @ts-ignore await Excel.run(async (context) => { context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color; await context.sync(); }) } // @ts-ignore Office.onReady((info) => { // @ts-ignore Office.actions.associate("FillColor", async (message) => { const { Cell: cell, Color: color } = JSON.parse(message); await fillColor(cell, color); return "Cell color changed."; }) });- La
Dans le dossier commandes , créez un fichier nommé commands.html et donnez-lui le contenu suivant. Ce fichier est nécessaire, car les fichiers JavaScript ne peuvent pas être directement chargés dans le type de runtime utilisé par Office pour les plug-ins de l’API Copilot. Au lieu de cela, un fichier HTML avec un
<script>élément charge le Code JavaScript. Notez les détails suivants sur ce fichier.- Étant donné que le seul objectif du fichier est de charger d’autres fichiers, l’élément
<body>est vide. Le fichier n’a pas d’interface utilisateur et n’est jamais affiché pour les utilisateurs. - Il charge le fichier office.js, qui est la bibliothèque JavaScript Office, à partir d’un serveur Microsoft.
- Il n’a pas d’élément
<script>pour charger un fichier commands.js (transpilé à partir du commands.ts que vous avez créé), car cet<script>élément est ajouté au moment de la génération par un fichier que vous ajoutez à une étape ultérieure. - Lorsque project est généré et servi sur un serveur, l’URL de ce fichier HTML correspond à la valeur de la
extensions.runtimes.code.pagepropriété dans le manifeste. Consultez Configurer le manifeste plus haut dans cet article.
<html> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <!-- Office JavaScript API --> <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script> </head> <body> </body> </html>- Étant donné que le seul objectif du fichier est de charger d’autres fichiers, l’élément
Copier les fichiers de configuration du projet
Office utilise l’infrastructure des compléments Office pour exécuter des plug-ins d’API pour la bibliothèque JavaScript Office. Pendant la période de préversion initiale pour les plug-ins d’API Office locaux, il n’existe pas de modèle Agents Toolkit pour ce type de projet. Pour cette raison, certains fichiers utilisés par agents Toolkit pour le développement de compléments Office doivent être ajoutés au projet. Le moyen le plus rapide de générer ces fichiers consiste à créer un projet de complément, à copier les fichiers nécessaires du projet de complément vers ce projet d’agent, puis à apporter quelques modifications légères.
Ouvrez une nouvelle fenêtre Visual Studio Code.
Sélectionnez Microsoft 365 Agents Toolkit dans la barre d’activité.
Sélectionnez Créer un agent/une application.
Sélectionnez Complément Office.
Sélectionnez Volet Office.
Dans la liste Dossier de l’espace de travail, sélectionnez Dossier par défaut pour stocker le dossier racine de votre projet à l’emplacement par défaut ou accédez à un dossier dans lequel vous souhaitez placer le nouveau projet d’agent.
Entrez n’importe quelle chaîne comme Nom de l’application , puis appuyez sur Entrée.
Le projet s’ouvre dans une nouvelle fenêtre Visual Studio Code. Fermez la nouvelle fenêtre Visual Studio Code et celle à partir de laquelle vous avez créé le projet.
Copiez les fichiers suivants à partir de la racine du projet de complément que vous avez créé vers la racine du projet de plug-in d’API. Après avoir copié les fichiers, supprimez le dossier du projet de complément.
- babel.config.json
- package.json
- tsconfig.json
- webpack.config.js
Remarque
Une partie du contenu de ces fichiers n’est pas nécessaire pour votre projet de plug-in d’API. Dans les étapes restantes de cette section, vous apportez uniquement les modifications minimales nécessaires à ces fichiers pour vous assurer que le plug-in se charge et s’exécute correctement. Nous travaillons dur pour développer un modèle de projet Agents Toolkit pour les plug-ins qui appellent les API de la bibliothèque JavaScript Office.
Dans Visual Studio Code, ouvrez le fichier webpack.config.js.
Recherchez la définition de l’objet
entry, puis supprimez-y lataskpanepropriété. Lorsque vous avez terminé, laentrypropriété doit ressembler à ce qui suit.entry: { polyfill: ["core-js/stable", "regenerator-runtime/runtime"], commands: "./src/commands/commands.ts", },Recherchez la définition du
pluginstableau. En haut se trouve un appel denew HtmlWebpackPluginpour un volet Office de complément. Supprimez cet appel denew HtmlWebpackPlugin. Lorsque vous avez terminé, l’ensemblepluginsdu tableau doit ressembler à ce qui suit.plugins: [ new CopyWebpackPlugin({ patterns: [ { from: "appPackage/assets/*", to: "assets/[name][ext][query]", }, { from: "appPackage/manifest*.json", to: "[name]" + "[ext]", transform(content) { if (dev) { return content; } else { return content.toString().replace(new RegExp(urlDev, "g"), urlProd); } }, }, ], }), new HtmlWebpackPlugin({ filename: "commands.html", template: "./src/commands/commands.html", chunks: ["polyfill", "commands"], }), ],Dans le dossier appPackage , il y a deux fichiers image : color.png et outline.png. Pour utiliser l’infrastructure des outils de complément, ces fichiers doivent être déplacés. Créez un sous-dossier nommé assets dans le dossier appPackage et déplacez-y les deux fichiers.
Ouvrez manifest.json et modifiez les valeurs des
colorpropriétés etoutlinepour qu’elles correspondent à leurs nouveaux emplacements. Lorsque vous avez terminé, laiconspropriété doit ressembler à ce qui suit."icons": { "outline": "assets/outline.png", "color": "assets/color.png" },
Tester l’agent et le plug-in
Dans votre interface de ligne de commande (CLI), accédez à la racine du projet de plug-in d’API, puis exécutez
npm install. Attendez la fin de l’installation.Fermez toutes les applications Office.
Dans Visual Studio Code, sélectionnez Microsoft 365 Agents Toolkit dans la barre d’activité, puis dans le volet COMPTES, vérifiez que vous êtes connecté à un compte Microsoft 365 dans lequel la prise en charge est activée pour Copilot et pour le chargement d’applications personnalisées.
Sélectionnez Provisionner dans le volet CYCLE DE VIE .
Entre autres choses, l’approvisionnement crée un dossier de build à l’intérieur du dossier appPackage avec le fichier zip du package. Le fichier contient le manifeste et les fichiers JSON pour l’agent et le plug-in.
Dans votre interface CLI à la racine du projet, exécutez
npm run dev-serverpour démarrer le serveur sur localhost.Remarque
Si vous êtes invité à supprimer un ancien certificat et/ou à en installer un nouveau, acceptez les deux invites.
Attendez qu’une ligne s’affiche dans la fenêtre du serveur, semblable à l’exemple suivant, qui indique que l’application a été compilée avec succès. Cette sortie signifie que le serveur exécute et gère les fichiers.
webpack 5.99.8 compiled successfully in 1090 msLa première étape du test dépend de la plateforme.
- Pour tester dans Office sur Windows, ouvrez Excel, puis ouvrez (ou créez) un classeur.
- Pour tester dans Office sur le Web, dans un navigateur, accédez à
https://excel.cloud.microsoft, puis ouvrez (ou créez) un classeur.
Le processus d’ouverture de votre agent dépend de l’interface utilisateur de Copilot dans les applications Office, qui est en transition.
- Si vous voyez un boutonCopilot sur le ruban (et non un menu déroulant), sélectionnez le bouton Copilot pour ouvrir le volet Copilot.
- Si vous voyez un menu déroulant Copilot , ouvrez le menu et sélectionnez Compétences de l’application dans la liste déroulante pour ouvrir le volet Copilot .
Sélectionnez le contrôle hamburger dans le volet Copilot .
Dans le volet, l’agent Excel doit figurer dans la liste des agents. Vous devrez peut-être sélectionner En savoir plus pour afficher la liste de tous les agents. Si l’agent n’est pas répertorié, essayez une ou les deux actions suivantes.
- Patientez quelques minutes et rechargez Copilot.
- Avec Copilot ouvert à la liste des agents, placez le curseur dans le volet Copilot et appuyez sur Ctrl+R.
Sélectionnez Agent Excel, sélectionnez le démarrage de la conversation Modifier la couleur de cellule , puis sélectionnez le contrôle Envoyer dans la zone de conversation en bas du volet. Dans quelques secondes, vous devriez voir une invite de confirmation similaire à ce qui suit.
Sélectionnez Confirmer en réponse à l’invite de confirmation. La couleur de la cellule doit changer.
Conseil
Si Copilot signale une erreur, répétez votre invite, mais ajoutez la phrase suivante à l’invite : « Si vous obtenez une erreur, signalez-moi le texte complet de l’erreur ».
Essayez d’entrer d’autres combinaisons de cellule et de couleur dans la zone de conversation, par exemple « Définir la cellule G5 sur la couleur du ciel ».
Apporter des modifications à l’agent
Le rechargement en direct et le rechargement à chaud pour un plug-in d’API Office ne sont pas pris en charge dans la période de préversion. Pour apporter des modifications, commencez par arrêter le serveur et désinstallez l’agent en procédant comme suit.
L’arrêt du serveur dépend de la fenêtre dans laquelle il s’exécute.
- Si le serveur web s’exécute dans la même invite de commandes ou Visual Studio Code TERMINAL où vous avez exécuté
npm run dev-server, donnez le focus à la fenêtre et appuyez sur Ctrl+C. Pour mettre fin au processus, choisissez « Y » en réponse à l’invite. - Si le serveur web s’exécute dans une fenêtre distincte, dans une invite de commandes, l’interpréteur de commandes bash ou Visual Studio Code TERMINAL à la racine du projet, exécutez
npm run stop. La fenêtre du serveur se ferme.
- Si le serveur web s’exécute dans la même invite de commandes ou Visual Studio Code TERMINAL où vous avez exécuté
Effacez le cache Office en suivant les instructions fournies dans Effacer manuellement le cache.
Ouvrez Teams et sélectionnez Applications dans la barre d’activité, puis sélectionnez Gérer vos applications en bas du volet Applications .
Recherchez AgentDev Excel dans la liste des applications.
Pour développer sa ligne, sélectionnez la flèche à gauche du nom.
Sélectionnez l’icône de corbeille près de l’extrémité droite de la ligne, puis sélectionnez Supprimer dans l’invite.
Apportez vos modifications, puis répétez les étapes décrites dans Tester l’agent et le plug-in.