afv-library/skills/developing-agentforce/references/instruction-resolution.md

Instruction Resolution

How Agent Script instructions are processed at runtime: from static text to dynamic LLM prompts.

---

1. Three Phases of Instruction Resolution

Agent Script instructions go through three distinct phases at runtime. Understanding these phases is critical for writing effective instructions and debugging unexpected behavior.

Phase 1: Pre-LLM Setup
   (deterministic -- runs before the LLM sees anything)
       |
       v
Phase 2: LLM Reasoning
   (non-deterministic -- LLM processes the assembled prompt)
       |
       v
Phase 3: Post-Action Loop
   (deterministic -- runs after an action completes, then loops back to Phase 1)

---

2. Phase 1: Pre-LLM Resolution

During Phase 1, the Agent Script runtime evaluates deterministic constructs in instructions: -> blocks. This happens BEFORE the LLM sees any text.

What Happens in Phase 1

1. if/else evaluation: Conditions are evaluated against current variable values. Only the matching branch is included in the prompt.
2. Variable injection: {!@variables.X} tokens are replaced with current values.
3. run execution: Deterministic run @actions.X calls execute and their outputs are captured.
4. set execution: Variable assignments execute immediately.
5. transition to: If reached, the topic switch happens immediately (LLM is never called).

Phase 1 Example

Given this instruction block:

reasoning:
   instructions: ->
      # 1. Post-action check (from previous loop)
      if @variables.refund_approved == True:
         | Your refund has been processed. Reference: {!@variables.refund_id}
         transition to @topic.confirmation

      # 2. Pre-LLM data loading
      if @variables.data_loaded == False:
         run @actions.load_customer_profile
            with customer_id = @variables.customer_id
            set @variables.risk_score = @outputs.risk_score
            set @variables.tier = @outputs.tier
         set @variables.data_loaded = True

      # 3. Dynamic instructions
      | Customer tier: {!@variables.tier}, Risk score: {!@variables.risk_score}

      if @variables.risk_score >= 80:
         | HIGH RISK -- Offer full cash refund to retain this customer.
         | Do NOT offer store credit. Prioritize retention.

      if @variables.risk_score < 80:
         | STANDARD -- Offer $10 store credit as goodwill.
         | Only escalate to cash refund if customer insists.

First turn resolution (variables at defaults):

• refund_approved == True -> False. Skip this block.
• data_loaded == False -> True. Execute run @actions.load_customer_profile. Variables now set.
• Set data_loaded = True.
• Inject {!@variables.tier} -> "gold", {!@variables.risk_score} -> 85.
• risk_score >= 80 -> True. Include high-risk instructions.
• risk_score < 80 -> False. Skip standard instructions.

What the LLM actually sees:

Customer tier: gold, Risk score: 85
HIGH RISK -- Offer full cash refund to retain this customer.
Do NOT offer store credit. Prioritize retention.

---

3. Phase 2: LLM Processing

In Phase 2, the LLM receives the assembled prompt and produces a response. The LLM sees:

The 4-Message Prompt Structure

The Agent Script runtime assembles a 4-message prompt for the LLM:

#	Message Role	Content Source	Purpose
1	System	system: instructions: + agent metadata	Global persona, safety rules, capabilities
2	System	topic: reasoning: instructions: (resolved from Phase 1)	Topic-specific operating instructions
3	User/Assistant	Conversation history (all turns)	Context for the current request
4	System	Available actions + their descriptions	Tool palette the LLM can choose from

What the LLM Decides

Based on the assembled prompt, the LLM:

1. Selects an action (if applicable) from the available actions list
2. Fills slot parameters (... values) from conversation context
3. Generates a text response to send to the user
4. Decides whether to transition (if a transition action is available and appropriate)

What the LLM Does NOT See

• Raw if/else blocks (already resolved in Phase 1)
• run statements (already executed in Phase 1)
• set statements (already executed)
• available when conditions (already evaluated -- hidden actions are simply absent)
• after_reasoning blocks (run after the LLM, not shown to it)

---

4. Phase 3: Post-Action Loop

After the LLM selects and executes an action, the system loops back to Phase 1 for re-resolution. This is the post-action loop pattern described in the SKILL.md architecture section.

Loop Sequence

1. Phase 1 resolves instructions (first time)
2. Phase 2: LLM reasons and selects an action
3. Action executes -> outputs captured in variables
4. Phase 1 re-resolves instructions (with updated variables)
   - Post-action checks at TOP of instructions fire
   - New data is injected into the prompt
5. Phase 2: LLM reasons again with updated context
6. Repeat until: transition, escalation, or no action selected

Why Post-Action Checks Go at the TOP

Place post-action checks at the TOP of instructions: -> so they fire immediately on re-resolution:

reasoning:
   instructions: ->
      # POST-ACTION CHECK (at TOP -- fires on re-resolution)
      if @variables.order_cancelled == True:
         | Your order has been cancelled successfully.
         transition to @topic.confirmation

      # These instructions are for the FIRST entry (before action runs)
      | I can help you cancel your order.
      | What is your order number?

If the check were at the BOTTOM, the LLM would see the "ask for order number" instructions again even after the cancellation succeeded, causing confusion.

---

5. Recommended Instruction Order

Within a instructions: -> block, follow this order for maximum clarity:

reasoning:
   instructions: ->
      # 1. POST-ACTION CHECKS (deterministic transitions)
      if @variables.action_completed == True:
         transition to @topic.next_step

      # 2. PRE-LLM DATA LOADING (deterministic actions)
      if @variables.data_needed == True:
         run @actions.load_data
            with id = @variables.record_id
            set @variables.loaded_data = @outputs.result

      # 3. CONDITIONAL INSTRUCTIONS (based on state)
      if @variables.is_verified == True:
         | Full access granted. You can:
         | - View account details
         | - Make changes
         | - Request refunds

      if @variables.is_verified == False:
         | Please verify your identity first.
         | I need your email address and order number.

      # 4. STATIC INSTRUCTIONS (always included)
      | Be concise and professional.
      | Always confirm before making changes.

---

6. Common Instruction Patterns

Pattern 1: Security Gate

Prevent access to sensitive actions until identity is verified:

reasoning:
   instructions: ->
      if @variables.is_verified == False:
         | You must verify your identity before I can help with account changes.
         | Please provide your email address.

      if @variables.is_verified == True:
         | Identity verified. I can now help with account changes.
         | What would you like to do?

   actions:
      update_account: @actions.update_account_info
         description: "Update account information"
         available when @variables.is_verified == True
         with field = ...
         with value = ...

The available when guard hides the action from the LLM until verification passes. The conditional instructions tell the user what to do.

Pattern 2: Data-Dependent Instructions

Load data first, then tailor instructions based on the result:

reasoning:
   instructions: ->
      run @actions.get_account_status
         with account_id = @variables.account_id
         set @variables.account_status = @outputs.status
         set @variables.balance = @outputs.balance

      | Account status: {!@variables.account_status}
      | Current balance: {!@variables.balance}

      if @variables.account_status == "delinquent":
         | IMPORTANT: This account is delinquent.
         | Collect payment before processing any other requests.
         | Offer payment plan options if customer cannot pay in full.

      if @variables.account_status == "active":
         | This account is in good standing.
         | Process requests normally.

Pattern 3: Action Chaining

Execute one action, then use its output to drive the next:

reasoning:
   instructions: ->
      # Post-action check: case was created in previous loop
      if @variables.case_id != "":
         | Case {!@variables.case_id} has been created.
         run @actions.assign_case
            with case_id = @variables.case_id
            with priority = @variables.priority
         transition to @topic.case_confirmation

      | I need to collect some information to create a support case.
      | What is the issue you're experiencing?

Pattern 4: Multi-Condition Routing

Route based on multiple variable values:

reasoning:
   instructions: ->
      if @variables.intent == "billing" and @variables.is_verified == True:
         | I can help with your billing question.
         transition to @topic.billing_support

      if @variables.intent == "billing" and @variables.is_verified == False:
         | For billing questions, I need to verify your identity first.
         transition to @topic.identity_verification

      if @variables.intent == "general":
         | How can I help you today?

---

7. Anti-Patterns to Avoid

Anti-Pattern 1: Nested If Blocks

# WRONG -- Agent Script does not support nested if or else if
if @variables.tier == "gold":
   if @variables.is_verified == True:
      | VIP treatment
   else:
      | Verify first

# CORRECT -- Use compound conditions
if @variables.tier == "gold" and @variables.is_verified == True:
   | VIP treatment

if @variables.tier == "gold" and @variables.is_verified == False:
   | Verify first

Anti-Pattern 2: Post-Action Check at Bottom

# WRONG -- Check at bottom; LLM sees stale instructions on re-resolution
reasoning:
   instructions: ->
      | What is your order number?

      if @variables.order_status != "":
         transition to @topic.show_status

# CORRECT -- Check at TOP
reasoning:
   instructions: ->
      if @variables.order_status != "":
         transition to @topic.show_status

      | What is your order number?

Anti-Pattern 3: Persona in Topic Instructions

# WRONG -- Persona text duplicated in every topic
reasoning:
   instructions: |
      You are a friendly, professional customer service agent.
      Help the customer with their order.

# CORRECT -- Persona in system instructions, topic has operational instructions only
system:
   instructions: |
      You are a friendly, professional customer service agent.

topic order_support:
   reasoning:
      instructions: ->
         | Help the customer check their order status.
         | Ask for the order number if not provided.

Anti-Pattern 4: Using | When -> Is Needed

# WRONG -- Using literal mode when conditionals are needed
reasoning:
   instructions: |
      if @variables.is_verified == True:
         Show account details.

# The above sends the literal text "if @variables.is_verified == True:" to the LLM!

# CORRECT -- Use procedural mode for conditionals
reasoning:
   instructions: ->
      if @variables.is_verified == True:
         | Show account details.

Anti-Pattern 5: Missing Variable Injection Syntax

# WRONG -- Variable name as literal text
reasoning:
   instructions: ->
      | Your order ID is @variables.order_id

# CORRECT -- Use injection syntax
reasoning:
   instructions: ->
      | Your order ID is {!@variables.order_id}

Anti-Pattern 6: run Inside after_reasoning

While run compiles inside after_reasoning:, its runtime behavior is inconsistent across bundle types. Prefer using run in reasoning: instructions: -> or reasoning: actions: instead.

# RISKY -- run in after_reasoning has inconsistent behavior
after_reasoning:
   run @actions.log_event
      with event = "turn_completed"

# SAFER -- Use instructions: -> for deterministic runs
reasoning:
   instructions: ->
      # Post-action logging
      if @variables.last_action != "":
         run @actions.log_event
            with event = @variables.last_action

---

8. Syntax Patterns Reference

Literal Mode (|)

Static text passed directly to the LLM. No evaluation occurs:

instructions: |
   Help the customer with their order.
   Be professional and concise.

Or with the | prefix on each line (inside procedural mode):

instructions: ->
   | Help the customer with their order.
   | Be professional and concise.

Procedural Mode (->)

Enables conditionals, variable injection, and deterministic actions:

instructions: ->
   if @variables.condition == True:
      | Text shown when condition is true.
   else:
      | Text shown when condition is false.

Variable Injection

| Your order {!@variables.order_id} is {!@variables.status}.

Deterministic Run

run @actions.load_data
   with param = @variables.value
   set @variables.result = @outputs.field

Deterministic Set

set @variables.counter = @variables.counter + 1

Deterministic Transition

transition to @topic.next_topic

Conditional Transition

if @variables.all_collected == True:
   transition to @topic.confirmation

---

9. Programmatic Trace Access

To verify how instructions were resolved at runtime, use the trace files generated by sf agent preview.

Trace File Location

.sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json

Reading Instruction Resolution from Traces

# Extract the resolved instructions that the LLM received
jq -r '.planTrace.steps[] | select(.type == "LLM_STEP") | .input' \
  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json

# Extract the LLM's response
jq -r '.planTrace.steps[] | select(.type == "LLM_STEP") | .output' \
  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json

# Check which variables were set during resolution
jq -r '.planTrace.steps[] | select(.type == "ACTION_STEP") | {name: .name, pre: .preVars, post: .postVars}' \
  ~/.sf/sfdx/agents/MyAgent/sessions/*/traces/*.json

Verifying Phase 1 Resolution

To confirm that if/else blocks resolved correctly, compare the trace's LLM_STEP input against your instructions: -> block. The LLM input should contain only the branches that matched, with all {!@variables.X} tokens replaced with actual values.

If the trace shows unexpected instruction text:

1. Check that you used -> mode (not | mode) when conditionals are present
2. Verify variable values at the time of resolution (check preVars on preceding ACTION_STEP)
3. Confirm that if conditions use the correct comparison operators

Using STDM for Production Trace Analysis

For production agents, use the Session Trace Data Model (STDM) in Data Cloud to access trace data programmatically. The STDM captures LLM_STEP records with input and output fields that contain the resolved prompt and LLM response. This is useful for auditing instruction resolution at scale across hundreds of live sessions.

---

10. Resolution Across Topic Transitions

When a topic transition occurs (via @utils.transition to @topic.X or transition to @topic.X), instruction resolution starts fresh in the new topic:

1. The current topic's remaining instructions are NOT processed
2. The new topic's before_reasoning: runs (if present)
3. The new topic's reasoning: instructions: resolves from Phase 1
4. The LLM receives the new topic's assembled prompt

Important: Variables persist across transitions. A variable set in Topic A is available in Topic B. This is how you pass data between topics:

# Topic A: Collect data
topic collect_info:
   reasoning:
      instructions: ->
         | Please provide your order number.
      actions:
         capture_order: @actions.get_order_id
            with input = ...
            set @variables.order_id = @outputs.order_id

   after_reasoning:
      if @variables.order_id != "":
         transition to @topic.process_order

# Topic B: Use the data
topic process_order:
   reasoning:
      instructions: ->
         # order_id is available from Topic A
         | Processing order {!@variables.order_id}...
         run @actions.get_order_details
            with order_id = @variables.order_id
            set @variables.order_status = @outputs.status