@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/patterns/advanced-input-bindings.agent

@@ -0,0 +1,141 @@
+# Advanced Input Bindings Pattern
+# Demonstrates all parameter binding techniques for Agent Script actions
+#
+# ★ When To Use This Pattern:
+#   - Learning different ways to pass values to actions
+#   - Combining LLM slot filling with variable binding
+#   - Chaining outputs between multiple actions
+#   - Complex multi-input action scenarios
+#
+# ★ Key Insight:
+#   - `...` (ellipsis) = LLM extracts value from conversation (slot filling)
+#   - `"value"` = Fixed constant value
+#   - `@variables.x` = Value from stored state
+#   - `@outputs.x` = Value from previous action's output
+#
+# ★ Common Use Cases:
+#   - Order lookup with user-provided order ID
+#   - Multi-step workflows with data passing
+#   - Conditional parameter binding
+#
+# This is a PARTIAL template - integrate into a complete agent file
+
+# Variables for demonstrating different binding patterns
+variables:
+	# ... standard linked variables ...
+	current_account_id: mutable string = ""
+		description: "Currently selected account ID"
+	order_id: mutable string = ""
+		description: "Order ID being processed"
+	amount: mutable number = 0
+		description: "Transaction amount"
+	status: mutable string = ""
+		description: "Current operation status"
+
+topic order_processing:
+	label: "Order Processing"
+	description: "Demonstrates advanced input binding patterns"
+
+	actions:
+		# Action with multiple input types
+		process_order:
+			description: "Process an order with various input methods"
+			inputs:
+				order_id: string
+					description: "The order ID to process"
+				amount: number
+					description: "Transaction amount in USD"
+				account_id: string
+					description: "Customer account ID"
+			outputs:
+				confirmation_number: string
+					description: "Order confirmation number"
+				processed_amount: number
+					description: "Final processed amount"
+			target: "flow://Process_Order"
+
+		get_account:
+			description: "Look up account details"
+			inputs:
+				account_id: string
+					description: "Account ID to look up"
+			outputs:
+				account_name: string
+					description: "Account name"
+				credit_limit: number
+					description: "Available credit"
+			target: "flow://Get_Account_Details"
+
+		send_notification:
+			description: "Send order notification"
+			inputs:
+				confirmation_number: string
+					description: "Order confirmation to include"
+				recipient_account: string
+					description: "Account to notify"
+			outputs:
+				sent: boolean
+					description: "Whether notification was sent"
+			target: "flow://Send_Order_Notification"
+
+	reasoning:
+		instructions: ->
+			| Help the customer process their order.
+			|
+			| INPUT BINDING EXAMPLES:
+			| 1. Slot filling (...) - LLM extracts from conversation
+			| 2. Fixed values - Always use a constant
+			| 3. Variable binding - Use stored state
+			| 4. Output chaining - Use results from previous action
+			|
+			| Ask for order details and process appropriately.
+
+		actions:
+			# ★ PATTERN 1: Slot Filling (LLM extracts from conversation)
+			# User says "Process order ORD-12345" -> LLM fills order_id="ORD-12345"
+			slot_fill_lookup: @actions.process_order
+				with order_id=...
+				with amount=...
+				with account_id=...
+				set @variables.order_id = @outputs.confirmation_number
+
+			# ★ PATTERN 2: Fixed Value (constant)
+			# Always uses the same account for default lookups
+			fixed_account: @actions.get_account
+				with account_id="001DEFAULT000001"
+				set @variables.status = @outputs.account_name
+
+			# ★ PATTERN 3: Variable Binding (from stored state)
+			# Uses the account ID saved earlier in the conversation
+			variable_binding: @actions.get_account
+				with account_id=@variables.current_account_id
+				set @variables.status = @outputs.account_name
+
+			# ★ PATTERN 4: Output Chaining (from previous action)
+			# Uses confirmation_number from process_order to send notification
+			chained_output: @actions.process_order
+				with order_id=...
+				with amount=@variables.amount
+				with account_id=@variables.current_account_id
+				set @variables.order_id = @outputs.confirmation_number
+				run @actions.send_notification
+					with confirmation_number=@outputs.confirmation_number
+					with recipient_account=@variables.current_account_id
+
+			# ★ PATTERN 5: Mixed Binding (combining patterns)
+			# Some inputs from LLM, some from variables, some fixed
+			mixed_binding: @actions.process_order
+				with order_id=...                              # LLM slot fills
+				with amount=@variables.amount                   # From variable
+				with account_id="001INTERNAL00001"              # Fixed value
+
+# ★ Insight: Binding Pattern Decision Tree
+#
+# Need the LLM to extract from conversation?     -> Use `...`
+# Value is always the same constant?             -> Use "value"
+# Value was captured in a previous step?         -> Use @variables.x
+# Value comes from another action's output?      -> Use @outputs.x (in callback)
+#
+# ★ Common Mistake: Using @outputs.x outside of a `run` callback
+# @outputs.x is only available inside the action's callback chain
+# Store important outputs in @variables for use elsewhere

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   |
+#
+# ═══════════════════════════════════════════════════════════════