适用于 Microsoft 365 Copilot 的 API 插件

API 插件使 Microsoft 365 Copilot 中的声明性代理能够与具有 OpenAPI 说明的 REST API 进行交互。 使用 API 插件，用户可以要求声明性代理不仅查询 REST API 以获取信息，还可以创建、更新和删除数据和对象。 REST API 可以执行的任何作都可以通过自然语言提示进行访问。

API 插件提供 OpenAPI 说明文档和插件清单，Copilot 使用该文档了解 API 的功能。 然后，Copilot 可以决定何时安装并启用的插件的 API 适合回答任何给定的提示。 若要详细了解 API 插件所需的清单文件，请参阅 Microsoft 365 Copilot 的 API 插件清单架构。

例如，考虑一个预算 API，该 API 允许查询和创建预算、收取费用或向现有预算添加资金。 提示“Contoso 旅行预算中还剩多少”可能会触发预算插件，进行以下 API 调用。

GET /budgets?name=contoso%20travel

Copilot 使用 API 调用的响应来生成其响应：“Contoso 旅行预算当前有 5,000 美元的可用资金。 如果需要将资金分配给特定类别或跟踪支出，我也可以为你提供帮助。 只要告诉我如何帮助！

提示“向 Megan 的机票的 Contoso 旅行预算收取 500 美元”可以转换为以下 API 调用。

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot 使用返回的信息回复用户：“Megan 机票 500 美元的收费已成功处理。 Contoso 旅行预算现在还有 4,500 美元的可用资金。 如果你需要做更多的交易或需要进一步的预算帮助，请告诉我！

API 插件的工作原理

1. 用户询问代理“第四咖啡大厅装修预算还剩多少？”

2. 代理从其可用插件中标识与预算相关的插件，该插件具有获取预算详细信息的函数 GetBudget 。 它将用户问题的部分映射到函数的参数： budgetName=""。

3. 代理 要求用户 允许其发送到 Fourth Coffee lobby renovation 插件。

4. 用户选择允许与插件共享数据一次，或者选择始终允许共享此函数的数据。

5. 如果插件的 API 需要 身份验证，则插件会从令牌存储中请求令牌或 API 密钥。

6. 令牌存储返回令牌或密钥。 如果需要，令牌存储会导致代理提示用户登录。

7. 代理将请求发送到插件的 API，该 API 托管在 Microsoft 365 之外。

   GET /budgets?budgetName=Fourth+Coffee+lobby+renovation
   

8. API 返回其 OpenAPI 规范中指定的格式的 API 响应。

   {
     "name": "Fourth Coffee lobby renovation",
     "availableFunds": 5000.00
   }
   

9. 代理基于 API 响应生成响应。

10. 代理发出回应：“第四咖啡大厅装修预算中留下的可用资金是5,000美元。

确认作

Copilot 在将任何数据发送到 API 插件之前会询问用户。

默认情况下，仅检索数据的 API 为用户提供了“始终允许”选项，而修改数据的 API 则不会。 插件开发人员可以替代这些默认值。 有关详细信息，请参阅 适用于 Microsoft 365 Copilot 的 API 插件的确认提示。

自定义响应演示文稿

Copilot 使用 API 响应中的数据生成对话响应。 插件可以通过提供自适应卡片模板以结构化方式显示数据来自定义这些响应。

针对 Copilot 业务流程协调程序优化插件

Microsoft 365 Copilot 可以从其剧目中的许多技能中独一无二地选择正确的技能。 但是，如何确保 Copilot 选择 你的插件 来提供正确的技能呢？

答案在于如何描述插件、其技能和启动技能的参数。 在插件清单中指定简洁准确的说明，以便最好地确保 Copilot 业务流程协调程序知道何时以及如何调用插件。

向业务流程协调程序描述插件的方式取决于生成的插件类型，如下表所述。

生成 API 插件包

开发人员可以使用两种工具来生成 API 插件包。

• Visual Studio 或 Visual Studio Code 中的 Microsoft 365 代理工具包可以根据现有的 OpenAPI 说明创建插件包。 如果没有现有 API，则 Agents Toolkit 还具有具有示例 API 和相应插件包的初学者项目。
• Kiota 是一个命令行工具和Visual Studio Code扩展，可以根据现有的 OpenAPI 说明生成插件包。

限制

声明性代理插件

当声明性代理包含声明 性代理清单中定义的最多五个插件时，始终会将插件注入到提示符中。 当定义了五个以上的插件时，代理将使用语义匹配。 语义匹配基于插件的说明，而不是插件本身中的任何单个函数。

插件可以包含无限数量的函数。 即使只匹配一个函数，也会返回所有函数。 但是，由于令牌窗口限制，如果包含 10 个以上的函数，响应的质量可能会降低。

插件输入和输出的令牌窗口截断大型内容。 功能限制可能会随着模型改进而变化，具体取决于任何系统开销。 针对较小的令牌长度进行优化，或根据需要选择允许流式传输大型内容的扩展性选项。

相关内容

• 从现有 API for Microsoft 365 Copilot 生成 API 插件
• 使用适用于 Microsoft 365 Copilot 的新 API 生成 API 插件
• Microsoft 365 Copilot 的 API 插件清单架构
• 使用 API 插件编写声明性代理的有效说明