@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/patterns/open-gate-routing.agent

@@ -0,0 +1,286 @@
+# Open Gate Routing Pattern
+# 3-variable state machine for auth-gated topic routing with LLM bypass
+#
+# ★ When To Use This Pattern:
+#   - Multiple protected topics require authentication before access
+#   - You want to bypass the LLM topic selector when a gate topic holds focus
+#   - Users should be redirected to auth, then automatically returned to their
+#     original intended topic after authentication completes
+#   - You need an EXIT_PROTOCOL to reset state when users change intent
+#
+# ★ Key Insight (Zero Credit Bypass):
+#   When open_gate is set, before_reasoning in the topic_selector
+#   deterministically routes via "transition to" — the LLM never reasons.
+#   This saves credits on every turn the gate holds focus.
+#
+# ★ The 3 Variables:
+#   open_gate    — Which topic currently holds focus ("null" = none)
+#   next_topic   — Deferred destination after auth completes
+#   authenticated — Whether the user has passed authentication
+#
+# ★ EXIT_PROTOCOL:
+#   Any topic can reset open_gate to "null" when the user changes intent.
+#   This releases the gate lock and returns control to the LLM topic selector.
+#
+# ★ Related Patterns:
+#   - Latch Variable (SKILL.md) — simpler 1-variable version, no auth gate
+#   - Bidirectional Routing (bidirectional-routing.agent) — specialist consultation, not interception
+#   - Verification Gate (fsm-architecture.md) — linear one-time gate, no deferred return
+#
+# ★ Credit: Hua Xu (Salesforce APAC FDE team) — production pattern from Kogan agent deployment
+#
+# This is a PARTIAL template - integrate into a complete agent file
+
+variables:
+	# ... standard linked variables ...
+	open_gate: mutable string = "null"
+		description: "Which topic currently holds focus (null = LLM decides)"
+	next_topic: mutable string = ""
+		description: "Deferred destination after authentication completes"
+	authenticated: mutable boolean = False
+		description: "Whether the user has passed authentication"
+
+# ─────────────────────────────────────────────────────────────────────
+# TOPIC SELECTOR (Entry Point)
+# When open_gate is set, bypasses LLM entirely (zero credit cost)
+# ─────────────────────────────────────────────────────────────────────
+start_agent topic_selector:
+	description: "Routes to topics — deterministic bypass when open_gate is set"
+
+	before_reasoning:
+		# ★ GATE CHECK: If a topic holds focus, bypass LLM entirely
+		if @variables.open_gate == "protected_workflow":
+			transition to @topic.protected_workflow
+		if @variables.open_gate == "account_management":
+			transition to @topic.account_management
+		if @variables.open_gate == "authentication_gate":
+			transition to @topic.authentication_gate
+
+	reasoning:
+		instructions: ->
+			| You are a customer service agent.
+			| Route the customer to the appropriate topic:
+			| - Order status, returns, or shipping → protected workflow
+			| - Account settings or profile changes → account management
+			| - General questions → general inquiry
+		actions:
+			go_protected: @utils.transition to @topic.protected_workflow
+			go_account: @utils.transition to @topic.account_management
+			go_general: @utils.transition to @topic.general_inquiry
+
+# ─────────────────────────────────────────────────────────────────────
+# PROTECTED WORKFLOW (Requires Authentication)
+# Checks auth state, redirects to auth gate if needed, locks focus if authed
+# ─────────────────────────────────────────────────────────────────────
+topic protected_workflow:
+	description: "Handles order status, returns, and shipping (requires authentication)"
+
+	before_reasoning:
+		# ★ AUTH CHECK: Redirect unauthenticated users to auth gate
+		if @variables.authenticated == False:
+			set @variables.next_topic = "protected_workflow"
+			set @variables.open_gate = "authentication_gate"
+			transition to @topic.authentication_gate
+
+		# ★ FOCUS LOCK: Keep gate open so topic selector bypasses LLM
+		set @variables.open_gate = "protected_workflow"
+
+	reasoning:
+		instructions: ->
+			| The customer is authenticated.
+			| Help them with order status, returns, or shipping inquiries.
+			|
+			| If the customer changes the subject to something unrelated,
+			| let them know you will redirect them.
+		actions:
+			lookup_order: @actions.get_order_status
+				with order_id=...
+				set @variables.order_result = @outputs.status
+
+			# ★ EXIT_PROTOCOL: User changed intent — release gate
+			exit_to_menu: @utils.transition to @topic.exit_protocol
+
+	after_reasoning:
+		# Logging or cleanup after each turn (optional)
+		set @variables.last_topic = "protected_workflow"
+
+# ─────────────────────────────────────────────────────────────────────
+# ACCOUNT MANAGEMENT (Second Protected Topic)
+# Demonstrates the pattern scales to N protected topics
+# ─────────────────────────────────────────────────────────────────────
+topic account_management:
+	description: "Handles account settings and profile changes (requires authentication)"
+
+	before_reasoning:
+		# ★ AUTH CHECK: Same pattern as protected_workflow
+		if @variables.authenticated == False:
+			set @variables.next_topic = "account_management"
+			set @variables.open_gate = "authentication_gate"
+			transition to @topic.authentication_gate
+
+		# ★ FOCUS LOCK
+		set @variables.open_gate = "account_management"
+
+	reasoning:
+		instructions: ->
+			| The customer is authenticated.
+			| Help them with account settings and profile changes.
+			|
+			| If the customer changes the subject to something unrelated,
+			| let them know you will redirect them.
+		actions:
+			update_profile: @actions.update_customer_profile
+				with field_name=...
+				with new_value=...
+				set @variables.update_result = @outputs.success
+
+			# ★ EXIT_PROTOCOL: User changed intent — release gate
+			exit_to_menu: @utils.transition to @topic.exit_protocol
+
+# ─────────────────────────────────────────────────────────────────────
+# AUTHENTICATION GATE
+# Handles auth flow, then routes back via next_topic
+# ─────────────────────────────────────────────────────────────────────
+topic authentication_gate:
+	description: "Verifies customer identity before allowing access to protected topics"
+
+	before_reasoning:
+		# ★ FOCUS LOCK: Hold gate open during auth flow
+		set @variables.open_gate = "authentication_gate"
+
+	reasoning:
+		instructions: ->
+			if @variables.authenticated == True:
+				| You are already authenticated. Redirecting you now.
+
+			if @variables.authenticated == False:
+				| I need to verify your identity before I can help with that.
+				| Please provide your email address and verification code.
+		actions:
+			verify_identity: @actions.verify_customer
+				with email=...
+				with verification_code=...
+				set @variables.authenticated = @outputs.is_verified
+
+	after_reasoning:
+		# ★ POST-AUTH ROUTING: If authenticated, route to deferred destination
+		if @variables.authenticated == True:
+			if @variables.next_topic == "protected_workflow":
+				set @variables.open_gate = "protected_workflow"
+				transition to @topic.protected_workflow
+			if @variables.next_topic == "account_management":
+				set @variables.open_gate = "account_management"
+				transition to @topic.account_management
+
+# ─────────────────────────────────────────────────────────────────────
+# EXIT PROTOCOL (Resets Gate State)
+# Clears open_gate so LLM topic selector regains control
+# ─────────────────────────────────────────────────────────────────────
+topic exit_protocol:
+	description: "Resets gate state and returns to topic selector"
+
+	before_reasoning:
+		# ★ RELEASE GATE: Clear all gate state
+		set @variables.open_gate = "null"
+		set @variables.next_topic = ""
+		transition to @topic.topic_selector
+
+	reasoning:
+		instructions: ->
+			| Redirecting you to the main menu.
+
+# ─────────────────────────────────────────────────────────────────────
+# GENERAL INQUIRY (Unprotected Topic)
+# Demonstrates that not every topic needs gating
+# ─────────────────────────────────────────────────────────────────────
+topic general_inquiry:
+	description: "Handles general questions that do not require authentication"
+
+	reasoning:
+		instructions: ->
+			| Help the customer with general questions.
+			| No authentication is needed for this topic.
+			|
+			| If the customer needs help with orders or account settings,
+			| let them know they will need to verify their identity first.
+		actions:
+			go_protected: @utils.transition to @topic.protected_workflow
+			go_account: @utils.transition to @topic.account_management
+
+# ═════════════════════════════════════════════════════════════════════
+# ARCHITECTURE DIAGRAM
+# ═════════════════════════════════════════════════════════════════════
+#
+#                       ┌─────────────────────┐
+#                       │   topic_selector    │
+#                       │   (start_agent)     │
+#                       │                     │
+#                       │ before_reasoning:   │
+#                       │ if open_gate <> null │
+#                       │   → bypass LLM      │
+#                       └──────────┬──────────┘
+#              ┌───────────────────┼───────────────────┐
+#              ▼                   ▼                   ▼
+#   ┌──────────────────┐ ┌────────────────┐ ┌─────────────────┐
+#   │ protected_workflow│ │account_mgmt   │ │ general_inquiry  │
+#   │ (auth required)  │ │(auth required)│ │ (no auth needed) │
+#   │                  │ │               │ │                  │
+#   │ before_reasoning:│ │ before_reas.: │ │ (no gate logic)  │
+#   │ if !auth → gate  │ │ if !auth→gate │ │                  │
+#   │ if auth → lock   │ │ if auth→lock  │ │                  │
+#   └────────┬─────────┘ └───────┬───────┘ └─────────────────┘
+#            │                   │
+#            ▼                   ▼
+#   ┌──────────────────────────────────────┐
+#   │         authentication_gate          │
+#   │                                      │
+#   │ before_reasoning: lock gate          │
+#   │ reasoning: verify identity           │
+#   │ after_reasoning:                     │
+#   │   if auth → route via next_topic     │
+#   └──────────────────────────────────────┘
+#
+# ═════════════════════════════════════════════════════════════════════
+# VARIABLE STATE FLOW WALKTHROUGH
+# ═════════════════════════════════════════════════════════════════════
+#
+# User says: "I want to check my order status"
+#
+# Step 1: topic_selector
+#   open_gate = "null" → LLM reasons → routes to protected_workflow
+#
+# Step 2: protected_workflow.before_reasoning
+#   authenticated = False → set next_topic = "protected_workflow"
+#   → set open_gate = "authentication_gate"
+#   → transition to authentication_gate
+#
+# Step 3: authentication_gate.before_reasoning
+#   open_gate = "authentication_gate" (lock)
+#
+# Step 4: User provides email + code → verify_customer succeeds
+#   authenticated = True
+#
+# Step 5: authentication_gate.after_reasoning
+#   authenticated = True, next_topic = "protected_workflow"
+#   → set open_gate = "protected_workflow"
+#   → transition to protected_workflow
+#
+# Step 6: protected_workflow.before_reasoning
+#   authenticated = True → set open_gate = "protected_workflow" (lock)
+#   → LLM reasons with full access to protected actions
+#
+# Step 7: User says "actually, never mind"
+#   → LLM selects exit_to_menu action
+#   → exit_protocol.before_reasoning: open_gate = "null"
+#   → transition to topic_selector (LLM regains control)
+#
+# ═════════════════════════════════════════════════════════════════════
+# PATTERN COMPARISON
+# ═════════════════════════════════════════════════════════════════════
+#
+# Pattern              | Variables | Auth Gate | Deferred Return | LLM Bypass
+# ─────────────────────┼───────────┼───────────┼─────────────────┼───────────
+# Latch Variable       | 1         | No        | No              | Partial
+# Bidirectional Route  | 1-2       | No        | Yes (manual)    | No
+# Verification Gate    | 1         | Yes       | No              | No
+# Open Gate (this)     | 3         | Yes       | Yes (automatic) | Full

package/skills/agentforce-development/assets/patterns/procedural-instructions.agent

@@ -0,0 +1,273 @@
+# Procedural Instructions Pattern
+# Execute actions inline within instructions block for conditional data loading
+#
+# ★ When To Use This Pattern:
+#   - Fetch data only when needed (lazy loading)
+#   - Chain data lookups based on conditions
+#   - Build up context progressively
+#   - Reduce unnecessary API calls
+#
+# ★ Key Insights:
+#   - `run @actions.x` can appear INSIDE `instructions: ->` blocks
+#   - Actions execute when their containing conditional is true
+#   - Different from actions: block which defines what LLM CAN call
+#   - This is PROCEDURAL (you control when) vs DECLARATIVE (LLM chooses)
+#
+# ★ Use Case Distinction:
+#   - actions: block = "LLM, here are tools you MAY use"
+#   - run in instructions = "Do this NOW when condition met"
+#
+# This is a COMPLETE template - customize for your use case
+
+system:
+	instructions: "You are a customer service agent. Efficiently gather context as needed to help customers. Only fetch data when required for the current task."
+	messages:
+		welcome: "Hello! How can I help you today?"
+		error: "I encountered an issue retrieving your information. Let me try again."
+
+config:
+	agent_name: "Smart_Service_Agent"
+	default_agent_user: "agent@company.salesforce.com"
+	agent_label: "Smart Service Agent"
+	description: "Agent with procedural data loading"
+
+variables:
+	# Standard linked variables
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+
+	# Progressive data loading variables
+	customer_loaded: mutable boolean = False
+		description: "Whether customer data has been loaded"
+	orders_loaded: mutable boolean = False
+		description: "Whether order data has been loaded"
+	cases_loaded: mutable boolean = False
+		description: "Whether case data has been loaded"
+
+	# Customer data
+	customer_name: mutable string = ""
+		description: "Customer's full name"
+	customer_tier: mutable string = ""
+		description: "Customer tier: standard, premium, vip"
+	account_id: mutable string = ""
+		description: "Associated account ID"
+
+	# Order data
+	recent_order_id: mutable string = ""
+		description: "Most recent order ID"
+	order_status: mutable string = ""
+		description: "Status of the recent order"
+	tracking_number: mutable string = ""
+		description: "Shipping tracking number"
+
+	# Case data
+	open_case_count: mutable number = 0
+		description: "Number of open support cases"
+	last_case_subject: mutable string = ""
+		description: "Subject of most recent case"
+
+language:
+	default_locale: "en_US"
+
+start_agent topic_selector:
+	label: "Topic Selector"
+	description: "Routes to topics with procedural data loading"
+
+	actions:
+		# Data loading actions
+		load_customer:
+			description: "Load customer profile data"
+			inputs:
+				contact_id: string
+					description: "Contact ID to look up"
+					is_required: True
+			outputs:
+				name: string
+					description: "Customer name"
+				tier: string
+					description: "Customer tier"
+				account_id: string
+					description: "Associated account"
+			target: "flow://Get_Customer_Profile"
+
+		load_orders:
+			description: "Load recent order data"
+			inputs:
+				contact_id: string
+					description: "Contact ID"
+					is_required: True
+			outputs:
+				order_id: string
+					description: "Most recent order ID"
+				status: string
+					description: "Order status"
+				tracking: string
+					description: "Tracking number"
+			target: "flow://Get_Recent_Orders"
+
+		load_cases:
+			description: "Load support case data"
+			inputs:
+				contact_id: string
+					description: "Contact ID"
+					is_required: True
+			outputs:
+				open_count: number
+					description: "Number of open cases"
+				last_subject: string
+					description: "Last case subject"
+			target: "flow://Get_Open_Cases"
+
+	reasoning:
+		# ★ PROCEDURAL INSTRUCTIONS with inline action execution
+		instructions: ->
+			# ★ STEP 1: Always load customer data first (if not already loaded)
+			# This runs BEFORE any conversation happens
+			if @variables.customer_loaded == False:
+				run @actions.load_customer
+					with contact_id=@variables.ContactId
+					set @variables.customer_name = @outputs.name
+					set @variables.customer_tier = @outputs.tier
+					set @variables.account_id = @outputs.account_id
+				set @variables.customer_loaded = True
+
+			# Now we have customer context
+			| Hello {!@variables.customer_name}!
+			|
+			if @variables.customer_tier == "vip":
+				| As a VIP customer, I'm here to provide priority support.
+			|
+			| How can I help you today?
+			| - Order status or tracking
+			| - Support cases
+			| - Account questions
+
+		actions:
+			go_orders: @utils.transition to @topic.order_status
+			go_cases: @utils.transition to @topic.support_cases
+			go_account: @utils.transition to @topic.account_help
+
+topic order_status:
+	label: "Order Status"
+	description: "Check order status with lazy loading"
+
+	actions:
+		get_tracking_details:
+			description: "Get detailed tracking information"
+			inputs:
+				order_id: string
+					description: "Order ID to look up"
+			outputs:
+				carrier: string
+					description: "Shipping carrier"
+				estimated_delivery: string
+					description: "Estimated delivery date"
+				current_location: string
+					description: "Current package location"
+			target: "flow://Get_Tracking_Details"
+
+	reasoning:
+		instructions: ->
+			# ★ LAZY LOADING: Only fetch orders when user enters this topic
+			if @variables.orders_loaded == False:
+				run @actions.load_orders
+					with contact_id=@variables.ContactId
+					set @variables.recent_order_id = @outputs.order_id
+					set @variables.order_status = @outputs.status
+					set @variables.tracking_number = @outputs.tracking
+				set @variables.orders_loaded = True
+
+			# Now provide order information
+			| Here's your most recent order:
+			| Order ID: {!@variables.recent_order_id}
+			| Status: {!@variables.order_status}
+			|
+			if @variables.tracking_number != "":
+				| Tracking: {!@variables.tracking_number}
+			|
+			| Would you like more details or help with something else?
+
+		actions:
+			get_details: @actions.get_tracking_details
+				with order_id=@variables.recent_order_id
+			back: @utils.transition to @topic.topic_selector
+
+topic support_cases:
+	label: "Support Cases"
+	description: "Review support cases with lazy loading"
+
+	reasoning:
+		instructions: ->
+			# ★ LAZY LOADING: Only fetch cases when needed
+			if @variables.cases_loaded == False:
+				run @actions.load_cases
+					with contact_id=@variables.ContactId
+					set @variables.open_case_count = @outputs.open_count
+					set @variables.last_case_subject = @outputs.last_subject
+				set @variables.cases_loaded = True
+
+			# Present case information
+			if @variables.open_case_count == 0:
+				| You have no open support cases.
+				| Is there something I can help you with?
+
+			if @variables.open_case_count > 0:
+				| You have {!@variables.open_case_count} open case(s).
+				| Most recent: {!@variables.last_case_subject}
+				|
+				| Would you like to:
+				| - Check the status of a specific case
+				| - Create a new support case
+				| - Return to the main menu
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+			escalate: @utils.escalate
+				description: "Transfer to support specialist"
+
+topic account_help:
+	label: "Account Help"
+	description: "Account questions - customer data already loaded"
+
+	reasoning:
+		instructions: ->
+			# ★ DATA ALREADY AVAILABLE - no loading needed
+			# Customer data was loaded in topic_selector
+			| Account Information:
+			| Name: {!@variables.customer_name}
+			| Tier: {!@variables.customer_tier}
+			| Account ID: {!@variables.account_id}
+			|
+			| What would you like to know about your account?
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+# ★ Insight: Procedural vs Declarative Actions
+#
+# PROCEDURAL (run in instructions):
+#   - You control WHEN the action runs
+#   - Executes based on conditionals
+#   - Good for: data loading, setup, guaranteed actions
+#   - Example: "Always load customer before greeting"
+#
+# DECLARATIVE (actions: block):
+#   - LLM decides IF and WHEN to call
+#   - Based on user request
+#   - Good for: optional tools, user-triggered actions
+#   - Example: "User can ask for refund if they want"
+#
+# COMBINE BOTH:
+#   - Use procedural for setup/loading
+#   - Use declarative for user interactions
+#   - Result: Efficient, context-aware agents
+
+# ★ Performance Benefits:
+#   - Fetch only what's needed per topic
+#   - Avoid loading all data upfront
+#   - Reduce API calls for simple conversations
+#   - Better response times