Créer votre premier complément en tant que compétence Copilot

2025-06-10

Dans cet article, vous allez suivre le processus de création d’un agent Excel Copilot simple qui peut effectuer des actions sur le contenu d’un classeur Excel. L’application inclut également un complément du volet Office Excel.

Prérequis pour les connaissances

Compréhension de base des agents déclaratifs dans Microsoft 365 Copilot. Si vous ne les connaissez pas déjà, nous vous recommandons les actions suivantes.
- Lisez Agents déclaratifs pour Microsoft 365 Copilot vue d’ensemble.
- Suivez le tutoriel qui commence dans Créer des agents déclaratifs à l’aide de Microsoft 365 Agent Toolkit.

Prérequis logiciels

Tous les prérequis répertoriés dans Créer des agents déclaratifs à l’aide de Microsoft 365 Agent Toolkit.
Microsoft 365 Agent Toolkit.

Démarrer avec un complément Office

Créez un complément Excel de base en procédant comme suit.

Créez un complément Office dans microsoft 365 Agent Toolkit en suivant les instructions fournies dans Créer des projets de complément Office avec microsoft 365 Agent Toolkit. Arrêtez après la création du projet. N’effectuez pas les étapes décrites dans la section de chargement indépendant.

Remarque

Lorsque vous êtes invité à nommer le complément, utilisez « Complément Excel + Agent ».
Le projet s’ouvre dans une nouvelle fenêtre Visual Studio Code. Fermez la fenêtre Visual Studio Code d’origine.
Dans une invite de commandes ou Visual Studio Code TERMINAL à la racine du projet, exécutez npm install.

Charger et tester le complément

Vérifiez que le complément fonctionne en effectuant les étapes suivantes.
1. Sélectionnez Affichage | Exécutez dans Visual Studio Code. Dans le menu déroulant EXÉCUTER ET DÉBOGUER, sélectionnez Bureau Excel (Edge Chromium) .
2. Appuyez sur la touche F5. Le projet est généré et une fenêtre Node dev-server s’ouvre. Ce processus peut prendre quelques minutes. Finalement, Excel s’ouvre.
Remarque

S’il s’agit de la première fois que vous avez chargé un complément Office sur votre ordinateur (ou la première fois en plus d’un mois), vous pouvez être invité à supprimer un ancien certificat et/ou à en installer un nouveau. Acceptez les deux invites.
1. Sélectionnez le bouton Compléments dans le ruban Accueil , puis dans le menu volant qui s’ouvre, sélectionnez votre complément.
2. Un groupe de compléments Contoso avec un bouton Afficher le volet des tâches s’affiche dans le ruban Accueil . Utilisez le bouton pour ouvrir le volet Office du complément.
Remarque

Si une invite WebView Stop On Load s’affiche, sélectionnez OK.
1. Une fois le volet Office ouvert, sélectionnez Exécuter. Une cellule de la feuille de calcul devient jaune.
2. Arrêtez le débogage et désinstallez le complément en arrêtant Excel et en l’exécutant npm run stop dans une invite de commandes ou Visual Studio Code TERMINAL à la racine du projet.
  
  Importante
  
  L’arrêt du débogage dans l’interface utilisateur de Visual Studio Code ne fonctionne pas actuellement en raison d’un bogue. En outre, ni la fermeture d’Excel ni la fermeture manuelle de la fenêtre du serveur de développement n’arrêtent le serveur de manière fiable, ni n’entraînent l’annulation de l’exécution du complément par Excel. Vous devez exécuter npm run stop.

Ajouter un agent déclaratif Copilot

Ajoutez l’agent en procédant comme suit.

Dans le fichier manifeste, apportez les modifications suivantes.
1. Ajoutez l’objet suivant à la racine. Par convention, il est placé juste en dessous de la propriété « validDomains ». Vous créez le fichier « declarativeAgent.json » dans une étape ultérieure.
```
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "ContosoCopilotAgent",
      "file": "declarativeAgent.json"
    }
  ]
},
```
2. Il existe plusieurs objets dans le "extensions.runtimes" tableau. Recherchez celui dont "id" la valeur est « CommandRuntime » et copiez-le en tant qu’objet runtime supplémentaire dans le tableau.
3. Apportez les modifications suivantes à cet objet runtime supplémentaire.
  1. Remplacez « "id" CommandRuntime » par « CopilotAgentActionsRuntime ».
  2. Remplacez sa "actions.id" propriété par « fillcolor ». Il s’agit de l’ID d’une fonction que vous ajoutez à une étape ultérieure.
  3. Remplacez la propriété par "actions.type" « executeDataFunction ».
Créez un fichier dans le dossier appPackage nommé declarativeAgent.json.

Collez le contenu suivant dans le fichier. (Vous créez le fichier Excel-API-local-plugin.json mentionné dans ce json dans une étape ultérieure.)

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
     "version": "v1.4",
     "name": "Excel Add-in + 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": "localExcelPlugin",
             "file": "Excel-API-local-plugin.json"
         }
     ]
 }

Créez un fichier dans le dossier appPackage nommé Excel-API-local-plugin.json.

Collez le contenu suivant dans le fichier.

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
     "schema_version": "v2.3",
     "name_for_human": "Excel Add-in + Agent",
     "description_for_human": "Add-in Actions in Agents",
     "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",
                 "allowed_host": ["workbook"]
             },
             "run_for_functions": ["fillcolor"]
         }
     ]
 }

Ouvrez le fichier \src\commands\commands.ts et ajoutez le code suivant à la fin de celui-ci.

async function fillcolor(cell, color) {
    await Excel.run(async (context) => {
         context.workbook.worksheets
             .getActiveWorksheet()
             .getRange(cell).format.fill.color = color;
         await context.sync();
     })
}

Office.onReady((info) => {
     Office.actions.associate("fillcolor", async (message) => {
         const {Cell: cell, Color: color} = JSON.parse(message);
         await fillcolor(cell, color);
         return "Cell color changed.";
     });
});

Mettre à jour les fichiers de configuration de projet pour un complément combiné et l’agent Copilot

Il existe un fichier appelé teamsapp.yaml ou m365agents.yaml à la racine du projet. Remplacez son contenu par ce qui suit :

# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
# Creates a Teams app
  - uses: teamsApp/create
    with:
     # Teams app name
     name: Contoso Agent ${{APP_NAME_SUFFIX}}
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID

# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Extend your Teams app to Outlook and the Microsoft 365 app
  - uses: teamsApp/extendToM365
    with:
     # Relative path to the build app package.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     titleId: M365_TITLE_ID
     appId: M365_APP_ID

# Triggered when 'teamsapp publish' is executed
publish:
# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Apply the Teams app manifest to an existing Teams app in
# Teams Developer Portal.
# Will use the app id in manifest file to determine which Teams app to update.
  - uses: teamsApp/update
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Publish the app to
# Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
# for review and approval
  - uses: teamsApp/publishAppPackage
    with:
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
projectId: da53b0a2-1561-415e-919a-5b870bcd2f49

Remplacez la valeur de projectId dans la dernière ligne de contenu que vous avez collée à l’étape précédente par un nouveau GUID généré de manière aléatoire.
Ouvrez le fichier \env.env.dev et ajoutez les lignes suivantes à la fin du fichier, juste après la ligne « ADDIN_ENDPOINT= ».
```
TEAMS_APP_ID=
TEAMS_APP_TENANT_ID=
M365_TITLE_ID=
M365_APP_ID=
```

Tester le complément et l’agent

Fermez toutes les applications Office.
Ouvrez microsoft 365 Agent Toolkit.
Dans le volet Cycle de vie , sélectionnez Provisionner. Entre autres choses, l’approvisionnement effectue les opérations suivantes :
- Définissez les valeurs des quatre lignes que vous avez ajoutées au fichier .env.dev.
- Créez un dossier /build dans le 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 une invite de commandes ou Visual Studio Code TERMINAL à la racine du projet, exécutez npm run dev-server pour démarrer le serveur sur localhost. Attendez qu’une ligne s’affiche dans la fenêtre du serveur que l’application a compilée avec succès. Cela signifie que le serveur exécute et gère les fichiers.

Remarque

Si c’est la première fois depuis un mois que vous exécutez un serveur local pour un complément Office sur votre ordinateur, vous pouvez être invité à supprimer un ancien certificat et/ou à en installer un nouveau. Acceptez les deux invites.
La première étape du test dépend de la plateforme.
- Pour tester dans Office sur Windows, ouvrez Excel. Dans quelques instants, le bouton Afficher le volet Office apparaît dans le ruban Accueil du groupe Complément Contoso. (S’il n’apparaît pas dans le ruban, sélectionnez le bouton Compléments sur le ruban, puis sélectionnez l’application Complément Excel + Agent dans le menu volant qui s’ouvre.)
- Pour tester dans Office sur le Web, dans un navigateur, accédez à https://excel.cloud.microsoft.com/, puis créez un classeur.
Ouvrez Copilot à partir du ruban et sélectionnez le contrôle hamburger dans le volet Copilot . Complément Excel + Agent doivent figurer dans la liste des agents. (Vous devrez peut-être sélectionner En savoir plus pour vous assurer que tous les agents sont répertoriés.) Si l’agent ne l’est pas, essayez l’une des actions suivantes, ou les deux.
- Patientez quelques minutes et rechargez Copilot.
- Avec Copilot ouvert à la liste des agents, cliquez sur le curseur dans la fenêtre Copilot et appuyez sur Ctrl+R.
Lorsque l’agent est répertorié, sélectionnez-le. Le volet Complément Excel + Agent s’ouvre.
Sélectionnez le starter Modifier la couleur de cellule, puis appuyez sur le contrôle Envoyer dans la zone de conversation en bas du volet. 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 dans le complément ou l’agent

Le rechargement dynamique et le rechargement à chaud pour un complément et un agent combinés 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’extension 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. Choisissez « Y » en réponse à l’invite pour mettre fin au processus.
- Si le serveur web s’exécute dans une fenêtre distincte, exécutez npm run stopdans une invite de commandes ou Visual Studio Code TERMINAL à la racine du projet.
Effacez le cache Office en suivant les instructions fournies dans Effacer manuellement le cache.
Ouvrez Teams et sélectionnez Applications dans la barre de l’application, puis sélectionnez Gérer vos applications en bas du volet Applications .
Recherchez Complément Excel + Agent dans la liste des applications, puis sélectionnez la flèche à gauche du nom pour développer sa ligne.
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 le complément et l’agent.

Résolution des problèmes

Consultez Résolution des problèmes liés aux compléments et agents combinés.

Étapes suivantes

Ajouter un agent Copilot à un complément existant