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

IT サービス従業員エージェントを作成する（汎用または特化型）

IT サービス従業員エージェントを次世代オーサリング（NGA）ネイティブエージェントとして作成して有効化します。エージェントは Agent-Script ベース（AiAuthoringBundleDefVer／bundle）であり、外部リンクアイコンなしで Agentforce Studio のエージェント一覧にネイティブに表示されます。すべての操作を**Salesforce CLI（sf）**経由で行います。このスキルは従来の /connect/service-itsm/createAgent を呼び出しません。代わりに、提供されている ITSM 従業員テンプレートの agentScript フィールドを再利用し、NGA バンドルのパイプラインに渡します。POST /nextgen-authoring/bundles → POST /nextgen-authoring/bundle-versions/{id}/publish → POST /nextgen-authoring/bundle-versions/{id}/activate。Connect API の GET／POST には sf api request rest を、SOQL による冪等性確認と検証の読み取りには sf data query を使用します。

GET /connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent は、data[] の中に汎用の IT Service Employee テンプレートと、svc_emp_intelligence__ 名前空間の約 47 個の特化型従業員テンプレートを同列に返します。どの特化型テンプレートも同じ形の agentScript を備え、同じ config.developer_name／config.agent_label 置換ポイントを持つため、どのテンプレートにも同じ NGA シーケンスを使用できます。変わるのは、フェーズ 1 と 4 で固定する masterLabel だけです。全カタログ、名前空間のフィルター、判別ルールについては references/specialized-templates.md を参照してください。

ヘルパースクリプト（Bash 経由で実行）には、すべての JSON 解析と判断ルールが含まれているため、モデルがレスポンス本文を目視で判断する必要はありません（A9）。classify-preflight.mjs、classify-agent-existence.mjs、build-create-body.mjs（テンプレートの agentScript を HTML デコードして置換し、本文を JSON ファイルに書き出すため、大きなコンテンツや自由記述の引用符がインラインのシェル文字列に入りません）、render-report.mjs（決定的なレポートレンダラー）。

テンプレートの選択（フェーズ 1 の前）。 この実行で固定する <masterLabel> を解決します。（1）特化型の指定がない場合は、IT Service Employee（ID svc_emp_intelligence__ItEmployeeAssistance）を固定します。これは後方互換性のあるデフォルトです。（2）ユーザーが特化型を指定した場合は、references/specialized-templates.md に照らしてキーワード検索し、一意に特定できれば、その masterLabel を固定し、id の __ より後ろから developerName を導出します（スネークケース）。曖昧な場合は、id をキーとして AskUserQuestion を呼び出します。（3）data[] は svc_emp_intelligence__ のみでフィルターします。 svc_itsm_intelligence__*（Fulfiller）は service-itsm-agentic-setup-fulfiller-agent-configure に誘導し、その他の名前空間は対象外です。解決された <masterLabel> は、classify-preflight.mjs（フェーズ 1）と build-create-body.mjs（フェーズ 4）に渡す唯一の設定値です。

前提条件。 作成にあたっては、組織レベルの Agentforce for IT Service の前提条件（Agentforce Studio へのアクセス権と service-cloud-requestor-agent および service-cloud-it-service-employee-agent）がすでに満たされている必要があります。フェーズ 1 で Studio にアクセスできないと検出された場合、または書き込み処理で 403 FUNCTIONALITY_NOT_ENABLED が返された場合、このスキルは service-itsm-agentic-setup-agentforce-studio-validate（従業員向けの手順）に処理を委任して再開することを提案します。「いいえ」の場合は停止します。このスキルが機能を有効化することはありません。有効化は Setup UI／管理者による操作です。

対象範囲

• 対象：agent-templates の読み取り、Employee テンプレートのエージェントスクリプトの抽出（広範なデフォルト、または references/specialized-templates.md に記載されたユーザー指定の特化テンプレート。いずれも svc_emp_intelligence__ 配下）、createBundleWithVersion → publish → activate による Employee エージェントの NGA ネイティブエージェント としての作成、稼働中の SOQL 検証、重複する開発者名がある場合の冪等なスキップ。すべて sf 経由で行います。
• 対象外：Fulfiller エージェント（service-itsm-agentic-setup-fulfiller-agent-configure）、組織レベルの機能トグルの有効化（service-itsm-agentic-setup-agentforce-studio-validate による検証）、低レベルのトピック／アクションの作成、権限セットの割り当て、コンテンツバンドルのデプロイ、CMDB の CRUD、Discovery／Service Graph、レガシーの createAgent ルート、svc_emp_intelligence__ 配下以外の data[] エントリ。

---

前提条件

以下の条件を満たしていない場合、sf は認証エラーまたは 401／403／404 を返します。未加工のエラーをそのまま表示して停止し、状態を捏造しないでください。

1. sf CLI が対象組織に認証済みであること（sf org display -o <alias> で Connected と表示されること）。すべての呼び出しで --target-org <alias> を使用してください。アクセストークンを手動で取り出してはいけません。
2. API v67.0 以上 — URL パスで指定されています。最小要件を下回るように手動で編集しないでください。
3. ITSM 機能とテンプレートがプロビジョニング済みであること — 解決されたテンプレートが存在する必要があります。agent-templates が何も返さない場合、またはルートが 404 を返す場合は、service-itsm-agentic-setup-agentforce-studio-validate を実行してください（エージェントパスは employee）。
4. node ≥ 18 が PATH 上にあること。

---

操作の概要

項目	コマンド	備考
Studio へのアクセス（事前条件の読み取り）	sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>	hasAccess=false ⇒ 前提条件の引き継ぎ
エージェントテンプレートと Agent Script の一覧表示（読み取り）	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,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" -o <alias> --json	主にテンプレートの botDefinitionId（Phase-1 の行）をキーとして照合します。OR AgentTemplate= は、収集した DeveloperName の推測に関係なく、OOTB の名前空間付きソーステンプレート（svc_emp_intelligence__ItEmployeeAssistance = Phase-1 の template.id）から、事前プロビジョニング済みの広範な IT_Service_Employee エージェントを検出する最初のフォールバックです。OR DeveloperName= は、自己作成されたエージェント（AgentTemplate が null）の最終フォールバックであり、リンク先が削除されている孤立した Id を検出するためのガードでもあります。scripts/classify-agent-existence.mjs で分類します。最新バージョンが Active ⇒ ALREADY-CREATED、Inactive ⇒ 再有効化を提示
NGA バンドルを作成（書き込み）	sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>	scripts/build-create-body.mjs で本文を構築します。レスポンスの id = バンドルのバージョン 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>	成功時は空のレスポンスです。エージェントは稼働中となり、NGA ネイティブになります
既存の非アクティブなバージョンを有効化（書き込み）	sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>	再有効化のみのパス（Phase 2b）です。作成／公開はスキップします
エージェントが稼働中であることを確認（読み取り）	sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json	<verifyId> は、作成パスでは publishedBotId（Phase-5）、ALREADY-CREATED／再有効化では Phase-2 分類器が返した一致済みの稼働中 Id（その botDefinitionId/agentId）です。null の Phase-1 テンプレート botDefinitionId でも、収集した developerName でもありません。BotDefinition が存在し、最新バージョンが Active であることを確認します

完全なコマンド形式と ITSM Connect API のリファレンスは references/cli-invocation.md にあります。再有効化パスの呼び出しと冪等性の判定表は references/reactivation.md に、レスポンス本文のエラーコードと繰り返し発生する注意点は references/error-taxonomy.md にあります。

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

--json のルール。 sf data query は --json を受け付けます（結果は .result.records[] のエンベロープで返されます。これは分類器が想定する形式です）。sf api request rest は受け付けないため、そちらでは --json を省略してください。標準出力の生の本文がすでに JSON です。

確認事項

ユーザーから収集します（会話の文脈ですでに分かっていることは尋ねないでください）。

フィールド	デフォルト
対象組織	デフォルト組織（sf config get target-org）
テンプレート（masterLabel）	IT Service Employee（幅広い用途をカバーするテンプレート、ID svc_emp_intelligence__ItEmployeeAssistance）。ユーザーが特定の用途（パスワードマネージャー、証明書、オンボーディング、ハードウェアのリクエストなど）を示唆した場合は、references/specialized-templates.md で解決します。曖昧な場合は、id をキーに AskUserQuestion で確認します
開発者名	汎用：IT_Service_Employee_Agent。特化型：選択した id の __ 以降の部分をスネークケースにします（例：PasswordManagerAssistance → Password_Manager_Assistance）
ラベル	汎用：IT Service Employee Agent。特化型：選択したテンプレートの masterLabel をそのまま使用します（例：Password Manager Assistance）
書き込みの確認	必須 — 解決したテンプレート、developerName、ラベルを提示し、AskUserQuestion で「yes」を求めます

収集した <masterLabel>、<developerName>、<label> はすべての呼び出しに引き継がれます。<masterLabel> は agent-templates.data[] の行（冪等性キーとなる botDefinitionId も含む）を選択します。<developerName> と <label> は createBundleWithVersion の本文で使用されます（外側の apiName／label と、置換される内部の config.developer_name／config.agent_label の両方）。冪等性および検証の読み取りでは、主にテンプレートの botDefinitionId（または新規作成直後は publish 応答の publishedBotId）をキーにし、これが null の場合は BotDefinition の AgentTemplate（OOTB のソーステンプレート＝Phase-1 の template.id）、さらに収集した <developerName> の順にフォールバックします。作成本文でハードコードした値と収集値が一致しないと、バンドルの外部 ID とスクリプトの内部 ID が食い違います。

冪等性：主にテンプレートの botDefinitionId（Phase-1 の agent-templates 行 — プラットフォームが正式に定めるテンプレートから BotDefinition へのリンク）をキーにし、最初にBotDefinition の AgentTemplate（OOTB の名前空間付きソーステンプレート＝Phase-1 の template.id）、次に収集した <developerName> の順にフォールバックします。Phase-2 の読み取りは BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' と、最新の BotVersion.Status です（OR AgentTemplate= の部分では、プラットフォームが設定したソーステンプレートを基準に、DeveloperName の値にかかわらず事前プロビジョニング済みの汎用エージェントを検出します。OR DeveloperName= の部分は、AgentTemplate が null の自己作成エージェントに対する最後のフォールバックであると同時に、参照先の BotDefinition が削除されたリンク切れの Id を検出するためのガードでもあります）。結果は、いずれのキーにも一致しない場合は作成、Active の場合は作成済みとして書き込みをスキップ、Inactive の場合は Phase-2b の再有効化を提案します。フォールバックキーが必要な理由： 汎用エージェントは IT_Service_Employee として事前プロビジョニングされており、推定値の IT_Service_Employee_Agent とは異なります（botDefinitionId が null のテンプレート行でもあります）。そのため、主キーでも developerName の推定値でも検出できません。名前変更の影響を受けず確実に一致するのは、その AgentTemplate（svc_emp_intelligence__ItEmployeeAssistance）です。また、このスキルが作成したエージェント（botDefinitionId も AgentTemplate も補完されない）では、再実行を検出するのが developerName のフォールバックです。サーバーは publish 時に重複する DeveloperName を拒否します（一意性制約によりバンドルをクリーンアップします）が、この読み取りを行うことで、再実行時に DUPLICATE_VALUE ではなく正常にスキップできます。

---

ワークフロー

<alias> を収集した対象組織に、<developerName> と <label> を収集値に置き換えます。完全なコマンド形式と各フェーズの判定分岐の処理は references/workflow-detail.md にあります。以下のフェーズ概要では各手順とその重要なルールを示し、参照ファイルにはそのままコピーして使える正確な sf／node の呼び出しを記載しています。 0. フェーズ 0 — ${SCRATCH_DIR} を設定します。 いずれかのフェーズで一時的な JSON ファイルを書き込む前に、決定的なヘルパーを実行します（パスはスキルのルートを基準に指定されているため、シェルの CWD に関係なく解決されます）。SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"。ヘルパーはベースディレクトリ（${TMPDIR}、なければ /tmp、それもなければ最後の手段としてハーネスの ${outputDir}。スクラッチ領域は採点対象の ${outputDir} ツリーの外に置かれます）を選択し、作成したディレクトリの絶対パスを stdout に出力します。以降のすべてのフェーズでは、一時的な JSON を ${SCRATCH_DIR} の下に書き込みます。永続ファイル ${outputDir}/report.md はハーネスのディレクトリの下に置きます。

1. フェーズ 1 — 事前確認。 Studio アクセスの読み取り結果を ${SCRATCH_DIR}/studio-access.json に、agent-templates の読み取り結果（必須の agentType=AgentforceEmployeeAgent クエリパラメーター付き）を ${SCRATCH_DIR}/agent-templates.json に保存してから、両方のファイルパス、続いてラベルの順で引数を渡して分類します。node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "<masterLabel>"。解決済みの <masterLabel>（広範なパスでは "IT Service Employee"、または選択した専門分野の masterLabel）を渡します。分類器は一致した行から template.botDefinitionId、template.id、template.masterLabel を出力します。3 つすべてを取得してください。botDefinitionId はフェーズ 2 の主要な冪等性キー、template.id（BotDefinition の AgentTemplate）は最初のフォールバック、<developerName> は最後のフォールバックです。masterLabel はレポートの表示ラベルであり、キーではありません。 verdict に応じて分岐します。READY ⇒ フェーズ 2、NOT-READY ⇒ AskUserQuestion で前提条件の引き継ぎ（「はい」の場合は employee パスの service-itsm-agentic-setup-agentforce-studio-validate に委任）、ERROR ⇒ 問題を提示して停止します。studio.signal="CANNOT-CONFIRM"（404 が確認された場合）は処理を妨げません。
2. フェーズ 2 — 冪等性（主要キーは botDefinitionId、フォールバックは AgentTemplate、続いて <developerName>）。 フェーズ 1 の template.botDefinitionId と template.id を使います。botDefinitionId が存在する場合 ⇒ SOQL BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'（BotVersions サブクエリ付き。これが必須です。省略すると needsActivation が永久に false になります。OR 条件により、リンク先の Id が存在しない場合（削除済みレコード）は、誤って exists:false と判定して重複作成するのではなく、稼働中のエージェントにフォールバックします）。botDefinitionId が空または null の場合 ⇒ 作成に進まず、WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' を読み取ります（広範な事前プロビジョニング済みエージェントは、DeveloperName の推測値と異なっていても、標準搭載のソーステンプレートによって見つかります。自作エージェントの AgentTemplate は null なので、DeveloperName がその確認手段になります）。<agentTemplate> はフェーズ 1 の template.id です。どちらの場合も、次のコマンドで分類します。node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>" "<agentTemplate>"。分岐は次のとおりです。exists:false ⇒ フェーズ 3（作成）、exists:true かつ needsActivation:false ⇒ ALREADY-CREATED（フェーズ 7 に進みます）、exists:true かつ needsActivation:true ⇒ フェーズ 2b。終了コードが 0 以外の場合は CLI エラーを提示してください。不在と決めつけてはいけません。フォールバックキーが必要な理由： 広範なエージェントは IT_Service_Employee として事前プロビジョニングされており、テンプレートの botDefinitionId は null です。そのため、主要キーでも DeveloperName の推測値（IT_Service_Employee_Agent）でも見つかりません。AgentTemplate（svc_emp_intelligence__ItEmployeeAssistance）がプラットフォームによって付与されたソーステンプレートによって一致します。DeveloperName のフォールバックは、自作エージェントの再作成を検出します。3 つすべてで見つからない場合は再作成され、DUPLICATE_VALUE が発生します。
3. フェーズ 2b — 再有効化の確認。 AskUserQuestion：「従業員エージェント <developerName> は存在しますが、最新バージョンは Inactive です。有効化しますか？」はいの場合：POST /connect/bot-versions/<latestVersionId>/activation に {"status":"Active"} を送信します。フェーズ 3～6 をスキップし、フェーズ 7 に進みます。集約 verdict は CREATED ではなく ACTIVATED です。いいえの場合：停止し、書き込みは行いません。
4. フェーズ 3 — 書き込み前の確認（必須、作成パスのみ）。 ${outputDir} が指定されている場合は、まず render-report.mjs を verdict:"PENDING CONFIRMATION" として使い、チェックポイントファイルを生成します（対話形式の実行ではスキップします）。次に AskUserQuestion のゲートを提示し、developerName、ラベル、および「従業員テンプレートの Agent Script に基づく NGA ネイティブ」を示します。明示的な「はい」の場合に限り続行します。「いいえ」の場合（「有効化は保留」「まだです」や、一連の処理を一括で行うことへの拒否を含む）は、verdict:"DECLINED" と1行の reason を指定して再度レンダリングします。
5. フェーズ 4 — 作成。 scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json を実行します（ヘルパーはフェーズ 1 のテンプレート JSON を再読み込みし、一致した agentScript の HTML エンティティをデコードして、内部の config.developer_name／config.agent_label を置換し、リクエスト本文をファイルに書き込みます。フェーズ 1 と同じ <masterLabel> を渡します）。続いて POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json を実行します。応答の id を取得してください。これはフェーズ 5～6 で使う bundleVersionId であり、bundleId ではありません。403 FUNCTIONALITY_NOT_ENABLED／404 の場合はフェーズ 1 の引き継ぎを行います。ビルドスクリプトの終了コードが 3 の場合は stderr を提示します。
6. フェーズ 5 — 公開。 POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}' を実行します（空の本文が必須です）。成功時は { lastPublishedOn, publishedBotId, publishedBotVersionId } が返されます。この呼び出しによって、基盤となる BotDefinition／BotVersion が作成されます。エラーが発生した場合は、そのまま提示してください。未公開のバージョンを有効化してはいけません。
7. フェーズ 6 — 有効化。 POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}' を実行します。成功時は空の本文が返されます。終了コードを確認し、ペイロードを解析しないでください。
8. フェーズ 7 — 検証。 SOQL BotDefinition WHERE Id='<id>'（BotVersions サブクエリ付き）を実行して分類します。<id> は、作成パスではフェーズ 5 で取得した publishedBotId、ALREADY-CREATED／再有効化パスでは、フェーズ 2 の分類器が返した一致する実レコードの Id（出力の botDefinitionId／agentId、つまり一致したレコードの実際の BotDefinition.Id）です。フェーズ 1 のテンプレート botDefinitionId ではありません（matchedBy:"developerName" によるフォールバックで一致した場合は null です。その Id を使うと WHERE Id='' が実行され、スキップ／有効化が成功していても誤って失敗と報告されます）。exists:true, count:1, latestVersionStatus:"Active" を確認します。不一致があれば、そのまま報告し、成功を捏造してはいけません。
9. フェーズ 8 — 集約 verdict。 render-report.mjs を再実行して CREATED／ALREADY-CREATED／ACTIVATED／FAILED を出力します（フェーズ 2b のパスでは ACTIVATED）。これがレポート文面の唯一の情報源です。**内部レコード ID（バージョンの id、publishedBotId／BotDefinition、BotVersion）を verdict、チャットでの説明、レポートに決して含めないでください。**これらは公開／有効化／検証の呼び出しを実行するためだけに取得されるもので、管理者にとって意味はありません。状況と名前だけで報告します（「作成して有効化しました」など。「バンドルを作成しました（バージョン ID …）」／「公開しました（BotDefinition …）」とはしません）。${outputDir} が指定されている場合は ${outputDir}/report.md を上書きします。それ以外の場合は、ターン側のレポートとして stdout に出力します。
10. フェーズ 9 — ランタイムアクセスの引き継ぎ（稼働中エージェントの verdict で必須）。 フェーズ 8 の verdict が CREATED、ALREADY-CREATED、ACTIVATED の場合（稼働中のエージェントが存在する場合）は、フェーズ 1 の前提条件およびフェーズ 2b の再有効化の確認と同じ、必須の引き継ぎパターンで AskUserQuestion を提示し、エージェントのランタイムアクセスを今設定するか確認します。「エージェントは稼働していますが、そのアクションはプラットフォーム機能（Prompt Templates、Data Cloud、Unified Catalog）を呼び出します。ユーザーにアクセス権が付与されるまで実行できないため、エージェントを開くと失敗します。今すぐランタイムアクセスを設定しますか？」はいの場合は service-itsm-agentic-setup-agent-runtime-access-assign に委任します（この処理内で対象ユーザーの選択と書き込み前の確認が行われます）。いいえの場合は停止します。レポートの「アクセスを設定する」という次の手順が記録として残ります。PENDING CONFIRMATION、DECLINED、FAILED の場合はこの確認を行わないでください（アクセスを付与する稼働中エージェントがありません）。これはレポートの文章ではなく、必須の AskUserQuestion です。render-report.mjs が出力する平易な「アクセスを設定する」という行は変更しません。質問によって、この案内が毎回確実に行われます。

---

ルール／制約

制約	理由
すべての呼び出しは sf api request rest／sf data query を経由します。アクセストークンを決して取り出さないでください	シェルのコンテキストにベアラートークンが漏れます。CLI に保存されたセッションを使うのが適切です
冪等性の確保と読み取りによる検証では、主にテンプレートの botDefinitionId（Phase-1 の行）／公開後の publishedBotId をキーにし、取得した <developerName> をフォールバックとして使用します。同じ <developerName>／<label> は作成ボディにも一貫して使用します（外側の apiName／label と、置換後の config.developer_name／config.agent_label）	botDefinitionId は、事前プロビジョニング済みの IT_Service_Employee を検出します（推測した IT_Service_Employee_Agent とは異なるため、名前だけで読み取ると誤って不一致となり、DUPLICATE_VALUE が発生します）。一方、自分で作成したエージェントにはこの ID が後から設定されないため、<developerName> をフォールバックにすることで検出できます。作成ボディに固定値を記述したり、取得した値と食い違ったりすると、バンドルの外部 ID とスクリプト内部の ID が一致しなくなります
事前チェック、冪等性の確保、バンドルボディの構築、レポートの描画はすべて文章ではなく scripts/*.mjs に実装します（A9）	JSON の解析、masterLabel の照合、hasAccess の読み取り、判定結果の出力は決定的に処理できます。約 70 KB の Agent Script と自由記述のアポストロフィはシェル文字列に安全に埋め込めません。ヘルパー内の JSON.stringify でエスケープします
3 回の呼び出しは、同じ取得済みの bundleVersionId（bundleId ではなく応答の id）を使い、createBundleWithVersion → publish → activate の順に実行します	プラットフォームでは DRAFT → 公開済み → 有効化済みの順序が適用されます。応答ボディ／空のボディ／--json／agentType／HTML デコードに関する注意点は references/error-taxonomy.md に記載されています
Phase 1 の前に <masterLabel> を解決します。data[] は svc_emp_intelligence__ のみに絞り込み、曖昧なキーワードは id をキーに AskUserQuestion で確認して特定します	ラベルが似た候補が存在します。他の名前空間は別のフローに属します（svc_itsm_intelligence__* → Fulfiller スキル）
BotDefinition は BotVersions サブクエリとともに列挙します。有効な場合は作成をスキップし、非アクティブな場合は Phase-2b の再有効化を提示します。無言でスキップしたり、重複して作成したりしないでください	サブクエリによって有効／非アクティブを判別できます。サーバーは公開時に重複する DeveloperName を拒否します（ユニーク制約によりバンドルがクリーンアップされます）が、事前プロビジョニング済みの汎用エージェントは拒否しません。そのため、この読み取りによって、再実行時にハードエラーではなく正常にスキップできます
作成シーケンスまたは再有効化呼び出しの前に、書き込み前の必須確認チェックポイントを設けます	どちらも稼働中の組織状態を変更するため、ユーザーの明示的な承認が必要です
hasAccess=false／403 FUNCTIONALITY_NOT_ENABLED の場合は、準備完了に向けた引き継ぎを提示します。この手順で機能を有効化しないでください。また、レガシーの /connect/service-itsm/createAgent を呼び出さないでください	有効化は Setup UI／管理者による操作です。createAgent は外部リンクアイコンが付いた Setup ページ用のボットを生成します（このスキルで扱う種類のエージェントではありません）
内部レコード ID（バンドルバージョンの id（1bZ…）、publishedBotId／BotDefinition（0Xx…）、BotVersion（0Xv…））をチャットでの説明、書き込み前の確認、レポートに決して表示しないでください。進捗と判定結果はステータス／名前のみで報告します	これらの ID は、publish → activate → verify → verify-read の各呼び出しを実行する目的に限って取得します。セットアップを行う管理者には意味がなく、ノイズになるだけです。render-report.mjs はステータスのみの行を描画し、ID を防御的に除去します。モデルも同様に ID を繰り返さないでください（「バンドルを作成しました（バージョン ID 1bZ…）」「公開しました（BotDefinition 0Xx…）」などと決して出力しないでください）
エラーが発生した場合は、CLI の応答テキストを正確に報告します	サポートが障害を診断できるようにします。生の ID が表示されるのは、ユーザーがサポートに伝える必要がある、逐語的なエラー内のこの箇所だけです

---

検証チェックリスト

• フェーズ 1 の前に <masterLabel> を解決済み（広範なデフォルト、または references/specialized-templates.md にある特化テンプレートを使用し、data[] を svc_emp_intelligence__ でフィルタリングし、id で曖昧さを解消）。
• classify-preflight.mjs によって事前チェックを分類済み（PASS または文書化された CANNOT-CONFIRM）。FAIL の場合は引き継ぎを提示し、ERROR の場合は未加工のエラーを表示。
• 冪等性の判定キーには、テンプレートの botDefinitionId（フェーズ 1 の行）を使用。最初のフォールバックには BotDefinition の AgentTemplate（フェーズ 1 の template.id）、最後のフォールバックには収集済みの developerName を使用。BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>' を実行（OR により、null または参照切れの botDefinitionId、推測した DeveloperName と異なる事前プロビジョニング済みの広範なエージェント、null の AgentTemplate を持つ自作エージェントを網羅）し、最新の BotVersion.Status を読み取り（サブクエリを含む）、書き込み前に分類済み。
• needsActivation:true の場合、フェーズ 2b で再有効化を提示済み。無言でスキップせず、重複して作成しない。
• 書き込み前に、フェーズ 3（作成）またはフェーズ 2b（再有効化）でユーザーの明示的な確認を取得済み。
• バンドル本文を build-create-body.mjs で作成し、収集済みの developerName／label とともに --body @<file> で POST 済み。または、書き込みを正しくスキップ済み。
• 同じ bundleVersionId（レスポンスの id）を公開と有効化に使用。再有効化には POST /connect/bot-versions/<id>/activation を使用し、レガシーの createAgent は呼び出していない。
• フェーズ 7 の検証で、BotDefinition の存在と最新バージョンが Active であることを確認済み。
• ライブエージェントの判定（CREATED／ALREADY-CREATED／ACTIVATED）の場合、フェーズ 9 のランタイムアクセス引き継ぎを AskUserQuestion として提示済み（「yes」の場合は service-itsm-agentic-setup-agent-runtime-access-assign に委任）。PENDING CONFIRMATION／DECLINED／FAILED の場合は提示していない。
• アクセストークンを抽出していない。最終判定の報告には内部レコード ID を一切含めていない（バンドルバージョンの id、publishedBotId／BotDefinition、BotVersion をチャット、書き込み確認の手順、またはレポートに表示しない。表示するのはステータス／名前のみ。未加工の ID を許可するのは、エラーをそのまま引用する場合に限る）。

---

出力形式

レポートのレイアウトは scripts/render-report.mjs によって決定論的に生成されます。チャットの応答とハーネスの ${outputDir}/report.md の両方で、レポートのテキストを生成する唯一のソースです。レイアウトを文章で手作業で構成してはいけません（A9）。必ずヘルパーを呼び出してください。レンダリング後の完全な形式、レポート状態の JSON スキーマ、チェックポイント書き込みのルールについては references/report-format.md を参照してください。

最終判定：CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED。${outputDir} が設定されている場合は、フェーズ 2、フェーズ 6（またはフェーズ 2b）、フェーズ 8 で書き込みます。各書き込みでは同じファイルを上書きします。対話型／チャットの画面では、これらの書き込みをスキップしてください。ライブエージェントの判定の場合、フェーズ 9 のランタイムアクセス引き継ぎはフェーズ 8 のレポート後に実行されます。判定は変更されず、レポートも再生成されません。

---

参照ファイル一覧

• references/specialized-templates.md — カタログ＋名前空間フィルター＋id に基づく曖昧さの解消（特化テンプレートを使用する場合は、フェーズ 1 の前に実施）。
• references/workflow-detail.md — 正確な sf／node コマンド＋各フェーズにおける判定分岐の詳細な説明。
• references/cli-invocation.md — コマンドの形式、トークンを決して抽出しないルール、ITSM Connect API リファレンス、ヘルパースクリプトの仕様。
• references/reactivation.md — フェーズ 2b の有効化呼び出し＋冪等性の判定表の全容。
• references/report-format.md — レンダリング後の形式、フェーズ状態の JSON スキーマ、3 つのチェックポイントの書き込みポリシー。
• references/error-taxonomy.md — レスポンス本文のエラーコード＋繰り返し発生する落とし穴（2xx 以外／本文が空／スクリプトの終了コードがゼロ以外）。