Agent Script Explained — Build Predictable Agentforce Agents with Pro-Code

Stop relying solely on LLM interpretation. Agent Script gives you deterministic control over your Agentforce agents — pro-code style.

▶ Watch on YouTube

Agent Script Explained — Build Predictable Agentforce Agents with Pro-Code | SF Bolt

Agentforce agents are powerful — but left entirely to an LLM, their behaviour can be unpredictable. Agent Script is Salesforce's pro-code language for building agents in Agentforce Builder. It gives you programmatic control over when actions run, how variables are stored, when subagents are invoked, and how the agent reasons — without losing the conversational power of the LLM.

What Is Agent Script?

According to the official Agentforce Developer Guide, Agent Script is the language for building agents in Agentforce Builder. Script combines the flexibility of natural language instructions for handling conversational tasks with the reliability of programmatic expressions for handling business rules.

You can build predictable, context-aware agent workflows that don't rely solely on interpretation by an LLM. For example, you can use script to control when your agent transitions from one subagent to another or when actions are run in a particular sequence — sometimes called action chaining.

💡 Topics are now called SubagentsBeginning in April 2026, agent topics are now called subagents. There are no changes to functionality. During this transition, you may see a mix of the new and previous terms in documentation.

Three Ways to Write Agent Script

The official docs describe three authoring modes:

• Chat with Agentforce — describe what you want in plain English and Agentforce converts it to subagents, actions, instructions, and expressions
• Canvas view — script is summarised into readable blocks. Type / to add expressions and @ to add resources like subagents, actions, and variables
• Script view — write and edit Agent Script directly with syntax highlighting, autocompletion, and validation. This is the pro-code path

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.

The Two Halves of Agent Script: Deterministic + LLM

This is the core architectural idea. Agent Script preserves the conversational skills and complex reasoning ability derived from natural language prompts, and it adds the determinism of programmatic instructions.

In any given subagent you can define:

• Specific areas where an LLM is free to make reasoning decisions — handled via Reasoning Instructions
• Specific areas where the agent must execute deterministically — also handled via Reasoning Instructions, using logic instructions alongside prompt instructions
• Variables to reliably store information about the agent's current state, rather than relying on LLM context memory
• Conditional expressions to determine the agent's execution path or LLM utterances
• Conditions under which the agent transitions to a new subagent — deterministically or as an LLM tool

Variables

According to the official Variables reference, variables let agents deterministically remember information across conversation turns, track progress, and maintain context throughout the session. You define all variables in the variables block, and all subagents in the agent can access them.

There are three types:

Type	Description
Regular variable	You initialize it with a default value. Use mutable to allow the agent to change it.
Linked variable	Value is tied to an action's output. Can't have a default value, can't be set by the agent.
System variable	Predefined and prepopulated. Currently @system_variables.user_input is the only one — holds the customer's most recent utterance.

To reference a variable from the script, use @variables.<variable_name>. To reference a variable from within reasoning instructions, use {!@variables.<variable_name>}.

Supported variable types include string, number, boolean, object, date, id, and list[type].

Agent Script — variables block

variables:
  customer_name: mutable string
  order_total:   mutable number = 0
  is_member:     mutable boolean = False
  appointment_type: string
  last_action_result: linked string

Reasoning Instructions

According to the official Reasoning Instructions reference, a subagent's reasoning block contains instructions that Agentforce resolves into a prompt for the LLM. The resolved prompt instructs the LLM to perform the subagent's purpose.

There are two different parts of reasoning instructions: logic instructions and prompt instructions. Logic instructions are deterministic or conditional expressions that determine certain requirements, run actions, and set variables. Prompt instructions are passed as natural language to the LLM if the conditions are met.

The | (pipe) character separates deterministic logic from LLM prompt instructions in the same reasoning block:

Agent Script — reasoning instructions

reasoning:
  instructions:
    # Deterministic logic — runs regardless of LLM
    - @actions.verify_membership with (email: @variables.customer_email)
      set: is_member = result.verified

    # Conditional + LLM prompt (pipe separates logic from natural language)
    - @variables.is_member == True ->
      | Welcome back, {!@variables.customer_name}!
        You have access to member-exclusive pricing.
    - @variables.is_member == False ->
      | Let me help you get started.
        Would you like to hear about our membership benefits?

💡 The pipe | is how determinism meets LLM promptingLogic instructions are deterministic conditional expressions that run actions and set variables. Prompt instructions are passed as natural language to the LLM if the conditions are met. The prompt instructions can still reference literal values through @variables, @utils, and @actions.

Tools: Letting the LLM Decide vs. Forcing Execution

According to the official Tools reference, tools are executable functions that the LLM can choose to call, based on the tool's description and the current context. You define tools in the topic's reasoning.actions block.

Agent Script distinguishes between two types of action blocks:

• topic.actions — available to you from logic-based reasoning instructions (deterministic)
• topic.reasoning.actions — available to the LLM to call as needed, and can be referenced in your prompt-based instructions (LLM-driven)

You can use the available when parameter to deterministically specify when the tool is available.

Subagent Transitions

In reasoning actions, you can reference a topic directly with @topic.<topic_name> or through a declarative transition (@utils.transition to). Use a direct @topic.<topic_name> reference to delegate to a topic, similar to an action or tool call. After the referenced topic is run, the flow returns to the original topic. Transitions are one way, whereas a direct topic reference returns to the original caller.

Agent Script — subagent transition

reasoning:
  instructions:
    # Deterministic transition — always goes to billing when amount > 500
    - @variables.order_total > 500 ->
      @utils.transition to: billing_subagent

    # LLM-driven — LLM decides when to call this based on context
  actions:
    - name: escalate_to_support
      description: Escalate to human support agent when customer is frustrated
      action: @topic.support_handoff

Key Takeaways

🚀 Agent Script — Quick Reference

• Agent Script = deterministic logic + LLM prompting in one language
• Variables block: mutable for changeable, linked for action output, @system_variables.user_input for last utterance
• Reasoning instructions: logic (deterministic) + | pipe + prompt (LLM)
• topic.actions = deterministic execution; topic.reasoning.actions = LLM tool calls
• Transitions: @utils.transition to is one-way; @topic.name reference returns to caller
• Write in Canvas view, Script view, or VS Code via Agentforce DX
• Shorter reasoning instructions = more accurate and reliable agent behaviour

📄 Sources: Get Started with Agent Script  |  Agent Script Reference: Variables  |  Agent Script Reference: Reasoning Instructions  |  Agent Script Reference: Tools

Watch on YouTube - Full Build And Demo

 If you have any question please leave a comment below.

If you would like to add something to this post please leave a comment below.

Share this blog with your friends if you find it helpful somehow !