@salesforce/afv-skills 1.1.0 → 1.2.0

package/skills/agentforce-development/assets/agents/README.md

@@ -0,0 +1,45 @@
+# Complete Agent Templates
+
+Templates for building complete, deployable agents.
+
+## Learning Path
+
+| Template | Complexity | Description |
+|----------|------------|-------------|
+| `hello-world.agent` | Beginner | Minimal viable agent - start here |
+| `simple-qa.agent` | Beginner | Single-topic Q&A agent |
+| `multi-topic.agent` | Intermediate | Multi-topic routing agent |
+| `production-faq.agent` | Advanced | Production-ready FAQ with escalation |
+
+## Quick Start
+
+1. Copy a template to your SFDX project:
+   ```bash
+   mkdir -p force-app/main/default/aiAuthoringBundles/My_Agent
+   cp hello-world.agent force-app/main/default/aiAuthoringBundles/My_Agent/My_Agent.agent
+   cp ../metadata/bundle-meta.xml force-app/main/default/aiAuthoringBundles/My_Agent/My_Agent.bundle-meta.xml
+   ```
+
+2. Validate and deploy:
+   ```bash
+   sf agent validate authoring-bundle --api-name My_Agent --target-org your-org
+   sf agent publish authoring-bundle --api-name My_Agent --target-org your-org
+   ```
+
+## Required Blocks
+
+Every agent must have these blocks **in this order**:
+
+| Block | Purpose |
+|-------|---------|
+| `system:` | Agent personality and default messages |
+| `config:` | Deployment metadata (agent_name, label, etc.) |
+| `variables:` | Data connections and state storage |
+| `language:` | Locale configuration |
+| `start_agent` | Entry point topic (exactly one required) |
+
+## Next Steps
+
+- [components/](../components/) - Reusable action and topic templates
+- [patterns/](../patterns/) - Advanced patterns for complex behaviors
+- [metadata/](../metadata/) - XML metadata templates

package/skills/agentforce-development/assets/agents/hello-world.agent

@@ -0,0 +1,60 @@
+# Hello World Agent
+# The minimal viable Agentforce agent - start here!
+#
+# This template shows the absolute minimum structure required for a working agent.
+# Use this as your starting point when learning Agent Script.
+#
+# ★ Why This Structure?
+#   - system: Sets agent personality and default messages
+#   - config: Required metadata for deployment (agent_name must be unique)
+#   - variables: Linked variables connect to Messaging context (required for deployment)
+#   - language: Locale settings (required for deployment)
+#   - start_agent: Entry point topic (exactly one required)
+#
+# ★ Key Validation Points (from 100-point scoring):
+#   - [10 pts] config block with all 4 required fields
+#   - [10 pts] 3 linked variables (EndUserId, RoutableId, ContactId)
+#   - [5 pts] language block present
+#   - [10 pts] At least one start_agent topic
+#
+# Deploy with: sf agent publish authoring-bundle --api-name Hello_World_Agent --target-org [alias]
+
+system:
+	instructions: "You are a friendly assistant. Greet users warmly and help them."
+	messages:
+		welcome: "Hello! I'm here to help. What can I do for you today?"
+		error: "I'm sorry, something went wrong. Please try again."
+
+config:
+	agent_name: "Hello_World_Agent"
+	default_agent_user: "your.user@company.com"
+	agent_label: "Hello World Agent"
+	description: "A minimal example agent to learn Agent Script basics"
+
+variables:
+	# Linked variables (required) - Connect to Salesforce 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"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+# Entry point topic - this is where every conversation starts
+start_agent main:
+	label: "Main"
+	description: "Greets users and provides help"
+
+	reasoning:
+		instructions: ->
+			| Welcome the user warmly.
+			| Ask how you can help them today.
+			| Be friendly and conversational.

package/skills/agentforce-development/assets/agents/multi-topic.agent

@@ -0,0 +1,105 @@
+# Multi-Topic Agent Template
+# An agent with multiple conversation topics (hub-and-spoke pattern)
+# Users are routed to specialized topics based on their needs
+#
+# Usage: Replace {{placeholders}} with your values
+# Required: agent_name, default_agent_user, agent_label, description
+# Required: At least 2 topics with label and 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_intent: mutable string
+		description: "What the user is trying to accomplish"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	label: "Topic Selector"
+	description: "Routes users to the appropriate topic based on their needs"
+
+	reasoning:
+		instructions: ->
+			| Determine what the user needs help with.
+			| Route them to the most appropriate topic.
+			| If unclear, ask clarifying questions.
+		actions:
+			go_to_topic_one: @utils.transition to @topic.{{topic_one_name}}
+			go_to_topic_two: @utils.transition to @topic.{{topic_two_name}}
+			go_to_topic_three: @utils.transition to @topic.{{topic_three_name}}
+			go_to_farewell: @utils.transition to @topic.farewell
+			go_to_escalation: @utils.transition to @topic.escalation
+
+topic {{topic_one_name}}:
+	label: "{{TopicOneLabel}}"
+	description: "{{TopicOneDescription}}"
+
+	reasoning:
+		instructions: ->
+			| {{TopicOneInstructions}}
+		actions:
+			back_to_menu: @utils.transition to @topic.topic_selector
+
+topic {{topic_two_name}}:
+	label: "{{TopicTwoLabel}}"
+	description: "{{TopicTwoDescription}}"
+
+	reasoning:
+		instructions: ->
+			| {{TopicTwoInstructions}}
+		actions:
+			back_to_menu: @utils.transition to @topic.topic_selector
+
+topic {{topic_three_name}}:
+	label: "{{TopicThreeLabel}}"
+	description: "{{TopicThreeDescription}}"
+
+	reasoning:
+		instructions: ->
+			| {{TopicThreeInstructions}}
+		actions:
+			back_to_menu: @utils.transition to @topic.topic_selector
+
+topic farewell:
+	label: "Farewell"
+	description: "Ends the conversation gracefully"
+
+	reasoning:
+		instructions: ->
+			| Thank the user for reaching out.
+			| Wish them a great day.
+			| Let them know they can return anytime.
+
+topic escalation:
+	label: "Escalation"
+	description: "Handles requests to transfer to a live human agent"
+
+	reasoning:
+		instructions: ->
+			| If the user explicitly asks to speak with a human, escalate.
+			| Acknowledge the request and transfer gracefully.
+		actions:
+			escalate_to_human: @utils.escalate
+				description: "Escalate to a human agent"

package/skills/agentforce-development/assets/agents/production-faq.agent

@@ -0,0 +1,101 @@
+# Simple FAQ Agent
+# A minimal working example of an Agentforce agent
+# Uses pure LLM reasoning without external actions
+#
+# Deploy with: sf agent publish authoring-bundle --api-name Simple_FAQ_Agent --target-org [alias]
+
+system:
+	instructions: "You are a helpful FAQ assistant for our company. Answer questions accurately and concisely. If you don't know the answer, say so honestly. Never share sensitive or confidential information. Keep responses friendly and professional."
+	messages:
+		welcome: "Hello! I'm your FAQ assistant. How can I help you today?"
+		error: "I'm sorry, I encountered an issue. Please try again."
+
+config:
+	agent_name: "Simple_FAQ_Agent"
+	default_agent_user: "agent.user@company.com"
+	agent_label: "Simple FAQ Agent"
+	description: "A minimal FAQ agent that answers common questions using AI"
+
+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_question: mutable string
+		description: "The user's current question"
+	conversation_topic: mutable string
+		description: "The current topic being discussed"
+	question_count: mutable number
+		description: "Number of questions answered in this session"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	label: "Topic Selector"
+	description: "Routes incoming questions to the FAQ handler"
+
+	reasoning:
+		instructions: ->
+			| Listen to the user's question and determine how to help.
+			| If the question is about a specific topic, note it.
+			| Route to the FAQ handler for processing.
+		actions:
+			handle_faq: @utils.transition to @topic.faq_handler
+			end_conversation: @utils.transition to @topic.farewell
+
+topic faq_handler:
+	label: "FAQ Handler"
+	description: "Handles frequently asked questions and provides helpful answers"
+
+	reasoning:
+		instructions: ->
+			| Answer the user's question based on your knowledge.
+			| Be helpful, accurate, and concise.
+			| Keep responses under 3-4 sentences when possible.
+			| If you need more information, ask clarifying questions.
+			|
+			| Common topics you can help with:
+			| - Business hours and location
+			| - Return and refund policies
+			| - Shipping information
+			| - Product questions
+			| - Account and billing
+			|
+			| If the question is outside your knowledge:
+			| - Acknowledge you don't have that information
+			| - Suggest contacting customer support
+			| - Offer to help with something else
+		actions:
+			new_question: @utils.transition to @topic.topic_selector
+			end_conversation: @utils.transition to @topic.farewell
+			escalate: @utils.transition to @topic.escalation
+
+topic farewell:
+	label: "Farewell"
+	description: "Ends the conversation politely"
+
+	reasoning:
+		instructions: ->
+			| Thank the user for their questions.
+			| Wish them a great day.
+			| Let them know they can return anytime for more help.
+
+topic escalation:
+	label: "Escalation"
+	description: "Handles requests to speak with a human agent"
+
+	reasoning:
+		instructions: ->
+			| If the user wants to speak with a human, escalate gracefully.
+			| Acknowledge their request and transfer the conversation.
+		actions:
+			escalate_to_human: @utils.escalate
+				description: "Transfer to a human agent"

package/skills/agentforce-development/assets/agents/production-faq.bundle-meta.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+  <bundleType>AGENT</bundleType>
+</AiAuthoringBundle>

package/skills/agentforce-development/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 topic_selector:
+	label: "Topic Selector"
+	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 @topic.qa_handler
+			end_conversation: @utils.transition to @topic.farewell
+
+topic 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 @topic.topic_selector
+			end_conversation: @utils.transition to @topic.farewell
+
+topic 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-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>