@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/apex/models-api-queueable.cls

@@ -0,0 +1,225 @@
+/**
+ * @description Queueable job for AI generation using Agentforce Models API
+ *              Generates {{Description}} for {{ObjectName}} records
+ * @author {{Author}}
+ * @date {{Date}}
+ *
+ * @requires API v61.0+ (Spring '24)
+ * @requires Einstein Generative AI enabled
+ * @requires Einstein Generative AI User permission set
+ *
+ * @example
+ * // Invoke from trigger or other context:
+ * List<Id> recordIds = new List<Id>{ '001xx000003DGXXX' };
+ * System.enqueueJob(new {{ClassName}}_AI_Queueable(recordIds));
+ */
+public with sharing class {{ClassName}}_AI_Queueable implements Queueable, Database.AllowsCallouts {
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Available Models:
+     * - sfdc_ai__DefaultOpenAIGPT4OmniMini  (Cost-effective, faster)
+     * - sfdc_ai__DefaultOpenAIGPT4Omni      (More capable, slower)
+     * - sfdc_ai__DefaultAnthropic           (Claude - nuanced)
+     * - sfdc_ai__DefaultGoogleGemini        (Multimodal capable)
+     */
+    private static final String AI_MODEL = 'sfdc_ai__DefaultOpenAIGPT4OmniMini';
+
+    /**
+     * Maximum records to process in a single job.
+     * Recommended: 10-20 for AI processing to avoid timeouts.
+     */
+    private static final Integer MAX_RECORDS_PER_JOB = 20;
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // INSTANCE VARIABLES
+    // ═══════════════════════════════════════════════════════════════════════
+
+    private List<Id> recordIds;
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // CONSTRUCTOR
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Constructor
+     * @param recordIds List of {{ObjectName}} record IDs to process
+     */
+    public {{ClassName}}_AI_Queueable(List<Id> recordIds) {
+        this.recordIds = recordIds;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // QUEUEABLE EXECUTION
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Execute the queueable job
+     * @param context QueueableContext
+     */
+    public void execute(QueueableContext context) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return;
+        }
+
+        // Split into current batch and remaining
+        List<Id> currentBatch = new List<Id>();
+        List<Id> remainingIds = new List<Id>();
+
+        for (Integer i = 0; i < recordIds.size(); i++) {
+            if (i < MAX_RECORDS_PER_JOB) {
+                currentBatch.add(recordIds[i]);
+            } else {
+                remainingIds.add(recordIds[i]);
+            }
+        }
+
+        // Process current batch
+        processRecords(currentBatch);
+
+        // Chain next job if more records remain
+        if (!remainingIds.isEmpty() && !Test.isRunningTest()) {
+            System.enqueueJob(new {{ClassName}}_AI_Queueable(remainingIds));
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // PROCESSING LOGIC
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Process a batch of records
+     * @param batchIds Record IDs to process in this batch
+     */
+    private void processRecords(List<Id> batchIds) {
+        // Query records with fields needed for AI prompt
+        List<{{ObjectName}}> records = [
+            SELECT Id, Name
+                   // TODO: Add fields needed for AI context
+                   // , Description, Subject, Type
+            FROM {{ObjectName}}
+            WHERE Id IN :batchIds
+            WITH USER_MODE
+        ];
+
+        List<{{ObjectName}}> toUpdate = new List<{{ObjectName}}>();
+
+        for ({{ObjectName}} record : records) {
+            try {
+                // Generate AI content
+                String aiContent = generateAIContent(record);
+
+                if (String.isNotBlank(aiContent)) {
+                    // TODO: Update the target field with AI-generated content
+                    // record.AI_Summary__c = aiContent;
+                    toUpdate.add(record);
+                }
+            } catch (Exception e) {
+                // Log error but continue processing other records
+                logError(record.Id, e);
+            }
+        }
+
+        // Batch update
+        if (!toUpdate.isEmpty()) {
+            try {
+                update toUpdate;
+            } catch (DmlException e) {
+                System.debug(LoggingLevel.ERROR, 'DML Error: ' + e.getMessage());
+            }
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // AI GENERATION
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Generate AI content for a single record
+     * @param record The record to generate content for
+     * @return Generated text content
+     */
+    private String generateAIContent({{ObjectName}} record) {
+        // Build the prompt with record context
+        String prompt = buildPrompt(record);
+
+        // Create Models API request
+        aiplatform.ModelsAPI.createGenerations_Request request =
+            new aiplatform.ModelsAPI.createGenerations_Request();
+        request.modelName = AI_MODEL;
+
+        aiplatform.ModelsAPI_GenerationRequest genRequest =
+            new aiplatform.ModelsAPI_GenerationRequest();
+        genRequest.prompt = prompt;
+        request.body = genRequest;
+
+        // Call the API
+        aiplatform.ModelsAPI.createGenerations_Response response =
+            aiplatform.ModelsAPI.createGenerations(request);
+
+        // Extract and return generated text
+        if (response.Code200 != null &&
+            response.Code200.generations != null &&
+            !response.Code200.generations.isEmpty()) {
+            return response.Code200.generations[0].text;
+        }
+
+        return null;
+    }
+
+    /**
+     * @description Build the AI prompt for a record
+     * @param record The record to build prompt for
+     * @return Formatted prompt string
+     */
+    private String buildPrompt({{ObjectName}} record) {
+        // TODO: Customize this prompt for your use case
+        String prompt =
+            '{{PromptInstructions}}\n\n' +
+            'Record Information:\n' +
+            '- Name: ' + record.Name + '\n';
+            // TODO: Add more fields as needed
+            // '- Description: ' + record.Description + '\n' +
+            // '- Type: ' + record.Type + '\n';
+
+        return prompt;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // ERROR HANDLING
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Log processing errors
+     * @param recordId The record that failed
+     * @param e The exception that occurred
+     */
+    private void logError(Id recordId, Exception e) {
+        System.debug(LoggingLevel.ERROR,
+            '{{ClassName}}_AI_Queueable Error for ' + recordId + ': ' + e.getMessage());
+        System.debug(LoggingLevel.ERROR, 'Stack Trace: ' + e.getStackTraceString());
+
+        // TODO: Implement custom error logging
+        // Options:
+        // 1. Create Error_Log__c record
+        // 2. Publish Platform Event for monitoring
+        // 3. Send email notification
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // TEST SUPPORT
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Test-visible method to verify prompt generation
+     * @param record Test record
+     * @return Generated prompt
+     */
+    @TestVisible
+    private String testBuildPrompt({{ObjectName}} record) {
+        return buildPrompt(record);
+    }
+}

package/skills/agentforce-development/assets/bundle-meta.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  AUTHORING BUNDLE METADATA FILE
+  ==============================
+
+  CRITICAL NAMING CONVENTION:
+  - File MUST be named: AgentName.bundle-meta.xml
+  - NOT: AgentName.aiAuthoringBundle-meta.xml
+
+  DIRECTORY STRUCTURE:
+  force-app/main/default/aiAuthoringBundles/
+  └── MyAgent/
+      ├── MyAgent.agent              <- Agent Script file
+      └── MyAgent.bundle-meta.xml    <- This file (rename to match agent)
+
+  DEPLOYMENT COMMAND:
+  sf agent publish authoring-bundle --api-name MyAgent --target-org TARGET_ORG
+
+  DO NOT USE: sf project deploy start (will fail with "Required fields are missing: [BundleType]")
+-->
+<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <bundleType>AGENT</bundleType>
+</AiAuthoringBundle>

package/skills/agentforce-development/assets/components/apex-action.agent

@@ -0,0 +1,52 @@
+# Apex-Based Action Template
+# Define an action that calls a Salesforce Apex @InvocableMethod
+# This is a PARTIAL template - define actions inside a topic block
+#
+# Usage: Replace {{placeholders}} with your values
+# Place this inside a topic's actions: block
+#
+# ⚠️ The target format is apex://ClassName (NOT ClassName.MethodName)
+#    The runtime auto-discovers the @InvocableMethod on the class.
+# ⚠️ NO GenAiFunction metadata needed for AiAuthoringBundle (Agent Script).
+
+# Action Definition (place inside topic's actions: block)
+{{action_name}}:
+	description: "{{ActionDescription}}"
+	inputs:
+		{{input_1_name}}: {{input_1_type}}
+			description: "{{Input1Description}}"
+		{{input_2_name}}: {{input_2_type}}
+			description: "{{Input2Description}}"
+	outputs:
+		{{output_1_name}}: {{output_1_type}}
+			description: "{{Output1Description}}"
+		success: boolean
+			description: "Whether the operation succeeded"
+		error_message: string
+			description: "Error message if operation failed"
+	target: "apex://{{ApexClassName}}"
+
+# Usage in reasoning block:
+#
+# reasoning:
+#    instructions: ->
+#       | Help the user with their request.
+#    actions:
+#       invoke_{{action_name}}: @actions.{{action_name}}
+#          with {{input_1_name}}=...  # LLM fills from conversation
+#          with {{input_2_name}}=@variables.some_var  # From variable
+#          set @variables.result = @outputs.{{output_1_name}}
+#          set @variables.success = @outputs.success
+
+# Common Apex Target Patterns:
+# - apex://AccountService
+# - apex://CaseService
+# - apex://OrderService
+# - apex://IntegrationService
+# - apex://CalculationService
+
+# Apex Class Requirements:
+# - Must be global or public with sharing
+# - Must have exactly ONE @InvocableMethod annotation
+# - Use @InvocableVariable annotations on input/output wrapper class fields
+# - No GenAiFunction metadata needed for AiAuthoringBundle (Agent Script)

package/skills/agentforce-development/assets/components/error-handling.agent

@@ -0,0 +1,58 @@
+# Error Handling Topic Template
+# A topic with validation and guard clauses for critical operations
+# This is a PARTIAL template - use within a complete agent file
+#
+# Usage: Replace {{placeholders}} with your values
+# Note: Includes validation patterns and error handling
+
+topic {{topic_name}}:
+	label: "{{TopicLabel}}"
+	description: "{{TopicDescription}} - includes validation and error handling"
+
+	actions:
+		{{action_name}}:
+			description: "{{ActionDescription}}"
+			inputs:
+				{{input_name}}: {{input_type}}
+					description: "{{InputDescription}}"
+			outputs:
+				success: boolean
+					description: "Whether the operation succeeded"
+				error_message: string
+					description: "Error message if operation failed"
+				{{output_name}}: {{output_type}}
+					description: "{{OutputDescription}}"
+			target: "{{ActionTarget}}"
+
+	reasoning:
+		instructions: ->
+			# Validation guard clauses
+			if @variables.{{required_field}} is None:
+				set @variables.validation_passed = False
+				| I need {{RequiredFieldDescription}} before I can proceed.
+				| Please provide this information.
+
+			if @variables.{{amount_field}} > {{MaxAmount}}:
+				set @variables.validation_passed = False
+				| The {{AmountFieldDescription}} exceeds the maximum of {{MaxAmount}}.
+				| Would you like to:
+				| - Use the maximum allowed amount
+				| - Split into multiple operations
+				| - Contact support for a higher limit
+
+			if @variables.validation_passed == True:
+				| All validations passed. Proceeding with the operation.
+
+		actions:
+			# Only available when validation passes
+			execute_action: @actions.{{action_name}}
+				with {{input_name}}=@variables.{{input_variable}}
+				set @variables.operation_success = @outputs.success
+				set @variables.result = @outputs.{{output_name}}
+				available when @variables.validation_passed == True
+
+			# Handle errors
+			retry_operation: @utils.transition to @topic.{{topic_name}}
+				available when @variables.operation_success == False
+
+			back_to_menu: @utils.transition to @topic.topic_selector

package/skills/agentforce-development/assets/components/escalation-setup.agent

@@ -0,0 +1,169 @@
+# Escalation Setup Pattern
+# Complete agent template with connection block for human escalation
+#
+# ★ When To Use This Pattern:
+#   - Agent needs to transfer conversations to human agents
+#   - Using Omni-Channel for routing
+#   - Enhanced Chat or other messaging channels
+#
+# ★ Key Components:
+#   1. connection messaging: block - defines routing destination
+#   2. @utils.escalate action - triggers the transfer
+#   3. escalation topic - handles the handoff flow
+#
+# ★ Prerequisites:
+#   - Omni-Channel configured in Salesforce
+#   - Queue/Skill created for routing
+#   - Messaging channel active (Enhanced Chat, etc.)
+#
+# This is a COMPLETE template - customize for your use case
+
+system:
+	instructions: "You are a helpful customer service agent. Be professional, friendly, and helpful. If you cannot resolve an issue or the customer requests a human, transfer them to a live agent."
+	messages:
+		welcome: "Hello! I'm here to help you today. What can I assist you with?"
+		error: "I apologize, but I encountered an issue. Let me connect you with a human agent."
+
+config:
+	agent_name: "{{AGENT_NAME}}"
+	default_agent_user: "{{AGENT_USER_EMAIL}}"
+	agent_label: "{{AGENT_LABEL}}"
+	description: "Customer service agent with human escalation capability"
+
+variables:
+	# Required linked variables for messaging context
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+
+	# Escalation tracking variables
+	escalation_requested: mutable boolean = False
+		description: "Whether customer requested human agent"
+	escalation_reason: mutable string
+		description: "Reason for escalation"
+	# ⚠️ Use 'number' not 'integer' - integer type is NOT supported in AiAuthoringBundle
+	attempts_before_escalation: mutable number = 0
+		description: "Number of attempts before escalating"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+# ★ CONNECTION BLOCK - Required for @utils.escalate to work
+# This defines where escalated conversations are routed
+# Use singular 'connection' for one channel, plural 'connections' for multiple
+connection messaging:
+	# ⚠️ IMPORTANT: Only "OmniChannelFlow" is supported (not "queue", "skill", or "agent")
+	outbound_route_type: "OmniChannelFlow"
+	# API name of your Omni-Channel Flow
+	outbound_route_name: "{{OMNI_CHANNEL_FLOW_NAME}}"
+	# ⚠️ REQUIRED: escalation_message must be included when connection block is present
+	escalation_message: "Transferring you to a human agent now..."
+	# Optional: Allow agent to adapt responses during escalation
+	adaptive_response_allowed: True
+
+# ★ MULTI-CHANNEL EXAMPLE (use 'connections' plural for multiple channels)
+# connections:
+#    messaging:
+#       outbound_route_type: "OmniChannelFlow"
+#       outbound_route_name: "Chat_Support_Flow"
+#       escalation_message: "Connecting you to chat support..."
+#       adaptive_response_allowed: True
+#    telephony:
+#       outbound_route_type: "OmniChannelFlow"
+#       outbound_route_name: "Phone_Support_Flow"
+#       escalation_message: "Transferring to phone support..."
+#       adaptive_response_allowed: False
+
+# Entry point
+start_agent topic_selector:
+	label: "Topic Selector"
+	description: "Routes users to appropriate topics based on intent"
+
+	reasoning:
+		instructions: ->
+			| Greet the customer and determine their needs.
+			| If they ask for a human or live agent, route to escalation.
+			| Otherwise, try to help them directly.
+		actions:
+			go_help: @utils.transition to @topic.help
+			go_escalation: @utils.transition to @topic.escalation
+				available when @variables.escalation_requested == True
+
+topic help:
+	label: "Help"
+	description: "Provides assistance to customers"
+
+	reasoning:
+		instructions: ->
+			| Help the customer with their question.
+			| If you cannot resolve their issue after 2-3 attempts, offer to connect them with a human.
+			| If they explicitly ask for a human agent at any time, transfer immediately.
+			|
+			| Phrases that indicate escalation request:
+			| - "talk to a human"
+			| - "speak to someone"
+			| - "real person"
+			| - "live agent"
+			| - "customer service representative"
+			|
+			| Track escalation reason if provided:
+			set @variables.escalation_reason = ...
+		actions:
+			offer_escalation: @utils.transition to @topic.escalation
+
+			immediate_escalation: @utils.transition to @topic.escalation
+
+topic escalation:
+	label: "Escalation"
+	description: "Transfers conversation to human agent"
+
+	reasoning:
+		instructions: ->
+			| The customer is being transferred to a human agent.
+			| Acknowledge their request and apologize for any inconvenience.
+			| Let them know a human will be with them shortly.
+			|
+			| Say something like:
+			| "I understand you'd like to speak with a human agent. I'm connecting you now.
+			| A customer service representative will be with you shortly. Thank you for your patience."
+		actions:
+			# ★ ESCALATION ACTION
+			# This transfers the conversation to the queue defined in connection block
+			transfer_to_human: @utils.escalate
+				description: "Transfer to human agent when customer requests or issue cannot be resolved"
+
+# ★ NOTE: Skill-Based and Queue-Based Routing
+# ⚠️ As of Dec 2025, only "OmniChannelFlow" is supported for outbound_route_type
+# "queue", "skill", and "agent" cause validation errors
+# You must create an Omni-Channel Flow that routes to your desired queue/skill
+
+# ★ Alternative: GenAiPlannerBundle Escalation with Reason
+# If using GenAiPlannerBundle (not visible in Studio), you can use:
+#
+# actions:
+#    escalate_with_reason: @utils.escalate with reason="Customer requested human assistance"
+#
+# NOTE: The "with reason" syntax only works in GenAiPlannerBundle!
+# AiAuthoringBundle will fail with SyntaxError if you use it.
+
+# ★ Troubleshooting Escalation:
+#
+# Issue: "escalate" action not recognized
+# Fix: Add the connection messaging: block
+#
+# Issue: Transfer fails silently
+# Fix: Verify Omni-Channel queue exists and has available agents
+#
+# Issue: SyntaxError: Unexpected 'with'
+# Fix: You're using AiAuthoringBundle - remove "with reason" syntax
+#
+# Issue: Agent user lacks permissions
+# Fix: Grant Omni-Channel permissions to the default_agent_user

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

@@ -0,0 +1,66 @@
+# Flow-Based Action Template
+# Define an action that calls a Salesforce Flow
+# This is a PARTIAL template - define actions inside a topic block
+#
+# ⚠️ NOTE ON DEPLOYMENT METHODS:
+#    - AiAuthoringBundle: `with`/`set` clauses ARE supported (TDD validated v1.7.0+)
+#    - GenAiPlannerBundle: Full syntax including `with`/`set` also supported
+#
+# Both deployment methods support the Two-Level Action System:
+#   Level 1: Action definition in topic `actions:` block (with target/inputs/outputs)
+#   Level 2: Action invocation in `reasoning.actions:` block (with `with`/`set` clauses)
+#
+# Usage: Replace {{placeholders}} with your values
+# Place this inside a topic's actions: block
+
+# Action Definition (place inside topic's actions: block)
+{{action_name}}:
+	description: "{{ActionDescription}}"
+	inputs:
+		{{input_1_name}}: {{input_1_type}}
+			description: "{{Input1Description}}"
+		{{input_2_name}}: {{input_2_type}}
+			description: "{{Input2Description}}"
+	outputs:
+		{{output_1_name}}: {{output_1_type}}
+			description: "{{Output1Description}}"
+		{{output_2_name}}: {{output_2_type}}
+			description: "{{Output2Description}}"
+	target: "flow://{{FlowApiName}}"
+
+# Usage in reasoning block:
+#
+# ═══════════════════════════════════════════════════════════════════════════════
+# ✅ Recommended Pattern — Level 2 invocation with `with`/`set` (works in both
+#    AiAuthoringBundle and GenAiPlannerBundle, TDD validated v1.7.0+)
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# reasoning:
+#    instructions: ->
+#       | Help the user with their request.
+#    actions:
+#       invoke_{{action_name}}: @actions.{{action_name}}
+#          with {{input_1_name}}=...  # LLM fills from conversation
+#          with {{input_2_name}}=@variables.some_var  # From variable
+#          set @variables.result1 = @outputs.{{output_1_name}}
+#          set @variables.result2 = @outputs.{{output_2_name}}
+#
+# ═══════════════════════════════════════════════════════════════════════════════
+# Alternative: LLM auto-invoke based on action description (no explicit binding)
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# reasoning:
+#    instructions: ->
+#       | Help the user with their request.
+#       | Use the available actions when needed.
+#    actions:
+#       back_to_menu: @utils.transition to @topic.topic_selector
+
+# Common Flow Target Patterns:
+# - flow://Get_Account_Details
+# - flow://Create_Case
+# - flow://Update_Opportunity
+# - flow://Send_Email_Notification
+# - flow://Calculate_Discount
+
+# Input/Output Types: string, number, boolean, list[string], object