AiAuthoringBundle Metadata Type in SFDX

Architectural Overview#

As enterprise engineering teams scale Agentforce adoption, authoring agents solely via point-and-click UI builders creates bottlenecks in multi-developer Git workflows. The AiAuthoringBundle metadata type enables pro-code and hybrid development teams to define, version, and review Agentforce agent authoring specifications as a cohesive metadata bundle in Salesforce DX.

Architecturally, AiAuthoringBundle acts as the developer-friendly authoring representation that compiles and synchronizes with the runtime AiAgentDefinition and GenAiPlannerBundle execution engine.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiAuthoringBundle-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Source-driven authoring bundle for the B2B CPQ Quote Assistant agent.</description>
    <masterLabel>B2B Quote Assistant Bundle</masterLabel>
</AiAuthoringBundle>

Sample package.xml Manifest#

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

SFDX CLI Retrieval & Deployment#

Use the sf CLI to retrieve, validate, and deploy AiAuthoringBundle directories:

# Retrieve all AiAuthoringBundle components from the org
sf project retrieve start --metadata "AiAuthoringBundle:*"

# Retrieve a specific AiAuthoringBundle by name
sf project retrieve start --metadata "AiAuthoringBundle:B2B_Quote_Assistant_Bundle"

# Deploy the bundle directory directly
sf project deploy start --source-dir force-app/main/default/aiAuthoringBundles/B2B_Quote_Assistant_Bundle

Senior Architect Best Practices & Gotchas#

• Verify Action Targets Before Deploying: An AiAuthoringBundle frequently references GenAiFunction actions backed by autolaunched Flows or invocable Apex classes. Ensure all underlying Flows and Apex classes are deployed in the same transaction or already present in the target org.
• Avoid Mixed Authoring Collisions: Establish a clear team governance rule: if an agent is managed via AiAuthoringBundle in Git, restrict hotfix edits in the production Agent Builder UI so local SFDX bundles remain the single source of truth.

Frequently asked questions

What is AiAuthoringBundle in Salesforce Agentforce?

AiAuthoringBundle is a bundle metadata type that encapsulates declarative and pro-code agent authoring specifications, allowing developers to author and version agents directly in SFDX.

Where are AiAuthoringBundle files located in an SFDX project?

They are stored under force-app/main/default/aiAuthoringBundles/BundleName/ with a root .aiAuthoringBundle-meta.xml descriptor file.

How does AiAuthoringBundle improve CI/CD for Agentforce?

It unifies agent authoring artifacts into a single source-tracked bundle directory, simplifying code reviews, diffing, and multi-stage sandbox deployments.

How do I retrieve an AiAuthoringBundle using the Salesforce CLI?

Run sf project retrieve start --metadata AiAuthoringBundle to pull all authoring bundles into your local SFDX workspace.