Copilot Studio Client S2S深度解析：Microsoft 365 Agents SDK如何通过D2E API免Bot Service直连-港品优选

Copilot Studio Client S2S深度解析：Microsoft 365 Agents SDK如何通过D2E API免Bot Service直连

【免费下载链接】AgentsThe Microsoft 365 Agent SDK simplifies building full stack, multichannel, trusted agents for platforms including M365, Teams, Copilot Studio, and Webchat.项目地址: https://gitcode.com/gh_mirrors/agents/Agents

本文带你完整理解 Copilot Studio Client S2S 直连机制：微软开源的 Microsoft 365 Agents SDK（GitHub 加速计划 / agents / Agents 项目）基于 D2E（Direct-to-Engine）API，让你的应用跳过 Azure Bot Service，凭 Entra ID 令牌直接调用已发布的 Copilot Studio 智能体。这是目前构建跨后端、多通道、可信任 Agent 应用的关键能力，全文将用最简步骤带你跑通第一条对话。

📌 什么是 S2S 直连？一张表看懂 D2E 与 DirectLine 的区别

传统上，程序化调用 Copilot Studio 智能体需要走 DirectLine 通道，中间必须经过一次 Azure Bot Service（ABS）中转。而 S2S（Server-to-Server）直连模式下，请求路径被大幅缩短：

对比维度	DirectLine	D2E 直连（S2S）
请求路径	客户端 → Azure Bot Service → MCS	客户端 → PPAPI 网关 → MCS
身份认证	DirectLine secret/token（自定义）	仅支持 Entra ID（AAD）JWT
通信协议	Activity Protocol	Activity Protocol
时延表现	较高（多一跳 ABS）	更低（无 ABS 中转）
S2S 支持	需自定义流程	原生支持 App-only 或 OBO 令牌

💡PPAPI是位于 D2E 控制器之前的"前门"，负责校验 JWT 签名，下游所有服务直接信任网关已验证的声明，因此直连链路依然安全可控。

该能力目前处于Private Preview阶段，按环境/租户粒度开启，官方完整说明见 docs/copilot-studio-client-s2s-doc.md。

⚡ 两种集成模式：App-only 与用户委托（OBO）怎么选？

模式	令牌类型	用户上下文	适用场景
True S2S（应用上下文）	客户端凭据流程获取的 App-only 令牌	无	后端到后端、调度/代理类应用、匿名智能体（Agent 需设为 "No Authentication" 模式）
用户委托 S2S（OBO）	委托令牌（On-Behalf-Of）	有	应用代表用户发起调用、已启用身份认证的智能体

OBO 模式的访问规则：应用代理至少拥有 Agent 的 viewer 权限，且用户本人也具备访问权（owner / viewer / editor），两者缺一不可。

🚀 快速上手：四步完成 Copilot Studio Client S2S 连接

第一步：在 Copilot Studio 创建并发布 Agent

在 Copilot Studio 中创建 Agent 并发布，然后进入Settings → Advanced → Metadata记下三个关键值：Schema Name、Environment Id、Tenant Id。若使用 True S2S 模式，还需将智能体认证设为No Authentication。

第二步：在 Entra ID 创建应用注册并授权

在 Azure 门户创建新的 App Registration；
添加Power Platform API的CopilotStudio.Copilots.Invoke权限（按场景选择 Delegated 或 Application）；
由租户管理员授予管理员同意；
生成 Client Secret（或接入托管身份/联合凭据）。

第三步：将 Agent 共享给应用身份

在 Copilot Studio 打开 Agent，点击右上角 "…" →Share，搜索并选中你的应用身份，授予 viewer 权限并确认共享列表中已出现该应用。这一步是运行时 ACL 校验的前提。

第四步：配置并运行 Copilot Studio Client

核心配置项如下（.NET 示例取自samples/dotnet/copilotstudio-client/appsettings.json）：

配置项	说明
`EnvironmentId`/`SchemaName`/`TenantId`	来自 Agent 元数据，三件套定位目标智能体（也可直接提供`DirectConnectUrl`替代）
`AppClientId`	应用注册的 Client ID
`AppClientSecret`	仅 True S2S 需要
`UseS2SConnection`	`true`= 应用上下文；`false`= 用户委托（OBO）

项目为三大语言提供了官方客户端示例，均可直接参考：

.NET 示例：samples/dotnet/copilotstudio-client/（核心代码 Program.cs、S2S 令牌处理 AddTokenHandlerS2S.cs）
Node.js 示例：samples/nodejs/copilotstudio-client/
Python 示例：samples/python/copilotstudio-client/

运行前按各示例中的 env/appsettings 模板填入凭据，启动后即可获得控制台对话界面，完成与已发布 Agent 的第一轮对话。

🔒 三道安全护栏：防止跨轮次会话劫持

S2S 直连虽然免去了 Bot Service，但安全校验并未减少。系统会在每轮请求中执行三项身份一致性检查：

检查项	行为	失败时错误码
应用身份一致性	应用发起的会话只能由同一应用（相同 ObjectId）继续	`CallerIdentityMismatch`
用户身份一致性	用户委托会话只能由同一用户继续	`CallerIdentityMismatch`
身份类型一致性	App-only 会话不能被委托身份继续，反之亦然	`CallerIdentityTypeMismatch`

这些检查叠加在 PPAPI 网关 JWT 校验、每 Agent 共享 ACL 以及不可变的 ConversationInfo 记录之上。此外请牢记两条硬约束：仅限同租户（调用方应用必须与 Agent 在同一租户），以及True S2S 要求匿名模式（应用上下文中无用户，用户级认证的工具与连接不可用）。

官方建议在启用 S2S 时通过 DLP（数据防泄漏）策略限制智能体通道，仅保留明确用于 S2S 的入口，以符合企业安全治理要求。

📚 延伸阅读与项目资源

S2S 官方设计文档（含 Hello World 全流程、测试场景清单）：docs/copilot-studio-client-s2s-doc.md
.NET S2S 客户端示例：samples/dotnet/copilotstudio-client/
Node.js 客户端示例：samples/nodejs/copilotstudio-client/
Python 客户端示例：samples/python/copilotstudio-client/
OBO 授权完整示例（用户委托 S2S 的进阶参考）：samples/dotnet/obo-authorization/
错误码速查：AgentErrorCodes.md、AgentErrorCodesJS.md

🎯一句话总结：只需完成"应用注册 + 共享授权 + 客户端配置"三步，Microsoft 365 Agents SDK 的 Copilot Studio Client 即可通过 D2E API 免 Bot Service 直连你的智能体——更低时延、原生 Entra 认证、企业级 ACL 护栏，一次搞定。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析