Gearset's Agentforce metadata deployment solution simplifies the deployment of AI-powered configuration, such as Agent Scripts, in Salesforce. An Agent Script is the instruction manual for your AI. It tells the agent who it is, what it’s allowed to do, and how to use Salesforce tools to help customers while maintaining brand voice and security compliance. Rather than configuring agents purely through clicks in Agentforce Builder, Agent Script lets teams define their agent's logic, guardrails, and available tools in code.

This guide will explain how to successfully deploy the Agent Script (AiAuthoringBundle) metadata via Gearset.

Using the default Agentforce filter is a good starting point to make sure you've included all the relevant metadata in your comparison.

When you build an agent using Agent Script, it lives inside a Salesforce metadata type called an AiAuthoringBundle. Each bundle is made up of two files:

The AiAuthoringBundle is the source of truth for the agent. When it is published (committed) to an org, Salesforce reads it and automatically generates all the other metadata the agent needs to actually run.

To simplify the process of selecting the correct metadata Gearset will surface the AiAuthoringBundle as a single Agent Script in the comparison.

When you commit an Agent Script version in Agentforce Builder, Salesforce automatically generates a set of dependent metadata components:

These components are not manually created by the user. They are generated by Salesforce as a consequence of committing the Agent Script.

Crucially, the GenAiPlannerBundle is immutable; if the agent logic needs to change, a new version of the Agent Script must be committed, which generates a new GenAiPlannerBundle.

An Agent Script has a two-stage lifecycle that is fundamental to understanding deployment:

Draft: The agent is being worked on. It can be tested in Agentforce Builder but has not been committed. No GenAiPlannerBundle, BotVersion, or Bot regeneration has been triggered. The draft lives in the unversioned AiAuthoringBundle (no number suffix, e.g. My_Agent).

Committed: The developer has confirmed a version of the agent. Salesforce compiles the script, validates it, and generates all the dependent components listed above. A versioned, numbered snapshot is created (e.g. My_Agent_1, My_Agent_2, etc.).

The lifecycle looks like this:

To understand version assignment, it helps to know that every Agent Script actually exists in two forms simultaneously in an org:

The unversioned bundle (e.g. My_Agent): This is the draft slot. It holds the current working draft of the agent and has no number suffix. There is always exactly one of these per agent, and it is the only form that can be written to via a deployment.

Versioned bundles (e.g. My_Agent_1, My_Agent_2, My_Agent_7): These are committed, immutable snapshots. Each one was created when someone committed their draft. They cannot be overwritten or edited; they are a permanent historical record of what the agent looked like at that point in time.

The version number suffix on committed bundles is not a running counter maintained by Salesforce centrally. It is simply a label, and crucially, it is assigned independently in each org.

An added detail to be aware of is that the version numbers attached to AiAuthoringBundle are separate from the version numbers assigned to BotVersion records, so the two do not necessarily correspond to each other.

BotVersion records are generated automatically by Salesforce each time an AiAuthoringBundle is committed. However, Salesforce assigns BotVersion numbers sequentially based on how many bot versions have been committed, not based on which AiAuthoringBundle version triggered them.

Agent Scripts utilize a specific versioning logic when handled via the Metadata API.

During metadata comparisons, the latest version from the source is compared against the latest version in the target.

If the Agent Script has multiple versions on the source side, you can use the Agent Script Visualizer to identify which version is the latest in the source org currently.

If you want to deploy a different version, select your desired version from the dropdown menu.

Note: For Git to org comparisons, the latest version will always be selected for the comparison and deployment so the changes from different developers to the same Agent can be reviewed and merged correctly in the pipeline.

Once you've selected your Agent Script, click Next.

If the Agent Script in the target org is already committed, the target org will only allow the deployment of a draft version to prevent the overwrite of active logic.

Gearset's Problem Analyzer checks whether the selected version is committed, and alter the proposed deployment so that your Agent Script will be deployed as a draft.

Because Salesforce auto-generates the BotVersion, Bot, and GenAiPlannerBundle when the draft version of the Agent Script is committed, you don't need to include these as dependencies when you make your deployment.

Because Gearset makes the change automatically the user does not need to manually edit any metadata.

Once the Agent Script has been deployed as a draft to the target org, someone who doesn't use Gearset would need to log into Agentforce Builder and manually commit the draft to trigger generation of the GenAiPlannerBundle, Bot, and BotVersion.

Gearset handles this automatically, with a Commit Agent Script after deployment post-deployment step (currently only available for org to org deployments, with pipeline support coming soon).

When enabled, Gearset automatically triggers the commit in the target org after the deployment of the draft completes - generating all dependent components without any manual intervention.

Without Gearset, a user attempting to deploy an Agent Script would need to understand the committed-bundle constraint, manually edit their deployment package, deploy to the correct draft slot, then log into Agentforce Builder to commit the draft and generate the dependent components. Gearset automates each of these steps natively, without requiring the user to understand Salesforce's internal versioning model.

To learn more about deploying Agentforce with Gearset check out our other documentation or get in touch with our customer support team via the in-app chat.