service-agentforce-channel-configure

service-agentforce-channel-configure：将 Agentforce 代理接入渠道

在现有渠道和现有 Agentforce 代理之间添加入站路由。代理会接收来自该渠道的工作项；当代理不可用时，备用队列会处理溢出的工作项。

此技能通用，适用于任何 Agentforce 代理，而不仅限于 Help Agent 模板。

范围

包含：

• 解析或创建 QueueSobject SobjectType 正确的备用队列
• 分支 A（增强型聊天 / 增强型消息）：在现有 MessagingChannel 上部署 sessionHandlerType=AgentforceServiceAgent 和 sessionHandlerQueue，然后通过 Data API PATCH 绑定 SessionHandlerId
• 分支 B（语音）：假定电话号码和 PstnVoice MessagingChannel 已存在（由调用方预先配置，例如 service-helpagent-coordinate），然后创建入站 RoutingFlow（routingType: Copilot），将请求路由给代理，并将队列设为备用队列
• 分支 C（Email-to-Case）：通过直接分配案例所有者或 Omni-Channel RoutingFlow 配置入站路由；另外部署 BotEmailDefinition（Email Configuration），将代理关联到 Service Email，并将其绑定到路由地址
• 可选的出站升级：将已验证的代理到人工交接约定交由 service-agentforce-human-escalation-configure 处理

不包含：

• 创建代理——使用 agentforce-generate 或 service-helpagent-coordinate
• 创建 MessagingChannel——使用 service-digital-engagement-channel-configure
• 创建 Embedded Service Deployment——使用 service-digital-engagement-deployment-configure
• 创建语音或 Email-to-Case 渠道基础设施

---

必需输入

• 代理 DeveloperName 和代理标签（MasterLabel）——必须是现有且处于活动状态的代理
• 渠道类型——以下之一：增强型聊天、增强型消息（第三方）、语音、Email-to-Case
• 渠道标识符——MessagingChannel DeveloperName（分支 A），或渠道名称/上下文（分支 B/C）
• 目标组织别名

---

工作流

步骤按顺序执行。继续之前，先阅读 references/channel-types.md，确认路由分支。

阶段 0 — 生产环境写入保护（强制，在任何写入操作之前）

此技能会执行元数据/数据写入（编辑 MessagingChannel、部署 RoutingFlow、重新发布代理）。任何写入操作之前，都必须识别目标组织类型，并拒绝对真实生产环境进行操作：

sf data query --target-org $ORG --json \
  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1"

• 仅当 IsSandbox=true、或 TrialExpirationDate 非 null（试用版/CDO）、或 OrganizationType 为 Developer Edition / Base Edition 时，safe_to_write 才为 true。
• 如果 safe_to_write 为 false，立即停止——明确说明这是客户的真实生产组织，不会应用升级/渠道接入配置。不要进入任何写入阶段。
• 如果 safe_to_write 为 true，展示写入计划（将更改哪些 MessagingChannel/RoutingFlow/代理），并在继续之前征得用户对目标组织的明确确认。

绝不可绕过此检查——此处误写会导致实时客户流量被重新路由。

阶段 1 — 验证 Agent 并解析队列

1. 确认 Agent 存在且有一个活动版本：

   # Get the definition
   sf data query --target-org $ORG --json \
     --query "SELECT Id, DeveloperName, MasterLabel FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"
   
   # Check for an Active version
   sf data query --target-org $ORG --json \
     --query "SELECT Id, Status FROM BotVersion WHERE BotDefinitionId='{BOT_DEFINITION_ID}' AND Status='Active' LIMIT 1"
   

   如果找不到定义，或没有任何版本的 Status = Active，请停止并显示明确的消息。

   分支 A 注意事项 — Active BotVersion 是将 Agent 绑定为 sessionHandlerAsa 的必要条件，但并非充分条件。 平台只接受已配置/连接为可部署的 Agentforce Service Agent（通常是 ExternalCopilot）的 Agent。绑定仅处于 Active 状态的 Agent 会导致阶段 2 部署失败，并提示 Only active Agentforce Service Agents are supported for a Messaging Channel。写入前请以只读方式确认是否可绑定：如果该组织中已有任何 MessagingChannel 使用 sessionHandlerType=AgentforceServiceAgent，请检索该对象（sf project retrieve start --metadata "MessagingChannel:{EXISTING}" --target-org $ORG）并读取其 <sessionHandlerAsa> — 该集合就是该组织中可确证能绑定的 ASA。如果选定的 Agent 不是已配置的 ASA，且不存在可绑定的 ASA，请停止并报告 BLOCKED：请提供一个已配置为 Agentforce Service Agent 的 Agent。

2. 解析后备队列和路由配置 — 按照 references/queue-resolution.md 操作：

   • 根据渠道类型确定 SobjectType（参见 references/channel-types.md）
   • 查询现有兼容队列；通过 AskUserQuestion 呈现，或创建新队列
   • 查询是否已有 QueueRoutingConfig；如果没有，则使用正确的容量百分比创建一个
   • 记录 QUEUE_DEVELOPER_NAME、QUEUE_NAME 和 QUEUE_ID

---

阶段 2 — 配置入站路由

实时流量警告关卡（在任何分支执行前运行）

进行任何路由更改之前，请检测该渠道是否已有活动的入站路由（分支 A：SessionHandlerType 非空；分支 B/C：有任何活动的 RoutingFlow 分配给服务渠道）。如果有，先检查用户的提示是否已说明时间选择（“暂不切换”／“手动接线”／“先审核”→ 静默延期；“立即切换”／“立即激活”→ 静默继续）。仅当提示中未说明时，才通过 AskUserQuestion 发出警告，让用户选择 “立即重新路由” 或 “完成设置，然后手动接线” — 如果用户的回复含糊或未选择，则默认延期（绝不进行实时重新路由）。延期时，设置 DEFER_INBOUND_ROUTING=true，跳过所选分支中的渠道激活步骤，并在阶段 2 末尾打印手动接线说明。

如果该渠道没有现有路由，则完全跳过此关卡，直接继续。

完整的检测查询、准确的 AskUserQuestion 代码块、各分支的延期流程规则以及手动接线文案：references/live-traffic-gate.md。

分支 A — 增强型聊天 / 增强型消息（第三方）

无需 RoutingFlow。仅使用 sessionHandlerType + sessionHandlerQueue 部署 MessagingChannel，然后通过 Data API PATCH 绑定机器人。在 v67 中，Metadata API 不接受 sessionHandlerAsa — 部署时会静默丢弃该字段，除非运行 PATCH，否则 SessionHandlerId 会保持为 null。PATCH 之前，机器人必须处于 Active 状态（否则会提示“Only active Agentforce Service Agents are supported”）。

按顺序执行全部五个步骤。在当前 SFDX 项目中执行检索和编辑，以便部署从 force-app 读取编辑后的 .messagingChannel-meta.xml；不要使用临时目录。

1. 将当前 MessagingChannel 元数据检索到工作目录项目中：

   sf project retrieve start \
     --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
     --target-org $ORG
   

2. 就地编辑检索到的 .messagingChannel-meta.xml — 只设置以下两个字段（不要添加 <sessionHandlerAsa>）：

   <sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>
   <sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>
   

   使用文件编辑工具（Edit/Write）应用此编辑，使更改保存到工作目录中检索到的文件 force-app/main/default/messagingChannels/{CHANNEL_DEVELOPER_NAME}.messagingChannel-meta.xml — 不要通过内联 sed/cat heredoc 手动将其编辑到临时路径。步骤 3 中的部署必须读取这同一个磁盘文件。

3. 部署：

   sf project deploy start \
     --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
     --target-org $ORG
   

   如果部署失败，并提示 Only active Agentforce Service Agents are supported for a Messaging Channel，则此组织中的该 Agent 无法绑定（参见 Phase 1 注意事项）。不要使用同一个 Agent 重试 — 通道保持不变（失败的部署是原子操作）。报告 BLOCKED，并说明补救措施：绑定一个已配置为 Agentforce Service Agent 的 Agent，或为此 Agent 完成配置，然后重新运行。

4. 通过 Data API PATCH 绑定机器人：

   CHAN_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
   BOT_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
   QUEUE_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
   
   sf api request rest --method PATCH -o $ORG \
     "/services/data/v67.0/sobjects/MessagingChannel/${CHAN_ID}" \
     --body "{\"SessionHandlerId\":\"${BOT_ID}\",\"FallbackQueueId\":\"${QUEUE_ID}\"}"
   # Expected: HTTP 204
   

5. 验证：

   sf data query --target-org $ORG --json \
     --query "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id='${CHAN_ID}'"
   

   SessionHandlerId 和 FallbackQueueId 均不得为 null。

无需更改 Agent 文件 — 无需重新发布。继续执行 Phase 3（可选）。

---

分支 B — 语音

通过入站 Copilot RoutingFlow，将 PstnVoice MessagingChannel 接入，并将队列设为回退队列；重新发布 Agent 之前，还需添加必需的 modality voice: 块。

从头到尾遵循 references/channel-branch-voice.md。要点：

• 步骤 0 — 复用现有的 PstnVoice MessagingChannel，或先让 service-helpagent-coordinate 使用该技能的 Voice 通道参考配置一个通道；如果组织使用合作伙伴电话服务提供商，则中止（参见 references/channel-types.md）。
• 步骤 1–3 — 使用 references/routing-flow.md 中的模板编写并部署入站 RoutingFlow，确认 ActiveVersionId 非 null。
• 步骤 4 — 为 {CHANNEL_DEVELOPER_NAME} 部署一个 MessagingChannel 元数据文件，设置 sessionHandlerType=Flow、sessionHandlerFlow={FLOW_DEVELOPER_NAME}、sessionHandlerQueue={QUEUE_DEVELOPER_NAME}。否则不会执行该流程，通话会挂断。确认 SessionHandlerId 以 300 开头。
• 步骤 5 — 如果 .agent 文件中缺少平台默认的 modality voice: 块，则将其追加进去（voice_id UgBBYS2sOqTuMpoF3BR0，"Mark"，en_US）；不要询问用户。按照 references/agent-wiring.md 重新发布。

继续执行 Phase 3（可选）。

---

分支 C — 电子邮件转案例

让用户选择直接分配案例所有者，或使用 Omni-Channel Copilot RoutingFlow。此分支需要 API v68.0+、connection service_email: 接入方式以及 BotEmailDefinition。

请完整遵循 references/channel-branch-email.md。关键注意事项（完整操作指南见该文件）：

• 步骤 1 — 通过 Tooling-API PATCH 或 --metadata-dir Settings:Case 部署来绑定路由地址字段，绝不能使用源 --metadata Settings:Case 部署（它会读取 sourceApiVersion 并修改用户的项目）。
• 步骤 2 — 选择入站路由（AskUserQuestion）：案例所有者（caseOwner = Agent 的机器人用户）或 Omni-Channel 流（Copilot RoutingFlow + routingFlow/fallbackQueue）。无论选择哪种方式，都要解析机器人用户；路由字段应放入步骤 4d 的部署中。
• 步骤 3 — Agent 已处于活动状态，因此必须通过 停用 → 发布 → 激活 添加 connection service_email: 接入方式（直接发布会失败，并显示 couldn't find the default agent user）。如果需要升级处理，也在此处一并批量添加出站路由。
• 步骤 4 — BotEmailDefinition：预检保存时的关卡，验证回复模板，通过 --metadata-dir 部署，然后通过一次 Settings:Case 部署绑定路由地址（包括 botEmailDefinition + 步骤 2 的路由字段 + 必需的 casePriority）。如果失败则停止。

验证路由地址绑定后，分支 C 即完成。继续进入阶段 3。

---

阶段 3 — 出站升级处理（可选）

权威负责人： 完整的 Agent 到人工升级处理由 service-agentforce-human-escalation-configure 负责。这包括升级处理主题、规划器耦合、有人值守的人工队列、出站流、失败阈值指令、重新发布和确定性验证。

确认入站路由后，询问用户：

“入站路由已设置完成 — 该渠道会将请求路由到 [agent name]。你是否也想配置出站升级处理，以便 Agent 在收到请求时转交给人工处理？”

如果是，则委派给 service-agentforce-human-escalation-configure。将已解析的 Agent、 渠道类型、上下文对象和后备队列作为已知输入传递。不要在此处重复该技能的 写入或验证步骤。

规则 / 约束

规则	原因
进行任何更改前，验证 Agent 存在且处于 Active 状态	将渠道连接到不存在或非活动的 Agent 会导致运行时静默失败
如果渠道已有活跃的入站路由，请遵循提示词中明确的延后 / 切换意图，不要询问；否则通过 AskUserQuestion 发出警告，并在意图不明确时默认延后	重新路由会立即生效并影响实时流量——队列和 RoutingFlow 的创建始终继续；只有激活步骤需要经过确认，安全默认选项不会造成破坏
延后时，在 Phase 3 之前打印准确的手动连接说明	操作人员需要清楚知道准备好切换时要运行哪些命令
未先检索当前元数据时，绝不修改 MessagingChannel	未检索便覆盖会丢失现有设置
分支 A：不创建 RoutingFlow，也不重新发布 Agent；通过元数据部署 sessionHandlerType + sessionHandlerQueue，然后通过 Data API PATCH 设置 SessionHandlerId	v67 中 Metadata API 不接受 sessionHandlerAsa——部署会静默丢弃该字段，因此必须在部署后通过 Data API PATCH 绑定机器人。执行 PATCH 前，机器人必须处于 Active 状态
分支 B/C：始终创建新的 RoutingFlow，绝不复用现有组织级流程	开箱即用的平台流程通常有 ActiveVersionId: null，无法引用
分支 B/C：使用 routingType: Copilot 和 copilotLabel，不要使用 QueueBased	QueueBased 会直接路由到队列；Copilot 会先路由到 Agent，队列作为后备
必须查询 Queue Id 并将其写入 RoutingFlow XML	queueId 参数需要硬编码的 18 位记录 Id——不得留空
队列命名：{ChannelTypeLabel} Queue	按渠道类型命名，而非按 Agent 命名
出站升级为可选步骤——绝不因其阻碍入站路由完成	入站和出站彼此独立；无需完成出站步骤，入站连接便已完成
分支 C：通过 --metadata-dir 部署 BotEmailDefinition，绝不使用 --metadata BotEmailDefinition:<name>	它不在 CLI 的 SDR 注册表中，因此按名称指定类型的部署会失败；元数据格式部署可行
分支 C：不要将带有 ServiceCustomerVerification 主题的 Agent 连接到电子邮件	检测到后停止——不要自动移除（它可能是合法的多渠道 Agent 配置）。参见 channel-branch-email.md 第 4a 步

---

验证清单

队列

• 队列有一条 QueueSobject 记录，且 SobjectType 与渠道类型相符
• 运行用户是队列成员（如果是新建队列）
• 队列有正确 CapacityPercentage 的 QueueRoutingConfig（Chat / Voice / Email 分别为 50 / 100 / 25）

分支 A — MessagingChannel

• 部署后 SessionHandlerType = AgentforceServiceAgent
• Data API PATCH 前，机器人处于 Active 状态
• Data API PATCH 后，SessionHandlerId 非空（与机器人的 BotDefinition.Id 匹配，以 0Xx 开头）
• Data API PATCH 后，FallbackQueueId 非空（与解析出的队列 Id 匹配）

分支 B/C — RoutingFlow

• RoutingFlow 的 ActiveVersionId 非空
• 流程的 routeWork 操作中 routingType = Copilot
• copilotLabel 与 Agent 的确切 MasterLabel 匹配
• queueId 已填写（非空）

分支 C — 电子邮件路由地址

• 如果是新建：已创建 EmailRoutingAddress 记录，且 PersonalName 和 Address 正确
• 如果是新建：已为 CaseSettings 补丁设置 caseOrigin、saveEmailHeaders: true、addressType: EmailToCase
• 如果是新建：已告知用户验证邮件已发送到支持地址（不阻塞后续操作）

分支 C — BotEmailDefinition

• 预检通过：Agent 为 EinsteinServiceAgent，且其机器人用户具有 agentforceServiceAgentUser；活动版本包含 ServiceEmail 界面；电子邮件 Agent 上没有 ServiceCustomerVerification 主题
• 回复 EmailTemplate 为 SFX、HTML、公开，并包含 [[[GENERATED_CONTENT]]] + [[[LEGAL_DISCLOSURE]]]
• 无头路径（API ≥68）：通过 --metadata-dir 部署 BotEmailDefinition，且返回 success: true；legalDisclaimer/signature 至少为 10 个字符
• 将路由地址的 botEmailDefinition 子项设置为已部署组件的 fullName
• 在同一路由地址上设置入站路由：使用 caseOwner+caseOwnerType 或 routingFlow+fallbackQueue，并包含 casePriority

可选阶段 3 — 出站升级

• service-agentforce-human-escalation-configure 返回 CONFIGURED 或 ALREADY-CONFIGURED

---

参考文件索引

文件	阅读时机
references/channel-types.md	阶段 1 — 确定 SobjectType 和路由分支
references/queue-resolution.md	阶段 1 — 查询、创建队列并捕获 Id
references/live-traffic-gate.md	阶段 2 — 检测查询、延迟流规则，以及实时流量警告门控的手动接线副本
references/channel-branch-voice.md	分支 B — 完整的 Voice 入站接线：PstnVoice 通道选择、RoutingFlow、MessagingChannel 分配、modality voice: 重新发布
references/channel-branch-email.md	分支 C — 完整的 Email-to-Case 接线：API v68.0+ 前置条件门控、CaseSettings 标志、EmailRoutingAddress + 读取-修改-写入补丁、入站 RoutingFlow、必需的 connection service_email: 界面区块、无头 BotEmailDefinition 部署、路由地址绑定
references/botemaildefinition.md	分支 C 步骤 4 — BotEmailDefinition 字段、保存时的验证顺序、ASA 模板规则、--metadata-dir 部署步骤、ServiceEmail 界面前置条件、组合组织门控
references/routing-flow.md	分支 B/C — 入站 RoutingFlow XML 模板、部署、验证
references/agent-wiring.md	阶段 3（可选）— 出站升级 connection 区块
assets/BotEmailDefinition.botEmailDefinition-meta.xml	分支 C 步骤 4c — BotEmailDefinition 源文件的起始模板
assets/mdapi-package.xml	分支 C 步骤 4c — --metadata-dir 部署所用的元数据格式 package.xml
assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email + .email-meta.xml	分支 C 步骤 4b（备用方案）— 用户没有模板时使用的最简 ASA 兼容 SFX 回复模板
scripts/validate-botemaildefinition.py	分支 C 步骤 4c — 部署前验证 BotEmailDefinition 文件
scripts/validate-emailtemplate.py	分支 C 步骤 4b（备用方案）— 部署前验证 SFX 模板