@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,287 +0,0 @@
-# Open Gate Routing Pattern
-# 3-variable state machine for auth-gated subagent routing with LLM bypass
-#
-# ★ When To Use This Pattern:
-#   - Multiple protected subagents require authentication before access
-#   - You want to bypass the LLM subagent selector when a gate subagent holds focus
-#   - Users should be redirected to auth, then automatically returned to their
-#     original intended subagent 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 agent_router
-#   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 subagent currently holds focus ("null" = none)
-#   next_subagent   — Deferred destination after auth completes
-#   authenticated — Whether the user has passed authentication
-#
-# ★ EXIT_PROTOCOL:
-#   Any subagent can reset open_gate to "null" when the user changes intent.
-#   This releases the gate lock and returns control to the LLM subagent router.
-#
-# ★ 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 subagent currently holds focus (null = LLM decides)"
-	next_subagent: mutable string = ""
-		description: "Deferred destination after authentication completes"
-	authenticated: mutable boolean = False
-		description: "Whether the user has passed authentication"
-
-# ─────────────────────────────────────────────────────────────────────
-# SUBAGENT ROUTER (Entry Point)
-# When open_gate is set, bypasses LLM entirely (zero credit cost)
-# ─────────────────────────────────────────────────────────────────────
-start_agent agent_router:
-	label: "Subagent Router"
-	description: "Routes to subagents — deterministic bypass when open_gate is set"
-
-	before_reasoning:
-		# ★ GATE CHECK: If a subagent holds focus, bypass LLM entirely
-		if @variables.open_gate == "protected_workflow":
-			transition to @subagent.protected_workflow
-		if @variables.open_gate == "account_management":
-			transition to @subagent.account_management
-		if @variables.open_gate == "authentication_gate":
-			transition to @subagent.authentication_gate
-
-	reasoning:
-		instructions: ->
-			| You are a customer service agent.
-			| Route the customer to the appropriate subagent:
-			| - Order status, returns, or shipping → protected workflow
-			| - Account settings or profile changes → account management
-			| - General questions → general inquiry
-		actions:
-			go_protected: @utils.transition to @subagent.protected_workflow
-			go_account: @utils.transition to @subagent.account_management
-			go_general: @utils.transition to @subagent.general_inquiry
-
-# ─────────────────────────────────────────────────────────────────────
-# PROTECTED WORKFLOW (Requires Authentication)
-# Checks auth state, redirects to auth gate if needed, locks focus if authed
-# ─────────────────────────────────────────────────────────────────────
-subagent 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_subagent = "protected_workflow"
-			set @variables.open_gate = "authentication_gate"
-			transition to @subagent.authentication_gate
-
-		# ★ FOCUS LOCK: Keep gate open so subagent router 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 @subagent.exit_protocol
-
-	after_reasoning:
-		# Logging or cleanup after each turn (optional)
-		set @variables.last_subagent = "protected_workflow"
-
-# ─────────────────────────────────────────────────────────────────────
-# ACCOUNT MANAGEMENT (Second Protected Subagent)
-# Demonstrates the pattern scales to N protected subagents
-# ─────────────────────────────────────────────────────────────────────
-subagent 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_subagent = "account_management"
-			set @variables.open_gate = "authentication_gate"
-			transition to @subagent.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 @subagent.exit_protocol
-
-# ─────────────────────────────────────────────────────────────────────
-# AUTHENTICATION GATE
-# Handles auth flow, then routes back via next_subagent
-# ─────────────────────────────────────────────────────────────────────
-subagent authentication_gate:
-	description: "Verifies customer identity before allowing access to protected subagents"
-
-	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_subagent == "protected_workflow":
-				set @variables.open_gate = "protected_workflow"
-				transition to @subagent.protected_workflow
-			if @variables.next_subagent == "account_management":
-				set @variables.open_gate = "account_management"
-				transition to @subagent.account_management
-
-# ─────────────────────────────────────────────────────────────────────
-# EXIT PROTOCOL (Resets Gate State)
-# Clears open_gate so LLM subagent router regains control
-# ─────────────────────────────────────────────────────────────────────
-subagent exit_protocol:
-	description: "Resets gate state and returns to subagent router"
-
-	before_reasoning:
-		# ★ RELEASE GATE: Clear all gate state
-		set @variables.open_gate = "null"
-		set @variables.next_subagent = ""
-		transition to @subagent.agent_router
-
-	reasoning:
-		instructions: ->
-			| Redirecting you to the main menu.
-
-# ─────────────────────────────────────────────────────────────────────
-# GENERAL INQUIRY (Unprotected Subagent)
-# Demonstrates that not every subagent needs gating
-# ─────────────────────────────────────────────────────────────────────
-subagent 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 subagent.
-			|
-			| 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 @subagent.protected_workflow
-			go_account: @utils.transition to @subagent.account_management
-
-# ═════════════════════════════════════════════════════════════════════
-# ARCHITECTURE DIAGRAM
-# ═════════════════════════════════════════════════════════════════════
-#
-#                       ┌─────────────────────┐
-#                       │   agent_router    │
-#                       │   (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_subagent     │
-#   └──────────────────────────────────────┘
-#
-# ═════════════════════════════════════════════════════════════════════
-# VARIABLE STATE FLOW WALKTHROUGH
-# ═════════════════════════════════════════════════════════════════════
-#
-# User says: "I want to check my order status"
-#
-# Step 1: agent_router
-#   open_gate = "null" → LLM reasons → routes to protected_workflow
-#
-# Step 2: protected_workflow.before_reasoning
-#   authenticated = False → set next_subagent = "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_subagent = "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 agent_router (subagent router 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/developing-agentforce/assets/patterns/procedural-instructions.agent

@@ -1,273 +0,0 @@
-# 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 agent_router:
-	label: "Subagent Router"
-	description: "Routes to subagents 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 @subagent.order_status
-			go_cases: @utils.transition to @subagent.support_cases
-			go_account: @utils.transition to @subagent.account_help
-
-subagent 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 subagent
-			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 @subagent.agent_router
-
-subagent 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 @subagent.agent_router
-			escalate: @utils.escalate
-				description: "Transfer to support specialist"
-
-subagent 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 agent_router
-			| 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 @subagent.agent_router
-
-# ★ 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 subagent
-#   - Avoid loading all data upfront
-#   - Reduce API calls for simple conversations
-#   - Better response times