使用 REST API 中的工具擴充代理程式 （預覽版）

[本文章是發行前版本文件，且隨時可能變更。]

您可以使用 REST API (包括 OpenAI API) 將您建立的代理程式與外部系統連接，並存取可用資料以在代理程式中使用。 您可以透過向 Copilot Studio 提供以下三項內容將代理程式連接到 REST API：

• 定義 API 功能和可用動作的 OpenAPI 規範
• 有關所需驗證類型的詳細資訊，以及使用者連接到 API 存取外部系統的驗證詳細資訊
• 幫助語言模型決定何時呼叫 API 來利用資料的描述

可以透過 Copilot Studio 將 REST API 新增至 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 規範。

   上傳規範後，畫面會更新以指示規範檔案名稱和詳細資訊。

   

   在接下來的步驟中，我們將在 SunnyADO (一個 ADO 票證管理系統) 的具體範例中執行此程序。 在該範例中，目的是允許使用者透過代理程式擷取和更新他們的票證。

2. 驗證詳細資訊，然後選擇下一步。

   您將看到一個 API 外掛程式詳細資訊頁面，您可以在其中提供有關 API 的其他資訊。

   

   描述欄位最初根據您上傳的 API 規範中的描述進行填入。 提供詳細的說明，因為您的代理程式協調流程會使用說明來決定何時使用特定工具。 提供詳細資訊，包括同義詞，以幫助您的代理程式完成選擇過程。

   例如，最初提供的描述是：「管理票證的簡單服務」。

   更好的描述是：「用於從 SunnyADO 取得、擷取、尋找和顯示現有票證的系統。 它允許使用者更新、變更和管理票證，以提供更多資料來改進記錄。

3. 在描述欄位下輸入改進的描述。

4. 在解決方案底下，下拉式清單會列出目前環境中可用的所有解決方案。 選取要使用的解決方案。 有關解決方案的詳細資訊，請參閱解決方案概念。

   

   如果您有首選解決方案，或者所選連接器已在解決方案中，則會自動選擇該解決方案。

   您可以選擇解決方案，也可以將其留空。 如果將解決方案留空，系統會為您建立包含動作名稱和預設發佈者的解決方案。 透過將動作儲存在解決方案中，可以輕鬆地跨環境移動它。

   注意

   在這種情況下，如果您沒有看到預設解決方案或 CDS 預設解決方案作為選項，我們建議您使用自訂解決方案以便於管理。 如需更多資訊，請參閱：預設解決方案和自訂解決方案。

5. 選擇解決方案後，選擇下一步以繼續。

提供驗證詳細資訊

將顯示驗證頁面，以選擇 API 使用的驗證類型。

1. 從清單中選擇一種驗證方法。

2. 填寫驗證方法的必填欄位。 這些欄位根據驗證方法而有所不同。

   • 無：不需要其他欄位。
   • API 金鑰：
     • 參數標籤：API 參數的文字標籤。
     • 參數名稱：API 參數的文字名稱。
     • 參數位置：可以找到參數的位置。
   • 認證 2.0：
     • 用戶端識別碼：目標服務的用戶端 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 工具現在可用於您的代理程式。