/service-agentforce-human-escalation-configure

name: service-agentforce-human-escalation-configure
description: "Use to configure and verify Agentforce agent-to-human escalation, including human handoff, a staffed fallback queue, and failure-threshold directives. Triggers: configure agent escalation, escalate to a human agent, agent handoff to a queue, configure a human escalation queue, set an Agentforce fallback handoff. Do not use to create an agent or configure inbound channel routing; use service-agentforce-channel-configure for inbound routing."
metadata:
  version: "1.0"
  domains: ["Service", "Agentforce"]
  minApiVersion: "67.0"
  relatedSkills:
    - "agentforce-generate"
    - "service-agentforce-channel-configure"
    - "service-digital-engagement-channel-configure"
    - "service-itsm-agentic-setup-agentforce-coordinate"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck:
    - type: "license"
      value: "Agentforce"
allowed-tools: Bash Read Write AskUserQuestion

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](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](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](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 escalati