service-itsm-teams-employee-agent-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure the Embedded Agentforce Employee Agent in Microsoft Teams

在Microsoft Teams中配置嵌入式Agentforce员工代理

Make the embedded Agentforce agent ("IT Service Employee Agent") actually reply inside the Microsoft Teams ITSM custom client ("Salesforce Employee Assist" → "Ask AI Agent"). The Teams custom client loads a Messaging-in-App-and-Web (MIAW) deployment at runtime by its

esDeveloperName

, which is hard-wired to
Teams_AgentForce
in committed Core config (

service-cloud-requestor-agent-miaw.configuration.json

/ the Teams app manifest) — so the Embedded Service Deployment must be named exactly
Teams_AgentForce
and cannot be renamed per-org.

This is the hardest, most under-documented part of Teams ITSM. The full build-from-scratch recipe — verified live against a real org — lives in:

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

Execute one step at a time. These steps make real, state-changing API calls. Run a single operation, show its result, confirm it succeeded, then proceed — do not batch multiple setup calls into one parallel block.

让嵌入式Agentforce代理（"IT Service Employee Agent"）能够在Microsoft Teams ITSM自定义客户端（"Salesforce Employee Assist" → "Ask AI Agent"）内实际回复消息。Teams自定义客户端会在运行时通过其

esDeveloperName

加载Messaging-in-App-and-Web（MIAW）部署，该名称在已提交的核心配置（

service-cloud-requestor-agent-miaw.configuration.json

/ Teams应用清单）中被硬编码为
Teams_AgentForce
——因此嵌入式服务部署的名称必须精确为
Teams_AgentForce
，且无法按组织重命名。

这是Teams ITSM中最复杂、文档最不完善的部分。完整的从零开始构建方案——已在真实组织中验证通过——位于：

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

请逐步执行每个步骤。这些步骤会调用真实的、会改变状态的API。执行单个操作，查看结果，确认成功后再继续——请勿将多个设置调用批量放入一个并行块中。

Scope

范围

In scope: Building the MIAW channel + deployment the Teams custom client loads entirely via API (zero Setup-UI clicks) — a Web Enhanced-messaging channel with User Verification ON (auth mode = Auth) backed by an Enhanced Chat User Verification Key Set (
```
PublicKeyCertificateSet
```
, type
```
JWKS_URL
```
, endpoint
```
<Org>/id/keys
```
, issuer = Employee Site URL), the Teams_AgentForce
custom-client Embedded Service Deployment, and an Omni-Flow routing flow whose
```
routeWork
```
action targets a real, Active Agentforce Employee Agent. Creating and assigning the Agent Access permission set that grants the portal user access to the agent (the step that makes it actually reply). Verifying the token/routing chain end to end via API and diagnosing the "joined then left / no reply" symptom.
Out of scope: Enabling the Teams feature Salesforce Go page toggle and Azure/SSO/Named-Credential setup (
```
service-itsm-teams-configure
```
). Creating the employee portal/site (
```
experience-portal-create
```
). Fixing the Agentforce agent's own GenAI planner / Omni-Channel presence / capacity only after the auth-ON + Key Set chain and Agent-Access-assigned are all confirmed and the session still stays queue-owned with no agent reply — that residual case is an agent-runtime concern owned by the Agentforce Employee Agent team (see the "joins then leaves" section in the reference).

包含的内容：完全通过API（无需点击Setup-UI）构建Teams自定义客户端加载的MIAW渠道+部署——启用用户验证（认证模式=Auth）的Web增强消息渠道，其背后是增强聊天用户验证密钥集（
```
PublicKeyCertificateSet
```
，类型
```
JWKS_URL
```
，端点
```
<Org>/id/keys
```
，签发者=员工站点URL）、Teams_AgentForce
自定义客户端嵌入式服务部署，以及一个Omni-Flow路由流，其
routeWork
操作指向真实、活跃的Agentforce员工代理。创建并分配Agent Access权限集，授予门户用户访问代理的权限（这是让代理实际回复的关键步骤）。通过API端到端验证令牌/路由链，并诊断"加入后离开/无回复"的问题。
不包含的内容：启用Teams功能的Salesforce Go页面开关以及Azure/SSO/命名凭据设置（
```
service-itsm-teams-configure
```
）。创建员工门户/站点（
```
experience-portal-create
```
）。仅在确认启用认证+密钥集链且已分配Agent Access权限，但会话仍处于队列归属状态且无代理回复的情况下，才修复Agentforce代理自身的GenAI规划器/Omni-Channel在线状态/容量问题——这种残留情况属于Agentforce员工代理团队负责的代理运行时问题（请参考文档中的"加入后离开"部分）。

Prerequisites

前提条件

Teams ITSM feature enabled and the employee portal site live (run
```
service-itsm-teams-configure
```
and
```
experience-portal-create
```
first). You need the Employee Site URL (e.g.
```
https://<org>.my.site.com/empPortal
```
) and the org's My Domain URL.
A real, Active Agentforce Employee Agent exists (
```
SELECT Id FROM BotDefinition WHERE Type='InternalCopilot' AND AgentType='AgentforceEmployeeAgent'
```
, with an
```
Active
```
```
BotVersion
```
). If none exists, create it first — enabling the
```
service-cloud-it-service-employee-agent
```
Go feature may auto-provision it, but that is not guaranteed (verified: in one org the feature enabled but provisioned nothing). The reliable way to deploy it is service-itsm-agentic-setup-employee-agent-configure
(which reads the shipped Employee template's Agent Script and creates + publishes + activates the agent as an NGA-native bundle); the equivalent underlying path is the ITSM Connect agent-templates install + activate against
```
EmployeeCopilot__AgentforceEmployeeAgent
```
. Deploy the agent first, then run this skill to embed it in Teams. See the "Prerequisite: the IT Service Employee Agent must exist" section in the reference for both paths and their gotchas.

Teams ITSM功能已启用，且员工门户站点已上线（请先运行
```
service-itsm-teams-configure
```
和
```
experience-portal-create
```
）。你需要员工站点URL（例如
```
https://<org>.my.site.com/empPortal
```
）以及组织的My Domain URL。
存在一个真实、活跃的Agentforce员工代理（
```
SELECT Id FROM BotDefinition WHERE Type='InternalCopilot' AND AgentType='AgentforceEmployeeAgent'
```
，且拥有
```
Active
```
状态的
```
BotVersion
```
）。如果不存在，请先创建——启用
```
service-cloud-it-service-employee-agent
```
Go功能可能会自动预配，但这无法保证（已验证：在某个组织中，功能已启用但未预配任何内容）。可靠的部署方式是**
```
service-itsm-agentic-setup-employee-agent-configure
```
（它会读取已发布的员工模板的代理脚本，并以NGA原生包的形式创建、发布并激活代理）；等效的底层路径是ITSM Connect的agent-templates install + activate**，针对
```
EmployeeCopilot__AgentforceEmployeeAgent
```
。请先部署代理，再运行此技能将其嵌入Teams。有关两种路径及其注意事项，请参考文档中的"前提条件：IT服务员工代理必须存在"部分。

The causes of "agent joins then leaves" (read this before building)

"代理加入后离开"的原因（构建前请阅读）

The agent replies only when the whole chain is intact — missing a link produces the classic "agent joins the conversation, then leaves, no reply" symptom. All are fixable in this skill:

#	Requirement	Symptom if missing	Fix
1	Channel auth mode = Auth (User Verification ON) WITH a Key Set attached	`/unauthenticated/access-token` → `BAD_REQUEST` "Set the auth mode to false" (auth ON but no Key Set → client fell back to the unauthenticated endpoint); or 401 on `/eventrouter/v1/sse` (Key Set endpoint/issuer wrong)	Attach a `JWKS_URL` Key Set (endpoint `<Org>/id/keys` , issuer = Employee Site URL) and link it into the channel — do not turn auth off
2	Portal user has an Agent Access permission set enabling the IT Service Employee Agent	Tokens mint and SSE connects, but the agent joins then leaves with zero `ConversationEntry`	Create + assign a permission set with Agent Access → the agent
3	The `Teams_AgentForce` ESD exists + is published	`SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce'` → 0 rows; Teams can't load a missing deployment	Metadata-deploy the `API` -type ESD + Connect-publish it (step 3)

This reverses an earlier version of this skill that told you to turn User Verification OFF and never attach a Key Set. That was diagnosed on a build that flipped auth ON but forgot the Key Set, so the Teams client used the unauthenticated endpoint and hit "Set the auth mode to false." The verified, product-blessed fix is auth ON + a JWKS_URL Key Set (screenshot-confirmed live), which puts the client on the authenticated token flow the channel expects.

If the agent still won't reply after auth-ON + Key Set, Agent-Access-assigned, and the ESD created+published are all confirmed, delegate to
service-itsm-teams-debug
(its

AGENTFORCE

pass/fail checklist walks the full token/routing/ESD/agent chain) before escalating to the Agentforce Employee Agent team (agent Omni presence / capacity / GenAI planner) as the last resort. In the verified org, fixing the fixable causes above was sufficient.

只有当整个链路完整时，代理才会回复——缺少任何一个环节都会导致典型的"代理加入对话，然后离开，无回复"问题。所有这些问题都可以通过本技能修复：

#	要求	缺失时的症状	修复方法
1	渠道认证模式=Auth（启用用户验证）且已附加密钥集	`/unauthenticated/access-token` → `BAD_REQUEST` "Set the auth mode to false"（启用认证但无密钥集→客户端回退到未认证端点）；或 `/eventrouter/v1/sse` 返回401（密钥集端点/签发者错误）	附加 `JWKS_URL` 密钥集（端点 `<Org>/id/keys` ，签发者=员工站点URL）并将其链接到渠道——请勿关闭认证
2	门户用户拥有启用IT服务员工代理的Agent Access权限集	令牌生成成功且SSE连接，但代理加入后离开且无 `ConversationEntry`	创建并分配具有Agent Access权限的权限集给代理
3	`Teams_AgentForce` ESD已存在且已发布	`SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce'` → 0行；Teams无法加载缺失的部署	元数据部署 `API` 类型的ESD并通过Connect发布（步骤3）

本技能已修正早期版本的错误，早期版本曾要求关闭用户验证并从不附加密钥集。该错误是在启用认证但忘记添加密钥集的构建中发现的，导致Teams客户端使用未认证端点并触发"Set the auth mode to false"错误。经产品验证的正确修复方案是启用认证+JWKS_URL密钥集（已通过截图现场确认），这会让客户端使用渠道预期的已认证令牌流。

如果在确认启用认证+密钥集、已分配Agent Access权限、ESD已创建并发布后，代理仍然无法回复，请委托给
service-itsm-teams-debug
（其

AGENTFORCE

通过/失败检查表会遍历完整的令牌/路由/ESD/代理链路），最后再升级到Agentforce员工代理团队（代理Omni在线状态/容量/GenAI规划器）作为最后的手段。在已验证的组织中，修复上述可解决的问题后，代理即可正常回复。

Verified recipe (summary — 100% API, zero manual steps; full XML + calls in the reference)

已验证的方案（摘要——100% API，无手动步骤；完整XML和调用请参考文档）

Deploy in this order — Key Set first, then the channel that references it, then the ESD. All deploys use an isolated

sfdx-project.json

--api-version 67.0

. Run one step at a time.

Enhanced Chat User Verification Key Set — Metadata-deploy a
```
PublicKeyCertificateSet
```
with
```
<type>JWKS_URL</type>
```
,
```
<jwksEndPoint>
```
=
```
<Org_Url>/id/keys
```
,
```
<jwtIssuer>
```
= the Employee Site URL. Directory must be
```
PublicKeyCertificateSet/
```
, suffix
```
.PublicKeyCertificateSet-meta.xml
```
. (
```
JWKS_URL
```
is the endpoint-URL mode;
```
Jwks
```
is the uploaded-key mode and rejects a URL.)
Messaging channel, deployment type Web, domain = the Employee Site URL — Metadata-deploy a
```
MessagingChannel
```
(
```
messagingChannelType=EmbeddedMessaging
```
) whose
```
sessionHandlerFlow
```
= the routing flow that targets the IT Service Employee Agent and
```
sessionHandlerQueue
```
= the fallback queue (e.g.
```
chatqueue
```
). Turn User Verification ON and link the Key Set in one block:
```
<embeddedConfig><authMode>Auth</authMode><messagingAuthorizations>…publicKeyCertificateSetName…</messagingAuthorizations></embeddedConfig>
```
. Then activate the channel (
```
MessagingChannel.IsActive=true
```
) before publishing the ESD. The routing flow + fallback queue are prerequisites — if
```
Route_To_MIAW_AEA
```
was template-installed it ships with placeholder ids (repoint them); if none exists, author one. The
```
sfdc_livemessage
```
Omni service channel is standard/pre-existing (query, don't create). See the reference §A/§E/§F.
Create the
Teams_AgentForce
Embedded Service Deployment (ESD) — the deployment the Teams client loads by
```
esDeveloperName
```
. Metadata-deploy an API
-type ESD named exactly Teams_AgentForce
whose
```
<messagingChannel>
```
references the channel from step 2, then publish it via
```
POST /services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<esdId>
```
(
```
{}
```
→
```
isSuccess:true
```
; the publish route is v67.0). See reference §C/§D. If this ESD is missing, login works but the agent never replies — verify with
```
SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce'
```
(Tooling).
Create a permission set (e.g. "Agent Access") enabling the IT Service Employee Agent and assign it to the portal user (RBAC grant — confirm before assigning). See reference §G.
Retest from a brand-NEW Teams chat — existing sessions stay bound to the old deployment.

Do not use

POST /connect/service-itsm/createMessagingChannel

— it forces its own defaults; build the channel yourself so you control the flow/queue/dev-name and the exact auth + Key Set wiring. See the reference for the exact API bodies, object names, verification queries, and the full gotchas index.

请按以下顺序部署——先部署密钥集，再部署引用它的渠道，最后部署ESD。所有部署都使用

--api-version 67.0

的独立

sfdx-project.json

。请逐步执行每个步骤。

增强聊天用户验证密钥集——元数据部署
```
PublicKeyCertificateSet
```
，设置
```
<type>JWKS_URL</type>
```
，
```
<jwksEndPoint>
```
=
```
<Org_Url>/id/keys
```
，
```
<jwtIssuer>
```
= 员工站点URL。目录必须为
```
PublicKeyCertificateSet/
```
，后缀为
```
.PublicKeyCertificateSet-meta.xml
```
。（
```
JWKS_URL
```
是端点URL模式；
```
Jwks
```
是上传密钥模式，会拒绝URL。）
消息渠道，部署类型为Web，域=员工站点URL——元数据部署
```
MessagingChannel
```
（
```
messagingChannelType=EmbeddedMessaging
```
），其
```
sessionHandlerFlow
```
= 指向IT服务员工代理的路由流，
```
sessionHandlerQueue
```
= 备用队列（例如
```
chatqueue
```
）。在一个块中启用用户验证并链接密钥集：
```
<embeddedConfig><authMode>Auth</authMode><messagingAuthorizations>…publicKeyCertificateSetName…</messagingAuthorizations></embeddedConfig>
```
。然后在发布ESD之前激活渠道（
```
MessagingChannel.IsActive=true
```
）。路由流+备用队列是前提条件——如果
```
Route_To_MIAW_AEA
```
是通过模板安装的，它会附带占位符ID（请重新指向）；如果不存在，请自行创建。
```
sfdc_livemessage
```
Omni服务渠道是标准/预先存在的（请查询，不要创建）。请参考文档§A/§E/§F。
创建
Teams_AgentForce
嵌入式服务部署（ESD）——Teams客户端通过
```
esDeveloperName
```
加载的部署。元数据部署**
```
API
```
类型的ESD，名称精确为
```
Teams_AgentForce
```
，其
<messagingChannel>
引用步骤2中的渠道，然后通过
POST /services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<esdId>
发布（
{}
→
isSuccess:true
；发布路由为v67.0**）。请参考文档§C/§D。如果缺少此ESD，登录成功但代理永远不会回复——请通过
```
SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='Teams_AgentForce'
```
（Tooling）验证。
创建权限集（例如"Agent Access"），启用IT Service Employee Agent并分配给门户用户（RBAC授权——分配前请确认）。请参考文档§G。
从全新的Teams聊天重新测试——现有会话仍会绑定到旧部署。

请勿使用

POST /connect/service-itsm/createMessagingChannel

——它会强制使用自身默认设置；请自行构建渠道，以便你控制流/队列/开发名称以及精确的认证+密钥集配置。请参考文档获取精确的API请求体、对象名称、验证查询以及完整的注意事项索引。

Skill	When to use instead
`service-itsm-teams-configure`	Enabling the Teams feature Salesforce Go page toggle + Azure/Entra app + SSO/Named Credentials — run first; it delegates here for the embedded agent
`experience-portal-create`	Creating the employee-service portal/site whose URL this skill consumes
`service-itsm-teams-debug`	Diagnosing why an already-built agent won't reply (or other Teams ITSM failures) — runs the `AGENTFORCE` pass/fail checklist and reports remediation
`service-itsm-channels-coordinate`	Top-level menu across Teams, Slack, Swarming, Notifications, Portal

技能	替代使用场景
`service-itsm-teams-configure`	启用Teams功能的Salesforce Go页面开关 + Azure/Entra应用 + SSO/命名凭据——请先运行此技能；它会将嵌入式代理的配置委托给本技能
`experience-portal-create`	创建本技能所需的员工服务门户/站点
`service-itsm-teams-debug`	诊断已构建的代理无法回复的原因（或其他Teams ITSM故障）——运行 `AGENTFORCE` 通过/失败检查表并报告修复方案
`service-itsm-channels-coordinate`	Teams、Slack、Swarming、通知、门户的顶级菜单