service-agentforce-contact-center-coordinate

service-agentforce-contact-center-coordinate：Agentforce Contact Center の音声チャネルを設定する

認証済みの組織からライブの着信音声チャネルまでの全行程を調整します。電話番号を取得し、プロビジョニング済みであることを確認して、有効な PstnVoice MessagingChannel を作成します。ユーザーはルーティングモデルを選択します。Omni Queue（通話を Agentforce Contact Center のキューに直接ルーティング）または Omni Flow（着信ルーティングフローを通じて Agentforce エージェントにルーティングし、キューをフォールバックとして使用）です。Omni Queue の経路では、Number Management API と MessagingChannel REST API のみを調整します。Omni Flow の経路では、チャネルの設定に加えて、Agentforce エージェントの作成／公開／有効化、および着信（Copilot）とエスカレーション（QueueBased）の RoutingFlow フローのデプロイも行えます。

範囲

• 対象範囲：利用可能な番号の取得、番号の取得、その CommunicationChannelLine の特定、ライブステータスの確認／調整、ルーティングモデルの選択、（キューまたはフロー経由でルーティングする）PstnVoice MessagingChannel の作成と有効化、および Omni Flow の経路では Agentforce エージェントの作成／公開／有効化と、着信およびエスカレーションの RoutingFlow フローのデプロイを行います。最後に設定の概要を提示します。
• 対象外：組織の認証またはプロビジョニング（対象組織はすでに認証済みである必要があります）、Agentforce／Einstein Service Agent の切り替え設定の有効化（オペレーターが切り替える組織設定です。references/agentforce-prerequisite.md を参照）、発信／音声調整、または既存のチャネルとエージェントの接続、および音声以外のチャネルの作成。

---

前提条件

• 認証済みの組織 — すべての経路で必要です（このスキルでは対話形式のログインを実行しません）。
• Omni Flow の経路のみ — 組織で Einstein と Agentforce Agents が有効になっている必要があります。 音声チャネルを Agentforce エージェントにルーティングするには、組織管理者が Setup UI で Einstein（Setup → Einstein Setup）、次に Agentforce Agents（Setup → Einstein → Agentforce / Agents）を有効にする必要があります。その後、スキルはエージェントの作成と公開に必要な正規の Einstein Agent User（Profile.Name = 'Einstein Agent User'）を特定またはプロビジョニングします。ユーザー名／プロファイルに Agent または Bot が含まれるだけの汎用ユーザーは使用しないでください。そのようなユーザーでは生成や検証はできても、公開に失敗する場合があります。Omni Queue の経路には、この前提条件はありません。手順の詳細：references/agentforce-prerequisite.md。

---

必須入力

進める前に、以下の情報を収集または確認してください。

• 対象組織：すでに認証済みの組織です。ユーザーがエイリアスを指定した場合は、それを使用します。ユーザーがデフォルト組織を指定した場合（またはエイリアスを指定しなかった場合）は、sf org display --json で解決し、result.alias を読み取ります（なければ result.username を使用します）。すべてのスクリプトで、その値を <alias> として使用してください。対話形式のログインは実行しないでください。
• 国：US または CA。
• 電話番号の種類：10DLC または Toll Free。
• 選択した番号：取得した一覧からユーザーが選んだ番号。
• ルーティングモデル：Omni Queue（デフォルト）または Omni Flow。ステップ 7 で確認します。
• （Omni Flow のみ）エージェントのソース：新しい Agentforce エージェントとルーティングフローを作成するか、公開済みの既存エージェントとその着信ルーティングフローを再利用します。
• （Omni Flow の新規エージェントのみ）エージェントのビジネスコンテキスト：エージェント名、エージェントの説明（エージェントの役割／目的）、会社名。sf agent generate agent-spec に渡します。エージェント名は <label> として使用し、<apiName> はそこから導出します（ステップ 9 のサブステップ 3 にある正規化＋一意性のルール）。役割、ウェブサイト、API 名は尋ねないでください。

認証済みの組織と、国および電話番号の種類の両方が決まるまでは進めないでください。ルーティングモデルと、Omni Flow の入力情報は、その経路を選択した場合にのみ収集してください。

---

ワークフロー

すべてのステップを順番に実行します。ステップが失敗した場合は、エラーを報告して停止し、続行しないでください。

1. 組織への接続を確認する — sf org display --target-org <alias> --json を実行し、result.instanceUrl を確認します。失敗した場合は、まず組織を認証するようユーザーに依頼してから、停止します。このスキルから対話型ログインを実行しないでください。

2. 設定を収集する — AskUserQuestion を使って、Country（US／CA）と Phone Number Type（10DLC／Toll Free）を収集します。どの選択肢も推奨またはデフォルトとして示さないでください。選択肢は中立的に提示します。続行する前に、両方の回答を待ちます。

3. 利用可能な番号を取得する — エンドポイントの仕様について、references/number_management_api.md を読みます。取得する前に、結果を絞り込む任意の方法を AskUserQuestion で提示します。具体的には、特定の市外局番（タイプが 10DLC の場合）またはプレフィックス（タイプが Toll Free の場合）の番号を取得するか、利用可能な番号をすべて一覧表示するかを尋ねます。推奨またはデフォルトの選択肢は設けず、中立的に提示します。空欄のままにするか、すべて一覧表示する方法を選ぶと、絞り込みなしで取得されます。その後、ユーザーが指定した市外局番／プレフィックスを任意の第4引数として渡す場合に限り、scripts/fetch-numbers.sh <alias> <country> <phoneType> [searchParam] を実行します。返された番号を番号付きリストで提示し、ユーザーに1つ選んでもらいます。どの番号も推奨またはデフォルトとして示さないでください。絞り込んだ取得で番号が見つからなかった場合は、その旨をユーザーに伝え、別の市外局番／プレフィックスで再試行するか、すべての番号を一覧表示するかを確認します。

4. 選択した番号を取得する — scripts/procure-number.sh <alias> <country> <phoneType> <number> を実行します。2xx 以外の応答が返された場合は、references/number_management_api.md に従ってステータスを判定し、明確なメッセージを伝えて停止します。

5. ChannelLine を解決する — scripts/resolve-channel-line.sh <alias> <number> を実行します。これは Code で CommunicationChannelLine を検索し、結果が空の場合は再試行します。ChannelLine の Id と CodeStatus を取得します。

6. 番号が有効か確認する — scripts/verify-number-live.sh <alias> <number> を実行します。これは Tooling API 経由で CodeStatus を確認し、有効でない場合は numberStateReconcile を呼び出して、references/verification_and_errors.md の戦略に従ってポーリングします。終了コードに応じて処理を分岐します。終了コード 3（ポーリング後も Live ではない）の場合は、警告を伝え、待機するか続行するかを尋ねます。終了コード 4（numberStateReconcile が2xx以外を返した）の場合は、2xx以外で停止するルールに従って停止して報告します。照合に失敗した状態でチャンネルを作成しないでください。

7. ルーティングモデルを選択する — AskUserQuestion を使って通話のルーティング方法を尋ね、ステップ9で分岐します。

   • Omni Queue（デフォルト） — Agentforce Contact Center のキューに直接ルーティングします。
   • Omni Flow — インバウンドルーティングフローを介して Agentforce エージェントにルーティングし、キューをフォールバックとして使用します。

8. コンタクトセンターのキューを解決する — scripts/resolve-acc-queue.sh <alias> を実行して、Agentforce Contact Center のデフォルトキュー Id を検索します。キュー Id をハードコードしないでください。これは組織ごとに異なります。どちらのモデルでも必要です。Omni Queue ではチャンネルの SessionHandlerId として使用し、Omni Flow では FallbackQueueId とエスカレーションフローのターゲットとして使用します。

9. 有効な音声チャンネルを作成する — references/messaging_channel.md を読み、選択したルーティングモデルに応じて分岐します。

   Omni Queue — scripts/create-voice-channel.sh <alias> <number> <channelLineId> <queueId> を実行します。これは、SessionHandlerId にキューを、ChannelLineId に解決済みの CommunicationChannelLine Id を設定し、IsActive: true とした PstnVoice の MessagingChannel を POST します。このリファレンスに記載されているフィールド／ステータスのエラーに対処します。 Omni Flow — references/omni-flow-routing.md を読み、次の手順を実行します。

   1. 前提条件ゲート — scripts/check-agentforce-prereq.sh <alias> を実行します（references/agentforce-prerequisite.md を参照）。終了コード 0 → 出力された正規の Einstein Agent User を --agent-user 用に取得します。スクリプトは既存の Einstein Agent User を再利用するか、sf org create agent-user でプロビジョニングします。終了コード 3 → 正規のユーザーが見つからず、プロビジョニングもできませんでした。多くの場合、トグルがオフになっているか、Agentforce Service Agent User ライセンスを利用できません。ユーザーに組織の問題を解決してから再実行するよう依頼します。ユーザーがキューのみのフォールバックを許可した場合は、上記の Omni Queue の作成手順を使用し、レポートにフォールバックしたことを記載します。
   2. 新規エージェントか既存エージェントか — AskUserQuestion を使用します。
      • 既存を使用 — 公開済みエージェントの API 名／ラベルと、受信 RoutingFlow の DeveloperName を尋ねてから、scripts/resolve-flow-definition.sh <alias> <flowDeveloperName> を実行して、受信 FlowDefinition の ID（300…）を取得します。resolve-flow-definition.sh が検証するのは、そのフローに有効なバージョンがあることだけで、エージェントが公開済みで Active かどうかは検証しません。続行する前に、エージェントの最新の BotVersion.Status = 'Active' を確認するか（SELECT Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<apiName>' ORDER BY VersionNumber DESC LIMIT 1）、その確認はユーザー自身の責任であることを伝えてください。確認しない場合、チャネルは作成されますが、通話はルーティングされません。サブステップ 5 に進みます。
      • 新規作成 — サブステップ 3 に進みます。
   3. エージェントを作成する — AskUserQuestion を使用して、エージェントの業務コンテキストを収集します。尋ねるのは エージェント名、エージェントの説明（エージェントの役割／目的。仕様の --role に設定されます）、会社名 のみです（役割、ウェブサイト、API 名は尋ねないでください）。エージェント名を <label> として使用します。エージェント名から <apiName>（BotDefinition.DeveloperName とルーティングフロー名のベースになります）を生成します。単語を PascalCase にし、英数字以外を除き、先頭を英字にします（必要に応じて A を前置します）。長さは最大 60 文字です。sf data query --query "SELECT DeveloperName FROM BotDefinition WHERE DeveloperName = '<apiName>'" --target-org <alias> で一意性を確認し、重複している場合は数値の接尾辞を追加します。まず scripts/prepare-agent-workdir.sh acc-voice-build で SFDX 作業ディレクトリを準備します。sf agent generate agent-spec は、作成バンドルのスクリプトを実行する前にプロジェクトコンテキストを必要とします。acc-voice-build 内から仕様を生成します。sf agent generate agent-spec --type customer --tone neutral --max-topics 5 --agent-user <einsteinAgentUser> --role "<agent description>" --company-name "<company name>" --output-file specs/<apiName>.yaml --target-org <alias> --json。次に、親／元の作業ディレクトリから scripts/create-voice-agent.sh <alias> <apiName> <label> acc-voice-build/specs/<apiName>.yaml acc-voice-build を実行します。このコマンドは作成バンドルを生成し、生成された default_agent_user を修正して、AiAuthoringBundle をデプロイ、検証、公開、アクティブ化します。プランナーを Atlas__VoiceAgent に切り替えないでください — 公開時に生成された Atlas__ConcurrentMultiAgentOrchestration を維持します（逸脱に関する注記は references/omni-flow-routing.md を参照）。
   4. ルーティングフローをデプロイする — scripts/create-routing-flows.sh <alias> <apiName> <label> <queueId> <queueName> acc-voice-build を実行します。このコマンドは、準備済みの SFDX 作業ディレクトリ内で受信フロー（<apiName>_Voice_Omni_Flow、Copilot）とエスカレーションフロー（<apiName>_Voice_Escalation、QueueBased）をレンダリングしてデプロイし、受信 FlowDefinition の ID（300…）を stdout に出力します。これを取得してください。サブステップ 3 と同じ acc-voice-build 作業ディレクトリを再利用します。
   5. チャネルを作成する — scripts/create-voice-channel.sh <alias> <number> <channelLineId> <flowDefinitionId> <queueId> を実行します。5 番目の引数によって POST が Omni Flow に切り替わります。SessionHandlerId は受信 FlowDefinition の ID、FallbackQueueId はキューです。

10. セットアップを確認してレポートを作成する — 作成した MessagingChannel を読み戻します。その後、assets/report-template.md の構成に正確に従ってレポートを作成します。すべてのフィールドに、この実行で得られた実際の値（組織エイリアス、国、電話番号の種類、ルーティングモデル、実際に実行したコマンド、取得した番号、解決した CommunicationChannelLine の Id とステータス、名前で解決したキューとその Id、作成した PstnVoice MessagingChannel の Id、DeveloperName、ChannelLineId、IsActive、SessionHandlerId、FallbackQueueId、Omni Flow の場合はエージェントの api-name／ラベルとインバウンド FlowDefinition Id）を記入し、最後に Outcome を 1 行で記載します。Omni Flow の行は、その経路を実行した場合にのみ含めます。項目ごとに 1 行とし、補足説明は加えず、該当するフィールドを省略しないでください。手順に失敗した場合も、到達したフィールドには値を記入し、Outcome に正確なエラーと失敗した手順を記載します。

---

ルール／制約

制約	理由
対話形式のログインは決して実行せず、認証済みの組織エイリアスを必須とする	認証と組織のライフサイクルは対象外であり、さまざまな環境でスキルを移植可能にするため
API の呼び出しには sf api request rest を使用し、アクセストークンを決して取り出さない	--target-org に対して CLI に保存されたセッションを使用し、生のトークンを扱わないため
キュー Id／SessionHandlerId／FlowDefinition Id をハードコードしない	これらは組織固有の値です。必ず解決してください（キューは手順 8、フローは resolve-flow-definition.sh を使用）
SessionHandlerId（Omni Flow の場合は FallbackQueueId も）を使ってルーティングを設定し、TargetQueueId や RoutingType は使用しない	Omni Queue：SessionHandlerId = キュー Id。Omni Flow：SessionHandlerId = インバウンド FlowDefinition Id（300…）、FallbackQueueId = キュー Id
Omni Flow：チャネルを作成する前に、エージェントを公開して有効化し、インバウンドフローをデプロイする（Active、300 プレフィックス）	チャネルの SessionHandlerId は、公開済みで有効なエージェントを参照する、稼働中のインバウンド FlowDefinition を指します
エージェントの plannerType を Atlas__VoiceAgent に変更しない	この組織では不透明なエラーが発生します。公開時に生成された Atlas__ConcurrentMultiAgentOrchestration を維持してください。音声は引き続き Copilot フロー経由でルーティングされます（例外）
Agentforce の前提条件を満たしていない場合、またはエージェント／フローの作成に失敗した場合、ユーザーが Omni Queue へのフォールバックを明示的に承認していない限り、停止して報告する	実行によっては、新しい Agentforce エージェントと Omni Flow チャネルが必要です。ルーティングモデルを暗黙的に変更しないでください
CommunicationChannelLine の関連付けには ChannelLine（スカラー値）ではなく ChannelLineId を使用する	ChannelLine はリレーション名であり、書き込み可能な作成フィールドは ChannelLineId です
MessageType は PstnVoice、IsActive は true にする	有効なインバウンド音声チャネルに必須です
PstnVoice チャネルに IsoCountryCode を設定しない	このチャネル種別では無効です
2xx 以外の API レスポンスを受け取った場合は停止して報告する	セットアップが一部だけ完了した状態を黙って残すより、明確に失敗を報告する方がよいため

---

注意点

Issue	解決方法
調達直後に ChannelLine が見つからない	レコードの反映は非同期です。バックオフを入れて再試行してください（Step 5 のスクリプトで処理されます）
番号の CodeStatus が Live ではない	numberStateReconcile を呼び出してポーリングしてください（Step 6 のスクリプトで処理されます）。プロビジョニング中のままの場合は警告してください
チャネル作成時に INVALID_FIELD: The value provided for foreign key reference ChannelLine is not a nested SObject が発生する	関係名 ChannelLine がスカラー項目として送信されています。Id は ChannelLineId で送信してください
FIELD_INTEGRITY_EXCEPTION により稼働状態ではない番号がブロックされる	検証が有効な場合に想定される動作です。番号が稼働状態になるまで待ってから再試行してください
DeveloperName が重複している	その名前のチャネルが存在します。一意の名前を生成するか、既存のチャネルを再利用してください
phoneNumberType にスペースが含まれている（Toll Free）	クエリー文字列の作成時に URL エンコードしてください（スクリプトで処理されます）
sf agent generate agent-spec が RequiresProjectError で失敗する	scripts/prepare-agent-workdir.sh acc-voice-build を実行してから、acc-voice-build 内で --output-file specs/<apiName>.yaml を指定して sf agent generate agent-spec を実行してください
sf agent publish に default agent user NEW AGENT USER と表示される	ジェネレーターが .agent ファイルにプレースホルダーを残しています。create-voice-agent.sh はデプロイ／公開の前に、仕様の agentUser から default_agent_user を修正します
sf agent publish に Unable to access the Salesforce Agent APIs または User doesn't have access to use agent と表示される	通常、仕様／バンドルで汎用の Agent／Bot プロファイルのユーザーが使われています。scripts/check-agentforce-prereq.sh を実行してください。プロファイルが正確に Einstein Agent User であるユーザーが返される必要があります
エージェントの公開／検証時に不明瞭なサーバーエラー（例：-1103525358）が発生する	plannerType: Atlas__VoiceAgent を設定すると発生します。これを削除し、Atlas__ConcurrentMultiAgentOrchestration を維持してください（変更点。create-voice-agent.sh はプランナーに触れません）
ルーティングフローのデプロイが does not contain a valid Salesforce DX project で失敗する	同じ準備済みの acc-voice-build 作業ディレクトリを使用してください。create-routing-flows.sh は現在、そのディレクトリ内から sf project deploy start を実行します
sf agent generate agent-spec／公開がライセンスまたは「default agent user」に関するエラーで失敗する	Agentforce の切り替えがオフか、Agentforce Service Agent User ライセンスを利用できません。有効にするか、ライセンスを解放／プロビジョニングしてください（references/agentforce-prerequisite.md）
Flow Id（301…）を SessionHandlerId として使用している	ハンドルが違います。SessionHandlerId には安定した FlowDefinition Id（300…）が必要です。resolve-flow-definition.sh がこれを返します
インバウンドフローをデプロイしたが、チャネルからエージェントにルーティングされない	エージェントは公開だけでなく有効化されている必要があり、インバウンドフローにも有効なバージョンが必要です。create-voice-agent.sh は BotVersion が Active であることを確認します。アクティブなバージョンがない場合、resolve-flow-definition.sh は 3 で終了します

---

出力の要件

このスキルでは主に、対象組織にレコードを作成します。

• 調達済みの電話番号（Number Management）。
• アクティブな PstnVoice MessagingChannel。コンタクトセンターキュー（Omni Queue）にルーティングするか、キューをフォールバック先とするインバウンドルーティングフローを介して Agentforce エージェントにルーティングします（Omni Flow）。
• Omni Flow のみ：公開済みでアクティブな Agentforce エージェントと、2 つの RoutingFlow フロー（インバウンド Copilot ＋エスカレーション QueueBased）。
• assets/report-template.md に従って作成するレポートと、最終サマリーテーブル（references/setup_summary.md）。

Omni Flow の手順では、デプロイを実行するために acc-voice-build/ の下に使い捨ての SFDX プロジェクト（仕様、オーサリングバンドル、フローメタデータ）も準備します。これらはローカルのビルド成果物であり、スキルの出力ではありません。

---

スキル間の連携

Omni Flow のパスでは、受信音声の配線（エージェント → 受信 Copilot フロー → チャネル、およびエスカレーションフロー）を独自に設定するため、その設定を別のチャネル設定スキルに委ねることはありません。このスキルが生成する音声サービスエージェントを超える、より詳細なエージェント作成（カスタムトピック、アクション、ナレッジ）は対象外です。

---

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

ファイル	参照するタイミング
references/number_management_api.md	ステップ 3～4 — Number Management のエンドポイント、パラメーター、ステータスコードのマッピング
references/verification_and_errors.md	ステップ 6 — ライブ検証のポーリング戦略とエラー処理
references/messaging_channel.md	ステップ 9 — MessagingChannel のフィールド契約（両方のルーティングモデル）と作成時のエラー処理
references/omni-flow-routing.md	ステップ 9（Omni Flow）— ルーティングモデルの契約、エージェント→フロー→チャネルの配線順序、新規と既存の分岐、プランナーからの逸脱、フォールバックルール
references/agentforce-prerequisite.md	ステップ 9（Omni Flow）— Agentforce の切り替えに関する前提条件、事前チェック、Omni-Queue へのフォールバック
references/setup_summary.md	ステップ 10 — ユーザー向けの概要表と次のステップ
assets/report-template.md	ステップ 10 — 作成する report.md の正確な構成
assets/omni-flow.flow-meta.xml	ステップ 9（Omni Flow）— 受信 Copilot RoutingFlow のテンプレート（create-routing-flows.sh によってレンダリング）
assets/escalation-flow.flow-meta.xml	ステップ 9（Omni Flow）— エスカレーション用 QueueBased RoutingFlow のテンプレート（create-routing-flows.sh によってレンダリング）
scripts/prepare-agent-workdir.sh	ステップ 9（Omni Flow）— エージェント仕様の生成前に必要な SFDX プロジェクトコンテキストを準備
scripts/fetch-numbers.sh	ステップ 3 — 利用可能なデフォルト番号を取得
scripts/procure-number.sh	ステップ 4 — 選択した番号を調達
scripts/resolve-channel-line.sh	ステップ 5 — CommunicationChannelLine をリトライ付きで解決
scripts/verify-number-live.sh	ステップ 6 — ライブステータスを検証／調整
scripts/resolve-acc-queue.sh	ステップ 8 — ACC のデフォルトキュー Id を解決
scripts/create-voice-channel.sh	ステップ 9 — アクティブな PstnVoice チャネルを作成（Omni Queue は 4 引数、Omni Flow は 5 引数）
scripts/check-agentforce-prereq.sh	ステップ 9（Omni Flow）— 前提条件の確認ゲート。--agent-user 用の Einstein Agent User を解決
scripts/create-voice-agent.sh	ステップ 9（Omni Flow）— Agentforce 音声エージェントを生成／検証／公開／有効化
scripts/create-routing-flows.sh	ステップ 9（Omni Flow）— 受信フローとエスカレーションフローをデプロイし、受信 FlowDefinition Id を出力
scripts/resolve-flow-definition.sh	ステップ 9（Omni Flow）— 受信フローの FlowDefinition Id（300…）を解決。既存フローの再利用を含む