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

config → variables → system → connection → knowledge → language → start_agent → topic

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

Block Internal Ordering

Within start_agent and topic blocks, sub-blocks follow this order:

description → system → actions → reasoning → after_reasoning

Within a reasoning block:

instructions → actions

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:
  developer_name: "refund_agent"
  agent_description: "Handles refund requests"
  agent_type: "AgentforceServiceAgent"
  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

Action-Only Types (valid for action I/O, NOT for mutable/linked variables):

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. knowledge: Block (Optional)

knowledge:
  knowledge_base: "My_Knowledge_Base"

💡 Knowledge bases are configured in the Salesforce org and referenced by name. The knowledge block enables RAG (Retrieval Augmented Generation) capabilities for the agent.

6. connections: Block (Optional)

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

Connection Types

7. 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"

8. 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

⚠️ else if is NOT supported: Agent Script does not have an else if keyword. Nested if inside else: is also invalid. Use compound conditions (if A and B:) or flatten to sequential if statements.

Multiline String Continuation

Long literal text can span multiple lines using indented continuation:

instructions: |
  | This is a long instruction that
    continues on the next line without a pipe.

The continued line is indented further than the | line and does NOT start with a new |.

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 Metadata Properties (TDD Validated v2.2.0)

Action definitions with target: support the following metadata properties. These are NOT valid on @utils.transition utility actions.

Action-Level:

Input-Level:

Output-Level:

Two-Level Action System

Agent Script uses a two-level system for actions. Understanding this distinction is critical:

Level 1: ACTION DEFINITION (in topic's `actions:` block)
   → Has `target:`, `inputs:`, `outputs:`, `description:`
   → Specifies WHAT to call (e.g., "flow://GetOrderStatus")

Level 2: ACTION INVOCATION (in `reasoning.actions:` block)
   → References Level 1 via `@actions.name`
   → Specifies HOW to call it (`with`, `set` clauses)
   → Does NOT use `inputs:`/`outputs:` (use `with`/`set` instead)

Complete Example:

topic order_lookup:
   description: "Look up order details"

   # Level 1: DEFINE the action (with target + I/O schemas)
   actions:
      get_order:
         description: "Retrieves order information by ID"
         inputs:
            order_id: string
               description: "Customer's order number"
         outputs:
            status: string
               description: "Current order status"
         target: "flow://Get_Order_Details"

   reasoning:
      instructions: |
         Help the customer check their order status.
      # Level 2: INVOKE the action (with/set, NOT inputs/outputs)
      actions:
         lookup: @actions.get_order
            with order_id = ...
            set @variables.order_status = @outputs.status

⚠️ I/O schemas are REQUIRED for publish: Action definitions with only description: and target: (no inputs:/outputs:) will PASS LSP and CLI validation but FAIL server-side compilation with "Internal Error." Always include complete I/O schemas in Level 1 definitions.

Lifecycle Hooks: before_reasoning: and after_reasoning:

Lifecycle hooks enable deterministic pre/post-processing around LLM reasoning. They are FREE (no credit cost).

topic main:
   description: "Topic with lifecycle hooks"

   # BEFORE: Runs deterministically BEFORE LLM sees instructions
   before_reasoning:
      # Content goes DIRECTLY here (NO instructions: wrapper!)
      set @variables.turn_count = @variables.turn_count + 1
      if @variables.needs_redirect == True:
         transition to @topic.redirect

   # LLM reasoning phase
   reasoning:
      instructions: ->
         | Turn {!@variables.turn_count}: How can I help?

   # AFTER: Runs deterministically AFTER LLM finishes reasoning
   after_reasoning:
      # Content goes DIRECTLY here (NO instructions: wrapper!)
      set @variables.interaction_logged = True

Key Rules:

• Content goes directly under the block (NO instructions: wrapper)
• Supports set, if, transition statements
• run does NOT work reliably in lifecycle blocks (use it in reasoning.actions: or instructions: -> instead)
• Both hooks are FREE (no credit cost) — use for data prep, logging, cleanup

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:
  developer_name: "pronto_refund_agent"
  agent_description: "Handles customer refund requests with churn risk assessment"
  agent_type: "AgentforceServiceAgent"
  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: Use != for not-equal comparisons. The <> operator does NOT compile (TDD validated v1.9.0).

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

@inputs in set — Deploy-Breaking Anti-Pattern

# ❌ WRONG — @inputs in set causes unknown error at deploy time
verify: @actions.verify_customer
   with account_number=...
   set @variables.account_number = @inputs.account_number

# ✅ CORRECT — use @utils.setVariables to capture input separately
collect_input: @utils.setVariables
   with account_number=...
verify: @actions.verify_customer
   with account_number=@variables.account_number
   set @variables.customer_name = @outputs.customer_name

Bare Action Names — Always Use @actions. Prefix

# ❌ WRONG — bare names in run, templates, and instructions
run set_user_name
| Use add_to_cart to add items.

# ✅ CORRECT — always prefix with @actions.
run @actions.set_user_name
| Use {!@actions.add_to_cart} to add items.

run @actions.X vs Reasoning-Level Utilities

run @actions.X resolves against the topic-level actions: block (definitions with target:). It does NOT work for reasoning-level utilities like @utils.setVariables.

# ❌ WRONG — set_user_name is defined as @utils.setVariables, not a topic-level action
run @actions.set_user_name   # "Action not found" error

# ✅ CORRECT — use @utils.setVariables directly in reasoning.actions:
reasoning:
   actions:
      set_user_name: @utils.setVariables
         with user_name=...