Étendre votre agent avec des outils à partir d’une API REST (préversion)

[Cet article fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]

Vous pouvez utiliser les API REST (y compris l’API OpenAI) pour connecter un assistant que vous créez à des systèmes externes et accéder aux données disponibles à utiliser dans votre assistant. Vous pouvez connecter votre assistant à une API REST en fournissant trois choses à Copilot Studio :

• Spécification OpenAPI définissant les fonctions de l’API et les actions disponibles
• Détails sur le type d’authentification nécessaire et les détails d’authentification permettant aux utilisateurs de se connecter à l’API pour accéder au système externe
• Descriptions pour aider le modèle de langage à déterminer quand appeler l’API pour utiliser les données

Les API REST peuvent être ajoutées aux assistants Copilot et aux assistants personnalisés via Copilot Studio.

Les assistants Copilot permettent à un créateur de combiner plusieurs sources de données telles que des connecteurs, des API, des invites et des sources de connaissances en un seul agent. Vous pouvez utiliser cet assistant pour étendre les expériences d’assistant de marque Microsoft comme Microsoft 365 Copilot.

Les agents personnalisés sont des agents autonomes qui contiennent des connecteurs, des API, des invites et des sources de connaissances. Vous pouvez utiliser directement des agents personnalisés en les intégrant à des sites web ou à d’autres canaux.

Prérequis

Quelques conditions préalables sont nécessaires pour étendre les expériences d’agent de marque Microsoft avec des actions de connecteur.

Pour tous les types d’expérience d’assistant, vous devez disposer d’informations d’identification de niveau créateur et d’une licence Copilot Studio.

Vous avez également besoin d’une copie de la spécification OpenAPI, de la connaissance du type d’authentification nécessaire et des détails d’authentification.

Ajouter une action API REST à un agent

L’ajout d’une API REST à votre agent implique quelques étapes. Les sections suivantes vous guident tout au long du processus.

Le processus d’ajout d’une API REST est identique pour les agents personnalisés et les assistants Copilot.

Le processus comprend quelques étapes.

Ajouter une action à l’agent

1. accédez à la page Vue d’ensemble de votre agent.

   

2. Dans la section Outils , sélectionnez Ajouter un outil. Vous pouvez également accéder à l’onglet Outils et sélectionner Ajouter un outil.

   La page Ajouter un outil s’affiche.

3. Sélectionnez Nouvel outil>API REST.

Fournir la spécification, la description et la solution de l’API

1. Chargez un fichier de spécification OpenAPI pour l’API REST à laquelle vous souhaitez vous connecter. Vous pouvez soit glisser-déposer le fichier de spécification dans l’écran Charger une API REST, soit parcourir votre système pour localiser le fichier que vous souhaitez utiliser.

   

   Nonte

   Le fichier de spécification OpenAPI doit être un fichier JSON au format v2. Si un fichier de spécification v3 est envoyé, il est automatiquement converti en fichier de spécification v2 au cours du processus de création.

   Une fois que vous avez téléchargé la spécification, l’écran est mis à jour pour indiquer le nom du fichier de spécification et les détails.

   

   Dans les étapes qui suivent, nous fondons la procédure sur un exemple spécifique de SunnyADO, un système de gestion des tickets ADO. Dans l’exemple, l’intention est de permettre aux utilisateurs de récupérer et de mettre à jour leurs tickets via l’agent.

2. Vérifiez les détails, puis sélectionnez Suivant.

   Une page de détails du plug-in d’API s’affiche où vous pouvez fournir des informations supplémentaires sur l’API.

   

   Le champ de description est initialement renseigné en fonction de la description de la spécification d’API que vous avez chargée. Fournissez une description détaillée, car l’orchestration des assistants utilise la description pour déterminer quand utiliser cet outil particulier. Fournissez des détails, y compris des synonymes, pour aider votre agent dans le processus de sélection.

   Par exemple, la description initiale fournie est : « Un service simple de gestion des tickets. »

   Une meilleure description est la suivante : « Un système utilisé pour obtenir, récupérer, trouver et afficher des tickets existants à partir de SunnyADO. Il permet aux utilisateurs de mettre à jour, de modifier et de gérer les tickets afin de fournir plus de données pour améliorer les enregistrements.

3. Saisissez une description améliorée dans le champ Description.

4. Sous Solution, une liste déroulante répertorie toutes les solutions disponibles dans l’environnement actuel. Sélectionnez la solution que vous souhaitez utiliser. Pour plus d’informations sur ce que sont les solutions, consultez Concepts de solution.

   

   Si vous avez une solution préférée ou si le connecteur que vous avez sélectionné est déjà dans la solution, cette solution est automatiquement sélectionnée.

   Vous pouvez soit sélectionner une solution, soit laisser le champ vide. Si vous laissez la solution vide, une solution est créée pour vous avec le nom de l’action et l’éditeur par défaut. Le stockage de votre action dans une solution vous permet de la déplacer facilement entre les environnements.

   Nonte

   Si vous ne voyez pas la solution par défaut ni la solution par défaut CDS comme option dans ce cas, nous vous recommandons d’avoir une solution personnalisée pour faciliter la gestion. Pour plus d’informations, consultez : Solution par défaut et solution personnalisée.

5. Une fois une solution sélectionnée, sélectionnez Suivant pour continuer.

Fournir les détails d’authentification

La page Authentification s’affiche pour sélectionner le type d’authentification à utiliser pour l’API.

1. Sélectionnez une méthode d’authentification dans la liste.

2. Renseignez les champs obligatoires pour la méthode d’authentification. Les champs varient en fonction de la méthode d’authentification.

   • Aucun : aucun autre champ n’est obligatoire.
   • Clé API :
     • Étiquette de paramètre : une étiquette de texte pour le paramètre API.
     • Nom du paramètre : nom textuel du paramètre d’API.
     • Emplacement du paramètre : la position où le paramètre peut être trouvé.
   • Auth 2.0 :
     • ID client : GUID client pour le service cible.
     • Clé secrète client : valeur secrète pour le client. Le secret ne s’affiche pas lorsque l’utilisateur ouvre le volet d’édition par la suite. Cependant, stockez la clé secrète, car vous en aurez besoin si vous choisissez d’apporter d’autres modifications.
     • URL d’autorisation : URL utilisée pour autoriser le système source.
     • URL du jeton : URL où le jeton peut être récupéré.
     • URL d’actualisation : URL vers laquelle vous êtes redirigé dans un scénario d’actualisation.
     • Étendue : URL de l’étendue attribuée à l’API pour les applications Microsoft Entra.
     • Quelle organisation Microsoft 365 accède aux points de terminaison : cela limite l’accès à la source à l’organisation du créateur ou à toutes les organisations.
     • Quelle application (client) peut utiliser les points de terminaison : GUID qui définit le système client qui peut être utilisé pour accéder à ces données. Les applications peuvent inclure Microsoft 365, Power Automate et d’autres options.

3. Une fois tous les champs remplis, sélectionnez Suivant.

   Vous êtes sur une page Sélectionner et configurer votre outil de plug-in où vous pouvez choisir les outils à activer pour l'API.

   

Sélectionner des outils pour l’API

Choisissez les outils pris en charge par l’API à activer. En règle générale, une API REST offre une gamme d’outils via les différentes combinaisons de points de terminaison et de méthode HTTP (get, put, post, delete, et ainsi de suite) définies dans la spécification de l’API. Dans certains cas, vous ne souhaitez peut-être pas que les utilisateurs de l'agent aient la possibilité d’exécuter toutes les actions généralement offertes par l’API. Par exemple, votre spécification d’API peut inclure des actions de mise à jour et de suppression, mais vous souhaitez que seuls les utilisateurs de votre agent puissent créer des enregistrements.

1. Sélectionnez un outil dans la liste à configurer.

   La page Configurer votre action de plug-in s’affiche.

   

2. Configurez l’action sélectionnée. Comme avec l’API globale, vous êtes invité à fournir un nom d’outil et une description de l’outil. Les descriptions sont initialement préremplies à partir des descriptions de la spécification de l’API. Le nom n’a pas besoin d’être unique, mais il doit représenter l’outil lui-même. La description, comme avec la description globale de l’API, doit être suffisamment spécifique pour fournir au modèle de langage des détails pour mieux identifier que votre requête s’aligne sur cet outil spécifique.

3. Une fois les champs renseignés, sélectionnez Suivant.

   La page Vérifier les paramètres de votre outil s’affiche .

   

   Cette page affiche les valeurs fournies dans le cadre des valeurs d’entrée et de sortie possibles. Ces valeurs ne peuvent pas être modifiées, mais les descriptions des entrées et sorties peuvent être mises à jour. Tout le contenu de cette page est extrait directement de la spécification d’API téléchargée.

4. Renseignez les valeurs selon vos besoins pour les descriptions. Les descriptions fournissent une définition de l’utilisation des valeurs. Si l’une des descriptions est vide, elle doit être complétée avant de pouvoir continuer. Vous pouvez coller le nom si vous n’avez pas une meilleure description.

5. Une fois les descriptions terminées, sélectionnez Suivant.

   Le premier outil est maintenant configuré et apparaît dans la liste des outils sélectionnés dans la page Sélectionner et configurer votre outil de plug-in .

   

6. Ajoutez toutes les autres actions que vous souhaitez inclure pour le moment. Une fois que vous avez terminé d’ajouter des outils que votre agent prend en charge, sélectionnez Suivant.

   La page Vérifier votre outil s’affiche. La page fournit les détails de l’outil d’API REST configuré.

   

Vérifier et publier

1. Si vous avez besoin d’effectuer des mises à jour, vous pouvez sélectionner Précédent et apporter vos modifications. Sinon, sélectionnez Suivant.

   Un écran s’affiche indiquant que votre outil est publié pendant la fin du processus. Vous en êtes informé une fois la publication terminée.

2. Une fois la publication terminée, vous êtes retourné à l’écran Choisir un outil . Ici, vous pouvez ajouter l’API REST nouvellement configurée dans votre assistant Copilot ou votre agent personnalisé et terminer la configuration du composant.

   

L’outil API REST est désormais disponible pour une utilisation dans votre agent.