Dylan Andersen's DocsDylan Andersen's Docs
Working with AgentforceThe New Agentforce BuilderAgent Script

Learning Script, Quickly

A domain-specific language for defining agent behavior in Salesforce's Agentforce Builder

Agent Script

Agent Script is a domain-specific language for defining agent behavior in Salesforce's Agentforce Builder. It provides a structured way to write, manage, and understand how AI agents handle conversations, execute actions, and make decisions.

Learning Script Quickly hero

What is Agent Script?

Agent Script lets you define:

  • Subagents - jobs that an agent can perform (previously called topics)
  • Actions - executable tasks (Flows, Apex, Prompts)
  • Variables - state that persists across conversation turns
  • Reasoning Instructions - prompts and logic that guide LLM behavior
  • Tools - functions the LLM can choose to call

Subagent vs. Topic

The current keyword is subagent. The older keyword topic still parses as a legacy alias so old scripts keep working, but all new scripts should use subagent. Some Salesforce doc pages still use "topic" in URLs or labels — treat them as the same concept.

Quick Start: Script Structure

A complete Agent Script consists of blocks that define configuration, variables, and subagents:

# Configuration
config:
  label: "My Agent"
  developer_name: "My_Agent"

# System messages
system:
  welcome: "Hello! How can I help you today?"
  error: "I'm sorry, something went wrong."

# Global variables
variables:
  user_name: mutable string = ""

# Subagents define agent capabilities
start_agent agent_router:
  description: "Entry point for all conversations"
  reasoning:
    instructions: |
      Greet the user and determine their intent.

subagent order_management:
  description: "Handles order-related requests"
  # ... actions and reasoning

A Starter Script You Can Actually Paste Into a .agent File

If you're learning the language, it helps to see one end-to-end script instead of eleven tiny fragments. This example uses real Agent Script shapes: mutable variables, a start_agent, deterministic action runs, and a second subagent for a reusable check.

config:
  label: "Field Service Weather Assistant"
  developer_name: "Field_Service_Weather_Assistant"

system:
  welcome: "Hi! I can help schedule field work and check whether weather will block the visit."
  error: "I hit a problem while working on that. Let me retry or route you to a human."

variables:
  customer_city: mutable string = ""
  work_order_id: mutable id = ""
  current_temperature: mutable number = 0
  weather_ready: mutable boolean = False
  service_window: mutable string = ""

start_agent request_router:
  description: "Routes customers to scheduling or weather-check workflows"
  reasoning:
    instructions: |
      Greet the customer and determine what they need.
      If they are asking about weather, site readiness, or appointment viability, use @subagent.weather_check.
      If they are asking to book or reschedule work, use @subagent.schedule_visit.

subagent weather_check:
  description: "Checks weather conditions before a field visit"
  actions:
    get_weather:
      target: flow://Get_Current_Weather_Data
      inputs:
        city:
          type: string
          required: True
      outputs:
        temperature:
          type: number
        conditions:
          type: string
  reasoning:
    instructions:
      if @variables.customer_city is not None and @variables.customer_city != "":
        -> run @actions.get_weather
        -> set @variables.current_temperature = @actions.get_weather.outputs.temperature
        -> set @variables.weather_ready = True
      |
      Help the customer understand whether current weather may affect the visit.
      If weather data is available, explain the result clearly and practically.

subagent schedule_visit:
  description: "Books or reschedules a field service appointment"
  actions:
    create_visit:
      target: flow://Create_Field_Service_Visit
      inputs:
        work_order_id:
          type: id
          required: True
        service_window:
          type: string
          required: True
      outputs:
        appointment_id:
          type: id
  reasoning:
    instructions:
      if @variables.weather_ready == False:
        -> run @subagent.weather_check
      |
      Help the customer pick a service window and confirm the appointment.
      Once they choose a time, create the visit and confirm what happens next.

Reference Pages

Naming Conventions

Important

All identifiers (variables, actions, subagents) must follow Salesforce developer name standards:

  • Begin with a letter (not underscore)
  • Alphanumeric characters and underscores only
  • Cannot end with underscore
  • No consecutive underscores (__)
  • Maximum 80 characters
  • Use snake_case for actions/subagents, camelCase for variables

Key Syntax Patterns

Referencing Variables

ContextSyntax
In script logic@variables.variable_name
In prompt instructions{!@variables.variable_name}

Running Actions

MethodDeterminismUsage
run @actions.action_nameDeterministic - always runsLogic blocks
{!@actions.action_name}Non-deterministic - LLM decidesPrompt instructions
Define as toolNon-deterministic - LLM decidesreasoning.actions block

Transitions

ContextSyntax
In before_reasoning / after_reasoningtransition to @subagent.name
In reasoning.actions (tools)@utils.transition to @subagent.name

Flow of Control

When a customer sends a message, the agent processes it through the following stages:

Customer Message

The conversation begins when a customer sends a message to the agent.

start_agent

The start_agent block runs on every utterance. This is the entry point that receives all customer messages and determines the initial routing.

The start_agent block always executes first, regardless of which subagent will handle the request.

Subagent Classification

The agent determines which subagent should handle the customer's request. This classification happens based on the reasoning instructions in start_agent and the descriptions of the available subagents.

Selected Subagent Execution

Once a subagent is selected, it executes in the following order:

  1. before_reasoning (optional)

    • Runs first if defined
    • Typically used for setup, validation, or pre-processing
    • Can transition to other subagents

  2. reasoning.instructions

    • Core logic and prompts for the LLM
    • Contains the main instructions that guide the agent's response
    • Can include actions, tools, and conditional logic

  3. after_reasoning (optional)

    • Runs last if defined
    • Typically used for cleanup, post-processing, or final transitions
    • Can transition to other subagents

Both before_reasoning and after_reasoning are optional blocks. If not defined, the subagent will proceed directly to reasoning.instructions.

Transitions vs. Subagent References

  • @utils.transition to @subagent.name - one-way, no return to caller
  • @subagent.name - delegates then returns to caller (like a function call)

Source: Salesforce Developers - Agent Script

Session Tracing & Agent Testing

Run agent tests from Cursor and read session traces to understand what your Agentforce agent actually did.

1. All About Blocks

Structural components of an Agent Script that contain properties describing data or procedures

On this page

What is Agent Script?Quick Start: Script StructureA Starter Script You Can Actually Paste Into a .agent FileReference PagesNaming ConventionsKey Syntax PatternsReferencing VariablesRunning ActionsTransitionsFlow of ControlCustomer Messagestart_agentSubagent ClassificationSelected Subagent Execution