Agentforce Bot Upgrade

Einstein Bot Upgrade Orchestrator

Purpose

Run a multi-bot upgrade-and-handoff cycle:

1. Parse and validate bot/version pairs from --bots
2. Follow Generate Agent Spec Reference per bot-version pair (parallelizable)
3. Aggregation step that requires all generated Agent Specs
4. /agentforce-generate per Agent Spec (parallelizable)
5. Post-conversion enhancement pass per generated Agent Script (parallelizable)

Inputs

Inputs:

• --mode <online|offline> is optional; default is online when omitted.
• If mode=online, required:
• --org-alias <org-alias>
• --bots <bot1:v1,bot2:v2,...>
• If mode=offline, required:
• --offline-dir <offline-dir>
• --interactive <true|false> is optional; default is true when omitted.

If required inputs are missing, handle per the Missing Input Handling and Interactive Mode rules below.

Interactive Mode

--interactive controls whether the skill pauses for user input during execution:

• --interactive true (default): resolve ambiguities, open questions, and approval gates by asking the user, as described in this skill and its references.
• --interactive false: run autonomously. Do NOT prompt the user at any decision point. For every open question, ambiguity, or approval gate, apply the documented recommended default/solution and record the auto-applied decision in the run artifacts (Agent Spec, open questions, extraction summary). The only hard stops permitted without prompting are inputs that are missing or contradictory with no safe recommended default — a missing mandatory launch input (--org-alias/--bots for online, --offline-dir for offline), no bots discovered, or the same bot given multiple versions. In those cases, report the issue and halt without prompting.

Propagate the effective --interactive value to the per-bot Generate Agent Spec workflow (Step 2), the planner workflow (Step 3), and the post-conversion enhancement pass (Step 5).

Missing Input Handling

Resolve missing required launch inputs before Step 1:

1. Online mode — `--org-alias` not provided. Resolve this before attempting to list bots (listing requires a target org).

• Interactive: list the available aliases of logged-in orgs and ask the user to select the target org. Use the SF CLI patterns in SF CLI Bot Reference.
• Non-interactive: halt with an explicit error naming the missing --org-alias input (do not prompt or list).

1. Online mode — bot name and version (`--bots`) not available.

• Interactive: using --org-alias as the target org, list every bot and its versions in the org, then ask the user to select the bot/version entries they want to convert to agents. Use the BotDefinition and BotVersion query patterns in SF CLI Bot Reference — omit the name/version filters to enumerate all bots and versions — present the results, and build the --bots workload from the user's selection.
• Non-interactive: halt with an explicit error naming the missing --bots input (do not prompt or list).

1. Offline mode — `--offline-dir` not available.

• Interactive: ask the user to provide the --offline-dir path, then continue.
• Non-interactive: fail with an explicit error naming the missing --offline-dir input (do not prompt).

References

Use these reference files during execution:

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

Execution Contract

Step 1: Parse and Validate --bots

Execute Step 1 in this order:

1. Resolve mode:

• If --mode omitted, use online.

1. Start fresh for this invocation:

• do not discover, inspect, or reuse outputs from previously existing runs
• treat this invocation as a clean execution context
• only use artifacts produced during the current invocation flow

1. Build initial workload list:

• mode=online: read --bots and split by comma.
• mode=offline: scan <offline-dir> and collect immediate sub-directories as bot workload roots.

1. Validate input shape:

• mode=online: each --bots token must match <bot-name>:<version>.
• mode=offline: ensure at least one bot sub-directory exists; otherwise STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).

1. Normalize workload entries:

• mode=online: build {bot_name, bot_version} entries.
• mode=offline: build {offline_bot_dir} entries (Annotate inferred bot name and version when derivable from the sub-directory structure; if not derivable, leave the entry unnamed and continue).

1. Enforce one-version-per-bot rule (online mode):

• If the same bot_name appears with multiple versions, STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).

1. Apply offline bot filter:

• If mode=offline and --bots is provided, use --bots only as a filter over discovered sub-directories; do not treat it as required offline input.

1. Persist Step 1 output:

• Save and carry forward a validated workload list for Step 2 parallel execution.

Step 2: Run Einstein Bot Upgrade (Per Bot-Version)

Execute the agent spec generation workflow from Generate Agent Spec Reference per bot-version combination:

• --mode <online|offline> (default online if omitted)
• mode-specific required inputs:
• online -> --org-alias, --bot, --bot-version
• offline -> --offline-dir
• --interactive <true|false> (pass through the effective orchestrator value; default true)

Parallelization rule:

• In mode=online, execute invocations in parallel because each bot-version pair is independent.
• In mode=offline, execute the Generate Agent Spec Reference workflow in parallel over every bot sub-directory discovered in Step 1.
• Pass --mode offline and --offline-dir <bot-subdirectory-path> per invocation.

Ensure each invocation (online/offline) uses isolated working directories to avoid cross-run file collisions.

Hard rules:

• Do not skip this step.

Step 3: Aggregation + Planner Step (Conditional)

After all upgrade invocations complete:

1. Always build a consolidated list of {bot_name, bot_version, run_project_dir, agent_spec_path}.
2. Always build list of failed/incomplete upgrade runs (if any).
3. Always build an initial ready-for-authoring list containing only valid Agent Spec entries.

• Each entry must include: {bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path}.

1. If total bot workload count is greater than 1:

• Execute planner workflow from Planner Workflow Reference using:
• all ready-for-authoring agent_spec_path values as spec_paths
• orchestrator working directory as working_dir
• the associated per-spec artifacts from each ready-for-authoring entry: handoff_json_path (handoff JSON) and open_questions_path (open questions)
• Require output file at <orchestrator working directory>/bot-upgrade-planner-output.json.
• Read bot-upgrade-planner-output.json and apply: