@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/patterns/lifecycle-events.agent

@@ -0,0 +1,127 @@
+# Lifecycle Events Pattern
+# Use before_reasoning and after_reasoning for initialization and cleanup
+#
+# ★ When To Use This Pattern:
+#   - Initialize state BEFORE the LLM starts reasoning
+#   - Track metrics (turn count, session duration)
+#   - Clean up or log AFTER reasoning completes
+#   - Set up context that instructions need to reference
+#
+# ★ Key Insight:
+#   - before_reasoning: Runs BEFORE each reasoning step (use for setup)
+#   - after_reasoning: Runs AFTER each reasoning step (use for cleanup/logging)
+#   - These are deterministic - they ALWAYS run, unlike LLM-chosen actions
+#
+# ★ CRITICAL SYNTAX RULES for Lifecycle Blocks:
+#   1. Use "transition to" NOT "@utils.transition to" for transitions
+#   2. The pipe (|) command is NOT supported in lifecycle blocks
+#   3. after_reasoning may NOT run if a transition occurs mid-topic
+#   4. `run` has inconsistent runtime behavior in lifecycle blocks —
+#      reliable primitives are `set`, `if`/`else`, `transition to`
+#
+# ★ Common Use Cases:
+#   - Increment conversation turn counter
+#   - Fetch fresh data before each response
+#   - Log conversation analytics after each turn
+#   - Reset temporary flags
+#   - Conditional routing based on state (use "transition to")
+#
+# This is a PARTIAL template - integrate into a complete agent file
+
+# Variables needed for lifecycle tracking
+variables:
+	# ... standard linked variables ...
+	turn_count: mutable number = 0
+		description: "Number of turns in conversation"
+	session_start: mutable string = ""
+		description: "Timestamp when session started"
+	last_activity: mutable string = ""
+		description: "Timestamp of last activity"
+	current_context: mutable string = ""
+		description: "Refreshed context for current turn"
+
+topic conversation:
+	label: "Conversation"
+	description: "Main conversation topic with lifecycle tracking"
+
+	actions:
+		get_timestamp:
+			description: "Gets current timestamp"
+			outputs:
+				current_timestamp: string
+					description: "Current ISO timestamp"
+			target: "apex://TimeService.getCurrentTimestamp"
+
+		refresh_context:
+			description: "Fetches latest context for user"
+			inputs:
+				user_id: string
+					description: "User to get context for"
+			outputs:
+				context: string
+					description: "User's current context"
+			target: "flow://Get_User_Context"
+
+		log_turn:
+			description: "Logs conversation turn analytics"
+			inputs:
+				turn_number: number
+					description: "Which turn this is"
+				topic_name: string
+					description: "Current topic"
+			outputs:
+				logged: boolean
+					description: "Whether log succeeded"
+			target: "apex://AnalyticsService.logTurn"
+
+	# ★ before_reasoning: Runs BEFORE each reasoning step
+	before_reasoning:
+		# Increment turn counter
+		set @variables.turn_count = @variables.turn_count + 1
+
+		# On first turn, record session start
+		if @variables.turn_count == 1:
+			run @actions.get_timestamp
+				set @variables.session_start = @outputs.current_timestamp
+
+		# ★ CORRECT: Use "transition to" (not @utils.transition to) in lifecycle blocks
+		# Example: Route away if session expired
+		# if @variables.session_expired == True:
+		#    transition to @topic.session_expired
+
+		# Refresh context before every turn
+		run @actions.refresh_context
+			with user_id=@variables.EndUserId
+			set @variables.current_context = @outputs.context
+
+	# Main reasoning block
+	reasoning:
+		instructions: ->
+			| You are on turn {!@variables.turn_count} of this conversation.
+			| Session started: {!@variables.session_start}
+			|
+			| Current user context:
+			| {!@variables.current_context}
+			|
+			| Respond helpfully using the refreshed context above.
+		actions:
+			end_conversation: @utils.transition to @topic.farewell
+
+	# ★ after_reasoning: Runs AFTER each reasoning step
+	after_reasoning:
+		# Log analytics for each turn
+		run @actions.log_turn
+			with turn_number=@variables.turn_count
+			with topic_name="conversation"
+
+		# Update last activity timestamp
+		run @actions.get_timestamp
+			set @variables.last_activity = @outputs.current_timestamp
+
+# ★ Insight: Lifecycle blocks vs Action callbacks
+#
+# - before_reasoning/after_reasoning: Run every turn, automatic
+# - run callbacks: Run only when parent action is invoked
+#
+# Use lifecycle for: Metrics, context refresh, session management
+# Use callbacks for: Post-action processing, chained operations

package/skills/agentforce-development/assets/patterns/llm-controlled-actions.agent

@@ -0,0 +1,184 @@
+# LLM-Controlled Actions Pattern
+# Demonstrates both deterministic and LLM-controlled action invocation
+#
+# ★ When To Use This Pattern:
+#   - When the LLM should decide which actions to invoke based on context
+#   - When actions should only be available under certain conditions
+#   - When you want the agent to make intelligent choices about tool usage
+#
+# ★ Key Insight:
+#   - Deterministic: "run @actions.x" - ALWAYS runs when code path is reached
+#   - LLM-Controlled: "{!@actions.x}" in instructions - LLM decides based on context
+#   - Tools in reasoning.actions - LLM chooses which to invoke
+#
+# ★ Two Invocation Methods:
+#   1. Deterministic (run @actions.x): Use in before/after_reasoning, action callbacks
+#   2. LLM-Controlled ({!@actions.x}): Reference in reasoning instructions
+#
+# This is a PARTIAL template - integrate into a complete agent file
+
+# Variables for tracking action context
+variables:
+	# ... standard linked variables ...
+	has_order_id: mutable boolean = False
+		description: "Whether user has provided an order ID"
+	order_id: mutable string
+		description: "The order ID provided by user"
+	action_taken: mutable string
+		description: "Last action taken by agent"
+
+topic order_assistance:
+	label: "Order Assistance"
+	description: "Helps customers with order-related questions"
+
+	# Define available actions
+	actions:
+		get_order_status:
+			description: "Retrieves order status by order ID"
+			inputs:
+				order_id: string
+					description: "The order ID to look up"
+			outputs:
+				status: string
+					description: "Current order status"
+				delivery_date: string
+					description: "Expected delivery date"
+			target: "flow://Get_Order_Status"
+
+		update_order:
+			description: "Updates an existing order"
+			require_user_confirmation: True    # ★ Ask user before executing
+			inputs:
+				order_id: string
+					description: "Order to update"
+				changes: string
+					description: "Changes to make"
+			outputs:
+				success: boolean
+					description: "Whether update succeeded"
+			target: "flow://Update_Order"
+
+		cancel_order:
+			description: "Cancels an order"
+			require_user_confirmation: True    # ★ Destructive action - confirm first
+			include_in_progress_indicator: True
+			inputs:
+				order_id: string
+					description: "Order to cancel"
+				reason: string
+					description: "Cancellation reason"
+			outputs:
+				refund_amount: number
+					description: "Refund amount"
+					filter_from_agent: False     # Show this to LLM
+			target: "flow://Cancel_Order"
+
+		log_interaction:
+			description: "Logs customer interaction for analytics"
+			inputs:
+				interaction_type: string
+					description: "Type of interaction"
+			outputs:
+				logged: boolean
+					description: "Whether log succeeded"
+			target: "flow://Log_Interaction"
+
+	# ★ Deterministic logging before reasoning
+	before_reasoning:
+		run @actions.log_interaction
+			with interaction_type="order_inquiry"
+
+	reasoning:
+		# ★ LLM-Controlled: Reference actions in natural language
+		# The LLM decides when to use these based on conversation context
+		instructions: ->
+			| Help the customer with their order inquiry.
+			|
+			| Available capabilities:
+			| - Use {!@actions.get_order_status} to look up order details when they provide an order ID
+			| - Use {!@actions.update_order} if they want to modify their order (requires confirmation)
+			| - Use {!@actions.cancel_order} if they want to cancel (requires confirmation)
+			|
+			| Always confirm destructive actions before proceeding.
+			| If they haven't provided an order ID, ask for it first.
+
+		# ★ Tools: LLM chooses which to invoke based on conversation
+		actions:
+			# Slot filling - LLM extracts order_id from conversation
+			lookup: @actions.get_order_status
+				with order_id=...
+				set @variables.order_id = @outputs.status
+
+			# Conditional availability - only show when order ID is known
+			update: @actions.update_order
+				with order_id=@variables.order_id
+				with changes=...
+				available when @variables.has_order_id == True
+
+			# Conditional availability with multiple conditions
+			cancel: @actions.cancel_order
+				with order_id=@variables.order_id
+				with reason=...
+				available when @variables.has_order_id == True
+				available when @variables.order_status != "shipped"
+
+			# Topic transitions
+			go_help: @utils.transition to @topic.general_help
+			go_escalation: @utils.transition to @topic.escalation
+				available when @variables.needs_human == True
+
+# ★ Insight: When to Use Each Method
+#
+# DETERMINISTIC (run @actions.x):
+#   - Audit logging (must always run)
+#   - Required follow-up actions
+#   - Guaranteed side effects
+#   - In before_reasoning / after_reasoning blocks
+#   - In action callbacks (run after parent)
+#
+# LLM-CONTROLLED (reasoning.actions or {!@actions.x}):
+#   - User-driven choices
+#   - Context-dependent operations
+#   - Optional actions based on conversation
+#   - When intelligence is needed to decide
+#
+# CONDITIONAL (available when):
+#   - Guard destructive operations
+#   - Show options only when prerequisites met
+#   - Enforce business rules
+
+# ★ Example: Action Callback Pattern (Deterministic Chaining)
+# Use "run" for guaranteed follow-up actions after a primary action
+
+topic checkout:
+	label: "Checkout"
+	description: "Handles order checkout"
+
+	actions:
+		create_order:
+			description: "Creates a new order"
+			inputs:
+				items: list[string]
+					description: "Items to order"
+			outputs:
+				order_id: string
+					description: "Created order ID"
+			target: "flow://Create_Order"
+
+		send_confirmation:
+			description: "Sends order confirmation email"
+			inputs:
+				order_id: string
+					description: "Order to confirm"
+			target: "flow://Send_Confirmation"
+
+	reasoning:
+		instructions: ->
+			| Process the customer's checkout request.
+		actions:
+			# ★ Action callback: send_confirmation ALWAYS runs after create_order
+			process_checkout: @actions.create_order
+				with items=...
+				set @variables.order_id = @outputs.order_id
+				run @actions.send_confirmation                # ★ Guaranteed to run
+					with order_id=@variables.order_id

package/skills/agentforce-development/assets/patterns/multi-step-workflow.agent

@@ -0,0 +1,282 @@
+# Multi-Step Workflow Pattern
+# Track progress through complex multi-stage processes using boolean flags
+#
+# ★ When To Use This Pattern:
+#   - User onboarding with multiple steps
+#   - Order/checkout processes
+#   - Application submissions (loan, support case, etc.)
+#   - Any workflow requiring completion tracking
+#
+# ★ Key Insights:
+#   - Use boolean flags to track step completion
+#   - Use number variable for step counter
+#   - Conditionally show instructions based on completion state
+#   - Chain actions with `run` for deterministic sequences
+#
+# ★ Why This Pattern:
+#   - Clear visibility into workflow progress
+#   - Resume interrupted workflows
+#   - Prevent skipping required steps
+#   - Show progress indicators to users
+#
+# This is a COMPLETE template - customize for your use case
+#
+# ★ Step Guard Pattern (Feb 2026 Community Best Practice):
+#   - The topic selector re-evaluates on EVERY user utterance
+#   - Without a step guard, follow-up messages ("my email is X") get re-routed
+#   - The `if @variables.current_step > 1:` guard in start_agent forces
+#     re-entry to the current workflow, bypassing LLM topic selection
+#   - Reset current_step to 1 when the workflow completes
+
+system:
+	instructions: "You are an onboarding assistant. Guide users through the account setup process step by step. Ensure all required steps are completed before finishing."
+	messages:
+		welcome: "Welcome! I'll help you set up your account. Let's go through this step by step."
+		error: "I encountered an issue. Let me try to continue from where we left off."
+
+config:
+	agent_name: "Onboarding_Agent"
+	default_agent_user: "agent@company.salesforce.com"
+	agent_label: "Onboarding Assistant"
+	description: "Guides users through multi-step onboarding workflow"
+
+variables:
+	# Standard linked variables
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+
+	# ★ WORKFLOW PROGRESS TRACKING - Boolean flags for each step
+	step_1_account_created: mutable boolean = False
+		description: "Step 1: Account has been created"
+	step_2_profile_completed: mutable boolean = False
+		description: "Step 2: Profile information has been collected"
+	step_3_preferences_set: mutable boolean = False
+		description: "Step 3: User preferences have been configured"
+	step_4_verification_done: mutable boolean = False
+		description: "Step 4: Email/phone verification completed"
+	onboarding_complete: mutable boolean = False
+		description: "All onboarding steps are complete"
+
+	# ★ STEP COUNTER - For progress indication
+	current_step: mutable number = 1
+		description: "Current step number (1-4)"
+	total_steps: mutable number = 4
+		description: "Total number of steps"
+
+	# Data collected during workflow
+	customer_id: mutable string = ""
+		description: "Created customer ID"
+	user_email: mutable string = ""
+		description: "User's email address"
+	user_name: mutable string = ""
+		description: "User's full name"
+	phone_number: mutable string = ""
+		description: "User's phone number"
+	notification_preference: mutable string = "email"
+		description: "Preferred notification method"
+	verification_code: mutable string = ""
+		description: "Verification code for confirmation"
+
+language:
+	default_locale: "en_US"
+
+start_agent onboarding:
+	description: "Multi-step account onboarding workflow"
+
+	actions:
+		# Step 1: Create account
+		create_account:
+			description: "Create a new customer account"
+			inputs:
+				email: string
+					description: "Customer email address"
+					is_required: True
+				name: string
+					description: "Customer full name"
+					is_required: True
+			outputs:
+				customer_id: string
+					description: "Newly created customer ID"
+				success: boolean
+					description: "Whether account creation succeeded"
+			target: "flow://Create_Customer_Account"
+
+		# Step 2: Update profile
+		update_profile:
+			description: "Update customer profile information"
+			inputs:
+				customer_id: string
+					description: "Customer ID to update"
+					is_required: True
+				phone: string
+					description: "Phone number"
+					is_required: False
+			outputs:
+				success: boolean
+					description: "Whether profile update succeeded"
+			target: "flow://Update_Customer_Profile"
+
+		# Step 3: Set preferences
+		set_preferences:
+			description: "Configure customer notification preferences"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+					is_required: True
+				notification_method: string
+					description: "Preferred notification method: email, sms, or both"
+					is_required: True
+			outputs:
+				success: boolean
+					description: "Whether preferences were saved"
+			target: "flow://Set_Customer_Preferences"
+
+		# Step 4: Send verification
+		send_verification:
+			description: "Send verification code to customer"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+					is_required: True
+				method: string
+					description: "Verification method: email or sms"
+					is_required: True
+			outputs:
+				success: boolean
+					description: "Whether verification was sent"
+			target: "flow://Send_Verification_Code"
+
+		# Verify code
+		verify_code:
+			description: "Verify the customer's code"
+			inputs:
+				customer_id: string
+					description: "Customer ID"
+					is_required: True
+				code: string
+					description: "Verification code entered by user"
+					is_required: True
+			outputs:
+				verified: boolean
+					description: "Whether code was correct"
+			target: "flow://Verify_Customer_Code"
+
+	reasoning:
+		instructions: ->
+			# ★ STEP GUARD — Force re-entry if workflow in progress
+			# This prevents the topic selector from re-routing the user
+			# mid-workflow when they provide follow-up information
+			if @variables.current_step > 1:
+				| Continuing your account setup...
+			# ★ PROGRESS DISPLAY - Show current status
+			| Welcome to account setup!
+			| Progress: Step {!@variables.current_step} of {!@variables.total_steps}
+			|
+			# ★ SHOW COMPLETED STEPS
+			if @variables.step_1_account_created == True:
+				| ✓ Step 1: Account Created
+			if @variables.step_1_account_created == False:
+				| ○ Step 1: Create Account (current)
+			if @variables.step_2_profile_completed == True:
+				| ✓ Step 2: Profile Complete
+			if @variables.step_2_profile_completed == False and @variables.step_1_account_created == True:
+				| ○ Step 2: Complete Profile (current)
+			if @variables.step_3_preferences_set == True:
+				| ✓ Step 3: Preferences Set
+			if @variables.step_3_preferences_set == False and @variables.step_2_profile_completed == True:
+				| ○ Step 3: Set Preferences (current)
+			if @variables.step_4_verification_done == True:
+				| ✓ Step 4: Verified
+			if @variables.step_4_verification_done == False and @variables.step_3_preferences_set == True:
+				| ○ Step 4: Verify Account (current)
+			|
+			# ★ STEP-SPECIFIC INSTRUCTIONS
+			if @variables.step_1_account_created == False:
+				| Let's start by creating your account.
+				| I'll need your email address and full name.
+
+			if @variables.step_1_account_created == True and @variables.step_2_profile_completed == False:
+				| Great! Account created. Now let's complete your profile.
+				| What's your phone number? (optional but recommended)
+
+			if @variables.step_2_profile_completed == True and @variables.step_3_preferences_set == False:
+				| Profile saved. Let's set your notification preferences.
+				| How would you like to receive notifications: email, sms, or both?
+
+			if @variables.step_3_preferences_set == True and @variables.step_4_verification_done == False:
+				| Almost done! I've sent a verification code.
+				| Please enter the code you received.
+
+			if @variables.onboarding_complete == True:
+				| 🎉 Congratulations! Your account is fully set up.
+				| Customer ID: {!@variables.customer_id}
+				| You're all ready to go!
+
+		actions:
+			# ★ STEP 1: Create Account
+			# Uses action chaining with `run` for automatic next step
+			do_step_1: @actions.create_account
+				with email=...
+				with name=...
+				set @variables.customer_id = @outputs.customer_id
+				set @variables.step_1_account_created = @outputs.success
+				set @variables.current_step = 2
+				available when @variables.step_1_account_created == False
+
+			# ★ STEP 2: Update Profile
+			do_step_2: @actions.update_profile
+				with customer_id=@variables.customer_id
+				with phone=...
+				set @variables.step_2_profile_completed = @outputs.success
+				set @variables.current_step = 3
+				available when @variables.step_1_account_created == True
+				available when @variables.step_2_profile_completed == False
+
+			# ★ STEP 3: Set Preferences
+			do_step_3: @actions.set_preferences
+				with customer_id=@variables.customer_id
+				with notification_method=...
+				set @variables.step_3_preferences_set = @outputs.success
+				set @variables.current_step = 4
+				# Automatically trigger verification after preferences
+				run @actions.send_verification
+					with customer_id=@variables.customer_id
+					with method=@variables.notification_preference
+				available when @variables.step_2_profile_completed == True
+				available when @variables.step_3_preferences_set == False
+
+			# ★ STEP 4: Verify
+			do_step_4: @actions.verify_code
+				with customer_id=@variables.customer_id
+				with code=...
+				set @variables.step_4_verification_done = @outputs.verified
+				set @variables.onboarding_complete = @outputs.verified
+				available when @variables.step_3_preferences_set == True
+				available when @variables.step_4_verification_done == False
+
+# ★ Insight: Multi-Step Workflow Best Practices
+#
+# BOOLEAN FLAGS:
+#   - One flag per step for clear completion tracking
+#   - Use meaningful names: step_1_account_created, not flag1
+#   - Check flags to enable/disable actions
+#
+# STEP COUNTER:
+#   - Provides simple progress indication
+#   - Can be used in template expressions for display
+#
+# ACTION AVAILABILITY:
+#   - Use `available when` to prevent out-of-order execution
+#   - Multiple `available when` clauses work as AND conditions
+#
+# ACTION CHAINING:
+#   - Use `run` for automatic sequential actions
+#   - Good for: send confirmation after save, log after complete
+#
+# RESUME CAPABILITY:
+#   - Boolean flags persist across conversation turns
+#   - User can pick up where they left off