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.
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. Learn more about Agent Scripts here.
Agentforce metadata
The underlying metadata that makes up an agent may be different depending on when they were created - for example over the course of 2026 alone the key metadata for the agents configuration has transitioned from GenAIPlannerBundle, to AiAuthoringBundle, and most recently in v68 of the metadata API they have transitioned to AiAgentDefinition and AiAgentDefinitionVersion. Legacy agents (created pre v65) are now deprecated by Salesforce as of the release of v68.
Because of the way that Gearset lets the user select the agent by name rather than by metadata type, as a Gearset user you don't need to worry about these changes.
You can see a table below documenting the evolution of Agentforce metadata:
Era | API | What an agent is, on disk |
Planner | v60–v63 |
|
Planner Bundle | v64–v67 |
|
Agent Script | v65–v67 | the above plus |
Agent Definition | v68+ |
|
Before your first deployment
If you have never made an Agentforce deployment before, you may want to make sure that the necessary features are enabled and your user has the correct Salesforce permissions.
In both source and target orgs, Agentforce / Einstein Generative AI need to be enabled through Setup.
If you're using source control, make sure that the API version in your source control repository is at least v65, and ideally at the current API version (at time of writing this is v68). As mentioned above, legacy (pre v65) agents have been deprecated by Salesforce, so you want to make sure you're operating at the correct version required for the current agent format.
Ensure that you, or the pipeline service user, have the necessary permission set licenses to retrieve Agentforce metadata types;
Agentforce (Default)
Agentforce Service Agent Builder
Einstein Prompt Templates
Prompt Template Manager
Deploying an agent with Gearset
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.
Gearset makes this easy, by giving you a list of your agents to choose from by name and automatically calculating the necessary components and dependencies for a complete and successful deployment.
We also automatically complete post deployment steps for you like agent activation, so that an agent that started out active in the org it was developed in can be uniformly activated in every other org it's deployed to.
Whether or not you use source control as part of your process, deploying your agent through Gearset gives you a clear audit trail, and the ability to roll back your deployments.
If you're deploying directly to an org, without a pipeline:
On the compare and deploy screen of Gearset, select your source and target environments. Select the option at the bottom of the screen named Data kits & agents.
After selecting this, you'll see a screen where you can see a list of Data kits (for the deployment of Data 360) and a list of your agents.
Select your agent that you want to deploy, and click next. You don't have to worry about selecting metadata, or a particular type of agent - knowing the name of the agent that you want to deploy is all you need.
Gearset will build a comparison between your source and target, using the latest version of the agent, and automatically find and select your dependencies.
If you decide that you want to deploy an earlier version of your agent simply select it from this drop down menu, Gearset will dynamically recalculate the dependencies.
After Gearset has found all of the components for deployment, you can review the changes in the comparison and click Next.
If there are environment specific values that need to be taken care of at this stage, then Gearset will automatically apply those changes. We'll also scan the proposed deployment for issues and suggest changes that will make sure that what you're proposing to deploy is successful.
It's common to hit a "cannot overwrite active logic" error when deploying committed agents, so Gearset will offer to convert your chosen agent to draft and then automatically re commit it in the target.
Gearset also checks your Agent Script for a default_agent_user field. Service agents need a user assigned in the target org, and without one Gearset can't activate or commit the agent for you, so a Problem Analyzer flags the field before you deploy.
What the Problem Analyzer offers depends on whether the agent already exists in the target org:
The agent already exists in the target org: Gearset reads the user assigned to it there and offers to replace the
default_agent_userin your Agent Script with that user at deploy time. Gearset offers this fix rather than applying it, so select it if you want the deployment to use the target org's user.The agent is new to the target org: there's no assigned user for Gearset to read, so Gearset warns you instead of offering a fix. Deploy the agent, then commit it in the target org manually for the first run. Later deployments of the same agent can then offer the swap.
After accepting the suggestions, click Pre-deployment summary. On the pre-deployment summary screen you can add deployment notes and confirm that you would like us to automatically re commit and activate your agent (it's recommended you toggle these to on).
You can validate and deploy your changes immediately, or validate them and schedule the deployment for later.
If you're using a Gearset pipeline:
In your Gearset pipeline page, select your source environment. Create a new feature branch (including a link to a ticket if you're using a ticketing system). Once you've named your branch, select the option named Data kits & agents, and click Build now.
After selecting this, you'll see a screen where you can see a list of Data kits (for the deployment of Data 360) and a list of your agents.
Select your agent that you want to deploy, and click next. You don't have to worry about selecting metadata, or a particular type of agent - knowing the name of the agent that you want to deploy is all you need.
Gearset will build a comparison between your source and target, using the latest version of the agent, and automatically find and select your dependencies.
If you decide that you want to deploy an earlier version of your agent simply select it from this drop down menu, Gearset will dynamically recalculate the dependencies.
After Gearset has found all of the components for deployment, you can review the changes in the comparison and click Next.
If there are environment specific values that need to be taken care of at this stage, then Gearset will automatically apply those changes. Environment variables will also be triggered as the change is deployed throughout the pipeline.
We'll also scan the proposed deployment for issues and suggest changes that will make sure that what you're proposing to deploy is successful. It's common to hit a "cannot overwrite active logic" error when deploying committed agents, so Gearset will offer to convert your chosen agent to draft and then automatically re commit it in the target.
After accepting the suggestions, click Pre-deployment summary. On the pre-deployment summary screen you can add a commit message.
Click Commit changes, and your branch (complete with agent) is now ready for you start deploying the agent through the pipeline.
To start that process, open a pull request to the first environment in your pipeline.
You want to make sure that the agent is uniformly recommitted, and activated as it moves through the pipeline, which Gearset can automate for you. Use post-deployment steps when you create your pull request, so that Gearset knows to do this for you.
Now that the pull request has been created, you can go through the normal process for your team to review the change, and then promote it to your target environment.
The pull request, complete with post deployment steps will automatically open against the next environment in the pipeline so the change validates for you while you're testing in the first org.
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: