Loading

Agentforce SFDX Deployment Prerequisites

Publish Date: Jan 29, 2026
Task

Before attempting to deploy an Agent using SFDX , your local / source environment and the target Salesforce Org must be strictly configured. Agentforce metadata is highly dependent on feature toggles and specific API versions. Skipping these checks is the primary cause of deployment failures.

Steps

1 . Local Environment Setup

Because Agentforce components are rapidly evolving, older versions cannot refer the new metadata types.

  • Update Salesforce CLI: Run sf update to ensure you have the latest CLI version.

  • Set API Version to 64.0+: Check your sfdx-project.json. You must target API version 64.0 or higher.

Critical Note: API v64.0+ introduced GenAiPlannerBundle, which replaces the older GenAiPlanner. For older API versions, some components may not get deployed.

2. Target Org Readiness Checklist

Log in to your Target Org (the org you are deploying to) and verify these four feature toggles are enabled.

Feature Area

Navigation Path

Action

Einstein

Setup → Einstein Setup

Toggle Turn on Einstein to "On".

Bots

Setup → Einstein Bots

Toggle Einstein Bots to "On".

Agents

Setup → Agents

Toggle Einstein Copilot for Salesforce to "On".

Data Cloud

Setup → Data Cloud Setup

Click Get Started / Enable.

Note: If your target is a Sandbox, Data Cloud must be enabled in your Production org first (Setup → Data Cloud Setup → Feature Manager → Data Cloud in Sandbox → Enable).

3. Agent User Configuration

Agents like Service Agent and Lead Nurturing Agent run as a specific user. This user must exist in the Target Org before deployment.

  1. Create the User: Create a new user in the Target Org.

  2. Assign License: Select Einstein Agent.

  3. Assign Profile: Select Einstein Agent User.

  4. Permission Sets: If your Agent needs to access specific Objects, Flows, or Apex, create a Permission Set and assign it to this user.

Additional Resources

Known Technical Constraints

Be aware of these specific metadata behaviors before you package your work:

  • Prompt Templates & Flows: If a Prompt Template references a Flow, it often fails validation.

    • Workaround: You may need to remove the Flow reference from the template XML before deploying, then manually re-add it in the Target Org’s Prompt Builder.

  • Spring '25 XML Error: If deploying GenAiPlugin or GenAiFunction, you may encounter an UNKNOWN_EXCEPTION. To fix this, remove or comment out these fields from your XML before deploying:

    • <ProgressIndicatorMessage>
    • <IsIncludeInProgressIndicator>
    • <CanEscalate>

  • Data Cloud Objects: These cannot be deployed via Metadata API. They must be bundled into a Data Kit and installed in the target org separately.

Knowledge Article Number

005237033

 
Loading
Salesforce Help | Article