Example: More Reliable Agent Instructions with Agent Script

Instructions Before Agent Script

These are the legacy builder instructions for a subagent that handles refund requests. Orders are eligible for a refund if the customer has a valid order ID or if the customer is a VIP customer. If an order is eligible for a return, the agent creates a refund request. If an order isn't eligible for a return, the agent offers to create a case for a rep to follow up with the customer.

This is a relatively simple example. (And as you probably know, the workflows you require for handling your business cases can be significantly more complex.) But it relies on the LLM to get a lot of things right.

• Your agent must understand your business context in order to make correct decisions. For example, what makes an order eligible for a refund? In the legacy builder, you can either use plain language to define it, which can add up to a lot of tokens and time spent refining your prompt to get your agent to understand. Or you can instruct your agent to run an action to determine whether an order is eligible, which your agent decides whether to do during its reasoning process.
• Your agent must understand the sequence of instructions that you want it to follow (validate the order number AND THEN validate whether the customer is a VIP AND THEN collect the right info AND THEN create a request). And the agent must follow the instructions correctly every time. In the legacy builder, your best bet is to include a complete sequence of instructions in a single instruction field and use clear order terms (such as "First, do X... Second, do Y... Finally, do Z…"). However, LLMs are best at predicting the next most likely step rather than a sequence of steps. And the more complex a natural language instruction, the more likely your agent will get confused.
• Your agent must understand which states and conditions, and therefore which instructions, apply. In the legacy builder, you have to use plain language to describe the logic and values that represent possible user states, which can result in large prompts and greater latency. No matter which states and conditions are true, the entire prompt is sent to the LLM at every turn, which means the LLM must sift through irrelevant information, correctly identify relevant information, and then adhere to only the relevant instructions. That's a lot like handing someone a long instruction manual without a table of contents. They're likely to forget things, skip steps, and lose their place, especially if they're interrupted.

Instructions After Agent Script

In the new builder, the graph-based Atlas reasoning engine and Agent Script give you more tools to control your agent's behavior and fine-tune your prompt, ensuring the agent adheres to your required business processes. The following is an example of instructions for a similar subagent, written in Agent Script.

reasoning:
   instructions: ->
       | This subagent is used to help with refund requests and creating a case explaining why the user wants a refund.

       if @variables.orderValidated == None
	 run @actions.Validate_Order
	  with Customer_ID=@variables.verifiedCustomerId
	  with Order_ID=@variables.orderId
	  set @variable.orderValidated=@outputs.Order_Validated

       if @variables.loyaltyTierLevel == None
	 run @actions.Get_Loyalty_Tier
	  with Customer_ID=@variables.verifiedCustomerId
	  set @variable.loyaltyTierLevel=@outputs.Loyalty_Tier

       if @variables.orderValidated == True
           | Help the customer create a refund request. Ask the customer to explain why they want a refund and pass the details into {!@actions.Create_Refund_Request}.

       if @variables.orderValidated == False and @variables.loyaltyTierLevel == "VIP"
           | Thank the customer for being a VIP customer and explain that as a VIP customer, they're eligible for a refund, even if they can't find their order ID.
Ask the customer to explain why they want a refund and pass the details into {!@actions.Create_Refund_Request}.

       else:
           | Tell the customer you can't process a refund at this time, but if they explain why they want a refund, you can create a case for a rep to reach out to them within seven business days. To create a case, ask them to explain why they
want a refund and use {!@actions.Create_New_Case}.

Here are some key ways that these instructions combine reasoning and determinism to make the agent more reliable.

The agent runs actions deterministically to fetch information about the customer and their current state.

How it works: For agents written in Agent Script, before any reasoning with an LLM takes place, the agent resolves the subagent's reasoning instructions from top to bottom, executing any logical expressions along the way in the order they're written. See How Subagent Instructions are Resolved to Build a Prompt. In this case, the reasoning instructions start with two actions (Validate Order and Get Loyalty Tier), so the agent has access to key customer information before constructing the prompt it uses for reasoning. (Plus, because they're nested in conditionals, the agent runs the actions only if the data hasn't already been fetched.) These actions are run before any reasoning takes place, so the outputs can be used to hydrate and fine-tune the prompt.

Benefits:

• Gives the agent access to accurate and reliable information, every time.
• Reduces the complexity of agent instructions by moving prerequisite steps ("first, fetch the data") out of reasoning. Instead of spending time and tokens thinking about what to do, the agent just does it. So, you can save the thinking for where it's most helpful.

The most important information about the customer and state is stored in variables, instead of relying on the agent context memory.

How it works: While agents often do a good job filling inputs and outputs through slot-filling, some information is too important to leave to chance, especially if you want to reuse it across subagents or conversational turns. In this case, the outputs of the Validate Order and Get Loyalty Tier actions are stored in variables, so they can be used in conditional statements.

Benefits:

• Improves agent accuracy by giving the agent values and data that are stable across subagents, actions, and conversational turns.
• Unlike information retrieved from the agent's context memory, values and data stored in variables can be used downstream in deterministic workflows, such as inputs to other agent actions, conditionals, or filters.

Instead of sending the same, large prompt to the LLM for every case or state, conditional statements and variables limit and refine the instructions and options sent to the LLM in agent reasoning.

How it works: Agents reason best when you give them focused and direct natural language instructions. Before reasoning begins, Agentforce evaluates each conditional statement deterministically, based on the values of the variables. Then when the agent constructs the prompt for reasoning, only the applicable instructions are included.

Current Context	Instructions Sent to the LLM
The order is validated @variables.orderValidated == True	Help the customer create a refund request. Ask the customer to explain why they want a refund and pass the details into {!@actions.Create_Refund_Request}.
The order isn't validated, but the customer is a VIP customer @variables.orderValidated == False AND @variables.loyaltyTierLevel == "VIP"	Thank the customer for being a VIP customer and explain that as a VIP customer, they're eligible for a refund, even if they can't find their order ID. Ask the customer to explain why they want a refund and pass the details into {!@actions.Create_Refund_Request}.
All other cases else	Tell the customer you can't process a refund at this time, but if they explain why they want a refund, you can create a case for a rep to reach out to them within seven business days. To create a case, ask them to explain why they want a refund and use {!@actions.Create_New_Case}.

Note This example looks only at subagent reasoning instructions, but you can use the same variables and principles to apply filters to agent actions and ensure that your agent sees only the actions that are relevant for the customer's current state and phase of steps in a larger process.

Benefits:

• Improves instruction adherence and reduces latency by fine-tuning the instructions before reasoning begins. The LLM doesn't have to sift through relevant and irrelevant instructions–it gets the right instructions from the start.
• Improves overall accuracy and response quality by reducing the instructions and options available for the LLM. The fewer choices that an agent has to make, the more likely it will make the right ones.