Agent Script Syntax Reference

Agent Script Syntax Reference

Complete syntax guide for the Agent Script DSL. Your entire agent in one .agent file.

Design Principles

Block Structure

Required Block Order

system → config → variables → language → connections → topic → start_agent

✅ Validated Finding: Documentation implies strict ordering, but both config-first and system-first orderings compile. Pick one convention and be consistent.

Block Definitions

1. system: Block (Required)

system:
  messages:
    welcome: "Hello! How can I help?"
    error: "Sorry, something went wrong."
  instructions: "You are a helpful assistant."

2. config: Block (Required)

config:
  agent_name: "RefundAgent"
  agent_label: "Refund Agent"
  description: "Handles refund requests"
  default_agent_user: "admin@yourorg.com"

⚠️ Critical: default_agent_user must exist in the org with the "Einstein Agent User" profile. Query: SELECT Username FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true

3. variables: Block (Optional)

variables:
  # Mutable: State we track and modify
  failed_attempts: mutable number = 0
  customer_verified: mutable boolean = False
  order_ids: mutable list[string] = []

  # Linked: Read-only from external sources
  session_id: linked string
    source: @session.sessionID
    description: "Current session identifier"
  customer_id: linked string
    source: @context.customerId
    description: "Customer ID from context"

Variable Types

Variable Modifiers

⚠️ Booleans are capitalized: Use True/False, not true/false

4. language: Block (Optional)

language:
  default: "en_US"
  supported: ["en_US", "es_ES", "fr_FR"]

5. connections: Block (Optional)

connections:
  crm_system:
    type: "http"
    credential: "CRM_Named_Credential"
    base_url: "https://api.example.com/v1"

Connection Types

6. topic: Block (Required - one or more)

topic main:
  description: "Main conversation handler"
  reasoning:
    instructions: |
      Help the user with their request.
    actions:
      do_something: @actions.my_action
        description: "Action description"

7. start_agent: Block (Required - exactly one)

start_agent entry:
  description: "Entry point for conversations"
  reasoning:
    instructions: |
      Greet the user and route appropriately.
    actions:
      go_main: @utils.transition to @topic.main
        description: "Navigate to main topic"

💡 The name can be anything - "main", "entry", "topic_selector" - just be consistent.

Instruction Syntax

Pipe vs Arrow Syntax

Arrow Syntax (->) Patterns

reasoning:
  instructions: ->
    # Conditional (resolves BEFORE LLM)
    if @variables.customer_verified == True:
      | Welcome back, verified customer!
    else:
      | Please verify your identity first.

    # Inline action execution
    run @actions.load_customer
      with customer_id = @variables.customer_id
      set @variables.customer_data = @outputs.data

    # Variable injection in text
    | Customer name: {!@variables.customer_name}

    # Deterministic transition
    if @variables.failed_attempts >= 3:
      transition to @topic.escalation

Instruction Syntax Elements

Action Configuration

Action Declaration

actions:
  action_name: @actions.my_action
    description: "What this action does"
    with input_param = @variables.some_value
    set @variables.result = @outputs.output_field
    available when @variables.is_authorized == True

Action Target Protocols

Core Targets (Validated)

Additional Targets (From agent-script-recipes)

Note: Untested targets are documented in the official AGENT_SCRIPT.md rules. They may require specific licenses, org configurations, or future API versions.

Utility Actions

Resource References

Whitespace Rules

Indentation

CRITICAL: Never mix tabs and spaces in the same file. This causes compilation errors.

Boolean Values

Complete Example

system:
  messages:
    welcome: "Welcome to Pronto Support!"
    error: "Sorry, something went wrong. Let me connect you with a human."
  instructions: "You are a helpful customer service agent for Pronto Delivery."

config:
  agent_name: "pronto_refund_agent"
  agent_label: "Pronto Refund Agent"
  description: "Handles customer refund requests with churn risk assessment"
  default_agent_user: "agent_user@myorg.com"

variables:
  # Mutable state
  customer_verified: mutable boolean = False
  failed_attempts: mutable number = 0
  churn_risk_score: mutable number = 0
  refund_status: mutable string = ""

  # Linked from session
  customer_id: linked string
    source: @session.customerId
    description: "Customer ID from messaging session"

topic identity_verification:
  description: "Verify customer identity before refund processing"
  reasoning:
    instructions: ->
      if @variables.failed_attempts >= 3:
        | Too many failed attempts. Escalating to human agent.
        transition to @topic.escalation

      if @variables.customer_verified == True:
        | Identity verified. Proceeding to refund assessment.
        transition to @topic.refund_processor

      | Please verify your identity by providing your email address.
    actions:
      verify: @actions.verify_customer
        description: "Verify customer by email"
        set @variables.customer_verified = @outputs.verified

topic refund_processor:
  description: "Process refund based on churn risk assessment"
  reasoning:
    instructions: ->
      # Post-action check (triggers on loop after refund)
      if @variables.refund_status == "Approved":
        run @actions.create_crm_case
          with customer_id = @variables.customer_id
        transition to @topic.success

      # Pre-LLM: Load churn data
      run @actions.get_churn_score
        with customer_id = @variables.customer_id
        set @variables.churn_risk_score = @outputs.score

      # Dynamic instructions based on score
      | Customer churn risk: {!@variables.churn_risk_score}%

      if @variables.churn_risk_score >= 80:
        | HIGH RISK - Offer full cash refund to retain customer.
      else:
        | LOW RISK - Offer $10 store credit as goodwill.
    actions:
      process_refund: @actions.process_refund
        description: "Issue the refund"
        available when @variables.customer_verified == True
        set @variables.refund_status = @outputs.status

topic escalation:
  description: "Escalate to human agent"
  reasoning:
    instructions: |
      Apologize for the inconvenience and transfer to a human agent.
    actions:
      handoff: @utils.escalate
        description: "Transfer to live support"

topic success:
  description: "Successful refund confirmation"
  reasoning:
    instructions: |
      Thank the customer and confirm their refund has been processed.

start_agent topic_selector:
  description: "Entry point - route to identity verification"
  reasoning:
    instructions: |
      Greet the customer and begin identity verification.
    actions:
      start: @utils.transition to @topic.identity_verification
        description: "Begin refund process"

Expression Operators

Comparison Operators

Note: Both <> and != are valid for "not equal" comparisons. Official Salesforce docs and community patterns use both interchangeably.

Logical Operators

Arithmetic Operators

⚠️ NOT supported: * (multiplication), / (division), % (modulo). For complex arithmetic, use a Flow or Apex action.

Access Operators

Conditional Expression (Ternary-like)

| Status: {!@variables.status if @variables.status else "pending"}

Expression Limitations (Sandboxed Python AST Subset)

Agent Script expressions use a sandboxed subset of Python. Not all Python operations are available.

Supported:

NOT Supported:

Apex Complex Type Notation

When action inputs or outputs reference Apex inner classes, use the @apexClassType notation:

@apexClassType/c__OuterClass$InnerClass

Example:

actions:
   process_order:
      inputs:
         line_items: list[object]
            complex_data_type_name: "@apexClassType/c__OrderService$LineItem"
      target: "apex://OrderService"

Note: This notation is used in the complex_data_type_name field of action input/output definitions in Agentforce Assets, not in the .agent file directly.

Common Pitfalls