Copyright 2023 Microsoft
This specification defines a machine readable document that provides instructions to an AI orchestrator and host that enable a skill to better meet the needs of the end user. The document instance is referred to as a plugin manifest and it describes a set of functions, along with the why, when and how to call those functions.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The plugin manifest described in this document is intended to meet the requirements for all Microsoft Copilots. It is expected that all Microsoft Copilots will provide support for plugins described by this manifest.
Unless specified otherwise, all members that are URLs MAY be relative references. Relative references in the manifest document are relative the location of the manifest document.
Unless specified otherwise, all string members SHOULD be limited to 4K characters. This string length does not confer any acceptable size for the entire document. Implementations a free to impose their own practical limits on manifest length.
JSON objects defined in this document support only the described members. Unrecognized members in any JSON object SHOULD make the entire document invalid.
To enable tooling to localize JSON strings, the character sequence [[<localization-key>]] is reserved to identify strings that SHOULD be localized. The <localization-key> is an identifier used to locate the desired localized string and MUST match the regex ^[a-zA-Z_][a-zA-Z0-9_]*. This sequence of characters SHOULD only be used in members that are noted as localizable. The mechanism used to replace these sequences with localized strings is implementation specific.
JSON objects defined in this document support the use of properties that start with the characters x- as an extensibility mechanism. Implementations SHOULD ignore extension members they do not recognize. Extension member values can be any valid JSON type.
JSON strings that are defined in this document as a known set of values MAY have the supported values extended by using a value that starts with the characters x-. Implementations SHOULD ignore extension values they do not recognize.
The root of the Plugin manifest document is a JSON object that contains members that describe the plugin.
The following example is a minimal plugin manifest that uses an [OpenAPI] description to identify the functions.
{
"schema_version": "v2",
"name_for_human": "GitHub Issues Plugin",
"description_for_model": "Search for GitHub issues by author, keyword or state",
"runtimes":
[
{
"type": "OpenApi",
"auth": { "type": "None" },
"spec": { "url": "https://github.com/ai/plugins/issues/openapi.yaml" }
}
]
}
A JSON string value that MUST be "v2.2".
It is important to note that v1 does not indicate an OpenAI manifest. To distinguish an OpenAI manifest from a "v1" document, the reader may use the presence of the "api" property at the root to signal an OpenAI manifest as it is a required property and is not allowed in a Plugin manifest.
A JSON string containing a short, human-readable name for the plugin. It MUST contain at least 1 non-whitespace character. Characters beyond 20 MAY be ignored. This is a required member. This member value is localizable. See 3.4 String Localization.
A JSON string containing the description for the plugin that will be provided to the model. This description should describe what the plugin is for, and in what circumstances its functions are relevant. Characters beyond 2048 MAY be ignored. This member value is localizable. See 3.4 String Localization.
A JSON string containing a human-readable description of the plugin. Characters beyond 100 MAY be ignored. This is a required member.
A JSON string containing a URL used to fetch a logo that MAY be used by the orchestrator. Implementations MAY provide alternative methods to provide logos that meet their visual requirements. This member value is localizable. See 3.4 String Localization.
A JSON string containing an email address of a contact for safety/moderation, support, and deactivation.
A JSON string containing an absolute URL that locates a document containing the terms of service for the plugin. This member value is localizable. See 3.4 String Localization.
A JSON string containing an absolute URL that locates a document containing the privacy policy for the plugin. This member value is localizable. See 3.4 String Localization.
A JSON string that contains an identifier used to prevent name conflicts between function names from different plugins that are used within the same execution context. The value MUST match the regex ^[A-Za-z0-9_]+ as defined by [RFC9485]. This is a required member.
A JSON array that contains an set of function objects. See 5. Function object. Each function object name MUST be unique within the array. The order of the array is not significant. If the functions member is not present and there exists an OpenAPI runtime, the functions will be inferred from the OpenAPI operations.
A JSON array that contain a set of runtime objects. See 11. Runtime object.
This member is a 12. Plugin Capabilities Object that provides the ability to describe capabilities that are supported by the plugin.
A JSON object that contains members with information related to how the model should interact with the function.
{
"functions":
[
{
"name": "add_todo",
"description": "Adds a new Todo",
"parameters": {
"type" : "object",
"properties": {
"description": {
"type": "string"
}
},
"required" : ["description"]
},
"returns": {
"type": "string"
}
}
]
}
A JSON string that uniquely identifies this function. The string identifier must match the regex ^[A-Za-z0-9_]+ as defined by [RFC9485]. Runtime objects MAY reference this identifier to bind the runtime to the function. When the function is bound to an OpenAPI runtime, the value must match an operationId` value in the OpenAPI description.
A JSON string containing a description better tailored to the model, such as token context length considerations or keyword usage for improved plugin prompting.
A JSON object that contains members that describe the parameters of a function in a runtime agnostic way. It mirrors the shape of [json-schema] to leverage the knowledge of the LLM but only supports a small subset of the JSON schema capabilities.
If the parameters property is not present, functions described by a 11. Runtime object of type openApi will use the OpenAPI description to determine the parameters.
Each member in the JSON object has a value of type 7. Function Parameter Object that describes the semantics of the parameter.
A JSON object 8. Return Object that describes the semantics of the value returned from the function.
A JSON object where each member name corresponds to an orchestrator state and the value is a state object 10. State object. Supported member names include: reasoning and responding.
A JSON object that contains a collection of data used to configure optional capabilities of the orchestrator while invoking the function.
A JSON object that is used to identify the set of parameters that can be passed to the function. This object is structured to mirror the shape of a JSON Schema object but it only supports a subset of JSON Schema keywords.
{
"type": "object",
"properties": {
"param1": {
"type": "string"
},
"param2": {
"type": "number"
}
},
"required": ["param1"]
}
A JSON string with the literal value of object. This member is optional.
A JSON object that contains the a map of the function parameter names and the definition of those function parameters using a 7. Function Parameter Object.
A JSON array that lists the names of properties that are required parameters. Unlike in JSON Schema, the values in this array MUST match the names listed in the 6. Function Parameters Object map.
A JSON object with members that describe the semantics of a parameter passed to the function.
{
"type": "string",
"description": "The color of the item",
"enum": ["green","blue","orange"]
}
A JSON string that MUST be one of the following: string, array, boolean, integer, number.
A JSON string that describes the information that can be passed as a parameter to the function.
A 7. Function Parameter Object that describes a single element in an array to be used as a parameter. Items MUST only be present when type is array.
A JSON array of strings that represent valid values for this parameter. This property can only be present when type is string.
A JSON value that has the same type as the type property used to indicate what value the API will use when a parameter value for an optional parameter is not provided.
A JSON object with members that describe the semantics of the value returned from the function.
{
"type": "string",
"description": "The value of your portfolio"
}
For plugin functions that return a response that is compatible with the Rich Responses protocol, the following return value can be specified.
"returns": {
"$ref": "https://copilot.microsoft.com/schemas/rich-responses-v1.0.json"
}
A JSON string that MUST be one of the following: string.
A JSON string that describes the information returned from the function.
{
"functions":
[
{
"name": "someFunction",
"capabilities":
{
"confirmation" : { ... },
"security_info": { ... }
}
}
]
}
A JSON object with members that describe a confirmation prompt that SHOULD be presented to the user before invoking the function. See 9.3 Confirmation object.
A JSON object that describes how the orchestrator can interpret the response payload and provide a visual rendering. The object is a 9.4 Response Semantics object
A JSON object that contains attestations about the behavior of the plugin in order to assess the risks of calling the function. This object is a 9.5 Security Info object.
{
"functions":
[
{
"capabilities":
{
"confirmation": {
"type": "adaptiveCard",
"title": "Windows Desktop Background",
"body": "Do you wish to change the desktop background?"
}
}
}
]
}
A JSON string that contains a title to be displayed on the confirmation dialog. This member value is localizable.
A JSON string that contains text to ask the user if they want the plugin can be called. This member value is localizable.
A JSON object that contains information to identify semantics of response payload and enable rendering that information in a rich visual experience using adaptive cards.
{
"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.4",
"body": [
{
"type": "TextBlock",
"text": "${name}",
"weight": "Bolder"
},
{
"type": "TextBlock",
"text": "${description}"
}
],
"action": [
{
"type": "Action.OpenUrl",
"title": "View",
"text": "${href}"
}
]
}
}
}
}
}
Example of dynamic card templates:
{
"functions": {
"capabilities": {
"response_semantics": {
"data_path": "$.attachments",
"properties": {
"title": "$.title",
"subtitle": "$.subtitle",
"url": "$.url",
"thumbnail_url": "$.thumbnailUrl",
"template_selector": "$.template"
}
}
}
}
}
A JSON string that contains a JSON Path [RFC9535] query that identifies a set of elements from the function response to be rendered using the template specified in each item.
A JSON object that contains a set of members whose value is a JSON string representing a JSONPath [RFC9535] query. Each JSONPath query is relative to a result value and locates a well-known data element within a result. The following well-known values are supported:
| Member name | Description |
|---|---|
| title | Title of a citation for the result |
| subtitle | Subtitle of a citation for the result |
| url | URL of citation for the result |
| thumbnail_url | URL of a thumbnail image for the result. |
| information_protection_label | Data sensitivity indicator of the result contents |
| template_selector | A JSONPath expression to an Adaptive Card instance to be used for rendering the result |
A JSON object that conforms with the Adaptive Card Schema and templating language. This Adaptive Card instance is used to render a result from the plugin response. This value is used if the template_selector is not present or fails to resolve to an adaptive card.
A JSON object that contains information to be used to aid in determining the relative risk of invoking the function.
{
"functions":
[
{
"name": "someFunction",
"capabilities":
{
"security_info":
{
"data_handling": ["GetPublicData", "GetPrivateData"]
}
}
}
]
}
A JSON array of strings that describe the data handling behavior of the plugin. The values in the array MUST be one of the following values: GetPublicData, GetPrivateData, DataTransform, ResourceStateUpdate.
A JSON object used to provide specific instructions for when the function is invoked in a specific orchestrator 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": []
}
}
}
]
}
A JSON string that describes the purpose of the function when used in a specific orchestrator state.
A JSON string or a JSON array of strings that are used to provide instructions to the orchestrator on how to use this function while in a specific orchestrator state. Providing a JSON string indicates the intent to provide a complete set of instructions that would override any built-in function prompts. A JSON array indicates the intent to augment the built in function prompting mechanism.
A JSON string or a JSON array of strings that are used to provide examples to the orchestrator on this function can be invoked.
A JSON object that describes the mechanics of how a function will be invoked. More than one runtime MUST NOT declare support for the same function either implicitly or explicitly using 11.1.3 run_for_functions.
A JSON string that identifies the type of runtime. The value MUST be one of the following values: OpenApi, LocalPlugin.
This member is required.
A JSON object that contains the authentication information required to invoke the runtime. See 11.2 Runtime authentication object. This member is required.
A JSON array that contains the names of the functions that will be invoked by this runtime. If this property is omitted then all functions described by the runtime are available. Provided string values can contain wildcards.
A JSON object that contains the runtime specific information required to invoke the runtime. See the following sections for the types of objects supported:
This member is required.
A JSON string that contains a [Liquid] template used to transform the plugin response payload prior to further processing. The Liquid template is provided with a context object that contains an object model that represents the plugin manifest.
{
"runtimes":
[
{
"auth": { "type": "None" }
},
{
"auth": {
"type": "OAuthPluginVault",
"reference_id": "0123456-abcdef"
}
}
]
}
A JSON string that represents the type of authorization required to invoke a function. Supported values are:
| Value | |
|---|---|
None |
Anonymous access to API |
OAuthPluginVault |
Access API with a token acquired through an OAuth flow (Requires reference_id value) |
ApiKeyPluginVault |
Access API with an API Key (Requires reference_id value) |
EntraOnBehalfOf |
Access API using an access token acquired by performing an OAuth token exchange [RFC8693] with the signed in user's access token as the assertion. |
A JSON string value used when type is OAuthPluginVault or ApiKeyPluginVault. The reference_id value is acquired independently when providing the necessary authentication configuration values. This mechanism exists to prevent the need for storing secret values in the plugin manifest.
A JSON array of strings that represent the scopes required to invoke the functions supported by this runtime. This member is only available when type is EntraOnBehalf.
The OpenApi execution spec object identifies a set of API Operations that map to functions available in this plugin. If an OperationId is present in the OpenAPI description it correlates to a function object with the same name.
{
"runtimes":
[
{
"type": "OpenApi",
"auth": { "type": "None" },
"spec":
{
"url": "https://example.org/api/openapi.yaml",
}
}
]
}
A JSON string that contains the URL to fetch the openAPI specification, called with a GET request. This member is required unless api_description is present.
A JSON string that contains an OpenAPI description. If this member is present then url is not required and will be ignored if present.
A JSON string that contains the progress style that will be used to display the progress of the function. The value MUST be one of the following values: None, ShowUsage, ShowUsageWithInput, ShowUsageWithInputAndOutput.
{
"runtimes":
[
{
"type": "LocalPlugin",
"spec": {
"local_endpoint": "...",
},
"runs_for_functions": [ "add_todo" ]
}
]
}
A JSON string that represents a local runtime identifier that links to a specific function to invoke locally (e.g. in the case of Windows it will link to a particular app).
A JSON object with members that describe capabilities that are applicable to the entire plugin.
A JSON array of objects that contain conversation starters that can be displayed to the user for suggestions on how to invoke the plugin. See 12.2 Conversation Starter Object.
A JSON object that contains an example of a question that can be answered by the plugin.
{
"conversation_starters": [
{
"title": "Developer tasks",
"text": "What issues are assigned to me?"
}
]
}
A JSON string that contains the title of the conversation starter. This member value is localizable. See 3.4 String Localization.
A JSON string that contains the text of the conversation starter. This a required property of a conversation starter object. This member value is localizable. See 3.4 String Localization.
This example demonstrates the use of instructions with an OpenAPI description.
{
"schema_version": "v1",
"name_for_human": "Suno",
"description_for_human": "<description for="" human="">",
"logo_url": "https://th.bing.com/th?id=OSK.935650835684F7E18AC3F31034DE6DF3",
"contact_email": "ionutro@microsoft.com",
"namespace": "suno",
"functions": [
{
"name": "createSong",
"description": "Create a song given the user preferences",
"parameters": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "The requested song description, eg. `a country song about Thanksgiving`"
}
}
},
"states": {
"reasoning": {
"description": "\n- `createSong(**params) -> str` creates a song about a given topic. This tool is only invoked if the request parameter is a safe and innocuous topic.",
"instructions": [
"Is the user requesting to create a song which would warrant the \"Parental Advisory Explicit Content\" label (e.g. topics about sex, politics, violence, self-harm, hate speech, coercion, etc.)? If so, I **must** invoke `withdraw()` and end the conversation.",
"Is the user requesting to create a haiku, poem, lyric, tune, melody, jingle, verse, sonnet or something other than a song?, If so, I **must not** invoke `createSong(**params)`.",
"Is the user requesting to create a song on a safe and innocuous topic? If so, invoke `createSong(**params)`.",
"If `createSong(**params)` is invoked already in this turn, I **will** not invoke the same tool again",
"Here are the parameters: ",
" * `topic(string, required)`: The requested song description, eg. `a country song about Thanksgiving`, in the user's language"
]
},
"responding": {
"description": "\n- `createSong(**params) -> str` creates a song about a given topic. This tool is only invoked if the request parameter is a safe and innocuous topic.",
"instructions": [
"The response to the user is generated asynchronously therefore I **SHOULD NOT** generate my own song or provide links or lyrics based on this tool's output. I can just let the user know their song will be available shortly and **stop responding** for that turn.",
"I **should not** respond with either sample or full form of lyrics to the song because the song created by `createSong(**params)` is shown to the user directly along with the lyrics.",
"If `createSong(**params)` was not invoked because the service was overloaded or the user reached their invocation limit, I **must** tell the user they can visit the `https://app.suno.ai` website to create more songs and display the link using Markdown syntax.",
"I **shall** tell the user they can visit the `https://app.suno.ai` website to create more songs and display the link using Markdown syntax."
]
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "https://turingbotdev.blob.core.windows.net/chatgpt-plugins/suno/api_bing.json"
},
"run_for_functions": [ "createSong" ]
}
]
}
This example demonstrates the use of a local endpoint.
{
"schema_version": "v2",
"name_for_human": "Windows Settings",
"description_for_human": "<description for="" human="">",
"contact_email": "ashleythomas@microsoft.com",
"namespace": "WindowsSkill",
"functions": [
{
"name": "set_windows_theme",
"description": "Change theme in Windows",
"parameters": {
"type": "object",
"properties": {
"themeName": {
"type": "string",
"enum": [ "dark", "light" ],
"description": "Windows theme that users want to set. Allowed themeName values: \"dark\", \"light\""
}
}
},
"states": {
"reasoning": {
"description": "\n# `set_windows_theme(**params) -> str`: This tool is used to change theme in windows. `params` is the themeName that the user wants to set.",
"instructions": "\n- Decide whether to invoke `set_windows_theme(**params)`:\n * Is the user directly requesting me to change the theme in the user's Windows operating system to either dark or light mode? If so, invoke `set_windows_theme(**params)`. Otherwise, I **must not** invoke `set_windows_theme(**params)`."
}
},
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Change theme",
"body": "{{ ''|model_generated }}"
}
}
},
{
"name": "change_bluetooth",
"description": "Turn Bluetooth on or off on user's device.",
"parameters": {
"type": "object",
"properties": {
"requestedState": {
"type": "string",
"enum": [ "on", "off" ],
"description": "The state to change Bluetooth to (on or off)."
}
},
"required": [ "requestedState" ]
},
"states": {
"reasoning": {
"description": "\n# `change_bluetooth(requestedState: str) -> str` Enables or disables Bluetooth on the user's device.",
"instructions": "\n- Decide whether to invoke `change_bluetooth(requestedState: str)`\n * Check the last user message in the 'conversation_memory'.\n * Does the user want to change the state of Bluetooth? If so, invoke `change_bluetooth(requestedState: str)`, such as `change_bluetooth({\"requestedState\":\"off\"})` if the user wants to turn Bluetooth off."
},
"responding": {
"description": "\n# `change_bluetooth(requestedState: str) -> str` Enables or disables Bluetooth on the user's device.",
"instructions": "\n * Check if `change_bluetooth(requestedState: str) -> str` was invoked. If so, respond concisely with the tool result for the user in 1-2 sentences. Do not include additional information or alternative ways of performing the same action. The response should be in the first person. Allowed Bluetooth states: 'on', 'off'."
}
},
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Bluetooth update",
"body": "{{ ''|model_generated }}"
}
},
"returns": {
"type": "string",
"description": "The response from the plugin"
}
},
{
"name": "toggle_do_not_disturb",
"description": "Help users update Do Not Disturb setting state to either on or off. In the on state, the users stop getting notifications from Windows. In the off state, the notifications are resumed.",
"parameters": {
"type": "object",
"properties": {
"requestedState": {
"type": "string",
"enum": [
"off",
"on"
],
"description": "The state to change the Do Not Disturb setting to \"on\" or \"off\"."
}
},
"required": [
"requestedState"
]
},
"states": {
"reasoning": {
"description": "\n# `toggle_do_not_disturb(requestedState: str) -> str`. Updates `Do Not Disturb` setting state to either on or off.",
"instructions": "\n- Decide whether to invoke `toggle_do_not_disturb(requestedState: str)`:\n * Check the last user message in the `conversation_memory`.\n * Does the user want to turn notifications on or off? If so, invoke `toggle_do_not_disturb(requestedState: str)`. Otherwise, I **must not** invoke `toggle_do_not_disturb(requestedState: str)`.",
"examples": []
}
},
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Update Do not disturb settings",
"body": "{{ ''|model_generated }}"
}
},
"returns": {
"type": "string",
"description": "Indicates whether the operation to turn Do Not Disturb on/off was successful. If not, contains details about the failure."
}
}
],
"runtimes": [
{
"type": "LocalPlugin",
"spec": {
"local_endpoint": "MicrosoftWindows.Client.CoPilotCanary_cw5n1h2txyewy/723.28600.70.6/WindowsSettingsPlugin"
},
"run_for_functions": [ "set_windows_theme", "change_bluetooth", "toggle_do_not_disturb" ]
}
]
}
This example demonstrates the use of a confirmation dialog.
{
"schema_version": "v2",
"name_for_human": "Donation",
"description_for_human": "Learn about NPO, get user info, donate via our website link or directly in chat with existing payment.",
"logo_url": "https://donationplugin2.azurewebsites.net/logo.png",
"contact_email": "xpaymktp@microsoft.com",
"legal_info_url": "https://donationplugin2.azurewebsites.net/legal.txt",
"namespace": "Donation",
"functions": [
{
"name": "SearchNposByName",
"description": "Search NPO (Non-Profit Organization) information with a given NPO name query",
"parameters": {
"type": "object",
"properties": {
"npo_name_query": {
"type": "string",
"description": "npo name query"
}
},
"required": [
"npo_name_query"
]
},
"states": {
"reasoning": {
"description": "\n# `SearchNposByName(**params) -> dict`: Search NPO (Non-Profit Organization) information with a given NPO name query.",
"instructions": [
"Do I need to retrieve NPO information using the given NPO name query to respond to the user message accurately? If so, invoke `SearchNposByNames(**params)`.",
"Here are the parameters:",
" npo_name_query(string): NPO name or NPO name keyword"
]
},
"responding": {
"description": "\n- `SearchNposByName(**params) -> dict`: Returns a list of NPOs",
"instructions": [
"I **must** ask how much the user wants to donate, only amount in USD is supported."
]
}
}
},
{
"name": "CollectUserInput",
"description": "Collect user input for donation",
"parameters": {
"type": "object",
"properties": {
"payment_card_hint": {
"type": "string",
"description": "Payment card hint to select the correct card for donation"
},
"npo_name": {
"type": "string",
"description": "Name of Npo that receiving the donation"
},
"amount": {
"type": "string",
"description": "Donation amount"
}
},
"required": [
"npo_name",
"amount"
]
},
"states": {
"reasoning": {
"description": "\n# `CollectUserInput(**params) -> dict`: Collect user input for donation",
"instructions": [
"I invoke `CollectUserInput(**params)` when the user has given how much to donate in `last_user_message`",
"I invoke `CollectUserInput(**params)` when the user has selected the payment card in `last_user_message`",
"Here are the parameters:",
" payment_card_hint(string): Payment card hint to select the correct card for donation.",
" npo_name(string): Name of NPO that receives the donation",
" amount(number): Donation amount, it **must** come from the user message"
]
},
"responding": {
"description": "\n- `CollectUserInput(**params) -> dict`: Returns the donation transaction for user to confirm",
"instructions": [
"If the donation status is NeedDonationAmount, I **must** ask user to how much the user wants to donate, only amount in USD is supported.",
"If the donation status is NeedPaymentCard, I **must** ask user to select a card from `saved_cards` and call `CollectUserInput(**params)` with the selected card",
"If the user wants to use another card or add new card, I will ask user to use the `donation_with_new_card_url` and I **must not** ask user to input card information in chat",
"The id of `saved_cards` is only used for requests to the donation API, and I **must not** expose it to the user",
"If the donation status is PendingConfirmation, I **must** show the `disclaimer` in my response"
]
}
}
},
{
"name": "ConfirmDonation",
"description": "Confirm a donation transaction from the user to the Npo",
"states": {
"reasoning": {
"description": "\n# `ConfirmDonation() -> dict`: Confirm donation transaction",
"instructions": [
"I invoke `ConfirmDonation()` when the donation status is `PendingConfirmation` in `turn_memory`",
"I must not invoke `ConfirmDonation()` when the donation status is not `PendingConfirmation` in `turn_memory`"
]
},
"responding": {
"description": "\n- `ConfirmDonation() -> dict`: Returns the donation result",
"instructions": [
"- I **must** tell the user donation result"
]
}
},
"capabilities": {
"confirmation": {
"type": "AdaptiveCard",
"title": "Confirm your donation",
"body": "Do you want to capture the donation transaction?"
}
}
},
{
"name": "ListDonations",
"description": "List donation histories for user",
"states": {
"reasoning": {
"description": "\n# `ListDonations() -> dict`: List donation histories for user",
"instructions": [
"Do I need to list the user's donation history in order to respond to the user's message accurately? If so, invoke `ListDonations()`."
]
},
"responding": {
"description": "\n- `ListDonations() -> dict`: Returns a list the donation histories",
"instructions": [
"I should list the donation histories in a table and show to the user",
"I should exclude the Expired or Pending donation result"
]
}
}
}
],
"runtimes": [
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "https://api.webxtsvc-ppe.microsoft.com/aiplugin/openapi-for-sydney-ppe.yaml"
},
"run_for_functions": [
"SearchNposByName",
"CollectUserInput",
"ConfirmDonation",
"ListDonations"
]
}
]
}
Plugins that use Local Endpoint Runtimes (11.4 Local Endpoint Execution Spec Object) are able to return specially formatted responses to produce rich visual responses. Local Endpoint runtimes use [JSON-RPC] to communicate with the plugin. The [JSON-RPC] result member MUST contain an array of 13.2.1 Local Plugin Result Object.
This JSON object contains members that contain information about the visual response.
{
"type": "text/adaptivecard",
"description_for_model": "",
"data": { /* string encoded Visual Card Data object */ }
}
It would be preferrable if the data element could be serialized as normal JSON rather than encoded JSON. This would align with how cardContent is currently serialized. Native JSON can be more easily validated, is easier to debug, less prone to errors and has better performance characteristics.
A JSON string that uniquely identifies this result.
A Media Type that communicates how to interpret the value of the data member. The value of the data is not required to match the syntax and semantics identified by the media type.
The syntax of this value is a subset of [RFC2045] section 5.1. The type value MUST start with "text/".
Currently supported type values are: text/adaptivecard, text/plain
The string text/adaptivecard is not the media type currently used for Adaptive Cards and would not be a value that could be registered officially with IANA Media Types if desired at some later point.
A JSON string containing a description for the model about what is being returned.
A JSON string that contains either plain text in the case that type equals text/plain or an escaped JSON serialization of 13.2.2 Visual Card Data Object in the case where type equals text/adaptivecard.
A JSON object that returned when 13.2.1 Local Plugin Result Object has the type text/adaptivecard.
The members of this object provide all the necessary information to render an adaptive card with data and handle an action invoked by the user via the adaptive card.
{
"template": "https://copilot.microsoft.com/schemas/visual-templates/flight_status_v1.0.json",
"data": {
"cardContent": {
"flightId": "LH490",
"departureDate": "1/1/24"
}
}
}
The cardContent property is an additional layer of nesting over and above what is shown in the examples included in [VisualPlugins]. It is possible that the additional layer of nesting was added to provide a safe location to include the callbackMessage property that is shared between orchestrator and client.
A JSON string that contains URL that starts with https://copilot.microsoft.com/schemas/visual-templates/. The remaining portion of the URL is used to identify a known [AdaptiveCardTemplate].
Member value is an instance of 13.2.3 Card Data Object.
A JSON object that contains both input and output data for an Adaptive Card.
A JSON object or JSON array that provides information that the [AdaptiveCardTemplate] is bound to. The structure of the JSON value id dependent on the Adaptive Card template.