Combiner des agents Copilot avec des compléments Office (préversion)

2025-06-10

Remarque

Cet article part du principe que vous êtes familiarisé avec les agents déclaratifs Copilot. Si ce n’est pas le cas, commencez par ce qui suit :

L’inclusion d’un agent Microsoft 365 Copilot dans 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.

Vous pouvez également considérer un complément Office comme une compétence dans un agent Copilot. Étant donné que les compléments Office utilisent la bibliothèque JavaScript Office pour effectuer des opérations de lecture et d’écriture sur des documents Office, ces opérations deviennent des actions dans l’agent Copilot.

Scénarios

Voici quelques-unes des méthodes sélectionnées par lesquelles l’ajout d’un agent Copilot améliore la valeur d’un complément pour les utilisateurs.

Apprendre à utiliser le 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 la 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 qui utilise la bibliothèque JavaScript Office peut être invité à produire une première liste brouillon de questions et à les insérer dans un document Word.
Analyse du contenu : un agent peut être utilisé pour analyser le contenu d’un document 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, puis extrait les réponses aux questions dans l’appel d’offres à partir d’un système principal. L’utilisateur invite simplement l’agent à « Fournir 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 dire « Examiner le document à la recherche d’éléments que j’ai manqués dans la liste d’audit ».
Insertion approuvée de données : si vous invitez un moteur d’IA classique avec une question, 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 complément qui permet d’insérer des recherches juridiques dans Word où elles peuvent ensuite être modifiées. Un utilisateur invite l’agent : « Dans quelles circonstances un bail d’espace résidentiel dans l’Indiana peut-il être rompu unilatéralement par le loueur ? » Le complément extrait ensuite le contenu, inchangé, des précédents et des lois.
- Prenons l’exemple d’un complément qui gère l’inventaire des ressources numériques. Dans la conversation de l’agent Copilot, un utilisateur demande : « Insérez 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ées dans l’ordre de la plupart des téléchargements. » Le complément extrait ensuite ces données, inchangées, à partir du système d’enregistrement et insère le tableau dans une feuille de calcul Excel.

Relation entre les agents Copilot et l’infrastructure de complément

Un agent Copilot est une interface en langage naturel pour un complément.

Un complément peut être configuré pour être uniquement une compétence dans un agent Copilot. Il n’est pas nécessaire d’inclure un volet Office, des boutons de ruban personnalisés ou des menus personnalisés ; mais il peut avoir l’une de ces compétences en plus d’être une compétence de copilote. La meilleure approche dépend des scénarios utilisateur que le complément doit activer.

Si le complément doit fournir des actions simples et rapides qui n’ont pas besoin de paramètres qui leur sont transmis, incluez des boutons ou menus personnalisés du ruban, appelés commandes de complément, dans le complément.
Si le complément a besoin d’une expérience de tableau de bord, si l’utilisateur doit configurer des 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 volet Office dans le complément.
Si le complément doit fournir des actions complexes qui nécessitent des paramètres passés au moment de l’exécution ou a besoin d’une interface en langage naturel, incluez un agent Copilot.

Remarque

Actuellement, seuls les compléments Excel, PowerPoint et Word peuvent être configurés en tant que compétence dans Copilot. Nous travaillons à la prise en charge d’Outlook.
Les agents Copilot ne sont actuellement pas pris en charge dans Office sur Mac.
Un complément doit utiliser le manifeste unifié pour que Microsoft 365 soit configuré en tant que compétence dans Copilot.
Un complément de contenu ne peut pas être une compétence dans Copilot.

Tâches principales

Il existe deux tâches principales pour configurer un complément en tant que compétence Copilot, et elles sont analogues aux deux tâches de configuration des commandes de fonction pour un complément.

Créez des fonctions JavaScript qui implémentent les actions de l’agent.
Utilisez JSON pour spécifier pour Office et les runtimes JavaScript les noms de ces fonctions.

Configuration JSON

La configuration d’un complément comme compétence Copilot nécessite trois fichiers au format JSON décrits dans les sous-sections suivantes.

Manifeste unifié pour Microsoft 365

Il existe deux parties du manifeste que vous configurez. Tout d’abord, créez un objet action qui identifie la fonction JavaScript appelée par l’action. Voici un exemple (avec un balisage superflu omis). Notez ce qui suit à propos de ce code.

La propriété « page » spécifie l’URL de la page web qui contient une balise de script incorporée qui, à son tour, spécifie l’URL du fichier JavaScript où la fonction est définie. Ce même fichier contient un appel de la méthode Office.actions.associate pour mapper la fonction à un ID d’action.
La "actions.id" propriété dans le manifeste est le même ID d’action que celui passé à l’appel de associate.
La "actions.type" propriété est définie sur « executeDataFunction », qui est le type qui peut accepter les paramètres et peut être appelé par Copilot.

"extensions": [

    ...

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

Ensuite, créez un objet agent déclaratif qui identifie le fichier contenant la configuration détaillée de l’agent. Voici un exemple.

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

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.

Configuration de l’agent déclaratif

Le fichier de configuration de l’agent inclut des instructions pour l’agent et spécifie un ou plusieurs fichiers de configuration de plug-in d’API qui contiendront la configuration détaillée des actions de l’agent. Voici un exemple. Notez ce qui suit à propos de ce JSON.

Le démarrage de conversation s’affiche dans le canevas de conversation de Copilot.
La "actions.id" propriété dans ce fichier est l’ID collectif de toutes les fonctions dans le fichier spécifié dans "actions.file". Il n’a pas besoin de correspondre "actions.id" au dans le manifeste.

{
    "$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"
        }
    ]
}

La documentation de référence pour les agents déclaratifs se trouve dans Schéma de l’agent déclaratif 1.3 pour Microsoft 365 Copilot.

Configuration du plug-in d’API Copilot

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 des fonctions JavaScript, y compris les instructions pour l’action. Il configure également le runtime JavaScript pour Copilot. Voici un exemple. À propos de ce JSON, notez les points suivants :

doit "functions.name" correspondre à la "extensions.runtimes.actions.id" propriété dans le manifeste du complément.
et "reasoning.description""reasoning.instructions" font référence à une fonction JavaScript, et non à une API REST.
La "responding.instructions" propriété fournit uniquement des conseils à Copilot sur la façon de répondre. Il n’impose pas de limites ou d’exigences structurelles à la réponse.
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.
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. Dans ce cas, il spécifie que la fonction JavaScript associée à la chaîne « fillcolor » est disponible dans un complément Office, plutôt que dans un point de terminaison REST. -La "runtimes.spec.allowed_host" 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. Dans ce cas, il spécifie que l’agent doit uniquement être visible dans Excel.

{
    "$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 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"]
        }
    ]
}

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.3 pour Microsoft 365 Copilot. Voici la documentation de deux nouvelles propriétés de la "runtimes.spec" propriété .

Propriété	Type	Description
`local_endpoint`	String	Facultatif. ID d’un ensemble de fonctions JavaScript disponibles. Cette propriété est à peu près analogue à la `"runtimes.spec.url"` propriété, mais pour les fonctions locales sur le client, pas les API REST. Actuellement, la seule valeur autorisée est « Microsoft.Office.Addin ».
`allowed_host`	String	Facultatif. Spécifie les copilotes d’application Office qui peuvent héberger l’agent. Les valeurs possibles sont « document », « mail », « presentation » et « workbook ».

Créer les fonctions JavaScript

Les fonctions JavaScript qui seront appelées par l’agent Copilot sont créées exactement comme les commandes de fonction sont créées . Voici un exemple. Notez ce qui suit à propos de ce code.

Contrairement à une commande de fonction, une fonction associée à une action Copilot peut prendre des paramètres.
Le premier paramètre de la associate méthode doit correspondre à la "extensions.runtimes.actions.id" propriété dans le manifeste du complément et à la "functions.name" propriété dans le json du plug-in d’API.

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, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

Une fois vos fonctions créées, créez un fichier HTML sans interface utilisateur qui contient une <script> balise qui charge le fichier JavaScript avec les fonctions. L’URL de ce fichier HTML doit correspondre à la valeur de la "extensions.runtimes.code.page" propriété dans le manifeste. Consultez Manifeste unifié pour Microsoft 365 plus haut dans cet article.

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

Voici quelques problèmes courants et des solutions suggérées.

L’action de l’agent échoue avec un message indiquant que l’action n’a pas été trouvée dans le complément. Voici quelques causes possibles.
- La "functions.name" valeur de propriété dans le json du plug-in ne correspond exactement à aucune "extensions.runtimes.actions.id" propriété dans le manifeste du complément.
- Il existe une correspondance "actions.id" dans le manifeste, mais la valeur frère "actions.type" du même objet d’action n’est pas « executeDataFunction ».
L’action de l’agent échoue avec un message indiquant que l’inscription du gestionnaire d’actions est introuvable. La cause suivante est possible.
- Le code JavaScript du complément n’a pas d’appel de Office.actions.associate avec le premier paramètre correspondant exactement à la valeur de propriété "functions.name" dans le json du plug-in.