@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/developing-agentforce/assets/template-multi-subagent.agent

@@ -1,160 +0,0 @@
-# Multi-Subagent 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 subagents 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 agent_router:
-    description: "Welcome the user and determine the appropriate subagent based on user input"
-    reasoning:
-        actions:
-            go_to_subagent_a: @utils.transition to @subagent.subagent_a
-            go_to_subagent_b: @utils.transition to @subagent.subagent_b
-            go_to_subagent_c: @utils.transition to @subagent.subagent_c
-            go_to_escalation: @utils.transition to @subagent.escalation
-            go_to_off_topic: @utils.transition to @subagent.off_topic
-
-subagent subagent_a:
-    label: "Subagent A"
-    description: "Describe what this subagent handles"
-
-    reasoning:
-        instructions: ->
-            | Replace this with instructions for subagent 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
-
-subagent subagent_b:
-    label: "Subagent B"
-    description: "Describe what this subagent handles"
-
-    reasoning:
-        instructions: ->
-            | Replace this with instructions for subagent B. This subagent 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
-
-subagent subagent_c:
-    label: "Subagent C"
-    description: "Describe what this subagent handles"
-
-    reasoning:
-        instructions: ->
-            | Replace this with base instructions for subagent 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
-
-subagent 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."
-
-subagent off_topic:
-    label: "Off Topic"
-    description: "Redirect conversation to relevant subagents 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 the subagents this agent supports.

package/skills/developing-agentforce/assets/template-single-subagent.agent

@@ -1,81 +0,0 @@
-# Single-Subagent 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 agent_router:
-    description: "Welcome the user and determine the appropriate subagent based on user input"
-    reasoning:
-        actions:
-            go_to_main: @utils.transition to @subagent.main
-            go_to_escalation: @utils.transition to @subagent.escalation
-            go_to_off_topic: @utils.transition to @subagent.off_topic
-
-subagent main:
-    label: "Main Subagent"
-    description: "Describe what this subagent 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 subagent.
-              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
-
-subagent 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."
-
-subagent off_topic:
-    label: "Off Topic"
-    description: "Redirect conversation to relevant subagents 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 the subagents this agent supports.

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

@@ -1,208 +0,0 @@
-# Verification Gate Architecture Template
-# ========================================
-#
-# This template demonstrates the Verification Gate pattern where users
-# must pass through identity verification before accessing sensitive subagents.
-#
-# 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 @subagent.identity_verification
-            description: "Begin identity verification process"
-
-# ============================================================
-# VERIFICATION GATE (Security Check)
-# ============================================================
-
-subagent 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 @subagent.escalation
-
-         # Already verified? Proceed to protected subagents
-         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 @subagent.account_management
-            description: "Access account settings"
-            available when @variables.customer_verified == True
-
-         go_to_refund: @utils.transition to @subagent.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
-# ============================================================
-
-subagent account_management:
-   description: "Manage customer account (requires verification)"
-   reasoning:
-      instructions: ->
-         # SECURITY GATE: Re-check verification
-         if @variables.customer_verified == False:
-            transition to @subagent.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 @subagent.identity_verification
-            description: "Return to main menu"
-
-# ============================================================
-# PROTECTED: Refund Processor (with Post-Action Pattern)
-# ============================================================
-
-subagent refund_processor:
-   description: "Process refund requests (requires verification)"
-   reasoning:
-      instructions: ->
-         # SECURITY GATE: Re-check verification
-         if @variables.customer_verified == False:
-            transition to @subagent.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 @subagent.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
-# ============================================================
-
-subagent 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 @subagent.identity_verification
-            description: "Start a new request"
-         end_conversation: @actions.end_session
-            description: "End the conversation"
-
-# ============================================================
-# ESCALATION (Handoff to Human)
-# ============================================================
-
-subagent 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/developing-agentforce/references/action-prompt-templates.md

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