Skip to content

forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-employee-agent-configure

service-itsm-agentic-setup-employee-agent-configure

Unverified

Create and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure).

FileKindSize
SKILL.mdskill md29.4 KB
references/cli-invocation.mdmarkdown22.4 KB
references/error-taxonomy.mdmarkdown4.1 KB
references/reactivation.mdmarkdown4.2 KB
references/report-format.mdmarkdown4.9 KB
references/specialized-templates.mdmarkdown10.5 KB
references/workflow-detail.mdmarkdown18.2 KB
scripts/build-create-body.mjsexecutablescript4.7 KB
scripts/classify-agent-existence.mjsexecutablescript13.5 KB
scripts/classify-preflight.mjsexecutablescript11.4 KB
scripts/create-scratch-dir.mjsexecutablescript2.3 KB
scripts/render-report.mjsexecutablescript12.2 KB

references/workflow-detail.md

View on GitHub
# Employee Agent — Workflow Detail

Detailed per-phase command shapes + verdict narrative for `service-itsm-agentic-setup-employee-agent-configure`. Read this alongside the phase headers in `SKILL.md` — the SKILL body holds the load-bearing rules, this file holds the exact commands and branch-by-branch verdict handling.

All calls go through `sf`; substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values.

## Phase 0 — Establish the per-run scratch directory

Before any phase writes a transient JSON file, invoke `scripts/create-scratch-dir.mjs` — path selection (`${TMPDIR}` → `/tmp` → `${outputDir}` last-resort, keeping transient captures out of the scored `${outputDir}` tree) and the `mkdtemp` call live in the helper so the deterministic logic never sits in prose (A9). Every subsequent phase writes its scratch JSON under `${SCRATCH_DIR}`, so runs never collide and the transient state stays scoped to the run:

```bash
SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"
```

The remaining phases reference `${SCRATCH_DIR}` for every transient path (studio-access, agent-templates, bot-existing, create-bundle-body, publish/activate response captures, report-state, verify). The **durable** run artifact — `${outputDir}/report.md` — is still written to the harness-provided directory.

## Phase 1 — Preflight: confirm Studio access + template provisioning

Capture the Studio-access read and the `agent-templates` read, then let `scripts/classify-preflight.mjs` make the deterministic decisions (never parse `hasAccess` or search `data[]` in prose — A9). The `agent-templates` `agentType` query param is **required** with value `AgentforceEmployeeAgent` (a call without it returns `400 MISSING_ARGUMENT: agentType`):

```bash
sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" \
  --method GET --target-org <alias> > ${SCRATCH_DIR}/studio-access.json 2>${SCRATCH_DIR}/studio-access.err || true
sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" \
  --method GET --target-org <alias> > ${SCRATCH_DIR}/agent-templates.json 2>${SCRATCH_DIR}/agent-templates.err || true
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 default broad path, or the picked specialized template's `masterLabel` (e.g. `"Password Manager Assistance"`) for a specialized path. The classifier matches `data[]` case-insensitively on `masterLabel` and confirms the matched row has a non-empty `agentScript`.

The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,masterLabel,signal}, verdict, reasons }`:

- `template.hasAgentScript:true` confirms the template carries the Agent Script content Phase 4 needs; capture the raw `agent-templates.json` file path — Phase 4 re-reads it directly (via `scripts/build-create-body.mjs`) rather than the classifier re-emitting the full script content.
- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key.** A populated value means this template has already been instantiated into a live `BotDefinition`; a `null` value means it has not been created yet OR it was created by this skill (self-created agents never back-fill the template row) OR — as with the broad pre-provisioned Employee agent — the platform instantiated it without joining the template row back. Capture `botDefinitionId` for Phase 2, and carry the collected `<developerName>` (first fallback) and `template.masterLabel` (second fallback) as the fallback keys.
- `verdict:"READY"` ⇒ continue to Phase 2.
- `verdict:"ERROR"` because `studio.signal="ERROR"` (the Studio-access read returned a parseable but non-404 error body — e.g. `401`/`403`) ⇒ do NOT proceed — surface the raw error and stop. This is a failed prerequisite read, not an unwired gate; do not let a present template push the verdict to READY.
- `verdict:"NOT-READY"` because `studio.signal="FAIL"` (`hasAccess=false`) ⇒ do NOT proceed — **offer the prerequisite hand-off**:
  - Present a single `AskUserQuestion`: _"Agentforce for IT Service prerequisites don't look satisfied on this org. Run `service-itsm-agentic-setup-agentforce-studio-validate` (employee path) to check readiness first?"_ (options: **Yes, check readiness** / **No, stop here**).
  - On **Yes**: delegate to `service-itsm-agentic-setup-agentforce-studio-validate` (read-only readiness check, `employee` agent path). If it reports NOT-READY, stop and report the missing prerequisite (enablement is a Setup-UI/admin action, outside both skills' write scope). If READY, resume from Phase 2.
  - On **No**: stop and report the missing prerequisite verbatim — no writes.
- `verdict:"NOT-READY"` because `template.signal="FAIL"` (empty/no matching template) ⇒ the org is not ITSM-provisioned; hand off to the readiness check.
- `template.signal="CANNOT-CONFIRM"` because the matched template has no `agentScript` ⇒ the NGA create has nothing to build from; surface this and stop (do not fall back to the legacy `createAgent` route — it is out of scope for this skill).
- `studio.signal="CANNOT-CONFIRM"` (a **confirmed** `404` — the access-check gate isn't wired on the org, expected on scratch orgs) does **not** block: a successful create/publish/activate is authoritative. A later `403 FUNCTIONALITY_NOT_ENABLED` on the write is the same signal as `hasAccess=false` — trigger the same hand-off offer.

## Phase 2 — Idempotency: does the target agent already exist, and is it active?

Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1), **FALLS BACK** first to the BotDefinition's `AgentTemplate` (the OOTB namespaced source template = Phase-1 `template.id`), and then to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into, but that link is populated **only** when the platform joined the row back — which it does NOT do for the broad pre-provisioned Employee agent (it ships active under DeveloperName `IT_Service_Employee` with a `null` template `botDefinitionId`) nor for an agent this skill creates (which never stamps `templateName`). So for the broad agent both the primary key and the `DeveloperName` guess miss (`IT_Service_Employee` ≠ the default `IT_Service_Employee_Agent`), and the `AgentTemplate`-keyed fallback — matching `svc_emp_intelligence__ItEmployeeAssistance`, the platform-stamped source template on the live `BotDefinition`, immune to any rename — is what recovers it; for a self-created repeat (null `AgentTemplate` too) the `DeveloperName` fallback is the guard. Never short-circuit to create when `botDefinitionId` is absent.

- **`template.botDefinitionId` is empty/null** (the broad pre-provisioned agent AND every self-created agent) ⇒ fall back to an `AgentTemplate` **`OR` `DeveloperName`** read (do **not** short-circuit to create — the broad agent is recovered by its OOTB source template, and a self-created agent from a prior run has a null template `botDefinitionId` but still exists). The `BotVersions` subquery is required — omitting it leaves `needsActivation` permanently false and hides the reactivation path:
  ```bash
  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" \
    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>" "<agentTemplate>"
  ```
- **`template.botDefinitionId` is present** ⇒ read the `BotDefinition` by Id **`OR` by the template's `AgentTemplate` `OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR AgentTemplate=` clause catches the pre-provisioned agent by its platform-stamped source template (`matchedBy:"agentTemplate"`) regardless of its DeveloperName. The `OR DeveloperName=` clause catches a **dangling** template→BotDefinition link — a `botDefinitionId` whose target row was since deleted: the by-Id half returns nothing, but the live same-name agent still surfaces, so the classifier falls back to it (`matchedBy:"developerName"`) instead of concluding `exists:false` and letting the create collide with `DUPLICATE_VALUE`:
  ```bash
  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>'" \
    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>" "<agentTemplate>"
  ```

The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"agentTemplate"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record (e.g. `IT_Service_Employee`), surface it in the report rather than the collected guess:

- `exists:false` ⇒ proceed to Phase 3 (create path).
- `exists:true` and `needsActivation:false` (latest version `Active`) ⇒ **ALREADY-CREATED** — skip the write, fall through to Phase 7 verification.
- `exists:true` and `needsActivation:true` (latest version `Inactive`) ⇒ do **not** create a duplicate agent — go to Phase 2b to offer activating the existing version instead.
- A non-zero exit (exit 3) means the query itself failed — surface the raw CLI error, do not assume the agent is absent.

## Phase 2b — Reactivation offer (existing agent found inactive)

Present the discovery to the user via `AskUserQuestion`: _"An Employee agent named `<developerName>` already exists but its latest version is Inactive. Activate the existing version instead of creating a new agent?"_ (options: **Yes, activate the existing version** / **No, stop here**).

- On **Yes**: activate the captured `latestVersionId` directly — no create/publish needed since the `BotDefinition`/`BotVersion` already exist:
  ```bash
  sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" \
    --method POST --body '{"status":"Active"}' \
    --target-org <alias> > ${SCRATCH_DIR}/activate-existing.json 2>${SCRATCH_DIR}/activate-existing.err || true
  ```
  On success, skip Phases 3–6 entirely (no create/publish/confirm-to-write for a fresh agent) and go straight to Phase 7 to verify. Report the aggregate verdict as **ACTIVATED** in Phase 8, not CREATED.
- On **No**: stop and report the current state (agent exists, latest version Inactive) without any writes.

## Phase 3 — Confirm-to-Write Checkpoint (REQUIRED, create path only)

**Before raising the confirmation gate**, if `${outputDir}` was provided (via the harness's generated-file location directive), render the report file via `scripts/render-report.mjs` with `verdict:"PENDING CONFIRMATION"` so it exists even if the harness parks at the question. Skip this write for interactive runs where no `${outputDir}` was passed. Report-state JSON shape lives in `references/report-format.md`.

```bash
node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
```

Report-state JSON shape:

```json
{
  "org": "<alias>",
  "template": {"masterLabel": "...", "id": "...", "kind": "broad umbrella"|"specialized"},
  "developerName": "...",
  "label": "...",
  "preflight": {"studioHasAccess": true|false, "templateAgentScriptPresent": true|false},
  "enumerate": {"existsBeforeWrite": true|false, "latestVersionStatus": "Active"|"Inactive"|"n/a"},
  "confirmToWrite": "pending",
  "verdict": "PENDING CONFIRMATION",
  "reason": "Run is paused at the confirm-to-write gate awaiting the user's explicit \"yes\"."
}
```

THEN **present the exact create request** (developerName + label, that this creates an NGA-native agent from the Employee template's Agent Script) and require an explicit "yes" via `AskUserQuestion`. **Proceed to Phase 4 ONLY on an explicit "yes".** On "no" (including "hold off on activation" / "not yet" / any decline of the atomic chain), stop and — if `${outputDir}` was provided — re-render with `verdict:"DECLINED"` and a one-line `reason` naming the user's decline. Never fabricate a partial "create-only" outcome.

## Phase 4 — Create the NGA bundle

Build the `createBundleWithVersion` request body with the helper — it re-reads the Phase-1 `agent-templates.json`, extracts the matched template's `agentScript`, fully HTML-decodes it, and substitutes its internal `config.developer_name` / `config.agent_label` with the **collected** `<developerName>` / `<label>` (so the bundle's outer `apiName` and the script's internal identity match). This also keeps the large script content and any free-text quotes/apostrophes out of an inline shell string:

```bash
node "<skill_dir>/scripts/build-create-body.mjs" ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json
sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" \
  --method POST \
  --body @${SCRATCH_DIR}/create-bundle-body.json \
  --target-org <alias> > ${SCRATCH_DIR}/create-bundle.json 2>${SCRATCH_DIR}/create-bundle.err || true
```

Pass the same resolved `<masterLabel>` used in Phase 1 — the builder re-reads `${SCRATCH_DIR}/agent-templates.json`, re-locates the row by `masterLabel`, decodes its `agentScript`, and substitutes the collected `<developerName>`/`<label>` into the script's internal `config.developer_name`/`config.agent_label` before writing the bundle body.

On success, the `POST /nextgen-authoring/bundles` response is a bundle-version detail: `{ apiName, label, bundleId, id, versionStatus:"DRAFT", assets:[...], ... }`. **Capture `id` — that is the `bundleVersionId` used in Phases 5 and 6, not `bundleId`.**

- `403 FUNCTIONALITY_NOT_ENABLED` / `404` → trigger the Phase-1 prerequisite hand-off offer (the NGA authoring namespace isn't provisioned on the org).
- A build-script exit 3 (template or `agentScript` not found in `${SCRATCH_DIR}/agent-templates.json`) → surface the script's stderr verbatim and stop; do not retry with a hand-typed template id.

## Phase 5 — Publish the bundle version

Publish the captured `bundleVersionId` — empty `--body '{}'` required (the CLI rejects a POST with no `--body`):

```bash
sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" \
  --method POST --body '{}' \
  --target-org <alias> > ${SCRATCH_DIR}/publish-bundle.json 2>${SCRATCH_DIR}/publish-bundle.err || true
```

On success: `{ lastPublishedOn, publishedBotId, publishedBotVersionId }`. This is the call that creates the underlying `BotDefinition`/`BotVersion`. An error here means the DRAFT version failed platform-side validation — surface it verbatim; do not attempt to activate an unpublished version.

## Phase 6 — Activate the bundle version

Activate the same `bundleVersionId`:

```bash
sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" \
  --method POST --body '{}' \
  --target-org <alias> > ${SCRATCH_DIR}/activate-bundle.json 2>${SCRATCH_DIR}/activate-bundle.err || true
```

Success returns an **empty body** — do not treat empty stdout as a failure; check the CLI exit code and fall through to Phase 7 to confirm via `BotDefinition`/`BotVersion` state instead of parsing a response payload.

## Phase 7 — Verify the agent is live

Read `BotDefinition` by Id (with `BotVersions` subquery, same shape as Phase 2) and classify. The verify `<verifyId>` is the create path's **`publishedBotId`** (captured from the Phase-5 publish response) 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 — using it would run the verify as `WHERE Id=''` and falsely report failure after a successful skip/activation). Never the collected `<developerName>`:

```bash
sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<verifyId>'" \
  --target-org <alias> --json > ${SCRATCH_DIR}/bot-verify.json 2>${SCRATCH_DIR}/bot-verify.err || true
node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-verify.json "<verifyId>"
```

Confirm `exists:true` with `count:1`, and — on the create or reactivation path — `latestVersionStatus:"Active"`. `exists:false` after a successful activate ⇒ report the discrepancy verbatim, do not fabricate success. Optionally cross-check `GET /nextgen-authoring/bundles` for an entry with the collected `apiName` and `isLegacy:false` to confirm the agent is NGA-native (no external-link icon in Agentforce Studio).

## Phase 8 — Aggregate verdict

Report the verdict (CREATED / ALREADY-CREATED / ACTIVATED / FAILED). Use **ACTIVATED** when Phase 2b's reactivation path was taken (existing agent found inactive, activated instead of creating new). **Do not surface internal record IDs** (the bundle version `id`, `publishedBotId`/`BotDefinition`, `BotVersion`) in the verdict, report, or chat narration — they drive the publish/activate/verify calls but mean nothing to the admin; report by status/name only. Emit the final report by re-invoking `scripts/render-report.mjs` with the fully populated phase-state JSON (it renders status-only rows and scrubs any stray ID). If `${outputDir}` was provided, overwrite `${outputDir}/report.md`; otherwise emit the helper's stdout as the turn-side report.

```bash
node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
```
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall