AgentPlatformSettings Metadata Type in SFDX

Architectural Overview#

Before any autonomous AI agent, reasoning planner, topic (GenAiPlugin), or action (GenAiFunction) can be deployed or executed in Salesforce, the underlying Agentforce runtime must be enabled at the org level. The AgentPlatformSettings metadata type (AgentPlatform.settings-meta.xml) serves as this master architectural switch.

In CI/CD pipelines that spin up scratch orgs or promote Agentforce solutions to testing sandboxes, AgentPlatformSettings must be deployed as the foundational prerequisite before any downstream AI agent metadata.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample AgentPlatform.settings-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AgentPlatformSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableAgentPlatform>true</enableAgentPlatform>
</AgentPlatformSettings>

Sample package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>AgentPlatform</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AgentPlatformSettings via the Salesforce CLI:

# Retrieve AgentPlatformSettings from the target org
sf project retrieve start --metadata "Settings:AgentPlatform"

# Deploy AgentPlatformSettings prior to deploying agent definitions
sf project deploy start --metadata "Settings:AgentPlatform"

Senior Architect Best Practices & Gotchas#

• Staged Deployment Pipeline: In automated CI/CD workflows, deploy Settings:AgentPlatform (and Einstein Generative AI settings) in a pre-deployment stage before deploying GenAiPlannerBundle, GenAiPlugin, and GenAiFunction components.
• Avoid Accidental Deactivation: Never deploy <enableAgentPlatform>false</enableAgentPlatform> to an active staging or production org—doing so immediately halts active Service Agents and Employee Agents across all channels.
• Agent User Security: Enabling the platform is only step one; ensure your autonomous agents execute under least-privilege user contexts governed by dedicated PermissionSet assignments.

Frequently asked questions

What does AgentPlatformSettings control in Salesforce?

It controls the master org-level enablement toggles for the Agentforce platform, allowing autonomous AI agents, planners, Topics, and Actions to execute.

Where is AgentPlatformSettings stored in an SFDX repository?

It is stored in force-app/main/default/settings/AgentPlatform.settings-meta.xml and referenced in package.xml under Settings with member AgentPlatform.

What happens if I deploy GenAiPlannerBundle before enabling AgentPlatformSettings?

Deploying agent planners, topics, or agent definitions to an org where AgentPlatformSettings is disabled will fail with a missing feature or invalid type error.

How do I retrieve AgentPlatformSettings using the Salesforce CLI?

Execute sf project retrieve start --metadata Settings:AgentPlatform to retrieve the XML configuration into your local project.