service-itsm-agentic-setup-agentforce-studio-validate

Agentforce for IT Service の前提条件を検証する

Fulfiller または Employee エージェントのいずれかのパスについて、Agentforce for IT Service の準備状況を確認します。ITSM エージェントを作成する前に、組織で適切な Salesforce Go の機能トグル（Agentforce for IT Service の設定ページにある項目）を有効にする必要があります。このスキルは Salesforce CLI（sf） を介してこれらのトグルを読み取ります。sf api request rest による Connect API の認証済み呼び出しを 1 回行い、ヘルパースクリプトが選択されたエージェントパスを READY／NOT-READY に分類します。

これは 3 スキルのフローにおける読み取り専用の手順です。何も有効化しません。トグルを有効にする操作は、別の書き込み可能なスキルで行います。

手順	スキル	処理内容
1. 検証（このスキル）	service-itsm-agentic-setup-agentforce-studio-validate	トグルを読み取る → READY／NOT-READY（書き込みなし）
2. 設定	service-itsm-agentic-setup-agentforce-studio-configure	無効なトグルを ON にする
3. エージェントの作成	service-itsm-agentic-setup-fulfiller-agent-configure	Fulfiller エージェントを作成して有効化する

NOT-READY の場合、このスキルは無効なトグルをそれぞれ示し、有効化のために service-itsm-agentic-setup-agentforce-studio-configure に引き継ぎます。このスキル自体が有効化の POST を行うことはありません。

機能トグルと、実際の featureApiName は次のとおりです。

Go ページのトグル	featureApiName	必要なパス
Agentforce Studio を有効にする	sales-cloud-agent-studio	両方のパス（共通）
Agentforce for IT Service	service-cloud-agentforce-for-itsm	両方のパス（共通）
IT Service Fulfiller Template	service-cloud-it-fulfiller-agent	fulfiller
IT Service Employee Template	service-cloud-requestor-agent	employee
Specialized Agent Templates for Employee	service-cloud-it-service-employee-agent	employee

すべて Connect API の機能（/connect/setup/discovery/...）です。読み取りには sf api request rest を使用し、Headless360 ディスパッチャーは不要です。分類は 決定論的であり、文章ではなく scripts/classify-readiness.mjs（Bash 経由で実行）に実装されています。

対象範囲

• 対象：connect/setup/discovery/features/status を介した Agentforce for IT Service の Go 機能トグルの読み取り、ヘルパースクリプトによる fulfiller または employee パスの機能ごとおよび全体の READY／NOT-READY 判定、NOT-READY の場合に無効なトグルをそれぞれ示し、有効化のために service-itsm-agentic-setup-agentforce-studio-configure に引き継ぐこと。
• 対象外：トグルの有効化（その書き込み操作は service-itsm-agentic-setup-agentforce-studio-configure が担当します。このスキルは読み取り専用で、有効化の POST は行いません）、エージェントの作成、コミット、有効化（service-itsm-agentic-setup-fulfiller-agent-configure が担当）、組織全体のマルチエージェントオーケストレーション用トグル（これは Headless360 専用の設定であり、ITSM Connect の機能でも設定ページのトグルでもありません）、権限セットの割り当て、CMDB の CRUD 操作。

---

どちらのパスですか？

ユーザーが fulfiller エージェント（IT 担当者向けエージェント）と employee エージェント（従業員向け／NGA エージェント）のどちらを設定しているか判断します。依頼内容から明確でない場合は、確認してください（AskUserQuestion）。パスによって必要なトグルが決まります。

• fulfiller → sales-cloud-agent-studio + service-cloud-agentforce-for-itsm + service-cloud-it-fulfiller-agent
• employee → sales-cloud-agent-studio + service-cloud-agentforce-for-itsm + service-cloud-requestor-agent + service-cloud-it-service-employee-agent

---

前提条件

このスキルが何かを読み取る前に、CLI と対象 org を設定する必要があります。いずれかの条件を満たしていない場合、sf は認証エラーまたは 401／403／404 を返します。状態を捏造せず、生のエラーをそのまま表示して停止してください。

1. sf CLI がインストールされ、対象 org に認証済みであること（sf org display -o <alias> に Connected と表示される）。すべての呼び出しで --target-org <alias> を使用してください。アクセストークンを手動で取り出したり渡したりしないでください。
2. API v67.0 以上：connect/setup/discovery 機能 API は v67.0 で利用可能です。バージョンは URL パスに固定されています。最低バージョンを下回るよう手動で編集しないでください。
3. PATH 上に node ≥ 18 があること（分類スクリプトの実行に使用）。

前提条件を満たしていない場合、sf は次のいずれかを返します。

• 認証エラー／401 Unauthorized → セッションの期限切れ、またはエイリアスの誤りです。sf org login web を再実行してください。
• 403 Forbidden → ユーザー／org に必要なアクセス権がありません（Agentforce ライセンスがありません）。
• 404 Not Found → この org のティアでは機能検出のエンドポイントが接続されていません。分類スクリプトは、本文がない場合やエラー本文を CANNOT-CONFIRM に分類し、致命的な失敗とはしません。

---

操作の概要

操作	コマンド	戻り値
機能トグルの読み取り	sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" --method POST --body '{"featureApiNames":[...]}' --target-org <alias>	{items:[{apiName,status,enableBlockedReasons[],dependencyStatuses[]}]} — status はトグルごとに ENABLED／NOT_ENABLED です。

このスキルが行うのは、上記の読み取りのみです。読み取り専用です。トグルの有効化（.../feature/{apiName}/enable）は対象外です。service-itsm-agentic-setup-agentforce-studio-configure に引き継いでください。sf api request rest は生の応答本文（JSON）を標準出力に出力します。これをファイルに保存し、分類スクリプトに渡してください。コマンドの完全な形式とエラー分類については、references/cli-invocation.md を参照してください。

アクセストークンを取り出さないでください。 sf api request rest を直接使用してください。対象 org の CLI に保存されたセッションが使われます。sf org display から accessToken を取り出して、アクセストークンを含む HTTP リクエストを手動で作成しないでください。これは CLI セッションを迂回し、シェルのコンテキストにベアラートークンを漏えいさせます。

---

アーキテクチャ — チェックの仕組み

手順	内容	使用するツール
パスを選択	fulfiller と employee のどちらかを判断します（不明な場合は質問します）	AskUserQuestion
トグルを読み取る	パスに必要なすべてのトグルについて機能ステータスを一括 POST し、ファイルに保存します	Bash（sf api request rest）
分類	scripts/classify-readiness.mjs <file> <agentType> [exitStatus] を実行し、機能ごとおよび全体の判定結果を取得します	Bash（node）
報告	分類スクリプトの判定結果を出力形式に合わせて表示します	—
引き継ぎ	NOT-READY の場合、無効になっている各トグルを示し、有効化するために service-itsm-agentic-setup-agentforce-studio-configure に引き継ぎます	—

このスキルは読み取り専用です。トグルを有効にすることはありません。

---

ワークフロー

<alias> を対象 org のエイリアスに置き換えます（ユーザーに尋ねるか、sf config のデフォルト org を使用します）。<agentType> は fulfiller または employee です。

フェーズ 1 — 機能トグルを読み取る

1. 選択したパスに必要なすべてのトグルについて、機能ステータスを一括 POST し、標準出力をファイルに保存します（常に 5 つすべてをリクエストしても安全です。分類スクリプトは、そのパスで必要なものだけを判定します）。--json は追加しないでください。

   sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" \
     --method POST \
     --body '{"featureApiNames":["sales-cloud-agent-studio","service-cloud-agentforce-for-itsm","service-cloud-it-fulfiller-agent","service-cloud-requestor-agent","service-cloud-it-service-employee-agent"]}' \
     --target-org <alias> > /tmp/features-status.json 2>/tmp/features-status.err
   echo $? > /tmp/features-status.exit
   

   分類スクリプトが、確認済みの 404（ゲートが接続されていない）と、認証／権限／通信の失敗を区別できるよう、コマンドの終了ステータス（$?）を保存します。|| true で終了ステータスを無視しないでください。フェーズ 2 で分類スクリプトに渡してください。

フェーズ 2 — 分類（ヘルパースクリプト）

2. キャプチャしたファイル、選択したエージェント種別、およびキャプチャした終了ステータスに対して分類器を実行します。スクリプトパスにはスキルの絶対ディレクトリを使用します。

   node "<skill_dir>/scripts/classify-readiness.mjs" /tmp/features-status.json <agentType> "$(cat /tmp/features-status.exit)"
   

   これは { agentType, readState, features, verdict, notEnabled, enableable, reasons, rawError } を出力します。各 feature は PASS | FAIL | CANNOT-CONFIRM | ERROR、verdict は READY | NOT-READY | CANNOT-CONFIRM | ERROR です。これが正式な判定結果です — 生の応答から文章で再導出しないでください。notEnabled には無効になっている必須トグルのすべてが一覧表示されます。enableable は enableBlockedReasons を持たないサブセットです — configure スキルがすぐに有効化できるものであり、残りは未解決の依存関係または購入／ライセンスのゲートによってブロックされています。

フェーズ 3 — レポート + 引き継ぎ

3. 分類器の出力を以下の出力フォーマットにレンダリングします。
   • READY → エージェントを作成するために service-itsm-agentic-setup-fulfiller-agent-configure（fulfiller パス）または service-itsm-agentic-setup-employee-agent-configure（employee パス）をユーザーに案内します。
   • NOT-READY → 無効になっている各トグルを（notEnabled から）明示します。enableable サブセットについては、それらを有効化するために service-itsm-agentic-setup-agentforce-studio-configure に引き継ぎます（AskUserQuestion で提案: 「N 個の前提条件トグルがオフです。service-itsm-agentic-setup-agentforce-studio-configure を実行して有効化しますか？」 → Yes の場合は委任、No の場合は停止して報告）。無効かつブロックされているトグル（notEnabled に含まれるが enableable には含まれないもの）については、その enableBlockedReasons をそのまま報告します — ブロッカーが解消されるまで有効化できません。このスキル自体は有効化を POST しません。
   • CANNOT-CONFIRM → ステータスがなかったトグルを明示し、この組織階層では機能検出サーフェスが配線されていない可能性があることを伝えます。
   • ERROR → 読み取りが失敗しました（認証／権限／トランスポート、または予期しないボディ — rawError を参照）。生の応答を提示して停止します。単なる配線の欠落として扱わないでください。

フェーズ 4 — （有効化後）再検証

4. ユーザーがトグルを有効化するために service-itsm-agentic-setup-agentforce-studio-configure を実行した場合は、ここでフェーズ 1 + フェーズ 2 を再実行して判定が READY に変わることを確認し、報告します。このスキル自体の役割は終始読み取り専用のままです。

---

ルール／制約

制約	理由
このスキルは読み取り専用です — 機能の有効化を POST することはありません	切り替えをオンにする処理は、書き込み機能を持つ別のスキル（service-itsm-agentic-setup-agentforce-studio-configure）が担当します。2つを分けておくことで、validate という動詞の意味を正確に保ち、同じ書き込み処理を2つのスキルが担当する事態を避けられます
NOT-READY の場合は、有効化を依頼するため service-itsm-agentic-setup-agentforce-studio-configure に引き継ぎます	.../feature/{apiName}/enable の書き込みパスは、このスキルが担当します（べき等で、依存関係の順序に従います）。このスキルは無効になっているものを示すだけです
読み取りには sf api request rest を使用し、アクセストークンを抽出したり、生の HTTP リクエストを手作業で組み立てたりしません	sf api request rest は --target-org に対して CLI に保存されたセッションを使用します。トークンを抽出すると、ベアラートークンがシェルのコンテキストに漏えいします
判定ロジックは文章ではなく、Bash から呼び出す scripts/classify-readiness.mjs に記述します	判定は、固定された機能ステータスに基づく決定的な判断表です。スクリプトは信頼できますが、文章による解釈は信頼できません（作成標準 A9）
必須の切り替え項目は、エージェントのパスによって異なります	Fulfiller エージェントと Employee エージェントでは、条件となるテンプレートの切り替え項目が異なります。分類スクリプトは両方のパスを処理します
これらは Connect API の機能です — Headless360 ではなく SF CLI を使用します	Connect／Tooling の同等機能があるため、SF CLI を優先します（Headless360HostedMcpServer の組織権限による制約を回避できます）
enableBlockedReasons が空でない場合、切り替え項目は enableable に含まれません — ブロッカーを報告します	依存関係の未充足や購入条件が解決するまでは、設定スキルでもブロックされた切り替え項目をオンにできません
sf api request rest に --json を渡さないでください	一部の Connect エンドポイントではサポートされていません。標準出力に出力される生のレスポンス本文がすでに JSON です

---

検証チェックリスト

• エージェントのパス（fulfiller／employee）を特定しました（不明な場合は確認しました）。
• 機能ステータスを取得する POST を sf api request rest で実行し、その本文をファイルに保存しました。
• ファイル、エージェントの種類、取得した終了ステータスを指定して scripts/classify-readiness.mjs を呼び出し、出力された {verdict, notEnabled, enableable, rawError} を記録しました。
• 判定結果（READY／NOT-READY／CANNOT-CONFIRM／ERROR）を分類スクリプトの出力どおりに報告しました。NOT-READY の場合は無効な切り替え項目をそれぞれ示し、enableable に含まれる項目に限って有効化ルートを示し、それ以外の項目については enableBlockedReasons を報告しました。ERROR の場合は生のレスポンスを提示し、このスキルを停止しました。
• このスキルでは機能を有効にしていません（読み取り専用です）。NOT-READY の場合は無効な切り替え項目を示し、service-itsm-agentic-setup-agentforce-studio-configure への引き継ぎを提案しました。また、アクセストークンは抽出していません。

---

出力形式

準備状況レポートは次の形式で提示してください。

Agentforce for IT Service — Prerequisite Check (via service-itsm-agentic-setup-agentforce-studio-validate)

Org:          <org-alias> (API v67.0)
Agent path:   fulfiller | employee

  [PASS|FAIL] Agentforce Studio ......................... ENABLED | NOT_ENABLED (sales-cloud-agent-studio)
  [PASS|FAIL] Agentforce for IT Service ................. ENABLED | NOT_ENABLED (service-cloud-agentforce-for-itsm)
  [PASS|FAIL] <path-specific toggle(s)> ................. ENABLED | NOT_ENABLED (<featureApiName>)

Verdict: READY  |  NOT-READY  |  CANNOT-CONFIRM  |  ERROR

Next steps:
  - <If READY: "Org satisfies the prerequisites for the <path> agent. Create it via service-itsm-agentic-setup-fulfiller-agent-configure (fulfiller) / the employee-agent skill.">
  - <If NOT-READY: list each disabled toggle; for the enableable ones, hand off to service-itsm-agentic-setup-agentforce-studio-configure to turn them on; for blocked ones, report the enableBlockedReasons.>
  - <If CANNOT-CONFIRM: state which toggle(s) returned no status and that the feature-discovery surface may not be wired on this org.>

このスキルは読み取り専用です。組織の状態は書き込まれません。生成されるファイルは、分類器に渡される一時的な応答キャプチャのみです。

各トグルのレポートラベルは、Agentforce Studio、Agentforce for IT Service、IT Service Fulfiller Template、IT Service Employee Template、Specialized Agent Templates for Employeeをそのまま使用してください。このスキルとservice-itsm-agentic-setup-agentforce-studio-configureの両方で、ラベルを一致させてください。（上記のトグルテーブルでは、Studio 行の Go ページのトグルは「Turn on Agentforce Studio」ですが、レポートに表示するラベルは単にAgentforce Studioです。）2つのエージェントテンプレートのトグルに付くTemplateサフィックスは、意図的に設定された正式なレポートラベルです。上記のStudio行と同様、セットアップページの短いトグルキャプション（IT Service Fulfiller／IT Service Employee）とは意図的に異なります。インストール済みエージェントは、エージェント設定スキルで別途命名されます（IT Service Fulfiller Agent／IT Service Employee Agent。Templateは付きません）。パス固有の行は、fulfillerパスではIT Service Fulfiller Template、employeeパスではIT Service Employee TemplateおよびSpecialized Agent Templates for Employeeです。「Requestor」、「Specialized」、「parent」など、独自の役割修飾語をラベルに追加しないでください。

---

リファレンスファイル一覧

ファイル	読み込むタイミング
references/cli-invocation.md	すべてのフェーズ — 正確なsf api request rest読み取り呼び出しの形式、feature-statusルート、読み取り専用／引き渡しルール、トークンを決して抽出しないルール、分類器の仕様、エラー分類