forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-bot-upgrade
agentforce-bot-upgrade
FlaggedUse this skill to upgrade Einstein Bots into Agentforce agents end-to-end in a single pass, orchestrating per-bot Agent Spec generation, agentforce-generate authoring, and post-conversion .agent enhancements. TRIGGER when: user asks to migrate, upgrade, or convert one or more Einstein Bots (BotDefinition/BotVersion chatbots) to Agentforce agents; runs a multi-bot bot-to-agent upgrade; needs Einstein Bot metadata turned into Agent Spec handoffs and generated .agent agents; convert bots to agents; upgrade my service bots; move bots to Agentforce. DO NOT TRIGGER when: user already has an approved Agent Spec and only wants direct .agent authoring, deploy, test, or observe flows; user wants to migrate or upgrade an EXISTING Agentforce agent from a legacy GenAiPlannerBundle to an NGA aiAuthoringBundle (that is agentforce-generate's 'Migrate a Legacy Agent to Agent Script' flow, not an Einstein Bot upgrade); the request is unrelated to Einstein Bot migration.
references/sf-cli-bot-reference.md
View on GitHub# SF CLI Bot Reference
Essential SF CLI command sequence for Online mode (org-backed retrieval) after inputs are finalized (`--org-alias`, `--bot`, `--bot-version`).
Do not use this reference in Offline mode (local metadata input). In offline mode, skip SF CLI retrieval and continue with extraction/mapping from local XML metadata files.
## 1) Prerequisite checks
```bash
sf --version
sf org display --json --target-org <org-alias>
```
If no orgs are available (no authenticated orgs are found), branch on the effective `--interactive` value:
- **`--interactive=true`**: ask the customer to log in to an org using:
```bash
sf org login web --instance-url <LOGIN_URL> --alias <ALIAS>
```
When asking, inform the customer about the default values so they can accept them or override:
- `--instance-url` defaults to `https://login.salesforce.com` when omitted. Tell the customer to use the default for production and Developer Edition orgs, `https://test.salesforce.com` for sandboxes.
- **`--interactive=false`**: do NOT prompt. Halt with an explicit error: `No authenticated org found for the provided --org-alias; run sf org login web and retry.`
## 2) Validate bot and version
`BotVersion.VersionNumber` is a numeric field, but `<bot-version>` is supplied in the `v1`/`v2`/`v3` format. Derive `<version-number>` by stripping the leading `v` from `<bot-version>` (e.g. `v1` -> `1`, `v12` -> `12`) and use that numeric value in the SOQL filter. Keep the original `<bot-version>` (`vN`) form for the metadata retrieval in section 3.
Listing bots:
```bash
sf data query --json --target-org <org-alias> \
--query "SELECT MasterLabel FROM BotDefinition WHERE Type = 'Bot'"
```
Listing bot versions:
```bash
sf data query --json --target-org <org-alias> \
--query "SELECT Id, VersionNumber, Status FROM BotVersion WHERE BotDefinition.Type = 'Bot'"
```
Validating the target bot:
```bash
sf data query --json --target-org <org-alias> \
--query "SELECT Id, DeveloperName, MasterLabel FROM BotDefinition WHERE Type = 'Bot' AND DeveloperName = '<bot-name>'"
```
Validating the target bot version:
```bash
sf data query --json --target-org <org-alias> \
--query "SELECT Id, VersionNumber, Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<bot-name>' AND VersionNumber = <version-number>"
```
Each validation query must return exactly one record. If either returns zero records, the bot or version does not exist in the target org: in interactive mode, show the user the bot/version listing above and ask them to pick a valid entry; in non-interactive mode, halt with an explicit error naming the missing `<bot-name>` or `<bot-version>`.
## 3) Retrieve bot metadata
Before retrieval, ensure an SF project directory exists:
1. If no project exists for this migration run (`sfdx-project.json` doesn't exist), create one:
`sf project generate --name <bot-name>-<bot-version>-agent --template "empty" --output-dir "."`
2. Change into that project directory.
3. Run all remaining sf cli commands from that same project directory.
```bash
sf project retrieve start --target-org <org-alias> \
--metadata "Bot:<bot-name>" "BotVersion:<bot-name>.<bot-version>"
```
## 4) Retrieve related ML domains (only if referenced)
After bot metadata retrieval, discover referenced ML domains from the retrieved bot XML metadata using the same pattern as the migration script (`relatedMlIntent` entries in `<Domain.Intent>` format), then retrieve each domain.
Bot XML exists at: `force-app/main/default/bots/<bot-name>/<bot-name>.bot-meta.xml` (relative to the generated SFDX project directory from section 3).
Use this sequence:
1. Read the bot metadata XML file.
2. Find all `relatedMlIntent` values.
3. For each value, split on `.` and keep only the domain name prefix.
4. De-duplicate the discovered domain names.
5. For each discovered domain, run:
`sf project retrieve start --target-org <org-alias> --metadata "MlDomain:<domain_name>"`
If no `relatedMlIntent` entries are found, skip MLDomain retrieval.
## 5) Retrieve invocation dependencies (Apex/Flow)
The pipeline extracts invocation names from bot metadata, then retrieves only those exact classes/flows.
### Apex classes
```bash
sf project retrieve start --target-org <org-alias> --manifest <apex-package.xml>
```
`<apex-package.xml>` should contain only required classes:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>ClassA</members>
<members>ClassB</members>
<name>ApexClass</name>
</types>
<version>67.0</version>
</Package>
```
### Flows
```bash
sf project retrieve start --target-org <org-alias> --manifest <flow-package.xml>
```
`<flow-package.xml>` should contain only required flows:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>FlowA</members>
<members>FlowB</members>
<name>Flow</name>
</types>
<version>67.0</version>
</Package>
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |