@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/agentforce-development/assets/patterns/prompt-template-action.agent

@@ -0,0 +1,188 @@
+# Prompt Template Action Pattern
+# Invoke Salesforce PromptTemplates directly from Agent Script
+#
+# ★ When To Use This Pattern:
+#   - Generate dynamic AI content (summaries, emails, recommendations)
+#   - Use Einstein Prompt Builder templates from agents
+#   - Combine structured data with LLM generation
+#   - Leverage existing PromptTemplate investments
+#
+# ★ Key Insights:
+#   - Target uses generatePromptResponse:// protocol (not flow://)
+#   - Input names MUST have "Input:" prefix (critical!)
+#   - Output field is always named "promptResponse"
+#   - PromptTemplate must be deployed BEFORE the agent
+#
+# ★ Important Limitation:
+#   - Template API name must exactly match target
+#   - Record-bound templates require recordId input
+#
+# This is a COMPLETE template - customize for your use case
+
+system:
+	instructions: "You are a content generation assistant. Help users create personalized content using AI templates. Always verify the generated content meets quality standards."
+	messages:
+		welcome: "Hello! I can help generate personalized content for you."
+		error: "I encountered an issue generating content. Let me try again."
+
+config:
+	agent_name: "Content_Generator_Agent"
+	default_agent_user: "agent@company.salesforce.com"
+	agent_label: "Content Generator"
+	description: "Agent that generates AI content using Prompt Templates"
+
+variables:
+	# Standard linked variables
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+
+	# Content generation variables
+	generated_schedule: mutable string = ""
+		description: "AI-generated schedule content"
+	generated_email: mutable string = ""
+		description: "AI-generated email content"
+	user_email: mutable string = ""
+		description: "User's email address"
+	user_timezone: mutable string = "America/Los_Angeles"
+		description: "User's timezone"
+	recipient_name: mutable string = ""
+		description: "Email recipient name"
+	email_topic: mutable string = ""
+		description: "Topic for email generation"
+
+language:
+	default_locale: "en_US"
+
+start_agent topic_selector:
+	label: "Content Generator"
+	description: "Routes to content generation options"
+
+	reasoning:
+		instructions: ->
+			| Ask the user what type of content they'd like to generate:
+			| 1. Personalized daily schedule
+			| 2. Professional email
+			|
+			| Route to the appropriate topic.
+		actions:
+			go_schedule: @utils.transition to @topic.schedule_generation
+			go_email: @utils.transition to @topic.email_generation
+
+topic schedule_generation:
+	label: "Schedule Generation"
+	description: "Generate personalized daily schedules"
+
+	actions:
+		# ★ PROMPT TEMPLATE ACTION - Key syntax elements:
+		# 1. target: uses generatePromptResponse:// protocol
+		# 2. inputs: MUST use "Input:" prefix
+		# 3. outputs: field name is always "promptResponse"
+		Generate_Personalized_Schedule:
+			description: "Generate a personalized daily schedule using AI."
+			inputs:
+				# ★ CRITICAL: Input names must have "Input:" prefix
+				# These map to {!email} and {!timezone} in the PromptTemplate
+				"Input:email": string
+					description: "User's email address for preference lookup"
+					is_required: True
+				"Input:timezone": string
+					description: "User's timezone for schedule formatting"
+					is_required: False
+			outputs:
+				# ★ Standard output field name for prompt responses
+				promptResponse: string
+					description: "The AI-generated schedule content"
+					is_used_by_planner: True
+					is_displayable: True
+			# ★ Target protocol: generatePromptResponse://TemplateApiName
+			target: "generatePromptResponse://Generate_Personalized_Schedule"
+
+	reasoning:
+		instructions: ->
+			| Help the user create a personalized daily schedule.
+			|
+			| 1. Ask for their email (required)
+			| 2. Ask for their timezone (optional, defaults to Pacific)
+			| 3. Generate the schedule using the AI template
+			| 4. Present the generated schedule
+			|
+			| The schedule will include morning routine, work blocks,
+			| breaks, and evening wind-down based on preferences.
+
+		actions:
+			create_schedule: @actions.Generate_Personalized_Schedule
+				# ★ Input binding with quoted field names
+				with "Input:email"=@variables.user_email
+				with "Input:timezone"=@variables.user_timezone
+				set @variables.generated_schedule = @outputs.promptResponse
+
+			back: @utils.transition to @topic.topic_selector
+
+topic email_generation:
+	label: "Email Generation"
+	description: "Generate professional emails"
+
+	actions:
+		# Another Prompt Template action example
+		Generate_Professional_Email:
+			description: "Generate a professional email draft."
+			inputs:
+				"Input:recipientName": string
+					description: "Name of the email recipient"
+					is_required: True
+				"Input:topic": string
+					description: "Topic or purpose of the email"
+					is_required: True
+				"Input:tone": string
+					description: "Desired tone: formal, friendly, urgent"
+					is_required: False
+			outputs:
+				promptResponse: string
+					description: "The generated email content"
+					is_used_by_planner: True
+					is_displayable: True
+			target: "generatePromptResponse://Generate_Professional_Email"
+
+	reasoning:
+		instructions: ->
+			| Help the user draft a professional email.
+			|
+			| Collect:
+			| 1. Recipient's name (required)
+			| 2. Email topic/purpose (required)
+			| 3. Desired tone: formal, friendly, or urgent (optional)
+			|
+			| Generate the email and present it for review.
+
+		actions:
+			create_email: @actions.Generate_Professional_Email
+				with "Input:recipientName"=...
+				with "Input:topic"=...
+				with "Input:tone"=...
+				set @variables.generated_email = @outputs.promptResponse
+
+			back: @utils.transition to @topic.topic_selector
+
+# ★ Insight: Prompt Template Integration Checklist
+#
+# BEFORE PUBLISHING AGENT:
+#   1. Create PromptTemplate metadata file
+#   2. Deploy PromptTemplate: sf project deploy start -m "PromptTemplate:Template_Name"
+#   3. Verify template exists: sf org list metadata -m PromptTemplate
+#
+# INPUT MAPPING:
+#   Agent Script "Input:fieldName" → PromptTemplate {!fieldName}
+#   "Input:email"                  → {!email}
+#   "Input:customerName"           → {!customerName}
+#
+# COMMON ERRORS:
+#   - HTTP 404: PromptTemplate not deployed yet
+#   - "property X not found": Input name doesn't match template variable
+#   - Missing "Input:" prefix: Inputs won't map correctly

package/skills/agentforce-development/assets/patterns/system-instruction-overrides.agent

@@ -0,0 +1,293 @@
+# System Instruction Overrides Pattern
+# Customize agent behavior with dynamic system-level instructions
+#
+# ★ When To Use This Pattern:
+#   - Different behavior for different user segments (VIP, standard, etc.)
+#   - Time-based instruction changes (business hours vs after hours)
+#   - Feature flags that change agent personality
+#   - A/B testing different conversation styles
+#
+# ★ Key Insight:
+#   - System block defines BASE behavior (always applies)
+#   - Topic instructions can OVERRIDE or EXTEND system behavior
+#   - Use conditionals in reasoning to dynamically adjust tone
+#   - Variables can control instruction branches
+#
+# ★ Important Limitation:
+#   - The system: block itself cannot use conditionals or variables
+#   - Dynamic behavior must be implemented in topic reasoning
+#
+# This is a COMPLETE template - customize for your use case
+
+system:
+	# Base instructions - always apply these guardrails
+	instructions: "You are a professional customer service agent. Always be helpful, courteous, and accurate. Never share confidential information. Escalate complex issues to human agents."
+	messages:
+		welcome: "Hello! How can I assist you today?"
+		error: "I apologize, but I encountered an issue. Let me try that again."
+
+config:
+	agent_name: "Dynamic_Service_Agent"
+	default_agent_user: "agent@company.salesforce.com"
+	agent_label: "Dynamic Service Agent"
+	description: "Agent with dynamic instruction overrides based on context"
+
+variables:
+	# Standard linked variables
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+
+	# Variables for dynamic instruction control
+	customer_tier: mutable string = "standard"
+		description: "Customer tier: standard, premium, or vip"
+	business_hours: mutable boolean = True
+		description: "Whether we're in business hours"
+	agent_mode: mutable string = "helpful"
+		description: "Agent personality mode: helpful, concise, formal"
+	feature_flags: mutable string = ""
+		description: "Comma-separated feature flags"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	label: "Topic Selector"
+	description: "Routes to appropriate topic based on user tier"
+
+	# ★ Use before_reasoning to set up context-based variables
+	before_reasoning:
+		# In a real implementation, these would come from a Flow/Apex lookup
+		# Here we show the pattern
+		run @actions.get_customer_tier
+			with contact_id=@variables.ContactId
+			set @variables.customer_tier = @outputs.tier
+		run @actions.check_business_hours
+			set @variables.business_hours = @outputs.is_business_hours
+
+	reasoning:
+		# ★ OVERRIDE PATTERN: Conditional instructions based on variables
+		instructions: ->
+			# VIP customers get personalized treatment
+			if @variables.customer_tier == "vip":
+				| PRIORITY CUSTOMER DETECTED
+				| Provide white-glove service. Use their name when possible.
+				| Offer proactive solutions. Never say "I can't" without an alternative.
+				| You have authority to offer 20% discounts.
+
+			# Premium gets enhanced support
+			if @variables.customer_tier == "premium":
+				| PREMIUM CUSTOMER
+				| Provide thorough, detailed responses.
+				| Offer to connect with a specialist if needed.
+				| You can offer 10% discounts.
+
+			# Standard tier
+			if @variables.customer_tier == "standard":
+				| Provide helpful, efficient service.
+				| Focus on resolving the issue quickly.
+
+			# After-hours override
+			if @variables.business_hours == False:
+				| NOTE: We are currently outside business hours.
+				| Complex issues should be logged for follow-up tomorrow.
+				| You cannot transfer to live agents right now.
+
+			# Mode-based personality adjustments
+			if @variables.agent_mode == "concise":
+				| Keep responses brief and to the point. Use bullet points.
+
+			if @variables.agent_mode == "formal":
+				| Use formal language. Address customer as Sir/Madam.
+
+			| Route the customer to the appropriate topic.
+
+		actions:
+			go_orders: @utils.transition to @topic.orders
+			go_billing: @utils.transition to @topic.billing
+			go_support: @utils.transition to @topic.support
+				available when @variables.business_hours == True
+
+	actions:
+		get_customer_tier:
+			description: "Get customer tier from Salesforce"
+			inputs:
+				contact_id: string
+					description: "Contact ID to look up"
+			outputs:
+				tier: string
+					description: "Customer tier: standard, premium, vip"
+			target: "flow://Get_Customer_Tier"
+
+		check_business_hours:
+			description: "Check if currently in business hours"
+			outputs:
+				is_business_hours: boolean
+					description: "True if in business hours"
+			target: "flow://Check_Business_Hours"
+
+topic orders:
+	label: "Order Management"
+	description: "Handle order inquiries with tier-appropriate service"
+
+	reasoning:
+		instructions: ->
+			# ★ Tier-specific instructions carry through to subtopics
+			if @variables.customer_tier == "vip":
+				| This is a VIP customer. Expedite all order requests.
+				| Offer free shipping upgrades proactively.
+
+			| Help the customer with their order inquiry.
+			| Look up order status, process changes, or handle returns.
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+topic billing:
+	label: "Billing Support"
+	description: "Handle billing with appropriate authority levels"
+
+	reasoning:
+		instructions: ->
+			# ★ Different authority based on tier
+			if @variables.customer_tier == "vip":
+				| You can waive fees up to $100 for VIP customers.
+				| Proactively offer payment plan options.
+
+			if @variables.customer_tier == "premium":
+				| You can waive fees up to $25 for premium customers.
+
+			if @variables.customer_tier == "standard":
+				| Fee waivers require manager approval. Escalate if requested.
+
+			| Help the customer understand their bill and resolve issues.
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+			escalate: @utils.escalate
+				description: "Transfer to billing specialist"
+				available when @variables.customer_tier == "standard"
+
+topic support:
+	label: "Technical Support"
+	description: "Technical support with business hours awareness"
+
+	reasoning:
+		instructions: ->
+			if @variables.business_hours == False:
+				| Technical support is limited outside business hours.
+				| Log the issue for follow-up and provide self-service resources.
+
+			if @variables.business_hours == True:
+				| Full technical support available. Troubleshoot thoroughly.
+
+			| Help resolve the customer's technical issue.
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+# ═══════════════════════════════════════════════════════════════════════════
+# ★ TOPIC-LEVEL SYSTEM OVERRIDES (NEW PATTERN)
+# These topics demonstrate complete persona switching using topic-level
+# system: blocks that OVERRIDE the global system instructions.
+# ═══════════════════════════════════════════════════════════════════════════
+
+topic formal_mode:
+	label: "Formal Communication"
+	description: "Professional business communication mode"
+
+	# ★ TOPIC-LEVEL SYSTEM OVERRIDE
+	# This completely replaces global system instructions for this topic
+	system:
+		instructions: "You are a formal business professional. Use professional language at all times. Address users as Sir or Madam. Avoid contractions, slang, and casual expressions. Focus on efficiency and clarity. Maintain a respectful, corporate tone."
+
+	reasoning:
+		instructions: ->
+			| [Formal Mode Engaged]
+			|
+			| Good day. How may I be of assistance?
+			| I am prepared to address your inquiry with the utmost professionalism.
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+topic creative_mode:
+	label: "Creative Assistant"
+	description: "Creative and imaginative communication mode"
+
+	# ★ TOPIC-LEVEL SYSTEM OVERRIDE
+	# Different persona entirely
+	system:
+		instructions: "You are a creative and imaginative assistant. Be playful, use metaphors and analogies. Think outside the box. Encourage brainstorming and wild ideas. Use emojis sparingly but effectively. Make conversations engaging and fun while still being helpful."
+
+	reasoning:
+		instructions: ->
+			| 🎨 [Creative Mode Activated!]
+			|
+			| Hey there, creative spirit! Ready to explore some ideas together?
+			| Think of me as your brainstorming buddy - no idea is too wild!
+			|
+			| What shall we dream up today?
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+topic technical_expert:
+	label: "Technical Expert"
+	description: "Deep technical expertise mode"
+
+	# ★ TOPIC-LEVEL SYSTEM OVERRIDE
+	# Specialist persona
+	system:
+		instructions: "You are a technical expert with deep knowledge. Use precise technical terminology. Provide detailed explanations with examples. Reference documentation when helpful. Assume the user has technical background. Be thorough but avoid unnecessary verbosity."
+
+	reasoning:
+		instructions: ->
+			| [Technical Expert Mode]
+			|
+			| I'm ready to dive deep into technical details.
+			| Feel free to use technical terminology - I'll match your level.
+			|
+			| What technical challenge are we solving?
+
+		actions:
+			back: @utils.transition to @topic.topic_selector
+
+# ★ Insight: Three Levels of Instruction Control
+#
+# LEVEL 1: GLOBAL SYSTEM BLOCK
+#   - Static text only (no variables, no conditionals)
+#   - Applies to ALL topics as baseline
+#   - Good for: Guardrails, base personality, universal rules
+#   - Example: "Never share confidential information"
+#
+# LEVEL 2: TOPIC-LEVEL SYSTEM BLOCK (NEW!)
+#   - Placed inside topic definition
+#   - COMPLETELY OVERRIDES global system for that topic
+#   - Good for: Persona switching, mode changes, specialist behavior
+#   - Example: topic formal_mode: system: instructions: "Be professional..."
+#
+# LEVEL 3: TOPIC REASONING INSTRUCTIONS
+#   - Dynamic (variables, conditionals, template expressions)
+#   - Extends/adjusts behavior within topic
+#   - Good for: Context-aware responses, personalization
+#   - Example: if @variables.is_vip: | Provide priority service
+#
+# OVERRIDE HIERARCHY:
+#   Topic system: > Global system: > Default behavior
+#
+# COMBINING APPROACHES:
+#   - Use GLOBAL system for universal guardrails
+#   - Use TOPIC system: for complete persona changes
+#   - Use TOPIC reasoning for dynamic conditional behavior
+#
+# Best Practice: Put guardrails in global system, personas in topic system,
+# and context-aware personalization in topic reasoning instructions.

package/skills/agentforce-development/assets/prompt-rag-search.agent

@@ -0,0 +1,131 @@
+# Prompt Template with RAG Search Template
+# =========================================
+#
+# This template demonstrates the pattern for combining Prompt Templates
+# with Data Cloud RAG (Retrieval Augmented Generation) for grounded responses.
+#
+# Pattern: Knowledge search + grounded response generation
+# Use when: FAQ bots, product knowledge agents, documentation assistants
+#
+# CREDIT CONSUMPTION:
+# - Prompt Templates: 2-16 credits per invocation
+# - Retriever actions: 20 credits per search
+# - TIP: Cache retriever results in variables, reuse across topics
+
+system:
+   messages:
+      welcome: "Hello! I can help answer questions about our products and services."
+      error: "I apologize, I couldn't find the information you need."
+   instructions: "You are a helpful knowledge assistant. Always provide grounded answers based on retrieved knowledge."
+
+config:
+   agent_name: "RAGSearchAgent"
+   agent_label: "Knowledge Assistant"
+   description: "Agent demonstrating Prompt Template with Data Cloud RAG pattern"
+   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User
+
+variables:
+   # Search state
+   search_query: mutable string = ""
+      description: "User's current search query"
+   search_results: mutable string = ""
+      description: "Retrieved knowledge chunks (cached for reuse)"
+   has_results: mutable boolean = False
+      description: "Whether search returned results"
+
+   # Response tracking
+   response_generated: mutable boolean = False
+      description: "Whether a response has been generated for current query"
+
+start_agent entry:
+   description: "Entry point - welcome and route to knowledge search"
+   reasoning:
+      instructions: |
+         Welcome the user and offer to help with questions.
+      actions:
+         go_search: @utils.transition to @topic.knowledge_search
+            description: "Start knowledge search"
+
+# ============================================================
+# KNOWLEDGE SEARCH TOPIC (RAG Pattern)
+# ============================================================
+
+topic knowledge_search:
+   description: "Search knowledge base and generate grounded responses"
+   reasoning:
+      instructions: ->
+         # POST-ACTION: Generate response after retrieval
+         if @variables.has_results == True and @variables.response_generated == False:
+            # Use Prompt Template to generate grounded response
+            run @actions.Generate_Grounded_Response
+               with query = @variables.search_query
+               with context = @variables.search_results
+            set @variables.response_generated = True
+
+         # NO RESULTS: Escalate or try different search
+         if @variables.has_results == False and @variables.search_query != "":
+            | I couldn't find information about that topic.
+            | Would you like to try a different search, or speak with a human agent?
+
+         # INITIAL STATE: Ask for question
+         if @variables.search_query == "":
+            | What would you like to know? I can help with:
+            | - Product information
+            | - Pricing and plans
+            | - Technical specifications
+            | - Troubleshooting guides
+
+      actions:
+         # Retriever action for RAG search
+         # This searches Data Cloud knowledge base
+         search_knowledge: @actions.Search_Knowledge_Base
+            description: "Search for relevant information"
+            with query = ...  # LLM extracts user's question
+            include_in_progress_indicator: True
+            progress_indicator_message: "Searching our knowledge base..."
+            set @variables.search_query = @outputs.original_query
+            set @variables.search_results = @outputs.retrieved_chunks
+            set @variables.has_results = @outputs.has_results
+            set @variables.response_generated = False  # Reset for new search
+
+         # Prompt Template for grounded response
+         # Configure in Agentforce Assets with:
+         # - Template instructions referencing retrieved context
+         # - Set output is_displayable: True (response shown to user)
+         generate_answer: @actions.Generate_Grounded_Response
+            description: "Generate answer from retrieved knowledge"
+            available when @variables.has_results == True
+            with query = @variables.search_query
+            with context = @variables.search_results
+
+         # New search
+         new_search: @utils.setVariables
+            description: "Search for something else"
+            with search_query = ""
+            with search_results = ""
+            with has_results = False
+            with response_generated = False
+
+         escalate_now: @utils.escalate
+            description: "Transfer to human agent"
+
+# ============================================================
+# FOLLOW-UP QUESTIONS TOPIC
+# ============================================================
+
+topic follow_up:
+   description: "Handle follow-up questions using cached context"
+   reasoning:
+      instructions: ->
+         # COST OPTIMIZATION: Reuse cached search_results instead of re-searching
+         if @variables.search_results != "":
+            | Based on what we discussed:
+            run @actions.Generate_Grounded_Response
+               with query = ...  # Follow-up question extracted by LLM
+               with context = @variables.search_results  # Reuse cached results!
+         else:
+            transition to @topic.knowledge_search
+
+      actions:
+         back_to_search: @utils.transition to @topic.knowledge_search
+            description: "Start a new search"