@salesforce/afv-skills 1.21.0 → 1.22.0

package/skills/agentforce-generate/assets/agents/simple-qa.agent

@@ -0,0 +1,72 @@
+# Simple Q&A Agent Template
+# A minimal agent that handles basic questions using LLM reasoning only
+# No external actions - just conversational AI
+#
+# Usage: Replace {{placeholders}} with your values
+# Required: agent_name, default_agent_user, agent_label, description
+
+system:
+	instructions: "{{SystemInstructions}}"
+	messages:
+		welcome: "{{WelcomeMessage}}"
+		error: "I'm sorry, I encountered an issue. Please try again."
+
+config:
+	agent_name: "{{AgentApiName}}"
+	default_agent_user: "{{AgentUser}}"
+	agent_label: "{{AgentLabel}}"
+	description: "{{AgentDescription}}"
+
+variables:
+	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"
+	user_query: mutable string
+		description: "The user's current question or request"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent agent_router:
+	label: "Subagent Router"
+	description: "Routes incoming requests to the Q&A handler"
+
+	reasoning:
+		instructions: ->
+			| Listen to the user's question.
+			| Route to the Q&A handler for processing.
+		actions:
+			handle_question: @utils.transition to @subagent.qa_handler
+			end_conversation: @utils.transition to @subagent.farewell
+
+subagent qa_handler:
+	label: "Q&A Handler"
+	description: "Handles questions and provides answers"
+
+	reasoning:
+		instructions: ->
+			| Answer the user's question based on your knowledge.
+			| Be helpful, accurate, and concise.
+			| Keep responses clear and easy to understand.
+			| If you need more information, ask clarifying questions.
+		actions:
+			new_question: @utils.transition to @subagent.agent_router
+			end_conversation: @utils.transition to @subagent.farewell
+
+subagent farewell:
+	label: "Farewell"
+	description: "Ends the conversation gracefully"
+
+	reasoning:
+		instructions: ->
+			| Thank the user for their questions.
+			| Wish them a great day.
+			| Let them know they can return anytime for more help.

package/skills/agentforce-generate/assets/agents/verification-gate.agent

@@ -0,0 +1,280 @@
+# Verification Gate Architecture Template
+# ========================================
+#
+# Users must pass identity verification before accessing protected subagents.
+#
+# Pattern: Security gate before protected functionality.
+# Use when: Handling sensitive data, payments, PII access.
+#
+# Key features:
+# - Deterministic verification (code-enforced, not LLM suggestions)
+# - available when guards make actions invisible until verified
+# - Post-action checks at TOP of instructions: ->
+# - Automatic escalation after 3 failed attempts
+
+system:
+	instructions: |
+		You are an AI secure customer service agent.
+		Always verify identity before sensitive operations.
+		Do not fabricate data — always use action results.
+	messages:
+		welcome: "Welcome! I'll need to verify your identity before we proceed."
+		error: "I apologize, something went wrong. Let me try again."
+
+config:
+	developer_name: "SecureAgent"
+	agent_label: "Secure Customer Agent"
+	description: "Agent with verification gate for sensitive operations"
+	default_agent_user: "einsteinagent@00dxx000001234.ext"
+
+variables:
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+		visibility: "External"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+		visibility: "External"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+		visibility: "External"
+	customer_verified: mutable boolean = False
+		description: "Has customer passed identity verification"
+	failed_attempts: mutable number = 0
+		description: "Number of failed verification attempts"
+	customer_email: mutable string = ""
+		description: "Customer email for verification"
+	refund_status: mutable string = ""
+		description: "Status of refund operation"
+	refund_amount: mutable number = 0
+		description: "Refund amount to process"
+	churn_risk_score: mutable number = 0
+		description: "Customer churn risk from Data Cloud"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent agent_router:
+	description: "Route through identity verification"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions or provide help directly.
+			Route all users to identity verification first.
+			If already verified, route to the appropriate subagent:
+			- Account questions -> use to_account
+			- Refund requests -> use to_refund
+		actions:
+			to_verify: @utils.transition to @subagent.identity_verification
+				description: "Begin identity verification"
+			to_account: @utils.transition to @subagent.account_management
+				description: "Access account settings"
+				available when @variables.customer_verified == True
+			to_refund: @utils.transition to @subagent.refund_processor
+				description: "Process a refund request"
+				available when @variables.customer_verified == True
+
+subagent identity_verification:
+	label: "Identity Verification"
+	description: "Verify customer identity before proceeding"
+
+	actions:
+		verify_email:
+			description: "Verify customer email against records"
+			target: "flow://Verify_Customer_Email"
+			inputs:
+				email: string
+					description: "Customer email to verify"
+			outputs:
+				verified: boolean
+					description: "Whether verification succeeded"
+
+	reasoning:
+		instructions: ->
+			if @variables.failed_attempts >= 3:
+				| Too many failed attempts. Transferring to a human agent.
+				transition to @subagent.escalation
+
+			if @variables.customer_verified == True:
+				| Identity verified! How can I help you today?
+
+			if @variables.customer_verified == False:
+				| Please verify your identity by confirming your email address.
+
+		actions:
+			check_email: @actions.verify_email
+				description: "Verify customer email"
+				with email = ...
+				set @variables.customer_verified = @outputs.verified
+
+			go_to_account: @utils.transition to @subagent.account_management
+				description: "Access account settings"
+				available when @variables.customer_verified == True
+
+			go_to_refund: @utils.transition to @subagent.refund_processor
+				description: "Process a refund request"
+				available when @variables.customer_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human agent"
+
+subagent account_management:
+	label: "Account Management"
+	description: "Manage customer account settings (requires verification)"
+
+	actions:
+		update_email:
+			description: "Update customer email address"
+			target: "apex://UpdateCustomerEmail"
+			inputs:
+				new_email: string
+					description: "New email address"
+			outputs:
+				success: boolean
+					description: "Whether update succeeded"
+
+		update_preferences:
+			description: "Update communication preferences"
+			target: "apex://UpdatePreferences"
+			inputs:
+				pref_type: string
+					description: "Preference type to update"
+				pref_value: string
+					description: "New preference value"
+			outputs:
+				success: boolean
+					description: "Whether update succeeded"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == False:
+				transition to @subagent.identity_verification
+
+			| Welcome to account management.
+			| What would you like to do with your account?
+			| Use the update actions to make changes.
+
+		actions:
+			change_email: @actions.update_email
+				description: "Update email address"
+				with new_email = ...
+				available when @variables.customer_verified == True
+
+			change_prefs: @actions.update_preferences
+				description: "Update communication preferences"
+				with pref_type = ...
+				with pref_value = ...
+				available when @variables.customer_verified == True
+
+			back: @utils.transition to @subagent.agent_router
+				description: "Return to main menu"
+
+subagent refund_processor:
+	label: "Refund Processor"
+	description: "Process refund requests (requires verification)"
+
+	actions:
+		check_churn_risk:
+			description: "Check customer churn risk score"
+			target: "apex://CheckChurnRisk"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+			outputs:
+				score: object
+					description: "Churn risk score 0-100"
+					complex_data_type_name: "lightning__numberType"
+
+		process_refund:
+			description: "Process a full cash refund"
+			target: "flow://Process_Refund"
+			inputs:
+				refund_type: string
+					description: "Type of refund (full or partial)"
+			outputs:
+				status: string
+					description: "Refund status"
+
+		issue_credit:
+			description: "Issue store credit"
+			target: "flow://Issue_Store_Credit"
+			inputs:
+				amount: object
+					description: "Credit amount"
+					complex_data_type_name: "lightning__numberType"
+			outputs:
+				status: string
+					description: "Credit status"
+
+		create_crm_case:
+			description: "Create a CRM case for the refund"
+			target: "flow://Create_CRM_Case"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+				refund_amount: object
+					description: "Refund amount"
+					complex_data_type_name: "lightning__numberType"
+			outputs:
+				case_id: string
+					description: "Created case ID"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == False:
+				transition to @subagent.identity_verification
+
+			if @variables.refund_status == "Approved":
+				run @actions.create_crm_case
+					with customer_id = @variables.ContactId
+					with refund_amount = @variables.refund_amount
+				transition to @subagent.success_confirmation
+
+			run @actions.check_churn_risk
+				with customer_id = @variables.ContactId
+				set @variables.churn_risk_score = @outputs.score
+
+			| Customer risk score: {!@variables.churn_risk_score}
+
+			if @variables.churn_risk_score >= 80:
+				| HIGH RISK - Offer a full cash refund to retain this customer.
+			else:
+				| STANDARD - Offer a $10 store credit as goodwill.
+
+		actions:
+			approve_full_refund: @actions.process_refund
+				description: "Approve full cash refund"
+				available when @variables.churn_risk_score >= 80
+				with refund_type = "full"
+				set @variables.refund_status = @outputs.status
+
+			offer_credit: @actions.issue_credit
+				description: "Offer store credit"
+				available when @variables.churn_risk_score < 80
+				with amount = 10
+				set @variables.refund_status = @outputs.status
+
+subagent success_confirmation:
+	label: "Success Confirmation"
+	description: "Confirm successful operation"
+	reasoning:
+		instructions: |
+			Great news! Your request has been processed successfully.
+			Is there anything else I can help you with?
+		actions:
+			new_request: @utils.transition to @subagent.agent_router
+				description: "Start a new request"
+
+subagent escalation:
+	label: "Escalation"
+	description: "Escalate to human agent"
+	reasoning:
+		instructions: |
+			I'm transferring you to a human agent who can better assist you.
+			Please hold while I connect you.
+		actions:
+			handoff: @utils.escalate
+				description: "Transfer to human agent"

package/skills/agentforce-generate/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-generate/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 --json --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-generate/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 subagent block
+#
+# Usage: Replace {{placeholders}} with your values
+# Place this inside a subagent'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 subagent'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)