You are here:
Planning and Designing for Agent Script
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.
Jump to...
- Get to Know Your Current Agent
- Identify Candidates for Redesign and Plan Improvements
- Explore Examples and Resources
- Balance Determinism with LLM Reasoning
Get to Know Your Current Agent
Analyze how and why your agent works the way that it does, so you can retain what works well today and plan for improvements in the new builder. Doing some or all of this upfront work helps you create a single view of your agent, so you can identify specific candidates for redesign.
- Establish a test baseline.
- Complete a dedicated run of manual tests in Agentforce Builder and batch
tests in Agentforce Testing Center to measure your agent’s current success
rate and objectively define what a “better” agent looks like for your
business. If you already have test scenarios that you run regularly, those
are the right place to start. See Tips for Testing to learn more.
Outcome Getting dedicated pre-migration baseline testing data helps you identify areas for improvement for your agent. It also sets you up to objectively measure post-migration performance, including regressions and success. - Develop a high-level understanding of your agent in the legacy builder.
- Identify subagents and their relationships, user journey paths, agent
decision points, and handoff criteria (escalation, expected transitions
between subagents).
Outcome These architectural details are important for mapping what you’re migrating and what you’re changing. They also point to places where determinism is likely to be helpful. For example, Agent Script gives you more control over agent routing, so it’s important to understand the relationship between subagents and expected transitions. Decision points and handoff criteria are also candidates for determinism, if the agent doesn’t reliably perform as expected. - Within each subagent, identify the purpose of each instruction and evaluate its quality.
- Is the instruction general (for example, provides guidelines for tone or
context) or functional (for example, specifies how to format an output)?
Does the instruction specify any required conditions or a sequence of steps?
Is terminology consistent across instructions?
Outcome After you understand your existing instructions, plan how you want to handle each in your migration: migrate with no changes, delete, or rewrite with Agent Script. Instructions that specify required conditions, sequences, or business rules are strong candidates for deterministic rewrites. - Collect and categorize current issues.
-
Cluster agent issues to develop a clear picture of what works and what’s broken. Gather all of the feedback on your existing agent in one place, including failed test results, logged bugs, and feedback from users or support teams. Then consolidate it into a single view. (As with many steps in this guide, you can use AI to help.)
From there, group the issues by type. Common categories can include intent recognition problems, routing failures, and data validation errors, but your agent's issues can point to other patterns. As you sort, look for overlap. For example, a cluster of routing failures might share a root cause, which means one change addresses several symptoms at once.
Outcome Having a single view of your agent’s issues sets you up to distinguish between regressions (things that worked before migrating and are broken after) versus design or functionality gaps (things that have never quite worked).
Longstanding bugs or gaps are an opportunity for redesign with Agent Script. Prioritize issues by cluster to determine the most important things to fix and what tools or deterministic elements to introduce.
Identify Candidates for Redesign and Plan Improvements
With a clear picture of your agent's architecture, instructions, and issues, you're ready to identify what to migrate as-is and what to redesign. Use what you’ve learned to prioritize the parts of your agent most likely to benefit from Agent Script, which gives you explicit control over the parts of your agent that natural language instructions alone can't reliably handle.
Here are some examples of candidates for redesign with Agent Script.
- Any subagent, instruction, or process with a high error rate
- A subagent that performs inconsistently due to many instructions and actions
- One or more subagents with different instructions or routing for different users
- Complex, multi-step processes, within a subagent or across several subagents
- Any business processes that must be followed and where variability is unacceptable
- Subagents and actions that require user verification (The general principles of gating subagents and actions with filters and variables haven’t changed, but the recommended patterns have. See Agent Script Pattern: Enforce Required Workflows for a Subagent.)
Agent Script provides a range of tools for improving agent reliability. Here are some common issues that it can help you solve.
| Issue | How Agent Script Can Help | Related Patterns |
|---|---|---|
| Your agent gets confused or loses track of information across turns or transitions. | Information gathered early in a conversation can get lost as the conversation shifts subjects when information is stored in context memory alone. Variables let you store and share state across your entire agent, enabling conditional logic, personalized responses, and deterministic workflows that depend on what happened earlier. Agent Script gives you flexible options for filling them, including slot-fill with the LLM, storing action outputs, or setting values directly. | |
| Your agent takes actions in the wrong order, or skips steps. | Sometimes an agent makes a different decision than the one your workflow requires. Agent Script lets you run actions deterministically, so execution is guaranteed. You can also chain actions in sequence—passing outputs from one directly as inputs to the next—either before reasoning begins, or automatically after the LLM selects an action. | |
| In a subagent with lots of instructions or lots of actions, your agent doesn’t follow your instructions consistently. | Too many choices lead to agent mistakes, especially in long conversations. Agent Script lets you scope what the LLM sees based on your user's current state, using variables and conditional logic to send only the instructions that apply, and filters to hide actions entirely when conditions aren't met. For example, the LLM sees different instructions for a customer with insurance than a customer who self-pays, or different actions for verified and unverified customers. The result is a smaller, more focused prompt at each step, and more reliable reasoning. | |
| Your agent doesn’t reliably choose or hand off to the right subagent at the right time. | Without explicit routing logic, the LLM decides where and when to send users. Agent Script lets you define transitions between subagents, deterministically when the path is fixed or in reasoning when conditions vary. You also have more control over routing with the Agent Router, which is a specialized subagent where you can define routing rules. For mandatory workflows like user verification, conditional transitions in Agent Router instructions guarantee those steps run before the conversation continues. |
Explore Examples and Resources
One of the best ways to learn how to build effective agents with Agent Script is to start from high-quality existing patterns and examples. Here are some Salesforce-validated examples that you can use for inspiration, or even copy and paste into your own agent.
- Agentforce Developer Guide: Common
Patterns
Common patterns for building agents with Agent Script. Each pattern focuses on a specific technique you can use to make your agents more reliable and effective.
- Agentforce Labs: Start Building
Get started in a sandbox environment with the complete Agent Script for a basic customer support, FAQ, or ecommerce agent. Then build in Agentforce Builder or your IDE of choice.
- Agent Script Recipes
A collection of standalone, working examples that teach specific Agent Script concepts.
Balance Determinism with LLM Reasoning
Agent Script gives you control over potentially every decision point in your agent. You define decisions, states, and processes that must be deterministic, and then you let the agent reason through the rest. This level of control is powerful, but it can also get in the way. When redesigning to improve agent behavior, the goal is to apply just enough control to keep your agent safe, predictable, and precise without eliminating the conversational flexibility that makes LLM reasoning so useful.
It's tempting to add deterministic controls everywhere, especially if your legacy builder agent struggled with reliability. But remember, every logical expression is a decision the model can’t make. Don't add determinism reflexively just because you can, or you risk recreating a rigid chatbot. Instead, identify decisions with business consequences, such as user authentication, financial transactions, or routing to sensitive queues. Control those with conditionals, filters, and variable mapping to action inputs and outputs. For everything else, let the LLM reason. Start open and add control where testing shows that you need it.
Here are some general guidelines.
- Use natural language instructions and LLM reasoning for conversational
understanding, context, and flexible decision-making.
When writing natural language instructions, keep these best practices in mind.
- Agents tend to perform best when natural language instructions are simpler and shorter.
- Avoid overlapping or conflicting instructions, which can degrade agent performance.
- LLMs are sensitive to language choice, so create plain language instructions that are precise, detailed, and direct. Use absolutes only when you mean it. Avoid jargon where possible. Use language consistently throughout all of your instructions.
Tip If you’re migrating natural language instructions from your existing agent, don’t be afraid to trim them down aggressively. Instructions in the legacy builder tend to be long and repetitive, covering behavior and edge cases you can now handle with a conditional or filter. Most of the time, you can safely delete everything except one or two core sentences. Lengthy natural language instructions can dilute what’s actually relevant and make it harder for your agent to understand what matters. - Use deterministic logic for actions with business consequences, such as data
checks, required sequences, business routing rules, compliance requirements,
and transactional operations.
For example, before any natural language prompt-based instructions run, use conditional logic to determine whether to thank a user for being a gold tier member, use a variable to customize the prompt, or deterministically run an action to look up information or send an email. Then you can focus the natural language instructions on what an AI model does best, without overloading the model’s context.
- For the highest level of reliability, move any logic with legal, safety, or
regulatory consequences to an agent action (for example, age
verification).
Build the logic into the action’s underlying Apex class or flow, and then give your agent detailed instructions about how and when to use the action.
Here are are some resources to help you balance determinism and reasoning in your agent design.
- Salesforce Help:
An Agentforce Guide to Context Engineering
This resource discusses the steps to build reliable and effective Agentforce solutions by using some context engineering best practices, to ensure you’re giving your AI agent the right information, tools, and instructions to achieve its goals.
- The 360 Blog: Agent Script: The
Control Plane for Agentic Decisions
A blog post, written by some of our resident Agent Script experts, that highlights the advantages of managing determinism and reasoning in a single interface and file. In addition to advice about the tools available in Agent Script and how to use them, it provides three versions of a simple agent that demonstrate three different levels of control–fully scripted (a workflow with an LLM on top), mixed (deterministic identity verification, but reasoning-driven resolution), and fully agentic (minimal determinism).
- Six Levels of Determinism in
Agentforce
A detailed framework for agent design, which helps you gradually move from lower to higher levels of control as needed. It defines six levels of agentic control and provides best practices for gaining and keeping control over agentic behavior for each of these levels.
