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

Les plug-ins d’API permettent aux agents Microsoft 365 Copilot d’interagir avec les services web et d’accéder aux 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 via des commandes en langage naturel vers un agent dans Copilot Chat.

Un plug-in d’API est composé d’un service d’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 inclut une description OpenAPI pour le service d’API. La description OpenAPI est importante, car elle explique à Copilot comment se connecter à l’API. Pour une découverte et des performances optimales des plug-ins avec Copilot, fournissez une description OpenAPI claire et explicite.

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 agents 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 des descriptions OpenAPI parmi d’autres cas d’usage, ou tout autre outil de votre choix. Une description OpenAPI valide fonctionne bien avec Copilot, mais elle garantit également que votre description OpenAPI peut fonctionner avec d’autres outils.

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 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 infos est utilisée comme description du manifeste de plug-in. Par conséquent, il est important de toujours disposer d’un champ de description bref et clair. Par exemple, voici une section d’informations d’une description OpenAPI d’un atelier de réparation.

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’API et de méthode HTTP offerte par l’API. Les ID d’opération sont des identificateurs uniques pour une opération dans l’API et sont utilisés par Copilot pour créer des fonctions 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 répondre à la demande de l’utilisateur.

Les ID d’opération sont affichés pendant le débogage en tant que 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 :

Paramètres: Si une opération prise en charge par votre API accepte des paramètres, incluez les paramètres dans la description OpenAPI. Incluez un champ de description pour chaque paramètre afin de le décrire brièvement et, si nécessaire, donnez 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 envoyer 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 status et une description de ce qu’elle représente. L’inclusion d’exemples de réponses permet à Copilot de comprendre ce qu’il faut 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

Contenu connexe

• Écrire des instructions pour les agents avec des plug-ins d’API
• Plug-ins d’API pour Microsoft 365 Copilot