@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/template-multi-topic.agent

@@ -0,0 +1,160 @@
+# Multi-Topic Agent Template
+# Copy this file to your AiAuthoringBundle directory and rename it to match
+# your agent's developer_name. Replace all placeholder values with real ones.
+# Add, remove, or rename topics as needed.
+
+system:
+    instructions: "You are a helpful assistant. Describe the agent's persona and purpose here."
+    messages:
+        welcome: "Hello! How can I help you today?"
+        error: "Sorry, it looks like something has gone wrong."
+
+config:
+    developer_name: "Agent_API_Name"
+    agent_label: "Agent Display Name"
+    description: "Description of the agent's purpose"
+    # agent_type: "AgentforceServiceAgent" for customer-facing (requires default_agent_user)
+    #             "AgentforceEmployeeAgent" for internal (remove default_agent_user line)
+    agent_type: "AgentforceServiceAgent"
+    default_agent_user: "username@identifier.org"
+
+variables:
+    collected_input: mutable string = ""
+        description: "Replace with a description of what this variable tracks"
+
+language:
+    default_locale: "en_US"
+    additional_locales: ""
+    all_additional_locales: False
+
+start_agent topic_selector:
+    description: "Welcome the user and determine the appropriate topic based on user input"
+    reasoning:
+        actions:
+            go_to_topic_a: @utils.transition to @topic.topic_a
+            go_to_topic_b: @utils.transition to @topic.topic_b
+            go_to_topic_c: @utils.transition to @topic.topic_c
+            go_to_escalation: @utils.transition to @topic.escalation
+            go_to_off_topic: @utils.transition to @topic.off_topic
+
+topic topic_a:
+    label: "Topic A"
+    description: "Describe what this topic handles"
+
+    reasoning:
+        instructions: ->
+            | Replace this with instructions for topic A.
+
+        actions:
+            action_a: @actions.action_a
+                with input_param = ...
+
+    actions:
+        action_a:
+            description: "Describe what this action does"
+            label: "Action A"
+            target: "apex://ClassName"
+            inputs:
+                input_param: string
+                    description: "Describe this parameter"
+                    label: "Parameter Name"
+                    is_required: True
+            outputs:
+                output_field: string
+                    label: "Output Name"
+                    description: "Describe this output"
+                    is_displayable: True
+                    filter_from_agent: False
+
+topic topic_b:
+    label: "Topic B"
+    description: "Describe what this topic handles"
+
+    reasoning:
+        instructions: ->
+            | Replace this with instructions for topic B. This topic demonstrates the gating pattern.
+
+        actions:
+            # Collect data into a variable first
+            collect_data: @utils.setVariables
+                description: "Collect user input into a variable"
+                with collected_input = ...
+
+            # Gate the main action behind the variable
+            main_action: @actions.action_b
+                description: "Describe what this gated action does"
+                available when @variables.collected_input != ""
+                with query_param = @variables.collected_input
+
+    actions:
+        action_b:
+            description: "Describe what this action does"
+            label: "Action B"
+            target: "prompt://PromptTemplateName"
+            inputs:
+                query_param: string
+                    description: "Describe this parameter"
+                    label: "Parameter Name"
+                    is_required: True
+            outputs:
+                result_text: string
+                    description: "Describe this output"
+                    label: "Result"
+                    is_displayable: False
+
+topic topic_c:
+    label: "Topic C"
+    description: "Describe what this topic handles"
+
+    reasoning:
+        instructions: ->
+            | Replace this with base instructions for topic C.
+
+            # Conditional instructions based on variable state
+            if @variables.collected_input != "":
+                | Additional instructions when the variable has been set.
+            else:
+                | Instructions when the variable has not been set yet.
+
+        actions:
+            action_c: @actions.action_c
+                with input_param = ...
+                # Bind an action output to an agent variable
+                set @variables.collected_input = @outputs.result_value
+
+    actions:
+        action_c:
+            description: "Describe what this action does"
+            label: "Action C"
+            target: "flow://FlowName"
+            inputs:
+                input_param: string
+                    description: "Describe this parameter"
+                    label: "Parameter Name"
+                    is_required: True
+            outputs:
+                result_value: string
+                    label: "Result Value"
+                    description: "Describe this output"
+                    is_displayable: True
+                    filter_from_agent: False
+
+topic escalation:
+    label: "Escalation"
+    description: "Handles requests from users who want to transfer or escalate their conversation to a live human agent."
+
+    reasoning:
+        instructions: ->
+            | If a user explicitly asks to transfer to a live agent, escalate the conversation.
+        actions:
+            escalate_to_human: @utils.escalate
+                description: "Escalate to a human agent."
+
+topic off_topic:
+    label: "Off Topic"
+    description: "Redirect conversation to relevant topics when user request goes off-topic"
+
+    reasoning:
+        instructions: ->
+            | The user request is off-topic. Do not answer general knowledge questions.
+              Redirect the conversation by asking how you can help with topics this agent supports.

package/skills/agentforce-development/assets/template-single-topic.agent

@@ -0,0 +1,81 @@
+# Single-Topic Agent Template
+# Copy this file to your AiAuthoringBundle directory and rename it to match
+# your agent's developer_name. Replace all placeholder values with real ones.
+
+system:
+    instructions: "You are a helpful assistant. Describe the agent's persona and purpose here."
+    messages:
+        welcome: "Hello! How can I help you today?"
+        error: "Sorry, it looks like something has gone wrong."
+
+config:
+    developer_name: "Agent_API_Name"
+    agent_label: "Agent Display Name"
+    description: "Description of the agent's purpose"
+    # agent_type: "AgentforceServiceAgent" for customer-facing (requires default_agent_user)
+    #             "AgentforceEmployeeAgent" for internal (remove default_agent_user line)
+    agent_type: "AgentforceServiceAgent"
+    default_agent_user: "username@identifier.org"
+
+language:
+    default_locale: "en_US"
+    additional_locales: ""
+    all_additional_locales: False
+
+start_agent topic_selector:
+    description: "Welcome the user and determine the appropriate topic based on user input"
+    reasoning:
+        actions:
+            go_to_main: @utils.transition to @topic.main
+            go_to_escalation: @utils.transition to @topic.escalation
+            go_to_off_topic: @utils.transition to @topic.off_topic
+
+topic main:
+    label: "Main Topic"
+    description: "Describe what this topic handles. The Atlas Reasoning Engine matches user utterances against this description."
+
+    reasoning:
+        instructions: ->
+            | Replace this with instructions for how the agent should handle requests in this topic.
+              Reference actions with the syntax shown below.
+
+        actions:
+            do_action: @actions.do_action
+                with input_param = ...
+
+    actions:
+        do_action:
+            description: "Describe what this action does"
+            label: "Action Display Name"
+            target: "apex://ClassName"
+            inputs:
+                input_param: string
+                    description: "Describe this parameter"
+                    label: "Parameter Display Name"
+                    is_required: True
+            outputs:
+                output_field: string
+                    label: "Output Display Name"
+                    description: "Describe this output"
+                    is_displayable: True
+                    filter_from_agent: False
+
+topic escalation:
+    label: "Escalation"
+    description: "Handles requests from users who want to transfer or escalate their conversation to a live human agent."
+
+    reasoning:
+        instructions: ->
+            | If a user explicitly asks to transfer to a live agent, escalate the conversation.
+        actions:
+            escalate_to_human: @utils.escalate
+                description: "Escalate to a human agent."
+
+topic off_topic:
+    label: "Off Topic"
+    description: "Redirect conversation to relevant topics when user request goes off-topic"
+
+    reasoning:
+        instructions: ->
+            | The user request is off-topic. Do not answer general knowledge questions.
+              Redirect the conversation by asking how you can help with topics this agent supports.

package/skills/agentforce-development/assets/verification-gate.agent

@@ -0,0 +1,208 @@
+# Verification Gate Architecture Template
+# ========================================
+#
+# This template demonstrates the Verification Gate pattern where users
+# must pass through identity verification before accessing sensitive topics.
+#
+# Pattern: Security gate before protected functionality
+# Use when: Handling sensitive data, payments, PII access
+#
+# Key Features:
+# - Deterministic verification (code-enforced, not LLM suggestions)
+# - available when guards make actions invisible until verified
+# - Post-action checks at TOP of instructions
+# - Automatic escalation after 3 failed attempts
+
+system:
+   messages:
+      welcome: "Welcome! I'll need to verify your identity before we proceed."
+      error: "I apologize, something went wrong. Let me try again."
+   instructions: "You are a secure customer service agent. Always verify identity before sensitive operations."
+
+config:
+   agent_name: "SecureAgent"
+   agent_label: "Secure Customer Agent"
+   description: "Agent with verification gate for sensitive operations"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+variables:
+   # Identity verification state
+   customer_verified: mutable boolean = False
+      description: "Has customer passed identity verification"
+   failed_attempts: mutable number = 0
+      description: "Number of failed verification attempts"
+
+   # Session context (read-only from external source)
+   customer_id: linked string
+      source: @session.customerId
+      description: "Customer ID from session"
+   customer_email: linked string
+      source: @session.customerEmail
+      description: "Customer email from session"
+
+   # Operation state
+   refund_status: mutable string = ""
+      description: "Status of refund operation"
+   churn_risk_score: mutable number = 0
+      description: "Customer churn risk from Data Cloud"
+
+# ============================================================
+# ENTRY POINT
+# ============================================================
+
+start_agent entry:
+   description: "Entry point - routes through verification"
+   reasoning:
+      instructions: |
+         Welcome the customer and route to identity verification.
+      actions:
+         start_verification: @utils.transition to @topic.identity_verification
+            description: "Begin identity verification process"
+
+# ============================================================
+# VERIFICATION GATE (Security Check)
+# ============================================================
+
+topic identity_verification:
+   description: "Verify customer identity before proceeding"
+   reasoning:
+      instructions: ->
+         # SECURITY: Check for lockout FIRST (deterministic)
+         if @variables.failed_attempts >= 3:
+            | Too many failed attempts. Transferring to a human agent.
+            transition to @topic.escalation
+
+         # Already verified? Proceed to protected topics
+         if @variables.customer_verified == True:
+            | Identity verified! How can I help you today?
+
+         # Not yet verified
+         if @variables.customer_verified == False:
+            | Please verify your identity by confirming your email address.
+            | I have your email on file - please confirm it matches.
+
+      actions:
+         verify_email: @actions.verify_email
+            description: "Verify customer email"
+            with email = @variables.customer_email
+            set @variables.customer_verified = @outputs.verified
+
+         # GUARDED: Only visible when verified
+         go_to_account: @utils.transition to @topic.account_management
+            description: "Access account settings"
+            available when @variables.customer_verified == True
+
+         go_to_refund: @utils.transition to @topic.refund_processor
+            description: "Process a refund request"
+            available when @variables.customer_verified == True
+
+         # Always available
+         escalate_now: @utils.escalate
+            description: "Transfer to human agent"
+
+# ============================================================
+# PROTECTED: Account Management
+# ============================================================
+
+topic account_management:
+   description: "Manage customer account (requires verification)"
+   reasoning:
+      instructions: ->
+         # SECURITY GATE: Re-check verification
+         if @variables.customer_verified == False:
+            transition to @topic.identity_verification
+
+         | Welcome to account management.
+         | What would you like to do with your account?
+
+      actions:
+         update_email: @actions.update_email
+            description: "Update email address"
+            available when @variables.customer_verified == True
+         update_preferences: @actions.update_preferences
+            description: "Update communication preferences"
+            available when @variables.customer_verified == True
+         back: @utils.transition to @topic.identity_verification
+            description: "Return to main menu"
+
+# ============================================================
+# PROTECTED: Refund Processor (with Post-Action Pattern)
+# ============================================================
+
+topic refund_processor:
+   description: "Process refund requests (requires verification)"
+   reasoning:
+      instructions: ->
+         # SECURITY GATE: Re-check verification
+         if @variables.customer_verified == False:
+            transition to @topic.identity_verification
+
+         # ====================================================
+         # POST-ACTION CHECK (at TOP - triggers on loop)
+         # ====================================================
+         if @variables.refund_status == "Approved":
+            # Deterministic follow-up - LLM cannot skip!
+            run @actions.create_crm_case
+               with customer_id = @variables.customer_id
+               with refund_amount = @variables.refund_amount
+            transition to @topic.success_confirmation
+
+         # ====================================================
+         # PRE-LLM: Load churn risk data
+         # ====================================================
+         run @actions.check_churn_risk
+            with customer_id = @variables.customer_id
+            set @variables.churn_risk_score = @outputs.score
+
+         # ====================================================
+         # DYNAMIC INSTRUCTIONS (based on churn risk)
+         # ====================================================
+         | Customer risk score: {!@variables.churn_risk_score}
+
+         if @variables.churn_risk_score >= 80:
+            | HIGH RISK - Offer a full cash refund to retain this customer.
+         else:
+            | STANDARD - Offer a $10 store credit as goodwill.
+
+      actions:
+         approve_full_refund: @actions.process_refund
+            description: "Approve full cash refund"
+            available when @variables.churn_risk_score >= 80
+            with type = "full"
+            set @variables.refund_status = @outputs.status
+
+         offer_credit: @actions.issue_credit
+            description: "Offer store credit"
+            available when @variables.churn_risk_score < 80
+            with amount = 10
+            set @variables.refund_status = @outputs.status
+
+# ============================================================
+# SUCCESS CONFIRMATION
+# ============================================================
+
+topic success_confirmation:
+   description: "Confirm successful operation"
+   reasoning:
+      instructions: |
+         Great news! Your request has been processed successfully.
+         Is there anything else I can help you with?
+      actions:
+         new_request: @utils.transition to @topic.identity_verification
+            description: "Start a new request"
+         end_conversation: @actions.end_session
+            description: "End the conversation"
+
+# ============================================================
+# ESCALATION (Handoff to Human)
+# ============================================================
+
+topic escalation:
+   description: "Escalate to human agent"
+   reasoning:
+      instructions: |
+         I'm transferring you to a human agent who can better assist you.
+         Please hold while I connect you.
+      actions:
+         handoff: @utils.escalate
+            description: "Transfer to human agent"

package/skills/agentforce-development/references/action-prompt-templates.md

@@ -0,0 +1,164 @@
+# Prompt Template Actions
+
+Invoking Salesforce Prompt Templates as actions within Agent Script.
+
+---
+
+## Overview
+
+Prompt Template Actions let agents invoke Salesforce Prompt Templates via the `generatePromptResponse://` protocol. The agent passes structured inputs to the template and receives a generated `promptResponse` output — keeping content generation in the template while the agent manages conversation flow.
+
+**When to use**: Personalized responses, summarization, content generation, recommendations — anything where an LLM prompt template produces better output than static Flow logic.
+
+---
+
+## Action Definition (Agentforce Assets)
+
+Define the action in **Setup > Agentforce > Action Definitions** (or via metadata API):
+
+```agentscript
+actions:
+  Generate_Personalized_Schedule:
+    description: "Generate a personalized schedule using a prompt template"
+    inputs:
+      "Input:email": string
+        description: "User's email address"
+        is_required: True
+      "Input:preferences": string
+        description: "User's scheduling preferences"
+        is_required: False
+    outputs:
+      promptResponse: string
+        description: "The personalized schedule generated by the template"
+        is_used_by_planner: True
+    target: "generatePromptResponse://Generate_Personalized_Schedule"
+```
+
+### Critical syntax rules
+
+| Rule | Example |
+|------|---------|
+| Target protocol | `"generatePromptResponse://TemplateName"` |
+| Input names **must be quoted** | `"Input:email"` not `Input:email` |
+| Input prefix is `Input:` | Matches the template's input field API name |
+| Output field is always `promptResponse` | Single string output from the template |
+
+---
+
+## Agent Script Invocation
+
+Reference the action definition in your `.agent` file:
+
+```agentscript
+topic schedule_generation:
+  reasoning:
+    actions:
+      generate_schedule: @actions.Generate_Personalized_Schedule
+        with "Input:email"=@variables.user_email
+             "Input:preferences"=...
+        set @variables.schedule = @outputs.promptResponse
+```
+
+**Input binding patterns** (same as regular actions):
+- `@variables.user_email` — variable binding (data from prior turns)
+- `...` — LLM slot-filling (extract from conversation)
+- `"professional"` — fixed value (business rule constant)
+
+---
+
+## Grounded Data Integration
+
+Templates can include **data providers** (Apex classes, Flows) that supply contextual data for personalized responses. The grounding happens inside the template — Agent Script only needs to pass the lookup key:
+
+```agentscript
+actions:
+  Get_Product_Recommendations:
+    description: "Generate personalized product recommendations based on purchase history"
+    inputs:
+      "Input:customerId": string
+        description: "Customer ID for personalization"
+        is_required: True
+    outputs:
+      promptResponse: string
+        description: "Personalized recommendations grounded in customer data"
+    target: "generatePromptResponse://Product_Recommender"
+```
+
+The template itself (configured in Prompt Builder) includes:
+- **Data Provider**: Apex class fetching customer purchase history
+- **Grounding**: Recent orders, preferences, browsing history
+- **Template instructions**: How to format recommendations using the grounded data
+
+---
+
+## Common Patterns
+
+### Pattern 1: Content Generation
+
+```agentscript
+generate_email: @actions.Generate_Email_Response
+  with "Input:customerMessage"=@variables.user_message
+       "Input:tone"="professional"
+       "Input:context"=@variables.case_context
+  set @variables.email_draft = @outputs.promptResponse
+```
+
+### Pattern 2: Summarization
+
+```agentscript
+summarize: @actions.Summarize_Conversation
+  with "Input:conversationHistory"=@variables.chat_history
+       "Input:maxLength"="500"
+  set @variables.summary = @outputs.promptResponse
+```
+
+### Pattern 3: Personalized Recommendations
+
+```agentscript
+recommend: @actions.Get_Product_Recommendations
+  with "Input:customerId"=@variables.customer_id
+       "Input:category"=...
+  set @variables.recommendations = @outputs.promptResponse
+```
+
+---
+
+## Known Limitation: `run` Keyword with Prompt Templates
+
+Chained actions using `run` may not properly map `"Input:X"` parameters:
+
+```agentscript
+# ❌ MAY NOT WORK — run + prompt template input binding:
+process: @actions.create_order
+  with customer_id=@variables.customer_id
+  run @actions.Generate_Order_Summary
+    with "Input:orderId"=@variables.order_id    # Input binding may fail
+
+# ✅ WORKAROUND — call as primary action instead:
+generate_summary: @actions.Generate_Order_Summary
+  with "Input:orderId"=@variables.order_id      # Works as primary action
+  set @variables.summary = @outputs.promptResponse
+```
+
+---
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `SyntaxError` on input binding | Missing quotes on parameter name | Use `"Input:email"` not `Input:email` |
+| Template not found | Wrong protocol or template name | Verify `generatePromptResponse://ExactTemplateName` |
+| Empty `promptResponse` | Template inactive or missing required inputs | Activate template in Setup, check all `is_required: True` inputs are bound |
+| Input not mapped | API name mismatch | Input field name after `Input:` must exactly match template's input API name |
+
+---
+
+## Checklist
+
+- [ ] Template exists in org and is **active**
+- [ ] Input field API names match template configuration exactly
+- [ ] All `is_required: True` inputs are bound (via `...`, `@variables`, or fixed)
+- [ ] `promptResponse` output is captured with `set`
+- [ ] Template response quality tested with representative inputs
+- [ ] If using grounded data: data provider returns expected records
+