Service Agentforce Human Escalation Configure

Configure Agentforce Agent → Human Escalation

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.

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.

Authoring models — classic vs next-gen (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.

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.

---

Inputs

For a non-MessagingSession context object (e.g. Case, VoiceCall), pass the matching SERVICE_CHANNEL_DEV_NAME / SERVICE_CHANNEL_LABEL.

Preconditions

1. sf CLI installed and authenticated to the target org (sf org display -o <alias> shows Connected). All calls use --target-org <alias>.
2. node ≥ 18 and jq on PATH (the deterministic classifiers and JSON assembly).
3. The agent exists and its latest BotVersion is Active. This skill fails closed if not.
4. 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.
5. 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.

---

Workflow

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

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.

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

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.
2. Transport channel present — for MessagingSession, SOQL MessagingChannel WHERE IsActive=true; zero rows → block with a pointer to service-digital-engagement-channel-configure.

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

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 in 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.

Phase 3 — Outbound QueueBased 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.