@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/developing-agentforce/assets/patterns/bidirectional-routing.agent

@@ -1,156 +0,0 @@
-# Bidirectional Routing Pattern
-# Navigate to a specialist subagent and return with results
-#
-# ★ When To Use This Pattern:
-#   - Main subagent needs specialized processing then returns
-#   - "Consult a specialist" pattern (like asking an expert)
-#   - Complex workflows where you leave, do work, then come back
-#   - Alternative to cramming everything into one subagent
-#
-# ★ Key Insight:
-#   Standard transitions (@utils.transition) are one-way.
-#   For round-trip routing, store the "return address" in a variable.
-#   The specialist subagent transitions back when done.
-#
-# ★ Architecture Decision:
-#   Use this when you want separation of concerns:
-#   - Main subagent: Orchestration and user interaction
-#   - Specialist subagent: Focused, complex processing
-#
-# This is a PARTIAL template - integrate into a complete agent file
-
-variables:
-	# ... standard linked variables ...
-	return_subagent: mutable string = ""
-		description: "Subagent to return to after specialist consultation"
-	specialist_result: mutable string = ""
-		description: "Result from specialist subagent"
-	consultation_status: mutable string = ""
-		description: "Status of specialist consultation"
-
-# Main orchestration subagent
-start_agent main_hub:
-	label: "Main Hub"
-	description: "Central hub that routes to specialists and handles results"
-
-	reasoning:
-		instructions: ->
-			| You are the main coordinator.
-			| When user needs specialized help:
-			| - For pricing questions, consult the pricing specialist
-			| - For technical issues, consult the technical specialist
-			|
-			| After specialist returns, communicate their findings to the user.
-			|
-			| Current specialist result: {!@variables.specialist_result}
-			| Consultation status: {!@variables.consultation_status}
-		actions:
-			# Route to pricing specialist (store return address first)
-			consult_pricing: @utils.transition to @subagent.pricing_specialist
-				available when @variables.consultation_status != "in_progress"
-
-			# Route to technical specialist
-			consult_technical: @utils.transition to @subagent.technical_specialist
-				available when @variables.consultation_status != "in_progress"
-
-			end_conversation: @utils.transition to @subagent.farewell
-
-# Pricing specialist subagent
-subagent pricing_specialist:
-	label: "Pricing Specialist"
-	description: "Handles complex pricing calculations and returns results"
-
-	actions:
-		calculate_price:
-			description: "Calculates complex pricing"
-			inputs:
-				product_id: string
-					description: "Product to price"
-				quantity: number
-					description: "Quantity requested"
-			outputs:
-				final_price: number
-					description: "Calculated price"
-				discount_applied: string
-					description: "Any discounts applied"
-			target: "flow://Calculate_Complex_Pricing"
-
-	# Mark consultation as in progress when entering
-	before_reasoning:
-		set @variables.consultation_status = "in_progress"
-		set @variables.return_subagent = "main_hub"
-
-	reasoning:
-		instructions: ->
-			| You are the pricing specialist.
-			| Focus ONLY on pricing questions.
-			| Calculate the price and prepare your findings.
-			| When done, return to the main hub with your results.
-		actions:
-			calculate: @actions.calculate_price
-				with product_id=...
-				with quantity=...
-				set @variables.specialist_result = @outputs.final_price
-
-			# Return to main hub with results
-			return_with_results: @utils.transition to @subagent.main_hub
-
-	# Mark consultation complete when leaving
-	after_reasoning:
-		set @variables.consultation_status = "completed"
-
-# Technical specialist subagent
-subagent technical_specialist:
-	label: "Technical Specialist"
-	description: "Handles technical troubleshooting and returns results"
-
-	actions:
-		diagnose_issue:
-			description: "Diagnoses technical issues"
-			inputs:
-				symptoms: string
-					description: "Reported symptoms"
-			outputs:
-				diagnosis: string
-					description: "Technical diagnosis"
-				solution: string
-					description: "Recommended solution"
-			target: "flow://Technical_Diagnosis"
-
-	before_reasoning:
-		set @variables.consultation_status = "in_progress"
-		set @variables.return_subagent = "main_hub"
-
-	reasoning:
-		instructions: ->
-			| You are the technical specialist.
-			| Focus ONLY on technical issues.
-			| Diagnose the problem and prepare your findings.
-			| When done, return to the main hub with your results.
-		actions:
-			diagnose: @actions.diagnose_issue
-				with symptoms=...
-				set @variables.specialist_result = @outputs.diagnosis
-
-			return_with_results: @utils.transition to @subagent.main_hub
-
-	after_reasoning:
-		set @variables.consultation_status = "completed"
-
-subagent farewell:
-	label: "Farewell"
-	description: "Ends the conversation"
-
-	reasoning:
-		instructions: ->
-			| Thank the user and say goodbye.
-
-# ★ Alternative: Simple one-way transitions (when you don't need to return)
-#
-# If the specialist doesn't need to return results to a coordinator,
-# use simple transitions without the return_subagent pattern:
-#
-# go_orders: @utils.transition to @subagent.orders
-# go_billing: @utils.transition to @subagent.billing
-#
-# The bidirectional pattern adds complexity - only use when needed.

package/skills/developing-agentforce/assets/patterns/critical-input-collection.agent

@@ -1,244 +0,0 @@
-# Critical Input Collection Pattern
-# Ensures reliable capture of critical data before proceeding with workflows
-#
-# ★ Problem This Solves:
-#   - LLM sends empty JSON to actions
-#   - LLM sends wrong field names (_id instead of account_id)
-#   - LLM extracts wrong values from conversation
-#   - Agent proceeds without required data, causing crashes
-#
-# ★ Root Cause:
-#   Slot filling (`with account_id=...`) relies on LLM inference, which is
-#   probabilistic and can fail in subtle ways. Critical inputs need
-#   deterministic collection with validation.
-#
-# ★ Key Patterns:
-#   1. First-Interaction Collection - Tell LLM its PRIMARY GOAL
-#   2. Variable Setter Action - Dedicated action to capture + validate + store
-#   3. Single-Use Pattern - `available when @var == ""` disables after use
-#   4. Null Guard Pattern - Block ALL downstream actions until input is valid
-#   5. Explicit Action References - Guide LLM with `{!@actions.x}` in instructions
-#
-# ★ When To Use This Pattern:
-#   - Workflows that REQUIRE a specific ID (account, order, case, etc.)
-#   - When slot filling has been unreliable
-#   - When invalid input causes downstream failures
-#   - Multi-subagent agents where input must persist across transitions
-#
-# This is a COMPLETE template - customize for your use case
-
-system:
-	instructions: "You are a research assistant. Your PRIMARY GOAL is to collect the account ID before performing any research. Never proceed without a validated account ID."
-	messages:
-		welcome: "Hello! I can help you research account information. Please provide the account ID to get started."
-		error: "I encountered an issue. Let me try again."
-
-config:
-	agent_name: "Account_Research_Agent"
-	default_agent_user: "agent@company.salesforce.com"
-	agent_label: "Account Research Agent"
-	description: "Demonstrates critical input collection patterns for reliable slot filling"
-
-variables:
-	# Standard linked variables (required)
-	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"
-
-	# ★ CRITICAL INPUT - The value that MUST be collected before proceeding
-	account_id: mutable string = ""
-		description: "The Salesforce Account ID (18-char, starts with 001) - MUST be collected and validated before any research"
-
-	# ★ VALIDATION STATE - Track whether input has been validated
-	account_id_validated: mutable boolean = False
-		description: "Whether account_id has been validated as a real Salesforce ID"
-
-	# ★ COLLECTION ATTEMPTS - Track retries to prevent infinite loops
-	collection_attempts: mutable number = 0
-		description: "Number of times we've tried to collect account_id"
-
-	# Research results
-	account_name: mutable string = ""
-		description: "Name of the account (from lookup)"
-	research_summary: mutable string = ""
-		description: "Research summary for the account"
-
-language:
-	default_locale: "en_US"
-	additional_locales: ""
-	all_additional_locales: False
-
-# ★ ENTRY POINT: Input Collection Subagent
-# This subagent's ONLY job is to collect and validate the critical input
-start_agent input_collector:
-	label: "Input Collector"
-	description: "Collects and validates the account ID before allowing research"
-
-	actions:
-		# ★ PATTERN 2: Variable Setter Action
-		# Dedicated action that captures, validates, and stores the input
-		capture_account_id:
-			description: "Captures and validates the Salesforce Account ID from user input"
-			inputs:
-				account_id: string
-					description: "The 18-character Salesforce Account ID provided by the user (format: starts with '001')"
-					is_required: True
-			outputs:
-				validated_account_id: string
-					description: "The validated account ID (empty if invalid)"
-				is_valid: boolean
-					description: "True if the account ID is valid and exists"
-				account_name: string
-					description: "Name of the account if found"
-				error_message: string
-					description: "Error message if validation failed"
-			target: "flow://Validate_Account_Id"
-			require_user_confirmation: False
-			include_in_progress_indicator: True
-			progress_indicator_message: "Validating account ID..."
-
-	reasoning:
-		# ★ PATTERN 1: First-Interaction Collection
-		# Tell the LLM its PRIMARY GOAL is to collect the input
-		instructions: ->
-			| YOUR PRIMARY GOAL: Collect the account ID from the user.
-			|
-			| CURRENT STATE:
-			if @variables.account_id == "":
-				| ⚠️ Account ID NOT YET COLLECTED
-				| ASK the user for their Salesforce Account ID.
-				| The ID should be 18 characters and start with "001".
-				|
-				| Example prompt: "Please provide the Account ID you'd like me to research."
-
-			if @variables.account_id != "" and @variables.account_id_validated == False:
-				| 🔄 Account ID received: {!@variables.account_id}
-				| Attempting validation...
-				|
-				| Use {!@actions.capture_account_id} to validate this ID.
-
-			if @variables.account_id_validated == True:
-				| ✅ Account ID validated: {!@variables.account_id}
-				| Account Name: {!@variables.account_name}
-				|
-				| Transition to research subagent to begin analysis.
-
-			if @variables.collection_attempts > 2 and @variables.account_id_validated == False:
-				| ❌ Multiple validation failures.
-				| Ask the user to verify their Account ID is correct.
-				| Suggest they check Salesforce for the correct ID format.
-
-		actions:
-			# ★ PATTERN 3: Single-Use Pattern
-			# Action becomes unavailable once account_id is successfully captured
-			validate_id: @actions.capture_account_id
-				with account_id=...
-				set @variables.account_id = @outputs.validated_account_id
-				set @variables.account_id_validated = @outputs.is_valid
-				set @variables.account_name = @outputs.account_name
-				set @variables.collection_attempts = @variables.collection_attempts + 1
-				# ★ SINGLE-USE: Unavailable once validated
-				available when @variables.account_id_validated == False
-
-			# ★ PATTERN 4: Null Guard Pattern
-			# Transition ONLY available when input is validated
-			go_research: @utils.transition to @subagent.research
-				available when @variables.account_id_validated == True
-
-# ★ RESEARCH SUBAGENT: Only accessible after input is validated
-subagent research:
-	label: "Account Research"
-	description: "Performs research on the validated account"
-
-	actions:
-		# Research action that USES the validated account_id
-		research_account:
-			description: "Performs detailed research on the account"
-			inputs:
-				account_id: string
-					description: "The validated account ID"
-					is_required: True
-			outputs:
-				research_summary: string
-					description: "Summary of research findings"
-				signal_summary: string
-					description: "Key signals detected"
-			target: "flow://Research_Account"
-			include_in_progress_indicator: True
-			progress_indicator_message: "Researching account..."
-
-	reasoning:
-		instructions: ->
-			| Researching account: {!@variables.account_name} ({!@variables.account_id})
-			|
-			if @variables.research_summary == "":
-				| Use {!@actions.research_account} to analyze this account.
-			if @variables.research_summary != "":
-				| Research complete!
-				| {!@variables.research_summary}
-
-		actions:
-			# ★ PATTERN 4: Null Guard - Uses variable binding, NOT slot filling
-			# This ensures the validated ID is used, not LLM re-extraction
-			do_research: @actions.research_account
-				with account_id=@variables.account_id
-				set @variables.research_summary = @outputs.research_summary
-				# ★ GUARD: Only available if we have validated ID (defensive)
-				available when @variables.account_id_validated == True
-				available when @variables.research_summary == ""
-
-			# Return to collector for new account
-			new_account: @utils.transition to @subagent.input_collector
-				available when @variables.research_summary != ""
-
-# ═══════════════════════════════════════════════════════════════════════════
-# ★ INSIGHTS: Critical Input Collection
-# ═══════════════════════════════════════════════════════════════════════════
-#
-# WHY SLOT FILLING FAILS:
-#   The `...` syntax relies on LLM to extract values from conversation.
-#   This is probabilistic and can fail when:
-#   - User provides ID in unexpected format
-#   - Multiple IDs mentioned in conversation
-#   - LLM abbreviates or modifies field names
-#   - Context window is cluttered with other data
-#
-# THE SOLUTION: DETERMINISTIC COLLECTION
-#   Instead of `with account_id=...` on EVERY action:
-#   1. Collect ONCE with a dedicated setter action
-#   2. Validate BEFORE storing
-#   3. Store in variable: `set @variables.account_id = @outputs.validated_id`
-#   4. Use variable binding: `with account_id=@variables.account_id`
-#   5. Guard all actions: `available when @variables.account_id_validated == True`
-#
-# PATTERN SUMMARY:
-#
-# ┌─────────────────────────────────────────────────────────────────┐
-# │                CRITICAL INPUT COLLECTION FLOW                    │
-# ├─────────────────────────────────────────────────────────────────┤
-# │                                                                  │
-# │  User provides ID    ────►  Setter Action (slot fills once)      │
-# │                              │                                   │
-# │                              ▼                                   │
-# │                          Validation                              │
-# │                              │                                   │
-# │                    ┌────────┴────────┐                          │
-# │                    ▼                 ▼                          │
-# │               Valid               Invalid                       │
-# │                 │                    │                          │
-# │    set @variables.account_id     Ask again                      │
-# │    set @variables.validated=True (limit retries)                │
-# │                 │                                               │
-# │                 ▼                                               │
-# │    All downstream actions use                                   │
-# │    @variables.account_id (NOT ...)                              │
-# │                                                                  │
-# └─────────────────────────────────────────────────────────────────┘
-#
-# ═══════════════════════════════════════════════════════════════════════════

package/skills/developing-agentforce/assets/patterns/delegation-routing.agent

@@ -1,89 +0,0 @@
-# Subagent Delegation vs Transition Pattern
-# Understanding the difference between delegation and permanent handoffs
-#
-# ★ KEY CONCEPTS:
-#
-#   DELEGATION (@subagent.* syntax):
-#   - Syntax: action_name: @subagent.subagent_name
-#   - Control CAN return to the calling subagent
-#   - Use for: consulting specialists, sub-tasks, getting help
-#
-#   TRANSITION (@utils.transition syntax):
-#   - Syntax: action_name: @utils.transition to @subagent.subagent_name
-#   - PERMANENT handoff - control does NOT return
-#   - Use for: menu navigation, workflow stages, permanent routing
-#
-# ★ When To Use Each:
-#   DELEGATION: "Consult an expert then continue here"
-#   TRANSITION: "Go to this subagent and stay there"
-#
-# ★ Implementation Note:
-#   If delegation syntax doesn't work in your deployment method,
-#   use the bidirectional-routing.agent pattern which manually
-#   tracks return context via variables.
-#
-# This is a PARTIAL template - integrate into a complete agent file
-
-# ═══════════════════════════════════════════════════════════════
-# PATTERN 1: Subagent Delegation (can return)
-# ═══════════════════════════════════════════════════════════════
-
-# Delegation syntax in reasoning.actions:
-#
-# reasoning:
-#    actions:
-#       # Delegation - specialist CAN return control to this subagent
-#       consult_expert: @subagent.specialist_subagent
-#          description: "Consult specialist for complex questions"
-#          available when @variables.needs_expert_help == True
-#
-# The specialist subagent processes the request and control returns
-# to the original subagent when done.
-
-# ═══════════════════════════════════════════════════════════════
-# PATTERN 2: Transition (permanent handoff)
-# ═══════════════════════════════════════════════════════════════
-
-# Transition syntax in reasoning.actions:
-#
-# reasoning:
-#    actions:
-#       # Transition - permanent move to orders subagent
-#       go_orders: @utils.transition to @subagent.orders
-#
-# Control moves to orders subagent and STAYS there.
-# User continues in that subagent until another transition occurs.
-
-# ═══════════════════════════════════════════════════════════════
-# PATTERN 3: Manual Bidirectional (fallback pattern)
-# ═══════════════════════════════════════════════════════════════
-
-# If delegation doesn't work, use variables to track return:
-# See: bidirectional-routing.agent for full implementation
-
-variables:
-	return_subagent: mutable string = ""
-		description: "Subagent to return to after specialist"
-	specialist_result: mutable string = ""
-		description: "Result from specialist consultation"
-
-# Before going to specialist, store return address:
-# set @variables.return_subagent = "main_hub"
-# go_specialist: @utils.transition to @subagent.specialist
-
-# In specialist, transition back when done:
-# return_home: @utils.transition to @subagent.main_hub
-
-# ═══════════════════════════════════════════════════════════════
-# COMPARISON TABLE
-# ═══════════════════════════════════════════════════════════════
-#
-# | Feature              | Delegation        | Transition              |
-# |----------------------|-------------------|-------------------------|
-# | Syntax               | @subagent.name       | @utils.transition to    |
-# | Returns to caller?   | YES               | NO                      |
-# | Use in actions:      | YES               | YES                     |
-# | Use in lifecycle:    | NO                | YES (bare syntax)       |
-# | Best for             | Consult & return  | Menu/workflow routing   |
-#
-# ═══════════════════════════════════════════════════════════════

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

@@ -1,127 +0,0 @@
-# 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-subagent
-#   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"
-
-subagent conversation:
-	label: "Conversation"
-	description: "Main conversation subagent 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"
-				subagent_name: string
-					description: "Current subagent"
-			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 @subagent.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 @subagent.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 subagent_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