@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/developing-agentforce/assets/patterns/README.md

@@ -1,254 +0,0 @@
-# Agent Script Patterns
-
-This folder contains reusable patterns for common Agentforce scenarios.
-
-## Pattern Decision Tree
-
-```
-What do you need?
-│
-├─► Guaranteed post-action processing?
-│   └─► Use: action-callbacks.agent
-│       (run keyword for deterministic callbacks)
-│
-├─► Setup/cleanup for every reasoning turn?
-│   └─► Use: lifecycle-events.agent
-│       (before_reasoning / after_reasoning blocks)
-│
-├─► Navigate to specialist subagent and return with results?
-│   └─► Use: bidirectional-routing.agent
-│       (store return address, specialist subagent transitions back)
-│
-├─► Complex parameter passing to actions?
-│   └─► Use: advanced-input-bindings.agent
-│       (slot filling, variable binding, output chaining)
-│
-├─► Dynamic behavior based on user context?
-│   └─► Use: system-instruction-overrides.agent
-│       (tier-based, time-based, feature flag instructions)
-│
-├─► Authentication gate with deferred routing?
-│   └─► Use: open-gate-routing.agent
-│       (3-variable state machine with LLM bypass)
-│
-└─► None of the above?
-    └─► Start with: ../getting-started/hello-world.agent
-```
-
-## Patterns Overview
-
-### 1. [action-callbacks.agent](action-callbacks.agent)
-
-**Purpose**: Chain actions with guaranteed execution using `run` keyword.
-
-**Use when**:
-- Follow-up actions MUST happen after parent action
-- Audit logging required for compliance
-- Order matters (send email AFTER order created)
-
-**Key syntax**:
-```agentscript
-process_order: @actions.create_order
-   with customer_id=...
-   set @variables.order_id = @outputs.order_id
-   run @actions.send_confirmation        # Always runs after create_order
-      with order_id=@variables.order_id
-   run @actions.log_activity             # Always runs after confirmation
-      with event_type="ORDER_CREATED"
-```
-
----
-
-### 2. [lifecycle-events.agent](lifecycle-events.agent)
-
-**Purpose**: Run code before/after every reasoning step automatically.
-
-**Use when**:
-- Track conversation metrics (turn count, duration)
-- Refresh context before each response
-- Log analytics after each turn
-- Initialize state on first turn
-
-**Key syntax**:
-```agentscript
-subagent conversation:
-   before_reasoning:
-      set @variables.turn_count = @variables.turn_count + 1
-      run @actions.refresh_context
-
-   reasoning:
-      instructions: ->
-         | This is turn {!@variables.turn_count}
-
-   after_reasoning:
-      run @actions.log_analytics
-```
-
----
-
-### 3. [bidirectional-routing.agent](bidirectional-routing.agent)
-
-**Purpose**: Navigate to specialist subagent and return with results.
-
-**Use when**:
-- Complex workflows spanning multiple subagents
-- "Consult an expert" pattern
-- Need to bring results back to coordinator
-- Want separation of concerns
-
-**Key syntax**:
-```agentscript
-# In main subagent
-consult_pricing: @utils.transition to @subagent.pricing_specialist
-
-# In specialist subagent
-before_reasoning:
-   set @variables.return_subagent = "main_hub"
-
-# ... do specialist work ...
-
-return_with_results: @utils.transition to @subagent.main_hub
-```
-
----
-
-### 4. [advanced-input-bindings.agent](advanced-input-bindings.agent)
-
-**Purpose**: Master all parameter binding techniques for actions.
-
-**Use when**:
-- Learning different ways to pass values to actions
-- Complex multi-input action scenarios
-- Chaining outputs between multiple actions
-- Mixing LLM slot filling with stored state
-
-**Key syntax**:
-```agentscript
-reasoning:
-   actions:
-      # Slot filling: LLM extracts from conversation
-      lookup: @actions.get_order
-         with order_id=...
-
-      # Variable binding: Use stored state
-      bound: @actions.get_order
-         with order_id=@variables.current_order_id
-
-      # Output chaining: Use previous action's result
-      process: @actions.create_order
-         with items=...
-         set @variables.order_id = @outputs.order_id
-         run @actions.send_notification
-            with order_id=@outputs.order_id    # Chained output
-```
-
-**Binding Pattern Quick Reference**:
-| Pattern | Syntax | When to Use |
-|---------|--------|-------------|
-| Slot Filling | `with x=...` | LLM extracts from conversation |
-| Fixed Value | `with x="value"` | Always use a constant |
-| Variable | `with x=@variables.y` | Use stored state |
-| Output | `with x=@outputs.y` | Chain from previous action |
-
----
-
-### 5. [system-instruction-overrides.agent](system-instruction-overrides.agent)
-
-**Purpose**: Dynamic agent behavior based on context (user tier, time, features).
-
-**Use when**:
-- Different behavior for different user segments (VIP vs standard)
-- Time-based changes (business hours vs after hours)
-- Feature flags controlling agent personality
-- A/B testing different conversation styles
-
-**Key syntax**:
-```agentscript
-# System block: Static base instructions
-system:
-   instructions: "You are a professional agent. Be helpful and courteous."
-
-# Subagent reasoning: Dynamic overrides
-reasoning:
-   instructions: ->
-      if @variables.customer_tier == "vip":
-         | PRIORITY CUSTOMER - Provide white-glove service.
-         | You have authority to offer 20% discounts.
-
-      if @variables.business_hours == False:
-         | We are outside business hours.
-         | Complex issues should be logged for follow-up.
-
-      | Respond to the customer's inquiry.
-```
-
-**Override Strategy**:
-| Layer | Type | Best For |
-|-------|------|----------|
-| `system:` | Static | Guardrails, base personality |
-| `reasoning:` | Dynamic | Personalization, context-aware behavior |
-
----
-
-### 6. [open-gate-routing.agent](open-gate-routing.agent)
-
-**Purpose**: Auth-gated subagent routing with LLM bypass using a 3-variable state machine.
-
-**Use when**:
-- Multiple protected subagents require authentication before access
-- You want zero-credit LLM bypass while a gate subagent holds focus
-- Users should be redirected to auth, then automatically returned to their intended subagent
-- You need an EXIT_PROTOCOL to release gate state when users change intent
-
-**Key syntax**:
-```agentscript
-# agent_router bypasses LLM when open_gate is set
-before_reasoning:
-   if @variables.open_gate == "protected_workflow":
-      transition to @subagent.protected_workflow
-   if @variables.open_gate == "authentication_gate":
-      transition to @subagent.authentication_gate
-```
-
-**Credit**: Hua Xu (Salesforce APAC FDE team) — production pattern from Kogan agent deployment.
-
----
-
-## Pattern Combinations
-
-These patterns can be combined:
-
-```
-lifecycle-events + action-callbacks
-├── before_reasoning: Initialize context
-├── reasoning: Process with callbacks
-│   └── action with run callbacks
-└── after_reasoning: Log results
-
-open-gate-routing + lifecycle-events
-├── before_reasoning: Gate check + context refresh
-├── reasoning: Protected actions (if authenticated)
-└── after_reasoning: Post-auth routing + analytics
-```
-
-## Validation Scoring Impact
-
-| Pattern | Scoring Boost | Key Requirements |
-|---------|--------------|------------------|
-| Action Callbacks | +5 pts | No nested run |
-| Lifecycle Events | +5 pts | Proper block placement |
-| Bidirectional | +5 pts | Return transitions |
-| Input Bindings | +5 pts | Proper binding patterns |
-| System Overrides | +5 pts | Static system, dynamic subagents |
-| Open Gate | +5 pts | 3-variable coordination |
-
-## Anti-Patterns to Avoid
-
-| ❌ Don't | ✅ Do Instead |
-|----------|---------------|
-| Nested `run` inside `run` | Sequential `run` at same level |
-| Lifecycle in wrong order | before_reasoning, reasoning, after_reasoning |
-| Forget return transition | Always include return action in specialists |
-| Use lifecycle for one-time setup | Use if @variables.turn_count == 1 |
-| Missing EXIT_PROTOCOL in gate pattern | Always include gate reset subagent |
-| Hardcoding gate subagent name in open_gate | Use variable-driven routing |

package/skills/developing-agentforce/assets/patterns/action-callbacks.agent

@@ -1,178 +0,0 @@
-# Action Callbacks Pattern
-# Use the `run` keyword for deterministic post-action processing
-#
-# ★ When To Use This Pattern:
-#   - You need guaranteed follow-up after an action completes
-#   - Audit logging or notifications must ALWAYS happen
-#   - Chain multiple actions where order matters
-#
-# ★ Key Insight:
-#   The `run` keyword executes AFTER the parent action completes.
-#   This is deterministic (not LLM-decided) - the callback ALWAYS runs.
-#   Use this when you can't afford to skip follow-up steps.
-#
-# ★ Validation Impact:
-#   - [5 pts] Actions with proper callback structure
-#   - Avoid nested run (only 1 level of nesting allowed)
-#
-# This is a PARTIAL template - integrate into a complete agent file
-
-subagent order_processing:
-	label: "Order Processing"
-	description: "Processes orders with guaranteed confirmation and logging"
-
-	actions:
-		create_order:
-			description: "Creates a new order in the system"
-			inputs:
-				customer_id: string
-					description: "Customer identifier"
-				items: list[string]
-					description: "List of item SKUs"
-				total: number
-					description: "Order total amount"
-			outputs:
-				order_id: string
-					description: "Generated order ID"
-				status: string
-					description: "Order creation status"
-			target: "flow://Create_Order"
-
-		send_confirmation:
-			description: "Sends order confirmation email"
-			inputs:
-				order_id: string
-					description: "Order ID to confirm"
-				customer_email: string
-					description: "Customer email address"
-			outputs:
-				sent: boolean
-					description: "Whether email was sent"
-			target: "flow://Send_Order_Confirmation"
-
-		log_activity:
-			description: "Logs activity for audit trail"
-			inputs:
-				event_type: string
-					description: "Type of event to log"
-				details: string
-					description: "Event details"
-			outputs:
-				logged: boolean
-					description: "Whether log was recorded"
-			target: "apex://AuditService.logEvent"
-
-	reasoning:
-		instructions: ->
-			| Help the customer place their order.
-			| Ensure confirmation is sent after successful orders.
-			| All order activities must be logged for compliance.
-		actions:
-			# This action uses callbacks to guarantee follow-up
-			process_order: @actions.create_order
-				with customer_id=@variables.customer_id
-				with items=...
-				with total=...
-				set @variables.order_id = @outputs.order_id
-				set @variables.order_status = @outputs.status
-				# Callback 1: Always send confirmation after order created
-				run @actions.send_confirmation
-					with order_id=@variables.order_id
-					with customer_email=@variables.customer_email
-				# Callback 2: Always log the activity
-				run @actions.log_activity
-					with event_type="ORDER_CREATED"
-					with details=@variables.order_id
-
-			back_to_menu: @utils.transition to @subagent.agent_router
-
-# ★ Anti-Pattern: Nested run (DO NOT DO THIS)
-#
-# process: @actions.first
-#    run @actions.second
-#       run @actions.third   # ❌ INVALID - nested run not allowed
-#
-# ★ Correct Pattern: Sequential callbacks (all at same level)
-#
-# process: @actions.first
-#    run @actions.second     # ✅ First callback
-#    run @actions.third      # ✅ Second callback (runs after second)
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# ★ Pattern 2: Simple Variable Updates (No Callback Needed)
-# ═══════════════════════════════════════════════════════════════════════════════
-#
-# For simple operations like incrementing counters or storing outputs,
-# use `set` statements directly - NO `run` keyword needed.
-#
-# ⚠️ IMPORTANT: This pattern works in BOTH GenAiPlannerBundle AND AiAuthoringBundle
-#    The `run` keyword ONLY works in GenAiPlannerBundle (not AiAuthoringBundle)
-#    Use `set` statements for AiAuthoringBundle deployments
-#
-# Example: Create case and track count (works in BOTH bundle types)
-
-subagent case_management:
-	label: "Case Management"
-	description: "Creates cases and tracks statistics"
-
-	actions:
-		create_case:
-			description: "Creates a new support case"
-			inputs:
-				inp_CustomerId: string
-					description: "Contact ID for the case"
-				inp_Subject: string
-					description: "Subject line for the case"
-			outputs:
-				out_CaseNumber: string
-					description: "Generated case number"
-				out_CaseId: string
-					description: "Salesforce ID of the created case"
-			target: "flow://Create_Case"
-
-	reasoning:
-		instructions: ->
-			| Help the customer create support cases.
-			| Track case count for session statistics.
-		actions:
-			# ✅ Simple pattern - just use `set` for variable updates
-			create_support_case: @actions.create_case
-				with inp_CustomerId=@variables.ContactId
-				with inp_Subject=...
-				set @variables.case_number = @outputs.out_CaseNumber
-				set @variables.case_id = @outputs.out_CaseId
-				set @variables.cases_created = @variables.cases_created + 1  # Direct increment!
-
-			back_to_menu: @utils.transition to @subagent.agent_router
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# ⛔ INVALID KEYWORDS - NEVER USE THESE
-# ═══════════════════════════════════════════════════════════════════════════════
-#
-# The following keywords DO NOT EXIST in Agent Script. Using them causes:
-#   SyntaxError: Unexpected '[keyword]'
-#
-# ❌ internal_actions  - Does not exist (Claude may invent this for "local helpers")
-# ❌ helper_actions    - Does not exist
-# ❌ private_actions   - Does not exist
-# ❌ local_actions     - Does not exist
-#
-# If you need simple variable operations after an action, use `set` directly:
-#
-# ❌ WRONG (internal_actions does not exist):
-#
-# internal_actions:
-#    increment_counter:
-#       set @variables.count = @variables.count + 1
-#
-# reasoning:
-#    actions:
-#       process: @actions.create_case
-#          run @actions.increment_counter   # ❌ Can't reference internal action
-#
-# ✅ CORRECT (use set directly in the action block):
-#
-# reasoning:
-#    actions:
-#       process: @actions.create_case
-#          set @variables.count = @variables.count + 1  # ✅ Direct set works!

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

@@ -1,141 +0,0 @@
-# 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"
-
-subagent 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