ℹ️ Agent Script aka AIAuthoringBundle metadata is only supported at API v65 and higher, check the version your orgs and repository are using.
Gearset's Agentforce metadata deployment solution simplifies the deployment of AI-powered configuration, such as Agent Scripts. 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. 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, org to org as well as through an automated Pipeline.
What metadata do you need to deploy?
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:
A standard XML registration file (
<agent-name>.bundle-meta.xml)The Agent Script file itself (
<agent-name>.agent), which contains the logic.
ℹ️ To simplify the process of selecting the correct metadata Gearset will surface the AiAuthoringBundle as a single Agent Script in the comparison.
This is what those two files look like when committed to source control:
The AiAuthoringBundle (aka Agent Script) is the source of truth for the agent. When it is committed in an org, Salesforce automatically generates all the other metadata the agent needs to actually run.
When you commit an Agent Script in Agentforce Builder, Salesforce automatically generates a set of dependent metadata components:
A versioned snapshot of the AiAuthoringBundle: a read-only copy of the Agent Script at the time of commit.
An Einstein Bot: the Agentforce agent record itself, created or regenerated from the Script.
A Bot Version: a record of that specific version of the bot.
A GenAiPlannerBundle (aka Agent Planner Bundle): an immutable execution plan that Salesforce generates from the script; this is what actually runs the agent at runtime.
These components are generated by Salesforce as a consequence of committing the Agent Script - if you don't see them in your comparison it may be because you're looking at an un-committed draft version.
Once you've committed (specifically, clicking the Commit Version button in the Salesforce UI) the agent that version is fixed. If the agent logic needs to change, a new version of the Agent Script will need to be created and then deployed.
The Significance of the Committed vs Active vs Draft states
An Agent Script has 3 different states, Draft, Committed and Active.
Draft: This version of the agent is being worked on, and changes can be made to it. It can be tested in Agentforce Builder but has not been committed. No GenAiPlannerBundle, BotVersion, or Bot creation has been triggered.
Committed: The user has committed this version of the agent. Salesforce compiles the script, and generates all the dependent components listed above. A versioned snapshot is created. You cannot un-commit an agent from the Agent Builder UI, so if you need to make changes to the agent you will need to create a new draft version.
Active: The Agent is now available, active, and can be used for the purpose for which it was intended.
To iterate on the agent and develop it further a user will need to create a new version, and make changes to that new draft.
How to deploy an Agent Script (aka AiAuthoringBundle) with Gearset
Before you run your comparison, selecting a filter to make sure that all the metadata you need is retrieved is a good start. Gearset has a default Agentforce filter that we recommend you use.
Because an Agent Script is versioned metadata there may be multiple numbered versions of the same Agent in the same org. This could be confusing if Gearset were to display them all as individual lines in the comparison, so we simplify the view. The Agent is represented as a single row in the comparison, with the most recent version on top.
During metadata comparisons, the latest version from the source is compared against the latest version in the target. You can change the version you want to compare using the dropdown menu.
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.
When the Agent script is stored in your source control repository Gearset will automatically strip the version number, to make sure that the agent in repository exists as a single version. This makes sure that the version of the agent
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.
ℹ️ Committed versions of an Agent Script/AiAuthoringBundle are immutable and cannot be overwritten. If a deployment was to target a committed bundle version with another committed version of the Agent Script, the target Salesforce org would reject it with a "you cannot deploy to a published bundle" validation error.
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.
Post-deployment step: automatic commit in the target
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.
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.
How does Gearset help?
Gearset performs the above series of steps automatically throughout the deployment process, to make sure that the user can choose the specific version of the agent they need, know that it will validate successfully, have it committed in the target and automatically activated without any manual intervention. Gearset automates each of these steps natively, without requiring the user to understand Salesforce's internal versioning model. This means that as the agent is deployed through your pipeline it will require no manual intervention.
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.