Important to note: Make sure to use at least API version 65 for the comparison to retrieve the Agent Script metadata type.
Introduction
An Agentforce agent is an AI-powered assistant built on Salesforce’s Agentforce platform that can help users by handling questions and tasks without needing constant guidance. It is designed to help teams work faster and more efficiently by combining generative AI with Salesforce data, automation, and decision-making capabilities.
This guide will explain how to successfully deploy Agentforce Agents via Gearset.
Prerequisites
In both source and target orgs, Agentforce / Einstein Generative AI must be enabled through Setup.
Your Metadata API version must be 60.0 or higher because the Agentforce (GenAI) metadata types (like GenAiPlanner, GenAiFunction, GenAiPlugin, etc.) were introduced starting in API version 60.
Please, ensure that you have the necessary permission set licenses to retrieve Agentforce metadata types.
The required licenses include:Agentforce (Default)
Agentforce Service Agent Builder
Einstein Prompt Templates
Prompt Template Manager
What metadata is needed in the filter?
To move an Agentforce agent from one org to another, you need to deploy the metadata that covers the core agent definition and its version, the planning or reasoning configuration, and the associated topics, actions, and prompt templates that power the agent’s functionality.
It is recommended to select Default Agentforce comparison filter to include all the required dependencies in the comparison.
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.
How to deploy an Agent with Gearset
If the agent was created using the Agent Script editor, you need to select the Agent Script (AiAuthoringBundle) metadata type in the filter.
This demo will explain how to successfully deploy the Agent Scripts (AiAuthoringBundle) metadata via Gearset.
What metadata is needed in the filter?
In your metadata filter, you will need to include at leasr Agent Script along with the Einstein Bot metadata types. Using the default Agentforce filter is a good starting point.
How to deploy your Agent (AiAuthoringBundle) metadata with Gearset
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 target Agent Script is committed, Salesforce will only allow deployment of a draft version, which will automatically create a new version in the target environment. A problem analyzer will appear to highlight this.
The committed Agent Scripts cannot be deployed in isolation. They must be deployed alongside the Bot, BotVersion and the GenAiPlanner Bundle that the Agent Script is dependant on.
You will encounter a problem analyzer due to missing dependencies if you don't include them in the deployment.
When you deploy a draft Agent script to a target environment, if the latest version in target is already committed, the deployment process automatically triggers the creation of a new draft version in the target org to preserve history and prevent the accidental overwriting of active logic.
Note: In some cases, deploying a committed Agent Script can result in unexpected Salesforce errors. We recommend deploying the scripts as drafts first and then committing them in the target.
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.
Check out these related documents on deploying Agentforce metadata types: