Unlocking Deterministic AI: A Developer’s Deep Dive into Agentforce Script

If you’ve been building with Agentforce, you are likely familiar with the Agent Builder Canvas view, which allows you to build agents via a low-code drag-and-drop UI or by chatting directly with Agentforce. While the Canvas view is fantastic for abstracting complexity, there comes a point where complex enterprise use cases require the precision, predictability, and version control of actual code.

Enter Agent Script, the underlying compiled language specifically designed by Salesforce for building Agentforce agents. Available in the builder’s Script view or locally via the Agentforce DX VS Code Extension, Agent Script provides a developer-friendly environment with syntax highlighting, autocompletion, and validation.

Let’s dive into the core features of Agent Script and explore how dropping down into the code gives you unprecedented control over your Agentforce deployments.

The hybrid approach: Merging logic and LLM reasoning

The most powerful aspect of Agent Script is that it bridges the gap between declarative, procedural, and natural language programming. Relying entirely on an LLM to interpret instructions can sometimes lead to unpredictable behavior. Agent Script solves this by combining the flexibility of LLM interpretation with the reliability of programmatic expressions.

In Agent Script, you can define specific execution paths using two distinct syntax markers:

  • Logic Instructions (->): These run deterministically every single time. You use them for running actions, defining if/else business rules, and setting variables.
  • Prompt Instructions (|): These represent the natural language sent directly to the reasoning engine, allowing the LLM to interpret how to respond to the user.

By combining these side-by-side, you can guarantee that a workflow—like verifying an account or checking an order status—executes predictably before the LLM takes over to craft the customer-facing response.

Explicit state management via variables

In the Agent Builder UI, you might rely heavily on the LLM’s conversational memory to maintain context. Agent Script introduces robust, explicit state management through the variables block. By relying on deterministic variables rather than LLM context memory, you make your agent significantly more reliable.

Agent Script supports several variable types, including:

  • Regular Variables: Mutable or immutable variables with types like string, number, boolean, list, and object.
  • Linked Variables: Variables whose values are directly tied to an external source, such as the output of an action.
  • System Variables: Predefined variables, such as @system_variables.user_input, which explicitly captures the customer’s most recent utterance.

Variables can be injected dynamically into LLM prompt instructions using the {!@variables.<variable_name>} syntax.

Granular control: Actions vs. tools

While the Canvas view groups capabilities together, Agent Script explicitly differentiates between Topic Actions and Reasoning Actions (Tools).

  1. Deterministic Actions: If you want an action (like an Apex class, Flow, or Prompt Template) to run every single time a topic is parsed, you use the run @actions.<action_name> command within your logic instructions. This is perfect for data-fetching before the LLM begins reasoning.
  2. Tools for the LLM: If you want the LLM to subjectively decide whether to invoke an action based on context, you expose it in the reasoning.actions block.

Agent Script also introduces the available when parameter, giving you the power to conditionally show or hide a tool from the reasoning engine based on current variable states (e.g., available when @variables.verified == True).

Advanced flow of control and routing

Every agent built with Agent Script begins execution at a special block called start_agent (known as the “Topic Selector” in the Canvas view). This block serves as the entry point for topic classification and routing.

From there, developers can orchestrate complex transitions using the @utils.transition to command. Transitions in Agent Script are strictly one-way; once executed, the agent halts the current directive block, discards the existing prompt, and immediately passes control to the new topic.

Alternatively, you can delegate control by referencing a topic directly (@topic.<topic_name>) inside your reasoning actions. Unlike declarative transitions, a direct topic reference acts like a standard tool call—once the delegated topic completes, the flow of control returns to the original topic.

Developer experience (DX) first

Agent Script is whitespace-sensitive, utilizing indentation to indicate structure much like Python or YAML. Because it is a compiled language that translates down to lower-level metadata, it integrates beautifully into the modern Salesforce developer workflow.

Instead of making changes purely in a UI, advanced developers can use Agentforce DX to pull the script file into their local Salesforce DX project. From there, you can leverage the Agentforce DX Visual Studio Code extension for standard code editing, version control, and CI/CD pipelines.

Why adopt Agent Script?

While the Agent Builder Canvas view is excellent for rapid prototyping and simple use cases, Agent Script is where the true power of Agentforce lies. By adopting Agent Script, developers gain the ability to chain actions deterministically, enforce strict if/else conditional logic, and precisely engineer the context passed to the LLM. If you are building enterprise-grade AI agents, it’s time to switch to the Script view.

Contact Us