Actions Reference

Actions Reference

Migrated from the former sf-ai-agentforce-legacy/docs/actions-reference.md on 2026-02-07. For context-aware descriptions, instruction references, and input binding patterns, see action-patterns.md. For prompt template actions (generatePromptResponse://), see action-prompt-templates.md.

Complete guide to Agent Actions in Agentforce: Flow, Apex, API actions, escalation routing, and GenAiFunction metadata.

Action Properties Reference

All actions in Agent Script support these properties:

Action Definition Properties

Note: label, require_user_confirmation, include_in_progress_indicator, and progress_indicator_message are valid on action definitions with target: but NOT on @utils.transition utility actions (see Val_Action_Properties vs Val_Action_Meta_Props).

Input Properties (TDD Validated v2.2.0)

Output Properties (Updated v2.2.0)

is_displayable vs filter_from_agent: Both control the same behavior. is_displayable: False is the standard property name (used in SKILL.md and zero-hallucination patterns). filter_from_agent: True is an older alias that achieves the same result.

Example with All Properties

actions:
   process_payment:
      description: "Processes payment for the order"
      require_user_confirmation: True    # Ask user before executing
      include_in_progress_indicator: True
      inputs:
         amount: number
            description: "Payment amount"
         card_token: string
            description: "Tokenized card number"
      outputs:
         transaction_id: string
            description: "Transaction reference"
         card_last_four: string
            description: "Last 4 digits of card"
            filter_from_agent: True     # Hide from LLM context
      target: "flow://Process_Payment"
      available_when: @variables.cart_total > 0

Action Target Types (Complete Reference)

AgentScript supports 22+ action target types. Use the correct protocol for your integration:

Target Format: <type>://<DeveloperName> (e.g., flow://Get_Account_Info, standardInvocableAction://sendEmail)

Common Examples:

# Flow action (most common)
target: "flow://Get_Customer_Orders"

# Apex action
target: "apex://CustomerServiceController"

# Prompt template
target: "generatePromptResponse://Email_Draft_Template"

# Standard invocable action (built-in Salesforce)
target: "standardInvocableAction://sendEmail"

# External service (API call)
target: "externalService://Stripe_Payment_API"

Tip: Before creating a custom Flow, check if a standardInvocableAction:// already exists for your use case.

Action Invocation Methods

Deployment Method Capabilities

run keyword IS supported in reasoning.actions: post-action blocks and instructions: -> blocks (Validated Jan 2026)

# ✅ WORKS — run in reasoning.actions post-action block
create: @actions.create_order
   with customer_id = @variables.customer_id
   run @actions.send_confirmation     # ✅ Chains after create_order
   set @variables.order_id = @outputs.id

# ✅ WORKS — run in instructions: -> block
reasoning:
   instructions: ->
      run @actions.load_customer
         with id = @variables.customer_id
         set @variables.name = @outputs.name

# ❌ DOES NOT WORK — run in before_reasoning (no LLM context)
before_reasoning:
   run @actions.log_turn    # ❌ May not execute as expected

Note: The Dec 2025 finding that run was "NOT supported" has been superseded. As of Jan 2026, run works in post-action chains and procedural instruction blocks. It does NOT work reliably in before_reasoning:.

{!@actions.name} interpolation in instructions (Updated Feb 2026)

The {!@actions.action_name} syntax embeds a reference to the full action definition into reasoning instructions. This gives the LLM richer context about available actions.

# ✅ WORKS — reference action in instructions for guided selection
reasoning:
   instructions: ->
      | To look up an order, use {!@actions.get_order}.
      | To check shipping status, use {!@actions.track_shipment}.

Note: The Dec 2025 finding that this was broken has been superseded. See action-patterns.md for detailed usage patterns and examples.

Correct Approach: Use reasoning.actions Block

The LLM automatically selects appropriate actions from those defined in the reasoning.actions block:

topic order_management:
   description: "Handles order inquiries"

   actions:
      get_order:
         description: "Retrieves order information"
         inputs:
            order_id: string
               description: "The order ID"
         outputs:
            status: string
               description: "Order status"
         target: "flow://Get_Order_Details"

   reasoning:
      instructions: ->
         | Help the customer with their order.
         | When they ask about an order, look it up.
      actions:
         # LLM automatically selects this when appropriate
         lookup: @actions.get_order
            with order_id=...
            set @variables.order_status = @outputs.status

Action Type 1: Flow Actions

When to Use

• Standard Salesforce data operations (CRUD)
• Business logic that can be expressed in Flow
• Screen flows for guided user experiences
• Approval processes

Implementation

actions:
  create_case:
    description: "Creates a new support case for the customer"
    inputs:
      subject:
        type: string
        description: "Case subject line"
      description:
        type: string
        description: "Detailed case description"
      priority:
        type: string
        description: "Case priority (Low, Medium, High, Urgent)"
    outputs:
      caseNumber:
        type: string
        description: "Created case number"
      caseId:
        type: string
        description: "Case record ID"
    target: "flow://Create_Support_Case"

Flow Requirements

For an action to work with agents, the Flow must:

1. Be Autolaunched — processType: AutoLaunchedFlow
2. Have Input Variables — Marked as isInput: true
3. Have Output Variables — Marked as isOutput: true
4. Be Active — status: Active

Flow Variable Example:

<variables>
    <name>subject</name>
    <dataType>String</dataType>
    <isCollection>false</isCollection>
    <isInput>true</isInput>
    <isOutput>false</isOutput>
</variables>

Best Practices

Action Type 2: Apex Actions

When to Use

• Complex calculations or algorithms
• Custom integrations requiring Apex
• Operations not possible in Flow
• Bulk data processing
• When you need full control over execution

Two Deployment Paths (CRITICAL DISTINCTION)

⚠️ The official agent-script-recipes repo uses apex://ClassName directly with ZERO GenAiFunction metadata. GenAiFunction is only needed when configuring agents through the Agent Builder UI or deploying via GenAiPlannerBundle.

Path A: AiAuthoringBundle (Agent Script — RECOMMENDED)

Step 1: Create Apex Class with @InvocableMethod

public with sharing class CalculateDiscountAction {

    public class DiscountRequest {
        @InvocableVariable(label='Order Amount' required=true)
        public Decimal orderAmount;

        @InvocableVariable(label='Customer Tier' required=true)
        public String customerTier;
    }

    public class DiscountResult {
        @InvocableVariable(label='Discount Percentage')
        public Decimal discountPercentage;

        @InvocableVariable(label='Final Amount')
        public Decimal finalAmount;
    }

    @InvocableMethod(
        label='Calculate Discount'
        description='Calculates discount based on order amount and customer tier'
    )
    public static List<DiscountResult> calculateDiscount(List<DiscountRequest> requests) {
        List<DiscountResult> results = new List<DiscountResult>();
        for (DiscountRequest req : requests) {
            DiscountResult result = new DiscountResult();
            result.discountPercentage = getTierDiscount(req.customerTier);
            result.finalAmount = req.orderAmount * (1 - result.discountPercentage / 100);
            results.add(result);
        }
        return results;
    }

    private static Decimal getTierDiscount(String tier) {
        Map<String, Decimal> tierDiscounts = new Map<String, Decimal>{
            'Bronze' => 5, 'Silver' => 10, 'Gold' => 15, 'Platinum' => 20
        };
        return tierDiscounts.containsKey(tier) ? tierDiscounts.get(tier) : 0;
    }
}

Step 2: Reference DIRECTLY in Agent Script via apex://

topic discount_calculator:
   description: "Calculates discount for customer order"

   # Level 1: Action DEFINITION with target
   actions:
      calculate_discount:
         description: "Calculates discount based on order amount and customer tier"
         inputs:
            orderAmount: number
               description: "The total order amount before discount"
            customerTier: string
               description: "Customer membership tier"
         outputs:
            discountPercentage: number
               description: "Applied discount percentage"
            finalAmount: number
               description: "Final order amount after discount"
         target: "apex://CalculateDiscountAction"   # Direct Apex — NO GenAiFunction needed!

   reasoning:
      instructions: |
         Help the customer calculate their discount.
      # Level 2: Action INVOCATION referencing the Level 1 definition
      actions:
         calc: @actions.calculate_discount
            with orderAmount=...
            with customerTier=@variables.tier
            set @variables.final_amount = @outputs.finalAmount

✅ No GenAiFunction, no GenAiPlugin, no metadata deployment beyond the Apex class itself. The apex://ClassName target auto-discovers the @InvocableMethod on the class.

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

Action inputs: and outputs: names in Agent Script must exactly match the @InvocableVariable field names in the Apex class:

Partial Output Pattern: You can declare a subset of the target's outputs in your action definition — you don't need to map every output parameter. This is useful when you only need one field from a multi-output action.

Bare @InvocableMethod Pattern (NOT Compatible)

⚠️ TDD Finding (v2.1.0): Apex classes using bare List<String> parameters (no @InvocableVariable wrapper classes) are incompatible with Agent Script actions. The framework cannot discover bindable parameter names without @InvocableVariable annotations.

// ❌ INCOMPATIBLE with Agent Script — bare parameters, no wrappers
public class BareAction {
    @InvocableMethod(label='Bare Action')
    public static List<String> execute(List<String> inputs) {
        return inputs;
    }
}

// ✅ COMPATIBLE — wrapper classes with @InvocableVariable
public class WrappedAction {
    public class Request {
        @InvocableVariable(label='Input Text' required=true)
        public String inputText;  // ← This field name becomes the I/O name
    }
    public class Response {
        @InvocableVariable(label='Output Text')
        public String outputText;  // ← This field name becomes the I/O name
    }
    @InvocableMethod(label='Wrapped Action')
    public static List<Response> execute(List<Request> requests) { ... }
}

Rule: Always use @InvocableVariable wrapper classes when your Apex action will be called from Agent Script.

⚠️ Namespace Warning (Unresolved): In namespaced packages, apex://ClassName may fail at publish time with "invocable action does not exist," even when the Apex class is confirmed deployed via SOQL. It is unclear whether namespace prefix syntax is required (e.g., apex://ns__ClassName). If you encounter this in a namespaced org, try: (1) apex://ns__ClassName format, (2) wrapping the Apex in a Flow and using flow:// instead. See known-issues.md for tracking.

Path B: Agent Builder UI (GenAiPlannerBundle — Legacy)

If you're NOT using Agent Script and are building agents through the Agent Builder UI, you need GenAiFunction metadata to wrap the Apex class. See the templates/metadata/genai-function-apex.xml template for the XML format.

Note: GenAiFunction XML (API v65.0) only supports these elements: masterLabel, description, invocationTarget, invocationTargetType, isConfirmationRequired. Input/output schemas are defined via input/schema.json and output/schema.json bundle files, NOT inline XML elements.

Action Type 3: API Actions (External System Integration)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  API ACTION ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────┤
│  Agent Script                                                │
│       │                                                      │
│       ▼                                                      │
│  flow://HTTP_Callout_Flow                                    │
│       │                                                      │
│       ▼                                                      │
│  HTTP Callout Action (in Flow)                               │
│       │                                                      │
│       ▼                                                      │
│  Named Credential (Authentication)                           │
│       │                                                      │
│       ▼                                                      │
│  External API                                                │
└─────────────────────────────────────────────────────────────┘

Implementation Steps

1. Create Named Credential (via sf-integration skill)
2. Create HTTP Callout Flow wrapping the external call
3. Reference Flow in Agent Script with flow:// target

Security Considerations

Connection Block (Escalation Routing)

The connection block enables escalation to human agents via Omni-Channel. Both singular (connection) and plural (connections) forms are supported.

Basic Syntax

# Messaging channel (most common)
connection messaging:
   outbound_route_type: "OmniChannelFlow"
   outbound_route_name: "Support_Queue_Flow"
   escalation_message: "Transferring you to a human agent..."
   adaptive_response_allowed: True

Multiple Channels

# Use plural form for multiple channels
connections:
   messaging:
      escalation_message: "Transferring to messaging agent..."
      outbound_route_type: "OmniChannelFlow"
      outbound_route_name: "agent_support_flow"
      adaptive_response_allowed: True
   telephony:
      escalation_message: "Routing to technical support..."
      outbound_route_type: "OmniChannelFlow"
      outbound_route_name: "technical_support_flow"
      adaptive_response_allowed: False

Connection Block Properties

Supported Channels

CRITICAL: Values like "queue", "skill", "agent" for outbound_route_type cause validation errors!

Escalation Action

# AiAuthoringBundle - basic escalation
actions:
   transfer_to_human: @utils.escalate
      description: "Transfer to human agent"

# GenAiPlannerBundle - with reason parameter
actions:
   transfer_to_human: @utils.escalate with reason="Customer requested"

Prerequisites for Escalation

1. Omni-Channel configured in Salesforce
2. Omni-Channel Flow created and deployed
3. Connection block in agent script
4. Messaging channel active (Enhanced Chat, etc.)

GenAiFunction Metadata Summary (Agent Builder UI / GenAiPlannerBundle ONLY)

⚠️ NOT needed for AiAuthoringBundle (Agent Script). If you're writing .agent files, use target: "apex://ClassName" or target: "flow://FlowName" directly. See Action Type 2 above.

GenAiFunction wraps Apex, Flows, or Prompts as Agent Actions for the Agent Builder UI path.

<!-- Minimal valid GenAiFunction XML (API v65.0) -->
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>What this action does</description>
    <invocationTarget>FlowOrApexName</invocationTarget>
    <invocationTargetType>flow|apex|prompt</invocationTargetType>
    <isConfirmationRequired>false</isConfirmationRequired>
    <masterLabel>Display Name</masterLabel>
</GenAiFunction>

Input/Output Schemas: Use input/schema.json and output/schema.json files in the GenAiFunction bundle directory. Do NOT use inline XML elements like <genAiFunctionInputs>, <genAiFunctionOutputs>, <genAiFunctionParameters>, or <capability> — these are NOT valid in the Metadata API XML schema (API v65.0).

Prompt Template Types

Template Variable Types

Cross-Skill Integration

Orchestration Order for API Actions

When building agents with external API integrations, follow this order:

┌─────────────────────────────────────────────────────────────┐
│  INTEGRATION + AGENTFORCE ORCHESTRATION ORDER                │
├─────────────────────────────────────────────────────────────┤
│  1. sf-connected-apps  → Connected App (if OAuth needed)     │
│  2. sf-integration     → Named Credential + External Service │
│  3. sf-apex            → @InvocableMethod (if custom logic)  │
│  4. sf-flow            → Flow wrapper (HTTP Callout / Apex)  │
│  5. sf-deploy          → Deploy all metadata to org          │
│  6. sf-ai-agentscript  → Agent with flow:// target           │
│  7. sf-deploy          → Publish (sf agent publish            │
│                           authoring-bundle)                   │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

Debugging Tips

1. Check deployment status: sf project deploy report
2. Verify GenAiFunction deployment: sf org list metadata -m GenAiFunction
3. Test Flow independently: Use Flow debugger in Setup with sample inputs
4. Check agent logs: Agent Builder → Logs

Related Documentation

• action-patterns.md — Context-aware descriptions, instruction references, binding strategies
• action-prompt-templates.md — Prompt template invocation (generatePromptResponse://)
• fsm-architecture.md — FSM design and node patterns