Créer des descriptions OpenAPI effectives pour étendre Microsoft 365 Copilot

Les plug-ins d’API permettent aux agents de Microsoft 365 Copilot d’interagir avec les services web et d’accéder à des informations en temps réel. Un plug-in d’API permet aux utilisateurs d’interagir avec les données en temps réel de leur système métier (LOB) via des commandes en langage naturel vers un agent dans Copilot Chat.

Un plug-in API est composé d’un service API, de sa description OpenAPI et d’un fichier manifeste. Le manifeste du plug-in informe l’orchestrateur Copilot des fonctionnalités de l’API. Le manifeste du plug-in comprend une description OpenAPI pour le service API. La description OpenAPI est importante car elle décrit à Copilot comment se connecter à l’API. Pour optimiser la détectabilité et les performances des plug-ins avec Copilot, fournissez une description OpenAPI claire et significative.

Cet article décrit les éléments qui rendent une description OpenAPI efficace pour un plug-in qui étend les fonctionnalités de l’agent Copilot.

Éléments de description OpenAPI

Cette section décrit les éléments d’une description OpenAPI et comment les optimiser pour les assistants Copilot.

Validation OpenAPI : Une bonne première étape consiste à vérifier que votre description OpenAPI suit les règles de la spécification OpenAPI. Vous pouvez utiliser Hidi, un outil en ligne de commande qui peut valider les descriptions d’OpenAPI entre autres cas d’utilisation, ou tout autre outil de votre choix. Une description OpenAPI valide fonctionne non seulement bien avec Copilot, mais garantit également que votre description OpenAPI peut fonctionner avec d’autres outils.

La section d’informations : le champ de description est facultatif dans la spécification OpenAPI, mais il est essentiel pour une description OpenAPI destinée à étendre les compétences de Copilot. Copilot a besoin du champ de description pour savoir ce que fait l’API et quand utiliser le plug-in. Lors de la génération d’un manifeste de plug-in à partir d’un document OpenAPI, la description dans la section d’informations est utilisée comme description du manifeste du plug-in. Par conséquent, il est important de toujours avoir un champ de description bref et clair. Par exemple, voici une section d’informations de la description d’un atelier de réparation OpenAPI.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

ID d’opération : Une technique utile pour améliorer la facilité d’utilisation d’une description OpenAPI consiste à ajouter un operationID pour chaque combinaison de chemin d’accès API et de méthode HTTP offerte par l’API. Les ID d’opération sont des identificateurs uniques d’une opération dans l’API et sont utilisés par Copilot pour créer des fonctions qui sont exécutées lors de la réponse à l’invite d’un utilisateur.

Ajoutez également une description explicite de chaque opération prise en charge par votre API. Une fois que Copilot a choisi d’utiliser un plug-in en fonction de l’invite de l’utilisateur et de la description du plug-in, il recherche dans les descriptions des chemins d’accès pour déterminer le point de terminaison à utiliser pour satisfaire la demande de l’utilisateur.

Les ID d’opération sont affichés pendant le débogage sous forme de fonctions pour indiquer les opérations que Copilot tente d’exécuter. Voici un exemple de document OpenAPI et un exemple de sortie du débogueur correspondant :

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Sortie du débogueur :

Image du débogueur montrant la fonction sélectionnée d’un module.

Paramètres : Si une opération prise en charge par votre API accepte des paramètres, incluez ces paramètres dans la description OpenAPI. Incluez un champ de description pour chaque paramètre afin de le décrire brièvement et, le cas échéant, de donner un exemple d’utilisation du paramètre. Les paramètres sont utilisés par Copilot pour obtenir toutes les informations requises à partir de l’invite d’un utilisateur pour effectuer une requête à l’API.

Voici un exemple :

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Réponses : Définissez clairement toutes les réponses possibles pour chaque opération, y compris les réponses de réussite et d’erreur. Chaque réponse doit avoir un code de status et une description de ce qu’il représente. L’inclusion d’exemples de réponses aide Copilot à comprendre ce qu’il peut attendre de l’API.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error