Agent Script Best Practices: Building Agentforce Agents That Behave Like Software

Agentforce agents are becoming more capable, but capability alone is not what makes an enterprise agent production-ready.

The harder problem is control.

An agent needs enough freedom to understand ambiguous requests, reason through context, and respond naturally. At the same time, organizations need predictable execution around authentication, permissions, business rules, transactions, routing, and sensitive operations.

That is exactly where Agent Script becomes important.

Salesforce designed Agent Script as a hybrid language that combines deterministic programmatic logic with LLM reasoning. Logic instructions execute predictably, while prompt instructions give the model room to reason.

At VurtuoLabs, we think this is the right mental model for Agent Script:

Use Agent Script to define where the agent can reason, where it cannot, and what must happen before it is allowed to move forward.

That distinction changes how you architect Agentforce.

What Is Agent Script?

Agent Script is Salesforce’s scripting language for building Agentforce agents.

It allows developers to define:

• subagents

• actions

• variables

• conditional logic

• transitions

• routing

• system behavior

• reasoning instructions

• runtime configuration

The important part is that Agent Script combines two different execution models.

Deterministic instructions handle things such as:

if customerVerified == False:
    route_to_verification

if customerVerified == False:
    route_to_verification

if customerVerified == False:
    route_to_verification

while reasoning instructions can tell the model:

Understand what the customer is trying to accomplish and determine
whether their request belongs to Orders, Returns, or General Support

Understand what the customer is trying to accomplish and determine
whether their request belongs to Orders, Returns, or General Support

Understand what the customer is trying to accomplish and determine
whether their request belongs to Orders, Returns, or General Support

The first should behave exactly the same every time.

The second intentionally gives the model room to interpret language.

Salesforce describes Agent Script as combining deterministic logic with LLM reasoning within the same workflow.

That hybrid architecture is the reason Agent Script matters.

The Biggest Agent Script Mistake: Making Everything Agentic

One of the easiest mistakes when building agents is pushing too much responsibility into the LLM.

Consider a customer service agent.

You could write:

Before processing a return, make sure the customer has been verified
and that the order is eligible for a return

Before processing a return, make sure the customer has been verified
and that the order is eligible for a return

Before processing a return, make sure the customer has been verified
and that the order is eligible for a return

That sounds reasonable.

But you are asking the model to remember and enforce two business rules.

A better architecture is:

Identity Verified?
        |
       No
        |
        v
Verification Subagent
        |
       Yes
        |
        v
Check Return Eligibility
        |
    Eligible?
     /     \
   No       Yes
             |
             v
        Return Action

Identity Verified?
        |
       No
        |
        v
Verification Subagent
        |
       Yes
        |
        v
Check Return Eligibility
        |
    Eligible?
     /     \
   No       Yes
             |
             v
        Return Action

Identity Verified?
        |
       No
        |
        v
Verification Subagent
        |
       Yes
        |
        v
Check Return Eligibility
        |
    Eligible?
     /     \
   No       Yes
             |
             v
        Return Action

The LLM does not get to decide whether verification matters.

The system does.

Agent Script provides patterns specifically for enforcing required workflows and conditionally exposing capabilities. Salesforce recommends deterministic transitions when a step must occur, rather than relying on the model to choose it.

This leads to one of our primary Agentforce design principles.

Deterministic outside. Agentic inside.

Use deterministic logic for:

• authorization

• identity verification

• eligibility

• transaction limits

• workflow sequencing

• required fields

• compliance requirements

• system state

• escalation thresholds

Use LLM reasoning for:

• understanding intent

• interpreting unstructured language

• summarization

• question answering

• determining which appropriate tool fits a request

• generating explanations

• handling conversational variation

The LLM should reason inside boundaries created by the system.

Not create the boundaries itself.

Best Practice 1: Keep start_agent Small

Every request initially enters through the Agent Script start_agent block, which acts as the agent router.

That makes it one of the most important pieces of the architecture.

It is also very easy to overload.

A common implementation begins adding more and more instructions:

Determine if this is billing.
Determine if this is support.
Determine if the customer wants an order.
Check whether they are verified.
Check whether they mentioned an account.
Check whether this should escalate.
Check whether

Determine if this is billing.
Determine if this is support.
Determine if the customer wants an order.
Check whether they are verified.
Check whether they mentioned an account.
Check whether this should escalate.
Check whether

Determine if this is billing.
Determine if this is support.
Determine if the customer wants an order.
Check whether they are verified.
Check whether they mentioned an account.
Check whether this should escalate.
Check whether

Eventually the router becomes another giant prompt.

Instead, treat start_agent like an API gateway.

Its job should primarily be:

1. Establish critical state.

2. Enforce global prerequisites.

3. Identify the appropriate subagent.

4. Transition.

Salesforce similarly recommends limiting the number of subagents exposed through the router and using distinct descriptions to improve routing accuracy.

A clean architecture might look like:

start_agent

├── Identity
├── Orders
├── Returns
├── Billing
└── Escalation

start_agent

├── Identity
├── Orders
├── Returns
├── Billing
└── Escalation

start_agent

├── Identity
├── Orders
├── Returns
├── Billing
└── Escalation

Each subagent should own a clearly bounded domain.

Best Practice 2: Hide Tools the Agent Should Not Be Able to Use

Prompting an agent not to use an action is weaker than preventing the action from being available.

Agent Script’s available when pattern allows actions and subagents to disappear from the model’s available toolset when conditions are not satisfied.

For example:

create_return

available when:
    customer_verified == True
    and return_eligible == True

create_return

available when:
    customer_verified == True
    and return_eligible == True

create_return

available when:
    customer_verified == True
    and return_eligible == True

Conceptually, this is much stronger than:

Do not create a return unless the customer is verified

Do not create a return unless the customer is verified

Do not create a return unless the customer is verified

Why?

Because an available tool can potentially be selected by the reasoning engine.

A tool that is unavailable cannot.

Salesforce explicitly recommends filtering business-sensitive capabilities rather than relying entirely on prompt instructions, including as protection against user manipulation and reasoning mistakes.

This is one of the most important Agent Script patterns for enterprise deployments.

Think of it as least privilege for agents.

Only expose the capability when the agent actually needs it.

Best Practice 3: Use Variables for State, Not Memory for Everything

Agentic applications are stateful systems.

The agent may need to know:

• whether the customer is verified

• which account is active

• which order is being discussed

• whether an eligibility check succeeded

• what step of a workflow has been completed

Those values should not depend on the model remembering them from conversation history.

Agent Script variables provide explicit state that can persist across subagents and conversational turns.

For example:

customer_verified = False
selected_order_id = None
return_eligible = False

customer_verified = False
selected_order_id = None
return_eligible = False

customer_verified = False
selected_order_id = None
return_eligible = False

Now your workflow can make deterministic decisions based on known state.

But there is an important second rule:

Do not turn every piece of conversational context into a variable.

Store state when it materially changes system behavior.

Good variables:

identity_verified
order_id
return_eligible
escalation_required

identity_verified
order_id
return_eligible
escalation_required

identity_verified
order_id
return_eligible
escalation_required

Probably unnecessary:

customer_sounded_frustrated_three_messages_ago

customer_sounded_frustrated_three_messages_ago

customer_sounded_frustrated_three_messages_ago

Unless that information directly controls your workflow.

Salesforce similarly recommends using variables strategically rather than storing every available piece of information.

Best Practice 4: Make Multi-Step Operations Deterministic

Suppose an agent needs to:

1. Retrieve an order.

2. Check its return eligibility.

3. Retrieve the refund method.

4. Create a return.

5. Send confirmation.

You could give the LLM five tools and hope it calls them correctly.

Or you can explicitly sequence the operation.

Agent Script supports deterministic action chaining so that workflows can execute in a guaranteed order.

This becomes especially important as agents move from answering questions to performing work.

The more transactional the workflow becomes, the less you should depend on the model remembering an exact sequence.

A useful rule is:

Conversation can be probabilistic.

Transactions should be deterministic.

Best Practice 5: Give the Agent Less Context, Not More

One of the recurring misconceptions in agent development is that more context automatically creates a smarter agent.

Usually it creates a noisier one.

An agent deciding whether to process an order return probably does not need:

• every Account field

• every Contact field

• every historical case

• 40 unrelated actions

• the entire corporate knowledge base

• every available subagent

Context engineering is fundamentally about giving the model the right context at the right moment.

Salesforce’s guidance similarly emphasizes intentionally curating the information, instructions, tools, and data available to the agent.

Agent Script gives developers several ways to enforce that principle.

Use:

• specialized subagents

• scoped actions

• available when

• variables

• deterministic data fetching

• explicit resource references

Instead of giving one giant agent everything.

Best Practice 6: Reference Actions and Resources Explicitly

If you have two actions:

lookup_customer
lookup_customer_orders

lookup_customer
lookup_customer_orders

lookup_customer
lookup_customer_orders

and your reasoning instructions simply say:

Find their orders

Find their orders

Find their orders

the model will probably figure it out.

Probably is not what we optimize for in production.

Agent Script allows reasoning instructions to reference specific resources directly.

Salesforce supports explicit references to actions, variables, and subagents, giving the reasoning engine a stronger signal about what resource should be used.

The architecture should make the correct decision obvious.

This also means naming matters.

Prefer:

get_customer_open_orders
check_order_return_eligibility
create_customer_return
go_to_order_support

get_customer_open_orders
check_order_return_eligibility
create_customer_return
go_to_order_support

get_customer_open_orders
check_order_return_eligibility
create_customer_return
go_to_order_support

over:

get_data
check_status
process
next

get_data
check_status
process
next

get_data
check_status
process
next

Your naming system becomes part of the context the model reasons over.

Best Practice 7: Do Not Rebuild Salesforce Business Logic Inside Agent Script

This is an architectural boundary we think is particularly important.

Agent Script should orchestrate agent behavior.

It should not become the new home for every enterprise business rule.

If your organization already has reliable logic in:

• Flow

• Apex

• APIs

• validation rules

• integration services

keep that execution where it belongs.

Expose it to the agent as an action.

A clean Agentforce architecture looks more like:

               Agentforce
                   |
                   v
              Agent Script
         orchestration + routing
                   |
            ┌──────┼──────┐
            v      v      v
          Flow    Apex    APIs
            |      |      |
            └──────┼──────┘
                   |
                   v
            Enterprise Data

               Agentforce
                   |
                   v
              Agent Script
         orchestration + routing
                   |
            ┌──────┼──────┐
            v      v      v
          Flow    Apex    APIs
            |      |      |
            └──────┼──────┘
                   |
                   v
            Enterprise Data

               Agentforce
                   |
                   v
              Agent Script
         orchestration + routing
                   |
            ┌──────┼──────┐
            v      v      v
          Flow    Apex    APIs
            |      |      |
            └──────┼──────┘
                   |
                   v
            Enterprise Data

Agent Script decides when the capability should be used.

Your application layer determines how the transaction actually works.

That separation makes agents easier to test, govern, maintain, and evolve.

Best Practice 8: Treat Agent Script Like Source Code

Agent Script should not be treated like a prompt somebody configured once inside Setup.

It is application logic.

Salesforce made Agentforce Builder and Agent Script generally available during the Summer ‘26 cycle and also open-sourced the Agent Script parser, linter, compiler, Language Server Protocol tooling, and editor integrations.

That signals an important shift.

Agent development is increasingly becoming software development.

Your Agent Script should therefore participate in the same engineering lifecycle as the rest of your Salesforce implementation:

Design
  ↓
Develop
  ↓
Lint
  ↓
Version Control
  ↓
Deploy
  ↓
Test
  ↓
Observe
  ↓
Iterate

Design
  ↓
Develop
  ↓
Lint
  ↓
Version Control
  ↓
Deploy
  ↓
Test
  ↓
Observe
  ↓
Iterate

Design
  ↓
Develop
  ↓
Lint
  ↓
Version Control
  ↓
Deploy
  ↓
Test
  ↓
Observe
  ↓
Iterate

Salesforce also provides downloadable Agent Script documentation specifically so coding agents and development environments can reference current syntax, deployment rules, patterns, and examples. The documentation bundle is currently updated weekly.

This opens the door to much stronger Agentforce development workflows around:

• Git

• CI/CD

• Salesforce CLI

• automated testing

• regression testing

• coding agents

• code review

• environment promotion

That is where enterprise agent development is headed.

Where Should You Use Agent Script?

Agent Script becomes most valuable when an agent has workflow complexity or business risk.

Strong use cases include:

Customer Service

Verification → Customer → Order → Eligibility → Resolution

Employee Support

Employee → Permission Check → HR Data → Action

Sales Operations

Lead → Account Context → Qualification → Opportunity Action

Financial Service Workflows

Identity → Account → Eligibility → Transaction

IT Service Management

User → Device → Issue Classification → Remediation → Escalation

Commerce

Customer → Product → Inventory → Cart → Transaction

In all of these cases, the model needs freedom to communicate naturally while the system needs control over what actually happens.

That is Agent Script’s sweet spot.

Where You Probably Do Not Need Heavy Agent Script

Not every agent requires sophisticated orchestration.

If your use case is primarily:

User Question
      ↓
Knowledge Retrieval
      ↓
Answer

User Question
      ↓
Knowledge Retrieval
      ↓
Answer

User Question
      ↓
Knowledge Retrieval
      ↓
Answer

you may not need a complex graph of variables, conditions, subagents, and transitions.

Adding unnecessary deterministic logic can make an agent harder to maintain without making it meaningfully safer.

The goal is not maximum Agent Script.

The goal is the minimum deterministic architecture required to make the agent reliable.

Salesforce’s own Agent Script guidance recommends starting with the fewest instructions necessary and adding complexity as testing reveals a need for it.

That is a philosophy we strongly agree with.

The Architecture We Recommend

When designing Agentforce implementations, think in four layers.

1. Reasoning Layer

The LLM handles ambiguity.

What is the user trying to accomplish

What is the user trying to accomplish

What is the user trying to accomplish

2. Orchestration Layer

Agent Script controls the workflow.

What is the agent allowed to do next

What is the agent allowed to do next

What is the agent allowed to do next

3. Execution Layer

Flow, Apex, APIs, and integrations perform the work.

How does the transaction happen

How does the transaction happen

How does the transaction happen

4. Data Layer

Salesforce, Data Cloud, Knowledge, and external systems provide trusted state.

What is actually true

What is actually true

What is actually true

The resulting architecture looks like this:

                  USER
                    |
                    v
             LLM REASONING
                    |
                    v
              AGENT SCRIPT
      routing / state / guardrails
                    |
          ┌─────────┼─────────┐
          v         v         v
        FLOW       APEX      API
          |         |         |
          └─────────┼─────────┘
                    |
                    v
           TRUSTED SYSTEMS

                  USER
                    |
                    v
             LLM REASONING
                    |
                    v
              AGENT SCRIPT
      routing / state / guardrails
                    |
          ┌─────────┼─────────┐
          v         v         v
        FLOW       APEX      API
          |         |         |
          └─────────┼─────────┘
                    |
                    v
           TRUSTED SYSTEMS

                  USER
                    |
                    v
             LLM REASONING
                    |
                    v
              AGENT SCRIPT
      routing / state / guardrails
                    |
          ┌─────────┼─────────┐
          v         v         v
        FLOW       APEX      API
          |         |         |
          └─────────┼─────────┘
                    |
                    v
           TRUSTED SYSTEMS

Each layer has a different responsibility.

And that separation is what makes the agent predictable.

Agent Script Is Bigger Than Prompt Engineering

The first generation of enterprise AI was largely about prompts.

The next generation is about architecture.

As agents become capable of actually performing work inside enterprise systems, organizations need a way to combine probabilistic intelligence with deterministic software.

Agent Script gives Salesforce developers a native mechanism for doing exactly that.

The strongest Agentforce implementations will not be the ones with the longest instructions.

They will be the ones that deliberately determine:

• what the LLM decides

• what software decides

• what context the model receives

• which tools the model can access

• what state the system maintains

• what must happen deterministically

• what actions should never depend on interpretation

That is the shift from building a chatbot to engineering an agent.

And it is where Agent Script becomes one of the most important pieces of the Agentforce stack.