service-itsm-agentic-setup-agent-runtime-access-assign

アクティベート済みITSMエージェントにランタイムアクセスを付与する

ITSMエージェント（Fulfiller または Employee）は作成してアクティベートしても、開いた瞬間に失敗することがあります。そのアクションが、ユーザーには実行できないプラットフォーム機能を呼び出すためです。このスキルは、アクティベーション後に、1回の確認を経て書き込み可能な次の2つの手順でその問題を解消します。

1. ランタイムのアクション実行権限。 プロビジョニング済みの機能権限セットを検出し、ユーザーが機能ごとに階層（ユーザー／エージェントまたは管理者）と、付与するユーザーを選択できるようにしてから割り当てます。ライセンスが必要な場合は、先にライセンスを割り当てます。
2. カスタムの「Agent Access」権限セット。 Agent Accessを作成（または再利用）し、ユーザーが選択したアクティベート済みエージェントに付与します（エージェントごとにSetupEntityAccessを1つ作成）。その後、同じユーザーに割り当てます。

検証済みの機能 → 階層 → 権限セットの対応表はreferences/permset-topology.mdにあります。すべての機能が揃っている組織はありません。プロビジョニング済みのものだけを割り当て、残りは利用不可として報告します。機能が存在しなくても、決して失敗させないでください。

すべての読み取りと書き込みは**Salesforce CLI（sf）**を通じて行います。メタデータ XML、トークンの抽出、MCPは使用しません。

対象範囲

• 対象：プロビジョニング済みのプラットフォーム機能権限セットの検出、機能ごとの階層選択、付与対象ユーザーの確認（実行ユーザーも提示しますが、無断で選ぶことはありません）と特定、ライセンスが必要な階層のPSL→権限セットの冪等な割り当て、カスタムAgent_Access権限セットの作成／再利用、選択されたアクティベート済みエージェントごとのSetupEntityAccess付与の追加、Agent_Accessのユーザーへの割り当て、読み戻しによる割り当ての検証。
• 対象外（担当スキルを括弧内に記載）：Agentforce for IT ServiceのGoトグル／Studio設定（service-itsm-agentic-setup-agentforce-studio-configure）；Employeeエージェント（service-itsm-agentic-setup-employee-agent-configure）またはFulfillerエージェント（service-itsm-agentic-setup-fulfiller-agent-configure）の作成またはアクティベーション；Fulfillerアクティベーションにおけるアクション表示の問題（作成／アクティベーション時のもので、ここで扱うランタイムの問題ではありません。service-itsm-agentic-setup-itsm-agentforce-permset-assign）；CMDBアクセス（service-itsm-agentic-setup-cmdb-access-assign）；ITSM以外の一般的な権限セット割り当て；機能権限セットの作成／編集。

すべての決定論的な判断を担うヘルパースクリプト（すべてBash経由で実行）（A9）

I/Oコントラクトの全文はreferences/helper-contracts.mdにあります。

• scripts/classify-platform-permset-availability.mjs — プロビジョニング済みの機能、各階層のpresentとneedsPsl、および各階層に対する組織独自の表示ラベル。
• scripts/resolve-target-user.mjs — APIルートのidentity URLから取得する実行ユーザーのId（形式が不正な場合は処理を中止）。
• scripts/rank-candidate-users.mjs — 提示する、実在する最大5名の非サービスユーザー候補。対象者に応じて順位付けします（Fulfillerエージェントでは標準ライセンスを優先し、EmployeeエージェントではUnified Employeeを優先）。
• scripts/gate-unified-catalog-tiers.mjs — 付与対象ユーザーごとに、提示するUnified Catalogの階層を決定します（Community User → Unified Employee、Admin → System Administrator）。それ以外の場合、そのユーザーにはUCを提示しません。
• scripts/classify-activated-agents.mjs — アクティベート済みエージェント候補のリスト（1つ以上のActiveなBotVersionを持つBotDefinition InternalCopilot）。
• scripts/classify-agent-access-state.mjs — Agent_Accessを作成する必要があるか、および選択されたエージェントのうち付与がまだ必要なものを判定します（冪等性）。
• scripts/classify-assignment-state.mjs — ユーザーと権限セットの組み合わせごとの冪等性を判定します。選択した階層のneedsPsl:falseの場合は、センチネルNO-PSLを渡します。

---

前提条件

1. sf CLIがインストールされ、対象組織で認証済みであること（sf org display -o <alias>でConnectedと表示されること）。すべての呼び出しで--target-org <alias>を使用します。アクセストークンを手作業で抽出したり渡したりしてはいけません。
2. API v67.0以降。
3. PATH上に**node ≥ 18**があること。

前提条件を満たさない場合、sfは認証エラーまたは401／403／404を返します。生のレスポンスをそのまま報告して停止してください。状態を捏造してはいけません。

---

確認事項

会話から推測できないことだけを質問します。

• 対象組織 — sf エイリアスです。未設定の場合は sf config get target-org を既定値にします。
• 対象ユーザー — 暗黙の既定値は決して使いません。指定されていない場合は、AskUserQuestion で質問します（フェーズ 2 を参照）。指定されている場合は、その指定に従います。
• プロビジョニングする機能ごとのティア — プロビジョニングする機能ごとに、どのティアにするか（軽量な ユーザー／エージェント向けか、完全な 管理者向けか）を質問します。自動選択は決してしません。
• 有効化するエージェント — 有効化済みエージェントの一覧から複数選択します。有効化済みのものが 1 つだけの場合も、必ず確認します。
• 書き込みの確認 — すべての書き込みをまとめて 1 回で確認します。書き込みを行う前に、AskUserQuestion を使って明示的な「はい」を得る必要があります。

---

ワークフロー

すべての呼び出しは sf を介して行います。<alias> は対象組織に置き換えてください。各スクリプトのパスには、必ずスキルの絶対ディレクトリを使用してください。正確なコマンド形式については、references/cli-invocation.md を参照してください。

フェーズ 1 — 読み取り：何がプロビジョニングされ、何が有効化されているか？

1. 6 つのプラットフォーム機能の権限セットをクエリし、ファイルに保存して分類します。

   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
   

   分類器は { features, provisionedFeatures, absentFeatures, verdict } を返します。verdict:"ASSIGNABLE" ⇒ 1 つ以上の機能がプロビジョニングされています。verdict:"NONE-PROVISIONED" ⇒ 割り当て可能な機能の権限セットはありません（それでも Agent Access に関する確認には進みます）。verdict:"CANNOT-CONFIRM" ⇒ 生のエラーを提示して停止します。

2. 有効化済みエージェント（BotDefinition とアクティブバージョンの子クエリ）をクエリし、保存して分類します。

   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" ⇒ 複数選択用に activatedAgents[] を提示します。verdict:"NONE-ACTIVE" ⇒ Agent_Access でアクセス権を付与できるものはありません（その旨を報告します。NONE-PROVISIONED も該当する場合は作業がないため停止します）。

フェーズ 2 — 対象ユーザーの選択（暗黙の既定値は使わない）

3. 実行ユーザーを解決して名前付きの選択肢として提示し、組織内のアクティブユーザーをクエリして、ヘルパーが実在する非サービスユーザーの候補を順位付けし、すぐ選べる候補として提示できるようにします。明示されていない既定値で処理を進めることは決してしません。

   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>
   

   verdict:"RESOLVED" の場合は userId を保持し、ラベル用に /tmp/itsm-running-user.json から Name を取得します。CANNOT-CONFIRM の場合は理由を提示して停止します。プロンプトで対象ユーザーがすでに指定されている場合（「自分に付与して」／ユーザー名など）は、質問せずその指定に従います。それ以外の場合は、この権限付与の対象となるエージェントに基づいて <audience> を設定します。fulfiller（標準ライセンスのユーザーを優先）または employee（Unified Employee ユーザーを優先）、どちらにも該当しなければ any とします。リクエスト／引き継ぎで指定されたエージェント、またはフェーズ 1 の有効化済みエージェント一覧から推測します。rank-candidate-users.mjs は、実在する非サービスユーザーの候補を対象に、指定された対象者向けに順位付けした最大 5 名を返します。これらのユーザーを直接選択肢として提示する AskUserQuestion（複数選択）を必ず使用してください。ユーザー名を通常の文章で尋ねる方法は使いません。実行ユーザー（ラベルは 「Me — 」、または 「Me」。こちらを推奨）と、上位候補を提示します。選択画面には 4 つの選択肢を提示できるため、「Me」と順位上位 3 名の候補を提示します。組み込みの 「Other」 から、一覧にない任意のユーザー名を入力できます。選択または入力された各ユーザーは Username で解決します（クエリ形式は references/cli-invocation.md を参照し、それぞれ専用のファイルに保存します）。非アクティブまたは不明なユーザーはスキップし、その旨を注記します。以下のすべての割り当てには、確認済みのユーザー ID を使用します。

フェーズ 3 — 選択（書き込みなし）

4. プロビジョニング済みの各機能について、AskUserQuestion でティア（ユーザー／エージェントまたは管理者）を尋ね、選択したティアの { name, Id, LicenseId, needsPsl } を記録します。存在しない機能はそれぞれ「この組織ではプロビジョニングされていないためスキップ」として報告します。Unified Catalog は選択したユーザーごとにライセンス形状による制約があります — scripts/gate-unified-catalog-tiers.mjs を、各ユーザー自身のキャプチャを使ってユーザーごとに 1 回実行し、その offer[] のティアのみを提示します。Community User は Unified Employee ユーザーにのみ、Admin は System Administrator にのみ提示します。omit の場合、そのユーザーについて Unified Catalog を「このユーザーのライセンス／プロファイルには該当しないためスキップ」としてスキップします。提示されていないものは、書き込み失敗にはなりません。
5. 有効化済みエージェントのうち、Agent_Access に追加するものを AskUserQuestion で尋ねます（複数選択可）。それらの BotDefinition Id をカンマ区切りのリストとして記録します。

フェーズ 4 — 冪等性の読み取り（書き込みなし）

6. Agent Access の状態。 Agent_Access の permset をクエリし、存在する場合に限り、その既存の BotDefinition 付与をクエリします（キャプチャ先は /tmp/agent-access.json と /tmp/sea.json。クエリ形状は references/cli-invocation.md → フェーズ 4 を参照）。次に、選択したエージェント Id と照合して分類します。

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

   Agent_Access がまだ存在しない場合は、第 2 引数に NO-PERMSET を渡します。分類結果は { permsetExists, permsetId, missingAgentIds, needsCreate, needsGrants, verdict } です。

7. ユーザーと permset の組み合わせごと。 対象ユーザー ×（選択した各機能ティア および Agent_Access）について、既存の割り当てを読み取り（PermissionSetAssignment、および needsPsl:true の場合に限り PermissionSetLicenseAssign。形状は references/cli-invocation.md を参照）、分類します。Agent_Access は単独です（needsPsl:false → NO-PSL）。機能ティアは、その行の needsPsl を使用します。ステップ 6 で Agent_Access が存在しない（needsCreate:true）と判定された場合は、キー指定の PermissionSetAssignment の読み取りをスキップします — permset がないため、判定結果は NEEDS-WRITE です。フェーズ 6 で作成した後、名前で割り当てます。Agent_Access のキー指定の読み取りは、ステップ 6 で既存の permsetId が返された場合に限り実行します。

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

フェーズ 5 — 書き込み前の確認チェックポイント（必須）

8. 統合サマリーを 1 つ提示します — 対象ユーザー全員、割り当てる各機能ティア（およびスキップする各機能）、Agent_Access を作成するかどうかと付与するエージェント、さらにすべての permset 割り当てを含めます。AskUserQuestion で明示的な「はい」の回答を必須とします。「いいえ」の場合は停止し、書き込みを行わずに予定状態を報告します。ライセンスで制限されるティアを割り当てると、ライセンスシートを消費し、ライブセッションに反映されます。

フェーズ 6 — 書き込み（フェーズ 4 で必要と判定されたもののみ）

9. Agent Access 権限セット（1 回のみ）：needsCreate の場合、/sobjects/PermissionSet に {"Name":"Agent_Access","Label":"Agent Access"} を POST し、新しい id を取得します。次に、missingAgentIds の各 ID について、/sobjects/SetupEntityAccess に {"ParentId":"<permsetId>","SetupEntityId":"<agentId>"} を POST します — SetupEntityType は送信しないでください（作成可能な項目ではなく、0Xx キーのプレフィックスから導出されます）。付与時に DUPLICATE_VALUE が返された場合 ⇒ すでに付与済みとして成功扱いにします。

10. 機能階層（ユーザーごと）：フェーズ 4 の判定が NEEDS-WRITE だった各階層について、needsPsl の順に処理します。

    • needsPsl:true — まず、その階層独自の LicenseId を使用して /sobjects/PermissionSetLicenseAssign に PSL を POST し、その後 sf org assign permset --name <tierName> を実行します（実行中のユーザーの場合：--on-behalf-of を省略します。名前指定のユーザーの場合：--on-behalf-of "<username>" を指定します）。
    • needsPsl:false — PSL の POST は省略し、sf org assign permset のみを実行します。

11. Agent Access の割り当て（ユーザーごと）：フェーズ 4 の判定が NEEDS-WRITE の場合、sf org assign permset --name Agent_Access を実行します（実行中のユーザーの場合：--on-behalf-of を省略します。名前指定のユーザーの場合：--on-behalf-of "<username>" を指定します）。--on-behalf-of は Username で解決され、005 ID や $USERNAME シェル変数では解決されません（references/cli-invocation.md を参照）。

    レスポンスの処理（すべての書き込み）：成功 ⇒ 完了。DUPLICATE_VALUE／already has ⇒ 冪等な成功。PSL の POST で INSUFFICIENT_ACCESS／座席数不足が発生 ⇒ 停止し、利用可能な座席がないことをユーザーに伝えます。その他のエラー ⇒ 原文のまま提示し、FAILED とします。（詳しい分類は references/cli-invocation.md を参照。）

フェーズ 7 — 検証と集計

12. 書き込んだ割り当て（対象ユーザーの PermissionSetAssignment／PermissionSetLicenseAssign、Agent_Access の SetupEntityAccess）を再読み込みし、意図した各レコードが存在することを確認します。その後、集計結果を 1 つ報告します。
    • ASSIGNED — 書き込みが 1 件以上行われ、読み戻しですべて確認できた場合。
    • ALREADY-ASSIGNED — 書き込みが必要なものはなく、意図した状態がすでにすべて存在していた場合。
    • PARTIAL — 一部の割り当てには成功したものの、少なくとも 1 件が FAILED になった、または読み戻しで確認できなかった場合。該当するものを列挙します。
    • NONE-PROVISIONED — 機能が 1 つもプロビジョニングされておらず、エージェントも有効化されていないため、割り当てるものがない場合。作成／有効化スキルを案内します。
    • FAILED — 試行したすべての書き込みで、重複以外のエラーが返された場合。エラーをそのまま報告します。

---

ルール／制約

制約	理由
割り当てる前にプロビジョニング済みの機能を検出し、存在しない機能は失敗扱いにせず、「プロビジョニングされていません」と報告する	3 つすべてがそろっている組織はありません。存在しない権限セットを割り当てようとするとエラーになり、実際の状態が隠れてしまいます
プロビジョニング済みの機能ごとに、ユーザー／エージェントと管理者のどちらのティアにするかを確認し、自動選択しない	機能の利用には、より権限の少ないティアで十分です。管理者ティアでは過剰な権限を付与してしまいます
Fulfiller エージェントには standard-license のユーザーを、Employee エージェントには Unified Employee のユーザーを提示する。ランカーはサービスアカウント／ボットアカウントを除外する	対象の組み合わせが間違っていると、そのエージェントを実行できないユーザーが提示されます
Unified Catalog ティアは、そのティアを保持できるユーザーにのみ提示する（Community User → Unified Employee、Admin → System Administrator）。それ以外の場合は、そのユーザーについては省略する。scripts/gate-unified-catalog-tiers.mjs を使用する	UC PSL はライセンス構成によって制限されます。対象外のティアはシート不足ではなく、書き込み時の致命的なエラーになります
利用可否／冪等性／有効化に関する判断はすべてヘルパースクリプトで行い、文章による判断は行わない	書き込み／成功の可否はスクリプトが判定します。スクリプトは決定論的ですが、文章はそうではありません（A9）
needsPsl は選択したティア自身の LicenseId から行ごとに読み取り、その LicenseId を PSL の POST に使用する。PSL 名をハードコードしない	組織によってライセンス構成が異なります。誤った PermissionSetLicenseId を指定すると、別のシートが POST されます
needsPsl:true の場合は、権限セットより先に PSL を割り当てる	権限セットはライセンスに紐付いているため、先にシートを確保します
Agent_Access がアクセスを付与するのは有効化済みのエージェントのみとし、BotDefinition の Id を SetupEntityId とする SetupEntityAccess 行を介して付与する	Apex クラスへのアクセスと同様に、エージェントごとに 1 行のアクセス付与が必要です
SetupEntityAccess の POST には ParentId と SetupEntityId のみを指定し、SetupEntityType は指定しない	作成不可です。SetupEntityId のキー接頭辞から導出されるため、指定するとエラーになります
Agent_Access は、標準データ API で /sobjects/PermissionSet に POST して作成し、Tooling／Metadata XML は使わない	データ API では Name と Label だけで作成でき、デプロイは不要です
いかなる書き込みよりも前に、書き込みに対する確認を一度にまとめて行う	シートの消費数やライブセッションへの影響を含む全計画について、一度の承認を得る必要があります
すべての書き込みで DUPLICATE_VALUE／already has は冪等な成功として扱う	再実行しても安全である必要があります。重複は状態がすでに反映されていることを意味します
ASSIGNED と報告する前に、読み戻して検証する	POST の戻りコードだけでは、行が存在することを証明できません
アクセストークンを決して取り出さず、MCP ディスパッチャーも使用しない	トークンを取り出すと、ベアラー認証情報が漏えいします
CLI の応答に含まれるエラーテキストを正確に報告する	サポート担当者が失敗の原因を診断しやすくなります

---

検証チェックリスト

• プロビジョニング済みの機能は scripts/classify-platform-permset-availability.mjs で分類され、存在しない機能は失敗ではなく「プロビジョニングされていません」と報告された。
• プロビジョニング済みの機能ごとに、ユーザー／エージェントと管理者のどちらのティアにするかが選択され、自動選択されなかった。Unified Catalog のティアは scripts/gate-unified-catalog-tiers.mjs によりユーザーごとに判定された。
• 有効化済みエージェントは scripts/classify-activated-agents.mjs で分類され、アクティブバージョンのエージェントのみが提示された。
• 対象ユーザーが確認された。ユーザー名が指定されていない場合は、黙って選択せず、AskUserQuestion を通じて確認された（実行ユーザー ＋ scripts/rank-candidate-users.mjs による対象者別の順位付けユーザー ＋「その他」）。実行ユーザーは scripts/resolve-target-user.mjs で特定され、指定ユーザーは Username で特定された。
• Agent_Access の作成／付与は scripts/classify-agent-access-state.mjs で判断され、SetupEntityAccess の POST には ParentId と SetupEntityId のみが指定された。
• 書き込み前に、ユーザーと権限セットの組み合わせごとの冪等性が scripts/classify-assignment-state.mjs で分類された。
• needsPsl:true の場合、選択したティア自身の LicenseId に基づいて PSL が POST され、権限セットより先に POST された。
• すべての書き込みより前に、書き込みに対する確認を一度にまとめて行うゲートが実行された。
• DUPLICATE_VALUE／already has は成功として扱われ、その他のエラーはそのまま提示された。
• 割り当ては読み戻して検証され、集約した判定が 1 つ報告された（フェーズ 7 を参照）。

---

出力形式

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

レコード ID、HTTP コード、DUPLICATE_VALUE、オブジェクト名や開発者向け名称などの内部用語は、ユーザー向けの出力に含めないでください。

---

参照ファイルの一覧

ファイル	読むタイミング
references/permset-topology.md	機能／ティアのマトリックスを変更する場合は必ず読みます。6 つのプラットフォーム権限セット、そのティア、PSL、および Agent_Access ／ SetupEntityAccess によるエージェントアクセスの仕組みについて説明しています
references/cli-invocation.md	すべてのフェーズで読みます。sf data query ／ sf api request rest の POST ／ sf org assign permset の正確な呼び出し形式、--json のルール、トークンを絶対に抽出しないルール、レスポンスのエンベロープ、エラーの分類について説明しています
references/helper-contracts.md	7 つすべてのヘルパースクリプトの入出力形式と、それぞれの判定結果の解釈方法について説明しています