AiAgentDefinitionVersion Metadata Type in SFDX

Architectural Overview#

Much like Salesforce Flow separates FlowDefinition from individual Flow versions, Agentforce separates the parent AiAgentDefinition from AiAgentDefinitionVersion. Each AiAgentDefinitionVersion represents a discrete, testable iteration of an autonomous agent—binding a specific version number and lifecycle status (Active, Draft, Inactive) to a GenAiPlannerBundle.

This versioning architecture is essential for zero-downtime AI DevOps: teams can iterate on new topics and actions in a draft version, run automated evaluations, and cut over traffic cleanly.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiAgentDefinitionVersion-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AiAgentDefinitionVersion xmlns="http://soap.sforce.com/2006/04/metadata">
    <aiAgentDefinition>Enterprise_Order_Support_Agent</aiAgentDefinition>
    <description>Added automated RMA eligibility verification topic and stricter refund guardrails.</description>
    <genAiPlanner>Enterprise_Order_Support_Planner_v2</genAiPlanner>
    <status>Active</status>
    <versionNumber>2</versionNumber>
</AiAgentDefinitionVersion>

Sample package.xml Manifest#

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

SFDX CLI Retrieval & Deployment#

Retrieve and deploy agent versions using the Salesforce CLI:

# Retrieve all AI Agent Definition Versions
sf project retrieve start --metadata "AiAgentDefinitionVersion:*"

# Deploy the parent definition and specific version together
sf project deploy start --metadata "AiAgentDefinition:Enterprise_Order_Support_Agent" "AiAgentDefinitionVersion:Enterprise_Order_Support_Agent_v2"

Senior Architect Best Practices & Gotchas#

• Immutable Active Versions: Once an AiAgentDefinitionVersion is Active in an org, attempting to overwrite its planner bindings without first deactivating it or incrementing versionNumber can trigger Metadata API lock errors.
• Source Control Pruning: Keep only the current active version (and optionally one previous rollback version) in your main Git branch so your repository doesn’t accumulate dozens of obsolete draft versions.

Frequently asked questions

Why does Salesforce separate AiAgentDefinition and AiAgentDefinitionVersion?

Separating the agent identity from its version allows architects to build, test, and evaluate new draft versions of an agent without disrupting the currently active version in production.

Where are AiAgentDefinitionVersion files stored in SFDX?

They are stored in force-app/main/default/aiAgentDefinitionVersions with the .aiAgentDefinitionVersion-meta.xml file extension.

Can I modify an Active AiAgentDefinitionVersion directly in production?

No, active agent versions are locked to guarantee runtime stability. You must either deactivate the version first or deploy a new version number and activate it.

How do I retrieve AiAgentDefinitionVersion via Salesforce CLI?

Run sf project retrieve start --metadata AiAgentDefinitionVersion to fetch all agent version definitions into your local workspace.