service-itsm-teams-employee-agent-configure

在 Microsoft Teams 中配置嵌入式 Agentforce Employee Agent

让嵌入式 Agentforce Agent（“IT Service Employee Agent”）在 Microsoft Teams ITSM 自定义客户端（“Salesforce Employee Assist” → “Ask AI Agent”）中实际回复。Teams 自定义客户端会在运行时通过其 esDeveloperName 加载 Messaging-in-App-and-Web（MIAW）部署；在已提交的 Core 配置（service-cloud-requestor-agent-miaw.configuration.json / Teams 应用清单）中，该名称被硬编码为 Teams_AgentForce，因此 Embedded Service Deployment 必须恰好命名为 Teams_AgentForce，且无法按组织重命名。

这是 Teams ITSM 中最难、文档最少的部分。从头开始构建的完整操作指南——已在真实组织中实时验证——见：

→ references/teams-embedded-employee-agent.md

一次执行一个步骤。 这些步骤会发起真实的状态变更 API 调用。每次只运行一个操作，展示其结果并确认成功后再继续——不要将多个设置调用合并到一个并行代码块中。

范围

• 范围内：完全通过 API 构建 Teams 自定义客户端加载的 MIAW 通道 + 部署（不点击 Setup UI）——使用 Enhanced-messaging 的 Web 通道，并开启 User Verification（auth 模式 = Auth），由 Enhanced Chat User Verification Key Set（PublicKeyCertificateSet，类型 JWKS_URL，端点 <Org>/id/keys，issuer = Employee Site URL）提供支持；创建自定义客户端的 Embedded Service Deployment Teams_AgentForce；创建 Omni-Flow 路由流，其 routeWork 操作指向一个真实且处于 Active 状态的 Agentforce Employee Agent。创建并分配 Agent Access 权限集，授予门户用户访问该 Agent 的权限（这一步会让 Agent 真正回复）。通过 API 端到端验证令牌/路由链，并诊断“已加入后离开 / 无回复”问题。
• 范围外：启用 Teams 功能的 Salesforce Go 页面开关，以及 Azure/SSO/Named-Credential 设置（service-itsm-teams-configure）。创建员工门户/站点（experience-portal-create）。仅当确认 auth-ON + Key Set 链和 Agent-Access-assigned 都已就绪，但会话仍由队列持有且 Agent 没有回复时，才处理 Agentforce Agent 自身的 GenAI planner / Omni-Channel presence / capacity 问题——这种剩余情况属于 Agentforce Employee Agent 团队负责的 Agent 运行时问题（见参考文档中的 “joins then leaves” 部分）。

前置条件

• 已启用 Teams ITSM 功能，且员工门户站点已上线（请先运行 service-itsm-teams-configure 和 experience-portal-create）。你需要 Employee Site URL（例如 https://<org>.my.site.com/empPortal）以及组织的 My Domain URL。
• 存在一个真实且处于 Active 状态的 Agentforce Employee Agent（SELECT Id FROM BotDefinition WHERE Type='InternalCopilot' AND AgentType='AgentforceEmployeeAgent'，且有一个处于 Active 状态的 BotVersion）。如果不存在，请先创建——启用 service-cloud-it-service-employee-agent Go 功能可能会自动配置该 Agent，但不保证会这样做（已验证：某个组织启用了该功能，但没有配置任何内容）。可靠的部署方式是 service-itsm-agentic-setup-employee-agent-configure（该方式会读取随附的 Employee 模板中的 Agent Script，并以 NGA-native bundle 的形式创建、发布并激活 Agent）；对应的底层路径是针对 EmployeeCopilot__AgentforceEmployeeAgent 执行 ITSM Connect agent-templates install + activate。先部署 Agent，再运行本技能将其嵌入 Teams。两种方式及其注意事项详见参考文档中的 “Prerequisite: the IT Service Employee Agent must exist” 部分。

“Agent 加入后又离开”的原因（构建前请阅读）

只有整个链路完整时，Agent 才会回复——缺少任何一个环节都会出现经典症状：“Agent 加入对话，然后离开，没有回复”。这些问题都可以在此技能中修复：

#	要求	缺失时的症状	修复方法
1	通道身份验证模式 = Auth（User Verification 已开启），并附加了 Key Set	/unauthenticated/access-token → BAD_REQUEST “Set the auth mode to false”（身份验证已开启但没有 Key Set → 客户端回退到未经过身份验证的端点）；或 /eventrouter/v1/sse 返回 401（Key Set 端点／颁发者错误）	附加一个 JWKS_URL Key Set（端点为 <Org>/id/keys，颁发者为 Employee Site URL），并将其关联到通道——不要关闭身份验证
2	Portal 用户拥有 Agent Access 权限集，以启用 IT Service Employee Agent	令牌成功生成，SSE 连接成功，但 Agent 加入后又离开，且没有任何 ConversationEntry	创建并分配一个包含 Agent Access 的权限集 → 指向该 Agent
3	Teams_AgentForce ESD 已创建并发布	SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce' → 0 行；Teams 无法加载缺失的部署	通过 Metadata 部署 API 类型的 ESD，并通过 Connect 发布（步骤 3）

这与此技能的早期版本建议相反：早期版本曾建议关闭 User Verification，并且不要附加 Key Set。之所以得出这个结论，是因为当时的构建开启了身份验证，却忘记了 Key Set，导致 Teams 客户端使用了未经身份验证的端点，并遇到 “Set the auth mode to false” 错误。经验证且获得产品认可的修复方式是：开启身份验证 + 使用 JWKS_URL Key Set（已通过实时截图确认），这样客户端就会使用通道所需的经过身份验证的令牌流程。

如果确认已开启身份验证并附加 Key Set、已分配 Agent Access，且 ESD 已创建并发布，但 Agent 仍然不回复，请在升级到 Agentforce Employee Agent 团队（负责 Agent Omni 状态／容量／GenAI 规划）作为最后手段之前，转交给 service-itsm-teams-debug（其 AGENTFORCE 通过／失败检查清单会逐项检查完整的令牌／路由／ESD／Agent 链路）。在经过验证的组织中，修复上述可修复原因就足够了。

已验证的操作指南（摘要 — 100% 通过 API 完成，无需手动操作；完整 XML 和调用见参考资料）

按以下顺序部署 — 先部署 Key Set，再部署引用它的渠道，最后部署 ESD。 所有部署均使用位于 --api-version 67.0 的隔离 sfdx-project.json。每次只运行一个步骤。

1. Enhanced Chat User Verification Key Set — 通过 Metadata 部署包含 <type>JWKS_URL</type>、<jwksEndPoint> = <Org_Url>/id/keys、<jwtIssuer> = Employee Site URL 的 PublicKeyCertificateSet。目录必须为 PublicKeyCertificateSet/，后缀必须为 .PublicKeyCertificateSet-meta.xml。 （JWKS_URL 是端点 URL 模式；Jwks 是上传密钥模式，不接受 URL。）
2. Messaging 渠道，部署类型为 Web，域名 = Employee Site URL — 通过 Metadata 部署 MessagingChannel（messagingChannelType=EmbeddedMessaging），其 sessionHandlerFlow = 指向 IT Service Employee Agent 的 路由 Flow，sessionHandlerQueue = 备用队列（例如 chatqueue）。在同一个代码块中启用 User Verification 并关联 Key Set： <embeddedConfig><authMode>Auth</authMode><messagingAuthorizations>…publicKeyCertificateSetName…</messagingAuthorizations></embeddedConfig>。 然后，在发布 ESD 之前激活渠道（MessagingChannel.IsActive=true）。路由 Flow 和备用队列是前置条件 — 如果 Route_To_MIAW_AEA 是通过模板安装的， 则其中包含占位符 ID（请重新指定）；如果不存在，则自行创建。sfdc_livemessage Omni 服务渠道是标准/预先存在的（请查询，不要创建）。参见参考资料 §A/§E/§F。
3. 创建 Teams_AgentForce Embedded Service Deployment（ESD） — Teams 客户端通过 esDeveloperName 加载的部署。通过 Metadata 部署一个**API 类型**、名称恰好为 Teams_AgentForce 的 ESD，其 <messagingChannel> 引用步骤 2 中的渠道，然后通过 POST /services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<esdId> 发布（{} → isSuccess:true；发布路由为 v67.0）。参见参考资料 §C/§D。如果缺少此 ESD， 登录会成功，但 Agent 永远不会回复 — 使用 SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce'（Tooling）进行验证。
4. 创建权限集（例如“Agent Access”），启用 IT Service Employee Agent，并分配给门户用户（授予 RBAC 权限 — 分配前请确认）。参见参考资料 §G。
5. 在一个全新的 Teams 聊天中重新测试 — 现有会话仍绑定到旧部署。

不要使用 POST /connect/service-itsm/createMessagingChannel — 它会强制使用自己的默认值；请自行创建渠道，以便控制 Flow、队列、开发者名称以及精确的身份验证和 Key Set 配置。具体 API 请求体、对象名称、验证查询和完整的常见问题索引，请参见参考资料。

相关技能

技能	适用场景
service-itsm-teams-configure	启用 Salesforce Go 页面中的 Teams 功能开关 + Azure/Entra 应用 + SSO/Named Credentials — 请先运行；它会将嵌入式 Agent 的配置委托给此技能
experience-portal-create	创建此技能所需 URL 对应的员工服务门户/站点
service-itsm-teams-debug	诊断已构建的 Agent 为何不回复（或其他 Teams ITSM 故障）— 运行 AGENTFORCE 通过/失败检查清单并报告修复措施
service-itsm-channels-coordinate	Teams、Slack、Swarming、Notifications、Portal 的顶层菜单