Salesforce Docs Portal

Upgrade an Agent from the Legacy Builder to the New Builder

Create a new version of an agent from the legacy Agentforce Builder in Setup in the new Agentforce Builder in Agentforce Studio, with just a few clicks. The new version contains all of the original agent's subagents, actions, system messages and settings, data, and connections, converted to Agent Script. Upgrading an agent doesn't affect the original agent in the legacy builder. You can continue to access and edit the agent in the legacy builder.

Required Editions

Available in: Lightning Experience
Available in: Enterprise, Performance, Unlimited, and Developer Editions. Required add-on licenses vary by agent type.
User Permissions Needed
To upgrade an agent: Manage AI Agents AND the required permissions for your agent type
  1. From Setup, in the Quick Find box, enter Agentforce Agents, and then select Agentforce Agents.
  2. From the dropdown menu next to your agent in the list view, select Upgrade to New Builder.
  3. Select the version of the agent you want to upgrade, and then click Upgrade.
    A draft version of your agent is created in the new Agentforce Builder.
  4. To open your agent in the new builder, click Let's Go. Otherwise, you can continue to your agent in the legacy builder or exit.
  5. Optionally, optimize your agent's instructions for Agent Script.
    1. If you clicked Let's Go and opened your agent in Canvas view in the new builder, you'll see a banner notification to optmize your agent. From the banner, click Optimize, and then expand the Agent Optimizer panel, if it's not already open.
    2. Otherwise, from the Agents page of the Agentforce Studio app, open your agent in the new builder. In the Agent Optimizer panel, enter "Optimize my agent's script to clean up, improve quality, and follow Agent Script best practices."
    Optimizer reviews your natural language instructions to suggest improvements and add deterministic controls to improve your agent's reliability and performance. Accept or reject Optimizer's suggestions, and then save your changes.

Any change in reasoning or instructions can affect agent behavior. After upgrading, carefully test your agent in the new builder to ensure it performs as expected. Adjust your instructions as necessary. Then when you're ready, commit and activate your agent.

Because the upgraded agent is a version of the original agent, keep these considerations in mind.

  • The upgraded version of your agent inherits the name of the agent you created it from and is appended with the next sequential number (for example, if you upgrade My Agent - 3 in the legacy builder, your new version in the new builder is named My Agent - 4). Each subsequent version you create follows the same pattern, whether you create it in the new or legacy builder.
  • When you open an agent version, it opens in the compatible builder. This is true whether you open a version from the Agents list in Agentforce Studio, the list view in the Agentforce Agents Setup page, or from the version dropdown within either builder. If you open the top-level agent from the Agents list in Agentforce Studio or the list view in the Agentforce Agents Setup page, the most recent version of the agent opens in the compatible builder.
  • You can only have one active version of an agent at a time. If you upgrade a version of an agent that's active in the legacy builder, the agent remains active and ongoing agent conversations aren't interrupted. However, if you activate any other version of the agent, including the upgraded version in the new builder, the originally active version is deactivated.
  • Deleting a version of an agent doesn't affect any other version of the agent. Deleting an entire agent deletes all versions of the agent, no matter which builder they were created in.
  • The following fields apply across all agent versions. If you make changes to these fields, the changes apply across all versions of the agent in the legacy builder and the new builder.
    • Agent Label or Agent Name (agent_label)
    • API Name or Developer Name (developer_name)
  • Troubleshoot Agent Upgrade Errors
    When you upgrade an existing agent, Agentforce does most of the work for you. But metadata and syntax differences between the new and legacy Agentforce Builders can still cause validation errors when you save or commit your upgraded agent. Learn more about common issues and how to solve them.

See Also