forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-agentforce-human-escalation-configure
service-agentforce-human-escalation-configure
UnverifiedUse 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.
scripts/tests/_bootstrap.py
View on GitHub"""Shared paths + fake-`sf` harness for the escalation-configure contract suite (org-free, network-free; drives the bash+Node skill via subprocess, asserting exit codes + emitted JSON)."""
from __future__ import annotations
import os
import subprocess
import tempfile
from pathlib import Path
# skills/ root is three levels up (.../<skill>/scripts/tests/_bootstrap.py). In the flat copy
# this is the repo's skills/ directory; in a plugin mirror it is that plugin's own bundled
# skills/ directory, which only contains its own roster.
SKILLS_ROOT = Path(__file__).resolve().parents[3]
_COORDINATOR = "service-itsm-agentic-setup-agentforce-coordinate"
def _find_flat_skills_root(start: Path) -> Path | None:
"""Walk up from this file to the directory holding the ITSM coordinator skill: the repo's
flat skills/ root, or its team directory under contributed-skills/. Cross-skill references
that aren't part of this skill's own plugin roster (like the coordinator's verdict script
below) must resolve here, not under SKILLS_ROOT, since a plugin mirror's SKILLS_ROOT only
contains its own bundled skills. The walk stops at the repo root so a stray skills/ tree in
a parent directory is never executed; None means the coordinator isn't in this checkout."""
for parent in start.parents:
if (parent / "skills" / _COORDINATOR).is_dir():
return parent / "skills"
for team_copy in sorted((parent / "contributed-skills").glob(f"*/{_COORDINATOR}")):
if team_copy.is_dir():
return team_copy.parent
if (parent / ".git").exists():
break
return None
FLAT_SKILLS_ROOT = _find_flat_skills_root(Path(__file__).resolve())
SKILL_DIR = "service-agentforce-human-escalation-configure"
SCRIPT = f"{SKILL_DIR}/scripts/verify-and-configure.sh"
# The ITSM coordinator's advancement gate - exercised for the escalation verdict mapping. Not
# bundled per-plugin, so resolved against FLAT_SKILLS_ROOT (see run_node's root parameter).
VERDICT_SCRIPT = "service-itsm-agentic-setup-agentforce-coordinate/scripts/verify-child-verdict.mjs"
# A fake `sf` that reports a PRODUCTION customer org so the safe_to_write guard must refuse.
# A fake `project deploy` returns a sentinel so a guard bypass would surface loudly.
_FAKE_SF_PROD = r"""#!/usr/bin/env bash
sub="${1:-} ${2:-}"; args="$*"
case "$sub" in
"org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
"data query")
if printf '%s' "$args" | grep -q "FROM Organization"; then
echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":false,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}]}}'
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
exit 0;;
"project deploy")
echo '{"status":1,"result":{"success":false},"message":"FAKE_SF_DEPLOY_SHOULD_NOT_BE_REACHED"}'; exit 1;;
*) echo '{"status":0,"result":{}}'; exit 0;;
esac
"""
# A fake `sf` for a SANDBOX org where every deterministic surface already resolves (active agent,
# MessagingChannel, queue + QueueSobject + QRC, active RoutingFlow) and `project retrieve` writes
# canEscalate=true / an outboundRouteName so the doc-driven surfaces verify true. The FAKE_* env vars
# below toggle each surface off to exercise the block/create paths; a GroupMember POST flips membership
# via a marker file (stateful convergence); canonical QRC id 0RC000000000001AAA makes create+adopt converge.
_FAKE_SF_SANDBOX = r"""#!/usr/bin/env bash
sub="${1:-} ${2:-}"; args="$*"
SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
AGENT_ACTIVE="${FAKE_AGENT_ACTIVE:-1}"
MC_PRESENT="${FAKE_MC_PRESENT:-1}"
QS_PRESENT="${FAKE_QS_PRESENT:-1}"
QRC_PRESENT="${FAKE_QRC_PRESENT:-1}"
QUEUE_PRESENT="${FAKE_QUEUE_PRESENT:-1}"
QUEUE_BOUND="${FAKE_QUEUE_BOUND:-1}"
QUEUE_MEMBERS="${FAKE_QUEUE_MEMBERS:-1}"
ROUTE_TYPE="${FAKE_ROUTE_TYPE:-OmniChannelFlow}"
ROUTE_SURFACE="${FAKE_ROUTE_SURFACE:-Messaging}"
# FAKE_GENAI_MD=0 → org exposes no GenAiPlugin/GenAiPlannerBundle metadata types (the escalation
# preflight must then BLOCK before any write). Default 1 → the authoring metadata is exposed.
GENAI_MD="${FAKE_GENAI_MD:-1}"
# FAKE_MODEL pins the authoring model the org advertises: classic (GenAiPlugin+GenAiPlannerBundle),
# nga (AiAuthoringBundle, no GenAiPlannerBundle), or none. Empty => derive from GENAI_MD (1=classic,0=none).
MODEL="${FAKE_MODEL:-}"
if [ -z "$MODEL" ]; then [ "$GENAI_MD" = "1" ] && MODEL="classic" || MODEL="none"; fi
TARGET_MODEL="${FAKE_TARGET_MODEL:-$MODEL}"
# FAKE_NGA_SURFACE=1 => retrieved AiAuthoringBundle contains connection messaging: + @utils.escalate
# (Service escalation surface present). 0 => neither (surface missing => INCOMPLETE on nga).
NGA_SURFACE="${FAKE_NGA_SURFACE:-1}"
RC_ID="0RC000000000001AAA"
# Opt-in call log: when FAKE_SF_CALLLOG points at a file, append every invocation's args so a
# test can prove which mutations did (or did NOT) happen - e.g. idempotent re-runs create nothing.
if [ -n "${FAKE_SF_CALLLOG:-}" ]; then printf '%s\n' "$args" >> "$FAKE_SF_CALLLOG"; fi
_has_members() { [ "$QUEUE_MEMBERS" = "1" ] || [ -f "$SELF_DIR/.gm_added" ]; }
case "$sub" in
"org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
"org list")
if printf '%s' "$args" | grep -q "metadata-types"; then
case "$MODEL" in
classic) echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"GenAiPlugin"},{"xmlName":"GenAiPlannerBundle"}]}}';;
nga) echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"AiAuthoringBundle"},{"xmlName":"GenAiPlugin"}]}}';;
both) echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"AiAuthoringBundle"},{"xmlName":"GenAiPlugin"},{"xmlName":"GenAiPlannerBundle"}]}}';;
*) echo '{"status":0,"result":{"metadataObjects":[{"xmlName":"Bot"},{"xmlName":"BotTemplate"},{"xmlName":"BotBlock"}]}}';;
esac
else
echo '{"status":0,"result":{}}'
fi
exit 0;;
"data query")
if printf '%s' "$args" | grep -q "FROM Organization"; then
echo '{"status":0,"result":{"records":[{"Id":"00Dxx0000000000EAA","IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Developer Edition"}]}}'
elif printf '%s' "$args" | grep -q "FROM BotDefinition"; then
if [ "$AGENT_ACTIVE" = "1" ]; then
echo '{"status":0,"result":{"records":[{"Id":"0Xx000000000001AAA","DeveloperName":"Support_Agent","MasterLabel":"Support Agent","BotVersions":{"records":[{"Id":"04V000000000001AAA","Status":"Active"}]}}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[{"Id":"0Xx000000000001AAA","DeveloperName":"Support_Agent","MasterLabel":"Support Agent","BotVersions":{"records":[{"Id":"04V000000000001AAA","Status":"Inactive"}]}}],"totalSize":1}}'
fi
elif printf '%s' "$args" | grep -q "FROM MessagingChannel"; then
if [ "$MC_PRESENT" = "1" ]; then
echo '{"status":0,"result":{"records":[{"Id":"0M9000000000001AAA","DeveloperName":"Support_Chat"}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
elif printf '%s' "$args" | grep -q "FROM QueueSobject"; then
if [ "$QS_PRESENT" = "1" ]; then
echo '{"status":0,"result":{"records":[{"Id":"0Q9000000000001AAA"}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
elif printf '%s' "$args" | grep -q "FROM QueueRoutingConfig"; then
if [ "$QRC_PRESENT" = "1" ]; then
echo '{"status":0,"result":{"records":[{"Id":"'"$RC_ID"'","DeveloperName":"Human_Support_Queue_RC"}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
elif printf '%s' "$args" | grep -q "FROM FlowDefinitionView"; then
echo '{"status":0,"result":{"records":[{"ApiName":"Human_Escalation_Outbound_Flow","ActiveVersionId":"301000000000001AAA"}],"totalSize":1}}'
elif printf '%s' "$args" | grep -q "FROM GroupMember"; then
if _has_members; then
echo '{"status":0,"result":{"records":[{"UserOrGroupId":"005000000000001AAA"}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
elif printf '%s' "$args" | grep -q "FROM User"; then
if printf '%s' "$args" | grep -q "COUNT(Id)"; then
if _has_members; then
echo '{"status":0,"result":{"records":[{"c":1}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[{"c":0}],"totalSize":1}}'
fi
else
# Id-by-username (assignment path) → an active user row.
echo '{"status":0,"result":{"records":[{"Id":"005000000000002AAA"}],"totalSize":1}}'
fi
elif printf '%s' "$args" | grep -q "FROM Group"; then
if [ "$QUEUE_PRESENT" = "1" ]; then
if [ "$QUEUE_BOUND" = "1" ]; then
echo '{"status":0,"result":{"records":[{"Id":"00G000000000001AAA","QueueRoutingConfigId":"'"$RC_ID"'"}],"totalSize":1}}'
else
echo '{"status":0,"result":{"records":[{"Id":"00G000000000001AAA","QueueRoutingConfigId":null}],"totalSize":1}}'
fi
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
else
echo '{"status":0,"result":{"records":[],"totalSize":0}}'
fi
exit 0;;
"api request")
# Data API POST/PATCH (QueueSobject bind, QueueRoutingConfig create, Group.QueueRoutingConfigId bind).
if printf '%s' "$args" | grep -q "sobjects/QueueRoutingConfig"; then
echo '{"success":true,"id":"'"$RC_ID"'"}'
elif printf '%s' "$args" | grep -q "sobjects/QueueSobject"; then
echo '{"success":true,"id":"0Q9000000000009AAA"}'
elif printf '%s' "$args" | grep -q "sobjects/GroupMember"; then
touch "$SELF_DIR/.gm_added"
echo '{"success":true,"id":"0GM00000000001AAA"}'
else
# Group PATCH → 204 empty body on success.
echo ''
fi
exit 0;;
"project retrieve")
dir=$(printf '%s' "$args" | sed -n 's/.*--target-metadata-dir[ =]\([^ ]*\).*/\1/p'); dir="${dir:-.}"
mkdir -p "$dir"
if printf '%s' "$args" | grep -q "AiAuthoringBundle:"; then
[ "$TARGET_MODEL" = "nga" ] || [ "$TARGET_MODEL" = "both" ] || exit 1
if [ "$NGA_SURFACE" = "1" ]; then
cat > "$dir/Support_Agent.agent" <<'AGENT'
start_agent support_agent:
connection messaging:
end_user_client: customer_web_client
reasoning:
actions:
human_handoff: @utils.escalate
description: "Transfer the user to a human agent."
AGENT
else
cat > "$dir/Support_Agent.agent" <<'AGENT'
start_agent support_agent:
reasoning:
actions:
answer: @actions.AnswerQuestionWithKnowledge
AGENT
fi
elif printf '%s' "$args" | grep -q "GenAiPlugin:"; then
if [ "${FAKE_AUTHORING_FIXTURE:-0}" = "1" ]; then
# Metadata-format bundle whose GenAiPlugin has no XSD anchor, so the canEscalate patcher
# refuses after the deactivate and the rollback path runs.
mkdir -p "$dir/genAiPlugins"
echo '<?xml version="1.0"?><Package xmlns="x"></Package>' > "$dir/package.xml"
printf '<?xml version="1.0"?>\n<GenAiPlugin xmlns="x"></GenAiPlugin>\n' > "$dir/genAiPlugins/Escalate_Topic.genAiPlugin"
else
echo '<canEscalate>true</canEscalate>' > "$dir/plugin.xml"
fi
elif printf '%s' "$args" | grep -q "GenAiPlannerBundle:"; then
[ "$TARGET_MODEL" = "classic" ] || [ "$TARGET_MODEL" = "both" ] || exit 1
cat > "$dir/bundle.xml" <<BXML
<GenAiPlannerBundle>
<plannerSurfaces>
<surfaceType>${ROUTE_SURFACE}</surfaceType>
<outboundRouteConfigs>
<escalationMessage>Transferring you to a live support agent.</escalationMessage>
<outboundRouteName>Human_Escalation_Outbound_Flow</outboundRouteName>
<outboundRouteType>${ROUTE_TYPE}</outboundRouteType>
</outboundRouteConfigs>
</plannerSurfaces>
</GenAiPlannerBundle>
BXML
fi
echo '{"status":0,"result":{"success":true}}'; exit 0;;
"project deploy")
echo '{"status":0,"result":{"success":true,"files":[{"fullName":"Human_Escalation_Outbound_Flow","type":"Flow","state":"Created"}]}}'; exit 0;;
"agent activate")
# FAKE_ACTIVATE_FAIL=1 → reactivation fails, so a rollback must report the agent left inactive.
if [ "${FAKE_ACTIVATE_FAIL:-0}" = "1" ]; then
echo '{"status":1,"message":"FAKE_ACTIVATE_FAILED"}'; exit 1
fi
echo '{"status":0,"result":{}}'; exit 0;;
*) echo '{"status":0,"result":{}}'; exit 0;;
esac
"""
# Only what bash, node, and version-manager shims need, so tokens, SF_* overrides, and
# NODE_OPTIONS from the developer's shell never reach the scripts under test.
_ENV_PASSTHROUGH = ("PATH", "HOME", "TERM", "TMPDIR", "LANG", "LC_ALL", "USER", "SHELL")
def _base_env():
return {k: os.environ[k] for k in _ENV_PASSTHROUGH if k in os.environ}
def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
"""Run the orchestrator; return (returncode, merged stdout+stderr)."""
env = _base_env()
if scrub_sf:
kept = [d for d in env.get("PATH", "").split(os.pathsep)
if d and not os.path.exists(os.path.join(d, "sf"))]
env["PATH"] = os.pathsep.join(kept)
if path_prefix:
env["PATH"] = path_prefix + os.pathsep + env.get("PATH", "")
if extra_env:
env.update({k: str(v) for k, v in extra_env.items()})
proc = subprocess.run(
["bash", str(SKILLS_ROOT / SCRIPT), *args],
capture_output=True, text=True, env=env, cwd=str(SKILLS_ROOT),
)
return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
def run_node(script_rel, args, root=None):
"""Run a bundled Node helper; return (returncode, stdout). Pass `root=FLAT_SKILLS_ROOT`
for cross-skill scripts not bundled in this skill's own plugin roster."""
base = root if root is not None else SKILLS_ROOT
proc = subprocess.run(
["node", str(base / script_rel), *args],
capture_output=True, text=True, cwd=str(base), env=_base_env(),
)
return proc.returncode, (proc.stdout or "")
class FakeSf:
"""Context manager: a temp dir holding an executable fake `sf` first on PATH."""
def __init__(self, body=_FAKE_SF_PROD):
self._body = body
self._tmp = None
def __enter__(self):
self._tmp = tempfile.mkdtemp(prefix="esc-fake-sf-")
sf = Path(self._tmp) / "sf"
sf.write_text(self._body)
sf.chmod(0o755)
return self._tmp
def __exit__(self, *exc):
import shutil
if self._tmp:
shutil.rmtree(self._tmp, ignore_errors=True)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |