Agentforce Agent Script Guide

Language Overview

Agent Script is Salesforce's new declarative scripting language for building AI agents on the Agentforce 360 Platform. Announced at Dreamforce 2025, it's a high-level, domain-specific language (DSL) designed to empower agents with programmatic precision while maintaining the flexibility of LLMs.

Key Characteristics

• Compiled Language: Agent Script doesn't run directly; it generates a structured specification called an "Agent Graph" consumed by the Atlas Reasoning Engine
• Declarative: Define what the agent should do, not how
• State-based: Uses variables to maintain conversation state
• Topic-driven: Conversations are organized into logical topics
• Action-oriented: Integrates with external systems through actions
• Human-readable: Syntax designed for both low-code and pro-code developers

File Structure

Required Files

1. config.yml - Agent Configuration

Defines agent metadata and settings.

config:
   agent_name: string              # Display name of the agent
   developer_name: string          # Internal/API name (snake_case)
   default_agent_user: string      # Default user assignment
   user_locale: string             # Locale code (e.g., en_US)
   enable_enhanced_event_logs: boolean
   agent_description: string       # Description of agent purpose

2. system.yml - System Instructions

Defines global agent behavior and messages.

system:
   instructions:
      # Natural language instructions for agent personality and behavior
      # Can be multi-line text
   
   messages:
      welcome: string              # Greeting message
      error: string                # Error fallback message
      # Add custom message templates as needed

3. variables.yml - State Variables

Declares all variables used across topics and actions.

variables:
   variable_name: type = default_value
      description: "Description of the variable"

Example Variables:

variables:
   user_verified: boolean = False
      description: "Whether user has completed verification"
   
   user_email: string
      description: "User's email address"
   
   order_total: number = 0
      description: "Total order amount"

Core Concepts

Complete Official Example: Weather Forecast Topic

topic forecast_service:
   description: "Provides detailed weather forecasts including hourly and multi-day predictions"
   
   reasoning_instructions:
      >>
         Deliver comprehensive weather forecasts tailored to user needs.
         
         Call {{@action.Get_Weather_Forecast}} with {{@variable.user_city}} and {{@variable.user_country}} if available.
         Include forecast_days parameter (1-14 days) and set include_hourly flag based on user needs.
         
         Present multi-day forecasts showing daily conditions, high/low temperatures, precipitation chances, and wind information.
         Always include forecast confidence level and highlight notable weather trends.
         
         If user also wants current conditions, {{@action.current_conditions}} can transition to current weather service.
         If severe weather is detected in forecast data, {{@action.alert_monitoring}} can transition to alerts.
         
         Gather missing preferences when needed: number of days, hourly details, or location clarification.
   
   reasoning_actions:
      @action.Get_Weather_Forecast
         with city=@variable.user_city
         with country=@variable.user_country
         with forecast_days
         with include_hourly
         set @variable.forecast_data = @result.daily_forecast
         set @variable.hourly_forecast = @result.hourly_forecast
      
      @utils.transition to @topic.current_weather_service as current_conditions
         description: "Check current weather conditions alongside the forecast."
      
      @utils.transition to @topic.severe_weather_alerts as alert_monitoring
         description: "Monitor for any severe weather in the forecast period."

Agent Script vs. Natural Language Instructions

Before Agent Script, developers defined agent behavior using purely natural language instructions. While this worked, it lacked programmatic control over execution flow.

Old Approach (Natural Language Only):

Deliver comprehensive weather forecasts tailored to user needs.
First, call the Get_Weather_Forecast action with {$User_City} and {$User_Country} if available.
Include forecast_days parameter (1-14 days) and set include_hourly flag based on user needs.

Present multi-day forecasts showing daily conditions, high/low temperatures, precipitation chances, and wind information.
Always include forecast confidence level and highlight notable weather trends.

You can't provide any information about the current weather.
You don't handle any alert monitoring for severe weather situations.

Gather missing preferences when needed: number of days, hourly details, or location clarification.

New Approach (Agent Script):

topic forecast_service:
   description: "Provides detailed weather forecasts including hourly and multi-day predictions"
   
   reasoning_instructions:
      >>
         Deliver comprehensive weather forecasts tailored to user needs.
         Call {{@action.Get_Weather_Forecast}} with {{@variable.user_city}}.
         
         If user wants current conditions, {{@action.current_conditions}} can transition to current weather service.
   
   reasoning_actions:
      @action.Get_Weather_Forecast
         with city=@variable.user_city
         with country=@variable.user_country
         set @variable.forecast_data = @result.daily_forecast
      
      @utils.transition to @topic.current_weather_service as current_conditions
         description: "Check current weather conditions alongside the forecast."

Key Advantages:

• Programmatic control over action execution and transitions
• Direct variable assignment and manipulation
• Conditional logic with available when
• Deterministic handoffs between topics
• Reduced ambiguity in agent behavior

Topics

Topics represent distinct conversation flows or capabilities. They are the primary organizational unit.

Topic Selector (Entry Point)

Every agent must have one topic selector that acts as the router.

start_agent topic_selector:
   description: "Routes conversation to appropriate topic"
   
   reasoning_instructions:
      >>
         Multi-line natural language instructions.
         Use {{@action.action_name}} to reference actions.
         Use {{@variable.variable_name}} to reference variables.
   
   reasoning_actions:
      # Available actions the agent can take

Standard Topics

topic TopicName:
   description: "What this topic handles"
   
   before_reasoning:
      # Code executed before agent reasoning
      # Typically used to fetch data or check conditions
   
   reasoning_instructions:
      >>
         Natural language instructions for this topic.
         Guide the agent on how to handle conversations.
   
   reasoning_actions:
      # Available actions in this topic

Actions

Actions are the interface between the agent and external systems (Salesforce Flows, APIs, etc.).

Action Invocation (in topics)

Actions can be invoked with parameters in two ways:

Style 1: Explicit Assignment

@action.Get_Weather_Forecast
   with city=@variable.user_city
   with country=@variable.user_country
   with forecast_days
   with include_hourly
   set @variable.forecast_data = @result.daily_forecast
   set @variable.hourly_forecast = @result.hourly_forecast

Style 2: Parameter Name Only (collected from user)

@action.action_name
   available when condition          # Optional: when action is available
   with parameter_name               # Input parameter (collected from user)
   with parameter=@variable.var_name # Input from variable
   set @variable.result_var = @result.output_field  # Capture output

Action Definition (separate file)

action_name:
   description: "What this action does"
   
   inputs:
      param_name: type               # Required inputs
   
   outputs:
      output_name: type              # Expected outputs
         description: "Optional description"
   
   target: "flow://FlowName"         # Integration target

Variables and References

Variables must be declared in variables.yml before use.

Reference Patterns

• @variable.variable_name - Reference a variable
• @result.output_field - Reference action output
• @action.action_name - Reference an action
• @topic.TopicName - Reference a topic
• @utils.transition - Built-in utility for topic transitions

Transitions

Transitions move the conversation between topics.

@utils.transition to @topic.TargetTopic as action_alias
   description: "Why this transition exists"
   available when @variable.condition == value

Conditional Logic

In before_reasoning blocks:

before_reasoning:
   if @variable.var_name != None:
      run @action.action_name
         with param=@variable.value
         set @variable.result = @result.output

In reasoning_actions:

@action.action_name
   available when @variable.var_name == value
   available when @variable.other_var != True

Syntax Reference

How Agent Script Works

Agent Script is a compiled language. When you write your agent definition, it doesn't run directly. Instead:

1. Agent Script code is compiled into a structured specification
2. This creates an Agent Graph - an executable representation of your agent
3. The Atlas Reasoning Engine consumes and executes this graph
4. The engine performs reflective loops, multi-topic coordination, and multi-agent orchestration exactly as you defined

Indentation Rules

• Use 3 spaces per indentation level
• Consistent indentation is critical
• No tabs

Multi-line Strings

Use >> for multi-line content:

reasoning_instructions:
   >>
      This is line one.
      This is line two.
      Use {{@action.name}} for template substitution.

Comments

# This is a comment
variables:
   # Section comment
   var_name: string  # Inline comment

Template Substitution in Instructions

In reasoning_instructions blocks, reference actions and variables using double curly braces:

reasoning_instructions:
   >>
      Call {{@action.Get_Weather_Forecast}} with {{@variable.user_city}}.
      
      If user wants current conditions, {{@action.current_conditions}} can transition to current weather service.
      
      Present the data from {{@variable.forecast_data}}.

Template Syntax:

• {{@action.action_name}} - Reference an action in natural language instructions
• {{@variable.var_name}} - Reference a variable's value in instructions

Chained Actions

Execute multiple actions in sequence:

@action.first_action
   with param=@variable.input
   set @variable.intermediate = @result.output
   run @action.second_action
      with param=@variable.intermediate
      with other_param="static value"

Best Practices

1. Topic Organization

• Start with Topic Selector: Always route through a central selector
• Single Responsibility: Each topic should handle one logical capability
• Clear Naming: Use descriptive topic names (Identity, Menu, Escalation)

2. Variable Management

• Declare All Variables: Always declare in variables.yml with descriptions
• Use Defaults: Provide sensible default values
• Group Logically: Use comments to group related variables

3. Action Design

• Validate Before Calling: Check prerequisites with available when
• Confirm User Intent: For destructive actions, always confirm
• Handle Results: Always capture action outputs with set

4. Error Handling

• Check for None: Always validate required variables exist
• Provide Fallbacks: Use system.messages.error for failures
• Guide Users: Give clear instructions when actions fail

5. User Experience

• Natural Instructions: Write conversational reasoning_instructions
• Progressive Disclosure: Don't overwhelm with all options upfront
• Confirm Actions: Summarize what was done after completing actions
• Offer Next Steps: Guide users to related capabilities

Common Patterns

Authentication Flow

topic Identity:
   before_reasoning:
      if @variable.user_email != None:
         run @action.send_verification
            with email=@variable.user_email
            set @variable.verification_code = @result.code
   
   reasoning_actions:
      @action.validate_code
         with user_code
         set @variable.verified = @result.is_valid
      
      @utils.transition to @topic.MainMenu
         available when @variable.verified == True

CRUD Operations

topic DataManagement:
   reasoning_actions:
      @action.create_item
         with name
         with description
         set @variable.new_item_id = @result.item_id
      
      @action.update_item
         with item_id=@variable.selected_item_id
         with changes_json
         set @variable.update_summary = @result.summary
      
      @action.delete_item
         with item_id=@variable.selected_item_id
         set @variable.deletion_confirmed = @result.success

Escalation Pattern

topic Support:
   before_reasoning:
      run @action.check_availability
         set @variable.agent_available = @result.is_available
   
   reasoning_actions:
      @action.connect_agent
         available when @variable.agent_available == True
         with session_id=@variable.session_id
      
      @action.create_ticket
         available when @variable.agent_available != True
         with subject
         with description
         set @variable.ticket_number = @result.ticket_id

Debugging Tips

1. Check Indentation: Most errors come from incorrect spacing
2. Validate References: Ensure all @variable, @action, @topic exist
3. Test Conditions: Verify boolean logic in available when clauses
4. Trace Data Flow: Follow variable assignments through actions
5. Review Descriptions: Use clear descriptions for better AI reasoning

Integration Points

Actions can target:

• Salesforce Flows: flow://FlowName
• Apex Methods: apex://ClassName.methodName (inferred)
• External APIs: Via Flow callouts (indirect)

All business logic should be implemented in the target system, with the agent definition focusing on conversation flow and user experience.