service-agentforce-human-escalation-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure Agentforce Agent → Human Escalation

配置Agentforce智能体→人工升级流程

Wire an Agentforce agent so it can hand a conversation off to a human agent through an Omni-Channel queue. This skill configures and verifies the escalation surfaces, then reports a single machine-readable JSON verdict. It is idempotent per developer name and refuses to write to production orgs. It runs standalone or as a stage in a larger setup flow (after the agent is created and active).

The agent, queue, outbound flow name, routed context object, service channel, and failure thresholds are all inputs, so the same skill serves any scenario (IT employee support, customer messaging, etc.) — the caller supplies the scenario-specific identifiers.

This skill is the authoritative owner of agent-to-human (outbound) escalation.

service-agentforce-channel-configure

may wire a basic outbound flow +

connection

block in the same pass as inbound channel setup, but it delegates full escalation configuration and verification here.

配置Agentforce智能体，使其能够通过Omni-Channel队列将对话转接给人工坐席。本技能会配置并验证升级相关组件，然后输出一份机器可读的JSON判定结果。它针对开发者名称具备幂等性，且拒绝写入生产环境组织。可独立运行，也可作为更大规模设置流程中的一个阶段（需在智能体创建并激活后执行）。

智能体、队列、出站流名称、路由上下文对象、服务渠道以及故障阈值均为输入项，因此同一技能可适用于任意场景（如IT员工支持、客户消息沟通等）——调用方只需提供场景特定的标识符即可。

本技能是智能体到人工（出站）升级流程的权威管理工具。

service-agentforce-channel-configure

可能会在配置入站渠道的同时，配置基础出站流+

connection

模块，但完整的升级配置与验证工作均由本技能负责。

The honest boundary — what is deterministic vs. directive vs. runtime

明确边界——确定性配置、指令性规则与运行时操作的区别

Escalation in Agentforce is assembled from surfaces with different verifiability:

Deterministic (this skill writes and/or round-trip verifies via the Metadata/Data API):
```
canEscalate=true
```
on the escalation topic (
```
GenAiPlugin
```
);
```
outboundRouteConfigs
```
on the agent's Messaging planner surface (
```
GenAiPlannerBundle
```
), where the SAME block couples
```
outboundRouteName
```
to
```
outboundRouteType=OmniChannelFlow
```
on a Messaging-class surface; a QueueBased outbound
```
RoutingFlow
```
with a non-null
```
ActiveVersionId
```
; a human queue with a
```
QueueSobject
```
for the context object, its
```
QueueRoutingConfig
```
bound to the queue, and at least one active human member (a queue with zero members can never route an escalation to a human, so it never reaches
```
CONFIGURED
```
); and the agent Active after republish.
Directive / native policy (authored as Agent Script instructions, not a metadata counter): the default two consecutive failures threshold plus per-topic overrides (e.g. password reset = one failure). There is no metadata field that counts failed turns — the threshold is instruction text, verified by an ADK eval rubric, not a runtime read. See references/failure-policy.md.
Runtime / manual only: the actual conversational trigger,
```
AgentWork
```
creation, and same-session context preservation. These cannot be driven headlessly — they are a documented manual test + eval rubric. See references/runtime-verification.md.

Agentforce中的升级流程由不同可验证性的组件构成：

确定性配置（本技能通过Metadata/Data API写入和/或往返验证）：升级主题（
```
GenAiPlugin
```
）上的
```
canEscalate=true
```
；智能体消息规划器组件（
```
GenAiPlannerBundle
```
）上的
```
outboundRouteConfigs
```
，其中同一模块需在消息类组件上将
```
outboundRouteName
```
与
```
outboundRouteType=OmniChannelFlow
```
关联；带有非空
```
ActiveVersionId
```
的基于队列的出站
```
RoutingFlow
```
；包含上下文对象对应的
```
QueueSobject
```
、绑定到队列的
```
QueueRoutingConfig
```
且至少有一名活跃人工成员的人工队列（成员数为0的队列永远无法将升级请求路由给人工，因此永远无法达到
```
CONFIGURED
```
状态）；重新发布后处于激活状态的智能体。
指令性/原生规则（以Agent Script指令形式编写，非元数据计数器）：默认的连续两次失败阈值，以及针对特定主题的覆盖规则（例如密码重置=一次失败）。不存在统计失败轮次的元数字段——阈值为指令文本，由ADK评估规则验证，而非运行时读取。详情请参阅references/failure-policy.md。
运行时/仅手动操作：实际对话触发、
```
AgentWork
```
创建以及同会话上下文保留。这些无法通过无头模式实现——需通过文档化的手动测试+评估规则完成。详情请参阅references/runtime-verification.md。

Authoring models — classic vs next-gen (NGA)

创作模型——经典版与下一代版（NGA）

Salesforce exposes two Agentforce authoring models, and Phase 1b auto-detects which the org supports from its metadata types. The routing infrastructure (queue,

QueueSobject

, members,

QueueRoutingConfig

, outbound

RoutingFlow

) is identical in both; only the agent-side escalation surface differs.

classic — org exposes
```
GenAiPlugin
```
+
```
GenAiPlannerBundle
```
. The agent surface is
```
canEscalate
```
(topic) +
```
outboundRouteConfigs
```
(planner Messaging surface). This surface is authored in Phase 4 (hand-edited, or via the optional
```
AUTHOR_SURFACES=1
```
pass) and round-trip verified in Phase 7.
nga — org exposes
```
AiAuthoringBundle
```
(Agent Script) and no
```
GenAiPlannerBundle
```
. There is no
```
outboundRouteConfigs
```
metadata; the agent surface is a reachable
```
@utils.escalate
```
action (Service agents) or a create-record action (Employee agents, which cannot use
```
@utils.escalate
```
), and the queue routing is carried entirely by the deterministic routing half. This skill verifies that surface from the retrieved bundle and delegates its authoring to
```
agentforce-generate
```
.
none — neither surface is exposed → the skill fails closed before any write.

Detection can be pinned with

AUTHORING_MODEL_OVERRIDE=classic|nga

when both coexist. Full rules, the Service-vs-Employee split, and the NGA verdict set live in references/nga-escalation.md.

Salesforce提供两种Agentforce创作模型，Phase 1b会根据组织的元数据类型自动检测其支持的模型。路由基础设施（队列、

QueueSobject

、成员、

QueueRoutingConfig

、出站

RoutingFlow

）在两种模型中完全相同；仅智能体端的升级组件存在差异。

经典版——组织支持
```
GenAiPlugin
```
+
```
GenAiPlannerBundle
```
。智能体组件为
```
canEscalate
```
（主题）+
```
outboundRouteConfigs
```
（规划器消息组件）。该组件在Phase 4中创作（手动编辑或通过可选的
```
AUTHOR_SURFACES=1
```
执行），并在Phase 7中进行往返验证。
NGA版——组织支持
```
AiAuthoringBundle
```
（Agent Script）且不支持
```
GenAiPlannerBundle
```
。不存在
```
outboundRouteConfigs
```
元数据；智能体组件为可访问的
```
@utils.escalate
```
操作（服务类智能体）或创建记录操作（员工类智能体，无法使用
```
@utils.escalate
```
），队列路由完全由确定性配置部分负责。本技能会验证从检索到的组件中提取的该模块，并将其创作工作委托给
```
agentforce-generate
```
。
无支持——两种组件均不支持→技能在执行任何写入操作前直接失败。

当两种模型共存时，可通过

AUTHORING_MODEL_OVERRIDE=classic|nga

固定检测结果。完整规则、服务类与员工类智能体的区别以及NGA判定集请参阅references/nga-escalation.md。

Scope

范围

In scope: enabling the escalation topic (
```
canEscalate
```
); wiring
```
outboundRouteConfigs
```
on the
```
GenAiPlannerBundle
```
Messaging surface; deploying the bundled QueueBased outbound
```
RoutingFlow
```
; create-or-adopt of the human queue (
```
QueueSobject
```
for the context object) and its
```
QueueRoutingConfig
```
; authoring the failure-threshold directives; republish + reactivate; and a deterministic config round-trip verdict. Idempotent re-run.
Out of scope: creating/activating the agent; inbound channel transport (
```
sessionHandlerAsa
```
on the
```
MessagingChannel
```
) and the agent's outbound
```
connection
```
block (owned by
```
service-agentforce-channel-configure
```
); provisioning the messaging channel itself (
```
service-digital-engagement-channel-configure
```
); broader Omni-Channel routing infrastructure; standalone queue provisioning outside an escalation context; and any production-org write.

包含范围：启用升级主题（
```
canEscalate
```
）；在
```
GenAiPlannerBundle
```
消息组件上配置
```
outboundRouteConfigs
```
；部署捆绑的基于队列的出站
```
RoutingFlow
```
；创建或适配人工队列（上下文对象对应的
```
QueueSobject
```
）及其
```
QueueRoutingConfig
```
；编写故障阈值指令；重新发布+重新激活；输出确定性配置的往返判定结果；支持幂等性重运行。
排除范围：创建/激活智能体；入站渠道传输（
```
MessagingChannel
```
上的
```
sessionHandlerAsa
```
）以及智能体的出站
```
connection
```
模块（由
```
service-agentforce-channel-configure
```
负责）；配置消息渠道本身（
```
service-digital-engagement-channel-configure
```
）；更广泛的Omni-Channel路由基础设施；升级上下文之外的独立队列配置；写入生产环境组织。

Inputs

输入项

Input	Positional	Env	Default
Org alias	1 (required)	—	—
Agent developer name	2	`AGENT_DEVELOPER_NAME`	`Support_Agent`
Queue developer name	3	`QUEUE_DEVELOPER_NAME`	`Human_Support_Queue`
Escalation topic API name	4	`ESCALATION_TOPIC_API_NAME`	(unset — surface unverified)
Planner bundle API name	5	`PLANNER_BUNDLE_API_NAME`	(unset — surface unverified)
Outbound flow developer name	—	`FLOW_DEVELOPER_NAME`	`Human_Escalation_Outbound_Flow`
Outbound flow label	—	`FLOW_LABEL`	flow name with `_` → space
Context object (routed sObject)	—	`CONTEXT_OBJECT`	`MessagingSession`
Service channel dev name / label	—	`SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL`	`sfdc_livemessage` / `Messaging`
Human members to add if empty	—	`QUEUE_MEMBER_USERNAMES`	(unset)
Failure threshold (consecutive failed attempts before hand-off)	—	`DEFAULT_FAILURE_THRESHOLD`	`2`
Threshold directive authored (out-of-band flag)	—	`THRESHOLD_AUTHORED`	`0`

For a non-

MessagingSession

context object (e.g.

Case

VoiceCall

), pass the matching

SERVICE_CHANNEL_DEV_NAME

SERVICE_CHANNEL_LABEL

输入项	位置参数	环境变量	默认值
组织别名	1（必填）	—	—
智能体开发者名称	2	`AGENT_DEVELOPER_NAME`	`Support_Agent`
队列开发者名称	3	`QUEUE_DEVELOPER_NAME`	`Human_Support_Queue`
升级主题API名称	4	`ESCALATION_TOPIC_API_NAME`	（未设置——组件未验证）
规划器组件API名称	5	`PLANNER_BUNDLE_API_NAME`	（未设置——组件未验证）
出站流开发者名称	—	`FLOW_DEVELOPER_NAME`	`Human_Escalation_Outbound_Flow`
出站流标签	—	`FLOW_LABEL`	流名称中的 `_` 替换为空格
上下文对象（路由对象）	—	`CONTEXT_OBJECT`	`MessagingSession`
服务渠道开发者名称/标签	—	`SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL`	`sfdc_livemessage` / `Messaging`
队列为空时添加的人工成员	—	`QUEUE_MEMBER_USERNAMES`	（未设置）
故障阈值（转接前连续失败次数）	—	`DEFAULT_FAILURE_THRESHOLD`	`2`
阈值指令已编写（带外标志）	—	`THRESHOLD_AUTHORED`	`0`

对于非

MessagingSession

的上下文对象（如

Case

、

VoiceCall

），请传入匹配的

SERVICE_CHANNEL_DEV_NAME

SERVICE_CHANNEL_LABEL

。

Preconditions

前置条件

sf
CLI installed and authenticated to the target org (
```
sf org display -o <alias>
```
shows Connected). All calls use
```
--target-org <alias>
```
.
node
≥ 18 and jq
on PATH (the deterministic classifiers and JSON assembly).
The agent exists and its latest
BotVersion
is Active. This skill fails closed if not.
For
MessagingSession
handoff, an active
MessagingChannel
exists. This skill fails closed if none is found. Other context objects use a different transport and are not gated on
```
MessagingChannel
```
.
Sandbox / trial CDO / Developer Edition org. The skill refuses to configure escalation on a real production customer org.

If a precondition fails,

sf

surfaces the raw error — do not fabricate state; surface it and stop.

已安装并认证
sf
CLI到目标组织（执行
```
sf org display -o <alias>
```
显示已连接）。所有调用均使用
```
--target-org <alias>
```
参数。
node
版本≥18且**
```
jq
```
**已添加到PATH（用于确定性分类器和JSON组装）。
智能体已存在且其最新
BotVersion
处于激活状态。若不满足，技能将直接失败。
对于
MessagingSession
转接场景，需存在活跃的
MessagingChannel
。若未找到，技能将直接失败。其他上下文对象使用不同传输方式，无需依赖
```
MessagingChannel
```
。
沙盒/试用CDO/开发者版组织。技能拒绝在真实生产客户组织中配置升级流程。

若前置条件不满足，

sf

会显示原始错误——请勿伪造状态；直接显示错误并停止执行。

Workflow

工作流程

Phase 0 — Production write-guard (mandatory, first write-gate)

Phase 0 — 生产环境写入防护（强制，首个写入网关）

Before any write, the orchestrator queries

Organization

(

IsSandbox

TrialExpirationDate

OrganizationType

) and computes

safe_to_write

. If the org is a real production customer org, the skill emits

status: "BLOCKED"

and stops. This is enforced in

scripts/verify-and-configure.sh

— never bypass it.

在执行任何写入操作前，编排器会查询

Organization

（

IsSandbox

、

TrialExpirationDate

、

OrganizationType

）并计算

safe_to_write

。若组织为真实生产客户组织，技能会输出

status: "BLOCKED"

并停止执行。此规则在

scripts/verify-and-configure.sh

中强制执行——请勿绕过。

Phase 1 — Preconditions (read-only, fail closed)

Phase 1 — 前置条件检查（只读，不满足则失败）

Agent Active — SOQL
```
BotDefinition
```
(+ latest
```
BotVersion
```
), classified deterministically by scripts/classify-agent-active.mjs. Not found or inactive → block with the activation click-path.

Transport channel present — for

MessagingSession

, SOQL

MessagingChannel WHERE IsActive=true

; zero rows → block with a pointer to

service-digital-engagement-channel-configure

智能体激活状态——通过SOQL查询
```
BotDefinition
```
（+最新
```
BotVersion
```
），由scripts/classify-agent-active.mjs进行确定性分类。若未找到或未激活→阻止执行并提供激活操作路径。
传输渠道存在性——对于
```
MessagingSession
```
场景，通过SOQL查询
```
MessagingChannel WHERE IsActive=true
```
；若无结果→阻止执行并指向
```
service-digital-engagement-channel-configure
```
。

Phase 2 — Human queue (create-or-adopt) + members

Phase 2 — 人工队列（创建或适配）+成员

Resolve the queue by DeveloperName. If missing, deploy a

Queue

(canonical Metadata API element order:

doesSendEmailToMembers

name

queueSobject

) with a

QueueSobject

for

CONTEXT_OBJECT

. For an adopted queue missing the binding, add the context object additively via the Data API. Create the

QueueRoutingConfig

if absent and bind it to the queue (

Group.QueueRoutingConfigId

), re-querying to confirm the bind persisted.

Members (human routability): the queue must have at least one active human member — otherwise the escalation routes to an empty queue. The skill counts

GroupMember

rows that resolve to an active

User

. If there are none and you pass

QUEUE_MEMBER_USERNAMES

(comma-separated usernames), it validates each against the username grammar up front, resolves the active

User

, and POSTs the

GroupMember

; it then re-counts. If the queue still has zero active human members the verdict is

INCOMPLETE

with

queueHasActiveDirectUserMember

missing

(an active direct user is necessary — not sufficient — for human routability; full Omni permission-set + presence-status eligibility is proven only at runtime). When there is no eligible member, the skill also skips QueueRoutingConfig binding and outbound-flow activation, so it never wires an empty queue. Use an approved Omni provisioning workflow when richer member reconciliation is required.

通过开发者名称解析队列。若队列不存在，则部署一个

Queue

（标准Metadata API元素顺序：

doesSendEmailToMembers

、

name

、

queueSobject

），并为

CONTEXT_OBJECT

添加对应的

QueueSobject

。对于已适配但缺少绑定的队列，通过Data API增量添加上下文对象。若

QueueRoutingConfig

不存在则创建，并绑定到队列（

Group.QueueRoutingConfigId

），重新查询以确认绑定已生效。

成员（人工路由可用性）：队列必须至少有一名活跃人工成员——否则升级请求将路由到空队列。技能会统计可解析为活跃

User

的

GroupMember

行数。若成员数为0且传入了

QUEUE_MEMBER_USERNAMES

（逗号分隔的用户名），则会预先验证每个用户名的语法，解析对应的活跃

User

，并POST

GroupMember

；随后重新统计成员数。若队列仍无活跃人工成员，判定结果为

INCOMPLETE

，并在

missing

中标记

queueHasActiveDirectUserMember

（活跃直接用户是人工路由可用性的必要非充分条件；完整的Omni权限集+在线状态资格仅能在运行时验证）。当无合格成员时，技能还会跳过QueueRoutingConfig绑定和出站流激活，因此永远不会配置空队列。如需更复杂的成员协调，请使用已批准的Omni配置工作流。

Phase 3 — Outbound QueueBased RoutingFlow

Phase 3 — 基于队列的出站RoutingFlow

Deploy the bundled outbound flow template assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml, substituting the flow name/label, queue DeveloperName, and service-channel tokens. The flow looks the queue up by DeveloperName at runtime (portable, no hardcoded Id). After deploy,

FlowDefinitionView.ActiveVersionId

must be non-null.

部署捆绑的出站流模板assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml，替换流名称/标签、队列开发者名称以及服务渠道令牌。流会在运行时通过开发者名称查找队列（可移植，无硬编码Id）。部署完成后，

FlowDefinitionView.ActiveVersionId

必须非空。

Phase 4 — Escalation topic + planner outbound route (doc-driven edits)

Phase 4 — 升级主题+规划器出站路由（文档驱动的编辑）

These two edits require per-org topic/bundle discovery, so they are authored explicitly (retrieve → edit → deploy), then verified by the orchestrator when you pass the topic/bundle API names. Follow references/escalation-mechanism.md:

Retrieve the escalation topic (
```
GenAiPlugin
```
), set
```
<canEscalate>true</canEscalate>
```
, deploy.
Retrieve the agent's
```
GenAiPlannerBundle
```
, add
```
outboundRouteConfigs
```
(
```
escalationMessage
```
,
```
outboundRouteName=<FLOW_DEVELOPER_NAME>
```
,
```
outboundRouteType=OmniChannelFlow
```
) on the Messaging planner surface, deploy. The verifier couples name + type inside the SAME block on a Messaging-class surface (via scripts/extract-outbound-route.mjs) — a bundle with the right name and an
```
OmniChannelFlow
```
type in unrelated blocks will not pass.

这两项编辑需要针对每个组织进行主题/组件发现，因此需显式创作（检索→编辑→部署），然后在传入主题/组件API名称时由编排器验证。请遵循references/escalation-mechanism.md：

检索升级主题（
```
GenAiPlugin
```
），设置
```
<canEscalate>true</canEscalate>
```
，然后部署。
检索智能体的
```
GenAiPlannerBundle
```
，在消息规划器组件上添加
```
outboundRouteConfigs
```
（
```
escalationMessage
```
、
```
outboundRouteName=<FLOW_DEVELOPER_NAME>
```
、
```
outboundRouteType=OmniChannelFlow
```
），然后部署。验证器会检查同一消息类组件中的名称+类型是否关联（通过scripts/extract-outbound-route.mjs）——仅包含正确名称但在无关模块中包含
```
OmniChannelFlow
```
类型的组件无法通过验证。

Phase 5 — Failure-threshold directives (native policy)

Phase 5 — 故障阈值指令（原生规则）

The failure threshold and any per-topic overrides are directives, not enforced counters — there is no metadata field that counts failed turns (see references/failure-policy.md). The orchestrator does not write these into the agent; it only renders

DEFAULT_FAILURE_THRESHOLD

(default

) into the local directive template assets/escalation-thresholds.instructions.md — pass e.g.

DEFAULT_FAILURE_THRESHOLD=3

for a three-attempt scenario — and reports that value under

threshold.default_failures

(with

threshold.directive_rendered

) as verdict evidence. Authoring the rendered directive into the agent's Agent Script is a manual/out-of-band step; set

THRESHOLD_AUTHORED=1

on the verifier run to record

threshold.authored=true

. The directive is eval-verified, never a headless runtime read, so it never blocks the deterministic verdict.

故障阈值及任何针对特定主题的覆盖规则均为指令，而非强制计数器——不存在统计失败轮次的元数字段（详情请参阅references/failure-policy.md）。编排器不会将这些内容写入智能体；仅会将

DEFAULT_FAILURE_THRESHOLD

（默认值为

）渲染到本地指令模板assets/escalation-thresholds.instructions.md中——例如传入

DEFAULT_FAILURE_THRESHOLD=3

可设置三次尝试的场景——并在判定结果的证据中报告该值（包含

threshold.directive_rendered

）。将渲染后的指令写入智能体的Agent Script是手动/带外步骤；在验证器运行时设置

THRESHOLD_AUTHORED=1

可记录

threshold.authored=true

。指令由评估规则验证，而非无头运行时读取，因此永远不会阻止确定性判定结果。

Phase 6 — Republish + reactivate

Phase 6 — 重新发布+重新激活

After the Phase 4/5 edits, republish and reactivate the agent so they take effect. These are manual operator commands for the hand-edited path; the orchestrator itself only publishes/deactivates/reactivates the agent inside the optional

AUTHOR_SURFACES=1

pass (see "Running it"):

bash

sf agent validate authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
sf agent publish  authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
sf agent activate --api-name "$AGENT_DN" --target-org "$ORG"

完成Phase 4/5的编辑后，重新发布并重新激活智能体，使更改生效。对于手动编辑路径，这些是人工操作命令；编排器仅会在可选的

AUTHOR_SURFACES=1

执行模式下（请参阅“运行方式”）发布/停用/重新激活智能体：

bash

sf agent validate authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
sf agent publish  authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
sf agent activate --api-name "$AGENT_DN" --target-org "$ORG"

Phase 7 — Deterministic verification (single JSON verdict)

Phase 7 — 确定性验证（单一JSON判定结果）

The orchestrator round-trips every deterministic surface, assembles an evidence object, and classifies it with scripts/verify-escalation-config.mjs into one of three states so a missing escalation policy can never masquerade as fully configured:

```
CONFIGURED
```
— all deterministic surfaces satisfied and the failure-threshold directive is authored.
```
ROUTING_CONFIGURED_POLICY_PENDING
```
— routing and the agent escalation surface are verified, but the failure-threshold directive (
```
thresholdAuthored
```
) is not yet confirmed. Author it (
```
AUTHOR_SURFACES=1
```
/
```
THRESHOLD_AUTHORED=1
```
) and re-run to reach
```
CONFIGURED
```
.
```
INCOMPLETE
```
— one or more deterministic surfaces are missing (see
```
missing[]
```
).

Note the NGA escalation-surface detection (scripts/classify-nga-escalation.mjs) is an advisory preflight — it matches for a reachable

@utils.escalate

/ create-record action in the authoring bundle but does not prove runtime reachability from the topic. Treat a passing NGA surface check as a strong signal, not end-to-end runtime proof; confirm the live handoff with the Phase 8 runtime step.

编排器会往返验证所有确定性组件，组装证据对象，并通过scripts/verify-escalation-config.mjs将其分类为三种状态，确保缺失的升级策略永远不会伪装成已完全配置：

```
CONFIGURED
```
——所有确定性组件均满足要求且故障阈值指令已编写完成。
```
ROUTING_CONFIGURED_POLICY_PENDING
```
——路由和智能体升级组件已验证，但故障阈值指令（
```
thresholdAuthored
```
）尚未确认。编写完成后（
```
AUTHOR_SURFACES=1
```
/
```
THRESHOLD_AUTHORED=1
```
）重新运行即可达到
```
CONFIGURED
```
状态。
```
INCOMPLETE
```
——一个或多个确定性组件缺失（请参阅
```
missing[]
```
）。

请注意，NGA升级组件检测（scripts/classify-nga-escalation.mjs）是预检查建议——它会匹配创作组件中可访问的

@utils.escalate

/创建记录操作，但无法证明从主题到该操作的运行时可达性。将NGA组件检查通过视为强信号，而非端到端运行时证明；请通过Phase 8的运行时步骤确认实际转接功能。

Phase 8 — Runtime / manual proof (out of headless scope)

Phase 8 — 运行时/手动验证（无头模式范围外）

Confirm the conversational trigger,

AgentWork

creation, and same-session context preservation with a live conversation — see references/runtime-verification.md.

通过真实对话确认对话触发、

AgentWork

创建以及同会话上下文保留——详情请参阅references/runtime-verification.md。

Running it

运行方式

bash

bash scripts/verify-and-configure.sh <org-alias> \
  [<agent-developer-name>] [<queue-developer-name>] \
  [<escalation-topic-api-name>] [<planner-bundle-api-name>]

Positionals 2–5 also read from env (see the Inputs table). Further scenario inputs are env-only:

FLOW_DEVELOPER_NAME

FLOW_LABEL

CONTEXT_OBJECT

SERVICE_CHANNEL_DEV_NAME

SERVICE_CHANNEL_LABEL

QUEUE_MEMBER_USERNAMES

```
PLAN_ONLY=1
```
previews (read-only) and stops before any write.
```
THRESHOLD_AUTHORED=1
```
marks the directive policy as authored for the verdict.
```
AUTHOR_SURFACES=1
```
(optional, run mode) — deterministically author the two doc-driven surfaces instead of hand-editing XML, following the Agentforce lifecycle in
```
agentforce-generate/references/known-issues.md
```
(Issue 18): publish (regenerate the compiled bundle) → retrieve the
```
GenAiPlugin
```
topic +
```
GenAiPlannerBundle
```
in metadata format (
```
--target-metadata-dir … --unzip
```
) → deactivate the agent (deploys fail while it is active) → apply a schema-aware, XSD-ordered, loss-less, idempotent patch (
```
scripts/patch-escalation-surfaces.mjs
```
) that sets
```
canEscalate=true
```
(after
```
aiPluginUtterances
```
, before
```
description
```
) and inserts
```
outboundRouteConfigs
```
(
```
outboundRouteType=OmniChannelFlow
```
, before
<surface>
on a Messaging-class planner surface, targeting the outbound flow) → deploy with
```
--metadata-dir
```
→ activate (fail-closed; the agent is never left inactive silently) → re-read the latest
BotVersion
so the verdict reflects the freshly-authored version. It requires the topic and/or bundle API names, runs only after the membership gate (never wires an empty queue), and refuses (blocks) rather than guess if it cannot find a safe, XSD-ordered patch point. Omit it to keep the skill verify-only.
The
```
canEscalate
```
and
```
outboundRouteConfigs
```
surfaces are verified only when you pass
```
<escalation-topic-api-name>
```
/
```
<planner-bundle-api-name>
```
(they are authored via the doc-driven edits in Phase 4).

Typical two-pass flow: run once to stand up the queue + outbound flow and preconditions; perform the Phase 4/5/6 doc-driven edits; then re-run with the topic + bundle API names and

THRESHOLD_AUTHORED=1

to reach

CONFIGURED

bash

bash scripts/verify-and-configure.sh <org-alias> \
  [<agent-developer-name>] [<queue-developer-name>] \
  [<escalation-topic-api-name>] [<planner-bundle-api-name>]

位置参数2–5也可从环境变量读取（请参阅输入项表格）。更多场景输入项仅支持环境变量：
```
FLOW_DEVELOPER_NAME
```
、
```
FLOW_LABEL
```
、
```
CONTEXT_OBJECT
```
、
```
SERVICE_CHANNEL_DEV_NAME
```
、
```
SERVICE_CHANNEL_LABEL
```
、
```
QUEUE_MEMBER_USERNAMES
```
。
```
PLAN_ONLY=1
```
会预览（只读）并在执行任何写入操作前停止。
```
THRESHOLD_AUTHORED=1
```
会在判定结果中标记指令规则已编写完成。
```
AUTHOR_SURFACES=1
```
（可选，运行模式）——确定性创作两个文档驱动的组件，而非手动编辑XML，遵循
```
agentforce-generate/references/known-issues.md
```
中的Agentforce生命周期（Issue 18）：发布（重新生成编译后的组件）→以元数据格式检索
```
GenAiPlugin
```
主题+
```
GenAiPlannerBundle
```
（
```
--target-metadata-dir … --unzip
```
）→停用智能体（激活状态下无法部署）→应用基于Schema、符合XSD顺序、无损耗、幂等的补丁（
```
scripts/patch-escalation-surfaces.mjs
```
），设置
```
canEscalate=true
```
（位于
```
aiPluginUtterances
```
之后，
```
description
```
之前）并插入
```
outboundRouteConfigs
```
（
```
outboundRouteType=OmniChannelFlow
```
，位于
<surface>
之前的消息类规划器组件上，指向出站流）→通过
--metadata-dir
部署→激活智能体（失败即停止；永远不会让智能体保持未激活状态）→重新读取最新
BotVersion
，使判定结果反映最新创作的版本。此模式需要主题和/或组件API名称，仅在成员检查通过后运行（永远不会配置空队列），若无法找到安全的XSD顺序补丁点则会**拒绝（阻止）**执行而非猜测。省略此参数可使技能仅执行验证操作。
仅当传入
```
<escalation-topic-api-name>
```
/
```
<planner-bundle-api-name>
```
时，才会验证
```
canEscalate
```
和
```
outboundRouteConfigs
```
组件（它们通过Phase 4中的文档驱动编辑创作）。

典型的两步流程：首次运行以创建队列+出站流并满足前置条件；执行Phase 4/5/6的文档驱动编辑；然后传入主题+组件API名称并设置

THRESHOLD_AUTHORED=1

重新运行，以达到

CONFIGURED

状态。

Output contract

输出约定

A single JSON object to stdout:

json

{
  "skill": "service-agentforce-human-escalation-configure",
  "status": "CONFIGURED",
  "agent": { "developer_name": "Support_Agent", "active": true },
  "queue": { "developer_name": "Human_Support_Queue", "id": "00G...", "active_direct_user_member_count": 1 },
  "outbound_flow": { "api_name": "Human_Escalation_Outbound_Flow", "active_version_id": "301..." },
  "escalation_topic": "Escalate_To_Human",
  "planner_bundle": "Support_Agent",
  "config_verification": {
    "verdict": "CONFIGURED",
    "deterministicPass": true,
    "directivePass": true,
    "checks": [],
    "missing": []
  },
  "next_steps": [],
  "manual_actions": [],
  "blocking_issue": null
}

```
status
```
:
```
CONFIGURED
```
(all deterministic surfaces satisfied),
```
INCOMPLETE
```
(some
```
config_verification.missing
```
), or
```
BLOCKED
```
(bad input / auth / production / precondition; exit 1).
Re-running an already-configured org is a no-op that returns
```
CONFIGURED
```
(idempotent).

向标准输出输出单一JSON对象：

json

{
  "skill": "service-agentforce-human-escalation-configure",
  "status": "CONFIGURED",
  "agent": { "developer_name": "Support_Agent", "active": true },
  "queue": { "developer_name": "Human_Support_Queue", "id": "00G...", "active_direct_user_member_count": 1 },
  "outbound_flow": { "api_name": "Human_Escalation_Outbound_Flow", "active_version_id": "301..." },
  "escalation_topic": "Escalate_To_Human",
  "planner_bundle": "Support_Agent",
  "config_verification": {
    "verdict": "CONFIGURED",
    "deterministicPass": true,
    "directivePass": true,
    "checks": [],
    "missing": []
  },
  "next_steps": [],
  "manual_actions": [],
  "blocking_issue": null
}

```
status
```
：
```
CONFIGURED
```
（所有确定性组件均满足要求）、
```
INCOMPLETE
```
（部分
```
config_verification.missing
```
）或
```
BLOCKED
```
（输入错误/认证失败/生产环境/前置条件不满足；退出码1）。
对已配置完成的组织重新运行时，会执行空操作并返回
```
CONFIGURED
```
（幂等性）。

Idempotency

幂等性

Existing queue,

QueueSobject

QueueRoutingConfig

, queue members, and an already-active outbound flow are reused, not recreated (members are only added when the queue has zero active members and

QUEUE_MEMBER_USERNAMES

is supplied; already-present members are left untouched). The doc-driven edits (

canEscalate

outboundRouteConfigs

) are set-if-absent. A second run against a fully configured org performs no writes and returns

CONFIGURED

现有队列、

QueueSobject

、

QueueRoutingConfig

、队列成员以及已激活的出站流会被复用，而非重新创建（仅当队列为空且传入

QUEUE_MEMBER_USERNAMES

时才会添加成员；已存在的成员不会被修改）。文档驱动的编辑（

canEscalate

、

outboundRouteConfigs

）仅会在缺失时设置。对已完全配置的组织执行第二次运行时，不会执行任何写入操作并返回

CONFIGURED

。

Verification

验证

Run the bundled escalation contract tests after changing this skill or its scripts:

bash

python3 scripts/tests/test_escalation_contracts.py

修改本技能或其脚本后，请运行捆绑的升级合约测试：

bash

python3 scripts/tests/test_escalation_contracts.py