通过

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

  • 项目

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

重要

API 插件仅支持作为 声明性代理中的作。 智能 Microsoft 365 Copilot 副驾驶®中未启用它们。

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 插件的工作原理

显示 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. 代理发送响应“第四咖啡大厅装修预算中留下的可用资金是5000美元。

确认作

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

插件确认对话框的屏幕截图。

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

自定义响应演示文稿

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

来自 API 插件的自适应卡片响应的屏幕截图

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

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

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

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

插件类型 描述者 了解详细信息
API 插件 OpenAPI 说明 如何使 OpenAPI 文档在扩展 Copilot 时有效
Copilot Studio 操作 Copilot Studio对话映射中的名称和说明 使用生成 AI 协调副驾驶主题和作
消息扩展插件 应用部件清单 消息扩展插件指南

生成 API 插件包

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

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

限制

API 响应中的 URL 经过修订

为了保护用户的隐私，Copilot 会编辑 API 响应中包含的任何 URL。 此行为的唯一例外是响应语义属性对象中的 属性指定的url属性中的任何 URL。

相关内容