Implementing Your Migration

Migrate Your Agent in Stages

Approach your migration in stages so that it’s easier to stabilize and troubleshoot later.

1. Migrate your agent as is.

   Start with a baseline migration of all subagents, instructions, and actions. Stand up the legacy agent design in the new builder and verify that it works end-to-end.

2. Identify and fix any regressions.

   To identify regressions, verify your agent’s Agent Script syntax and check for any errors in the builder. Then run the same manual and batch tests that you ran previously to establish your agent’s pre-migration baseline.

   • Anything that was working in the agent in the legacy builder and isn’t working in the new builder is a regression.
   • Anything else is an improvement or an enhancement.

   Fix any regressions before making other changes, so you can isolate and troubleshoot issues. If something is broken after the baseline migration, you know it’s a result of the migration and not a change you made.

   

   Tip Using Agentforce to upgrade your agent makes issues like validation errors less likely. However, any change in reasoning can affect agent performance. It’s important to test your agent end-to-end because of the differences in the data model and underlying reasoning engine between the legacy and new builders.
3. Harden and improve your agent with Agent Script.

   After your baseline agent is stable in the new builder, you can start making changes to improve your agent’s reliability and performance. At this point, you can take advantage of the capabilities that Agent Script has to offer to fix things that never quite worked in the legacy builder and strategically introduce determinism to add predictability and consistency.

4. Expand your agent.

   At some point in your agent migration, you may hear the siren song of your agent wishlist and think about expanding your agent’s capabilities to new subagents, use cases, or integrations. Resist the urge to expand too soon. Focus on your agent migration before introducing new functionality. Doing too much at once, especially before your agent is stable in the new builder, risks muddying your agent’s architecture and making issues harder to track, isolate, and troubleshoot.

Make Changes in Small Batches, and Test After Each Batch

Whether you’re fixing regressions or hardening your agent with Agent Script, avoid making lots of changes in one go. This can make it harder to isolate and test any issues your changes may create (for example, a compile error), especially if you’re using third-party AI coding tools. Approach your changes iteratively to measure improvements, document results, and minimize regressions.

• Make structural and architectural changes first, then fit-and-finish changes after.
• Test after each change and track your metrics against your baseline.
• Commit your agent and create new versions after significant changes, not tiny fixes. Learn more about the agent versioning and editing lifecycle in the new builder.

Tips for Testing

Testing is critical for establishing a baseline, objectively measuring outcomes and improvements, and minimizing regressions. When you migrate, there are changes to your agent’s reasoning and instructions, which can affect agent behavior. No matter which migration tool or tools you use, plan to carefully test, adjust, and test again to make sure that your agent performs as expected.

• Test at the beginning of each stage of your agent migration, and again after each batch of changes. Plan to test early and often, including:
  • Before you migrate, to establish an initial baseline and identify issues.
  • After your initial migration, to establish a baseline in the new builder and identify regressions.
  • After every major change or batch of small changes
• Create a testing plan that includes manual testing in Agentforce Builder and batch testing in Agentforce Testing Center. Run the same plan to track against your baseline. At minimum, a good testing plan covers:
  • Core agent functionality, such as case creation, appointment booking, order tracking, or FAQ with the Answer Questions with Knowledge action.
  • Personas based on real user behavior, such as authenticated users, unauthenticated users, impatient or unhappy users, users who engage in lots of small talk.
  • A range of simple and more complex scenarios, including multi-turn conversations, multi-subagent use cases, and edge cases.
• If you've implemented customer verification, including any filtering based on the verifiedCustomerId or isVerified variables, explicitly test your agent's behavior as an unverified end user and as a verified end user. In the new builder, preview your agent in live test mode. To simulate verified and unverified users, in the Variables tab, override the values of any variables you use to store the results of customer verification or verified customer IDs.
• Explicitly test for abrupt changes in the agent conversation. Users can shift from requests to small talk, make new requests before their current request is complete, or otherwise change the topic of conversation. Although agents are adaptable, issues with topic switching can be easy to miss if you’re not looking for them. To effectively test, change the subject three or four times in a preview conversation to verify reliable agent behavior.
• Testing capabilities differ between the legacy builder and the new builder, for both manual testing and batch testing. Get to know the testing tools available for each. Plan to test the same functionality, personas, and scenarios across the legacy and new tools so that you can compare metrics as accurately as possible.

Tips for Working with Third-Party AI Tools

Agents are metadata and Agent Script is highly portable, so you have the flexibility to use low-code, pro-code, and third-party tools for migrating and enhancing your agent. Use a combination of whatever tools work best for you, but keep these tips for working with third-party tools in mind.

• Third-party AI coding tools don’t always get Agent Script syntax right, even with Agentforce skills loaded. Download the official Agent Script documentation and share it with your coding agent. Always manually review AI-generated changes before accepting them and refactor changes into valid Agent Script syntax, if necessary. When in doubt, refer to Agent Script documentation in the Agentforce Developer Guide, and use AI for a second opinion.
• Get the most from Claude, Cursor, and other AI tools by defining clear constraints and goals. Clarity about success criteria helps these tools provide actionable results. For example, general requests like “improve my agent” aren’t likely to get you effective results on their own. You’re more likely to get a better result if you make a more specific request (for example, “make sure the agent always checks order eligibility before it tries to process a return”). And sharing this migration guide as context can help the AI tools understand your requirements and suggest effective approaches.
• There’s more than one way to work with AI tools, and you don’t have to optimize your entire agent at once. If you’re not getting the results you want, or you find it difficult to understand broad changes to your agent’s design and behavior, treat the AI tools more like strategic partners and collaborators than independent contractors. You can use them iteratively to diagnose specific, discrete issues, validate approaches, and implement solutions. Here are some examples of effective, bite-sized workflows.
  • When you use an AI coding tool with pre-loaded skills to make a change, review the change in plan mode. Ask it to explain why it made specific changes to challenge and validate design decisions and determine the best path forward. Then execute the change in agent mode.
  • Review an instruction manually and note recommended changes. In ask mode, ask for an AI perspective on your changes–does AI agree, what would it do differently, and why? Use this process to decide which changes to keep. Then execute the changes in agent mode in small batches.

Tips for Working in Teams

Currently, we don’t recommend collaborating on the same agent in the builder at the same time. But there are ways to work together effectively on your agent migration.

• In addition to AI review of any changes, consider peer review as a quality check before committing agent changes.
• Limit multi-player collaboration to simple, self-contained issues and fixes.
• Each builder should work in their own copy of the agent. Then manually diff and merge the copies. Like many other steps in this guide, you can use AI can help with this.