适用于智能 Microsoft 365 Copilot 副驾驶® 的 API 插件清单架构 2.2

项目
11/19/2024

API 插件使智能 Microsoft 365 Copilot 副驾驶®能够与 OpenAPI 说明所述的 REST API 进行交互。 API 插件中的 OpenAPI 说明描述了 Copilot 可以与之交互的 REST API。此外，API 插件包括一个插件清单文件，该文件提供有关插件的元数据，例如插件的名称、说明和版本。插件清单还包括有关插件功能的信息，例如它支持的 API 和它可以执行的操作。

以下文章介绍 API 插件清单文件使用的 2.2 架构。有关 API 插件的详细信息，请参阅用于智能 Microsoft 365 Copilot 副驾驶®的 API 插件。

与以前版本相比的更改

此架构版本引入了版本 2.1 中的以下更改。

security_info向 Function capabilities 对象添加了属性。此属性允许你证明插件的行为，以评估调用函数的风险。
从插件功能对象中删除了localization已弃用的属性。使用 2.1 架构的 Teams 工具包生成的清单包括已弃用 localization 属性。如果包含此属性，则使用 2.2 架构的清单将失败验证。

JSON 架构

本文档中所述的架构可在此处找到 JSON 架构格式。

约定

URL 中的相对引用

除非另有指定，否则作为 URL 的所有属性都可以是相对引用。清单文档中的相对引用与清单文档的位置相对。

字符串长度

除非另有说明，否则所有字符串属性应限制为 4K 个字符。此字符串长度不会为整个文档赋予任何可接受的大小。实现可以自由地对清单长度施加自己的实际限制。

无法识别的属性

本文档中定义的 JSON 对象仅支持所述的属性。任何 JSON 对象中无法识别的属性都应使整个文档无效。

字符串本地化

可本地化字符串可以使用本地化键而不是文本值。语法为 [[key_name]]，其中 key_name 是本地化文件中属性中的 localizationKeys 键名称。有关本地化的详细信息，请参阅本地化代理。

本地化字符串示例

{
    "schema_version": "v2.2",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

插件清单对象

插件清单文档的根是包含描述插件的属性的 JSON 对象。

插件清单对象包含以下属性。

属性	类型	说明
`schema_version`	String	必需。架构版本。以前的版本是 `v1` 和 `v2`。必须设置为 `v2.2`。
`name_for_human`	字符串	必填。插件的简短用户可读名称。它必须至少包含一个非白空间字符。可以忽略超过 20 的字符。此属性可本地化。
`namespace`	String	已弃用。可选。
`description_for_model`	String	可选。提供给模型的插件的说明。此说明应描述插件的用途，以及其功能在什么情况下相关。可以忽略超过 2048 的字符。此属性可本地化。
`description_for_human`	String	必填。插件的可读说明。可以忽略超过 100 的字符。此属性可本地化。
`logo_url`	String	可选。用于提取业务流程协调程序可能使用的徽标的 URL。实现 MAY 提供了替代方法，用于提供满足其视觉要求的徽标。此属性可本地化。
`contact_email`	String	可选。安全/审查、支持和停用联系人的电子邮件地址。
`legal_info_url`	String	可选。一个绝对 URL，用于查找包含插件服务条款的文档。此属性可本地化。
`privacy_policy_url`	String	可选。一个绝对 URL，用于查找包含插件隐私策略的文档。此属性可本地化。
`functions`	Function 对象的数组	可选。描述插件可用的函数的一组函数对象。每个函数对象名称在数组中必须唯一。数组的顺序并不重要。 `functions`如果该属性不存在，并且存在 OpenAPI 运行时，则从 OpenAPI 操作推断函数。
`runtimes`	OpenAPI 运行时对象的数组	可选。描述插件使用的运行时的一组运行时对象。
`capabilities`	插件功能对象	可选。描述插件的功能。

函数对象

与模型应如何与函数交互的信息。

函数对象包含以下属性。

属性	类型	说明
`id`	String	可选。
`name`	String	必填。唯一标识此函数的字符串。运行时对象可以引用此标识符来将运行时绑定到函数。当函数绑定到 OpenAPI 运行时时，该值必须与 OpenAPI 说明中的值匹配 `operationId` 。值必须与正则表达式匹配 `^[A-Za-z0-9_]+$` 。
`description`	String	可选。更适合模型的说明，例如令牌上下文长度注意事项或用于改进插件提示的关键字 (keyword) 用法。
`parameters`	函数参数对象	可选。一个对象，该对象包含以与运行时无关的方式描述函数的参数的属性。它镜像 json 架构的形状，但仅支持 JSON 架构功能的一小部分。 `parameters`如果该属性不存在，类型为的运行时对象所描述的`OpenApi`函数使用 OpenAPI 说明来确定参数。 JSON 对象中的每个成员都是描述参数语义的函数参数对象。
`returns`	返回对象 OR Rich 返回对象	可选。描述从函数返回的值的语义。
`states`	函数状态对象	可选。定义业务流程协调程序状态的状态对象。
`capabilities`	函数功能对象	可选。包含用于在调用函数时配置业务流程协调程序的可选功能的数据集合。

函数对象示例

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

函数参数对象

一个对象，用于标识可传递给函数的参数集。此对象的结构镜像 JSON 架构对象的形状，但它仅支持 JSON 架构关键字的子集。

函数参数对象包含以下属性。

属性	类型	说明
`type`	String	可选。 JSON 架构类型。必须设置为 `object`。
`properties`	函数参数属性对象	必填。一个对象，用于将参数名称映射到其定义。
`required`	字符串数组	可选。必需参数的属性的名称。与 JSON 架构中不同，此数组中的值必须与属性中列出的 `properties` 名称匹配。

函数参数对象示例

{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

函数参数属性对象

一个对象，用于将参数名称映射到其定义。

函数参数属性对象包含以下属性。

属性	类型	说明
名称匹配 `^[A-Za-z0-9_]+$`	函数参数对象	可选。与属性名称匹配的参数对应的参数定义。

函数参数对象

一个对象，用于描述函数参数的语义。

函数参数对象包含以下属性。

属性	类型	说明
`type`	String	必填。指定参数的类型。可取值为：`string`、`array`、`boolean`、`integer`、`number`。
`items`	函数参数对象	可选。一个函数参数对象，用于描述数组中的单个元素。仅当为 `array`时`type`，必须存在。
`enum`	字符串数组	可选。此参数的有效值的数组。仅当为 `string`时`type`，必须存在。
`description`	String	可选。参数的说明。
`default`	数组、布尔值、字符串、数字、整数	可选。属性指定的 `type` 类型的值，指示 API 在未提供可选参数的值时使用的值。

函数参数示例

{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

返回对象

包含从函数返回的值的语义。

返回对象包含以下属性。

属性	类型	说明
`type`	String	必填。指定 API 返回的值的类型。可能的值为： `string`。
`description`	String	可选。 API 返回的值的说明。

Rich 返回对象

指示函数返回与丰富响应协议兼容的响应。

rich 返回对象包含以下属性。

属性	类型	说明
`$ref`	String	必需。必须设置为 `https://copilot.microsoft.com/schemas/rich-response-v1.0.json`。

函数状态对象

定义业务流程协调程序状态的状态对象。

函数状态对象包含以下属性。

属性	类型	说明
`reasoning`	State 对象	可选。模型可以调用函数和执行计算的状态。
`responding`	State 对象	可选。模型可以生成向用户显示的文本的状态。模型无法调用处于响应状态的函数。
`disengaging`	State 对象	可选。

State 对象

包含在特定业务流程协调程序状态中调用函数的具体说明。

状态对象包含以下属性。

属性	类型	说明
`description`	String	可选。描述在特定业务流程协调程序状态中使用函数的用途。
`instructions`	数组、字符串	可选。字符串或字符串数组，用于向业务流程协调程序提供有关在特定业务流程协调程序状态中如何使用此函数的说明。提供单个字符串表示打算提供一组完整的指令，以替代任何内置函数提示。提供字符串数组指示增强内置函数提示机制的意图。
`examples`	数组、字符串	可选。字符串或字符串数组，用于向业务流程协调程序提供有关如何调用此函数的示例。

状态对象示例

{
  "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": []
        }
      }
    }
  ]
}

函数功能对象

包含用于在调用函数时配置业务流程协调程序的可选功能的数据集合。

函数功能对象包含以下属性。

属性	类型	说明
`confirmation`	确认对象	可选。描述在调用函数之前应向用户显示的确认对话框。
`response_semantics`	响应语义对象	可选。描述业务流程协调程序如何解释响应有效负载并提供视觉呈现。
`security_info`	安全信息对象	可选。包含有关插件行为的证明，以评估调用函数的风险。如果省略此属性，则函数无法与包含代理的其他插件或功能交互。

确认对象

描述业务流程协调程序如何在调用函数之前要求用户确认。

确认对象包含以下属性。

属性	类型	说明
`type`	String	可选。指定确认的类型。可取值为：`None`、`AdaptiveCard`。
`title`	String	可选。确认对话框的标题。此属性可本地化。
`body`	String	可选。确认对话框的文本。此属性可本地化。

响应语义对象

包含用于标识响应有效负载语义并使用自适应卡片在丰富的视觉体验中呈现该信息的信息。

响应语义对象包含以下属性。

属性	类型	说明
`data_path`	String	必填。 JSONPath RFC9535 查询，用于标识函数响应中的一组元素，这些元素将使用每个项中指定的模板呈现。
`properties`	响应语义属性对象	可选。允许将 JSONPath 查询映射到已知数据元素。每个 JSONPath 查询相对于结果值。
`static_template`	Object	可选。符合自适应卡片架构和模板语言的 JSON 对象。此自适应卡片实例用于呈现插件响应的结果。如果 `template_selector` 不存在或无法解析为自适应卡，则使用此值。
`oauth_card_path`	String	可选。

静态模板示例

{
  "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}"
            }
          ]
        }
      }
    }
  }
}

动态模板示例

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

响应语义属性对象

允许将 JSONPath 查询映射到已知数据元素。每个 JSONPath 查询相对于结果值。

响应语义属性对象包含以下属性。

属性	类型	说明
`title`	String	可选。结果引文的标题。
`subtitle`	String	可选。结果引文的副标题。
`url`	String	可选。结果引文的 URL。
`thumbnail_url`	String	可选。结果缩略图图像的 URL。
`information_protection_label`	String	可选。结果内容的数据敏感度指示器。
`template_selector`	String	可选。要用于呈现结果的自适应卡片实例的 JSONPath 表达式。

安全信息对象

包含用于确定调用函数的相对风险的信息。

安全信息对象包含以下属性。

属性	类型	说明
`data_handling`	字符串数组	必需。描述函数的数据处理行为的字符串数组。有效值为 `GetPublicData`、、`GetPrivateDataDataTransform`、 `DataExport`和 `ResourceStateUpdate`。

数据处理值

值	说明	示例
`GetPublicData`	指示函数从不需要身份验证的外部源检索数据。	一个函数，用于调用服务以从公共网站检索数据。
`GetPrivateData`	指示函数从需要身份验证的外部源或用户的当前应用程序检索数据。	一个函数，用于从专用数据库或用户当前打开的文档获取数据。
`DataTransform`	指示函数仅返回基于输入的输出，而不引入任何新数据或导致资源更新。	将数字转换为单词或设置日期格式的函数。
`DataExport`	指示函数将数据发送或写入到函数本身外部的位置。	将数据保存到本地或云文件的函数。
`ResourceStateUpdate`	指示函数通过启动事务、更改现实世界中的进程、授予或拒绝权限或执行需要用户显式确认的任何其他操作来影响资源。	一个函数，用于预订酒店房间或将工作项的状态从 `active` 更改为 `resolved`。

注意

尝试安装插件时， DataExport 使用值的插件清单可能无法通过验证。这是暂时的，不久将得到解决。

OpenAPI 运行时对象

描述插件如何调用 OpenAPI 函数。

OpenAPI 运行时对象包含以下属性。

属性	类型	说明
`type`	String	必填。将此运行时标识为 OpenAPI 运行时。必须设置为 `OpenApi`。
`auth`	运行时身份验证对象	必填。调用运行时所需的身份验证信息。
`run_for_functions`	字符串数组	可选。此运行时中可用的函数的名称。如果省略此属性，则运行时描述的所有函数都可用。提供的字符串值可以包含通配符。多个运行时不得隐式或显式声明对同一函数的支持。
`spec`	OpenAPI 规范对象	必填。包含调用运行时所需的 OpenAPI 信息。

OpenAPI 规范对象

包含调用运行时所需的 OpenAPI 信息。

OpenAPI 规范对象包含以下属性。

属性	类型	说明
`url`	String	可选。用于提取 OpenAPI 规范的 URL，通过 GET 请求调用。除非存在，否则 `api_description` 此成员是必需的。
`api_description`	String	可选。包含 OpenAPI 说明的字符串。如果此成员存在， `url` 则不是必需的，如果存在，则忽略。
`progress_style`	String	可选。用于显示函数进度的进度样式。可取值为：`None`、`ShowUsage`、`ShowUsageWithInput`、`ShowUsageWithInputAndOutput`。

OpenAPI 规范对象示例

{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}

运行时身份验证对象

包含插件用于向运行时进行身份验证的信息。

运行时身份验证对象包含以下属性。

属性	类型	说明
`type`	String	可选。指定调用函数所需的身份验证类型。可取值为：`None`、`OAuthPluginVault`、`ApiKeyPluginVault`。
`reference_id`	String	可选。当为 `OAuthPluginVault` 或 `ApiKeyPluginVault`时`type`使用的值。提供 `reference_id` 所需的身份验证配置值时，将独立获取该值。存在此机制是为了防止需要在插件清单中存储机密值。

运行时身份验证对象示例

{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

插件功能对象

描述插件的功能。

插件功能对象包含以下属性。

属性	类型	说明
`conversation_starters`	Conversation 初学者对象的数组	可选。可向用户显示的对话启动器，以获取有关如何调用插件的建议。

对话初学者对象

插件可以回答的问题示例。

对话初学者对象包含以下属性。

属性	类型	说明
`text`	String	必填。对话启动器的文本。此属性可本地化。
`title`	String	可选。对话初学者的标题。此属性可本地化。

对话初学者对象示例

{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

清单示例

下面是插件清单文件的示例，该文件使用本文中所述的大多数清单属性和对象属性：

{
  "schema_version": "v2.2",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "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": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "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."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "GetPublicData",
            "GetPrivateData"
          ]
        }
      }
    },
    {
      "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."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "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"
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    }
  ],
  "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/"
}

另请参阅

用于智能 Microsoft 365 Copilot 副驾驶®的 API 插件

通过

适用于 智能 Microsoft 365 Copilot 副驾驶® 的 API 插件清单架构 2.2

与以前版本相比的更改

JSON 架构

约定

URL 中的相对引用

字符串长度

无法识别的属性

字符串本地化

本地化字符串示例

插件清单对象

函数对象

函数对象示例

函数参数对象

函数参数对象示例

函数参数属性对象

函数参数对象

函数参数示例

返回对象

Rich 返回对象

函数状态对象

State 对象

状态对象示例

函数功能对象

确认对象

响应语义对象

静态模板示例

动态模板示例

响应语义属性对象

安全信息对象

数据处理值

OpenAPI 运行时对象

OpenAPI 规范对象

OpenAPI 规范对象示例

运行时身份验证对象

运行时身份验证对象示例

插件功能对象

对话初学者对象

对话初学者对象示例

清单示例

另请参阅

反馈

其他资源

适用于智能 Microsoft 365 Copilot 副驾驶® 的 API 插件清单架构 2.2