service-itsm-teams-coordinate

ITSM 向け Microsoft Teams — エンドツーエンドのセットアップ自動化

完全な Microsoft Teams for Employee Service（ITSM）のセットアップを、ひと続きのフローとして進めます。 各段階を専門の子スキルに委任しますが、順序は自分で管理し、 すべての段階を途中で許可を求めることなく進めます。人間が実際に操作する必要がある箇所でのみ停止します。それ以外では停止しません。

目標

ユーザーを、何もない状態から、動作する Teams ITSM 統合（IT Desk と IT Service、Swarming、そして希望する場合は埋め込み Agentforce エージェント）まで、1 回のガイド付き実行で導きます。子スキルが検証済みの API 詳細を担当し、このスキルはそれらを順番に実行して引き継ぎを管理する指揮役です。

中核となる運用ルール — 継続して実行し、必要な場合にのみ停止する

ユーザーが情報を提供するか、プラットフォーム外で操作する必要がある場合を除き、途中で停止せずにすべて実行します。 段階の間にメニューを再表示してはいけません。各段階の後に「続行しますか？」と尋ねてはいけません。また、このスキルの子スキルが API 経由で実行できる Setup の切り替え操作を、ユーザーにクリックするよう求めてはいけません。進捗を随時報告しながら、次の段階へ直ちに進みます。

フロー全体には、必須の停止がちょうど 3 回、分岐が1 つあります。

• 停止 1 — Azure/Entra アプリ（ステージ 2）：アプリ登録の手順をユーザーに提示し、ユーザーがアプリを登録して認証情報を提供するまで待ちます。これを実行できる Salesforce API はありません。Client ID と Tenant ID は秘密ではない識別子なので、チャットで提供してもかまいません。Client Secret は機密性の高い認証情報です。会話で尋ねてはいけません。 エージェントは、シークレットを gitignore 対象のシークレットファイルに書き込み、そこから読み取るための、正確なコピーペースト用コマンドを 1 つユーザーに提示します（! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written）。先頭の ! はそのまま残します。これにより、このセッションの Bash で行が実行され、ファイルが保持されます。エージェントは値を表示、エコー、ログ出力してはいけません。
• 停止 2 — IT Desk アプリのインストール（ステージ 3）：Microsoft Marketplace のリンクを提示し、ユーザーが "installed" と返信するまで待ちます。テナントのカタログに Teams アプリをインストールできる API はありません。
• 停止 3 — IT Service アプリのインストール（ステージ 4）：IT Service アプリについて、停止 2 と同じ手順を実行します。
• 分岐 — IT Service Agentforce エージェント（ステージ 7）：IT Desk エージェントは自動的に動作しますが、IT Service の埋め込みエージェントは未対応です。実行するかユーザーに尋ね、はいと答えた場合にのみステージ 8 を実行します。

停止時にユーザーから応答がない場合は、そのまま待ちます。値を捏造したり、先へ進んだりしてはいけません。それ以外の段階間の移行はすべて自動です。

各段階では、一度に 1 つの操作を実行します。 子スキルは状態を変更する実際の API 呼び出しを行うため、1 つの操作を実行して成功を確認してから、次へ進んでください。状態を変更する呼び出しを、並列ブロックにまとめてはいけません。「途中で停止しない」とは、段階間に許可を求めないという意味であり、書き込みを並列実行するという意味ではありません。

フロー（次の順序で実行）

ステージ 1 — Teams for Employee Service の Go 機能を有効化する

機能の有効化部分のみを対象に、service-itsm-teams-configure を呼び出します（手順 1～3）。service-cloud-itsm-teams-integration を有効化し、ITSMTeamsEnabled が true と読み取られることを確認します。進捗を報告してから、直ちにステージ 2 へ進みます。ここで停止してはいけません。

ステージ 2 — Microsoft Entra アプリ + 名前付き認証情報 ⟶ 停止 1

引き続き service-itsm-teams-configure（ステップ 4a）で、ユーザーに Azure／Entra アプリ登録の正確なクリック手順を、記載されている Microsoft Graph のアクセス許可も含めて提示し、認証情報が提供されるまで停止してください。クライアント ID と テナント ID は秘密ではない識別子なので、チャットで受け取って構いません。クライアントシークレットは機密情報です。会話内で決して要求しないでください。 gitignore 対象のシークレットファイルに書き込むための、正確なコピー＆ペースト用コマンドを 1 つユーザーに提示し、そのファイルから読み取ってください （! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written）。先頭の ! はそのままにしてください。このセッションの Bash でその行が実行され、ファイルが保持されます。シークレットを決して表示またはエコーしないでください。識別子が提供され、シークレットがファイルに保存されたら、直ちに次の処理を行ってください。

• それらの値を、Named Credential MSTeamsSetupClientCredentialsEC と Auth Provider microsoft_auth_provider に、API 経由で自分で書き込んでください。手動操作は不要です（正確な API ボディは、子スキルのステップ 5 と azure-credential-population のリファレンスに記載されています）。呼び出し時にファイルからシークレットを読み取り、ログに記録されるテキストに生の値を埋め込まないでください。
• 静的な Grant Admin Consent リンクを提示し、優先サイトを登録してください（子ステップ 5）。 その後、自動的にステージ 3 に進んでください。

ステージ 3 — IT Desk のセットアップ（担当者側） ⟶ 停止 2

service-itsm-teams-itdesk-configure を呼び出してください。チェックリスト全体を進めてください。

• Org の設定 OrgHasITSMFulfillerTeams をオンにします（API 経由）。
• ユーザーアクセスの管理 — 確認済みのユーザーに担当者用権限セットを割り当てます。 TeamsForITSrvcsUser + MicrosoftGraphAccess に加え、API Enabled ログイン権限セット （一般的には Teams_Employee_ApiAccess）も必要です。これはログインに必須であり、任意ではありません。
• スウォーミングをオンにする — このステージには service-itsm-swarming-configure が含まれます（service-cloud-swarming を有効にし、SWARM_COLLABORATION_TOOL = "Teams" を設定します）。
• IT Desk の Microsoft Marketplace リンクとヘルプドキュメントを提示し、Azure アカウントのメールアドレスは Salesforce ユーザーのメールアドレス／Username と一致する必要があるとユーザーに伝えてください（SSO は MS UPN から Username に解決されます）。ユーザーが 「installed」 と返信するまで停止してください。その後、ステージ 4 に進みます。

ステージ 4 — IT Service のセットアップ（従業員側） ⟶ 停止 3

service-itsm-teams-itservice-configure を呼び出してください。チェックリスト全体を進めてください。

• Org の設定 OrgHasEmployeeServiceTeams をオンにします（API 経由）。
• ユーザーアクセスの管理 — 確認済みの UEL ユーザーに従業員用権限セットを割り当てます。 TeamsForEmployeeUser（ダイアログで割り当てるのはこれだけであり、MicrosoftGraphAccess は割り当てません）に加え、子スキルのログイン前提条件で必要とされる API Enabled ログイン権限セットも割り当てます。
• Digital Experience Site（SLACK_PREFERRED_SITE）を API 経由で選択します。
• IT Service の Microsoft Marketplace リンクとヘルプドキュメントを提示し、メールアドレスを一致させる必要がある旨を再度伝えてください。ユーザーが 「installed」 と返信するまで停止してください。その後、ステージ 5 に進みます。

ステージ 5 — ログインの確認をユーザーに依頼する

ユーザーに Teams で IT Desk アプリを開き、担当者の認証情報でサインインするよう依頼してください。また、IT Service アプリには UEL／従業員の認証情報でサインインし、両方が読み込まれることを確認してもらいます。どちらかが失敗した場合は、先に service-itsm-teams-debug に案内し、ログインの合否診断を行ってください。

ステージ 6 — IT Desk の「Ask Agentforce」エージェントは自動で動作すると伝える

IT Desk へのログインが確認できたら、IT Desk の Ask Agentforce は自動で動作し、担当者側で追加のセットアップは不要だとユーザーに伝えてください。

ステージ 7 — IT Service の Agentforce エージェントを提案する ⟶ 分岐

IT Service 側には未完了の作業があり、埋め込み Agentforce エージェント（「Ask AI Agent」）は、メッセージングチャネル + Key Set + Embedded Service Deployment を作成するまで応答しないことをユーザーに伝えてください。今すぐセットアップするかどうかを尋ねてください（AskUserQuestion を使用）。いいえの場合は完了サマリーに進みます。はいの場合はステージ 8 を実行します。

ステージ 8 — IT サービス組み込みエージェントの構築（ユーザーが「はい」と答えた場合のみ）

service-itsm-teams-employee-agent-configure を呼び出します。これは、ユーザー検証 ON + JWKS_URL キーセットを備えた Web メッセージングチャネル、Teams_AgentForce 組み込みサービスデプロイメント（公開）、ルーティングフロー、およびポータルユーザーに対する Agent Access 権限セットを — 100% API 経由で — 構築します。その後、ユーザーに まったく新しい Teams チャットから再テストして、エージェントが応答することを確認するよう伝えてください。

各ステージの後

• 子の実際の判定を報告する —「完了」と決して決めつけないでください。 ステージが完了するのは、その子スキルが明示的に成功を報告したときだけです。子が blocked を報告した場合（最も一般的なのは、Entra アプリが未登録の状態でのステージ 2、または「インストール済み」を待つ中断）、そのステージを Blocked/待機中 のままにして中断状態を維持してください — 完了としてマークしたり、先に進めたりしないでください。
• メニューを再提示しないでください。今何が終わったのか、次に何をするのかを述べ、それから実行してください。
• レポートは簡潔に — 要約し、書き写さないでください。 各ステージは、ステージ進捗テーブルの 1 行のステータスと、せいぜい短い文 1 つ分のコンテキストとして報告してください。子スキルの API リクエスト/レスポンス本文、ツール呼び出しログ、または段階的な内部処理をレポートに貼り付けないでください — その詳細は子スキルにあり、ここで再び語り直すことは、肥大化した低シグナルのレポートの最大の原因です。読み手が必要としているのは何が起きたかと次は何かであり、すべての呼び出しの再生ではありません。

完了サマリー

フローが終了したとき（ステージ 7 が「いいえ」、またはステージ 8 が完了、またはユーザーが解決しないことを選んだハードブロック）、各ステージの実際のステータスを要約してください。ヘッダー: すべてのステージが完了 → Complete。ブロック中/待機中のステージがまだある → Incomplete (action required) と正確な次のステップ。それ以外 → Finished。

ルール

• セットアップヘッダーに必ず「(via service-itsm-teams-coordinate)」を表示してください。
• ステージは継続的に実行してください。対話的な停止は HALT 1〜3 とステージ 7 の分岐のみです。
• 子スキルが API 経由で切り替えられるセットアップのトグル（機能の有効化、組織の環境設定、権限セットの割り当て、デジタルサイト、名前付き資格情報）をユーザーにクリックさせるよう決して求めないでください。
• 中断の値（Azure 資格情報、「インストール済み」）や子の成功を決して捏造しないでください — 実際の返信を待ってください。
• すべてのステージをその子スキルに委任してください。子の API ロジックをここでインラインで再実装しないでください。
• 会話全体を通して進捗を追跡してください — 完了したステージを再実行しないでください。
• 出力に Salesforce レコード ID を表示しないでください — 人間が読める名前のみにしてください。
• ステージ 3 と 4 では、不一致がよくあるサイレントログイン失敗であるため、マーケットプレイスのリンクとともに必ず Azure のメールアドレスは Salesforce のメールアドレスと一致しなければならないという注意を記載してください。

検証チェックリスト

進捗メッセージやサマリーを出力する前に、次を確認してください:

• ヘッダー行が (via service-itsm-teams-coordinate) で終わっている。
• フローが継続的に実行されている — 定義された 3 つの中断とステージ 7 の分岐以外に、ステージ間に権限ゲートが挿入されていない。
• 各ステージのステータスが子の実際の判定（In progress、Blocked/待機中、または Done）を反映しており、ハードコードされた既定値ではない。
• 中断（Azure 資格情報、「インストール済み」）を待っているステージは待機中として表示され、決して Done になっていない。
• ステージ 3 と 4 がそれぞれマーケットプレイスのリンクおよびメール一致の注意を提示した。
• ステージ 7 の分岐が yes/no の質問として提示され、ステージ 8 が明示的な「はい」の場合にのみ実行された。
• 次のアクションが子スキルに委任している。機能がここでインラインで構成されていない。
• 出力に Salesforce レコード ID が表示されていない — 人間が読める名前のみである。

参照ファイルインデックス

File	When to read
examples/output-templates.md	Progress and completion-summary text blocks