113 Syntax Db87a372

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"

Common Pitfalls