如何将 Azure AI Foundry 代理服务与 OpenAPI 指定工具配合使用

现在，可以使用 OpenAPI 3.0 指定工具将 Azure AI 代理连接到外部 API，从而实现与各种应用程序的可缩放互操作性。 使自定义工具能够使用托管标识 (Microsoft Entra ID) 对访问和连接进行身份验证，以增强安全性，因此非常适合与现有基础结构或 Web 服务集成。

OpenAPI 指定工具通过提供标准化、自动化和可缩放的 API 集成来提高函数调用体验，从而增强代理的功能和效率。 OpenAPI 规范提供了一种用于描述 HTTP API 的正式标准。 这样，人们就可以了解 API 的工作原理、API 序列如何协同工作、生成客户端代码、创建测试、应用设计标准等。 目前，我们使用 OpenAPI 3.0 指定的工具支持三种身份验证类型：anonymous、 API keymanaged identity

使用支持

先决条件

1. 确保已完成快速入门中的先决条件和设置步骤。

2. 检查 OpenAPI 规范中是否存在以下要求：

   1. 虽然 OpenAPI 规范并不要求，但要搭配 OpenAPI 工具使用每个函数，仍需使用 operationId。
   2. operationId 应仅包含字母、- 和 _。 可以对其进行修改以满足要求。 建议使用描述性名称来帮助模型有效地确定要使用的函数。

使用 API 密钥进行身份验证

使用 API 密钥身份验证，可以使用各种方法（例如 API 密钥或持有者令牌）对 OpenAPI 规范进行身份验证。 每个 OpenAPI 规范仅支持一个 API 密钥安全架构。如果需要多个安全架构，请创建多个 OpenAPI 规范工具。

1. 更新 OpenAPI 规范安全架构。 它具有一个 securitySchemes 部分，以及一种 apiKey 类型的方案。 例如：

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   通常，您只需更新与连接中名称 name 相对应的key字段。 如果安全方案包含多个方案，我们建议只保留其中一个。

2. 更新 OpenAPI 规范以包括一个 security 部分：

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. 移除 OpenAPI 规范中需要 API 密钥的任何参数，因为 API 密钥将通过连接存储和传递，如本文稍后所述。

4. 创建用于存储 API 密钥的 custom keys 连接。

   1. 转到 Azure AI Foundry 门户并选择“AI Project”。 单击“连接的资源”。

   2. 在设置页中选择“+ 新建连接”。

      注释

      如果在以后重新生成 API 密钥，则需要使用新密钥更新连接。

      

   3. 在“其他资源类型”中选择“自定义密钥”。

      

   4. 输入以下信息

      • 键：安全方案的 name 字段。 在此示例中，它应为 x-api-key

               "securitySchemes": {
                  "apiKeyHeader": {
                            "type": "apiKey",
                            "name": "x-api-key",
                            "in": "header"
                        }
                }
        

      • 值：YOUR_API_KEY
      • 连接名称：YOUR_CONNECTION_NAME（需要在下面的示例代码中使用此连接名称。）
      • 访问：可以选择仅“仅限此项目”或“共享到所有项目”。 只需在下面的示例代码中确保输入连接字符串的项目有权访问此连接。

5. 创建连接后，可以通过 SDK 或 REST API 使用它。 使用本文顶部的选项卡查看代码示例。

使用托管标识进行身份验证（Microsoft Entra ID）

Microsoft Entra ID 是基于云的标识和访问管理服务，员工可以使用该服务访问外部资源。 Microsoft Entra ID 允许使用额外的安全性对 API 进行身份验证，而无需传入 API 密钥。 设置托管身份验证后，代理将通过其正在使用的 Azure AI 服务进行身份验证。

若要设置使用托管标识进行身份验证，请：

1. 启用代理的 Azure AI 服务，确保已启用 system assigned managed identity。

   

2. 创建要通过 OpenAPI 规范连接到的服务的资源。

3. 分配对资源的适当访问权限。

   1. 请单击访问控制以管理您的资源

   2. 单击“ 添加 ”，然后在屏幕顶部 添加角色分配 。

      

   3. 选择所需的正确角色分配，通常至少需要 READER 角色。 然后单击“下一步”。

   4. 选择托管标识，然后单击选择成员。

   5. 在托管标识下拉菜单中，搜索 Azure AI 服务 ，然后选择代理的 AI 服务。

   6. 单击“完成”。

4. 完成设置后，可以通过 Foundry 门户、SDK 或 REST API 继续使用该工具。 使用本文顶部的选项卡查看代码示例。