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/extraction-blueprint.md
View on GitHub# Extraction Blueprint
## Goal
Extract only migration-relevant behavior from Einstein Bot and discard transport noise.
## Required Extractions
### 1) Dialog Graph
**Input files:**
Paths below are shown relative to the bots root directory. For org-backed retrieval this root is the SFDX default metadata directory `force-app/main/default/` (so the full path is `force-app/main/default/bots/<BotName>/…`, as retrieved in [SF CLI Bot Reference](sf-cli-bot-reference.md) section 3). For offline input this root is the provided `--offline-dir` (e.g. `bots/`).
- `bots/<BotName>/<BotName>.bot-meta.xml` (bot-level metadata)
- `bots/<BotName>/<version>.botVersion-meta.xml` (dialog + step graph source of truth)
**Build the graph with this process:**
1. Parse every `<botDialogs>` block in `<version>.botVersion-meta.xml` as one node.
2. For each node, capture:
- `developerName` (node id)
- `label`
- `mlIntent` (if present)
- `dialogGroup` / grouping metadata if present
3. Treat each `<botSteps>` entry inside a dialog as a step in execution order.
4. While scanning each step, also detect action invocations and variable mappings from bot steps:
- invocation/action step types (for example `Invocation`)
- action identifier/name and invocation type (`apex`, `flow`, `standardInvocableAction`, etc.)
- variables read by the action (bot variables passed as invocation inputs)
- variables updated by the action (bot variables set from invocation outputs)
- escalation actions from system messages:
- if a dialog contains `conversationSystemMessage` of type `Transfer`, add an action entry with `action_type: "escalate"`
- resolve the escalation target (`target_type` is one of `queue`, `flow`, `bot`, or `skill`) from the `systemMessageMappings` under that `conversationSystemMessage`:
- **`systemMessageMappings` present:** for each mapped variable (`variableName`):
- **target type** — infer from the variable's `SObjectType` in its `<conversationVariables>` declaration (for example `FlowDefinition` -> `flow`, `Queue` -> `queue`). If `SObjectType` is absent or matches none of these, record it as an open question; do not guess.
- **target value/name** — infer from the variable/value assignments that write the mapped variable earlier in the conversation: `VariableOperation` `Set` steps whose `botVariableOperands` `targetName` is the mapped variable (use `sourceName` for a metadata reference such as `sourceType: FlowDefinition`, or `sourceValue` for a literal), and action output mappings (`invocationMappings` of type `Output`) that write it. When an action output writes the variable, the value is dynamic: record the action and output parameter instead of a fixed name. When different paths assign different values, record each value with the condition under which it is assigned. If no assignment is found, record it as an open question.
- **`systemMessageMappings` absent:** the transfer uses the bot's default routing. Read the `<defaultOutboundFlow>` entry in `bots/<BotName>/<BotName>.bot-meta.xml`. The target type is `flow` and the target name is that entry's value. If the bot has no `<defaultOutboundFlow>`, record the unresolved target as an open question.
- store the resolved `target_type`, the target identifier/value, the source of the resolution (`systemMessageMappings` variable + assignment step, or `defaultOutboundFlow`), and the condition guarding the transfer step on the action record
- end chat from system messages:
- if a dialog contains `conversationSystemMessage` of type `EndChat`, add an action entry with `action_type: "end_session"`
- this is the terminal step in the conversation and indicates that the conversation should be ended
- persist this as `invoked_actions` on the dialog node and as action-level records in `action_inventory`
5. While scanning each step, detect transition-producing step types:
- `Navigation` with `<botNavigationLinks>`
- `Group` containing nested `Navigation`
- `Wait` type steps, which define intent-driven routing points (intent redirect behavior)
6. For every discovered transition, add one directed edge:
- `source_dialog` -> `targetBotDialog`
- `type` (`redirect`, `call`, `intent_redirect`)
7. Capture conditions from enclosing step/group when present:
- `leftOperandName`
- `operatorType`
- `rightOperandValue`
- store as a normalized condition expression on the edge
8. Mark graph role hints:
- probable entry dialogs (for example `Welcome`, `Main_Menu`, or system entry mapping)
- terminal dialogs (for example paths ending in `SystemMessage` + `EndChat`, with no outbound navigation)
**Required output for dialog graph extraction:**
```json
{
"nodes": [
{
"dialog": "Main_Menu",
"label": "Main Menu",
"intent": "Main_Menu",
"invoked_actions": [
{
"action_name": "Airline_Get_User_Details",
"action_type": "flow",
"variables_read": ["user_email"],
"variables_written": ["airline_user", "is_success"]
}
]
}
],
"edges": [
{
"source": "Main_Menu",
"target": "Bookings_Menu",
"type": "redirect",
"condition": null
}
]
}
```
**Quality checks:**
- Every `targetBotDialog` in edges must resolve to an existing dialog node.
- Keep `Call` and `Redirect` distinct (do not merge semantics).
- Preserve multiple outgoing edges from the same step when configured.
### 2) Intent Layer
- Intent name/developer name
- Intent description
- Linked dialogs
- Intent examples/utterances (if available)
**Intent summarization workflow:**
1. For each dialog node in the dialog graph, read its `mlIntent` value (if present).
2. Treat that `mlIntent` as the lookup key for intent metadata in `MlDomain` with the same name.
3. From the matched intent metadata, extract:
- `developerName`
- `label` / `description` (if present)
- `mlIntentUtterances` (training utterances)
4. Generate a concise intent summary (2-3 sentences) per unique intent:
- sentence 1: user goal the intent represents
- sentence 2: typical phrasing style inferred from `mlIntentUtterances`
- sentence 3 (optional): routing nuance or disambiguation hint if overlapping with other intents
5. If an `mlIntent` is referenced by a dialog but no matching `MlDomain` intent is found:
- flag the intent as unresolved
- add it to `open_questions`
- still generate a provisional summary from dialog label/description with `confidence: low`
### 3) Variable and Entity Layer
**Input files:**
- `bots/<BotName>/<BotName>.bot-meta.xml` (context variables, slot/entity metadata)
- `bots/<BotName>/<version>.botVersion-meta.xml` (conversation variable usage through steps)
**Variable extraction and typing rules:**
1. Extract context variables from `bot-meta.xml` (`<contextVariables>` entries).
2. Mark every context variable as:
- `variable_type: linked`
- `data_type`: map from bot metadata `dataType`
- `source`: derive from context mappings (`SObjectType` + `fieldName`) when present
3. Extract conversation variables directly from `botVersion-meta.xml` `<conversationVariables>` entries (authoritative source for declared conversation variables).
4. Mark every conversation variable as:
- `variable_type: mutable`
- `data_type`: read directly from the variable's declared data type in `<conversationVariables>`
**Required output shape (variables):**
```json
{
"variables": [
{
"name": "ContactId",
"data_type": "Id",
"variable_type": "linked",
"source": "MessagingEndUser.ContactId"
},
{
"name": "Complaint_Id",
"data_type": "Text",
"variable_type": "mutable"
}
]
}
```
### 4) Action/Invocation Layer
- Action name and invocation type (`apex`, `flow`, etc.)
- Inputs, outputs, and variable mappings
- Also extract knowledge-backed action signals from `botVersion-meta.xml`:
1. If `knowledgeActionEnabled` is `true`:
- add an action entry with `action_type: "knowledge"`
- include `knowledgeActionEnabled: true`
2. If `knowledgeFallbackEnabled` is `true`:
- add an action entry with `action_type: "knowledge"`
- include `knowledgeFallbackEnabled: true`
- When both fields are `true`, capture both flags (either on one combined knowledge action record or two explicit knowledge action records), but ensure both booleans are present in extracted output.
**Offline mode signature generation (required):**
When input mode is offline (`.bot-meta.xml` + `.botVersion-meta.xml` provided, no org fetch):
1. Prioritize existing local implementation files. For each invoked action, if its Apex class (under `classes/`, using `@InvocableMethod` / `@InvocableVariable`), Flow (under `flows/`), or other referenced artifact is present in `--offline-dir`, generate the signature from that file.
2. Fall back to bot metadata mappings only for actions whose implementation files are not present locally (do not block on missing Apex/Flow source code). For each such invocation mapping:
- extract action parameter names from invocation input/output mapping keys
- resolve mapped bot variable names from mapping values
- infer parameter types from mapped variable declarations in `<conversationVariables>` / `<contextVariables>` when available
3. If type cannot be inferred, use a conservative placeholder type (`Text` or `Object`) and flag in notes/open questions.
4. Keep unresolved/partial signatures as non-blocking and continue extraction.
**Signature construction rules:**
1. Do not copy bot variable names as action parameter names unless metadata explicitly uses the same name.
2. Preserve both layers in output:
- contract layer: `input_name` / `output_name`, `type`
- mapping layer: `mapped_variable`, `variable_type` (`mutable` or `linked`)
3. For each signature entry, capture direction explicitly:
- `direction: input` for values read by the action
- `direction: output` for values written by the action
4. If one action is invoked multiple times with different mappings, keep one action signature and record per-call mapping context separately (for example `call_context`).
### 5) Dialog Clusters and Categorization
After extracting actions and dialog/action mappings, categorize bot functionality into dialog clusters.
1. Classify actions into groups using these priority criteria (highest priority first):
- actions working on the same underlying entity SHOULD be grouped together
- actions writing/updating the same variable SHOULD be grouped together
- actions reading the same input variable CAN be grouped together
- actions invoked by dialogs in the same dialog group CAN be grouped together
- actions with similar intent CAN be grouped together
2. Keep group size between:
- minimum: 1 action
- maximum: 4 actions
If a group exceeds 4 actions, split it while preserving higher-priority criteria.
3. An action may belong to multiple groups when criteria requires an overlap.
4. Assign dialogs to groups based on associated actions:
- for each grouped action, trace back dialogs that invoke it
- include those dialogs in the corresponding dialog cluster
- maintain an `action_dialog_mapping` for each group (`action -> [dialogs]`)
5. Generate a short functional description (2-3 sentences) per group using grouped actions and associated dialogs.
## Extraction Output Shape
Build an intermediate extraction summary used by mapping:
```json
{
"run_identity": {},
"dialog_graph": {
"nodes": [],
"edges": []
},
"intent_catalog": {},
"variables": {},
"action_inventory": {},
"dialog_clusters": {},
"unmapped_items": {}
}
```
## Persist Extraction Output
Write the extraction summary to a JSON file before starting mapping.
- Output filename: `extraction-summary.json`
- Output location: same working/output directory used for the current bot/version handoff artifacts
- The file content must preserve the extraction output shape defined above
- If extraction is rerun, overwrite this file with the latest extraction snapshot
`action_inventory` should include any extracted knowledge action entries with explicit `knowledgeActionEnabled` and/or `knowledgeFallbackEnabled` boolean flags when present in bot version metadata.
## Extraction Principles
- Favor explicit configured behavior over assumptions.
- Preserve branch conditions where available.
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 |