如何搭配 OpenAPI 指定工具使用 Foundry Agent Service。

你現在可以透過 OpenAPI 3.0 指定工具，將 Azure AI 代理連接到外部 API，實現與各種應用程式的可擴展互通性。 透過使用管理身份（Microsoft Entra ID）進行認證，您可以安全地啟用自訂工具來驗證存取與連線。 此方法非常適合與現有基礎設施或網路服務整合。

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 金鑰認證，你可以透過不同方法驗證你的 OpenAPI 規格，例如 API 金鑰或持有人令牌。 每個 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. 建立 custom keys 連線以儲存您的 API 金鑰。

   1. 前往 Microsoft Foundry 入口網站 ，從左側導覽窗格選擇 管理中心 。

      

   2. 在左側導覽窗格的 AI 專案下選擇 「已連接資源 」。

   3. 在 [設定] 頁面中選取 [+ 新增連線]。

      備註

      如果您在之後的日期中重新產生 API 金鑰，則需要使用新金鑰來更新連線。

      

   4. 選取其他資源類型的自定義金鑰。

      

   5. 輸入下列資訊

      • 金鑰： 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 金鑰。 當你設定好受管理身份驗證後，代理使用的 Foundry 工具會負責驗證。

在設定管理身分驗證時，你需要提供一個 Audience 值。 受眾是 OAuth2 資源識別碼（亦稱為作用域或應用程式 ID URI），用以識別受管理身份可存取的 API 或服務。

常見的受眾價值觀：

• Azure AI 服務（包括 Foundry）： https://cognitiveservices.azure.com/
• Azure Resource Manager APIs: https://management.azure.com/
• Microsoft Graph：https://graph.microsoft.com/
• 在 Microsoft Entra ID 註冊的自訂 API：請使用在 API 應用程式註冊取得的應用程式 ID URI

使用受控身份進行驗證設定：

1. 請確保您的 Foundry 資源啟用了系統指定的管理身份。

   

2. 透過 OpenAPI 規範為你想連接的服務建立資源。

3. 為該資源分配適當的存取權限。

   1. 選擇 存取控制（Access Control ）作為你的資源。

   2. 選擇 新增 ，然後在螢幕頂 端新增角色分配 。

      

   3. 選擇所需的適當角色分配。 通常，至少需要 READER 的角色。 然後選取下一步。

   4. 選擇 管理身份 ，然後選擇 選擇成員。

   5. 在受管理身份下拉選單中，搜尋 Foundry Tools ，然後選擇你代理人的 Foundry 工具。

   6. 選取 完成。

4. 完成設定後，你可以透過 Foundry 入口網站、SDK 或 REST API 使用這個工具。 使用本文頂端的索引標籤來查看程式代碼範例。