Créer un agent déclaratif avec un plug-in d’API
En ajoutant des actions à un agent déclaratif, vous lui permettez de récupérer et de mettre à jour les données stockées dans des systèmes externes. La connexion d’un agent à des systèmes externes que vous utilisez dans votre organization vous permet d’utiliser des agents pour prendre en charge vos processus métier. Les sections suivantes expliquent les différents éléments impliqués dans l’extension d’un agent déclaratif avec des actions.
Agent déclaratif
Les agents déclaratifs peuvent inclure une ou plusieurs actions qui leur permettent d’interagir avec des systèmes externes en temps réel. Par le biais d’actions, les agents peuvent lire et modifier les données stockées dans une application externe. Une action se connecte à une API via un plug-in d’API. L’agent définit ses actions dans le manifeste à l’aide du tableau d’actions :
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
"version": "v1.0",
"name": "Il Ristorante",
"description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.",
"instructions": "$[file('instruction.txt')]",
"actions": [
{
"id": "menuPlugin",
"file": "ai-plugin.json"
}
]
}
Vous définissez une action en ajoutant un élément au tableau d’actions . Chaque élément identifie de manière unique une action à l’aide d’un ID et utilise la propriété de fichier pour faire référence à un fichier de définition de plug-in distinct dans le projet qui décrit le plug-in d’API.
Définition de plug-in
Un fichier de définition de plug-in décrit un plug-in d’API qu’un agent déclaratif utilise pour communiquer avec une API. La définition du plug-in se compose de plusieurs sections, telles que les informations de base, les fonctions et les runtimes.
Informations de base
Chaque fichier de définition de plug-in contient des informations de base sur le plug-in, telles que son nom et sa description. L’extrait de code suivant montre un exemple d’informations de plug-in de base :
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.1/schema.json",
"schema_version": "v2.1",
"namespace": "ilristorante",
"name_for_human": "Il Ristorante",
"description_for_human": "See the today's menu and place orders",
"description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
"functions": [
],
"runtimes": [
],
"capabilities": {
"localization": {},
"conversation_starters": []
}
}
Le contenu des propriétés name_for_human et description_for_human est purement informatif. La propriété description_for_model est importante, car l’agent l’utilise pour décider s’il doit appeler le plug-in pour l’invite de l’utilisateur. Si vous voyez que votre agent n’appelle pas votre plug-in pour des invites spécifiques, vous devez case activée si la description du modèle contient les informations nécessaires pour que l’agent le considère comme pertinente.
Une autre propriété importante est l’espace de noms qui est requis et que l’agent utilise pour lever l’ambiguïté des actions entre les différents plug-ins. Si vous le supprimez ou fournissez une valeur non valide qui ne correspond pas au schéma, cela peut empêcher l’agent d’utiliser votre plug-in. L’espace de noms doit correspondre à l’expression ^[A-Za-z0-9_]+régulière suivante , ce qui signifie qu’il doit se composer d’au moins un caractère, tel que A-Z, a-z, 0-9ou _. Tout autre caractère n’est pas valide.
Fonctions
La section suivante de la définition du plug-in est functions. Les fonctions définissent une ou plusieurs opérations d’API que le plug-in d’API peut effectuer et indiquent à l’agent comment afficher les données qu’il reçoit de l’API. L’extrait de code suivant montre un exemple de fonction :
{
"functions": [
{
"name": "getDishes",
"description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
"capabilities": {
"response_semantics": {
"data_path": "$.dishes",
"properties": {
"title": "$.name",
"subtitle": "$.description"
},
"static_template": {
...trimmed for brevity
}
}
}
}
]
}
Chaque fonction se compose de plusieurs éléments.
Nom
Le nom identifie de manière unique l’opération dans le plug-in d’API, et qui doit correspondre exactement à un operationId de la spécification d’API associée. Si le nom que vous spécifiez ne correspond à aucune opération, microsoft 365 Agents Toolkit génère une erreur lors de la génération du projet. Si vous déployez une fonction dont le nom ne correspond pas à un operationId, l’agent ne peut pas appeler cette fonction.
Description
L’agent utilise la description pour faire correspondre une fonction à l’invite d’un utilisateur. Lorsque vous décrivez la fonction, veillez à expliquer les tâches qu’elle effectue, y compris les variantes, telles que le filtrage ou le tri des informations. Si la description est inexacte ou incomplète, l’agent ne peut pas la mettre en correspondance avec l’invite spécifique et ne peut pas appeler la fonction.
Sémantique de réponse
La propriété response_semantics indique à l’agent comment il doit afficher les données qu’il reçoit de l’API. Il se compose de trois propriétés : data_path, propriétés et static_template.
Si votre API retourne une structure de données complexe et que vous souhaitez que l’agent n’affiche qu’une partie spécifique de celle-ci, vous utilisez la propriété data_path pour spécifier une expression de chemin d’accès JSON qui pointe vers la partie appropriée de la réponse de l’API. Considérez la réponse de l’API suivante :
{
"dishes": [
{
"id": 1,
"name": "Classic Italian Frittata",
"description": "A fluffy omelette filled with sautéed mushrooms, onions, and melted pecorino, served with a side of roasted cherry tomatoes.",
"image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/frittata.jpeg",
"price": 8.99,
"allergens": [
"eggs",
"dairy"
],
"course": "breakfast",
"type": "dish"
},
...trimmed for brevity
]
}
Les données que vous souhaitez que l’agent affiche se trouve dans la propriété dishes , c’est pourquoi vous définissez la propriété data_path sur l’expression $.dishes JSONPath qui fait référence à la propriété dishes de l’objet racine indiqué par $.
La partie suivante de la sémantique de réponse est les propriétés. À l’aide de propriétés, vous indiquez à l’agent laquelle des propriétés de données de la réponse de l’API représentent les propriétés de l’élément, telles que le titre, la description ou l’URL. Lorsque votre API retourne plusieurs éléments, l’agent utilise le mappage sémantique pour inclure les informations les plus pertinentes dans la réponse. Considérez le mappage sémantique suivant :
{
"response_semantics": {
"properties": {
"title": "$.name",
"subtitle": "$.description"
}
}
}
Lorsque l’agent répond, il produit une réponse telle que :
Pour chaque plat, l’agent inclut un titre en gras, suivi d’une description. Étant donné que le mappage n’inclut pas d’URL ou d’étiquette de confidentialité, l’agent ne les inclut pas dans sa réponse.
La dernière partie de la sémantique de réponse est static_template. Vous utilisez un modèle statique pour définir un modèle de carte adaptative que l’agent doit utiliser pour afficher les données de l’API.
Conseil
Pour en savoir plus sur l’utilisation de modèles de carte adaptative avec des plug-ins d’API, consultez le module d’apprentissage Utiliser des cartes adaptatives pour afficher des données dans les plug-ins d’API pour les agents déclaratifs dans la section Plus de ressources à la fin de ce module d’apprentissage.
Services d’exécution
La dernière partie de la définition du plug-in est les runtimes. Les runtimes décrivent les API utilisées par le plug-in et les fonctions qui appartiennent à quelle API. L’extrait de code suivant montre une définition d’exécution :
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "apiSpecificationFile/ristorante.yml"
},
"run_for_functions": [
"getDishes",
"placeOrder"
]
}
Vous commencez par définir le type de description de l’API. À l’heure actuelle, les plug-ins d’API prennent uniquement en charge OpenAPI.
Ensuite, vous définissez si l’API est anonyme ou nécessite une authentification. Le type d’authentification None signifie que l’agent peut appeler l’API de manière anonyme. Si vous devez communiquer avec une API sécurisée, mettez à jour la valeur en conséquence pour qu’elle corresponde au mécanisme d’authentification de l’API. Pour plus d’informations sur les mécanismes d’authentification pris en charge, consultez la documentation.
Conseil
Pour en savoir plus sur la connexion de plug-ins d’API à des API sécurisées, consultez le module d’apprentissage Authentifier votre plug-in d’API pour les agents déclaratifs avec des API sécurisées dans la section Autres ressources à la fin de ce module d’apprentissage.
Dans la section suivante nommée spec, vous fournissez une référence à un document de spécification d’API local qui décrit l’API que le plug-in d’API peut utiliser. À l’aide de la propriété url , vous spécifiez un chemin d’accès relatif au fichier dans le projet.
La dernière partie est la propriété run_for_functions qui spécifie les fonctions spécifiées qui appartiennent à cette API.
Conseil
Lors de la génération du projet, Microsoft 365 Agents Toolkit vérifie que les fonctions spécifiées dans cette propriété correspondent aux fonctions définies dans la section fonctions et échoue avec une erreur si ce n’est pas le cas. Microsoft 365 Agents Toolkit vérifie la cohérence de votre projet vous donne des commentaires précoces et vous aide à éviter les erreurs difficiles à déboguer.
Spécification de l’API
Une partie importante de chaque plug-in d’API est la spécification de l’API, qui fournit des informations importantes sur l’API, notamment :
- Emplacement de l’API.
- Si l’API nécessite une authentification et, le cas échéant, de quelle manière.
- Quelles opérations l’API prend en charge.
- Pour chaque opération, les données attendues et la façon dont elle peut répondre.
Lorsqu’un agent charge un plug-in d’API, il utilise toutes ces informations pour générer une demande d’API, appeler l’API et traiter sa réponse. Il est donc important que vous décriviez clairement tous les paramètres et propriétés, afin que l’agent comprenne comment les utiliser pour répondre à la demande de l’utilisateur.
Si vous envisagez d’utiliser une API existante, veillez à inclure uniquement la partie de sa spécification d’API que vous envisagez d’utiliser dans le plug-in d’API. Si vous incluez l’ensemble de la spécification de l’API, mais que vous n’utilisez qu’une ou deux opérations, il est plus difficile pour l’agent d’analyser les informations pertinentes à partir de la spécification d’API volumineuse.
Conseil
Si vous devez utiliser une partie de votre spécification d’API existante, envisagez d’utiliser Hidi. Il s’agit d’un outil créé par Microsoft qui vous permet d’extraire facilement une partie pertinente d’une spécification d’API avec toutes les entités associées. Vous trouverez plus d’informations à la fin de ce module d’apprentissage.
Les agents prennent en charge les spécifications de l’API OpenAPI dans YAML et JSON.
Conseil
Lorsque vous créez une API personnalisée à utiliser par votre plug-in d’API et que vous l’exécutez à partir de votre ordinateur local, vous devez l’exposer à Internet afin que l’agent puisse l’appeler. Vous pouvez exposer votre API à l’aide de tunnels dev, un outil créé par Microsoft pour partager des services locaux sur Internet. Si vous utilisez Microsoft 365 Agents Toolkit pour créer votre agent avec le plug-in d’API, il démarre non seulement automatiquement un tunnel de développement, mais met également à jour automatiquement l’URL de votre API dans la spécification de l’API, ce qui vous permet de vous concentrer sur la création de votre solution.
Comment il s’intègre
Maintenant que vous connaissez les différents éléments d’un agent déclaratif avec un plug-in d’API, voyons comment ils s’intègrent. Le diagramme suivant montre les relations entre les différents éléments.
Vous utilisez des applications Microsoft Teams pour empaqueter et distribuer vos agents. Chaque application Teams peut contenir un ou plusieurs agents déclaratifs, chacun optimisé pour un scénario spécifique. Un agent, selon son objectif, peut contenir zéro ou plusieurs plug-ins d’API qui lui permettent de communiquer avec des systèmes externes. Un plug-in définit une ou plusieurs fonctions. Chaque fonction effectue une tâche spécifique et fait référence à exactement une opération d’API. En plus des fonctions, un plug-in d’API fait référence à une ou plusieurs spécifications d’API qui décrivent les API qu’il utilise. À son tour, chaque spécification d’API définit une ou plusieurs opérations qu’un plug-in peut utiliser via ses fonctions.