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

Output Properties

Example with All Properties

actions:
   process_payment:
      description: "Processes payment for the order"
      label: "Process Payment"
      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

CRITICAL: Deployment Method Limitations

run keyword is NOT supported in AiAuthoringBundle (Tested Dec 2025)

# ❌ FAILS in AiAuthoringBundle - SyntaxError: Unexpected 'run'
before_reasoning:
   run @actions.log_turn    # NOT SUPPORTED!

create: @actions.create_order
   run @actions.send_email  # NOT SUPPORTED!

{!@actions.name} interpolation does NOT work (Tested Dec 2025)

# ❌ FAILS - SyntaxError: Unexpected '{'
reasoning:
   instructions: ->
      | Use {!@actions.get_order} to look up order details.  # BROKEN!

Correct Approach: Use reasoning.actions Block

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

topic order_management:
   label: "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 (via GenAiFunction)

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

Implementation Steps

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;

        @InvocableVariable(label='Promo Code')
        public String promoCode;
    }

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

        @InvocableVariable(label='Discount Amount')
        public Decimal discountAmount;

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

        @InvocableVariable(label='Applied Rules')
        public String appliedRules;
    }

    @InvocableMethod(
        label='Calculate Discount'
        description='Calculates discount based on order amount, customer tier, and promo code'
    )
    public static List<DiscountResult> calculateDiscount(List<DiscountRequest> requests) {
        List<DiscountResult> results = new List<DiscountResult>();

        for (DiscountRequest req : requests) {
            DiscountResult result = new DiscountResult();
            Decimal tierDiscount = getTierDiscount(req.customerTier);
            Decimal promoDiscount = getPromoDiscount(req.promoCode);

            result.discountPercentage = Math.max(tierDiscount, promoDiscount);
            result.discountAmount = req.orderAmount * (result.discountPercentage / 100);
            result.finalAmount = req.orderAmount - result.discountAmount;
            result.appliedRules = buildAppliedRules(tierDiscount, promoDiscount);

            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;
    }

    private static Decimal getPromoDiscount(String promoCode) {
        if (String.isBlank(promoCode)) return 0;
        return promoCode == 'SAVE20' ? 20 : 0;
    }

    private static String buildAppliedRules(Decimal tierDiscount, Decimal promoDiscount) {
        List<String> rules = new List<String>();
        if (tierDiscount > 0) rules.add('Tier discount: ' + tierDiscount + '%');
        if (promoDiscount > 0) rules.add('Promo discount: ' + promoDiscount + '%');
        return String.join(rules, '; ');
    }
}

Step 2: Create GenAiFunction Metadata

<?xml version="1.0" encoding="UTF-8"?>
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Calculate Discount</masterLabel>
    <description>Calculates customer discount based on tier and promo codes</description>
    <developerName>Calculate_Discount_Action</developerName>

    <invocationTarget>CalculateDiscountAction</invocationTarget>
    <invocationTargetType>apex</invocationTargetType>

    <isConfirmationRequired>false</isConfirmationRequired>

    <capability>
        Calculate customer discounts considering their membership tier and any
        promotional codes. Returns the discount percentage, discount amount,
        and final order amount.
    </capability>

    <genAiFunctionInputs>
        <developerName>orderAmount</developerName>
        <description>The total order amount before discount</description>
        <dataType>Number</dataType>
        <isRequired>true</isRequired>
    </genAiFunctionInputs>

    <genAiFunctionInputs>
        <developerName>customerTier</developerName>
        <description>Customer membership tier: Bronze, Silver, Gold, or Platinum</description>
        <dataType>Text</dataType>
        <isRequired>true</isRequired>
    </genAiFunctionInputs>

    <genAiFunctionInputs>
        <developerName>promoCode</developerName>
        <description>Optional promotional code</description>
        <dataType>Text</dataType>
        <isRequired>false</isRequired>
    </genAiFunctionInputs>

    <genAiFunctionOutputs>
        <developerName>discountPercentage</developerName>
        <description>Applied discount percentage</description>
        <dataType>Number</dataType>
    </genAiFunctionOutputs>

    <genAiFunctionOutputs>
        <developerName>discountAmount</developerName>
        <description>Dollar amount of discount</description>
        <dataType>Number</dataType>
    </genAiFunctionOutputs>

    <genAiFunctionOutputs>
        <developerName>finalAmount</developerName>
        <description>Final order amount after discount</description>
        <dataType>Number</dataType>
    </genAiFunctionOutputs>
</GenAiFunction>

Step 3: Reference in Agent Topic

After deploying the GenAiFunction, it appears in Agent Builder under available actions.

Important: Agent Script apex:// Limitation

Known Issue: The apex://ClassName syntax in Agent Script does not work reliably. Always use GenAiFunction metadata for Apex actions.

❌ Does NOT Work:

actions:
  calculate_discount:
    target: "apex://CalculateDiscountAction"  # BROKEN

✅ Works: Deploy GenAiFunction metadata and add to topic via Agent Builder UI.

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

GenAiFunction wraps Apex, Flows, or Prompts as Agent Actions.

<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Display Name</masterLabel>
    <developerName>API_Name</developerName>
    <description>What this action does</description>
    <invocationTarget>FlowOrApexName</invocationTarget>
    <invocationTargetType>flow|apex|prompt</invocationTargetType>
</GenAiFunction>

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