Écrire des instructions efficaces pour les agents déclaratifs avec des plug-ins d’API

Les agents déclaratifs adaptent Microsoft 365 Copilot aux besoins spécifiques d’une organisation. Lorsque vous créez des agents déclaratifs avec Microsoft 365 Agents Toolkit, vous pouvez ajouter des compétences à votre agent via des plug-ins d’API. Les plug-ins d’API permettent à votre agent d’interroger et d’interagir avec les données d’une organisation via des API.

Cet article décrit l’architecture de l’agent et fournit les meilleures pratiques pour l’écriture d’instructions pour les agents déclaratifs qui incluent des plug-ins d’API.

Principaux composants des agents déclaratifs avec des plugins API

Les agents déclaratifs qui appellent des plug-ins d’API comprennent plusieurs composants qui garantissent une intégration et une fonctionnalité efficaces. Comprendre cette architecture vous aidera à concevoir votre agent efficacement. L’architecture comprend les composants suivants :

• Manifeste de l’application : décrit comment votre application est configurée et fait référence au manifeste de l’agent déclaratif.
• Manifeste de l’agent déclaratif : définit la configuration de l’agent, y compris les instructions, les fonctionnalités, les démarrages de conversation et les actions. Fait référence au manifeste du plug-in.
• Manifeste de plug-in : décrit la configuration du plug-in, y compris les fonctions disponibles et une référence à la spécification OpenAPI.
• Spécification OpenAPI : fournit des définitions détaillées des points de terminaison d’API, y compris les chemins, les paramètres, les formats de demande et de réponse, et l’authentification.

Ensemble, ces fichiers définissent le comportement de l’agent et la façon dont il interagit avec l’API sous-jacente.

Pour plus d’informations sur les plug-ins d’API, consultez :

• Plug-ins pour Microsoft 365 Copilot
• Comment rendre un document OpenAPI efficace pour étendre les fonctionnalités de Copilot

Mappage de fonction dans le manifeste du plug-in

Dans le manifeste du plug-in, chaque fonction doit correspondre à un operationId correspondant dans la spécification OpenAPI . Ainsi, lorsque l’agent appelle une fonction (par exemple, createTask), il sait quel point de terminaison d’API appeler.

Les exemples suivants montrent le mappage dans le manifeste du plugin et la fonction mappée dans la spécification OpenAPI.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Meilleures pratiques pour les instructions d’agent

L’écriture d’instructions efficaces est essentielle pour garantir le succès des agents déclaratifs avec des plugins API. Pour optimiser votre agent, appliquez le mappage de fonctions correct, utilisez le chaînage pour permettre des interactions plus riches et testez et affinez de façon itérative le comportement de votre agent.

Appliquez les bonnes pratiques suivantes lors de l’écriture d’instructions pour les agents déclaratifs avec des plug-ins d’API :

• Évitez les instructions ambiguës ou négatives. Des instructions contrastées ou négatives peuvent introduire de l’ambiguïté et perturber le modèle. Concentrez-vous sur la définition de cas d’utilisation valides avec des exemples positifs. S’il est important de faire la distinction entre les requêtes valides et non valides, fournissez des critères clairs et des exemples qui définissent la réponse attendue de l’agent pour chacune d’elles.
• Utiliser des exemples Fournissez des exemples clairs pour guider le comportement des agents. Par exemple :

Saisie utilisateur : Quel temps fait-il à Prague ? Appel de l’agent : getWeather(location="Prague ») Entrée utilisateur : « Ai-je besoin d’un parapluie demain ? » Appel d’agent : getWeather(location=user_location, forecast="tomorrow »)

• Examinez et testez les instructions. Testez les instructions dans différents scénarios pour vérifier que l’agent effectue les appels de fonction corrects. Si, lors de tests, vous constatez que l’agent appelle des fonctions de manière inattendue, révisez la description de la fonction dans la spécification OpenAPI et clarifiez les instructions de l’agent pour améliorer le mappage d’intention.

• Concevez des instructions pour les conversations à plusieurs tours. Lorsque vous intégrez des plug-ins d’API, concevez vos instructions pour que l’agent gère les conversations à plusieurs tours.

Par exemple, si la fonction nécessite plusieurs paramètres, en plus de définir les paramètres requis dans la spécification OpenAPI, demandez à l’agent de collecter tous les paramètres avant d’effectuer l’appel d’API. Cela garantit que l’agent collecte toutes les informations requises dans une séquence logique.

L’exemple suivant montre comment donner des instructions à un agent météo pour les conversations multitour et le flux d’agent qui en résulte.

Instructions pour l’agent

Flux d’agent

Si l’utilisateur pose des questions sur la météo : - Demandez à l’utilisateur l’emplacement. - Demandez à l’utilisateur le jour de prévision. - Demandez à l’utilisateur le système d’unités. - N’appelez getWeather que lorsque vous collectez toutes les valeurs.

Utilisateur : « Quel temps fait-il ? » Agent : « Où êtes-vous ? » Utilisateur : « London" Agent : « Préférez-vous les informations météorologiques en unités métriques ou impériales ? » User : « Metric" Agent : « Avez-vous besoin de la météo d’aujourd’hui ou des prévisions pour demain ? » User : « Aujourd’hui" Agent : « Je vais vérifier la case activée pour Londres pour aujourd’hui" L’agent appelle : getWeather(location="London », forecast="today », system="Metric »)

Pour obtenir les meilleures pratiques générales concernant les instructions de l’agent, consultez Rédiger des instructions efficaces.

Chaînage des appels de fonction dans les plug-ins d’API

Le chaînage des appels de fonction permet aux agents déclaratifs de combiner plusieurs actions d’API dans un flux transparent. Les sections suivantes décrivent les modèles courants et comment écrire des instructions pour chacun d’entre eux.

Chaînage d’appels de fonction avec la sortie comme paramètre d’entrée

Utilisez le résultat d’un appel d’API comme entrée pour un autre. Cela est utile lorsque le résultat de la première fonction est nécessaire pour exécuter la deuxième fonction. Cela peut fonctionner sur plusieurs plugins.

Dans l’exemple suivant, un agent déclaratif avec API Météo et API To-do crée une tâche To-Do avec des données provenant des prévisions météorologiques.

Instructions pour l’agent	Flux d’agent
Pour obtenir la météo, utilisez toujours l’action getWeather , puis créez une tâche avec le titre « température d’arrivée » et ajoutez l’emplacement et la température mentionnés dans la météo au titre de la tâche.	Utilisateur : « Obtenir la météo à Prague" Agent : Appels getWeather (location="Prague », forecast="today ») Agent : utilise les données du premier appel pour créer une tâche à faire createTask (title ="{weather output} »)

Chaînage basé sur l’historique des conversations au sein d’un agent

Lorsque vous utilisez le chaînage basé sur l’historique des conversations, l’agent utilise les réponses antérieures pour gérer les actions de suivi. Cette approche utilise l’historique des conversations pour conserver le contexte.

Dans l’exemple suivant, un agent supprime une tâche par son nom.

Instructions pour l’agent	Flux d’agent
1. Lorsque l’utilisateur demande à répertorier toutes les tâches, appelez getTasks pour récupérer la liste des tâches avec le titre et l’ID. 2. Après avoir listé les tâches, si l’utilisateur demande à supprimer une tâche, utilisez l’ID de la réponse pour appeler deleteTask.	Utilisateur : « Afficher toutes les tâches dans le dossier Tâches ? » Agent : alls getTasks (folderId="Tasks ») et affiche toutes les tâches avec les ID. Utilisateur : Agent « Delete TaskMaster Pro to-do » : utilise les informations de l’historique des conversations pour trouver l’ID de la tâche et supprime la tâche en appelant deleteTask.

Chaînage avec la connaissance SharePoint

Le chaînage des appels d’API permet à un agent de combiner des sources de connaissances et des actions pour concevoir des flux de travail plus complexes.

Dans l’exemple suivant, un agent récupère les données de projet status à partir de SharePoint et crée les tâches correspondantes dans Microsoft To-Do pour le suivi.

Instructions pour l’agent	Flux d’agent
- Pour obtenir les statuts des projets, utilisez la connaissance de SharePoint ProjectDeadlines. - Créez toujours une tâche à faire pour chaque projet en utilisant la mise à jour du status pour le titre.	Utilisateur : « Pouvez-vous fournir une mise à jour sur le status de tous les projets ? » Agent : Extrait les données de status du projet de SharePoint, puis utilise createTask pour générer une tâche à faire pour chaque projet.

Chaînage avec l’interprète de code

Il est également possible d’enchaîner les appels d’API et d’intégrer des fonctionnalités supplémentaires, telles qu’un interpréteur de code. Cela permet à un agent de traiter les sorties d’API de manière dynamique pour permettre des flux de travail plus avancés.

Dans l’exemple suivant, un agent crée un graphique basé sur les données des tâches à effectuer.

Instructions pour l’agent	Flux d’agent
Lorsque l’utilisateur demande à répertorier toutes les tâches, appelez getTasks pour récupérer la liste des tâches avec le titre et l’ID, puis tracez également le graphique pour la sortie.	Utilisateur : « Retrieve all tasks in Tasks" Agent : appelle le getTasks (folderId="Tasks ») et affiche toutes les tâches avec des ID. Agent : Appelle l’interprète de code pour lancer la génération de graphiques en fonction de la sortie du premier appel.

Cet exemple exécute également plusieurs actions à la fois. Cela est utile pour lancer une série d’actions connexes qui ne nécessitent pas plusieurs entrées utilisateur.

Lorsque l’interpréteur de code génère un fichier (par exemple, une image de graphique ou une feuille de calcul), Copilot présente automatiquement un lien de téléchargement dans la réponse, ce qui permet aux utilisateurs d’enregistrer le fichier localement. Pour plus d’informations, consultez Générer des fichiers téléchargeables.

Contenu connexe

• Créer un agent déclaratif avec Visual Studio Code
• Plug-ins pour Microsoft 365 Copilot