@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/components/n-ary-conditions.agent

@@ -0,0 +1,110 @@
+# N-ary Boolean Conditions Template
+# Demonstrates using 3+ conditions with and/or operators
+#
+# This is a PARTIAL template - integrate into a complete agent file
+#
+# ★ KEY CONCEPTS:
+#
+#   N-ary AND: All conditions must be true
+#   N-ary OR:  At least one condition must be true
+#   Grouping:  Use () for complex expressions
+#
+# ★ Supported Contexts:
+#   - if statements in before_reasoning/after_reasoning
+#   - available when clauses on actions
+#
+# ★ Common Mistake:
+#   DO NOT nest if statements. Use N-ary and/or instead.
+#   ❌ if a: if b: if c: (nested - INVALID)
+#   ✅ if a and b and c:   (flat - CORRECT)
+
+# ═══════════════════════════════════════════════════════════════
+# PATTERN 1: Three+ AND conditions in lifecycle
+# ═══════════════════════════════════════════════════════════════
+
+# Example: Require multiple authentication checks
+topic secure_action:
+	label: "Secure Action"
+	description: "Performs security-sensitive operations"
+
+	before_reasoning:
+		# All three conditions must be true
+		if @variables.is_authenticated and @variables.has_permission and @variables.session_valid:
+			transition to @topic.authorized_action
+		# Otherwise stay in this topic
+
+	reasoning:
+		instructions: ->
+			| User needs to authenticate before proceeding.
+
+# ═══════════════════════════════════════════════════════════════
+# PATTERN 2: Three+ OR conditions in lifecycle
+# ═══════════════════════════════════════════════════════════════
+
+# Example: Any elevated role gets access
+topic admin_panel:
+	label: "Admin Panel"
+	description: "Administrative features"
+
+	before_reasoning:
+		# Any one of these roles grants access
+		if @variables.is_admin or @variables.is_moderator or @variables.is_superuser:
+			transition to @topic.admin_features
+		# Non-admins redirected
+		transition to @topic.access_denied
+
+# ═══════════════════════════════════════════════════════════════
+# PATTERN 3: N-ary conditions in available when
+# ═══════════════════════════════════════════════════════════════
+
+topic order_management:
+	label: "Order Management"
+	description: "Handles order operations"
+
+	reasoning:
+		instructions: ->
+			| Help the customer with their order.
+		actions:
+			# Action available only when ALL conditions met
+			process_return: @actions.handle_return
+				description: "Process a return request"
+				available when @variables.order_exists == True and @variables.within_return_window == True and @variables.item_eligible == True
+
+			# Action available when ANY premium tier matches
+			use_priority: @actions.priority_service
+				description: "Use priority service queue"
+				available when @variables.tier == "gold" or @variables.tier == "platinum" or @variables.tier == "enterprise"
+
+			# Mixed: specific product AND any valid status
+			expedite: @actions.expedite_order
+				description: "Expedite the current order"
+				available when @variables.product_type == "perishable" and (@variables.status == "pending" or @variables.status == "processing")
+
+# ═══════════════════════════════════════════════════════════════
+# PATTERN 4: Complex grouped conditions
+# ═══════════════════════════════════════════════════════════════
+
+topic smart_routing:
+	label: "Smart Routing"
+	description: "Routes based on complex criteria"
+
+	before_reasoning:
+		# Premium with any product type OR standard with warranty
+		if (@variables.tier == "premium" and @variables.product_type != None) or (@variables.tier == "standard" and @variables.has_warranty == True):
+			transition to @topic.priority_support
+
+# ═══════════════════════════════════════════════════════════════
+# ANTI-PATTERNS - DO NOT USE
+# ═══════════════════════════════════════════════════════════════
+
+# ❌ WRONG - Nested if statements (causes "Missing required element" error)
+# before_reasoning:
+#    if @variables.a == True:
+#       if @variables.b == True:
+#          if @variables.c == True:
+#             transition to @topic.x
+
+# ✅ CORRECT - Flat N-ary condition
+# before_reasoning:
+#    if @variables.a == True and @variables.b == True and @variables.c == True:
+#       transition to @topic.x

package/skills/agentforce-development/assets/components/topic-with-actions.agent

@@ -0,0 +1,40 @@
+# Topic with Actions Template
+# A topic that integrates with external systems via Flow or Apex actions
+# This is a PARTIAL template - use within a complete agent file
+#
+# Two-Level Action System:
+#   Level 1: topic.actions block DEFINES actions (with target:, inputs:, outputs:)
+#   Level 2: reasoning.actions block INVOKES them (with @actions.name, with/set)
+#
+# Usage: Replace {{placeholders}} with your values
+# Note: Actions defined inside topic are local to that topic
+
+topic {{topic_name}}:
+	description: "{{TopicDescription}}"
+
+	# Level 1: DEFINE actions available to this topic
+	actions:
+		{{action_name}}:
+			description: "{{ActionDescription}}"
+			inputs:
+				{{input_name}}: {{input_type}}
+					description: "{{InputDescription}}"
+			outputs:
+				{{output_name}}: {{output_type}}
+					description: "{{OutputDescription}}"
+			target: "{{ActionTarget}}"  # flow://FlowName or apex://ClassName
+
+	reasoning:
+		instructions: ->
+			| {{TopicInstructions}}
+			| Use the available actions to help the user.
+			| Capture and communicate results clearly.
+
+		# Level 2: INVOKE the actions defined above
+		actions:
+			invoke_action: @actions.{{action_name}}
+				with {{input_name}}=...
+				set @variables.{{result_variable}} = @outputs.{{output_name}}
+
+			back_to_menu: @utils.transition to @topic.topic_selector
+				description: "Return to main menu"

package/skills/agentforce-development/assets/deterministic-routing.agent

@@ -0,0 +1,166 @@
+# Deterministic Routing Template (Zero-Hallucination Pattern)
+# ============================================================
+#
+# This template demonstrates the zero-hallucination intent classification
+# pattern using action output flags to control LLM behavior.
+#
+# Pattern: Classify intent deterministically, route without hallucination
+# Use when: Critical routing decisions that must not be influenced by LLM creativity
+#
+# KEY PATTERN:
+# In Agentforce Assets, set action outputs with:
+# - is_displayable: False  (LLM cannot show this to user)
+# - is_used_by_planner: True  (LLM can use for routing)
+#
+# This ensures the LLM routes based on classification but cannot
+# generate hallucinated responses based on the classification data.
+
+system:
+   messages:
+      welcome: "Hello! How can I help you today?"
+      error: "I apologize, something went wrong. Let me try again."
+   instructions: "You are a customer service agent. Route users to the correct department based on their intent."
+
+config:
+   agent_name: "DeterministicRoutingAgent"
+   agent_label: "Smart Router Agent"
+   description: "Agent demonstrating zero-hallucination intent routing pattern"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+variables:
+   # Intent classification (populated by action with is_displayable: False)
+   classified_intent: mutable string = ""
+      description: "Classification result - hidden from user responses"
+   confidence_score: mutable number = 0
+      description: "Classification confidence (0-100)"
+
+   # Routing state
+   needs_classification: mutable boolean = True
+      description: "Whether user intent needs classification"
+   low_confidence_warning: mutable boolean = False
+      description: "Flag for low confidence routing"
+
+start_agent topic_selector:
+   description: "Classify intent and route deterministically"
+   reasoning:
+      instructions: ->
+         # ====================================================
+         # DETERMINISTIC ROUTING (based on classified_intent)
+         # ====================================================
+
+         # Route ONLY when classification is complete
+         if @variables.needs_classification == False:
+
+            # HIGH-CONFIDENCE ROUTING
+            if @variables.confidence_score >= 80:
+               if @variables.classified_intent == "billing":
+                  transition to @topic.billing
+               if @variables.classified_intent == "technical_support":
+                  transition to @topic.technical_support
+               if @variables.classified_intent == "sales":
+                  transition to @topic.sales
+               if @variables.classified_intent == "returns":
+                  transition to @topic.returns
+
+            # LOW-CONFIDENCE: Confirm with user
+            if @variables.confidence_score < 80:
+               set @variables.low_confidence_warning = True
+               | I want to make sure I route you correctly.
+               | It sounds like you need help with **{!@variables.classified_intent}**.
+               | Is that correct?
+
+         # INITIAL STATE: Ask for help topic
+         if @variables.needs_classification == True:
+            | I can help with billing, technical support, sales, or returns.
+            | What do you need help with today?
+
+      actions:
+         # CRITICAL: This action's outputs must be configured in Agentforce Assets:
+         # - classified_intent: is_displayable=False, is_used_by_planner=True
+         # - confidence_score: is_displayable=False, is_used_by_planner=True
+         #
+         # This ensures LLM cannot hallucinate based on classification data
+         classify_intent: @actions.Classify_User_Intent
+            description: "Determine what the user needs help with"
+            with user_message = ...  # LLM extracts from conversation
+            set @variables.classified_intent = @outputs.intent
+            set @variables.confidence_score = @outputs.confidence
+            set @variables.needs_classification = False
+
+         # Manual routing for low-confidence cases
+         go_billing: @utils.transition to @topic.billing
+            description: "Yes, I need billing help"
+            available when @variables.low_confidence_warning == True and @variables.classified_intent == "billing"
+
+         go_support: @utils.transition to @topic.technical_support
+            description: "Yes, I need technical support"
+            available when @variables.low_confidence_warning == True and @variables.classified_intent == "technical_support"
+
+         go_sales: @utils.transition to @topic.sales
+            description: "Yes, I need sales help"
+            available when @variables.low_confidence_warning == True and @variables.classified_intent == "sales"
+
+         go_returns: @utils.transition to @topic.returns
+            description: "Yes, I need returns help"
+            available when @variables.low_confidence_warning == True and @variables.classified_intent == "returns"
+
+         # Reclassify if user said "no"
+         reclassify: @utils.setVariables
+            description: "That's not what I need - let me clarify"
+            available when @variables.low_confidence_warning == True
+            with needs_classification = True
+            with classified_intent = ""
+            with confidence_score = 0
+            with low_confidence_warning = False
+
+# ============================================================
+# ROUTED TOPICS
+# ============================================================
+
+topic billing:
+   description: "Handle billing inquiries"
+   reasoning:
+      instructions: |
+         Help the customer with their billing question.
+         You can view invoices, explain charges, or process payments.
+      actions:
+         back: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+         escalate_now: @utils.escalate
+            description: "Transfer to billing specialist"
+
+topic technical_support:
+   description: "Handle technical support issues"
+   reasoning:
+      instructions: |
+         Help the customer with their technical issue.
+         Troubleshoot problems and provide solutions.
+      actions:
+         back: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+         escalate_now: @utils.escalate
+            description: "Transfer to technical specialist"
+
+topic sales:
+   description: "Handle sales inquiries"
+   reasoning:
+      instructions: |
+         Help the customer with sales questions.
+         Provide product information and pricing.
+      actions:
+         back: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+         escalate_now: @utils.escalate
+            description: "Transfer to sales representative"
+
+topic returns:
+   description: "Handle return requests"
+   reasoning:
+      instructions: |
+         Help the customer with their return request.
+         Check eligibility and process returns.
+      actions:
+         back: @utils.transition to @topic.topic_selector
+            description: "Return to main menu"
+         escalate_now: @utils.escalate
+            description: "Transfer to returns specialist"

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"