Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-bot-upgrade

agentforce-bot-upgrade

Flagged

Use 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>
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall