--- schema_version: "1" id: 0629e5b735db586ae4c233c18236d4bea9c021b993fa4bb849245261e0df9d7b title: Preparing to Migrate collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/agent_migrate_prepare.md canonical_url: https://help.salesforce.com/s/articleView?id=ai.agent_migrate_prepare.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 6fecddb2e50b9a0222d6bf12b0e88fc6a685da4ddec9e17672bc8cd087c2162c description: 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. products: - Agentforce - Cross Cloud release: "264" --- # Preparing to Migrate 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. Jump to... - [Get to Know the New Builder and Agent Script](https://help.salesforce.com/s/articleView?id=ai.agent_migrate_prepare.htm&release=264.0.0&type=5) - [Explore and Select Migration Tools](https://help.salesforce.com/s/articleView?id=ai.agent_migrate_prepare.htm&release=264.0.0&type=5) ## Get to Know the New Builder and Agent Script The new Agentforce Builder is designed for building enterprise-ready agents, with the reliability that your business demands and the flexibility that LLMs make possible. | Key Point | New Builder | Old Builder | | --- | --- | --- | | Take advantage of Agentforce improvements and innovations. | New Agentforce features, including Agentforce Voice enhancements, are planned for the new builder only. | No new features or enhancements are planned. New agent creation is available in the new builder only. | | Build more reliable, more powerful, more accurate, and faster agents with [hybrid reasoning](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."). | With the upgraded Atlas reasoning engine and Agent Script, you can combine deterministic logic with natural language, so you can more reliably map business processes onto your agent. | Limited to reasoning with natural language prompts, with limited guardrails. | | [Get richer testing and debugging.](https://help.salesforce.com/s/articleView?id=ai.agent_preview_and_test.htm&release=264.0.0&type=5 "Manual testing, like you do in Agentforce Builder, is the starting point for validating your agent’s performance. It offers a detailed, step-by-step evaluation of your agent's interactions and utterances and is especially effective for confirming configurations and exploring how the agent responds to different inputs. Throughout the agent lifecycle, plan to revisit manual testing in Agentforce Builder, especially after making changes to your agent.") | In agent previews, see a summary of your agent's reasoning for each message. Dig into detailed tracing and debugging to help you make informed, precise fixes. | Supports previews of agent conversations, but with limited diagnostics on the plan canvas only. | | Build the way you want, including AI-first with Agent Optimizer or third-party tools. | Chat with [Agent Optimizer](https://help.salesforce.com/s/articleView?id=ai.agent_optimize_dev.htm&release=264.0.0&type=5 "Focus on what you want your agent to do, not how to configure or fix it. Agent Optimizer is a built-in coding agent that extends, refines, and troubleshoots your agents directly in Agentforce Builder, at no additional cost. Explore use cases and considerations for working with Optimizer.") to build, test, and troubleshoot at any experience level. Build with natural language and convenient shortcuts [in Canvas view](https://help.salesforce.com/s/articleView?id=ai.agent_canvas.htm&release=264.0.0&type=5 "Get to know the features of Agentforce Builder’s Canvas view that help you build powerful and reliable agents with Agent Script.") or write directly [in Script view](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-script.html) with developer-friendly aids. Editable in VS Code and CLI, and compatible with third-party AI coding tools. | Limited to a UI experience. No built-in AI assistance. | | Spend less effort toggling between tabs and views. | [Embedded in Agentforce Studio](https://help.salesforce.com/s/articleView?id=ai.agent_builder_studio.htm&release=264.0.0&type=5 "The Agentforce Studio app is the home of the new Agentforce Builder and a central hub for building, testing, and monitoring your agents. By default, Agentforce Studio is available in the App Launcher to all users in orgs with access to Agentforce. Each feature within Agentforce Studio requires its own permissions."), a central hub for building, testing, and monitoring your agents. You can empower users across your business to build agents without granting admin-level permissions. | Managed in Salesforce Setup, across many tabs. Access requires admin-level permissions. | Agent Script is the language for building agents in the new Agentforce Builder. It combines the flexibility of natural language instructions for conversational tasks with the reliability of programmatic expressions for business rules. Use Agent Script to manage instruction overload, reduce latency, and improve overall agent accuracy, instruction adherence, and response quality. In the legacy builder, instructions were written only in natural language, resulting in large, complicated prompts that exceeded LLM context windows. These instructions were often misinterpreted or applied inconsistently, so agents didn’t always behave the way that you wanted them to. Agent Script gives you more tools to control agent behavior. You define decisions, states, and processes that must be deterministic, and then the agent reasons through the rest. So you can build predictable, context-aware agent workflows that don’t rely solely on interpretation by an LLM, all in one file, without switching tools. ![Tip](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/images/icon_tip.png) Tip Check out these examples to see what makes Agent Script so powerful. - [_Salesforce Help_: Example: More Reliable Instructions with Agent Script](https://help.salesforce.com/s/articleView?id=ai.agent_example_script_before_after.htm&release=264.0.0&type=5 "Agent Script in the new Agentforce Builder makes it possible to build enterprise-ready agents that get your business processes right every time. This example highlights a few ways Agent Script can help you write instructions that manage instruction overload, reduce latency, and improve overall agent accuracy, instruction adherence, and response quality.") Walk through a detailed example of agent instructions written in natural language in the legacy builder and those same instructions converted to Agent Script in the new builder. - [_The 360 Blog_: Proving the Power of Script](https://www.salesforce.com/blog/datasite-agentforce/) Learn how one customer used deterministic logic in Agent Script to achieve a 17-point jump in case deflection. The language itself is designed to be human-readable so that non-developers can get a basic understanding of how the agent works from the script itself. But you don’t have to author script directly to build an agent with Agent Script and take advantage of the control that it offers. Agentforce Builder gives you different ways to write Agent Script, depending on your goals, tools, and preferences. - You can chat with Agentforce and explain what you want your agent to be able to do (for example, "If the order total is over $100, then offer free shipping."). Agentforce converts your request into subagents, actions, instructions, and other expressions. - In Canvas view, Agent Script is summarized into easily understandable blocks, which you can expand to view the underlying script. You can edit your agent with the help of quick action shortcuts. Type / to add expressions for common patterns (for example, if/else conditionals) and @ to add resources (subagents, actions, and variables). Advanced users can switch to Script view to write and edit script directly, with developer-friendly aids like syntax highlighting, autocompletion, and validation. - Developers can also use Agentforce DX to generate or retrieve a script file into their local Salesforce DX project and then work with it in Visual Studio Code. The Agentforce DX VS Code Extension fully supports the Agent Script language with standard code editing features. This approach also works with third-party AI coding tools. Here are some resources for learning more. - [_Salesforce Help_: Build Enterprise-Ready Agents with the New Agentforce Builder](https://help.salesforce.com/s/articleView?id=ai.agent_builder_intro.htm&release=264.0.0&type=5 "Build context-aware agents with the predictability that your business demands and the flexibility that LLMs make possible.") - [_Agentforce Implementation Guide_: Customer-Facing Agents](https://sfdc.co/implement-customer-agents) (Now Updated for the New Builder and Agent Script) - [_Agentforce Developer Guide_: Get Started with Agent Script](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-script.html) ## Explore and Select Migration Tools You can upgrade your agent with Agentforce or migrate using other AI tools. Before you migrate, explore your options and decide which migration path works best for you, your agent, and for the different stages of your migration.
Migration Path Description When To Use
Upgrade with Agentforce Upgrading your agent is a UI-driven path to create a new version of an agent from the legacy builder in the new builder. 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, and you can continue to access and edit the agent in the legacy builder. Optionally, Agentforce can optimize your agent for Agent Script.
  • You prefer a UI-driven workflow.
  • You feel more comfortable writing, reviewing, and debugging Agent Script in natural language in Canvas view, with built-in validation.
  • You want your new agent to look as much like your original agent as possible, so you can more easily compare, diff, and validate.
  • You want to manage your new agent in the same project as your original agent.
Use Salesforce Development Skills

Use Salesforce development skills, available in the Agentforce Vibes (AFV) Library and in the Agentforce Development Lifecycle (ADLC) Library, to convert your agent into Agent Script. Many of these skills are optimized to work with Agentforce Vibes and other Agentforce DX tools, but you can use them with any AI coding tools.

Note
Note Salesforce development skills are general purpose skills for Agent Script development and not dedicated migration tools.
  • You prefer working in a CLI.
  • You want to work with one or more third-party AI coding tools to help you write, debug, and refine your Agent Script, and you’re comfortable reviewing it manually.
  • You’re comfortable comparing, diffing, and validating your agent even if the new agent looks substantially different from the original.
You can also combine these migration paths. For example, you can upgrade your agent with Agentforce to stand up a version of your agent in the new builder quickly, and then you can use the AFV Agentforce Development skill to iterate on it from there. Get started building with Salesforce development skills in Agentforce Labs. - Agentforce Vibes - Claude Code - Cursor - ...plus many others. ![Tip](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/images/icon_tip.png) Tip If you use a third-party AI tool to migrate, keep in mind that they don’t always get Agent Script syntax right, even with Agentforce skills loaded. Always plan to manually review AI-suggested changes before applying them. [See more tips for working with third-party AI tools.](https://help.salesforce.com/s/articleView?id=ai.agent_migrate_implement.htm&release=264.0.0&type=5) Any change in reasoning or instructions can affect agent behavior. No matter which tools you use to migrate, plan to carefully test your agent in the new builder to ensure that it performs as expected. Adjust your instructions as necessary before activating and deploying your agent.