@salesforce/afv-skills 1.1.0 → 1.2.0

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

@@ -0,0 +1,156 @@
+# Bidirectional Routing Pattern
+# Navigate to a specialist topic and return with results
+#
+# ★ When To Use This Pattern:
+#   - Main topic 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 topic
+#
+# ★ Key Insight:
+#   Standard transitions (@utils.transition) are one-way.
+#   For round-trip routing, store the "return address" in a variable.
+#   The specialist topic transitions back when done.
+#
+# ★ Architecture Decision:
+#   Use this when you want separation of concerns:
+#   - Main topic: Orchestration and user interaction
+#   - Specialist topic: Focused, complex processing
+#
+# This is a PARTIAL template - integrate into a complete agent file
+
+variables:
+	# ... standard linked variables ...
+	return_topic: mutable string = ""
+		description: "Topic to return to after specialist consultation"
+	specialist_result: mutable string = ""
+		description: "Result from specialist topic"
+	consultation_status: mutable string = ""
+		description: "Status of specialist consultation"
+
+# Main orchestration topic
+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 @topic.pricing_specialist
+				available when @variables.consultation_status != "in_progress"
+
+			# Route to technical specialist
+			consult_technical: @utils.transition to @topic.technical_specialist
+				available when @variables.consultation_status != "in_progress"
+
+			end_conversation: @utils.transition to @topic.farewell
+
+# Pricing specialist topic
+topic 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_topic = "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 @topic.main_hub
+
+	# Mark consultation complete when leaving
+	after_reasoning:
+		set @variables.consultation_status = "completed"
+
+# Technical specialist topic
+topic 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_topic = "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 @topic.main_hub
+
+	after_reasoning:
+		set @variables.consultation_status = "completed"
+
+topic 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_topic pattern:
+#
+# go_orders: @utils.transition to @topic.orders
+# go_billing: @utils.transition to @topic.billing
+#
+# The bidirectional pattern adds complexity - only use when needed.

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

@@ -0,0 +1,244 @@
+# 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-topic 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 Topic
+# This topic'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 topic 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 @topic.research
+				available when @variables.account_id_validated == True
+
+# ★ RESEARCH TOPIC: Only accessible after input is validated
+topic 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 @topic.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/agentforce-development/assets/patterns/delegation-routing.agent

@@ -0,0 +1,89 @@
+# Topic Delegation vs Transition Pattern
+# Understanding the difference between delegation and permanent handoffs
+#
+# ★ KEY CONCEPTS:
+#
+#   DELEGATION (@topic.* syntax):
+#   - Syntax: action_name: @topic.topic_name
+#   - Control CAN return to the calling topic
+#   - Use for: consulting specialists, sub-tasks, getting help
+#
+#   TRANSITION (@utils.transition syntax):
+#   - Syntax: action_name: @utils.transition to @topic.topic_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 topic 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: Topic Delegation (can return)
+# ═══════════════════════════════════════════════════════════════
+
+# Delegation syntax in reasoning.actions:
+#
+# reasoning:
+#    actions:
+#       # Delegation - specialist CAN return control to this topic
+#       consult_expert: @topic.specialist_topic
+#          description: "Consult specialist for complex questions"
+#          available when @variables.needs_expert_help == True
+#
+# The specialist topic processes the request and control returns
+# to the original topic when done.
+
+# ═══════════════════════════════════════════════════════════════
+# PATTERN 2: Transition (permanent handoff)
+# ═══════════════════════════════════════════════════════════════
+
+# Transition syntax in reasoning.actions:
+#
+# reasoning:
+#    actions:
+#       # Transition - permanent move to orders topic
+#       go_orders: @utils.transition to @topic.orders
+#
+# Control moves to orders topic and STAYS there.
+# User continues in that topic 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_topic: mutable string = ""
+		description: "Topic to return to after specialist"
+	specialist_result: mutable string = ""
+		description: "Result from specialist consultation"
+
+# Before going to specialist, store return address:
+# set @variables.return_topic = "main_hub"
+# go_specialist: @utils.transition to @topic.specialist
+
+# In specialist, transition back when done:
+# return_home: @utils.transition to @topic.main_hub
+
+# ═══════════════════════════════════════════════════════════════
+# COMPARISON TABLE
+# ═══════════════════════════════════════════════════════════════
+#
+# | Feature              | Delegation        | Transition              |
+# |----------------------|-------------------|-------------------------|
+# | Syntax               | @topic.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/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