代理 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 按调用作为输入参数提供。 连接选择连接器如何向代理进行身份验证：无身份验证、静态 API 密钥、Microsoft Entra ID仅限应用令牌（客户端凭据）或Microsoft Entra ID委派用户令牌（用户登录）。 对于这两个Microsoft Entra ID选项，持有者令牌访问群体（在连接上配置的资源 URL）必须与目标代理预期的访问群体匹配。

Prerequisites

  • 部署的Microsoft代理 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添加为 Web 重定向 URI。
  • 对于 API 密钥和客户端凭据选项，代理的预期令牌访问群体（通常是代理的Microsoft应用 ID，例如api://<appId>或应用 ID GUID）。 对于用户登录，受众必须是应用 ID GUID（请参阅下文）。

获取凭据

Microsoft Entra ID（客户端凭据）

连接器发送仅限应用的令牌。 若要对 API 请求进行身份验证，需要：

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

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

Microsoft Entra ID（用户登录）

连接器发送登录到连接的帐户的委托令牌，以便代理可以代表该帐户交换它（例如，使用Microsoft 365 智能体 SDKConnectorUserAuthorization处理程序）。 您将需要：

  1. 代理Microsoft Entra ID应用程序的租户 ID。
  2. 客户端 ID：代理自己的Microsoft应用 ID。 仅当令牌颁发给代理自己的应用程序时，Microsoft 365 智能体 SDK才代表用户交换令牌。
  3. 该应用程序的 客户端密码 。
  4. 资源 URL：代理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。 代理通过 POSTing 回复活动以异步方式（正常传递）返回到serviceUrl入站活动（调用方（例如，Microsoft Copilot Studio）提供 SAS 键回调serviceUrl）。
  • Microsoft Entra ID（用户登录）连接始终将登录连接的帐户的委托令牌发送到该连接的每个调用，包括代表与代理聊天的其他人的呼叫。 它不会为每个调用方发送单独的令牌，因此活动 from 的用户可以不同于令牌中的用户。 仅将请求授权为已验证令牌中的帐户，并且不会将活动的 from 标头或请求标头视为聊天人员的授权。 如果代理必须充当与之聊天的每个人，请不要使用此连接类型。
  • 如果已登录帐户的同意被吊销，或者其会话无法再刷新，请再次登录到连接。
  • 此连接器以预览版提供。 可用性和功能可能会更改。

正在创建连接

连接器支持以下身份验证类型：
API 密钥 使用目标代理在自定义 HTTP 标头中预期的静态 API 密钥进行身份验证。 指定标头名称（例如 x-api-key）及其值。 所有区域 不可共享
Microsoft Entra ID（客户端凭据） 使用 client_credentials 流从Microsoft Entra ID应用程序中挖掘 OAuth 持有者令牌。 持有者令牌访问群体（资源 URL）必须与目标代理预期的受众匹配。 所有区域 不可共享
Microsoft Entra ID（用户登录） 通过目标代理的Microsoft Entra ID应用程序（授权代码流）登录，并发送登录帐户的委托持有者令牌。 使用此连接进行的每次调用都使用登录到连接的帐户，而不是与代理聊天的人员。 若要代表用户交换令牌，代理需要其下游委派的权限和许可配置。 所有区域 不可共享
不进行身份验证 在没有任何身份验证标头的情况下调用目标代理终结点。 仅将此与显式接受匿名调用的代理一起使用。 所有区域 可共享
默认值 [已弃用] 此选项仅适用于没有显式身份验证类型的较旧连接，并且仅用于向后兼容性。 所有区域 不可共享

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

Microsoft Entra ID（用户登录）

身份验证 ID：oauthAuthorizationCode

适用：所有区域

通过目标代理的Microsoft Entra ID应用程序（授权代码流）登录，并发送登录帐户的委托持有者令牌。 使用此连接进行的每次调用都使用登录到连接的帐户，而不是与代理聊天的人员。 若要代表用户交换令牌，代理需要其下游委派的权限和许可配置。

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

Name 类型 Description Required
租户 字符串 目标代理Microsoft Entra ID应用程序的租户 ID。 True
客户端 ID 字符串 目标代理Microsoft应用 ID。 使用代理自己的应用程序，以便代理可以代表用户交换委托的令牌。 True
客户端密码 安全字符串 目标代理Microsoft Entra ID应用程序的客户端密码。 True
资源 URL 字符串 委托令牌的受众。 必须是目标代理Microsoft应用 ID（GUID），与客户端 ID 相同的值：Microsoft Entra应用程序请求令牌本身时仅接受 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”。