Agent SDK （Preview）

將 Bot Framework / Microsoft Agents SDK 活動有效載荷轉發到使用者提供的代理端點。 每次通話中，代理端點的 URL 作為輸入參數提供。 建立連線時選擇認證：無需驗證、靜態 API 金鑰或Microsoft Entra ID OAuth （client_credentials）。 當選擇 OAuth 時，承載令牌受眾（連線上設定的資源 URL）必須與目標代理預期的受眾相符。

此連接器適用於以下產品和區域：

服務 Class Regions
Copilot Studio 標準 除以下部分外，所有Power Automate區域：
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
邏輯應用程式 標準 所有 Logic Apps 區域， 但下列區域除外：
     - Azure Government 區域
     - Azure 中國區域
     - 美國國防部 （DoD）
Power Apps 標準 除以下部分外，所有Power Apps區域
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
Power Automate（自動化服務） 標準 除以下部分外，所有Power Automate區域：
     - 美國政府 （GCC）
     - 美國政府（海灣合作委員會高中）
     - 由 21Vianet 營運的中國雲
     - 美國國防部 （DoD）
聯絡方式
名稱 Microsoft
URL https://support.microsoft.com
連接器中繼資料
發行者 Microsoft
網站 https://www.microsoft.com
隱私策略 https://privacy.microsoft.com/
類別 Productivity

Agent SDK 連接器會將 Bot Framework / Microsoft Agents SDK 活動載荷轉發到使用者提供的代理端點。 每次通話中提供代理端點 URL 作為輸入參數;OAuth 代幣由平台根據使用者提供的 Microsoft Entra ID 應用程式憑證在連線上設定，並以持有人憑證的形式注入，並於每次外發請求中注入為持有人憑證。 承載令牌受眾（連線上設定的資源網址）必須與目標代理預期的受眾相符。

先決條件

  • 一個已部署的 Microsoft Agents SDK / Bot Framework 代理程式，可透過 HTTPS 存取。
  • 一個註冊在承載該代理的租戶中的 Microsoft Entra ID 應用程式，並設定client_credentials了授權與呼叫目標代理的權限。
  • 代理人的預期代幣受眾（通常是代理人的 Microsoft 應用程式 ID）。api://<appId>

取得您的認證

要驗證您的 API 請求，您需要：

  1. Microsoft Entra ID 應用程式的租戶 ID。
  2. Microsoft Entra ID 應用程式的用戶端 ID（應用程式 ID）。
  3. 該應用程式的 客戶端秘密 。
  4. 資源 網址 與目標代理預期的受眾相符（機器人框架技能認證模式）。

建立連結時，請提供這些價值觀。 如果受眾不同，每位經紀人建立一個連結。

已知問題和限制

  • agentEndpoint輸入必須是完整的 HTTPS URL（例如，https://my-agent.azurewebsites.net）。 連接器會 /api/messages 附加並轉發活動有效載荷。
  • 連接器轉發活動有效載荷 as-is，且不會設定 deliveryMode。 代理會非同步（正常傳送）回應，透過 POST 回覆活動回傳給serviceUrl輸入活動（呼叫者，例如 Microsoft Copilot Studio，提供 SAS 鍵入回撥serviceUrl）。
  • 這個連接器目前還在預覽階段。 可用性與功能可能會有所變動。

正在建立連線

連接器支援下列驗證類型：
API 金鑰 用目標代理在自訂 HTTP 標頭中預期的靜態 API 金鑰來認證。 同時指定標頭名稱（例如 x-api-key）及其值。 所有地區 不可共享
Microsoft Entra ID （client credentials） 使用 client_credentials 流程，從 Microsoft Entra ID 應用程式鑄造 OAuth 持有人代幣。 持有人代幣受眾（資源網址）必須與目標代理預期的受眾相符。 所有地區 不可共享
無驗證 呼叫目標代理端點，且不使用任何認證標頭。 只對明確接受匿名電話的客服人員使用。 所有地區 可共用
預設值 [已棄用] 此選項僅適用於沒有明確驗證類型的舊連線，並且僅用於回溯相容性。 所有地區 不可共享

API 金鑰

認證 ID：apiKey

適用：所有地區

用目標代理在自訂 HTTP 標頭中預期的靜態 API 金鑰來認證。 同時指定標頭名稱（例如 x-api-key）及其值。

這不是可共用的連線。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

名稱 類型 Description Required
API 金鑰標頭名稱 字串 目標代理期待 API 金鑰的 HTTP 標頭名稱（例如 x-api-key 或 Ocp-Apim-Subscription-Key）。 沒錯
API 鍵值 安全字串 靜態 API 鍵值會在每個向目標代理端的請求中傳送。 沒錯

Microsoft Entra ID （client credentials）

Auth ID： oauthClientCredentials

適用：所有地區

使用 client_credentials 流程，從 Microsoft Entra ID 應用程式鑄造 OAuth 持有人代幣。 持有人代幣受眾（資源網址）必須與目標代理預期的受眾相符。

這不是可共用的連線。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

名稱 類型 Description Required
租戶 字串 Microsoft Entra ID 應用程式的租戶 ID 沒錯
用戶端識別碼 字串 Microsoft Entra ID 應用程式的用戶端（或應用程式）ID。 沒錯
用戶端密碼 安全字串 Microsoft Entra ID 應用程式的客戶端秘密。 沒錯
資源 URL 字串 OAuth 代幣的受眾。 通常是目標代理的Microsoft App ID（例如 api://< appId> 或 App ID GUID）。 沒錯

無驗證

認證ID：匿名

適用：所有地區

呼叫目標代理端點，且不使用任何認證標頭。 只對明確接受匿名電話的客服人員使用。

這是可共享的連接。 如果 Power App 與其他使用者共用，也會共用連線。 欲了解更多資訊，請參閱 Connectors 的畫布應用程式概覽 - Power Apps |Microsoft Docs

預設值 [已棄用]

適用：所有地區

此選項僅適用於沒有明確驗證類型的舊連線，並且僅用於回溯相容性。

這不是可共用的連線。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

動作

將活動傳送給代理人

將活動協定有效載荷轉發至代理端點 {agentEndpoint}/api/messages。 當連線使用 Microsoft Entra ID OAuth 時，標記受眾（連線上的資源 URL）必須與目標代理預期的受眾（Bot Framework 技能認證模式）相等;若受眾不同，則為每個代理建立一個連線。 連接器會轉發活動有效載荷 as-is，且不會設定「deliveryMode」;代理以非同步方式（正常傳送）回覆，透過將回覆活動發送至 inbound 活動中提供的「serviceUrl」。

將活動傳送給代理人

作業識別碼：
SendActivity

將活動協定有效載荷轉發至代理端點 {agentEndpoint}/api/messages。 當連線使用 Microsoft Entra ID OAuth 時，標記受眾（連線上的資源 URL）必須與目標代理預期的受眾（Bot Framework 技能認證模式）相等;若受眾不同，則為每個代理建立一個連線。 連接器會轉發活動有效載荷 as-is，且不會設定「deliveryMode」;代理以非同步方式（正常傳送）回覆，透過將回覆活動發送至 inbound 活動中提供的「serviceUrl」。

參數

名稱 機碼 必要 類型 Description
代理端點 URL
 agentEndpoint True string

目標 Microsoft Agents SDK / Bot Framework 端點的基礎網址（例如 https://my-agent.azurewebsites.net）。 連接器會附加 /api/訊息。
object

傳回

response
object

定義

物件

這是類型 'object'。