@salesforce/afv-skills 1.1.0 → 1.2.0

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

@@ -0,0 +1,254 @@
+# 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 and return with results?
+│   └─► Use: bidirectional-routing.agent
+│       (store return address, specialist 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
+topic 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 topic and return with results.
+
+**Use when**:
+- Complex workflows spanning multiple topics
+- "Consult an expert" pattern
+- Need to bring results back to coordinator
+- Want separation of concerns
+
+**Key syntax**:
+```agentscript
+# In main topic
+consult_pricing: @utils.transition to @topic.pricing_specialist
+
+# In specialist topic
+before_reasoning:
+   set @variables.return_topic = "main_hub"
+
+# ... do specialist work ...
+
+return_with_results: @utils.transition to @topic.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."
+
+# Topic 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 topic routing with LLM bypass using a 3-variable state machine.
+
+**Use when**:
+- Multiple protected topics require authentication before access
+- You want zero-credit LLM bypass while a gate topic holds focus
+- Users should be redirected to auth, then automatically returned to their intended topic
+- You need an EXIT_PROTOCOL to release gate state when users change intent
+
+**Key syntax**:
+```agentscript
+# topic_selector bypasses LLM when open_gate is set
+before_reasoning:
+   if @variables.open_gate == "protected_workflow":
+      transition to @topic.protected_workflow
+   if @variables.open_gate == "authentication_gate":
+      transition to @topic.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 topics |
+| 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 topic |
+| Hardcoding gate topic name in open_gate | Use variable-driven routing |

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

@@ -0,0 +1,178 @@
+# 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
+
+topic 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 @topic.topic_selector
+
+# ★ 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)
+
+topic 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 @topic.topic_selector
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ⛔ 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/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