使用 REST API 中的工具扩展代理（预览版）

[本文是预发行文档，可能会有所更改。]

您可以使用 REST API（包括 OpenAI API）将您创建的智能体与外部系统连接，并访问可以在您的智能体中使用的可用数据。 您可以通过向 Copilot Studio 提供以下三项来将您的智能体连接到 REST API：

• 定义 API 函数和可用操作的 OpenAPI 规范
• 所需身份验证类型的详细信息，以及用户连接到 API 以访问外部系统的身份验证详细信息
• 帮助语言模型确定何时调用 API 以利用数据的说明

REST API 可以通过 Copilot Studio 添加到 Copilot 智能体和自定义智能体。

Copilot 智能体允许制作者将多个数据源（如连接器、API、提示和知识源）合并到一个智能体中。 您可以使用此智能体扩展 Microsoft 品牌的智能体体验，如智能 Microsoft 365 Copilot 副驾驶®。

自定义智能体是包含连接器、API、提示和知识源的独立智能体。 您可以通过将自定义智能体集成到网站或其他渠道中来直接使用自定义智能体。

先决条件

使用连接器操作扩展 Microsoft 品牌的智能体体验需要一些先决条件。

对于所有智能体体验类型，您必须有制作者级证书和 Copilot Studio 许可证。

您还需要 OpenAPI 规范的副本、了解所需身份验证类型以及身份验证详细信息。

向智能体添加 REST API 操作

将 REST API 添加到智能体涉及几个步骤。 以下部分将引导您完成整个过程。

对于自定义智能体和 Copilot 智能体，添加 REST API 的过程是相同的。

整个过程有几个步骤。

向智能体添加操作

1. 前往智能体的概述页面。

   

2. 在 “工具” 部分中，选择“ 添加工具”。 还可以转到 “工具 ”选项卡，然后选择“ 添加工具”。

   将显示 “添加工具 ”页。

3. 选择 “新建工具>REST API”。

提供 API 规范、描述和解决方案

1. 为要连接的 REST API 上传 OpenAPI 规范文件。 您可以将规范文件拖放到上传 REST API 屏幕中，也可以浏览系统以找到要使用的文件。

   

   备注

   OpenAPI 规范必须为 v2 格式的 JSON 文件。 如果提交的是 v3 规范，则会在创建过程中自动转换为 v2 规范。

   上传规范后，屏幕将更新以指示规范文件名和详细信息。

   

   在下面的步骤中，我们以 ADO 票务管理系统 SunnyADO 的特定示例为基础。 在此示例中，目的是允许用户通过智能体检索和更新其票证。

2. 验证详细信息，然后选择下一步。

   您将看到一个 API 插件详细信息页面，您可以在其中提供有关 API 的其他信息。

   

   描述字段最初是根据您上传的 API 规范中的描述填充的。 提供详细说明，因为代理业务流程使用说明来确定何时使用特定工具。 提供详细信息，包括同义词，以帮助您的智能体进行选择过程。

   例如，提供的初始描述是：“管理工单的简单服务。”

   更好的描述是：“一个用于从 SunnyADO 获取、检索、查找和显示现有工单的系统。 它允许用户更新、更改和管理工单，以提供更多数据来改进记录。

3. 在描述字段中输入改进后的描述。

4. 在解决方案下，下拉列表将列出当前环境中可用的所有解决方案。 选择要使用的解决方案。 有关什么是解决方案的详细信息，请参阅解决方案概念。

   

   如果您有首选解决方案，或者您选择的连接器已在解决方案中，将会自动选择该解决方案。

   您可以选择一个解决方案或将其留空。 如果将解决方案留空，则会使用操作名称和默认发布者为您创建解决方案。 通过将操作存储在解决方案中，您可以轻松跨环境移动操作。

   备注

   在这种情况下，如果您没有看到默认解决方案或 CDS 默认解决方案作为选项，我们建议您使用自定义解决方案以便于管理。 有关更多信息，请参阅：默认解决方案与自定义解决方案。

5. 选择解决方案后，选择下一步继续。

提供身份验证详细信息

此时将显示身份验证页面，以选择要用于 API 的身份验证类型。

1. 从列表中选择身份验证方法。

2. 填写身份验证方法的必填字段。 这些字段因身份验证方法而异。

   • 无：不需要其他字段。
   • API 密钥：
     • 参数标签：API 参数的文本标签。
     • 参数名称：API 参数的文本名称。
     • 参数位置：可以找到参数的位置。
   • Auth 2.0：
     • 客户端 ID：目标服务的客户端 GUID。
     • 客户端密钥–客户端的密钥值。 之后，当用户打开编辑面板时，不会显示密钥。 但是，请存储密钥，当您选择进行进一步编辑时，您需要用到它。
     • 授权 URL：用于授权源系统的 URL。
     • 令牌 URL：可以检索令牌的 URL。
     • 刷新 URL：在刷新方案中重定向到的 URL。
     • 范围：为 Microsoft Entra 应用的 API 分配的范围 URL。
     • 哪个 Microsoft 365 组织访问终结点：将对源的访问限制为制作者的组织或所有组织。
     • 哪个应用（客户端）可以使用终结点：定义可用于访问此数据的客户端系统的 GUID。 应用可以包括 Microsoft 365、Power Automate 和其他选项。

3. 完成所有字段后，选择下一步。

   你会看到“ 选择并配置插件工具 ”页，可在其中选择要为 API 启用的工具。

   

选择用于 API 的工具

选择要启用的 API 支持的工具。 通常，REST API 通过 API 规范中定义的终结点和 HTTP 方法（获取、放置、发布、删除等）的各种组合提供一系列工具。 在某些情况下，您可能不希望智能体的用户能够执行 API 通常提供的每个操作。 例如，您的 API 规范可能包括更新和删除操作，但您只希望智能体的用户能够创建记录。

1. 从列表中选择要配置的工具。

   此时将显示配置插件操作页面。

   

2. 配置所选操作。 与整体 API 一样，系统会要求你提供工具名称和工具说明。 描述最初是根据 API 规范中的描述预填充的。 名称不需要唯一，但它应表示工具本身。 与总体 API 说明一样，说明应足够具体，以便提供语言模型的详细信息，以便更好地识别查询是否与此特定工具保持一致。

3. 字段填写完成后，选择下一步。

   将显示 “查看工具的参数 ”页。

   

   此页面显示作为可能的输入和输出值的一部分提供的值。 这些值无法更改，但是可以更新输入和输出的描述。 此页面中的所有内容都是直接从上传的 API 规范中提取的。

4. 根据需要填写描述的值。 这些说明提供了这些值的用途的定义。 如果任何描述为空，则必须先完成这些描述，然后才能继续。 如果您没有更好的描述，可以粘贴名称。

5. 完成说明后，选择下一步。

   现在配置了第一个工具，并显示在“选择”和“配置插件工具”页上的“所选工具”列表中。

   

6. 此时添加您希望包含的任何其他操作。 添加希望代理支持的工具后，请选择“ 下一步”。

   将显示“ 查看工具 ”页。 该页提供配置的 REST API 工具的详细信息。

   

审阅并发布

1. 如果需要进行任何更新，可以选择返回并进行更改。 否则，请选择下一步。

   屏幕显示您的工具正在发布，同时该过程正在完成。 发布完成后，系统会通知你。

2. 发布完成后，将返回到 “选择工具 ”屏幕。 在这里，您可以将新配置的 REST API 添加到您的 Copilot 智能体或自定义智能体中，并完成组件的配置。

   

REST API 工具现在可用于你的代理中。