Partager via

Ajouter un agent Copilot à un complément

L’ajout d’un agent Copilot à un complément Office offre deux avantages :

  • Copilot devient une interface en langage naturel pour les fonctionnalités du complément.
  • L’agent peut passer des paramètres au JavaScript qu’il appelle, ce qui n’est pas possible lorsqu’une commande de fonction est appelée à partir d’un bouton ou d’un élément de menu.

Remarque

Cet article suppose que vous êtes familiarisé avec la vue d’ensemble Combiner des agents Copilot avec des compléments Office et la documentation Copilot à laquelle il fait référence. Nous vous recommandons également de suivre le guide de démarrage rapide Créer votre premier complément en tant que compétence Copilot.

Importante

Cette fonctionnalité nécessite le manifeste unifié pour Microsoft 365. Si votre complément utilise uniquement le manifeste du complément, vous devez d’abord le convertir pour utiliser le manifeste unifié avant de pouvoir y ajouter un agent Copilot. Avant de poursuivre cet article, vous devez savoir comment empaqueter le manifeste et d’autres fichiers dans un fichier zip de package d’application et le charger de manière indépendante dans une application Office à des fins de test.

Tâches principales

Voici les tâches main pour ajouter un agent Copilot à votre complément. Les détails se trouvent dans les sous-sections.

Créer les fonctions pour les actions de l’agent

Si votre complément inclut une ou plusieurs commandes de fonction, votre projet dispose déjà d’un fichier JavaScript ou TypeScript qui définit les fonctions de ces commandes (généralement appelées commands.js ou commands.ts) et d’un fichier HTML sans interface utilisateur (généralement appelé commands.html) qui a une <script> balise pour charger le fichier de fonction. Nous vous recommandons d’utiliser ce même fichier de fonction pour définir les fonctions des actions de votre agent. Passez à la section Mettre à jour le fichier de fonction.

Créer les fichiers sources

Si votre projet n’a pas encore de fichiers de ce type, créez-les en procédant comme suit. La structure des dossiers et des fichiers et les noms de ces étapes ne sont pas obligatoires, mais nous les recommandons pour réduire les incompatibilités avec les outils de développement et la configuration des compléments pour les bundlers et les transpileurs, le cas échéant.

  1. Vérifiez qu’il existe un dossier \src hors de la racine du projet et qu’il dispose d’un dossier enfant nommé \commands.

  2. Créez un fichier commands.js (ou .ts) dans le dossier \commands . Vous y ajoutez du contenu dans une étape ultérieure.

  3. Créez un fichier commands.html dans le dossier \commands avec le contenu suivant. Notez les points suivants concernant ce balisage.

    • L’élément <body> est vide, car le fichier n’a pas d’interface utilisateur. Son seul objectif est de charger des fichiers JavaScript.

    • La bibliothèque JavaScript Office et le fichier commands.js que vous avez créés à l’étape précédente sont explicitement chargés.

      Remarque

      Dans le développement de compléments Office, il est courant d’utiliser des outils tels que webpack et ses plug-ins pour injecter <script> automatiquement des balises dans des fichiers HTML au moment de la génération. Si vous utilisez un tel outil, vous ne devez pas inclure <script> dans votre fichier source des balises qui vont être insérées par l’outil.

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

        <!-- Office JavaScript Library -->
        <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
        <!-- Function command file -->
        <script src="commands.js" type="text/javascript"></script>
    </head>
    <body>
    </body>
</html>

Mettre à jour le fichier de fonction

Définissez les fonctions pour les actions de votre agent en procédant comme suit. Ceux-ci supposent la structure et les noms de dossiers et de fichiers les plus courants.

Ouvrez le fichier de fonction (généralement, le \src\commands\commands.js (ou .ts)) et ajoutez les fonctions qui implémentent les actions de l’agent. Gardez à l’esprit les points suivants lorsque vous travaillez.

  • Comme tout code qui appelle des API dans la bibliothèque JavaScript Office, le fichier doit initialiser la bibliothèque, généralement en appelant Office.onReady.
  • Les fonctions appelées par les agents prennent un message paramètre qui spécifie les valeurs qu’Office utilisera lorsqu’il appelle des fonctions à partir de la bibliothèque JavaScript Office. Cet objet peut être analysé avec la JSON.parse méthode . Les valeurs de l’objet sont spécifiées par les utilisateurs en langage naturel.
  • Contrairement aux fonctions appelées avec des commandes de complément, ces fonctions n’ont pas de Office.AddinCommands.Event paramètre et n’appellent pas la Office.AddinCommands.Event.completed méthode . Au lieu de cela, les fonctions appelées par les agents retournent un objet de résultat du runtime JavaScript au runtime Copilot.
  • Les fonctions appelées à partir de Copilot ont moins de temps à exécuter que les fonctions appelées à partir d’une commande de fonction. Ce dernier a cinq minutes à terminer ou Office arrête le runtime JavaScript. Toutefois, les fonctions appelées par Copilot n’ont que deux minutes pour retourner un résultat ou le runtime est arrêté.
  • Pour chaque fonction, il doit y avoir un appel d’Office.actions.associate pour indiquer à Office quelle fonction dans le fichier doit être exécutée lorsque l’action de l’agent est appelée. La associate fonction mappe le nom de la fonction à un ID d’action que vous configurez dans le manifeste à une étape ultérieure. Si vous définissez plusieurs fonctions dans le même fichier, votre code doit appeler associate pour chacune d’elles.

Voici un exemple.

Office.onReady(function() {
    // Add any initialization code here.
});

async function fillColorFromUserData(message) {
    const {Cell: cell, Color: color} = JSON.parse(message);
    await Excel.run(async (context) => {
      context.workbook.worksheets
        .getActiveWorksheet()
        .getRange(cell).format.fill.color = color;
      await context.sync();
    });
    return "Cell color changed.";
}

Office.actions.associate("FillColor", fillColorFromUserData);

Mise à jour du manifeste

La configuration du manifeste pour l’agent Copilot comporte trois parties principales, comme décrit dans les sous-sections suivantes.

Utiliser le schéma de manifeste en préversion

Vérifiez que le manifeste fait référence à la préversion du schéma de manifeste en procédant comme suit.

  1. En haut du manifeste, vérifiez que la "$schema" propriété est la suivante :

    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",

  2. Vérifiez que la "manifestVersion" propriété est définie sur « devPreview ».

Configurer le runtime

  1. Dans le "extensions.runtimes" tableau, vérifiez qu’il existe un objet runtime qui est orienté vers l’exécution de fonctions JavaScript sans interface utilisateur. Il est essentiel que l’objet ait une "code.page" propriété qui spécifie l’URL absolue du fichier HTML sans interface utilisateur que vous avez créé (ou modifié) précédemment dans Mettre à jour le fichier de fonction.
  2. Dans le "actions" tableau de ce même objet runtime, ajoutez un objet dont "type" la propriété est définie sur « executeDataFunction » et dont "id" la propriété correspond exactement au premier paramètre de l’appel à Office.actions.associate dans une fonction que vous avez créée dans Mettre à jour le fichier de fonction.
  3. Répétez l’étape précédente pour chaque fonction que vous avez créée pour implémenter une action d’agent.

L’objet runtime doit ressembler à ce qui suit. Il peut y avoir d’autres propriétés de l’objet runtime, d’autres objets runtime dans le "runtimes" tableau et d’autres objets d’action dans le "actions" tableau.

"runtimes": [
    {
        "id": "CommandsRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/commands.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "FillColor",
                "type": "executeDataFunction",
            }
        ]
    }
]

Déclarer l’agent

  1. S’il n’en existe pas déjà un, ajoutez un objet « copilotAgents » à la racine du manifeste et assurez-vous qu’il dispose d’un tableau « declarativeAgents » enfant.

  2. Ajoutez un objet au tableau et spécifiez-lui "declarativeAgents" un objet unique et descriptif "id" .

  3. Affectez à la propriété de "file" l’objet l’URL relative du fichier de configuration de l’agent déclaratif. Vous créez ce fichier à une étape ultérieure.

    Voici un exemple.

    "copilotAgents": {
    "declarativeAgents": [
        {
            "id": "ContosoCopilotAgent",
            "file": "declarativeAgent.json"
        }
    ]
},

Conseil

Pour optimiser la compatibilité avec les outils Microsoft pour le développement de compléments, nous vous recommandons de créer un dossier nommé appPackage à la racine du projet et de déplacer le manifeste dans celui-ci.

Créer la configuration de l’agent et du plug-in d’API

  1. Créez un fichier dans le dossier où se trouve votre manifeste et attribuez-lui le nom utilisé dans la "copilot.declarativeAgents.file" propriété, par exemple declarativeAgent.json.

  2. Collez le contenu suivant dans le fichier.

    {
     "$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": "Office-API-local-plugin.json"
         }
     ]
 }

  3. Remplacez les valeurs de propriété par les nouvelles valeurs appropriées pour votre complément. Pour plus d’informations sur ces propriétés, consultez Objet manifeste de l’agent déclaratif.

    Remarque

    Vous créez le fichier que vous spécifiez dans la "actions.file" propriété à l’étape suivante. Dans l’exemple ci-dessus, il s’agit du fichier Office-API-local-plugin.json.

  4. Créez un autre fichier dans le dossier avec votre manifeste et attribuez-lui le nom que vous avez affecté à la "actions.file" propriété à l’étape précédente, par exemple , Office-API-local-plugin.json.

  5. 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"]
         }
     ]
 }

  6. Avec certaines exceptions indiquées plus tard, remplacez les valeurs de propriété par de nouvelles valeurs appropriées pour votre complément. Pour plus d’informations sur ces propriétés, consultez Schéma de manifeste de plug-in d’API 2.3 pour Microsoft 365 Copilot.

    Pendant que vous travaillez, gardez à l’esprit les points suivants.

    • Ne modifiez pas les "namespace"valeurs , "runtimes.type"ou "runtimes.spec.local_endpoint" .

    • Doit "functions.name" correspondre exactement aux deux éléments suivants :

      • Propriété "extensions.runtimes.actions.id" dans le manifeste (pour une action de type « executeDataFunction »).
      • Premier paramètre de l’appel à Office.actions.associate dans une fonction que vous avez créée dans Mettre à jour le fichier de fonction.

    • Le "runtimes.run_for_functions" tableau doit inclure la même chaîne ou "functions.name" une chaîne générique qui lui correspond.

    • et "reasoning.description""reasoning.instructions" font référence à une fonction JavaScript, et non à une API REST.

    • La "runtimes.spec.local_endpoint" propriété est nouvelle et ne figure pas encore dans la documentation de référence main pour le schéma des plug-ins d’API. Pour plus d’informations à ce sujet, voir ci-dessous. Il indique à l’agent Copilot de rechercher des fonctions dans un complément Office au lieu d’une URL de service REST.

Créer le package d’application

Importante

Pour tester l’agent, comme décrit plus loin dans cet article dans Tester l’agent, le segment de domaine des URL absolues dans le manifeste doit être un domaine localhost ; par exemple, localhost:3000. Vous pouvez remplacer ces segments par un domaine de production ultérieurement.

À l’aide de n’importe quel utilitaire zip, créez un fichier zip qui contient les fichiers suivants.

Importante

La plupart de ces fichiers ont des URL dans le manifeste qui sont relatives à l’emplacement du manifeste. La structure de dossiers du fichier zip doit donc conserver cette structure. Par exemple, si la "icons.color" valeur est « /assets/icon-32.png », il doit y avoir un dossier /assets dans le fichier zip contenant le fichier icon-32.png .

Conseil

Pour optimiser la compatibilité avec les outils Microsoft pour le développement de compléments, nous vous recommandons de créer un sous-dossier nommé build dans le dossier appPackage et de créer le fichier zip qu’il contient.

Tester l’agent

Les trois principales étapes de test de l’agent (chargement indépendant, démarrage d’un serveur et exécution de l’agent) sont décrites dans les sous-sections suivantes.

Charger une version test de l’agent et du complément

Le chargement indépendant est effectué via Teams, même s’il n’existe aucune fonctionnalité Teams dans l’application. Les étapes sont les suivantes.

  1. Fermez toutes les applications Office, puis effacez le cache Office en suivant les instructions fournies dans Effacer manuellement le cache.
  2. Ouvrez Teams et sélectionnez Applications dans la barre de l’application, puis sélectionnez Gérer vos applications en bas du volet Applications .
  3. Sélectionnez Charger une application dans la boîte de dialogue Applications , puis dans la boîte de dialogue qui s’ouvre, sélectionnez Charger une application personnalisée.
  4. Dans la boîte de dialogue Ouvrir , accédez au fichier zip du package et sélectionnez-le.
  5. Sélectionnez Ajouter dans la boîte de dialogue qui s’ouvre.
  6. Lorsque vous êtes invité à indiquer que l’application a été ajoutée, ne l’ouvrez pas dans Teams. Au lieu de cela, fermez Teams.

Démarrer le serveur

Votre tâche consiste à démarrer un serveur web local qui héberge les fichiers HTML et JavaScript de votre projet. La façon dont vous procédez dépend de plusieurs facteurs, notamment la structure de dossiers de votre projet, les outils que vous utilisez, tels qu’un bundler, un gestionnaire de tâches, une application serveur, et la façon dont vous avez configuré ces outils. Étant donné que vous ajoutez un agent à un projet de complément existant, vous savez déjà comment procéder. L’instruction suivante s’applique uniquement aux projets qui remplissent les conditions suivantes.

  • Il existe un fichier webpack.config.js à la racine du projet qui est similaire à ceux des projets de complément créés avec le générateur Yeoman pour les compléments Office ou microsoft 365 Agent Toolkit.

  • Il y a un fichier package.json à la racine du projet similaire à ceux créés par les deux mêmes outils et le fichier contient une section « scripts » avec le script suivant.

    "dev-server": "webpack serve --mode development"

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.

Exécuter l’agent

  1. Ouvrez l’application Office (Excel, PowerPoint ou Word) que votre agent et complément combinés ciblent. Attendez que le complément soit chargé. Cette opération peut prendre deux minutes. Selon votre version d’Office, les boutons du ruban et d’autres artefacts peuvent apparaître automatiquement. Dans les versions récentes, vous devez activer manuellement le complément : sélectionnez le bouton Compléments dans le ruban Accueil , puis, dans le menu volant qui s’ouvre, sélectionnez votre complément. Il aura le nom du nom de la "name.short" propriété dans le manifeste.

  2. Ouvrez Copilot à partir du ruban et sélectionnez le contrôle hamburger dans le volet Copilot . Votre agent doit figurer dans la liste des agents. Il a le nom spécifié dans la "name" propriété du fichier de configuration de l’agent déclaratif (qui peut ne pas être le même que le nom de la "name.short" propriété dans le manifeste) ; par exemple, Agent Excel. Vous devrez peut-être sélectionner Afficher plus pour vous assurer que tous les agents sont répertoriés. 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, cliquez sur le curseur dans la fenêtre Copilot et appuyez sur Ctrl+R.

    Capture d’écran de la liste des agents dans le volet Copilot d’une application Office

  3. Lorsque l’agent est répertorié, sélectionnez-le et le volet de l’agent s’ouvre. Les démarrages de conversation que vous avez configurés dans la "conversation_starters" propriété du fichier de configuration de l’agent déclaratif s’affichent.

  4. Sélectionnez un starter de conversation, 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. L’action de l’agent se produit.

  5. Essayez d’entrer invite la boîte de conversation qui est différente des entrées de conversation, mais que votre agent doit être en mesure de faire.

Apporter des modifications dans l’application

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’agent et le complément en procédant comme suit.

  1. Fermez l’application Office.
  2. Si le serveur web s’exécute dans le terminal Visual Studio Code, donnez le focus au terminal et appuyez sur Ctrl+C. Choisissez « Y » en réponse à l’invite pour mettre fin au processus. Passez ensuite à l’étape suivante. Si le serveur web s’exécute dans une fenêtre distincte, ignorez cette étape et passez à l’étape suivante.
  3. Dans une invite de commandes ou Visual Studio Code TERMINAL à la racine du projet, exécutez npm run stop.
  4. Effacez le cache Office en suivant les instructions fournies dans Effacer manuellement le cache.
  5. Ouvrez Teams et sélectionnez Applications dans la barre de l’application, puis sélectionnez Gérer vos applications en bas du volet Applications .
  6. Recherchez votre agent dans la liste des applications. Il aura le nom spécifié dans la "name" propriété du fichier de configuration de l’agent déclaratif ; par exemple, Complément Excel + Agent.
  7. Sélectionnez la flèche à gauche du nom pour développer sa ligne.
  8. 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.

Résolution des problèmes

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