Plug-ins MCP et API pour les agents déclaratifs

MCP et les plug-ins d’API sont des actions personnalisées qui permettent aux agents déclaratifs dans Microsoft 365 Copilot d’interagir avec les serveurs MCP (Model Context Protocol) ou les API REST qui ont une description OpenAPI. En utilisant l’un de ces plug-ins, les utilisateurs peuvent demander à un agent déclaratif d’interroger un serveur MCP ou une API REST pour obtenir des informations et, le cas échéant, de créer, mettre à jour et supprimer des données et des objets par le biais d’invites en langage naturel.

Cet article utilise un plug-in pour l’action personnalisée technique MCP ou API utilisée par un agent déclaratif. Pour le produit, le package, le registre et le cycle de vie du plug-in destinés au client, consultez Plug-ins pour Microsoft 365 Copilot.

Pendant la génération ou la réutilisation, utilisez cet article pour choisir une action MCP ou API et comprendre comment l’orchestrateur l’appelle. Vous terminez avec le modèle d’action technique et une procédure produit pour le mettre en œuvre. L’action qui en résulte est une dépendance de l’agent, et non une promesse de distribution publique séparée.

Important

Les plug-ins MCP et API fournissent des actions dans les agents déclaratifs. Il ne s’agit pas de packages de plug-ins installables de manière autonome : seul l’agent contenant peut accéder à leurs fonctions et outils. Pour plus d’informations sur la relation entre le package et le manifeste d’action, consultez Plug-ins et actions d’agent déclaratif.

Un plug-in d’API ou MCP utilise un manifeste de plug-in que Copilot lit pour en savoir plus sur l’API ou le serveur MCP disponible pour l’agent. Copilot peut ensuite décider quand l’agent doit utiliser cette intégration pour répondre à une invite. Pour en savoir plus sur ce manifeste, consultez Schéma du manifeste du plug-in API et MCP. Le package installable utilise un manifeste d’application Microsoft 365 distinct.

Comment Copilot découvre les outils du serveur MCP

Pour les plug-ins basés sur un serveur MCP, Copilot résout les outils du plug-in de manière dynamique au moment de l’exécution par défaut, directement à partir du serveur MCP. La découverte dynamique d’outils signifie que vous obtenez les derniers outils exposés par le serveur MCP sans attendre que l’agent soit reconditionné et republié. Lors de la génération de l’agent, un développeur peut éventuellement épingler un ensemble fixe d’outils dans le manifeste du plug-in à la place. Les plug-ins de l’API REST utilisent toujours les outils définis dans le manifeste du plug-in. Pour plus d’informations, consultez Créer des plug-ins à partir d’un serveur MCP pour Microsoft 365 Copilot et Découverte d’outils dynamiques pour les plug-ins MCP dans Microsoft 365 Copilot.

Cette valeur par défaut s’applique aux plug-ins MCP utilisés comme actions d’agent déclaratif. Pour un plug-in qui fait référence à un serveur MCP distant dans agentConnectors le manifeste d’application Microsoft 365, la découverte d’outils dynamiques nécessite la version 1.29 ou ultérieure du manifeste d’application et un hôte qui l’autorise. Pour plus d’informations, consultez Configurer des serveurs MCP distants pour les plug-ins Microsoft 365 Copilot.

Exemple de plug-in

Envisagez un serveur MCP de budgets qui permet d’interroger et de créer des budgets, de facturer des dépenses ou d’ajouter des fonds aux budgets existants. L’invite « Combien reste-t-il dans le budget de voyage de Contoso » pouvait déclencher un plug-in de budget, appelant l’outil get-budgets .

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

Copilot utilise la réponse du résultat de l’outil pour générer sa réponse : « Le budget de voyage de Contoso dispose actuellement de 5 000 $ de fonds disponibles. Si vous avez besoin d’allouer des fonds à des catégories spécifiques ou de suivre les dépenses, je peux également vous aider. Faites-moi savoir comment je peux vous aider !

L’invite « Facturer 500 $ au budget de voyage Contoso pour le billet d’avion de Megan » peut être traduite par l’appel de l’outil MCP suivant.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "charge-budget",
    "arguments": {
      "budgetName": "contoso travel",
      "amount": 500,
      "description": "Megan's airline ticket"
    }
  }
}

Copilot répond à l’utilisateur en utilisant les informations renvoyées : « Les frais de 500 USD pour le billet d’avion de Megan sont traités avec succès. Le budget de voyage de Contoso dispose désormais de 4 500 $ de fonds disponibles. Si vous devez effectuer d’autres transactions ou si vous avez besoin d’une aide supplémentaire pour votre budget, faites-le moi savoir !

Fonctionnement des plug-ins

Un diagramme de séquence montrant le flux de données du plug-in

  1. L’utilisateur demande à l’agent : « Combien reste-t-il dans le budget de rénovation du hall du Fourth Coffee ? »

  2. Pour un plug-in MCP qui utilise la découverte dynamique d’outils, l’agent récupère les définitions d’outils actuelles à partir du serveur MCP du plug-in au moment de l’exécution et valide tous les outils nouveaux ou modifiés avant de les utiliser. Pour un plug-in avec un jeu d’outils épinglé ou pour un plug-in d’API REST, l’agent utilise les outils définis dans le manifeste du plug-in à la place.

  3. L’agent identifie un plug-in lié au budget à partir de ses plug-ins disponibles qui dispose d’un outil ou d’une API GetBudget serveur MCP pour obtenir les détails du budget. Il mappe des parties de la question de l’utilisateur aux paramètres de la fonction : budgetName="".

  4. L’agent demande à l’utilisateur de l’autoriser à envoyer Fourth Coffee lobby renovation au plugin.

  5. L’utilisateur choisit d’autoriser le partage des données avec le plug-in une fois, ou choisit de toujours autoriser le partage des données pour cette fonction.

  6. Si le serveur MCP ou l’API du plug-in nécessite une authentification, le plug-in demande un jeton ou une clé API au magasin de jetons.

  7. Le magasin de jetons renvoie un jeton ou une clé. Si nécessaire, l’agent amène l’agent à inviter l’utilisateur à se connecter.

  8. L’agent envoie une demande au serveur MCP ou à l’API du plug-in, qui est hébergé en dehors de Microsoft 365.

  9. Le serveur MCP ou l’API retourne une réponse.

    {
      "name": "Fourth Coffee lobby renovation",
      "availableFunds": 5000.00
    }
    
  10. L’agent génère une réponse basée sur la réponse du serveur MCP ou de l’API.

  11. L’agent envoie la réponse suivante : « Les fonds disponibles dans le budget de rénovation du hall du Fourth Coffee sont de 5 000 $. »

Actions de confirmation

Copilot demande à l’utilisateur avant d’envoyer des données pour la première fois à un module.

Capture d’écran de la boîte de dialogue de confirmation d’un module.

Une fois que l’utilisateur a confirmé la connexion, les outils et API du serveur MCP qui récupèrent uniquement les données ne nécessitent pas de confirmation, contrairement aux outils et API qui modifient les données. Les développeurs de plug-ins peuvent remplacer ces valeurs par défaut. Pour plus d’informations, consultez Invites de confirmation pour MCP et les plug-ins d’API pour Microsoft 365 Copilot.

Personnalisation de la présentation de la réponse

Copilot génère des réponses conversationnelles en utilisant les données du serveur MCP ou les réponses de l’API. Les plugins peuvent personnaliser la façon dont ces données sont présentées et le mécanisme dépend du type de plugin.

  • Les plug-ins MCP peuvent fournir des réponses riches et interactives en utilisant des applications MCP : widgets d’interface utilisateur que le serveur MCP retourne avec le résultat de l’outil au moment de l’exécution. Étant donné que le widget est fourni avec la réponse de l’outil plutôt que défini dans le manifeste, les applications MCP fonctionnent, que le plug-in utilise un ensemble d’outils épinglés ou une découverte d’outil dynamique.

  • Les plugins d’API peuvent fournir des modèles de carte adaptative dans le manifeste du plugin pour afficher les données de manière structurée. Étant donné que les modèles sont définis par rapport aux opérations déclarées dans le manifeste, cette approche s’applique aux plug-ins d’API et aux plug-ins MCP qui utilisent un ensemble d’outils épinglés.

Pour les citations liées à la source sur n’importe quel type de plug-in, Copilot utilise la sémantique de réponse et peut déduire automatiquement les métadonnées de citation à partir de l’outil ou de la réponse API. L’inférence automatique est particulièrement utile pour les plug-ins MCP qui utilisent la découverte d’outils dynamique, où les outils sont résolus au moment de l’exécution et où il n’y a aucune définition d’outil de manifeste à configurer. Pour plus d’informations, voir Afficher les citations avec la sémantique des réponses.

Capture d’écran d’une réponse de carte adaptative à partir d’un plug-in d’API

Gestion des URL dans les réponses d’action

L’expérience de conversation Microsoft 365 Copilot peut afficher les URL retournées dans le cadre des réponses à l’action (qu’il s’agisse de plug-ins MCP, de plug-ins d’API, de connecteurs ou de flux) sous forme de liens cliquables. Le runtime Copilot contrôle ce comportement et ne l’évalue pas par rapport aux domaines déclarés par le plug-in (comme la section de la servers description OpenAPI d’un plug-in d’API).

Les règles de sécurité, de confiance et de stratégie de la plateforme régissent le comportement de rendu des URL pour les réponses d’action et peuvent changer au fil du temps. Ne vous fiez pas aux URL cliquables dans les réponses d’action pour les scénarios critiques pour la production.

Aidez l’orchestrateur Copilot à choisir les actions de votre agent

Décrivez l’intégration API ou MCP, ses fonctions ou outils, et leurs entrées avec précision afin que l’orchestrateur puisse sélectionner l’action appropriée pour la demande de l’utilisateur. Ces descriptions concernent les actions de l’agent, et non le nom ou la description de la boutique du package de plug-in externe.

Intégration d’actions Où le décrire En savoir plus
Plug-in API Manifeste du plug-in et opérations et descriptions des paramètres OpenAPI Créer des descriptions OpenAPI efficaces
Plug-in MCP Manifeste du plugin et descriptions des outils MCP ; Les définitions d’outil proviennent du serveur au moment de l’exécution ou sont épinglées dans le manifeste Détection dynamique des outils et outils épinglés

Les fonctions et les outils MCP ne sont pas identiques aux fichiers d’instructions réutilisables décrits dans Compétences en tant que fonctionnalités de plug-in.

Créer un agent déclaratif avec des actions API ou MCP

Pour le développement professionnel, commencez avec Work IQ Dev Tools. Choisissez d’abord un environnement documenté, puis ajoutez un outil dans la liste suivante lorsque vous avez besoin de ses capacités de génération ou d’intégration de projet :

  • Work IQ Dev Tools est l’outil recommandé. Permet wiqd agent add action d’ajouter une action OpenAPI ou MCP distante prise en charge à un projet d’agent déclaratif.
  • Les procédures pas à pas existantes basées sur Toolkit restent disponibles pour un serveur MCP, une description OpenAPI ou une nouvelle API REST. Suivez ces procédures lorsque vous travaillez sur un projet Toolkit.
  • Kiota peut générer un manifeste de plug-in API à partir d’une description OpenAPI existante.

L’API ou le manifeste du plug-in MCP configure l’intégration des actions de l’agent. Empaquetez et distribuez l’agent contenant via son itinéraire app-package pris en charge ; Le manifeste d’action n’est pas un package de plug-in installable indépendamment.

Conseil

Work IQ Dev Tools est généralement disponible. wiqd agent add action Ajoute une action à un projet d’agent déclaratif et wiqd agent validate --mode source exécute des vérifications hors connexion de la source de l’agent enregistrée. Une réussite de la case activée de source n’établit pas l’accessibilité des points de terminaison Runtime ou OpenAPI, l’exactitude de l’authentification ou l’acceptation du package final. Si vous omettez --mode, la validation est définie par défaut sur package, qui charge une copie d’un fichier zip existant et peut nécessiter une connexion. Pour connaître les modes de validation et la couverture, consultez la référence à la commande WIQD et la validation et MVL.

Limites

Ces limites concernent les plugins d’API et de MCP utilisés en tant qu’actions d’agent déclaratif, et non le nombre de compétences, d’agents ou de connecteurs dans un package de plugins installables.

Lorsqu’un agent déclaratif inclut jusqu’à cinq plug-ins définis dans le manifeste de l’agent déclaratif, l’agent injecte toujours les plug-ins dans l’invite. Lorsque l’agent inclut plus de cinq plug-ins, il utilise la correspondance sémantique. La correspondance sémantique est basée sur la description du plugin, et non sur l’une des fonctions ou outils individuels du plugin lui-même.

Un plugin peut inclure un nombre illimité de fonctions ou d’outils MCP. Toutes les fonctions ou outils d’un plug-in correspondant sont retournés, même si un seul est mis en correspondance. Pour un plug-in MCP qui utilise la découverte d’outils dynamique, les outils résolus à partir du serveur MCP au moment de l’exécution sont comptabilisés dans ce total. En raison des limites de fenêtre de jeton, la qualité des réponses peut se dégrader si plus de 10 fonctions ou outils sont inclus.

La fenêtre de jeton pour les entrées et les sorties d’un plug-in tronque le contenu volumineux. La limite fonctionnelle est susceptible d’être modifiée à mesure que les modèles s’améliorent et en fonction de toute surcharge du système. Optimisez les petites longueurs de jeton ou optez pour des options d’extensibilité qui permettent de diffuser en continu du contenu volumineux si nécessaire.

Étape suivante

Implémentez l’action MCP ou l’action API sélectionnée. Une fois que les composants fonctionnent individuellement, entrez Package & tester avec Intégrer et tester vos composants.