• 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__

  .

sf

401

403

404

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.

sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>

hasAccess=false

sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>

agentType=AgentforceEmployeeAgent

<masterLabel>

agentScript

sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" -o <alias> --json

botDefinitionId

OR DeveloperName=

botDefinitionId

scripts/classify-agent-existence.mjs

sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>

scripts/build-create-body.mjs

id

sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>

publishedBotId

publishedBotVersionId

BotDefinition

BotVersion

sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>

sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>

sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json

<verifyId>

publishedBotId

botDefinitionId

agentId

botDefinitionId

BotDefinition

references/cli-invocation.md

references/reactivation.md

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.

<alias>

<developerName>

<label>

references/workflow-detail.md

sf

node

1. 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.
2. Phase 1 — Preflight. Capture the Studio-access read +

   agent-templates

   read (with the required

   agentType=AgentforceEmployeeAgent

   query param), then classify via

   scripts/classify-preflight.mjs "<masterLabel>"

   — pass the resolved

   <masterLabel>

   (

   "IT Service Employee"

   for the broad path or the picked specialization's

   masterLabel

   ). The classifier also emits

   template.botDefinitionId

   from the matched row — capture it; it is the primary Phase-2 idempotency key (the collected

   <developerName>

   is the fallback 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.
3. Phase 2 — Idempotency (primary key

   botDefinitionId

   , fallback key

   <developerName>

   ). Take

   template.botDefinitionId

   from Phase 1. Present ⇒ SOQL

   BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'

   (+

   BotVersions

   subquery — required, else

   needsActivation

   is permanently false; the

   OR

   clause makes a dangling Id link — deleted target — fall back to the live same-name agent instead of a false

   exists:false

   → duplicate create). Empty/null ⇒ do NOT skip to create; fall back to

   WHERE DeveloperName='<developerName>'

   (a self-created agent's template row is never back-filled, so its

   botDefinitionId

   stays null even though the agent exists). Either way classify via

   scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"

   . 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 both keys:

   botDefinitionId

   catches the pre-provisioned

   IT_Service_Employee

   (≠ the guess

   IT_Service_Employee_Agent

   ); the

   developerName

   fallback catches self-created repeats — a miss on both re-creates and hits

   DUPLICATE_VALUE

   .
4. 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.
5. 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

   .
6. 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.
7. 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.
8. Phase 6 — Activate.

   POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'

   . Success returns an empty body — check exit code, do not parse a payload.
9. 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.
10. Phase 8 — Aggregate verdict. Emit CREATED / ALREADY-CREATED / ACTIVATED / FAILED (ACTIVATED on the Phase-2b path) +

    BotDefinition

    Id / bundle

    id

    by re-invoking

    render-report.mjs

    — the single source of report text. If

    ${outputDir}

    was provided, overwrite

    ${outputDir}/report.md

    ; otherwise emit stdout as the turn-side report.

• Resolved

  <masterLabel>

  before Phase 1 (broad default or specialization from

  references/specialized-templates.md

  ,

  data[]

  filtered to

  svc_emp_intelligence__

  , disambiguated on

  id

  ).
• Preflight classified by

  classify-preflight.mjs

  (PASS or documented CANNOT-CONFIRM); hand-off offered on FAIL; raw error surfaced on ERROR.
• Idempotency keyed on the template's

  botDefinitionId

  (Phase-1 row) with the collected developerName as fallback;

  BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'

  (the

  OR

  covers both a null and a dangling

  botDefinitionId

  ) + latest

  BotVersion.Status

  (subquery present) read + classified before any write.
• If

  needsActivation:true

  , Phase-2b reactivation offer presented — no silent skip, no duplicate create.
• Explicit user confirmation at Phase 3 (create) or Phase 2b (reactivation) before any write.
• Bundle body built by

  build-create-body.mjs

  , POSTed via

  --body @<file>

  with the collected

  developerName

  /

  label

  ; or write correctly skipped.
• Same

  bundleVersionId

  (response

  id

  ) used for publish + activate; reactivation used

  POST /connect/bot-versions/<id>/activation

  ; legacy

  createAgent

  never called.
• Phase-7 verify confirmed

  BotDefinition

  present + latest version Active.
• Access token never extracted; final verdict +

  BotDefinition

  /bundle Id reported.

• references/specialized-templates.md

  — catalog + namespace filter +

  id

  -based disambiguation (before Phase 1 on any specialization).

• references/workflow-detail.md

  — exact

  sf

  /

  node

  commands + full verdict-branch narrative per phase.

• references/cli-invocation.md

  — command shapes, never-extract-token rule, ITSM Connect API reference, helper-script contracts.

• references/reactivation.md

  — Phase-2b activation call + full idempotency verdict table.

• references/report-format.md

  — rendered shape, phase-state JSON schema, three-checkpoint write policy.

• references/error-taxonomy.md

  — response-body error codes + recurring foot-guns (any non-2xx / empty body / script non-zero exit).