Service Itsm Agentic Setup Agent Runtime Access Assign

Grant Runtime Access for an Activated ITSM Agent

An ITSM agent (Fulfiller or Employee) can be created and activated, yet fail the moment it's opened — its actions call platform features the user can't execute. This skill closes that gap after activation via two write-capable steps behind one confirmation:

1. Runtime action-execution permissions. Detect which feature permission sets are provisioned, let the user pick a tier per feature (user/agent vs admin) and which user(s) to grant, then assign — license first when license-gated.
2. A custom "Agent Access" permission set. Create (or reuse) Agent Access, grant the activated agents the user chooses (one SetupEntityAccess per agent), then assign it to the same user(s).

The verified feature → tier → permset matrix lives in references/permset-topology.md. No org has all three features — assign only what is provisioned and report the rest as unavailable, never failing on an absent feature.

Every read and write runs through the Salesforce CLI (sf) — no metadata XML, no token extraction, no MCP.

Scope

• In scope: detecting which platform feature permsets are provisioned; per-feature tier selection; asking which user(s) to grant (running user offered, never silent) and resolving them; PSL-then-permset assignment (license-gated tiers) idempotently; creating/reusing the custom Agent_Access permission set; adding a SetupEntityAccess grant per chosen activated agent; assigning Agent_Access to the user(s); verifying assignments by read-back.
• Out of scope (owning skill parenthesized): the Agentforce for IT Service Go toggles / Studio config (service-itsm-agentic-setup-agentforce-studio-configure); creating or activating the Employee (service-itsm-agentic-setup-employee-agent-configure) or Fulfiller (service-itsm-agentic-setup-fulfiller-agent-configure) agent; the Fulfiller activation action-surfacing gap (create/activate-time, not this runtime one — service-itsm-agentic-setup-itsm-agentforce-permset-assign); CMDB access (service-itsm-agentic-setup-cmdb-access-assign); generic non-ITSM permission-set assignment; authoring/editing feature permsets.

Helper scripts (all invoked via Bash) hold every deterministic decision (A9)

Full I/O contracts in references/helper-contracts.md.

• scripts/classify-platform-permset-availability.mjs — which features are provisioned, each tier's present + needsPsl, and the org's own display label per tier.
• scripts/resolve-target-user.mjs — running-user Id from the API-root identity URL (fails closed on a malformed shape).
• scripts/rank-candidate-users.mjs — up to five real, non-service candidate users to offer, ranked by audience (standard-license first for a Fulfiller agent, Unified Employee first for an Employee agent).
• scripts/gate-unified-catalog-tiers.mjs — per target user, which Unified Catalog tiers to offer (Community User → Unified Employee; Admin → System Administrator), else omit UC for that user.
• scripts/classify-activated-agents.mjs — the activated-agent candidate list (BotDefinition InternalCopilot with ≥1 Active BotVersion).
• scripts/classify-agent-access-state.mjs — whether Agent_Access must be created and which chosen agents still need a grant (idempotency).
• scripts/classify-assignment-state.mjs — per user+permset idempotency; pass the sentinel NO-PSL when the selected tier's needsPsl:false.

Preconditions

1. sf CLI installed and authenticated to the target org (sf org display -o <alias> shows Connected). All calls use --target-org <alias>; never extract or pass the access token by hand.
2. API v67.0+.
3. node ≥ 18 on PATH.

If a precondition fails, sf surfaces an auth or 401/403/404; report the raw response verbatim and stop — do not fabricate state.

Clarifying questions

Ask only what cannot be inferred from conversation:

• Target org — the sf alias. Default to sf config get target-org if unset.
• Target user(s) — never a silent default: if unnamed, ASK via AskUserQuestion (see Phase 2); if named, honor it.
• Tier per provisioned feature — for EACH provisioned feature, ask which tier (lighter user/agent vs full admin); never auto-select.
• Which activated agents — multi-select from the activated-agent list; if only one is activated, still confirm it.
• Confirm the write — one consolidated confirmation covering every write; require an explicit "yes" via AskUserQuestion before any write.

Workflow

All calls go through sf; substitute <alias> with the target org. Use the skill's absolute directory for every script path. Exact command shapes: references/cli-invocation.md.

Phase 1 — Read: what is provisioned, and what is activated?

1. Query the six platform feature permsets, capture to a file, and classify:

   sf data query \
     -q "SELECT Id, Name, Label, LicenseId FROM PermissionSet WHERE Name IN ('EinsteinGPTPromptTemplateUser','EinsteinGPTPromptTemplateManager','GenieUserEnhancedSecurity','GenieAdmin','UnifiedCatalogCommunityUser','UnifiedCatalogAdmin')" \
     --target-org <alias> --json > /tmp/itsm-platform-permsets.json 2>/tmp/itsm-platform-permsets.err || true
   node "<skill_dir>/scripts/classify-platform-permset-availability.mjs" /tmp/itsm-platform-permsets.json
   

   The classifier returns { features, provisionedFeatures, absentFeatures, verdict }. verdict:"ASSIGNABLE" ⇒ ≥1 feature is provisioned; verdict:"NONE-PROVISIONED" ⇒ no feature permset can be assigned (still continue to the Agent Access concern); verdict:"CANNOT-CONFIRM" ⇒ surface the raw error and stop.

2. Query the activated agents (BotDefinition + active-version child subquery), capture, and classify:

   sf data query \
     -q "SELECT Id, DeveloperName, MasterLabel, (SELECT Status FROM BotVersions WHERE Status='Active') FROM BotDefinition WHERE Type='InternalCopilot'" \
     --target-org <alias> --json > /tmp/itsm-agents.json 2>/tmp/itsm-agents.err || true
   node "<skill_dir>/scripts/classify-activated-agents.mjs" /tmp/itsm-agents.json
   

   verdict:"AGENTS-FOUND" ⇒ present activatedAgents[] for the multi-select; verdict:"NONE-ACTIVE" ⇒ there is nothing for Agent_Access to grant (report it; if NONE-PROVISIONED also holds there is no work — stop).

Phase 2 — Choose target user(s) (never a silent default)

3. Resolve the running user (to offer as a labelled option) and query active org users so a helper can rank real, non-service candidates to offer as ready picks — never proceed with an unstated default:

   sf api request rest "/services/data/v67.0/" --method GET --target-org <alias> > /tmp/api-root.json 2>/tmp/api-root.err || true
   node "<skill_dir>/scripts/resolve-target-user.mjs" /tmp/api-root.json
   sf data query -q "SELECT Name, Profile.Name, Profile.UserLicense.Name FROM User WHERE Id='<userId>'" --target-org <alias> --json > /tmp/itsm-running-user.json 2>/dev/null || true
   sf data query -q "SELECT Id, Name, Username, Profile.Name, Profile.UserLicense.Name FROM User WHERE IsActive = true ORDER BY LastLoginDate DESC NULLS LAST LIMIT 25" --target-org <alias> --json > /tmp/itsm-candidate-users.json 2>/dev/null || true
   node "<skill_dir>/scripts/rank-candidate-users.mjs" /tmp/itsm-candidate-users.json <audience> <userId>
   

   On verdict:"RESOLVED" keep userId; take its Name from /tmp/itsm-running-user.json for the label; on CANNOT-CONFIRM surface the reasons and stop. If the prompt already named the target user(s) ("grant me" / a username), honor it without asking. Otherwise set <audience> from the agent this grant is for — fulfiller (prefer standard-license users) or employee (prefer Unified Employee users), else any — inferring it from the agent named in the request/handoff or the Phase-1 activated set; rank-candidate-users.mjs returns up to five real, non-service candidates ranked for that audience. Present an AskUserQuestion (multi-select) with those users as direct selectable options — never a plain-prose username request: the running user (labelled "Me — ", or just "Me"; recommended) plus the top candidates. The picker allows four options, so offer "Me" + the top three ranked candidates; its built-in "Other" takes any username(s) not listed. Resolve each chosen/typed user by Username (query shape in references/cli-invocation.md, capturing each to its own file); skip inactive/unknown with a note. The confirmed user Ids drive every assignment below.

Phase 3 — Selections (no writes)

4. For each provisioned feature, ask the tier (user/agent vs admin) via AskUserQuestion and record the selected tier's { name, Id, LicenseId, needsPsl }; report each absent feature as "not provisioned on this org — skipped". Unified Catalog is license-shape gated per selected user — run scripts/gate-unified-catalog-tiers.mjs once per user against that user's own capture and offer only its offer[] tiers: Community User only to a Unified Employee user, Admin only to a System Administrator; on omit, skip Unified Catalog for that user as "not applicable for this user's license/profile — skipped" — never offered, never a failed write.
5. Ask which activated agents to add to Agent_Access via AskUserQuestion (multi-select). Record their BotDefinition Ids as a comma-separated list.

Phase 4 — Idempotency reads (no writes)

6. Agent Access state. Query the Agent_Access permset and (only if it exists) its existing BotDefinition grants — capture to /tmp/agent-access.json and /tmp/sea.json (query shapes in references/cli-invocation.md → Phase 4) — then classify against the chosen agent Ids:

   node "<skill_dir>/scripts/classify-agent-access-state.mjs" /tmp/agent-access.json <sea.json|NO-PERMSET> "<chosenAgentIds-csv>"
   

   Pass NO-PERMSET for the second arg when Agent_Access does not exist yet. The classifier returns { permsetExists, permsetId, missingAgentIds, needsCreate, needsGrants, verdict }.

7. Per user + permset. For each target user × (each selected feature tier and Agent_Access), read existing assignments (PermissionSetAssignment, plus PermissionSetLicenseAssign only when needsPsl:true; shapes in references/cli-invocation.md) and classify. Agent_Access is standalone (needsPsl:false → NO-PSL); a feature tier uses needsPsl from its own row. If step 6 flagged Agent_Access absent (needsCreate:true), skip its keyed PermissionSetAssignment read — no permset ⇒ verdict NEEDS-WRITE; Phase 6 creates it, then assigns by name. Run the keyed read for Agent_Access only when step 6 returned an existing permsetId:

   node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa.json </tmp/psla.json|NO-PSL>
   

Phase 5 — Confirm-to-write checkpoint (REQUIRED)

8. Present ONE consolidated summary — every target user, each feature tier to assign (and each absent feature being skipped), whether Agent_Access will be created and which agents it will grant, and every permset assignment — and require an explicit "yes" via AskUserQuestion. On "no", stop and report the planned state with no writes. Assigning a license-gated tier consumes a license seat and takes effect for a live session.

Phase 6 — Writes (only what Phase 4 flagged as needed)

9. Agent Access permset (once): if needsCreate, POST to /sobjects/PermissionSet {"Name":"Agent_Access","Label":"Agent Access"} and capture the new id. Then for each Id in missingAgentIds, POST to /sobjects/SetupEntityAccess {"ParentId":"<permsetId>","SetupEntityId":"<agentId>"} — do not send SetupEntityType (it is not createable; it is derived from the 0Xx key prefix). DUPLICATE_VALUE on a grant ⇒ already granted, treat as success.

10. Feature tiers, per user, for each tier whose Phase 4 verdict was NEEDS-WRITE, ordered by needsPsl:

    • needsPsl:true — POST the PSL to /sobjects/PermissionSetLicenseAssign (using the tier's own LicenseId) FIRST, then sf org assign permset --name <tierName> (running user: omit --on-behalf-of; named user: --on-behalf-of "<username>").
    • needsPsl:false — skip the PSL POST; run sf org assign permset only.

11. Agent Access assignment, per user: sf org assign permset --name Agent_Access (running user: omit --on-behalf-of; named user: --on-behalf-of "<username>") when its Phase 4 verdict was NEEDS-WRITE. --on-behalf-of resolves by Username, never a 005 Id or a $USERNAME shell var (see references/cli-invocation.md).

    Response handling (all writes): success ⇒ done; DUPLICATE_VALUE/already has ⇒ idempotent success; INSUFFICIENT_ACCESS/seat-exhaustion on a PSL POST ⇒ STOP and tell the user no seats are available; any other error ⇒ surface verbatim, mark FAILED. (Full taxonomy in references/cli-invocation.md.)

Phase 7 — Verify + aggregate

12. Re-read the assignments written (PermissionSetAssignment / PermissionSetLicenseAssign for the target user(s); SetupEntityAccess for Agent_Access) and confirm each intended row is present. Then report one aggregate verdict:
    • ASSIGNED — at least one write occurred and every read-back confirms it.
    • ALREADY-ASSIGNED — nothing needed writing; all intended state was already present.
    • PARTIAL — some assignments succeeded and at least one FAILED or didn't read back. List which.
    • NONE-PROVISIONED — no feature provisioned AND no agent activated: nothing to assign. Point at the create/enable skills.
    • FAILED — every attempted write returned an error other than a duplicate. Report the raw errors.

Rules / Constraints

Verification Checklist

• Provisioned features classified by scripts/classify-platform-permset-availability.mjs; absent reported "not provisioned", not failed.
• A tier (user/agent vs admin) was chosen per provisioned feature — no auto-selection; Unified Catalog tiers gated per user by scripts/gate-unified-catalog-tiers.mjs.
• Activated agents classified by scripts/classify-activated-agents.mjs; only active-version agents were offered.
• Target user(s) confirmed — when unnamed, asked via AskUserQuestion (running user + audience-ranked users from scripts/rank-candidate-users.mjs + "Other"), never silent. Running user via scripts/resolve-target-user.mjs; named by Username.
• Agent_Access create/grant decided by scripts/classify-agent-access-state.mjs; SetupEntityAccess POSTs sent ParentId+SetupEntityId only.
• Per user+permset idempotency classified by scripts/classify-assignment-state.mjs before any write.
• The selected tier's own LicenseId drove the PSL POST when needsPsl:true, POSTed before the permset.
• One consolidated confirm-to-write gate preceded every write.
• DUPLICATE_VALUE / already has treated as success; other errors surfaced verbatim.
• Assignments verified by read-back; one aggregate verdict reported (see Phase 7).

Output Format

ITSM Agent Runtime-Access Assignment (via service-itsm-agentic-setup-agent-runtime-access-assign)

Org:            <org-alias> (API v67.0)
Target user(s): <username> (<userId>)[, ...]

Runtime action permissions:
  Prompt Templates ...... <tier chosen: User | Manager | skipped | not provisioned>  -> <assigned | already-had | FAILED>
  Data Cloud ............ <tier chosen | skipped | not provisioned>                   -> <assigned | already-had | FAILED>
  Unified Catalog ....... <tier chosen | skipped | not provisioned>                   -> <assigned | already-had | FAILED>

Agent Access permission set:
  Permission set ........ <created | already existed>
  Agents granted ........ <comma-separated agent names, or none>
  Assigned to user(s) ... <assigned | already-had | FAILED>

Verdict: ASSIGNED | ALREADY-ASSIGNED | PARTIAL | NONE-PROVISIONED | FAILED
Reason:  <plain-language explanation, or empty on success>

Next steps:
  - <If ASSIGNED / ALREADY-ASSIGNED: "The user can now open and exercise the agent(s) in Agentforce Studio — action calls should no longer fail on missing permissions.">
  - <If PARTIAL: list which assignments succeeded and which failed, verbatim.>
  - <If NONE-PROVISIONED: nothing to assign — create/activate an agent and enable its features first.>
  - <If FAILED: list the observed error(s) verbatim + remediation.>

Keep internal jargon (record Ids, HTTP codes, DUPLICATE_VALUE, object/dev names) out of user-facing output.

Reference File Index