service-agentforce-contact-center-coordinate

service-agentforce-contact-center-coordinate：设置 Agentforce Contact Center 语音通道

协调从已认证组织到启用实时呼入语音通道的完整流程：申请电话号码、确认号码已配置，并创建处于活动状态的 PstnVoice MessagingChannel。用户选择路由模式——Omni Queue（将呼叫直接路由到 Agentforce Contact Center 队列）或 Omni Flow（通过呼入路由流将呼叫路由给 Agentforce Agent，并以队列作为后备）。Omni Queue 路径仅协调 Number Management 和 MessagingChannel REST API。Omni Flow 路径还可以编写、发布并激活 Agentforce Agent，并在连接通道之前部署其呼入（Copilot）和升级（QueueBased）RoutingFlow 流。

范围

• 范围内：获取可用号码、申请号码、解析其 CommunicationChannelLine、验证／协调实时状态、选择路由模式、创建并激活 PstnVoice MessagingChannel（队列路由或流路由）；对于 Omni Flow 路径，还包括编写／发布／激活 Agentforce Agent，以及部署其呼入和升级 RoutingFlow 流。最后提供设置摘要。
• 范围外：对组织进行认证或配置（目标组织必须已经过认证）、启用 Agentforce／Einstein Service Agent 开关（这是由操作员切换的组织偏好设置——参见 references/agentforce-prerequisite.md）、配置出站／语音调优，或将现有通道连接到 Agent，以及创建非语音通道。

---

前置条件

• 已认证的组织——所有路径都必需（此技能不会运行交互式登录）。
• 仅适用于 Omni Flow 路径——组织必须启用 Einstein 和 Agentforce Agents。 语音通道要路由到 Agentforce Agent，组织管理员必须先在 Setup UI 中启用 Einstein（Setup → Einstein Setup），然后启用 Agentforce Agents（Setup → Einstein → Agentforce / Agents）。随后，技能会解析或配置规范的 Einstein Agent User（Profile.Name = 'Einstein Agent User'），Agent 编写和发布均依赖此用户。不要使用用户名／配置文件仅仅包含 Agent 或 Bot 的通用用户；这些用户可能可以生成／验证，但发布会失败。Omni Queue 路径没有此类前置条件。完整步骤：references/agentforce-prerequisite.md。

---

必需输入

继续之前，请收集或确认以下信息：

• 目标组织：已认证的组织。如果用户指定了别名，请使用该别名。如果用户指的是其默认组织（或未提供别名），请使用 sf org display --json 解析，并读取 result.alias（如果没有则使用 result.username）；对每个脚本都将该值作为 <alias> 使用。不要运行交互式登录。
• 国家／地区：US 或 CA。
• 电话号码类型：10DLC 或 Toll Free。
• 所选号码：用户从获取的号码列表中选定的号码。
• 路由模式：Omni Queue（默认）或 Omni Flow。在步骤 7 中询问。
• （仅限 Omni Flow）Agent 来源：创建新的 Agentforce Agent 和路由流，或复用现有的已发布 Agent 及其呼入路由流。
• （仅限 Omni Flow，仅适用于新建 Agent）Agent 业务背景：Agent 名称、Agent 描述（Agent 的角色／用途）和公司名称——传递给 sf agent generate agent-spec。Agent 名称用作 <label>，并据此生成 <apiName>（步骤 9 子步骤 3 中的规范化与唯一性规则）；不要询问角色、网站或 API 名称。

如果组织尚未认证，或未选择国家／地区和电话号码类型，则不要继续。只有在选择了相应路径后，才收集路由模式及任何 Omni Flow 输入。

---

工作流

所有步骤都按顺序执行。如果某一步失败，请停止并报告错误，不要继续。

1. 确认组织连接——运行 sf org display --target-org <alias> --json 并读取 result.instanceUrl。如果失败，请先让用户对组织进行身份验证，然后停止。不要在此技能中运行交互式登录。

2. 收集配置——使用 AskUserQuestion 收集 Country（US/CA）和 Phone Number Type（10DLC/Toll Free）。不要将任何选项标记为推荐或默认；中立地呈现这些选项。等待用户提供两项信息后再继续。

3. 获取可用号码——阅读 references/number_management_api.md 了解端点约定。获取号码前，使用 AskUserQuestion 提供一种可选的结果筛选方式：询问用户是否要查找特定区号的号码（类型为 10DLC 时）或特定前缀的号码（类型为 Toll Free 时），或者列出所有可用号码。中立地呈现选项，不设推荐项或默认项；留空（或选择列出所有号码）会保留未筛选的获取方式。然后运行 scripts/fetch-numbers.sh <alias> <country> <phoneType> [searchParam]；只有在用户提供了区号/前缀时，才将其作为可选的第四个参数传入。将返回的号码以编号列表呈现，并让用户选择一个——不要将任何号码标记为推荐或默认。如果筛选后未返回任何号码，请告知用户，并提供使用其他区号/前缀重试或列出所有可用号码的选项。

4. 申请所选号码——运行 scripts/procure-number.sh <alias> <country> <phoneType> <number>。如果响应状态不是 2xx，根据 references/number_management_api.md 映射状态，并停止操作，同时给出清晰说明。

5. 解析 ChannelLine——运行 scripts/resolve-channel-line.sh <alias> <number>。该脚本按 Code 查询 CommunicationChannelLine，并在结果为空时重试。记录 ChannelLine 的 Id 和 CodeStatus。

6. 验证号码是否已启用——运行 scripts/verify-number-live.sh <alias> <number>。该脚本通过 Tooling API 检查 CodeStatus；如果号码尚未启用，则调用 numberStateReconcile，并按照 references/verification_and_errors.md 中的策略轮询。根据退出码分支处理：退出码 3（轮询后仍未达到 Live）→ 提示警告，并询问用户是等待还是继续；退出码 4（numberStateReconcile 返回非 2xx）→ 按照非 2xx 时停止的规则停止并报告——协调失败时不要创建 channel。

7. 选择路由模型——使用 AskUserQuestion 询问呼叫应如何路由，然后在步骤 9 中进行分支处理：

   • Omni Queue（默认）——直接路由到 Agentforce Contact Center 队列。
   • Omni Flow——通过入站路由 flow 将呼叫路由到 Agentforce agent，并以队列作为备用。

8. 解析 Contact Center 队列——运行 scripts/resolve-acc-queue.sh <alias>，查找 Agentforce Contact Center 默认队列的 Id。切勿硬编码队列 Id——它因组织而异。两种模型都需要该 Id：Omni Queue 将其用作 channel 的 SessionHandlerId；Omni Flow 将其用作 FallbackQueueId 和升级 flow 的目标。

9. 创建启用状态的语音 channel——阅读 references/messaging_channel.md，然后按照所选路由模型的分支操作。

   Omni Queue——运行 scripts/create-voice-channel.sh <alias> <number> <channelLineId> <queueId>。此操作会 POST 一个 PstnVoice MessagingChannel，其中 SessionHandlerId 设为队列，ChannelLineId 设为已解析的 CommunicationChannelLine Id，并将 IsActive: true。按照该参考文档中的说明处理字段错误和状态错误。 Omni Flow — 阅读 references/omni-flow-routing.md，然后：

   1. 前置条件检查 — 运行 scripts/check-agentforce-prereq.sh <alias>（参见 references/agentforce-prerequisite.md）。退出码为 0 → 记录输出的规范 Einstein Agent User，供 --agent-user 使用；该脚本会复用现有的 Einstein Agent User，或使用 sf org create agent-user 配置一个。退出码为 3 → 找不到或无法配置规范用户，通常是因为开关已关闭，或没有可用的 Agentforce Service Agent User 许可证；提示用户修复组织后重试。如果用户允许仅使用队列作为回退方案，则使用上方的 Omni Queue 创建流程，并在报告中注明该回退方案。
   2. 新建或使用现有 Agent — 使用 AskUserQuestion：
      • 使用现有 Agent — 询问已发布 Agent 的 API 名称/标签及其入站 RoutingFlow DeveloperName，然后运行 scripts/resolve-flow-definition.sh <alias> <flowDeveloperName>，获取入站 FlowDefinition Id（300…）。resolve-flow-definition.sh 只验证该 flow 是否有活动版本，不会验证 Agent 是否已发布且处于 Active 状态——继续前，确认 Agent 最新版本的 BotVersion.Status = 'Active'（SELECT Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<apiName>' ORDER BY VersionNumber DESC LIMIT 1），或者告知用户此项由其负责；否则会创建渠道，但呼叫无法路由。继续执行子步骤 5。
      • 新建 — 继续执行子步骤 3。
   3. 编写 Agent — 通过 AskUserQuestion 收集 Agent 的业务背景信息：仅询问 Agent 名称、Agent 描述（Agent 的角色/用途——这将成为规范中的 --role）和公司名称（不要询问角色、网站或 API 名称）。将 Agent 名称用作 <label>。根据 Agent 名称推导 <apiName>（它将成为 BotDefinition.DeveloperName 和路由流程名称的基础）：将各词转换为 PascalCase，只保留字母和数字，以字母开头（必要时添加前缀 A），最长 60 个字符。通过 sf data query --query "SELECT DeveloperName FROM BotDefinition WHERE DeveloperName = '<apiName>'" --target-org <alias> 确认名称唯一；如有冲突，追加数字后缀。首先使用 scripts/prepare-agent-workdir.sh acc-voice-build 准备 SFDX 工作目录；sf agent generate agent-spec 要求在运行编写捆绑包的脚本之前先准备好项目上下文。在 acc-voice-build 中生成规范：sf agent generate agent-spec --type customer --tone neutral --max-topics 5 --agent-user <einsteinAgentUser> --role "<agent description>" --company-name "<company name>" --output-file specs/<apiName>.yaml --target-org <alias> --json。然后，从父级/原始工作目录运行 scripts/create-voice-agent.sh <alias> <apiName> <label> acc-voice-build/specs/<apiName>.yaml acc-voice-build；该脚本会生成编写捆绑包、修复生成的 default_agent_user、部署 AiAuthoringBundle、验证、发布并激活 Agent。不要将 planner 切换为 Atlas__VoiceAgent — 保持发布时生成的 Atlas__ConcurrentMultiAgentOrchestration（偏离说明见 references/omni-flow-routing.md）。
   4. 部署路由流程 — 运行 scripts/create-routing-flows.sh <alias> <apiName> <label> <queueId> <queueName> acc-voice-build。该脚本会在已准备好的 SFDX 工作目录中渲染并部署入站（<apiName>_Voice_Omni_Flow、Copilot）和升级（<apiName>_Voice_Escalation、QueueBased）流程，然后在标准输出中打印入站 FlowDefinition Id（300…）——请记录该值。与子步骤 3 复用同一个 acc-voice-build 工作目录。
   5. 创建渠道 — 运行 scripts/create-voice-channel.sh <alias> <number> <channelLineId> <flowDefinitionId> <queueId>。第 5 个参数会将 POST 请求切换为 Omni Flow：SessionHandlerId = 入站 FlowDefinition Id，FallbackQueueId = 队列。

10. 确认设置并撰写报告 — 读取已创建的 MessagingChannel。然后严格按照 assets/report-template.md 中的结构撰写报告：每个字段都填写本次运行实际生成的值（组织别名、国家/地区、电话号码类型、路由模型、实际运行的命令、采购的号码、解析得到的 CommunicationChannelLine Id 和状态、按名称解析的队列及其 Id，以及已创建的 PstnVoice MessagingChannel Id、DeveloperName、ChannelLineId、IsActive、SessionHandlerId 和 FallbackQueueId；对于 Omni Flow，还要填写 Agent 的 api-name/label 和入站 FlowDefinition Id），并以单行 Outcome 结尾。只有选择了 Omni Flow 路径时才包含 Omni Flow 对应行。每项占一行，不要添加额外说明，也不要遗漏适用字段。如果某个步骤失败，仍须填写已完成步骤对应的字段，并在 Outcome 中说明确切错误及失败步骤。

---

规则 / 约束

约束	原因
切勿运行交互式登录；要求使用已预先认证的组织别名	认证和组织生命周期不在范围内；使技能可在不同环境中移植
通过 sf api request rest 调用 API；切勿提取访问令牌	使用 CLI 为 --target-org 保存的会话 — 不处理原始令牌
切勿硬编码队列 Id / SessionHandlerId / FlowDefinition Id	这些值因组织而异；务必解析（第 8 步解析队列，通过 resolve-flow-definition.sh 解析 Flow）
通过 SessionHandlerId（Omni Flow 还需设置 FallbackQueueId）关联路由，而不是 TargetQueueId 或 RoutingType	Omni Queue：SessionHandlerId = 队列 Id。Omni Flow：SessionHandlerId = 入站 FlowDefinition Id（300…），FallbackQueueId = 队列 Id
Omni Flow：创建渠道前，先发布并激活 Agent，并部署入站 Flow（Active，300 前缀）	渠道的 SessionHandlerId 指向一个已启用的入站 FlowDefinition，该 Flow 引用了已发布且激活的 Agent
不要将 Agent 的 plannerType 切换为 Atlas__VoiceAgent	此组织会以不明确的错误拒绝；保留由发布操作生成的 Atlas__ConcurrentMultiAgentOrchestration — 语音仍通过 Copilot Flow 路由（偏差）
如果不满足 Agentforce 前置条件，或创建 Agent/Flow 失败，请停止并报告，除非用户明确接受 Omni Queue 备用方案	某些运行需要新建 Agentforce Agent 和 Omni Flow 渠道；不要擅自降级路由模型
使用 ChannelLineId（而非标量字段 ChannelLine）关联 CommunicationChannelLine	ChannelLine 是关系名称；创建时可写入的字段是 ChannelLineId
MessageType 必须为 PstnVoice，且 IsActive: true	激活入站语音渠道所必需
不要在 PstnVoice 渠道上设置 IsoCountryCode	此渠道类型不支持该字段
遇到任何非 2xx API 响应时，停止并报告	静默留下未完成的设置比明确报告失败更糟

---

注意事项

问题	解决方法
采购后未立即找到 ChannelLine	记录会异步传播 — 使用退避策略重试（Step 5 脚本会处理此问题）
Number CodeStatus 不是 Live	调用 numberStateReconcile 并轮询（Step 6 脚本）；如果状态一直处于 provisioning，请发出警告
创建渠道时出现 INVALID_FIELD: The value provided for foreign key reference ChannelLine is not a nested SObject	关系名称 ChannelLine 被作为标量字段发送 — 将 Id 发送到 ChannelLineId
FIELD_INTEGRITY_EXCEPTION 阻止使用非 live 状态的号码	如果启用了验证，这是预期行为 — 等待号码变为 live 状态，然后重试
DeveloperName 重复	存在同名渠道 — 生成唯一名称或重复使用现有渠道
phoneNumberType 中包含空格（Toll Free）	构建查询字符串时进行 URL 编码（脚本会处理此问题）
sf agent generate agent-spec 失败并报 RequiresProjectError	运行 scripts/prepare-agent-workdir.sh acc-voice-build，然后在 acc-voice-build 目录中调用 sf agent generate agent-spec，并使用 --output-file specs/<apiName>.yaml
sf agent publish 显示 default agent user NEW AGENT USER	生成器在 .agent 文件中留下了占位符 — create-voice-agent.sh 会在部署/发布前根据规范中的 agentUser 修补 default_agent_user
sf agent publish 显示 Unable to access the Salesforce Agent APIs 或 User doesn't have access to use agent	通常是因为规范/包使用了通用 Agent/Bot 配置文件用户。运行 scripts/check-agentforce-prereq.sh；它必须返回一个配置文件恰好为 Einstein Agent User 的用户
发布/验证 Agent 时出现不明确的服务器错误（例如 -1103525358）	由设置 plannerType: Atlas__VoiceAgent 导致 — 移除此设置并保留 Atlas__ConcurrentMultiAgentOrchestration（偏差；create-voice-agent.sh 不会触碰 planner）
路由流部署失败并报 does not contain a valid Salesforce DX project	使用同一个准备好的 acc-voice-build 工作目录；create-routing-flows.sh 现在会在该目录中运行 sf project deploy start
sf agent generate agent-spec / 发布因许可问题或 "default agent user" 而失败	Agentforce 开关已关闭，或没有可用的 Agentforce Service Agent User 许可证。启用开关或释放/配置许可证（references/agentforce-prerequisite.md）
使用 Flow Id（301…）作为 SessionHandlerId	使用了错误的句柄 — SessionHandlerId 需要稳定的 FlowDefinition Id（300…）；resolve-flow-definition.sh 会返回该 Id
入站流已部署，但渠道无法将流量路由到 Agent	必须激活 Agent，而不只是发布；入站流也必须有一个有效版本 — create-voice-agent.sh 会验证 BotVersion 是否为 Active；如果没有有效版本，resolve-flow-definition.sh 会以 3 退出

---

输出预期

此技能主要在目标 org 中创建记录：

• 一个已采购的电话号码（Number Management）。
• 一个已激活的 PstnVoice MessagingChannel — 将其路由到联系中心队列（Omni Queue），或通过入站路由流路由到 Agentforce Agent，并将队列设为备用路由（Omni Flow）。
• 仅适用于 Omni Flow：一个已发布并激活的 Agentforce Agent，以及两个 RoutingFlow 流（入站 Copilot + 升级 QueueBased）。
• 按照 assets/report-template.md 编写的报告，以及最终摘要表（references/setup_summary.md）。

Omni Flow 路径还会在 acc-voice-build/ 下搭建一个临时 SFDX 项目（规范、创作包、流元数据）来运行部署 — 这些是本地构建产物，不属于技能输出。

---

跨技能集成

Omni Flow 路径会自行接入入站语音（Agent → 入站 Copilot 流程 → 渠道，外加一个升级流程），因此不会将这项配置工作交由单独的渠道配置技能处理。超出本技能生成的语音服务 Agent 范围的深入 Agent 编写工作（自定义主题、操作、知识）不在本技能范围内。

---

参考文件索引

文件	阅读时机
references/number_management_api.md	步骤 3–4 — Number Management 端点、参数和状态码映射
references/verification_and_errors.md	步骤 6 — 实时验证轮询策略和错误处理
references/messaging_channel.md	步骤 9 — MessagingChannel 字段约定（两种路由模型）和创建时的错误处理
references/omni-flow-routing.md	步骤 9（Omni Flow）— 路由模型约定、Agent→流程→渠道接入顺序、新建与已有的分支、规划器偏差、回退规则
references/agentforce-prerequisite.md	步骤 9（Omni Flow）— Agentforce 开关前置条件、预检和 Omni-Queue 回退
references/setup_summary.md	步骤 10 — 面向用户的摘要表和后续步骤
assets/report-template.md	步骤 10 — 编写 report.md 的确切结构
assets/omni-flow.flow-meta.xml	步骤 9（Omni Flow）— 入站 Copilot RoutingFlow 模板（由 create-routing-flows.sh 渲染）
assets/escalation-flow.flow-meta.xml	步骤 9（Omni Flow）— 升级 QueueBased RoutingFlow 模板（由 create-routing-flows.sh 渲染）
scripts/prepare-agent-workdir.sh	步骤 9（Omni Flow）— 在生成 Agent 规范前准备所需的 SFDX 项目上下文
scripts/fetch-numbers.sh	步骤 3 — 获取可用的默认号码
scripts/procure-number.sh	步骤 4 — 采购所选号码
scripts/resolve-channel-line.sh	步骤 5 — 重试并解析 CommunicationChannelLine
scripts/verify-number-live.sh	步骤 6 — 验证／协调实时状态
scripts/resolve-acc-queue.sh	步骤 8 — 解析 ACC 默认队列 Id
scripts/create-voice-channel.sh	步骤 9 — 创建启用的 PstnVoice 渠道（4 个参数用于 Omni Queue／5 个参数用于 Omni Flow）
scripts/check-agentforce-prereq.sh	步骤 9（Omni Flow）— 前置条件检查；解析 --agent-user 所需的 Einstein Agent 用户
scripts/create-voice-agent.sh	步骤 9（Omni Flow）— 生成／验证／发布／激活 Agentforce 语音 Agent
scripts/create-routing-flows.sh	步骤 9（Omni Flow）— 部署入站和升级流程；打印入站 FlowDefinition Id
scripts/resolve-flow-definition.sh	步骤 9（Omni Flow）— 解析入站流程的 FlowDefinition Id（300…），包括复用已有流程