agentforce-bot-upgrade

Einstein Bot Upgrade Orchestrator

目的

複数のボットのアップグレードと引き継ぎのサイクルを実行します。

1. --bots からボットとバージョンのペアを解析して検証します
2. ボットとバージョンのペアごとに［Generate Agent Spec Reference］(references/generate-agent-spec.md) に従います（並列実行可能）
3. 生成されたすべての Agent Spec を必要とする集約ステップを実行します
4. Agent Spec ごとに /agentforce-generate を実行します（並列実行可能）
5. 生成された Agent Script ごとに変換後の拡張処理を実行します（並列実行可能）

対象範囲 — このスキルが変換するのは Einstein Bot のみです（BotDefinition／BotVersion チャットボット）を、新しい Agentforce エージェントに変換します。既存の Agentforce エージェントをレガシーの GenAiPlannerBundle から NGA の aiAuthoringBundle に移行するものではありません。その場合は、agentforce-generate スキルの「レガシーエージェントを Agent Script に移行する」フローを使用してください。

入力

入力：

• --mode <online|offline> は省略可能です。省略した場合のデフォルトは online です。
• mode=online の場合、次が必須です。
  • --org-alias <org-alias>
  • --bots <bot1:v1,bot2:v2,...>
• mode=offline の場合、次が必須です。
  • --offline-dir <offline-dir>
• --interactive <true|false> は省略可能です。省略した場合のデフォルトは true です。

必須入力が不足している場合は、以下の「入力不足の処理」および「対話モード」のルールに従ってください。

対話モード

--interactive は、実行中にスキルがユーザー入力を求めて一時停止するかどうかを制御します。

• --interactive true（デフォルト）：このスキルと参照先で説明されているとおり、曖昧さ、未解決の質問、承認ゲートを解消するためにユーザーに質問します。
• --interactive false：自律的に実行します。いかなる判断時点でもユーザーに質問してはいけません。未解決の質問、曖昧さ、承認ゲートにはすべて、文書化された推奨デフォルトまたは解決策を適用し、自動適用した判断を実行成果物（Agent Spec、未解決の質問、抽出サマリー）に記録します。質問せずに許可されるハードストップは、安全な推奨デフォルトがない、不足している、または矛盾している入力に限られます。これには、必須の起動入力（オンラインの場合は --org-alias／--bots、オフラインの場合は --offline-dir）が不足している場合、ボットが見つからない場合、同じボットに複数のバージョンが指定されている場合が含まれます。この場合は問題を報告し、質問せずに停止してください。

有効な --interactive の値を、ボットごとの Generate Agent Spec ワークフロー（ステップ 2）、プランナーワークフロー（ステップ 3）、変換後の拡張処理（ステップ 5）に引き継いでください。

入力不足の処理

ステップ 1 の前に、不足している必須の起動入力を解決してください。

1. オンラインモード — --org-alias が指定されていない場合。 ボット一覧の取得を試みる前に解決してください（一覧の取得には対象 org が必要です）。
   • 対話モード：ログイン済み org の利用可能なエイリアスを一覧表示し、対象 org をユーザーに選択してもらいます。SF CLI Bot Reference の SF CLI パターンを使用してください。
   • 非対話モード：不足している入力として --org-alias を明示したエラーで停止してください（質問も一覧表示も行わないでください）。
2. オンラインモード — ボット名とバージョン（--bots）が指定されていない場合。
   • 対話モード：--org-alias を対象 org として、org 内のすべてのボットとそのバージョンを一覧表示し、エージェントに変換するボット／バージョンの項目をユーザーに選択してもらいます。SF CLI Bot Reference の BotDefinition と BotVersion のクエリパターンを使用してください。すべてのボットとバージョンを列挙するには名前／バージョンのフィルターを省略します。結果を提示し、ユーザーの選択から --bots の対象を作成してください。
   • 非対話モード：不足している入力として --bots を明示したエラーで停止してください（質問も一覧表示も行わないでください）。
3. オフラインモード — --offline-dir が指定されていない場合。
   • 対話モード：ユーザーに --offline-dir のパスを指定してもらい、その後続行します。
   • 非対話モード：不足している入力として --offline-dir を明示したエラーを出して停止してください（質問はしないでください）。

参照資料

実行中は、次の参照ファイルを使用してください。

1. SF CLI Bot Reference
2. Generate Agent Spec Reference
3. Planner Workflow Reference
4. Post-Conversion Enhancements Reference
5. Extraction Blueprint
6. Input Contract
7. Mapping Rules
8. Handoff Output Format
9. Quality Checklist

実行契約

ステップ 1：--bots の解析と検証

次の順序でステップ 1 を実行してください。

1. モードを解決します。
   • --mode が省略された場合は、online を使用します。
2. 今回の実行を新規に開始します。
   • 以前の実行で既に生成された出力を検出、確認、再利用しないでください。
   • 今回の実行コンテキストをクリーンなものとして扱ってください。
   • 今回の実行フローで生成された成果物のみを使用してください。
3. 初期ワークロードリストを作成します。
   • mode=online：--bots を読み取り、カンマで分割します。
   • mode=offline：<offline-dir> をスキャンし、直下のサブディレクトリをボットのワークロードルートとして収集します。
4. 入力形式を検証します。
   • mode=online：各 --bots トークンが <bot-name>:<version> に一致する必要があります。
   • mode=offline：ボットのサブディレクトリが少なくとも 1 つあることを確認します。ない場合は停止します（対話モードではユーザーに確認し、非対話モードでは「対話モード」のルールに従って明示的なエラーを出して終了します）。
5. ワークロードエントリを正規化します。
   • mode=online：{bot_name, bot_version} エントリを作成します。
   • mode=offline：{offline_bot_dir} エントリを作成します（サブディレクトリ構造から推定可能な場合は、推定したボット名とバージョンを記録します。推定できない場合は、名前のないエントリとして処理を続けます）。
6. ボットごとに 1 つのバージョンのみを許可するルールを適用します（オンラインモード）。
   • 同じ bot_name が複数のバージョンで指定されている場合は停止します（対話モードではユーザーに確認し、非対話モードでは「対話モード」のルールに従って明示的なエラーを出して終了します）。
7. オフラインボットのフィルターを適用します。
   • mode=offline で --bots が指定されている場合、検出したサブディレクトリのフィルターとしてのみ --bots を使用します。オフラインで必須の入力として扱わないでください。
8. ステップ 1 の出力を保存します。
   • 検証済みのワークロードリストを保存し、ステップ 2 の並列実行に引き継ぎます。

ステップ 2：Einstein Bot のアップグレードを実行（ボットとバージョンの組み合わせごと）

Generate Agent Spec Reference のエージェント仕様生成ワークフローを、ボットとバージョンの組み合わせごとに実行します。

• --mode <online|offline>（省略時のデフォルトは online）
• モードごとに必要な入力：
  • online → --org-alias、--bot、--bot-version
  • offline → --offline-dir
• --interactive <true|false>（オーケストレーターで有効な値をそのまま渡します。デフォルトは true）

並列化ルール：

• mode=online では、ボットとバージョンの各ペアは独立しているため、呼び出しを並列で実行します。
• mode=offline では、ステップ 1 で検出したすべてのボットサブディレクトリに対して、Generate Agent Spec Reference のワークフローを並列で実行します。
  • 呼び出しごとに --mode offline と --offline-dir <bot-subdirectory-path> を渡します。

ファイルの競合を避けるため、各呼び出し（オンライン／オフライン）には分離された作業ディレクトリを使用してください。

必須ルール：

• このステップを省略しないでください。

ステップ 3：集約とプランナーステップ（条件付き）

すべてのアップグレード呼び出しが完了したら：

1. {bot_name, bot_version, run_project_dir, agent_spec_path} の統合リストを必ず作成します。
2. 失敗または未完了のアップグレード実行のリストを必ず作成します（該当する場合）。
3. 有効な Agent Spec エントリのみを含む、オーサリング準備完了の初期リストを必ず作成します。
   • 各エントリには、{bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path} を含める必要があります。
4. bot の総ワークロード数が 1 より大きい場合：
   • プランナーワークフローのリファレンス のプランナーワークフローを、以下を使用して実行します。
     • オーサリング準備完了リストのすべての agent_spec_path 値を spec_paths として使用
     • オーケストレーターの作業ディレクトリを working_dir として使用
     • オーサリング準備完了リストの各エントリに関連付けられた spec ごとの成果物：handoff_json_path（handoff JSON）と open_questions_path（未解決の質問）
   • <orchestrator working directory>/bot-upgrade-planner-output.json に出力ファイルを必ず作成します。
   • bot-upgrade-planner-output.json を読み取り、以下を適用します。
     • specs_changed=true の場合：プランナーのフィールド（updated_spec_path、run_project_dir、handoff_json_path、open_questions_path）を使用して、オーサリング準備完了リストのエントリを置き換えます。
     • specs_changed=false の場合：元のオーサリング準備完了リストを変更せずに保持します。
5. bot の総ワークロード数が 1 の場合：
   • プランナーワークフロー全体をスキップします。
   • 元のオーサリング準備完了リストを変更せずに保持します。

プランナー出力の要件：

1. ブール値の specs_changed
2. 以下のエントリを含む updated_specs 配列：
   • original_spec_path
   • updated_spec_path
   • run_project_dir
   • handoff_json_path
   • open_questions_path
3. specs_changed=false の場合、updated_specs は空である必要があります。

ステップ 4：Agentforce-Generate を呼び出す（Agent Spec ごと）

最終的なオーサリング準備完了リスト（ステップ 3 のプランナーとの照合後）の各エントリについて：

0. /agentforce-generate を呼び出す前に、以下の推奨事項を生成された呼び出しコンテキストに追加します。
   • このオーケストレーション実行では、Agent Script のバージョンを有効化しないでください。
   • ドラフトの反復が必要です。.agent の生成、検証、デプロイ、プレビューでのテストは許可されています。
   • ユーザーがリリースを明示的に求めない限り、有効化は延期してください。
1. 最終的なオーサリング準備完了エントリから有効な run_project_dir を解決します。
2. <run_project_dir>/agentforce-generate-invocation-prompt.md を最後まで読みます。
3. ステップ 3 でプランナーによって更新された spec パスまたは成果物がある場合は、spec、handoff、未解決の質問の参照が更新後のファイルを指すよう、呼び出しコンテキスト内のパスを置き換えます。
   • プランナーによって run_project_dir も変更された場合は、プロンプトおよび出力契約のパスを解決する際に、更新後の run_project_dir を使用します。
4. 元の生成プロンプトに含まれる、パス以外のすべての指示を変更せずに維持します。
5. 解決済みの呼び出しコンテキストを使用して /agentforce-generate を呼び出します。
6. <run_project_dir>/agentforce-generate-output-contract.md を読み、指定どおりに出力を取得します。

並列処理のルール：

• 各実行は独立しているため、Agent Spec ごとに /agentforce-generate を並列で呼び出します。

出力契約に基づく取得ルール：

1. 必須フィールドおよび成果物については、出力契約を正式な基準として扱います。
2. 契約のフィールドが不足している場合は、ステータスを部分的とし、不足フィールドを明示的に列挙します。
3. 取得した出力は、契約内の名称に一致する決定的なキーで返します。
4. 出力ファイルのパスと、各必須成果物のステータスを維持します。
5. エントリのプロンプトまたは契約ファイルが見つからない場合は、そのエントリを partial として扱い、不足しているパスを記録したうえで、他のエントリの処理を続けます。

ステップ 5：変換後のエージェントスクリプトの強化（生成されたエージェントスクリプトごと）

ステップ 4 の完了後、生成された各 .agent 成果物について、次の処理を行います。

1. キャプチャした /agentforce-generate の出力から、生成された .agent ファイルのパスを特定します。
2. 変換後の強化に関するリファレンスに記載された変換後の強化ワークフローを、次の値を指定して実行します。
   • agentscript_file=<generated-agent-file-path>
   • mode=<online|offline>（ステップ 1 で解決された、実際に使用するオーケストレーターの実行モード）
   • オンラインモードの場合のみ：org_alias=<org-alias>（強化されたエージェントスクリプトを再デプロイするために必須）
3. 既存ファイルの強化を必須とします。
   • 最適化／強化された出力は、同じ .agent ファイルの場所に書き込む必要があります。
4. ファイルごとの強化ステータスと、部分的な失敗があればその内容を記録します。

並列化のルール：

• 各ファイルの強化は独立しているため、生成された .agent ファイル全体で変換後の強化ワークフローを並列実行します。

ステップ 6：実行レポートをまとめて完了する

作業対象のすべてのボットについてステップ 5 が完了した後、次の処理を行います。

1. オーケストレーターの作業ディレクトリに、空でない Markdown ファイルとして、人が読める単一の統合実行レポートを作成します。ボットごとに、実際の実行モード、プランナーが実行されたかどうか（executed または skipped）、生成された Agent Spec のパスと生成された .agent のパス、アクション一覧（NEEDS_STUB 項目を含む）、および --interactive=false の場合は自動適用された判断を記載する必要があります。
2. 実行レポートを最終成果物として扱います。他のすべての成果物（Agent Spec、引き継ぎ JSON、未解決の質問、プランナーの出力、生成された .agent ファイル）がすでに書き込まれた後にのみ、実行レポートを作成します。

成果物

次の内容を返します。

1. 解析されたボット／バージョンの一覧
2. ボットごとのアップグレード実行ステータス
3. 集約出力（Agent Spec の完全な一覧と、作成準備完了の最終サブセット）
4. プランナーワークフローのステータス（executed または skipped）と、実行された場合は bot-upgrade-planner-output.json のパス
5. /agentforce-generate の Spec ごとの実行ステータス
6. ボット／Spec ごとの生成された引き継ぎ成果物のパス（該当する場合はプランナーによって更新された成果物を含む）
7. 出力仕様に従ってキャプチャした /agentforce-generate の出力
8. エージェントごとの変換後の強化ステータス（強化された .agent ファイルのパスを含む）
9. ステップ 6 で作成された統合実行レポートのパス