Schéma de manifeste de plug-in d’API pour Microsoft 365 Copilot
Importante
Les plug-ins d’API sont actuellement uniquement pris en charge en tant qu’actions au sein d’agents déclaratifs. Ils ne sont pas activés dans Microsoft 365 Copilot. Consultez Ajouter un plug-in pour obtenir un exemple d’ajout d’un plug-in d’API à un agent déclaratif.
Les plug-ins d’API permettent aux Microsoft 365 Copilot d’interagir avec les API REST décrites par une description OpenAPI. La description OpenAPI dans un plug-in d’API décrit les API REST avec lesquelles Copilot peut interagir. En outre, un plug-in d’API inclut un fichier manifeste de plug-in qui fournit des métadonnées sur le plug-in, telles que le nom, la description et la version du plug-in. Le manifeste du plug-in inclut également des informations sur les fonctionnalités du plug-in, telles que les API qu’il prend en charge et les opérations qu’il peut effectuer.
L’article suivant décrit le schéma utilisé par les fichiers manifeste de plug-in d’API. Pour plus d’informations sur les plug-ins d’API, consultez Plug-ins d’API pour Microsoft 365 Copilot.
Schéma JSON
Le schéma décrit dans ce document se trouve au format de schéma JSONici.
Conventions
Références relatives dans les URL
Sauf indication contraire, toutes les propriétés qui sont des URL PEUVENT être des références relatives. Les références relatives dans le document manifeste sont relatives à l’emplacement du document manifeste.
Longueur de chaîne
Sauf indication contraire, toutes les propriétés de chaîne DOIVENT être limitées à 4 000 caractères. Cette longueur de chaîne ne confère aucune taille acceptable pour l’ensemble du document. Les implémentations sont libres d’imposer leurs propres limites pratiques sur la longueur du manifeste.
Propriétés non reconnues
Les objets JSON définis dans ce document prennent uniquement en charge les propriétés décrites. Les propriétés non reconnues dans n’importe quel objet JSON DOIVENT rendre l’intégralité du document non valide.
Localisation de chaîne
Les chaînes localisables peuvent utiliser une clé de localisation au lieu d’une valeur littérale. La syntaxe est [[key_name]]
, où key_name
est le nom de clé dans la localizationKeys
propriété dans vos fichiers de localisation. Pour plus d’informations sur la localisation, consultez Localiser votre agent.
Exemple de chaîne localisée
{
"schema_version": "v2.1",
"name_for_human": "[[plugin_name]]",
"description_for_human": "[[plugin_description]]"
}
Objet manifeste de plug-in
La racine du document manifeste du plug-in est un objet JSON qui contient des propriétés qui décrivent le plug-in.
L’objet manifeste du plug-in contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
schema_version |
String | Obligatoire. Version du schéma. Les versions précédentes sont v1 et v2 . Doit être défini sur v2.1 . |
name_for_human |
String | Obligatoire. Nom court et lisible par l’utilisateur pour le plug-in. Il DOIT contenir au moins un caractère nonwhitespace. Les caractères au-delà de 20 PEUVENT être ignorés. Cette propriété est localisable. |
namespace |
String | Déconseillé. Optional. |
description_for_model |
String | Facultatif. Description du plug-in fourni au modèle. Cette description doit décrire à quoi sert le plug-in et dans quelles circonstances ses fonctions sont pertinentes. Les caractères au-delà de 2048 PEUVENT être ignorés. Cette propriété est localisable. |
description_for_human |
String | Obligatoire. Description lisible du plug-in. Les caractères au-delà de 100 PEUVENT être ignorés. Cette propriété est localisable. |
logo_url |
String | Facultatif. URL utilisée pour récupérer un logo qui PEUT être utilisé par l’orchestrateur. Les implémentations PEUVENT fournir d’autres méthodes pour fournir des logos qui répondent à leurs besoins visuels. Cette propriété est localisable. |
contact_email |
String | Facultatif. Adresse e-mail d’un contact pour la sécurité/modération, le support et la désactivation. |
legal_info_url |
String | Facultatif. URL absolue qui localise un document contenant les conditions d’utilisation du plug-in. Cette propriété est localisable. |
privacy_policy_url |
String | Facultatif. URL absolue qui localise un document contenant la politique de confidentialité du plug-in. Cette propriété est localisable. |
functions |
Tableau de l’objet Function | Optional. Ensemble d’objets de fonction décrivant les fonctions disponibles pour le plug-in. Chaque nom d’objet de fonction DOIT être unique dans le tableau. L’ordre du tableau n’est pas significatif. Si la functions propriété n’est pas présente et qu’il existe un runtime OpenAPI, les fonctions sont déduites à partir des opérations OpenAPI. |
runtimes |
Tableau de l’objet runtime OpenAPI | Optional. Ensemble d’objets runtime décrivant les runtimes utilisés par le plug-in. |
capabilities |
Objet de fonctionnalités de plug-in | Optional. Décrit les fonctionnalités du plug-in. |
Objet Function
Informations relatives à la façon dont le modèle doit interagir avec une fonction.
L’objet de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
id |
String | Facultatif. |
name |
String | Obligatoire. Chaîne qui identifie de façon unique cette fonction. Les objets runtime PEUVENT référencer cet identificateur pour lier le runtime à la fonction . Lorsque la fonction est liée à un runtime OpenAPI, la valeur doit correspondre à une operationId valeur dans la description OpenAPI. La valeur doit correspondre à l’expression ^[A-Za-z0-9_]+$ régulière. |
description |
String | Facultatif. Description mieux adaptée au modèle, comme les considérations relatives à la longueur du contexte de jeton ou l’utilisation mot clé pour une invite de plug-in améliorée. |
parameters |
Objet paramètres de fonction | Optional. Objet qui contient des propriétés qui décrivent les paramètres d’une fonction de manière indépendante du runtime. Il reflète la forme de json-schema , mais ne prend en charge qu’un petit sous-ensemble des fonctionnalités de schéma JSON. Si la parameters propriété n’est pas présente, les fonctions décrites par un objet runtime de type OpenApi utilisent la description OpenAPI pour déterminer les paramètres. Chaque membre de l’objet JSON est un objet de paramètre de fonction qui décrit la sémantique du paramètre. |
returns |
Objet de retour OR Objet de retour enrichi | Optional. Décrit la sémantique de la valeur retournée par la fonction . |
states |
Objet d’états de fonction | Optional. Définit des objets d’état pour les états d’orchestrateur. |
capabilities |
Objet fonctionnalités de fonction | Optional. Contient une collection de données utilisée pour configurer les fonctionnalités facultatives de l’orchestrateur lors de l’appel de la fonction . |
Exemple d’objet Function
{
"functions": [
{
"name": "add_todo",
"description": "Adds a new Todo",
"parameters": {
"type": "object",
"properties": {
"description": {
"type": "string"
}
},
"required": [
"description"
]
},
"returns": {
"type": "string"
}
}
]
}
Objet paramètres de fonction
Objet utilisé pour identifier l’ensemble de paramètres qui peuvent être passés à la fonction. Cet objet est structuré pour miroir la forme d’un objet schéma JSON, mais il prend uniquement en charge un sous-ensemble de mots clés de schéma JSON.
L’objet de paramètres de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Facultatif. Type de schéma JSON. Doit être défini sur object . |
properties |
Objet propriétés des paramètres de fonction | Obligatoire. Objet qui mappe les noms de paramètres à leurs définitions. |
required |
Tableau de chaînes | Facultatif. Noms des propriétés qui sont des paramètres obligatoires. Contrairement au schéma JSON, les valeurs de ce tableau DOIVENT correspondre aux noms répertoriés dans la properties propriété . |
Exemple d’objet paramètres de fonction
{
"type": "object",
"properties": {
"param1": {
"type": "string"
},
"param2": {
"type": "number"
}
},
"required": [
"param1"
]
}
Objet propriétés des paramètres de fonction
Objet qui mappe les noms de paramètres à leurs définitions.
L’objet propriétés des paramètres de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
Correspondance de nom ^[A-Za-z0-9_]+$ |
Objet de paramètre de fonction | Optional. Définition de paramètre qui correspond au paramètre qui correspond au nom de la propriété. |
Objet de paramètre de fonction
Objet qui décrit la sémantique d’un paramètre de fonction.
L’objet de paramètre de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Obligatoire. Spécifie le type du paramètre. Les valeurs possibles sont les suivantes : string , array , boolean , integer , number . |
items |
Objet de paramètre de fonction | Optional. Objet de paramètre de fonction qui décrit un élément unique dans un tableau. DOIT être présent uniquement lorsque type a la valeur array . |
enum |
Tableau de chaînes | Facultatif. Tableau de valeurs valides pour ce paramètre. DOIT être présent uniquement lorsque type a la valeur string . |
description |
String | Facultatif. Description du paramètre. |
default |
Array, Boolean, String, Number, Integer | Optional. Valeur du type spécifié par la type propriété qui indique la valeur utilisée par l’API lorsqu’aucune valeur n’est fournie pour un paramètre facultatif. |
Exemple de paramètre de fonction
{
"type": "string",
"description": "The color of the item",
"enum": [
"green",
"blue",
"orange"
]
}
Objet de retour
Contient la sémantique de la valeur retournée par la fonction .
L’objet de retour contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Obligatoire. Spécifie le type de la valeur retournée par l’API. Les valeurs possibles sont : string . |
description |
String | Facultatif. Description de la valeur retournée par l’API. |
Objet de retour enrichi
Indique que la fonction retourne une réponse compatible avec le protocole Rich Responses.
L’objet de retour enrichi contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
$ref |
String | Obligatoire. Doit être défini sur https://copilot.microsoft.com/schemas/rich-response-v1.0.json . |
Objet d’états de fonction
Définit des objets d’état pour les états d’orchestrateur.
L’objet d’états de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
reasoning |
Objet State | Optional. État dans lequel le modèle peut appeler des fonctions et effectuer des calculs. |
responding |
Objet State | Optional. État dans lequel le modèle peut générer du texte affiché à l’utilisateur. Le modèle ne peut pas appeler des fonctions dans l’état de réponse. |
disengaging |
Objet State | Optional. |
Objet State
Contient des instructions spécifiques quand une fonction est appelée dans un état d’orchestrateur spécifique.
L’objet state contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
description |
String | Facultatif. Décrit l’objectif d’une fonction lorsqu’elle est utilisée dans un état d’orchestrateur spécifique. |
instructions |
Array, String | Optional. Chaîne ou tableau de chaînes utilisées pour fournir des instructions à l’orchestrateur sur la façon d’utiliser cette fonction dans un état d’orchestrateur spécifique. La fourniture d’une chaîne unique indique l’intention de fournir un ensemble complet d’instructions qui remplaceraient toutes les invites de fonction intégrées. La fourniture d’un tableau de chaînes indique l’intention d’augmenter le mécanisme d’invite de fonction intégré. |
examples |
Array, String | Optional. Chaîne ou tableau de chaînes utilisées pour fournir des exemples à l’orchestrateur sur la façon dont cette fonction peut être appelée. |
Exemple d’objet State
{
"functions": [
{
"name": "searchEmails",
"description": "search for Emails from using 3S search Service",
"states": {
"reasoning": {
"description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
"instructions": [
"Examine the output of `searchEmails(**params) -> str`.",
"Do not include any information that is not present in the JSON results.",
"Exclude any irrelevant data from the JSON results",
"Determine if the response contains an error field.",
"If an error is present, provide the error code and error message extracted from the response JSON.",
"If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
],
"examples": []
}
}
}
]
}
Objet fonctionnalités de fonction
Contient une collection de données utilisée pour configurer les fonctionnalités facultatives de l’orchestrateur lors de l’appel de la fonction .
L’objet de fonctionnalités de fonction contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
confirmation |
Objet Confirmation | Optional. Décrit une boîte de dialogue de confirmation qui DOIT être présentée à l’utilisateur avant d’appeler la fonction. |
response_semantics |
Objet sémantique de réponse | Optional. Décrit comment l’orchestrateur peut interpréter la charge utile de réponse et fournir un rendu visuel. |
Objet Confirmation
Décrit comment l’orchestrateur demande à l’utilisateur de confirmer avant d’appeler une fonction.
L’objet de confirmation contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Facultatif. Spécifie le type de confirmation. Les valeurs possibles sont les suivantes : None , AdaptiveCard . |
title |
String | Facultatif. Titre de la boîte de dialogue de confirmation. Cette propriété est localisable. |
body |
String | Facultatif. Texte de la boîte de dialogue de confirmation. Cette propriété est localisable. |
Objet sémantique de réponse
Contient des informations pour identifier la sémantique de la charge utile de réponse et permettre le rendu de ces informations dans une expérience visuelle enrichie à l’aide de cartes adaptatives.
L’objet sémantique de réponse contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
data_path |
String | Obligatoire. Une requête JSONPath RFC9535 qui identifie un ensemble d’éléments de la réponse de fonction à afficher à l’aide du modèle spécifié dans chaque élément. |
properties |
Objet de propriétés de sémantique de réponse | Optional. Autorise le mappage des requêtes JSONPath à des éléments de données connus. Chaque requête JSONPath est relative à une valeur de résultat. |
static_template |
Objet | Facultatif. Objet JSON conforme au schéma de carte adaptative et au langage de création de modèles. Cette instance de carte adaptative est utilisée pour afficher un résultat à partir de la réponse du plug-in. Cette valeur est utilisée si le template_selector n’est pas présent ou ne parvient pas à se résoudre en un carte adaptatif. |
oauth_card_path |
String | Facultatif. |
Exemple de modèle statique
{
"functions": {
"capabilities": {
"response_semantics": {
"data_path": "$.resources",
"properties": {
"title": "$.name",
"subtitle": "$.location",
"url": "$.href",
"information_protection_label": "$.ipLabel"
},
"static_template": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"text": "${name}",
"weight": "Bolder"
},
{
"type": "TextBlock",
"text": "${description}"
}
],
"action": [
{
"type": "Action.OpenUrl",
"title": "View",
"text": "${href}"
}
]
}
}
}
}
}
Exemple de modèle dynamique
{
"functions": {
"capabilities": {
"response_semantics": {
"data_path": "$.attachments",
"properties": {
"title": "$.title",
"subtitle": "$.subtitle",
"url": "$.url",
"thumbnail_url": "$.thumbnailUrl",
"template_selector": "$.template"
}
}
}
}
}
Objet de propriétés de sémantique de réponse
Autorise le mappage des requêtes JSONPath à des éléments de données connus. Chaque requête JSONPath est relative à une valeur de résultat.
L’objet de propriétés de sémantique de réponse contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
title |
String | Facultatif. Titre d’une citation pour le résultat. |
subtitle |
String | Facultatif. Sous-titre d’une citation pour le résultat. |
url |
String | Facultatif. URL d’une citation pour le résultat. |
thumbnail_url |
String | Facultatif. URL d’une image miniature pour le résultat. |
information_protection_label |
String | Facultatif. Indicateur de sensibilité des données du contenu du résultat. |
template_selector |
String | Facultatif. Une expression JSONPath vers une carte adaptative instance à utiliser pour le rendu du résultat. |
Objet runtime OpenAPI
Décrit comment le plug-in appelle les fonctions OpenAPI.
L’objet runtime OpenAPI contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Obligatoire. Identifie ce runtime en tant que runtime OpenAPI. Doit être défini sur OpenApi . |
auth |
Objet d’authentification runtime | Obligatoire. Informations d’authentification requises pour appeler le runtime. |
run_for_functions |
Tableau de chaînes | Facultatif. Noms des fonctions disponibles dans ce runtime. Si cette propriété est omise, toutes les fonctions décrites par le runtime sont disponibles. Les valeurs de chaîne fournies peuvent contenir des caractères génériques. Plusieurs runtimes NE DOIVENT PAS déclarer la prise en charge de la même fonction implicitement ou explicitement. |
spec |
Objet de spécification OpenAPI | Obligatoire. Contient les informations OpenAPI requises pour appeler le runtime. |
Objet de spécification OpenAPI
Contient les informations OpenAPI requises pour appeler le runtime.
L’objet de spécification OpenAPI contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
url |
String | Facultatif. URL permettant d’extraire la spécification OpenAPI, appelée avec une requête GET. Ce membre est obligatoire, sauf s’il api_description est présent. |
api_description |
String | Facultatif. Chaîne qui contient une description OpenAPI. Si ce membre est présent, url n’est pas obligatoire et est ignoré s’il est présent. |
progress_style |
String | Facultatif. Style de progression utilisé pour afficher la progression de la fonction. Les valeurs possibles sont les suivantes : None , ShowUsage , ShowUsageWithInput , ShowUsageWithInputAndOutput . |
Exemple d’objet de spécification OpenAPI
{
"runtimes":
[
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "https://example.org/api/openapi.yaml",
}
}
]
}
Objet d’authentification runtime
Contient des informations utilisées par le plug-in pour s’authentifier auprès du runtime.
L’objet d’authentification du runtime contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
type |
String | Facultatif. Spécifie le type d’authentification requis pour appeler une fonction. Les valeurs possibles sont None , OAuthPluginVault et ApiKeyPluginVault . |
reference_id |
String | Facultatif. Valeur utilisée quand type est OAuthPluginVault ou ApiKeyPluginVault . La reference_id valeur est acquise indépendamment lors de la fourniture des valeurs de configuration d’authentification nécessaires. Ce mécanisme existe pour éviter la nécessité de stocker des valeurs secrètes dans le manifeste du plug-in. |
Exemple d’objet d’authentification du runtime
{
"type": "OAuthPluginVault",
"reference_id": "0123456-abcdef"
}
Objet de fonctionnalités de plug-in
Décrit les fonctionnalités du plug-in.
L’objet de fonctionnalités du plug-in contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
conversation_starters |
Tableau de l’objet de démarrage de conversation | Optional. Démarrages de conversation qui peuvent être affichés à l’utilisateur pour obtenir des suggestions sur la façon d’appeler le plug-in. |
Objet de démarrage de conversation
Exemple de question à laquelle le plug-in peut répondre.
L’objet de démarrage de conversation contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
text |
String | Obligatoire. Texte du démarrage de la conversation. Cette propriété est localisable. |
title |
String | Facultatif. Titre du starter de conversation. Cette propriété est localisable. |
Exemple d’objet de démarrage de conversation
{
"conversation_starters": [
{
"title": "Developer tasks",
"text": "What issues are assigned to me?"
}
]
}
Exemple de manifeste
Voici un exemple de fichier manifeste de plug-in qui utilise la plupart des propriétés de manifeste et des propriétés d’objet décrites dans l’article :
{
"schema_version": "v2",
"name_for_human": "{{ 'nameForHuman' | localize: 'en-us' }}",
"description_for_human": "{{ 'descriptionForHuman' | localize: 'en-us' }}",
"description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
"capabilities": {
"localization": {
"en-us": {
"nameForHuman": {
"message": "Contoso Real Estate",
"description": "Name for human, in English"
},
"descriptionForHuman": {
"message": "Find up-to-date, detailed real estate properties for sale on the market",
"description": "Description for human, in English"
}
},
"fr-fr": {
"nameForHuman": {
"message": "Contoso Immobilier",
"description": "Name for human, in French"
},
"descriptionForHuman": {
"message": "Trouvez des propriétés immobilières à vendre sur le marché",
"description": "Description for human, in French"
}
}
}
},
"functions": [
{
"name": "getListings",
"description": "Get a list of properties matching the specified criteria",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city to search properties in"
},
"bedrooms": {
"type": "number",
"description": "The number of bedrooms the property should have"
},
"bathrooms": {
"type": "number",
"description": "The number of bathrooms the property should have"
},
"amenities": {
"type": "array",
"description": "The list of amenities the property should have",
"items": {
"type": "string",
"description": "One amenity the property should have",
"enum": [
"air conditioning",
"balcony",
"dishwasher",
"elevator",
"fireplace",
"furniture",
"garden",
"gym",
"heating",
"jacuzzi",
"laundry room",
"microwave",
"no furniture",
"parking",
"patio",
"sauna",
"swimming pool",
"terrace",
"wi-fi"
]
}
}
}
},
"returns": {
"type": "string",
"description": "A list of properties"
},
"states": {
"reasoning": {
"description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
"instructions": [
"If the user mentions a city in their question, only search in that city by using the city parameter.",
"If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
"Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
"Determine if the response contains an error field.",
"If an error is present, provide the error code and error message from the JSON response to the user.",
"If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
]
}
}
},
{
"name": "saveSearch",
"description": "Save a search for properties for sale",
"parameters": {
"type" : "object",
"properties": {
"city": {
"type": "string",
"description": "The city to search in"
},
"bedrooms": {
"type": "number",
"description": "The number of bedrooms"
}
},
"required": [ "city" ]
},
"returns": {
"type": "string",
"description": "The unique ID for the saved search"
},
"states": {
"responding": {
"description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
"instructions": [
"Examine the output of the `saveSearch` function.",
"Extract the unique ID integer from the output and include it in your response to the user."
]
}
}
},
{
"name": "deleteSavedSearch",
"description": "Delete a previously saved search",
"parameters": {
"type" : "object",
"properties": {
"id": {
"type": "integer",
"description": "The unique ID of the saved search"
}
},
"required": [ "id" ]
},
"returns": {
"type": "string",
"description": "True if the saved search was deleted, false otherwise"
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": { "type": "none" },
"run_for_functions": [ "getListings", "saveSearch", "deleteSavedSearch" ],
"spec": { "url": "http://contoso.com/openapi.yaml" }
}
],
"logo_url": "http://contoso.com/logo.png",
"contact_email": "contact@contoso.com",
"legal_info_url": "https://contoso.com/legal/",
}