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 作為輸入參數提供。 連線可選擇連接器如何向代理進行認證：無認證、靜態 API 金鑰、Microsoft Entra ID 應用程式專用憑證（用戶端憑證），或 Microsoft Entra ID 委派使用者憑證（使用者登入）。 對於兩種 Microsoft Entra ID 選項，承載權杖受眾（連線上設定的資源 URL）必須與目標代理預期的受眾相符。

先決條件

  • 一個已部署的 Microsoft Agents SDK / Bot Framework 代理程式，可透過 HTTPS 存取。
  • 針對 Microsoft Entra ID（用戶端憑證）：註冊於承載代理的租戶中的 Microsoft Entra ID 應用程式，並設定client_credentials授權並授權呼叫目標代理。
  • 對於 Microsoft Entra ID（使用者登入）：代理自身的 Microsoft Entra ID 應用程式（其 Microsoft 應用程式 ID），並附有用戶端秘密、使用者可同意的公開 API 範圍，稱為 Microsoft Graph User.Read（「登入並閱讀使用者資料」）在同意下授權，並https://global.consent.azure-apim.net/redirect/agentsdk新增為網頁重定向 URI。
  • API 金鑰與用戶端憑證選項則是代理的預期令牌受眾（通常是代理的 Microsoft 應用程式 ID api://<appId> 或應用程式 ID GUID）。 使用者登入時，受眾必須是 App ID GUID（見下文）。

取得您的認證

Microsoft Entra ID （client credentials）

連接器會傳送一個僅限應用程式的代幣。 要驗證您的 API 請求，您需要：

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

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

Microsoft Entra ID （user sign-in）

連接器會將已登入帳號的委派令牌傳送到連線，讓代理人能代表該帳號交換該令牌（例如，使用 Microsoft 365 Agents SDK ConnectorUserAuthorization 處理器）。 您將需要：

  1. 代理人的 Microsoft Entra ID 應用程式的租戶 ID。
  2. 客戶端 ID：代理自身的 Microsoft 應用程式 ID。 Microsoft 365 Agents SDK 僅在憑證發給代理自身應用程式時，才代表使用者交換該憑證。
  3. 該應用程式的 客戶端秘密 。
  4. 資源網址：代理的 Microsoft 應用程式 ID（GUID），與用戶端 ID 值相同。 因為代理自身的應用程式同時是客戶端與資源，Microsoft Entra 此處需要 GUID（AADSTS90009否則）;api://<appId>此選項不支援此功能。

建立連線時提供這些值，然後登入並同意代理的公開範圍。 每個客服人員建立一個連線。

應用程式還需要Microsoft Graph User.Read（「登入並閱讀使用者設定檔」）授權且需同意;若無此權限，登入將失敗，AADSTS90008。

若要將權杖交換下游 API，請設定該 API 對代理應用程式的授權權限，並取得使用者或管理員的同意。 在代理自身 API 上公開一個範圍並不會授予下游權限。

已知問題和限制

  • agentEndpoint輸入必須是完整的 HTTPS URL（例如，https://my-agent.azurewebsites.net）。 連接器會 /api/messages 附加並轉發活動有效載荷。
  • 連接器轉發活動有效載荷 as-is，且不會設定 deliveryMode。 代理會非同步（正常傳送）回應，透過 POST 回覆活動回傳給serviceUrl輸入活動（呼叫者，例如 Microsoft Copilot Studio，提供 SAS 鍵入回撥serviceUrl）。
  • Microsoft Entra ID（使用者登入）連線會將登入帳號的授權憑證傳送到該連線，針對每次該連線通話，包括代表與客服聊天的其他人通話。 它不會為每位呼叫者發送獨立的代幣，因此該活動 from 的使用者可能與代幣中的使用者不同。 請只授權請求作為驗證過的憑證中的帳戶，不要把活動或 from 請求標頭視為聊天對象的權限。 如果客服必須扮演每個與其聊天的人，就不要使用這種連線方式。
  • 如果已登入帳號的同意被撤銷或無法重新整理會話，請重新登入該連線。
  • 這個連接器目前還在預覽階段。 可用性與功能可能會有所變動。

正在建立連線

連接器支援下列驗證類型：
API 金鑰 用目標代理在自訂 HTTP 標頭中預期的靜態 API 金鑰來認證。 同時指定標頭名稱（例如 x-api-key）及其值。 所有地區 不可共享
Microsoft Entra ID （client credentials） 使用 client_credentials 流程，從 Microsoft Entra ID 應用程式鑄造 OAuth 持有人代幣。 持有人代幣受眾（資源網址）必須與目標代理預期的受眾相符。 所有地區 不可共享
Microsoft Entra ID （user sign-in） 透過目標代理的 Microsoft Entra ID 應用程式（授權碼流程）登入，並傳送已登入帳戶的委派持有人代幣。 每次用這個連線打的電話都是用登入連線的帳號，而不是跟客服聊天的人。 若要代表使用者交換令牌，代理人需要設定其下游委派權限與同意。 所有地區 不可共享
無驗證 呼叫目標代理端點，且不使用任何認證標頭。 只對明確接受匿名電話的客服人員使用。 所有地區 可共用
預設值 [已棄用] 此選項僅適用於沒有明確驗證類型的舊連線，並且僅用於回溯相容性。 所有地區 不可共享

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）。 沒錯

Microsoft Entra ID （user sign-in）

認證 ID：oauthAuthorizationCode

適用：所有地區

透過目標代理的 Microsoft Entra ID 應用程式（授權碼流程）登入，並傳送已登入帳戶的委派持有人代幣。 每次用這個連線打的電話都是用登入連線的帳號，而不是跟客服聊天的人。 若要代表使用者交換令牌，代理人需要設定其下游委派權限與同意。

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

名稱 類型 Description Required
租戶 字串 目標代理的 Microsoft Entra ID 應用程式的租戶 ID。 沒錯
用戶端識別碼 字串 目標代理的 Microsoft 應用程式 ID。 使用代理自己的應用程式，讓代理能代表使用者交換委派的令牌。 沒錯
用戶端密碼 安全字串 目標代理的 Microsoft Entra ID 應用程式的用戶端秘密。 沒錯
資源 URL 字串 觀眾是為了被委託的代幣。 必須是目標代理的 Microsoft 應用程式 ID（GUID），與用戶端 ID 值相同：當應用程式自行請求令牌時，Microsoft Entra 只接受 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'。