Sf AI Agentscript

SF-AI-AgentScript Skill

"Prompt engineering is like writing laws in poetry - beautiful, but not enforceable."

Agent Script transforms agent development from prompt-based suggestions to code-enforced guarantees. This skill guides you through writing, debugging, testing, and deploying Agentforce agents using the Agent Script DSL.

⚠️ CRITICAL WARNINGS

API & Version Requirements

MANDATORY Pre-Deployment Checks

1. default_agent_user MUST be valid - Query: SELECT Username FROM User WHERE Profile.Name = 'Einstein Agent User' AND IsActive = true
2. No mixed tabs/spaces - Use consistent indentation (2-space, 3-space, or tabs - never mix)
3. Booleans are capitalized - Use True/False, not true/false
4. Exactly one start_agent block - Multiple entry points cause compilation failure

⛔ SYNTAX CONSTRAINTS (Validated via Testing + Official Spec)

🔴 Reserved Field Names (Breaking in Recent Releases)

Common field names that cause parse errors when used as variable or I/O field names:

❌ RESERVED as variable/field names:
description, label, is_required, is_displayable, is_used_by_planner

✅ WORKAROUNDS for variable/field names:
description  → descriptions, description_text, desc_field
label        → label_text, display_label, label_field

Important distinction (TDD v2.2.0): is_required, is_displayable, is_used_by_planner, and label are reserved as variable/field names but are valid as action I/O metadata properties. For example, you cannot name a variable label, but you CAN use label: as a property on an action definition, input, or output. See "Action I/O Metadata Properties" below.

🔴 Feature Validity by Context (TDD Validated v2.2.0)

Key distinction: Many action metadata properties are valid on action definitions with targets (flow://, apex://) but NOT on utility actions (@utils.transition). The v1.3.0 finding that tested only @utils.transition was too narrow — v2.2.0 corrects this.

What works on @utils.transition actions:

actions:
   go_next: @utils.transition to @topic.next
      description: "Navigate to next topic"   # ✅ ONLY description works

What works on action definitions with target::

actions:
   process_order:
      label: "Process Order"                            # ✅ Display label
      description: "Process the customer's order"       # ✅ LLM description
      require_user_confirmation: True                   # ✅ Compiles (runtime Issue 6)
      include_in_progress_indicator: True               # ✅ Shows spinner
      progress_indicator_message: "Processing..."       # ✅ Custom spinner message
      inputs:
         order_id: string
            label: "Order ID"                           # ✅ I/O display label
            description: "The order identifier"
      outputs:
         status: string
            label: "Order Status"                       # ✅ I/O display label
            description: "Current order status"
      target: "apex://OrderProcessor"

🔴 complex_data_type_name Mapping Table (Critical for Actions)

"#1 source of compile errors" - Use this table when defining action inputs/outputs in Agentforce Assets.

Agent Script → Lightning Type Mapping (TDD Validated v2.1.0):

Use this when troubleshooting type errors between Agent Script action I/O and Apex/Flow targets.

Pro Tip: Don't manually edit complex_data_type_name - use the UI dropdown in Agentforce Assets > Action Definition, then export/import the action definition.

⚠️ Canvas View Corruption Bugs

CRITICAL: Canvas view can silently corrupt Agent Script syntax. Make complex edits in Script view.

Safe Workflow:

1. Use Script view for all structural edits (conditionals, actions, transitions)
2. Use Canvas only for visual validation and simple text changes
3. Always review in Script view after any Canvas edit

⚠️ Preview Mode Critical Bugs

CRITICAL REFRESH BUG: Browser refresh required after every Agent Script save before preview works properly.

Pattern for Testing Linked Variables:

# ❌ DOESN'T WORK IN PREVIEW (linked var from session):
RoutableId: linked string
   source: @MessagingSession.Id

# ✅ WORKAROUND FOR TESTING (hardcode value):
RoutableId: mutable string = "test-session-123"
   description: "MessagingSession Id (hardcoded for testing)"

# After testing, switch back to linked for production

Output Property Access Pattern:

# ❌ DOESN'T WORK IN PREVIEW (direct output access):
if @actions.check_status.result == "approved":
   | Approved!

# ✅ CORRECT (assign to variable first):
set @variables.status = @outputs.result
if @variables.status == "approved":
   | Approved!

if/else Nesting Rules — Two Valid Approaches

# ❌ WRONG - `else if` is NOT valid syntax
if @variables.tier == "gold":
   | Gold tier detected.
else if @variables.tier == "silver":    # SyntaxError!
   | Silver tier detected.

# ❌ WRONG - Direct nested if inside if (no else:) causes SyntaxError
if @variables.software_cost > 0:
   if @variables.software_cost <= 500:   # SyntaxError!
      | Auto-approve this software request.

# ❌ WRONG - else: with nested if ALSO causes SyntaxError (TDD validated 2026-02-14)
if @variables.is_member == True:
   | Welcome back, member!
else:
   if @variables.visit_count > 5:       # SyntaxError: Unexpected 'if'
      | Welcome back, frequent visitor!

# ✅ CORRECT Approach 1 - Compound condition (when logic allows)
if @variables.software_cost > 0 and @variables.software_cost <= 500:
   | Auto-approve this software request.

# ✅ CORRECT Approach 2 - Flatten to sequential ifs (for separate messages)
if @variables.order_verified == False or @variables.payment_confirmed == False:
   | ❌ **PROCESSING BLOCKED**
   | Missing requirements:

if @variables.order_verified == False:
   | - Order verification pending

if @variables.payment_confirmed == False:
   | - Payment confirmation pending

Summary: else if is NOT valid. Direct if inside if is NOT valid. else: with nested if is also NOT valid (TDD disproved 2026-02-14). Use compound conditions for multi-branch logic, or flatten to sequential ifs for separate outputs.

... is Slot-Filling Syntax (LLM Extracts from Conversation)

# ❌ WRONG - Using ... as default value
order_id: mutable string = ...

# ✅ CORRECT - Use ... only in action parameter binding
reasoning:
   actions:
      search: @actions.search_products
         with query=...           # LLM extracts from user message
         with category=...        # LLM decides based on context
         with limit=10            # Fixed value

Post-Action Directives: Only on @actions.*

# ❌ WRONG - @utils does NOT support set/run/if
go_next: @utils.transition to @topic.main
   set @variables.visited = True   # ERROR!

# ✅ CORRECT - Only @actions.* supports post-action
process: @actions.process_order
   with order_id=@variables.order_id
   set @variables.status = @outputs.status        # ✅ Works
   run @actions.send_notification                 # ✅ Works
   if @outputs.needs_review:                      # ✅ Works
      transition to @topic.review

Helper Topic Pattern (For Demo Agents Without Flows/Apex)

When you need to set variables without backend actions, use dedicated "helper topics":

# Main topic offers LLM-selectable action
topic verify_employee:
   reasoning:
      actions:
         complete_verification: @utils.transition to @topic.verification_success
            description: "Mark employee as verified"
            available when @variables.employee_verified == False

# Helper topic sets variables in instructions, then returns
topic verification_success:
   description: "Set verified state and return"
   reasoning:
      instructions: ->
         set @variables.employee_verified = True
         set @variables.employee_name = "Demo Employee"
         | ✓ Identity verified!
         transition to @topic.verify_employee  # Return to parent

Why this works: set statements ARE valid inside instructions: -> blocks. The topic loop pattern lets you change state without Flows/Apex.

💰 PRODUCTION GOTCHAS: Billing, Determinism & Performance

Credit Consumption Table

Key insight: Framework operations are FREE. Only actions that invoke external services consume credits.

✅ Lifecycle Hooks Validated (v1.3.0): The before_reasoning: and after_reasoning: lifecycle hooks are now TDD-validated. Content goes directly under the block (no instructions: wrapper). See "Lifecycle Hooks" section below for correct syntax.

Cost Optimization Pattern: Fetch data once in before_reasoning:, cache in variables, reuse across topics.

Lifecycle Hooks: before_reasoning: and after_reasoning:

TDD Validated (2026-01-20): These hooks enable deterministic pre/post-processing around LLM reasoning.

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.pre_processed = True
      set @variables.customer_tier = "gold"

   # LLM reasoning phase
   reasoning:
      instructions: ->
         | Customer tier: {!@variables.customer_tier}
         | How can I help you today?

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

Key Points:

• Content goes directly under before_reasoning: / after_reasoning: (NO instructions: wrapper)
• Supports set, if, run statements (same as procedural instructions: ->)
• before_reasoning: is FREE (no credit cost) - use for data prep
• after_reasoning: is FREE (no credit cost) - use for logging, cleanup

❌ WRONG Syntax (causes compile error):

before_reasoning:
   instructions: ->      # ❌ NO! Don't wrap with instructions:
      set @variables.x = True

✅ CORRECT Syntax:

before_reasoning:
   set @variables.x = True   # ✅ Direct content under the block

Supervision vs Handoff (Clarified Terminology)

# HANDOFF - child topic takes over completely:
checkout: @utils.transition to @topic.order_checkout
   description: "Proceed to checkout"
# → @topic.order_checkout generates the user-facing response

# SUPERVISION - parent remains in control:
get_advice: @topic.product_expert
   description: "Consult product expert"
# → @topic.product_expert returns, parent topic synthesizes final response

KNOWN BUG: Adding ANY new action in Canvas view may inadvertently change Supervision references to Handoff transitions.

Action Output Flags for Zero-Hallucination Routing

Key Pattern for Determinism: Control what the LLM can see and say.

When defining actions in Agentforce Assets, use these output flags:

Zero-Hallucination Intent Classification Pattern:

# In Agentforce Assets - Action Definition outputs:
outputs:
   intent_classification: string
      is_displayable: False       # LLM cannot show this to user
      is_used_by_planner: True    # LLM can use for routing decisions

# In Agent Script - LLM routes but cannot hallucinate:
topic intent_router:
   reasoning:
      instructions: ->
         run @actions.classify_intent
         set @variables.intent = @outputs.intent_classification

         if @variables.intent == "refund":
            transition to @topic.refunds
         if @variables.intent == "order_status":
            transition to @topic.orders

Action I/O Metadata Properties (TDD Validated v2.2.0)

Complete reference for all metadata properties available on action definitions, inputs, and outputs. These control how the LLM and UI interact with action parameters.

Action-Level Properties:

Input Properties:

Output Properties:

Cross-reference: filter_from_agent: True (in actions-reference.md) is equivalent to is_displayable: False. Both hide the output from user display. is_displayable is the standard property name.

User Input Pattern (is_user_input: True):

# LLM extracts the value from conversation context rather than asking explicitly
inputs:
   customer_name: string
      description: "Customer's full name"
      is_user_input: True    # LLM pulls from what user already said
      is_required: True      # Must have a value before action executes

Action Chaining with run Keyword

Known quirk: Parent action may complain about inputs needed by chained action - this is expected.

# Chained action execution:
process_order: @actions.create_order
   with customer_id = @variables.customer_id
   run @actions.send_confirmation        # Chains after create_order completes
   set @variables.order_id = @outputs.id

KNOWN BUG: Chained actions with Prompt Templates don't properly map inputs using Input:Query format:

# ❌ MAY NOT WORK with Prompt Templates:
run @actions.transform_recommendation
   with "Input:Reco_Input" = @variables.ProductReco

# ⚠️ TRY THIS (may still have issues):
run @actions.transform_recommendation
   with Reco_Input = @variables.ProductReco

📖 For prompt template action definitions, input binding syntax, and grounded data patterns, see resources/action-prompt-templates.md. For context-aware descriptions, instruction references ({!@actions.X}), and advanced binding strategies, see resources/action-patterns.md.

Latch Variable Pattern for Topic Re-entry

Problem: Topic selector doesn't properly re-evaluate after user provides missing input.

Solution: Use a "latch" variable to force re-entry:

variables:
   verification_in_progress: mutable boolean = False

start_agent topic_selector:
   reasoning:
      instructions: ->
         # LATCH CHECK - force re-entry if verification was started
         if @variables.verification_in_progress == True:
            transition to @topic.verification

         | How can I help you today?
      actions:
         start_verify: @topic.verification
            description: "Start identity verification"
            # Set latch when user chooses this action
            set @variables.verification_in_progress = True

topic verification:
   reasoning:
      instructions: ->
         | Please provide your email to verify your identity.
      actions:
         verify: @actions.verify_identity
            with email = ...
            set @variables.verified = @outputs.success
            # Clear latch when verification completes
            set @variables.verification_in_progress = False

Loop Protection Guardrail

Agent Scripts have a built-in guardrail that limits iterations to approximately 3-4 loops before breaking out and returning to the Topic Selector.

Best Practice: Map out your execution paths - particularly topic transitions. Ensure testing covers all paths and specifically check for unintended circular references between topics.

Token & Size Limits

Progress Indicators

Add user feedback during long-running actions:

actions:
   fetch_data: @actions.get_customer_data
      description: "Fetch customer information"
      include_in_progress_indicator: True
      progress_indicator_message: "Fetching your account details..."

VS Code Pull/Push NOT Supported

# ❌ ERROR when using source tracking:
Failed to retrieve components using source tracking:
[SfError [UnsupportedBundleTypeError]: Unsupported Bundle Type: AiAuthoringBundle

# ✅ WORKAROUND - Use CLI directly:
sf project retrieve start -m AiAuthoringBundle:MyAgent
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG

Language Block Quirks

• Hebrew and Indonesian appear twice in the language dropdown
• Selecting from the second set causes save errors
• Use adaptive_response_allowed: True for automatic language adaptation

language:
   locale: en_US
   adaptive_response_allowed: True  # Allow language adaptation

Cross-Skill Orchestration

Tip: Open Agentforce Studio list view with sf org open authoring-bundle -o TARGET_ORG (v2.121.7+). Open a specific agent with sf org open agent --api-name MyAgent -o TARGET_ORG.

📋 QUICK REFERENCE: Agent Script Syntax

Block Structure (CORRECTED Order per Official Spec)

config:        # 1. Required: Agent metadata (developer_name, agent_type, default_agent_user)
variables:     # 2. Optional: State management (mutable/linked)
system:        # 3. Required: Global messages and instructions
connection:    # 4. Optional: Escalation routing — use `connection messaging:` (singular, NOT `connections:`)
knowledge:     # 5. Optional: Knowledge base config
language:      # 6. Optional: Locale settings
start_agent:   # 7. Required: Entry point (exactly one)
topic:         # 8. Required: Conversation topics (one or more)

Config Block Field Names (CRITICAL)

⚠️ Common Error: Using incorrect field names from outdated documentation.

# ✅ CORRECT config block:
config:
  developer_name: "my_agent"
  agent_description: "Handles customer support inquiries"
  agent_type: "AgentforceServiceAgent"
  default_agent_user: "agent_user@00dxx000001234.ext"

Naming Rules (All Identifiers)

• Only letters, numbers, underscores
• Must begin with a letter
• No spaces, no consecutive underscores, cannot end with underscore
• Maximum 80 characters

Instruction Syntax Patterns

Transition vs Delegation (CRITICAL DISTINCTION)

# Delegation - returns to current topic after specialist finishes
consulting: @topic.expert_topic
   description: "Get expert advice"

# Transition - permanent handoff, no return
checkout: @utils.transition to @topic.checkout
   description: "Proceed to purchase"

Expression Operators (Safe Subset)

Variable Types

⚠️ Linked variables CANNOT use object or list types

Linked Variable Sources by Agent Type

⚠️ CRITICAL: Not all source bindings work for all agent types.

Workaround for Employee Agents: Employee Agents in the Copilot panel don't automatically receive record context. Use a mutable variable and have the Flow action look up the current record.

# ❌ DOESN'T WORK for Employee Agents:
case_id: linked string
   source: @Record.Id

# ✅ WORKAROUND - use mutable variable:
case_id: mutable string = ""
   description: "Case ID - enter or will be looked up by Flow"

Variable vs Action I/O Type Matrix

Critical distinction: Some types are valid ONLY for action inputs/outputs, NOT for Agent Script variables.

Source: AGENT_SCRIPT.md rules document from trailheadapps/agent-script-recipes

Action Target Protocols

Legend: ✅ TDD = Validated via deployment testing | 📋 Spec = Documented in AGENT_SCRIPT.md spec (requires specific org setup to test)

Using Flow and Apex Actions in Agent Script

For AiAuthoringBundle (Agent Script): flow:// and apex:// targets work directly — no GenAiFunction registration needed. The target just needs to exist in the org (active Flow or deployed Apex class with @InvocableMethod).

Two-Level Action System (CRITICAL to understand):

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

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

Complete Example:

topic order_status:
   description: "Look up order details"

   # Level 1: DEFINE the action with a target
   actions:
      get_case_details:
         description: "Fetch case information by ID"
         inputs:
            case_id: string
               description: "The Case record ID"
         outputs:
            subject: string
               description: "Case subject line"
         target: "flow://Get_Case_Details"   # Flow must exist and be active

   reasoning:
      instructions: |
         Help the customer check their case status.
      # Level 2: INVOKE the action defined above
      actions:
         lookup_case: @actions.get_case_details
            with case_id = @variables.case_id
            set @variables.case_subject = @outputs.subject

⚠️ PRODUCTION INSIGHT: 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 action definitions. Specifically, the outputs: block is required — having inputs: but no outputs: still triggers the Internal Error (TDD v2.1.0: Val_No_Outputs).

This was previously misattributed to a "flow:// target bug." The actual root cause is missing type contracts — adding inputs: and outputs: blocks resolves the issue for both flow:// and apex:// targets.

⚠️ Level 1 Without Level 2 Is Valid (TDD v2.1.0)

You do NOT need a Level 2 @actions.X invocation for every Level 1 action definition. Defining an action in the topic's actions: block with target:, inputs:, outputs: is sufficient — the LLM auto-selects from available actions based on their descriptions. Val_Level1_Only published successfully with ONLY Level 1 definitions.

I/O Name Matching Rules (TDD Validated v2.1.0):

Action input/output names in Agent Script MUST exactly match the @InvocableVariable field names in the Apex target.

Bare @InvocableMethod Pattern (NOT Compatible with Agent Script):

⚠️ CRITICAL: Apex methods returning List<String> directly (without @InvocableVariable wrapper classes) CANNOT be used as Agent Script action targets. The framework has no discoverable parameter names to bind against.

// ❌ DOES NOT WORK with Agent Script:
@InvocableMethod
public static List<String> greet(List<String> names) { ... }
// → No input name is discoverable — "name", "input", "names" all fail

// ✅ ALWAYS use wrapper classes for Agent Script:
public class GreetInput {
    @InvocableVariable(label='Name' required=true)
    public String userName;    // ← Agent Script uses "userName" as input name
}
public class GreetOutput {
    @InvocableVariable(label='Greeting')
    public String greeting;    // ← Agent Script uses "greeting" as output name
}
@InvocableMethod
public static List<GreetOutput> greet(List<GreetInput> inputs) { ... }

Partial Output Pattern:

You can declare a SUBSET of the target's outputs in your Agent Script action definition. You do NOT need to declare every output field from the Apex class. Val_Partial_Output confirmed: declaring only outputText from TestApexAction (which has a full output wrapper) publishes successfully.

⚠️ Common Error: ValidationError: Tool target 'X' is not an action definition — This means either:

1. The action is referenced in reasoning.actions: via @actions.X but X is not defined in the topic's actions: block, OR
2. The target: value points to a Flow/Apex class that doesn't exist in the org

Fix: Ensure you have BOTH levels: action definition (with target:) AND action invocation (with @actions.name).

Agent Builder UI Path (GenAiPlannerBundle — different workflow): If building agents through the Agent Builder UI (not Agent Script), you DO need GenAiFunction metadata. See resources/actions-reference.md for details.

Connection Block (Escalation Routing — Beta Feature)

⚠️ Service Agents Only: The connection block is only valid for agent_type: "AgentforceServiceAgent". Employee Agents do not support channel-based escalation routing.

⚠️ CRITICAL SYNTAX: Use connection messaging: (singular, NO wrapper block). The connections: (plural) wrapper from some docs/recipes does NOT compile. Each connection <channel>: is a standalone top-level block.

⚠️ outbound_route_name requires flow:// prefix: Using a bare Flow API name (e.g., "My_Flow") causes ERROR_HTTP_404 on publish. Must use "flow://My_Flow" format.

Minimal form (no routing — just enables the channel):

connection messaging:
   adaptive_response_allowed: True

Full form with escalation routing (production-validated on Vivint-DevInt, 2026-02-16):

connection messaging:
   outbound_route_type: "OmniChannelFlow"
   outbound_route_name: "flow://Route_from_Vivint_Virtual_Support"
   escalation_message: "One moment while I connect you with a support specialist."
   adaptive_response_allowed: False

All-or-nothing rule: When outbound_route_type is present, ALL three route properties are required (outbound_route_type, outbound_route_name, escalation_message). Omitting any one causes validation failure.

Key Properties:

…(truncated)