[本文章是發行前版本文件，且隨時可能變更。]
您可以使用 REST API (包括 OpenAI API) 將您建立的代理程式與外部系統連接，並存取可用資料以在代理程式中使用。 你可以透過提供 Copilot Studio 三項功能，將代理連接到 REST API：
- 定義 API 功能和可用動作的 OpenAPI 規範
- 有關所需驗證類型的詳細資訊，以及使用者連接到 API 存取外部系統的驗證詳細資訊
- 幫助語言模型決定何時呼叫 API 來利用資料的描述
你可以透過 Copilot Studio 為 Copilot 代理和自訂代理新增 REST API。
這很重要
本文包含 Microsoft Copilot Studio 預覽文件，內容可能會有所變動。
預覽功能不適用於生產環境，而且功能可能受到限制。 這些功能是在正式發行前先行推出，讓您能夠搶先體驗並提供意見反應。
如果你正在打造一個具備生產就緒的代理程式，請參考 Microsoft Copilot Studio 概述。
Copilot 代理允許創作者將多個資料來源如連接器、API、提示詞和知識來源整合成單一代理。 使用此代理程式來擴展 Microsoft 品牌代理體驗，如 Microsoft 365 Copilot。
自訂代理程式是包含連接器、API、提示和知識來源的獨立代理程式。 您可以透過將自訂代理程式整合到網站或其他管道來直接使用它們。
注意
你必須根據 OpenAPI v2 規範來建立 REST API 工具。 此要求是因為 Power Platform 在處理 API 規範時的行為所致。 如果你提交了 v3 規範，建立過程會自動將其轉換成 v2 規範。
必要條件
- 具備創客級的證照，以及 Copilot Studio 執照。
- 這是你想連接的 REST API 的 OpenAPI 規範副本
- 了解連接 API 所需的認證類型，以及認證細節。
在你的代理程式中新增 REST API 工具
要在您的代理程式中新增 REST API 工具，請完成以下步驟：
接下來的章節將一步步引導你完成整個過程。
新增 REST API 的流程對自訂代理和 Microsoft 365 Copilot 代理都是一樣的。
新增代理工具並選擇 REST API
請前往你經紀人的 總覽 頁面。
在 [工具] 區段中，選取 [ 新增工具]。 您也可以前往 工具 索引標籤，然後選取 新增工具。
新增 工具 頁面隨即顯示。
選取 [新增工具>REST API]。
提供 API 規範、描述與解決方案
上傳您要連接的 REST API 的 OpenAPI 規範檔案。 您可以將規範檔案拖曳到上傳 REST API 畫面中，也可以瀏覽系統以找到您想要使用的檔案。
注意
OpenAPI 規範必須是 v2 格式的 JSON 檔案。 如果你提交了 v3 規範，建立過程會自動將其轉換成 v2 規範。
上傳規格後，畫面會更新，顯示規格檔名稱及詳細資訊。
在接下來的步驟中，程序使用了一個特定的 SunnyADO 範例，這是一個 ADO 工單管理系統。 在該範例中，目的是允許使用者透過代理程式擷取和更新他們的票證。
確認細節後，選擇 下一步。
您將看到一個 API 外掛程式詳細資訊頁面，您可以在其中提供有關 API 的其他資訊。
描述欄位最初是根據你上傳的 API 規範中的描述來填充的。 提供詳細的說明，因為您的代理程式協調流程會使用說明來決定何時使用特定工具。 提供詳細資訊，包括同義詞，以幫助您的代理程式完成選擇過程。
例如，最初提供的描述是：「管理票證的簡單服務」。
更好的描述是：「用於從 SunnyADO 取得、擷取、尋找和顯示現有票證的系統。 它允許使用者更新、變更和管理票證，以提供更多資料來改進記錄。
在描述欄位下輸入改進的描述。
在解決方案底下，下拉式清單會列出目前環境中可用的所有解決方案。 選取要使用的解決方案。 在 解決方案概念中了解更多解決方案。
如果您有首選解決方案，或者所選連接器已在解決方案中，則會自動選擇該解決方案。
您可以選擇解決方案，也可以將其留空。 如果將解決方案留空，系統會為您建立包含動作名稱和預設發佈者的解決方案。 透過將動作儲存在解決方案中，可以輕鬆地跨環境移動它。
注意
如果在這種情況下你看不到預設解決方案或 CDS 預設解決方案，可以新增自定義解決方案以便於管理。 了解更多關於 預設解決方案與自訂解決方案的比較。
選擇解決方案後，選擇下一步以繼續。
提供認證細節
驗證頁面會出現。 選擇用於 API 的認證類型。
從清單中選擇一種驗證方法。 從三個選項中選擇：
- 無：存取 API 無需認證。
- API 金鑰：如果您的 API 需要 API 金鑰來進行驗證，請選擇此選項。 執行時，當代理想要使用 API 工具時，會提示使用者進行認證。 使用者提供 API 金鑰，代理則使用該金鑰連接 API。
- 認證 2.0：如果您的 MCP 伺服器使用 OAuth 2.0 進行認證，請選擇此選項。 OAuth 2.0 允許個別使用者透過身份提供者驗證 API。 此認證方式允許使用者授予您的應用程式（代理）權限，而無需與代理分享其憑證。
輸入所選認證方法所需的欄位。 這些欄位根據驗證方法而有所不同。
- 無：無需提供資訊。
-
API 金鑰：
- 參數標籤：用於呈現給使用者的 API 參數的文字標籤。
- 參數名稱：API 鍵參數實際用於標頭或查詢字串的名稱。
- 參數位置：你如何傳送 API 的金鑰。 選擇 標頭 或 查詢。
-
認證 2.0：
- 用戶端 ID：身分識別提供者在您註冊應用程式時發出的用戶端識別碼。 用戶端識別碼可讓身分識別提供者知道哪個應用程式正在提出要求。
- 用戶端密碼：身分識別提供者在您註冊應用程式時發出的用戶端密碼。 您的代理程式會傳送用戶端密碼以及用戶端識別碼，以證明您的代理程式有權要求 MCP 伺服器的存取權杖。
- 授權 URL：您的代理程式將使用者重新導向至身分提供者的端點，以登入並授予代理程式權限（在代理程式的聊天介面中顯示的同意卡）。 使用者在此處進行身份驗證，然後身份提供者使用授權碼在回呼 URL 上回應代理。
- 令牌網址：你的代理人用來將授權碼（或刷新令牌）交換成 存取令牌及 刷新令牌的端點。 存取權杖可讓您的代理程式代表使用者使用 MCP 伺服器。 重新整理權杖可讓您的代理程式在先前的存取權杖到期時從重新整理端點取得新的存取權和重新整理權杖。
- 重新整理 URL：要使用重新整理權杖要求新存取權杖 (這樣使用者在權杖到期時就不需要再次登入) 的端點。
- 範圍：（可選）：你的應用程式要求的權限，以空格分隔的清單呈現。
-
哪個 Microsoft 365 組織可以存取端點：此設定將來源的存取權限限制為僅供製作者的組織或所有組織存取。 選取下列任一項目：
- 僅限我的組織
- 任何Microsoft 365組織
- 哪個應用程式（用戶端）可以使用端點：GUID，定義了可用來存取這些資料的用戶端系統。 應用程式可能包含 Microsoft 365、Power Automate 及其他選項。
填寫所有欄位後，選擇 「下一步」。
「 選擇與配置你的工具 」頁面會出現，你可以從 API 中選擇啟用的工具。
從 API 中選擇工具
從 REST API 中選擇支援 API 的工具，加入你的代理程式。 一般而言，REST API 透過 API 規範中定義的端點與 HTTP 方法組合（取得、輸入、發佈、刪除等）提供一系列工具。 在某些情況下，您可能不希望代理程式的使用者能夠執行 API 通常提供的每個動作。 舉例來說，你的 API 規範可能包含更新和刪除的功能，但你只希望代理的使用者能建立紀錄。
從清單中選取要設定的工具。
「 配置您的工具 」頁面會顯示。
設定所選工具的名稱與描述。 類似整體 API，提供 工具名稱 與 工具描述。 描述最初是根據 API 規範中的描述預先填入的。 名稱不需要是唯一的，但應該代表工具本身。 描述和整體 API 描述一樣，應該足夠具體，讓語言模型能更好地判斷你的查詢是否符合這個特定工具。
欄位填寫完畢後，選擇下一步。
「 檢閱工具的參數 」頁面隨即顯示。
此頁面顯示輸入的預期值與回傳的輸出值。 你無法更改這些數值，但可以更新輸入和輸出的描述。 此頁面中的所有內容均直接從上傳的 API 規範中提取。
視需要更新描述。 這些描述提供了值用途的定義。 如果任何描述是空白的，你必須先完成才能繼續。 如果你沒有更好的描述，可以貼上名字。
完成描述後，選擇下一步。
第一個工具現在已設定，並顯示在選取並設定您的外掛程式工具頁面上的所選工具清單中。
在此時，請加入你想從 API 中加入的其他工具。 當你完成新增希望經紀人支援的工具後，選擇 「下一步」。
「 檢閱您的工具 」頁面隨即顯示。 此頁面提供已設定 REST API 工具的詳細資料。
檢閱和發佈
如果你需要更新，請選擇 返回 並進行你的更改。 否則，請選取 [下一步]。
畫面顯示您的工具正在發布中，並指示這一過程正在進行。 發佈完成後您會收到通知。
選擇 「建立連線 」以繼續。 你會回到 新增工具 畫面。
在工具類型選擇器中選擇 REST API 。 你可以從你的 API 看到新建立的工具。 您透過 API 新增的每個工具應該有一個對應的項目。
對於 API 中新設定的每個工具，請建立或選擇一個 API 連線，並將該工具加入你的代理程式：
- 在 新增工具 畫面中，選擇該工具。
- 在 「連線」中，選擇現有連線或 選擇建立新連線。
- 輸入所需的連接資訊，然後選擇建立與工具的連接。
- 選擇 新增並配置 ，將工具加入你的代理程式。
REST API 的工具現在已經可以在你的代理中使用了。
提示
若要更輕鬆地找到您的工具，請使用搜尋列來尋找它。