Create an IT Service Employee Agent (broad or specialized)

Create and activate an IT Service Employee Agent as a Next-Gen Authoring (NGA) native agent — Agent-Script-based (AiAuthoringBundleDefVer/bundle), appearing natively in Agentforce Studio's Agents list with no external-link icon — entirely through the Salesforce CLI (sf). This skill does not call the legacy /connect/service-itsm/createAgent; instead it reuses a shipped ITSM Employee template's agentScript field and feeds it into the NGA bundle pipeline: POST /nextgen-authoring/bundles → POST /nextgen-authoring/bundle-versions/{id}/publish → POST /nextgen-authoring/bundle-versions/{id}/activate. Commands: sf api request rest for Connect API GET/POST; sf data query for the SOQL idempotency + verify reads.

GET /connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent returns the broad IT Service Employee template plus ~47 specialized Employee templates under the svc_emp_intelligence__ namespace as siblings in data[]. Every specialized template ships the same agentScript shape with the same config.developer_name/config.agent_label substitution points, so the same NGA sequence works for any of them — only the masterLabel that Phases 1 and 4 pin against changes. Full catalog + namespace filter + disambiguation rules live in references/specialized-templates.md.

Helper scripts (invoked via Bash) hold every JSON-parsing / decision rule so the model never eyeballs a response body (A9): classify-preflight.mjs, classify-agent-existence.mjs, build-create-body.mjs (HTML-decodes + substitutes the template's agentScript and writes the body to a JSON file so large content and free-text quotes never hit an inline shell string), render-report.mjs (deterministic report renderer).

Template selection (before Phase 1). Resolve the <masterLabel> this run pins: (1) no specialization named ⇒ pin IT Service Employee (id svc_emp_intelligence__ItEmployeeAssistance) — the backwards-compatible default; (2) user names a specialization ⇒ keyword-match against references/specialized-templates.md, single unambiguous match ⇒ pin that masterLabel and derive developerName from id after __ (snake-cased); ambiguous ⇒ AskUserQuestion keyed on id; (3) filter data[] to svc_emp_intelligence__ only — svc_itsm_intelligence__* (Fulfiller) redirects to service-itsm-agentic-setup-fulfiller-agent-configure, other namespaces are out of scope. The resolved <masterLabel> is the single knob passed to classify-preflight.mjs (Phase 1) and build-create-body.mjs (Phase 4).

Prerequisites. Creation assumes the org-level Agentforce for IT Service prerequisites are already satisfied (Agentforce Studio access + service-cloud-requestor-agent + service-cloud-it-service-employee-agent). If Phase 1 detects Studio is not accessible — or if any write returns 403 FUNCTIONALITY_NOT_ENABLED — this skill offers to delegate to service-itsm-agentic-setup-agentforce-studio-validate (employee path) then resume; on "no", stops. This skill never enables features itself — enablement is a Setup-UI/admin action.

Scope

• In scope: Reading agent-templates; extracting an Employee template's Agent Script (broad default or a user-named specialization from references/specialized-templates.md — all under svc_emp_intelligence__); creating the Employee agent as an NGA-native agent via createBundleWithVersion → publish → activate; SOQL-verifying live; idempotent skip on duplicate developer name — all via sf.
• Out of scope: The Fulfiller agent (service-itsm-agentic-setup-fulfiller-agent-configure); enabling org-level feature toggles (validated by service-itsm-agentic-setup-agentforce-studio-validate); low-level topic/action authoring; perm-set assignment; content-bundle deployment; CMDB CRUD; Discovery / Service Graph; the legacy createAgent route; any data[] entry outside svc_emp_intelligence__.

---

Preconditions

If any of these are unmet, sf surfaces an auth error or a 401/403/404; surface the raw error verbatim and stop — do not fabricate state.

1. sf CLI authenticated to the target org (sf org display -o <alias> shows Connected). All calls use --target-org <alias>; never extract the access token by hand.
2. API v67.0+ — pinned in the URL path; do not hand-edit below the minimum.
3. ITSM features + templates provisioned — resolved template must be present. If agent-templates returns nothing or the routes 404, run service-itsm-agentic-setup-agentforce-studio-validate (agent path employee).
4. node ≥ 18 on PATH.

---

Operations at a glance

Concern	Command	Notes
Studio access (precondition read)	sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>	hasAccess=false ⇒ prerequisite hand-off
List agent templates + Agent Script (read)	sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>	agentType=AgentforceEmployeeAgent required; confirms resolved <masterLabel> template + non-empty agentScript
Enumerate existing agent + latest version status (read)	sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" -o <alias> --json	Keyed PRIMARILY on the template's botDefinitionId (Phase-1 row); OR AgentTemplate= is the first fallback that catches the pre-provisioned broad IT_Service_Employee agent by its OOTB namespaced source template (svc_emp_intelligence__ItEmployeeAssistance = Phase-1 template.id) regardless of the collected DeveloperName guess; OR DeveloperName= is the last fallback for self-created agents (null AgentTemplate) and the guard for a dangling Id link (deleted target). Classified by scripts/classify-agent-existence.mjs; Active latest ⇒ ALREADY-CREATED; Inactive latest ⇒ offer reactivation
Create the NGA bundle (write)	sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>	Body built by scripts/build-create-body.mjs; response id = the bundle version Id
Publish the bundle version (write)	sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>	Returns publishedBotId/publishedBotVersionId — creates the underlying BotDefinition/BotVersion
Activate the bundle version (write)	sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>	Empty response on success; agent is now live and NGA-native
Activate an existing inactive version (write)	sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>	Reactivation path only (Phase 2b) — skips create/publish
Verify agent is live (read)	sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json	<verifyId> = create path's publishedBotId (Phase-5) or the Phase-2 classifier's returned live matched Id (its botDefinitionId/agentId) on ALREADY-CREATED / reactivation — not the null Phase-1 template botDefinitionId, never the collected developerName; confirm BotDefinition present + latest version Active

Full command shapes and the ITSM Connect API reference live in references/cli-invocation.md; the reactivation-path call + idempotency verdict table live in references/reactivation.md; the response-body error codes and recurring gotchas live in references/error-taxonomy.md.

Never extract the access token. Use sf api request rest / sf data query directly — they use the CLI's stored session for the target org. Do not pull the accessToken out of sf org display and hand-build an HTTP request with it; that bypasses the CLI session and leaks a bearer token into shell context.

--json rule. sf data query takes --json (results come back in a .result.records[] envelope — that's what the classifier expects). sf api request rest does not — omit --json there; its raw stdout body is already JSON.

---

Clarifying Questions

Collect from the user (ask only what is not already in conversation context):

Field	Default
Target org	Default org (sf config get target-org)
Template (masterLabel)	IT Service Employee (broad umbrella, id svc_emp_intelligence__ItEmployeeAssistance). If the user hints at a specialization (password manager, certificate, onboarding, hardware request, etc.), resolve via references/specialized-templates.md; ambiguous ⇒ AskUserQuestion keyed on id
Developer name	Broad: IT_Service_Employee_Agent. Specialized: substring after __ in the picked id, snake-cased (e.g. PasswordManagerAssistance → Password_Manager_Assistance)
Label	Broad: IT Service Employee Agent. Specialized: the picked template's masterLabel verbatim (e.g. Password Manager Assistance)
Confirm the write	REQUIRED — present resolved template + developerName + label, then require "yes" via AskUserQuestion

The collected <masterLabel>, <developerName>, <label> are threaded through every call — <masterLabel> selects the row in agent-templates.data[] (which also carries the botDefinitionId idempotency key); <developerName>/<label> are used in the createBundleWithVersion body (both outer apiName/label AND the substituted internal config.developer_name/config.agent_label). The idempotency + verify reads key PRIMARILY on the template's botDefinitionId (or, after a fresh create, the publish response's publishedBotId) and fall back to the BotDefinition's AgentTemplate (the OOTB source template = Phase-1 template.id), then to the collected <developerName>, when that is null. A hardcode/collect mismatch on the create body diverges the bundle's outer identity from the script's internal identity.

Idempotency: keyed PRIMARILY on the template's botDefinitionId (Phase-1 agent-templates row — the platform's authoritative template→BotDefinition link), FALLING BACK first to the BotDefinition's AgentTemplate (the OOTB namespaced source template = Phase-1 template.id) and then to the collected <developerName>. The Phase-2 read is BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' (the OR AgentTemplate= half catches the broad pre-provisioned agent by its platform-stamped source template regardless of what DeveloperName it carries; the OR DeveloperName= half is both the last fallback for self-created agents — whose AgentTemplate is null — AND the guard for a dangling Id link whose target BotDefinition was deleted), + latest BotVersion.Status. Outcomes: no match on any key ⇒ create; Active ⇒ ALREADY-CREATED (skip write); Inactive ⇒ Phase-2b reactivation offer. Why the fallback keys: the broad agent ships pre-provisioned as IT_Service_Employee ≠ the guess IT_Service_Employee_Agent (a null-botDefinitionId template row too), so neither the primary key nor the developerName guess catches it — its AgentTemplate (svc_emp_intelligence__ItEmployeeAssistance) is the reliable, rename-immune key that matches it; and for an agent this skill creates (which back-fills neither botDefinitionId nor AgentTemplate), the developerName fallback is what catches a repeat run. The server does reject a duplicate DeveloperName at publish (unique-constraint → bundle cleanup), but only this read turns a repeat into a graceful skip instead of a DUPLICATE_VALUE.

---

Workflow

Substitute <alias> with the collected target org and <developerName> / <label> with the collected values. Full command shapes + per-phase verdict-branch handling live in references/workflow-detail.md — the phase summary below names each step and its load-bearing rule; the reference file holds the exact sf / node invocations to copy.

0. Phase 0 — Establish ${SCRATCH_DIR}. Before any phase writes a transient JSON file, invoke the deterministic helper (path is skill-root-qualified so it resolves regardless of the shell's CWD): SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")". The helper picks the base dir (${TMPDIR}, else /tmp, else the harness ${outputDir} last-resort — scratch stays OUT of the scored ${outputDir} tree) and emits the created dir's absolute path on stdout. Every subsequent phase writes its transient JSON under ${SCRATCH_DIR}; the durable ${outputDir}/report.md stays under the harness dir.
1. Phase 1 — Preflight. Capture the Studio-access read into ${SCRATCH_DIR}/studio-access.json and the agent-templates read (with the required agentType=AgentforceEmployeeAgent query param) into ${SCRATCH_DIR}/agent-templates.json, then classify by passing both file paths, then the label (that arg order): node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" — pass the resolved <masterLabel> ("IT Service Employee" for the broad path or the picked specialization's masterLabel). The classifier emits template.botDefinitionId, template.id, and template.masterLabel from the matched row — capture all three; botDefinitionId is the primary Phase-2 idempotency key, template.id (the BotDefinition's AgentTemplate) the first fallback, and <developerName> the last fallback; masterLabel is the report's display label, not a key. Branch on verdict: READY ⇒ Phase 2; NOT-READY ⇒ prerequisite hand-off via AskUserQuestion (delegate to service-itsm-agentic-setup-agentforce-studio-validate employee path on "yes"); ERROR ⇒ surface + stop; studio.signal="CANNOT-CONFIRM" (confirmed 404) does not block.
2. Phase 2 — Idempotency (primary key botDefinitionId, fallbacks AgentTemplate then <developerName>). Take template.botDefinitionId and template.id from Phase 1. Present botDefinitionId ⇒ SOQL BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' (+ BotVersions subquery — required, else needsActivation is permanently false; the OR clauses make a dangling Id link — deleted target — fall back to the live agent instead of a false exists:false → duplicate create). Empty/null botDefinitionId ⇒ do NOT skip to create; read WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' (the broad pre-provisioned agent is recovered by its OOTB source template even when its DeveloperName differs from the guess; a self-created agent carries a null AgentTemplate, so DeveloperName is its guard). <agentTemplate> is Phase-1 template.id. Either way classify via node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>" "<agentTemplate>". Branch: exists:false ⇒ Phase 3 (create); exists:true + needsActivation:false ⇒ ALREADY-CREATED (skip to Phase 7); exists:true + needsActivation:true ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. Why the fallback keys: the broad agent ships pre-provisioned as IT_Service_Employee with a null template botDefinitionId, so neither the primary key nor the developerName guess (IT_Service_Employee_Agent) catches it — its AgentTemplate (svc_emp_intelligence__ItEmployeeAssistance) matches it by the platform-stamped source template; the developerName fallback catches self-created repeats — a miss on all three re-creates and hits DUPLICATE_VALUE.
3. Phase 2b — Reactivation offer. AskUserQuestion: "Employee agent <developerName> exists but latest version is Inactive. Activate it?". On Yes: POST /connect/bot-versions/<latestVersionId>/activation with {"status":"Active"} — skips Phases 3–6, straight to Phase 7. Aggregate verdict is ACTIVATED, not CREATED. On No: stop, no writes.
4. Phase 3 — Confirm-to-Write (REQUIRED, create path only). If ${outputDir} was provided, first render the checkpoint file via render-report.mjs with verdict:"PENDING CONFIRMATION" (skip for interactive runs). THEN raise the AskUserQuestion gate presenting developerName + label + "NGA-native from the Employee template's Agent Script". Proceed only on explicit "yes"; on "no" (including "hold off on activation" / "not yet" / any decline of the atomic chain), re-render with verdict:"DECLINED" and a one-line reason.
5. Phase 4 — Create. scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json (helper re-reads Phase-1 templates JSON, HTML-decodes the matched agentScript, substitutes internal config.developer_name/config.agent_label, writes body to file — pass the same <masterLabel> used in Phase 1), then POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json. Capture response id — that is the bundleVersionId for Phases 5–6, not bundleId. 403 FUNCTIONALITY_NOT_ENABLED/404 ⇒ trigger the Phase-1 hand-off; build-script exit 3 ⇒ surface stderr.
6. Phase 5 — Publish. POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}' (empty body required). Success: { lastPublishedOn, publishedBotId, publishedBotVersionId } — this call creates the underlying BotDefinition/BotVersion. Any error ⇒ surface verbatim; never activate an unpublished version.
7. Phase 6 — Activate. POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'. Success returns an empty body — check exit code, do not parse a payload.
8. Phase 7 — Verify. SOQL BotDefinition WHERE Id='<id>' (+ BotVersions subquery) and classify — <id> is the create path's publishedBotId (captured from Phase 5) or, on the ALREADY-CREATED / reactivation path, the live matched Id the Phase-2 classifier returned (its botDefinitionId/agentId output — the actual BotDefinition.Id of the matched record), not the Phase-1 template botDefinitionId (which is null on a matchedBy:"developerName" fallback hit → the verify would run WHERE Id='' and falsely report failure after a successful skip/activation). Confirm exists:true, count:1, latestVersionStatus:"Active". Any discrepancy ⇒ report verbatim, do not fabricate success.
9. Phase 8 — Aggregate verdict. Emit CREATED / ALREADY-CREATED / ACTIVATED / FAILED (ACTIVATED on the Phase-2b path) by re-invoking render-report.mjs — the single source of report text. Never surface internal record IDs — the bundle version id, publishedBotId/BotDefinition, or BotVersion — in the verdict, chat narration, or the report; they are captured only to drive the publish/activate/verify calls and mean nothing to the admin. Report by status/name only ("created and activated"), never "Bundle created (version id …)" / "Published (BotDefinition …)". If ${outputDir} was provided, overwrite ${outputDir}/report.md; otherwise emit stdout as the turn-side report.
10. Phase 9 — Runtime-access hand-off (REQUIRED on a live-agent verdict). When the Phase-8 verdict is CREATED, ALREADY-CREATED, or ACTIVATED (a live agent now exists), raise an AskUserQuestion — the same enforced hand-off pattern as the Phase-1 prerequisite and Phase-2b reactivation offers — asking whether to set up the agent's runtime access now: "The agent is live, but its actions call platform features (Prompt Templates, Data Cloud, Unified Catalog) a user can't run until access is granted, so it fails when opened. Set up runtime access now?". On Yes, delegate to service-itsm-agentic-setup-agent-runtime-access-assign (it runs its own target-user selection + confirm-to-write gate). On No, stop — the report's "set up access" next-step line stands as the record. Do NOT raise this on PENDING CONFIRMATION, DECLINED, or FAILED (no live agent to grant access to). This is an enforced AskUserQuestion, not report prose — render-report.mjs still emits its plain-language "set up access" line unchanged; the question is what guarantees the offer is actually made every time.

---

Rules / Constraints