代理 SDK （预览版）

将 Bot Framework/Microsoft Agents SDK 活动有效负载转发到用户提供的代理终结点。 代理终结点 URL 按调用作为输入参数提供。 创建连接时选择身份验证：无身份验证、静态 API 密钥或Microsoft Entra ID OAuth（client_credentials）。 选择 OAuth 后，持有者令牌访问群体（在连接上配置的资源 URL）必须与目标代理预期的访问群体匹配。

此连接器在以下产品和区域中可用：

Service Class Regions
Copilot Studio 标准 除以下各项外的所有 Power Automate 区域：
     - 美国政府 （GCC）
     - 美国政府 （GCC High）
     - 由世纪互联运营的中国云
     - 美国国防部（DoD）
逻辑应用程序 标准 除以下各项外的所有 逻辑应用区域 ：
     - Azure 政府区域
     - Azure中国区域
     - 美国国防部（DoD）
Power Apps 标准 除以下各项外的所有 Power Apps 区域：
     - 美国政府 （GCC）
     - 美国政府 （GCC High）
     - 由世纪互联运营的中国云
     - 美国国防部（DoD）
Power Automate 标准 除以下各项外的所有 Power Automate 区域：
     - 美国政府 （GCC）
     - 美国政府 （GCC High）
     - 由世纪互联运营的中国云
     - 美国国防部（DoD）
联系人
Name Microsoft
URL https://support.microsoft.com
连接器元数据
Publisher Microsoft
网站 https://www.microsoft.com
隐私策略 https://privacy.microsoft.com/
Categories 生产力

代理 SDK 连接器将 Bot Framework/Microsoft Agents SDK 活动有效负载转发到用户提供的代理终结点。 代理终结点 URL 按调用作为输入参数提供;OAuth 令牌由平台从在连接上配置的Microsoft Entra ID应用程序凭据中优化，并在每个出站请求上作为持有者令牌注入。 持有者令牌访问群体（在连接上配置的资源 URL）必须与目标代理预期的受众匹配。

Prerequisites

  • 部署的Microsoft代理 SDK/Bot Framework 代理可以通过 HTTPS 访问。
  • 在托管代理的租户中注册Microsoft Entra ID应用程序，配置了调用目标代理的client_credentials授权和权限。
  • 代理的预期令牌受众（例如，代理Microsoft应用 IDapi://<appId>）。

获取凭据

若要对 API 请求进行身份验证，需要：

  1. Microsoft Entra ID应用程序的租户 ID。
  2. Microsoft Entra ID应用程序的客户端 ID（应用程序 ID）。
  3. 该应用程序的 客户端密码 。
  4. 与目标代理预期的受众匹配 的资源 URL （Bot Framework 技能身份验证模式）。

创建连接时提供这些值。 如果访问群体不同，则为每个代理创建一个连接。

已知问题和限制

  • 输入 agentEndpoint 必须是完整的 HTTPS URL（例如 https://my-agent.azurewebsites.net）。 连接器追加 /api/messages 并转发活动有效负载。
  • 连接器将转发活动有效负载 as-is，并且未设置 deliveryMode。 代理通过 POSTing 回复活动以异步方式（正常传递）返回到serviceUrl入站活动（调用方（例如，Microsoft Copilot Studio）提供 SAS 键回调serviceUrl）。
  • 此连接器以预览版提供。 可用性和功能可能会更改。

正在创建连接

连接器支持以下身份验证类型：
API 密钥 使用目标代理在自定义 HTTP 标头中预期的静态 API 密钥进行身份验证。 指定标头名称（例如 x-api-key）及其值。 所有区域 不可共享
Microsoft Entra ID（客户端凭据） 使用 client_credentials 流从Microsoft Entra ID应用程序中挖掘 OAuth 持有者令牌。 持有者令牌访问群体（资源 URL）必须与目标代理预期的受众匹配。 所有区域 不可共享
不进行身份验证 在没有任何身份验证标头的情况下调用目标代理终结点。 仅将此与显式接受匿名调用的代理一起使用。 所有区域 可共享
默认值 [已弃用] 此选项仅适用于没有显式身份验证类型的较旧连接，并且仅用于向后兼容性。 所有区域 不可共享

API 密钥

身份验证 ID：apiKey

适用：所有区域

使用目标代理在自定义 HTTP 标头中预期的静态 API 密钥进行身份验证。 指定标头名称（例如 x-api-key）及其值。

这是不可共享的连接。 如果 Power App 与另一个用户共享，系统会提示其他用户显式创建新连接。

Name 类型 Description Required
API 密钥标头名称 字符串 目标代理需要 API 密钥的 HTTP 标头的名称（例如 x-api-key 或 Ocp-Apim-Subscription-Key）。 True
API 密钥值 安全字符串 针对目标代理终结点的每个请求发送的静态 API 密钥值。 True

Microsoft Entra ID（客户端凭据）

身份验证 ID：oauthClientCredentials

适用：所有区域

使用 client_credentials 流从Microsoft Entra ID应用程序中挖掘 OAuth 持有者令牌。 持有者令牌访问群体（资源 URL）必须与目标代理预期的受众匹配。

这是不可共享的连接。 如果 Power App 与另一个用户共享，系统会提示其他用户显式创建新连接。

Name 类型 Description Required
租户 字符串 Microsoft Entra ID 应用程序的租户 ID True
客户端 ID 字符串 Microsoft Entra ID应用程序的客户端（或应用程序）ID。 True
客户端密码 安全字符串 Microsoft Entra ID应用程序的客户端密码。 True
资源 URL 字符串 OAuth 令牌的受众。 通常，目标代理Microsoft应用 ID（例如，api://< appId> 或应用 ID GUID）。 True

无身份验证

身份验证 ID：匿名

适用：所有区域

在没有任何身份验证标头的情况下调用目标代理终结点。 仅将此与显式接受匿名调用的代理一起使用。

这是可共享的连接。 如果 Power App 与其他用户共享，则连接也会共享。 有关详细信息，请参阅 画布应用的连接器概述 - Power Apps |Microsoft Docs

默认值 [已弃用]

适用：所有区域

此选项仅适用于没有显式身份验证类型的较旧连接，并且仅用于向后兼容性。

这是不可共享的连接。 如果 Power App 与另一个用户共享，系统会提示其他用户显式创建新连接。

操作

将活动发送到代理

将活动协议有效负载转发到 {agentEndpoint}/api/messages 中的代理终结点。 当连接使用 Microsoft Entra ID OAuth 时，令牌访问群体（连接上的资源 URL）必须与目标代理预期的受众相等（Bot Framework 技能身份验证模式）;如果访问群体不同，则为每个代理创建一个连接。 连接器转发活动有效负载 as-is，并且未设置“deliveryMode”;代理通过将 POSTing 回复活动异步（正常传递）回复到入站活动上提供的“serviceUrl”。

将活动发送到代理

操作 ID:
SendActivity

将活动协议有效负载转发到 {agentEndpoint}/api/messages 中的代理终结点。 当连接使用 Microsoft Entra ID OAuth 时，令牌访问群体（连接上的资源 URL）必须与目标代理预期的受众相等（Bot Framework 技能身份验证模式）;如果访问群体不同，则为每个代理创建一个连接。 连接器转发活动有效负载 as-is，并且未设置“deliveryMode”;代理通过将 POSTing 回复活动异步（正常传递）回复到入站活动上提供的“serviceUrl”。

参数

名称 密钥 必需 类型 说明
代理终结点 URL
 agentEndpoint True string

目标Microsoft代理 SDK/Bot Framework 终结点（例如）https://my-agent.azurewebsites.net的基 URL。 连接器追加 /api/messages。
object

返回

响应
object

定义

对象

这是类型“object”。