Migrating to the New Agentforce Builder: What to Know Before You Upgrade
Salesforce Agentforce is continuing to evolve, and the next big step for teams using agents is the move from the Legacy Agentforce Builder to the new Agentforce Builder. As Salesforce shifts its focus towards the new builder experience, organizations with existing agents should begin implementing their migration now rather than waiting until the legacy experience is fully phased out, which is set to be in February of 2027.
The good news is that teams do not have to rebuild every agent from scratch. Salesforce provides an “upgrade to new builder” feature that can move an existing legacy agent into the new Agentforce Builder. However, as with most platform migrations, the upgrade is not always a perfect one-click process. Some pieces may need to be reviewed, reconnected, or corrected before the migrated agent is ready.
Why the New Agentforce Builder Matters
The new Agentforce Builder is Salesforce’s next-generation experience for creating and managing AI agents. It is designed to give teams more control with the new script feature, and a more modern way to build agent behavior across subagents, actions, instructions, and connected data sources. For organizations already using Agentforce, this move is less about adopting a completely new tool and more about preparing existing agents for Salesforce’s future direction.
One of the most helpful parts of the migration process is that Salesforce allows users to upgrade an existing legacy agent into the new builder. This means teams can preserve much of the work they have already done, including the agent’s structure, instructions, subagents, and actions.
That said, the upgrade feature should be treated as a starting point, not the final step. After the agent is moved into the new builder, teams should carefully compare the migrated version against the legacy version. The goal is to confirm that the agent still has the right instructions, actions, knowledge sources, and routing logic before it is activated.
Prompt Template and Apex Actions May Need Manual Review
One area that requires close attention is action configuration, especially for Prompt Template actions and Apex actions. During migration, the action instructions may carry over, but the source reference may not transfer directly. In some cases, the prompt template action may keep the written instructions but fail to bring over the actual prompt template source.
To resolve this, users may need to return to the legacy builder and copy the correct developer name for the prompt template or Apex action. The developer name is easily integrated into the new builder through script view. This step is important because the new builder may show the action as present, but the underlying source may not be properly connected. Without that connection, users might not be able to commit or activate the agent at all.
Watch for Extra Input and Output Configurations
The new Agentforce Builder includes input and output configuration options that may not exist in the same way in the legacy builder. During migration, these additional configurations can sometimes appear in ways that create errors or prevent the agent from being committed successfully.
If errors appear after upgrading, teams should review each action’s input and output configuration carefully. Any extra configurations that were added during migration but are not necessary to the use case should be removed. This can help clear validation errors and ensure the action behaves like it did in the legacy builder.
Reattach Data Libraries After Migration
Another important migration step is reconnecting the attached data library. If an agent action relies on a data library, that connection may not remain attached after the transfer into the new builder.
This is a critical item to check because data libraries are what allow an agent to provide grounded, trusted responses instead of relying only on general instructions. After upgrading, users should confirm that the correct data library is attached to the appropriate subagent action.
They should also test questions that depend on that library to make sure the agent is retrieving and using the right information.
A Practical Migration Checklist
Before considering the migration complete, teams should confirm the following:
The agent has been upgraded into the new Agentforce Builder successfully
Prompt Template actions are connected to the correct prompt template source
Subagent actions reference the correct developer name from the legacy builder
Action instructions transferred as expected
Unnecessary input and output configurations have been removed
The connected data library has been reattached in the new builder
Key user scenarios have been tested against the legacy agent’s behavior
Key Takeaways
Migrating from the Legacy Agentforce Builder to the new Agentforce Builder is an important step for organizations using Salesforce Agentforce. While the upgrade feature helps teams avoid rebuilding agents from the ground up, it does not eliminate the need for careful review and testing. Prompt Template actions, Apex actions, input and output configurations, and data library connections should all be checked before the migrated agent is considered ready.
For teams planning their migration, the best approach is to start early, test thoroughly, and treat the upgrade as a structured project rather than a quick administrative task. By taking the time to validate each part of the agent, organizations can move confidently into the new builder while preserving the business value their existing agents already provide.
