@salesforce/afv-skills 1.1.0 → 1.2.0

package/skills/agentforce-development/assets/escalation-pattern.agent

@@ -0,0 +1,209 @@
+# Escalation Pattern Template
+# ===========================
+#
+# This template demonstrates the complete escalation pattern with:
+# - Multi-channel connection blocks (messaging, voice, web)
+# - Graceful handoff with escalation messages
+# - Pre-escalation data gathering
+# - OmniChannel routing configuration
+#
+# Pattern: Multi-channel escalation with context preservation
+# Use when: Any agent that needs human handoff capabilities
+
+system:
+   messages:
+      welcome: "Hello! I'm here to help. If I can't assist you, I can connect you with a specialist."
+      error: "I apologize, something went wrong. Let me connect you with someone who can help."
+   instructions: "You are a helpful agent. When you cannot resolve an issue, escalate to a human agent with full context."
+
+config:
+   agent_name: "EscalationPatternAgent"
+   agent_label: "Escalation Demo Agent"
+   description: "Agent demonstrating complete escalation patterns"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+# ============================================================
+# CONNECTION BLOCKS (Multi-Channel Escalation)
+# ============================================================
+
+connections:
+   # Messaging channel (SMS, WhatsApp, etc.)
+   connection messaging:
+      escalation_message: "One moment, I'm transferring our conversation to a specialist who can better assist you."
+      outbound_route_type: "OmniChannelFlow"
+      outbound_route_name: "<flow://Escalate_Messaging_To_Agent>"
+      adaptive_response_allowed: False
+
+   # Voice channel
+   connection voice:
+      escalation_message: "Please hold while I transfer you to a specialist. They will have full context of our conversation."
+      outbound_route_type: "Queue"
+      outbound_route_name: "Customer_Support_Queue"
+      adaptive_response_allowed: True
+
+   # Web chat channel
+   connection web:
+      escalation_message: "Connecting you with a live agent now. They'll be with you shortly."
+      outbound_route_type: "OmniChannelFlow"
+      outbound_route_name: "<flow://Web_Chat_Escalation_Flow>"
+      adaptive_response_allowed: False
+
+variables:
+   # Customer context
+   customer_name: mutable string = ""
+      description: "Customer's name for personalization"
+   customer_issue: mutable string = ""
+      description: "Summary of customer's issue"
+   issue_category: mutable string = ""
+      description: "Category of issue for routing"
+
+   # Escalation state
+   escalation_reason: mutable string = ""
+      description: "Reason for escalation"
+   attempts_before_escalation: mutable number = 0
+      description: "Number of resolution attempts"
+   ready_to_escalate: mutable boolean = False
+      description: "Whether pre-escalation data is gathered"
+
+start_agent entry:
+   description: "Entry point - greet and assess needs"
+   reasoning:
+      instructions: |
+         Greet the customer and understand their needs.
+         Try to help directly, escalate if needed.
+      actions:
+         go_support: @utils.transition to @topic.support
+            description: "Help with support issue"
+
+# ============================================================
+# SUPPORT TOPIC (With Escalation Triggers)
+# ============================================================
+
+topic support:
+   description: "Attempt to resolve issue, escalate if unable"
+   reasoning:
+      instructions: ->
+         # POST-ACTION: Check if escalation was triggered
+         if @variables.ready_to_escalate == True:
+            transition to @topic.pre_escalation
+
+         # Track attempts
+         | I'm here to help you with your issue.
+
+         if @variables.attempts_before_escalation >= 2:
+            | It seems like I'm having trouble resolving this.
+            | Would you like me to connect you with a specialist?
+
+      actions:
+         # Attempt resolution
+         try_resolve: @actions.Attempt_Resolution
+            description: "Try to resolve the issue"
+            with issue = ...  # LLM extracts from conversation
+            set @variables.customer_issue = @outputs.issue_summary
+            set @variables.issue_category = @outputs.category
+            set @variables.attempts_before_escalation = @variables.attempts_before_escalation + 1
+
+         # User-initiated escalation
+         request_human: @utils.setVariables
+            description: "I'd like to speak with a human"
+            with escalation_reason = "Customer requested human agent"
+            with ready_to_escalate = True
+
+         # Agent-initiated escalation (after failed attempts)
+         escalate_complex: @utils.setVariables
+            description: "Connect me with a specialist"
+            available when @variables.attempts_before_escalation >= 2
+            with escalation_reason = "Unable to resolve after multiple attempts"
+            with ready_to_escalate = True
+
+# ============================================================
+# PRE-ESCALATION TOPIC (Gather Context)
+# ============================================================
+
+topic pre_escalation:
+   description: "Gather information before escalating"
+   reasoning:
+      instructions: ->
+         # Ensure we have customer name for personalization
+         if @variables.customer_name == "":
+            | Before I transfer you, may I have your name so the specialist can address you properly?
+         else:
+            | Thank you, {!@variables.customer_name}. Let me prepare the transfer.
+
+         # Display summary of what we'll share
+         if @variables.customer_name != "" and @variables.customer_issue != "":
+            | I'll share the following with the specialist:
+            | - Your issue: {!@variables.customer_issue}
+            | - Category: {!@variables.issue_category}
+            | - Reason for transfer: {!@variables.escalation_reason}
+            |
+            | Ready to connect you now.
+            transition to @topic.escalation
+
+      actions:
+         # Capture customer name
+         save_name: @utils.setVariables
+            description: "Save customer name"
+            available when @variables.customer_name == ""
+            with customer_name = ...  # LLM extracts name from response
+
+         # Proceed to escalation
+         proceed: @utils.transition to @topic.escalation
+            description: "Proceed with transfer"
+            available when @variables.customer_name != ""
+
+         # Cancel escalation
+         cancel_escalation: @utils.setVariables
+            description: "Actually, let me try again with the bot"
+            with ready_to_escalate = False
+            with escalation_reason = ""
+            run @utils.transition to @topic.support
+
+# ============================================================
+# ESCALATION TOPIC (Handoff)
+# ============================================================
+
+topic escalation:
+   description: "Execute escalation to human agent"
+   reasoning:
+      instructions: ->
+         # Log escalation context (this gets passed to human agent)
+         run @actions.Log_Escalation_Context
+            with customer_name = @variables.customer_name
+            with issue_summary = @variables.customer_issue
+            with category = @variables.issue_category
+            with reason = @variables.escalation_reason
+            with attempt_count = @variables.attempts_before_escalation
+
+         | Transferring you now. Thank you for your patience!
+
+      actions:
+         # The actual escalation - uses connection block configuration
+         handoff: @utils.escalate
+            description: "Transfer to human agent"
+
+# ============================================================
+# OPTIONAL: SPECIALIZED ESCALATION QUEUES
+# ============================================================
+
+topic escalate_billing:
+   description: "Escalate specifically to billing team"
+   reasoning:
+      instructions: |
+         I'm connecting you with our billing specialists.
+         They'll be able to help with your account questions.
+      actions:
+         # Note: In production, you'd configure this action
+         # to route to a specific billing queue
+         billing_handoff: @utils.escalate
+            description: "Transfer to billing team"
+
+topic escalate_technical:
+   description: "Escalate specifically to technical support"
+   reasoning:
+      instructions: |
+         I'm connecting you with our technical support team.
+         They specialize in resolving complex technical issues.
+      actions:
+         tech_handoff: @utils.escalate
+            description: "Transfer to technical support"

package/skills/agentforce-development/assets/flow-action-lookup.agent

@@ -0,0 +1,115 @@
+# Flow Action Lookup Template
+# ============================
+#
+# This template demonstrates the pattern for calling Flow actions
+# that return complex data types (SObjects, lists, custom types).
+#
+# Pattern: Data lookup and display using Flow actions
+# Use when: Fetching records from Salesforce (Cases, Orders, Accounts)
+#
+# CRITICAL: When defining Flow action outputs in Agentforce Assets:
+# - For SObject returns: complex_data_type_name = "lightning__recordInfoType"
+# - For list[string]: complex_data_type_name = "lightning__textType"
+# - For currency: complex_data_type_name = "lightning__currencyType"
+
+system:
+   messages:
+      welcome: "Hello! I can help you look up order information."
+      error: "I apologize, something went wrong retrieving your data."
+   instructions: "You are a customer service agent helping users look up their orders."
+
+config:
+   agent_name: "FlowActionLookupAgent"
+   agent_label: "Order Lookup Agent"
+   description: "Agent demonstrating Flow action patterns with complex data types"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+variables:
+   # Customer context (from session)
+   customer_id: linked string
+      source: @session.customerId
+      description: "Customer ID from session context"
+
+   # Order data (populated by Flow action)
+   order_id: mutable string = ""
+      description: "Current order being viewed"
+   order_status: mutable string = ""
+      description: "Order status from lookup"
+   order_total: mutable string = ""
+      description: "Order total amount"
+   order_date: mutable string = ""
+      description: "Order date"
+
+   # Error handling
+   lookup_error: mutable boolean = False
+      description: "Whether lookup encountered an error"
+
+start_agent entry:
+   description: "Entry point - welcome and route to order lookup"
+   reasoning:
+      instructions: |
+         Welcome the customer and offer to help with order lookups.
+      actions:
+         go_lookup: @utils.transition to @topic.order_lookup
+            description: "Start order lookup"
+
+# ============================================================
+# ORDER LOOKUP TOPIC (Flow Action Pattern)
+# ============================================================
+
+topic order_lookup:
+   description: "Look up order details using Flow action"
+   reasoning:
+      instructions: ->
+         # POST-ACTION CHECK: Display results if order was found
+         if @variables.order_status != "":
+            | **Order Details**
+            | - Order ID: {!@variables.order_id}
+            | - Status: {!@variables.order_status}
+            | - Total: {!@variables.order_total}
+            | - Date: {!@variables.order_date}
+            |
+            | Is there anything else you'd like to know about this order?
+
+         # ERROR CHECK: Handle lookup failures
+         if @variables.lookup_error == True:
+            | I couldn't find that order. Please check the order ID and try again.
+            set @variables.lookup_error = False
+
+         # INITIAL STATE: Ask for order ID
+         if @variables.order_id == "":
+            | What order would you like me to look up?
+            | Please provide your order ID.
+
+      actions:
+         # Flow action with SObject return type
+         # In Agentforce Assets, set outputs.order_record complex_data_type_name = "lightning__recordInfoType"
+         lookup_order: @actions.Get_Order_Details
+            description: "Look up order by ID"
+            with order_id = ...  # LLM extracts from user message
+            include_in_progress_indicator: True
+            progress_indicator_message: "Looking up your order..."
+            set @variables.order_id = @outputs.order_id
+            set @variables.order_status = @outputs.status
+            set @variables.order_total = @outputs.total_amount
+            set @variables.order_date = @outputs.order_date
+            # Error handling: check if lookup failed
+            if @outputs.found == False:
+               set @variables.lookup_error = True
+
+         # Flow action returning a list of strings
+         # In Agentforce Assets, set outputs.product_names complex_data_type_name = "lightning__textType"
+         get_items: @actions.Get_Order_Line_Items
+            description: "Get list of items in the order"
+            available when @variables.order_id != ""
+            with order_id = @variables.order_id
+
+         clear_search: @utils.setVariables
+            description: "Search for a different order"
+            with order_id = ""
+            with order_status = ""
+            with order_total = ""
+            with order_date = ""
+
+         escalate_now: @utils.escalate
+            description: "Transfer to human agent"

package/skills/agentforce-development/assets/hub-and-spoke.agent

@@ -0,0 +1,104 @@
+# Hub-and-Spoke Architecture Template
+# ====================================
+#
+# This template demonstrates the Hub-and-Spoke pattern where a central
+# topic_selector (hub) routes conversations to specialized topics (spokes).
+#
+# Pattern: Multi-purpose agents handling distinct request types
+# Use when: Users may have different intents (orders, support, returns)
+
+system:
+   messages:
+      welcome: "Welcome! I can help with orders, returns, or general support."
+      error: "I apologize, something went wrong. Let me try again."
+   instructions: "You are a customer service agent for an e-commerce company."
+
+config:
+   agent_name: "HubAndSpokeAgent"
+   agent_label: "Customer Service Agent"
+   description: "Multi-purpose agent with hub-and-spoke architecture"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+variables:
+   customer_id: linked string
+      source: @session.customerId
+      description: "Customer ID from session"
+   order_id: mutable string = ""
+      description: "Current order being discussed"
+   issue_resolved: mutable boolean = False
+      description: "Whether the issue has been resolved"
+
+# ============================================================
+# HUB: Central Router
+# ============================================================
+
+start_agent topic_selector:
+   description: "Route to appropriate topic based on user intent"
+   reasoning:
+      instructions: |
+         Determine what the customer needs and route accordingly:
+         - Order questions → orders topic
+         - Return/refund requests → returns topic
+         - General questions → support topic
+      actions:
+         check_order: @utils.transition to @topic.orders
+            description: "Customer wants to check order status"
+         process_return: @utils.transition to @topic.returns
+            description: "Customer wants to return or refund"
+         general_help: @utils.transition to @topic.support
+            description: "General support questions"
+
+# ============================================================
+# SPOKE: Orders Topic
+# ============================================================
+
+topic orders:
+   description: "Handle order status and tracking inquiries"
+   reasoning:
+      instructions: ->
+         | Help the customer with their order inquiry.
+
+         if @variables.order_id != "":
+            | Current order: {!@variables.order_id}
+
+      actions:
+         lookup_order: @actions.get_order_status
+            description: "Look up order details"
+            with order_id = @variables.order_id
+         back_to_hub: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+
+# ============================================================
+# SPOKE: Returns Topic
+# ============================================================
+
+topic returns:
+   description: "Handle return and refund requests"
+   reasoning:
+      instructions: ->
+         | Help the customer with their return or refund request.
+         | Verify the order details before processing.
+
+      actions:
+         start_return: @actions.initiate_return
+            description: "Start a return process"
+         process_refund: @actions.process_refund
+            description: "Process a refund"
+         back_to_hub: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+
+# ============================================================
+# SPOKE: Support Topic
+# ============================================================
+
+topic support:
+   description: "Handle general support questions"
+   reasoning:
+      instructions: |
+         Help the customer with general questions.
+         If the question requires specialized help, route appropriately.
+      actions:
+         escalate: @utils.escalate
+            description: "Transfer to human agent"
+         back_to_hub: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"

package/skills/agentforce-development/assets/invocable-apex-template.cls

@@ -0,0 +1,187 @@
+/**
+ * Invocable Apex template for Agent Script action backing logic.
+ *
+ * Wire this class to an Agent Script action with:
+ *     target: "apex://{{ClassName}}"
+ *
+ * The @InvocableVariable field names on Request and Result become the
+ * action's input and output names in the .agent file. They must match
+ * character-for-character — including case.
+ *
+ * STUB USAGE: To create a minimal stub for unblocking deployment,
+ * delete the business logic in execute() and return hardcoded values.
+ * Do not add mock data, conditional logic, or JSON serialization to
+ * stubs — keep them minimal.
+ *
+ * Replace all {{placeholders}} before use.
+ */
+public with sharing class {{ClassName}} {
+
+    // ─── INVOCABLE METHOD ────────────────────────────────────────────
+    //
+    // Must be: static, accept List<Request>, return List<Result>.
+    // This signature supports bulkification when the action is called
+    // for multiple records in a single transaction.
+
+    @InvocableMethod(
+        label='{{ActionLabel}}'
+        description='{{ActionDescription}}'
+    )
+    public static List<Result> execute(List<Request> requests) {
+        List<Result> results = new List<Result>();
+
+        // ── Bulkification: collect IDs first, query once ──
+        // Avoids SOQL-in-loop governor limit issues.
+        Set<Id> recordIds = new Set<Id>();
+        for (Request req : requests) {
+            if (req.recordId != null) {
+                recordIds.add(req.recordId);
+            }
+        }
+
+        // ── USER_MODE ──
+        // `USER_MODE` enforces the running user's FLS/CRUD permissions.
+        // For service agents, the running user is the Einstein Agent User.
+        // If the user lacks read access to queried objects, queries return
+        // 0 rows with NO error — a silent failure. Verify object permissions
+        // before relying on `USER_MODE` queries.
+
+        // Static SOQL (Preferred): Use `WITH USER_MODE` clause:
+        Map<Id, {{SObjectName}}> recordsById = new Map<Id, {{SObjectName}}>();
+        if (!recordIds.isEmpty()) {
+            recordsById = new Map<Id, {{SObjectName}}>(
+                [SELECT Id, Name
+                 FROM {{SObjectName}}
+                 WHERE Id IN :recordIds
+                 WITH USER_MODE]
+            );
+        }
+
+        // Dynamic SOQL (Optional): Use `AccessLevel.USER_MODE` parameter. DO NOT use `WITH USER_MODE` clause!
+        // WARNING! `WITH USER_MODE` inside a dynamic string causes:
+        //   System.QueryException: unexpected token: 'WITH'
+        //
+        // WRONG:
+        //   String q = 'SELECT Id, Name FROM {{SObjectName}} WHERE Id IN :recordIds WITH USER_MODE';
+        //   recordsById = new Map<Id, {{SObjectName}}>(Database.query(q));
+        //
+        // RIGHT:
+        //   String q = 'SELECT Id, Name FROM {{SObjectName}} WHERE Id IN :recordIds';
+        //   recordsById = new Map<Id, {{SObjectName}}>(Database.query(q, AccessLevel.USER_MODE));
+
+        // ── Process each request ──
+        for (Request req : requests) {
+            Result r = new Result();
+            try {
+                {{SObjectName}} record = recordsById.get(req.recordId);
+                if (record == null) {
+                    r = errorResult('Record not found: ' + req.recordId);
+                } else {
+                    // TODO: Replace with actual business logic
+                    r.isSuccess = true;
+                    r.outputMessage = 'Processed: ' + record.Name;
+                    r.outputRecordId = record.Id;
+                }
+            } catch (Exception e) {
+                r = errorResult(e.getMessage());
+            }
+            results.add(r);
+        }
+
+        return results;
+    }
+
+    // ─── REQUEST WRAPPER ─────────────────────────────────────────────
+    //
+    // Each @InvocableVariable becomes an action input in Agent Script.
+    // The field name here must exactly match the input name in the
+    // .agent file's action definition.
+    //
+    // Supported types: Boolean, Date, DateTime, Decimal, Double,
+    //   Integer, Long, String, Id, Time, SObject types, List<T>
+
+    public class Request {
+        @InvocableVariable(
+            label='Record ID'
+            description='ID of the record to process'
+            required=true
+        )
+        public Id recordId;
+
+        @InvocableVariable(
+            label='Operation Type'
+            description='Type of operation to perform'
+            required=false
+        )
+        public String operationType;
+
+        @InvocableVariable(
+            label='Amount'
+            description='Numeric amount for calculations'
+            required=false
+        )
+        public Decimal amount;
+    }
+
+    // ─── RESULT WRAPPER ──────────────────────────────────────────────
+    //
+    // Each @InvocableVariable becomes an action output in Agent Script.
+    // The field name here must exactly match the output name in the
+    // .agent file's action definition.
+    //
+    // Always include isSuccess and errorMessage for consistent error
+    // handling. The agent can check isSuccess to decide what to tell
+    // the user.
+
+    public class Result {
+        @InvocableVariable(
+            label='Is Success'
+            description='Whether the operation completed successfully'
+        )
+        public Boolean isSuccess;
+
+        @InvocableVariable(
+            label='Error Message'
+            description='Error message if operation failed'
+        )
+        public String errorMessage;
+
+        @InvocableVariable(
+            label='Output Message'
+            description='Human-readable result for the agent to relay'
+        )
+        public String outputMessage;
+
+        @InvocableVariable(
+            label='Output Record ID'
+            description='ID of the processed or created record'
+        )
+        public Id outputRecordId;
+
+        @InvocableVariable(
+            label='Output Value'
+            description='Primary result value'
+        )
+        public String outputValue;
+
+        @InvocableVariable(
+            label='Output Amount'
+            description='Numeric result for calculations'
+        )
+        public Decimal outputAmount;
+
+    }
+
+    // ── Error factory ──────────────────────────────────────────────────
+    //
+    // Centralizes error construction so every failure path sets both
+    // isSuccess = false and errorMessage consistently. Defined on the
+    // outer class because Apex prohibits static methods in inner classes.
+
+    private static Result errorResult(String message) {
+        Result r = new Result();
+        r.isSuccess = false;
+        r.errorMessage = message;
+        return r;
+    }
+}