--- schema_version: "1" id: 099d2e6e618344af00e852ff3347455c2047d80d6ccb4d50ad48a8350b9405b6 title: Decide Whether to Migrate and When collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/agent_migrate_decide.md canonical_url: https://help.salesforce.com/s/articleView?id=ai.agent_migrate_decide.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: d77e4d95c4b9a0cf3583414beb93401a56e6dba3626633a852f13a99b966e290 description: The question isn’t whether to move to the new Agentforce Builder. It’s when to get started and what to bring with you. products: - Agentforce - Cross Cloud release: "264" --- # Decide Whether to Migrate and When The question isn’t whether to move to the new Agentforce Builder. It’s when to get started and what to bring with you. The new Agentforce Builder in Agentforce Studio is the future of Agentforce, designed to empower you to build more powerful, more predictable, and more portable agents. It gives you more control over agents and guardrails, and it’s the home of all future Agentforce innovations and improvements. [New agent creation moves to the new builder only starting the week of July 13, 2026.](https://help.salesforce.com/s/articleView?id=release-notes.rn_agentforce_legacy_agent_creation.htm&release=262&type=5&language=en_US) In short, **if you're building or running Agentforce agents today, the new builder is for you.** Getting started with the new builder doesn’t necessarily mean migrating your existing agents. Whether to migrate an agent depends on your investment in your existing agents and your business goals. - **If you haven’t started building yet:** Get started in the new builder. You don’t have an agent to migrate, but the content in [Preparing to Migrate](https://help.salesforce.com/s/articleView?id=ai.agent_migrate_prepare.htm&release=264.0.0&type=5 "Before you begin, familiarize yourself with the new Agentforce Builder and Agent Script, learn how the upgraded reasoning engine works, and explore migration tools to choose the approach that works best for you.") and [Planning and Designing for Agent Script](https://help.salesforce.com/s/articleView?id=ai.agent_migrate_plan_design.htm&release=264.0.0&type=5 "Before migrating, spend time designing your subagent instructions and conversational flow. The level of time and effort varies depending on what tools you plan to use to migrate, the complexity of your agent, and how well your agent performs today. This prep helps you determine what parts of your agent can be migrated directly with no changes and what parts are candidates for redesign. It also prepares you to make deliberate decisions about where to introduce determinism in your new agent, so you can improve your agent strategically instead of reactively.") may still be useful for you. - **If you’ve started building an agent in the legacy builder and you’re not yet in production:** This is a great time to make the switch. At this stage, you can choose to migrate the agent you’ve started working on to maintain your progress. Or you can redesign it from scratch when experimentation is low-risk. - **If you’re currently in production with an agent built in the legacy builder:** Migration is for you. This guide walks you through planning, implementing, and validating your migration with minimal disruption, and all of the tools available to get you there. - **If you have an agent that’s outdated or no longer in use:** Skip the upgrade. Archive or delete the agent in the legacy builder. If you need a replacement, start fresh in the new builder. If you decide to migrate your existing agent, expect your agent to change—for the better. The new Agentforce Builder is based on a fundamentally different reasoning engine than the legacy builder. Previously, the prompt-based reasoning engine sent all instructions to the LLM in a single reasoning phase. Now, the graph-based reasoning engine separates the agent's run-time behavior into roughly two phases: deterministic execution followed by reasoning. Because of this architectural change, instructions from your existing agent can perform differently when migrated as is. Some of your instructions may need to be refactored into new patterns, not just new syntax. You may find that some of your lengthiest, most repetitive instructions can be reduced to a sentence or two. And in some cases, you may find that it’s easier to take a fresh approach to instructions, designing them with the capabilities and affordances of Agent Script in mind, than to attempt to retrofit them. Agentforce and other tools, as well as strategies in this guide, can help you identify which instructions need changes and suggest improvements. Here are some resources that can help you understand the new run-time behavior of agents built in the new builder. - [_Salesforce Help_: How Agents Work](https://help.salesforce.com/s/articleView?id=ai.agent_builder_reasoning_engine.htm&release=264.0.0&type=5 "Follow the path of a user message through the Atlas reasoning engine to learn how Agentforce agents reason, take action, and generate responses.") - [_Salesforce Help_: How Subagent Instructions are Resolved to Build a Prompt](https://help.salesforce.com/s/articleView?id=ai.agent_topics_instructions_resolve.htm&release=264.0.0&type=5 "Learn about how an agent executes programmatic expressions in a subagent’s reasoning instructions to prepare for reasoning.") - [_Video_: How an Agentforce Agent Resolves Instructions to Build a Prompt](https://salesforce.vidyard.com/watch/ZmNo7jw7QJawi7SMcNefen) - [_Agentforce Developer Guide_: Agent Script Flow of Control](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-flow.html)