Agentforce Development

# Hello World Agent
# The minimal viable Agentforce agent - start here!
#
# This template shows the absolute minimum structure required for a working agent.
# Use this as your starting point when learning Agent Script.
#
# ★ Why This Structure?
#   - system: Sets agent personality and default messages
#   - config: Required metadata for deployment (agent_name must be unique)
#   - variables: Linked variables connect to Messaging context (required for deployment)
#   - language: Locale settings (required for deployment)
#   - start_agent: Entry point topic (exactly one required)
#
# ★ Key Validation Points (from 100-point scoring):
#   - [10 pts] config block with all 4 required fields
#   - [10 pts] 3 linked variables (EndUserId, RoutableId, ContactId)
#   - [5 pts] language block present
#   - [10 pts] At least one start_agent topic
#
# Deploy with: sf agent publish authoring-bundle --api-name Hello_World_Agent --target-org [alias]

system:
	instructions: "You are a friendly assistant. Greet users warmly and help them."
	messages:
		welcome: "Hello! I'm here to help. What can I do for you today?"
		error: "I'm sorry, something went wrong. Please try again."

config:
	agent_name: "Hello_World_Agent"
	default_agent_user: "your.user@company.com"
	agent_label: "Hello World Agent"
	description: "A minimal example agent to learn Agent Script basics"

variables:
	# Linked variables (required) - Connect to Salesforce Messaging context
	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"

language:
	default_locale: "en_US"
	additional_locales: ""
	all_additional_locales: False

# Entry point topic - this is where every conversation starts
start_agent main:
	label: "Main"
	description: "Greets users and provides help"

	reasoning:
		instructions: ->
			| Welcome the user warmly.
			| Ask how you can help them today.
			| Be friendly and conversational.

# Multi-Topic Agent Template
# An agent with multiple conversation topics (hub-and-spoke pattern)
# Users are routed to specialized topics based on their needs
#
# Usage: Replace {{placeholders}} with your values
# Required: agent_name, default_agent_user, agent_label, description
# Required: At least 2 topics with label and description

system:
	instructions: "{{SystemInstructions}}"
	messages:
		welcome: "{{WelcomeMessage}}"
		error: "I'm sorry, I encountered an issue. Please try again."

config:
	agent_name: "{{AgentApiName}}"
	default_agent_user: "{{AgentUser}}"
	agent_label: "{{AgentLabel}}"
	description: "{{AgentDescription}}"

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"
	user_intent: mutable string
		description: "What the user is trying to accomplish"

language:
	default_locale: "en_US"
	additional_locales: ""
	all_additional_locales: False

start_agent topic_selector:
	label: "Topic Selector"
	description: "Routes users to the appropriate topic based on their needs"

	reasoning:
		instructions: ->
			| Determine what the user needs help with.
			| Route them to the most appropriate topic.
			| If unclear, ask clarifying questions.
		actions:
			go_to_topic_one: @utils.transition to @topic.{{topic_one_name}}
			go_to_topic_two: @utils.transition to @topic.{{topic_two_name}}
			go_to_topic_three: @utils.transition to @topic.{{topic_three_name}}
			go_to_farewell: @utils.transition to @topic.farewell
			go_to_escalation: @utils.transition to @topic.escalation

topic {{topic_one_name}}:
	label: "{{TopicOneLabel}}"
	description: "{{TopicOneDescription}}"

	reasoning:
		instructions: ->
			| {{TopicOneInstructions}}
		actions:
			back_to_menu: @utils.transition to @topic.topic_selector

topic {{topic_two_name}}:
	label: "{{TopicTwoLabel}}"
	description: "{{TopicTwoDescription}}"

	reasoning:
		instructions: ->
			| {{TopicTwoInstructions}}
		actions:
			back_to_menu: @utils.transition to @topic.topic_selector

topic {{topic_three_name}}:
	label: "{{TopicThreeLabel}}"
	description: "{{TopicThreeDescription}}"

	reasoning:
		instructions: ->
			| {{TopicThreeInstructions}}
		actions:
			back_to_menu: @utils.transition to @topic.topic_selector

topic farewell:
	label: "Farewell"
	description: "Ends the conversation gracefully"

	reasoning:
		instructions: ->
			| Thank the user for reaching out.
			| Wish them a great day.
			| Let them know they can return anytime.

topic escalation:
	label: "Escalation"
	description: "Handles requests to transfer to a live human agent"

	reasoning:
		instructions: ->
			| If the user explicitly asks to speak with a human, escalate.
			| Acknowledge the request and transfer gracefully.
		actions:
			escalate_to_human: @utils.escalate
				description: "Escalate to a human agent"

# Simple FAQ Agent
# A minimal working example of an Agentforce agent
# Uses pure LLM reasoning without external actions
#
# Deploy with: sf agent publish authoring-bundle --api-name Simple_FAQ_Agent --target-org [alias]

system:
	instructions: "You are a helpful FAQ assistant for our company. Answer questions accurately and concisely. If you don't know the answer, say so honestly. Never share sensitive or confidential information. Keep responses friendly and professional."
	messages:
		welcome: "Hello! I'm your FAQ assistant. How can I help you today?"
		error: "I'm sorry, I encountered an issue. Please try again."

config:
	agent_name: "Simple_FAQ_Agent"
	default_agent_user: "agent.user@company.com"
	agent_label: "Simple FAQ Agent"
	description: "A minimal FAQ agent that answers common questions using AI"

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"
	user_question: mutable string
		description: "The user's current question"
	conversation_topic: mutable string
		description: "The current topic being discussed"
	question_count: mutable number
		description: "Number of questions answered in this session"

language:
	default_locale: "en_US"
	additional_locales: ""
	all_additional_locales: False

start_agent topic_selector:
	label: "Topic Selector"
	description: "Routes incoming questions to the FAQ handler"

	reasoning:
		instructions: ->
			| Listen to the user's question and determine how to help.
			| If the question is about a specific topic, note it.
			| Route to the FAQ handler for processing.
		actions:
			handle_faq: @utils.transition to @topic.faq_handler
			end_conversation: @utils.transition to @topic.farewell

topic faq_handler:
	label: "FAQ Handler"
	description: "Handles frequently asked questions and provides helpful answers"

	reasoning:
		instructions: ->
			| Answer the user's question based on your knowledge.
			| Be helpful, accurate, and concise.
			| Keep responses under 3-4 sentences when possible.
			| If you need more information, ask clarifying questions.
			|
			| Common topics you can help with:
			| - Business hours and location
			| - Return and refund policies
			| - Shipping information
			| - Product questions
			| - Account and billing
			|
			| If the question is outside your knowledge:
			| - Acknowledge you don't have that information
			| - Suggest contacting customer support
			| - Offer to help with something else
		actions:
			new_question: @utils.transition to @topic.topic_selector
			end_conversation: @utils.transition to @topic.farewell
			escalate: @utils.transition to @topic.escalation

topic farewell:
	label: "Farewell"
	description: "Ends the conversation politely"

	reasoning:
		instructions: ->
			| Thank the user for their questions.
			| Wish them a great day.
			| Let them know they can return anytime for more help.

topic escalation:
	label: "Escalation"
	description: "Handles requests to speak with a human agent"

	reasoning:
		instructions: ->
			| If the user wants to speak with a human, escalate gracefully.
			| Acknowledge their request and transfer the conversation.
		actions:
			escalate_to_human: @utils.escalate
				description: "Transfer to a human agent"

<?xml version="1.0" encoding="UTF-8"?>
<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <bundleType>AGENT</bundleType>
</AiAuthoringBundle>

# Simple Q&A Agent Template
# A minimal agent that handles basic questions using LLM reasoning only
# No external actions - just conversational AI
#
# Usage: Replace {{placeholders}} with your values
# Required: agent_name, default_agent_user, agent_label, description

system:
	instructions: "{{SystemInstructions}}"
	messages:
		welcome: "{{WelcomeMessage}}"
		error: "I'm sorry, I encountered an issue. Please try again."

config:
	agent_name: "{{AgentApiName}}"
	default_agent_user: "{{AgentUser}}"
	agent_label: "{{AgentLabel}}"
	description: "{{AgentDescription}}"

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"
	user_query: mutable string
		description: "The user's current question or request"

language:
	default_locale: "en_US"
	additional_locales: ""
	all_additional_locales: False

start_agent topic_selector:
	label: "Topic Selector"
	description: "Routes incoming requests to the Q&A handler"

	reasoning:
		instructions: ->
			| Listen to the user's question.
			| Route to the Q&A handler for processing.
		actions:
			handle_question: @utils.transition to @topic.qa_handler
			end_conversation: @utils.transition to @topic.farewell

topic qa_handler:
	label: "Q&A Handler"
	description: "Handles questions and provides answers"

	reasoning:
		instructions: ->
			| Answer the user's question based on your knowledge.
			| Be helpful, accurate, and concise.
			| Keep responses clear and easy to understand.
			| If you need more information, ask clarifying questions.
		actions:
			new_question: @utils.transition to @topic.topic_selector
			end_conversation: @utils.transition to @topic.farewell

topic farewell:
	label: "Farewell"
	description: "Ends the conversation gracefully"

	reasoning:
		instructions: ->
			| Thank the user for their questions.
			| Wish them a great day.
			| Let them know they can return anytime for more help.

/**
 * @description Queueable job for AI generation using Agentforce Models API
 *              Generates {{Description}} for {{ObjectName}} records
 * @author {{Author}}
 * @date {{Date}}
 *
 * @requires API v61.0+ (Spring '24)
 * @requires Einstein Generative AI enabled
 * @requires Einstein Generative AI User permission set
 *
 * @example
 * // Invoke from trigger or other context:
 * List<Id> recordIds = new List<Id>{ '001xx000003DGXXX' };
 * System.enqueueJob(new {{ClassName}}_AI_Queueable(recordIds));
 */
public with sharing class {{ClassName}}_AI_Queueable implements Queueable, Database.AllowsCallouts {

    // ═══════════════════════════════════════════════════════════════════════
    // CONFIGURATION
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * Available Models:
     * - sfdc_ai__DefaultOpenAIGPT4OmniMini  (Cost-effective, faster)
     * - sfdc_ai__DefaultOpenAIGPT4Omni      (More capable, slower)
     * - sfdc_ai__DefaultAnthropic           (Claude - nuanced)
     * - sfdc_ai__DefaultGoogleGemini        (Multimodal capable)
     */
    private static final String AI_MODEL = 'sfdc_ai__DefaultOpenAIGPT4OmniMini';

    /**
     * Maximum records to process in a single job.
     * Recommended: 10-20 for AI processing to avoid timeouts.
     */
    private static final Integer MAX_RECORDS_PER_JOB = 20;

    // ═══════════════════════════════════════════════════════════════════════
    // INSTANCE VARIABLES
    // ═══════════════════════════════════════════════════════════════════════

    private List<Id> recordIds;

    // ═══════════════════════════════════════════════════════════════════════
    // CONSTRUCTOR
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Constructor
     * @param recordIds List of {{ObjectName}} record IDs to process
     */
    public {{ClassName}}_AI_Queueable(List<Id> recordIds) {
        this.recordIds = recordIds;
    }

    // ═══════════════════════════════════════════════════════════════════════
    // QUEUEABLE EXECUTION
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Execute the queueable job
     * @param context QueueableContext
     */
    public void execute(QueueableContext context) {
        if (recordIds == null || recordIds.isEmpty()) {
            return;
        }

        // Split into current batch and remaining
        List<Id> currentBatch = new List<Id>();
        List<Id> remainingIds = new List<Id>();

        for (Integer i = 0; i < recordIds.size(); i++) {
            if (i < MAX_RECORDS_PER_JOB) {
                currentBatch.add(recordIds[i]);
            } else {
                remainingIds.add(recordIds[i]);
            }
        }

        // Process current batch
        processRecords(currentBatch);

        // Chain next job if more records remain
        if (!remainingIds.isEmpty() && !Test.isRunningTest()) {
            System.enqueueJob(new {{ClassName}}_AI_Queueable(remainingIds));
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    // PROCESSING LOGIC
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Process a batch of records
     * @param batchIds Record IDs to process in this batch
     */
    private void processRecords(List<Id> batchIds) {
        // Query records with fields needed for AI prompt
        List<{{ObjectName}}> records = [
            SELECT Id, Name
                   // TODO: Add fields needed for AI context
                   // , Description, Subject, Type
            FROM {{ObjectName}}
            WHERE Id IN :batchIds
            WITH USER_MODE
        ];

        List<{{ObjectName}}> toUpdate = new List<{{ObjectName}}>();

        for ({{ObjectName}} record : records) {
            try {
                // Generate AI content
                String aiContent = generateAIContent(record);

                if (String.isNotBlank(aiContent)) {
                    // TODO: Update the target field with AI-generated content
                    // record.AI_Summary__c = aiContent;
                    toUpdate.add(record);
                }
            } catch (Exception e) {
                // Log error but continue processing other records
                logError(record.Id, e);
            }
        }

        // Batch update
        if (!toUpdate.isEmpty()) {
            try {
                update toUpdate;
            } catch (DmlException e) {
                System.debug(LoggingLevel.ERROR, 'DML Error: ' + e.getMessage());
            }
        }
    }

    // ═══════════════════════════════════════════════════════════════════════
    // AI GENERATION
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Generate AI content for a single record
     * @param record The record to generate content for
     * @return Generated text content
     */
    private String generateAIContent({{ObjectName}} record) {
        // Build the prompt with record context
        String prompt = buildPrompt(record);

        // Create Models API request
        aiplatform.ModelsAPI.createGenerations_Request request =
            new aiplatform.ModelsAPI.createGenerations_Request();
        request.modelName = AI_MODEL;

        aiplatform.ModelsAPI_GenerationRequest genRequest =
            new aiplatform.ModelsAPI_GenerationRequest();
        genRequest.prompt = prompt;
        request.body = genRequest;

        // Call the API
        aiplatform.ModelsAPI.createGenerations_Response response =
            aiplatform.ModelsAPI.createGenerations(request);

        // Extract and return generated text
        if (response.Code200 != null &&
            response.Code200.generations != null &&
            !response.Code200.generations.isEmpty()) {
            return response.Code200.generations[0].text;
        }

        return null;
    }

    /**
     * @description Build the AI prompt for a record
     * @param record The record to build prompt for
     * @return Formatted prompt string
     */
    private String buildPrompt({{ObjectName}} record) {
        // TODO: Customize this prompt for your use case
        String prompt =
            '{{PromptInstructions}}\n\n' +
            'Record Information:\n' +
            '- Name: ' + record.Name + '\n';
            // TODO: Add more fields as needed
            // '- Description: ' + record.Description + '\n' +
            // '- Type: ' + record.Type + '\n';

        return prompt;
    }

    // ═══════════════════════════════════════════════════════════════════════
    // ERROR HANDLING
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Log processing errors
     * @param recordId The record that failed
     * @param e The exception that occurred
     */
    private void logError(Id recordId, Exception e) {
        System.debug(LoggingLevel.ERROR,
            '{{ClassName}}_AI_Queueable Error for ' + recordId + ': ' + e.getMessage());
        System.debug(LoggingLevel.ERROR, 'Stack Trace: ' + e.getStackTraceString());

        // TODO: Implement custom error logging
        // Options:
        // 1. Create Error_Log__c record
        // 2. Publish Platform Event for monitoring
        // 3. Send email notification
    }

    // ═══════════════════════════════════════════════════════════════════════
    // TEST SUPPORT
    // ═══════════════════════════════════════════════════════════════════════

    /**
     * @description Test-visible method to verify prompt generation
     * @param record Test record
     * @return Generated prompt
     */
    @TestVisible
    private String testBuildPrompt({{ObjectName}} record) {
        return buildPrompt(record);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<!--
  AUTHORING BUNDLE METADATA FILE
  ==============================

  CRITICAL NAMING CONVENTION:
  - File MUST be named: AgentName.bundle-meta.xml
  - NOT: AgentName.aiAuthoringBundle-meta.xml

  DIRECTORY STRUCTURE:
  force-app/main/default/aiAuthoringBundles/
  └── MyAgent/
      ├── MyAgent.agent              <- Agent Script file
      └── MyAgent.bundle-meta.xml    <- This file (rename to match agent)

  DEPLOYMENT COMMAND:
  sf agent publish authoring-bundle --api-name MyAgent --target-org TARGET_ORG

  DO NOT USE: sf project deploy start (will fail with "Required fields are missing: [BundleType]")
-->
<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <bundleType>AGENT</bundleType>
</AiAuthoringBundle>

# Apex-Based Action Template
# Define an action that calls a Salesforce Apex @InvocableMethod
# This is a PARTIAL template - define actions inside a topic block
#
# Usage: Replace {{placeholders}} with your values
# Place this inside a topic's actions: block
#
# ⚠️ The target format is apex://ClassName (NOT ClassName.MethodName)
#    The runtime auto-discovers the @InvocableMethod on the class.
# ⚠️ NO GenAiFunction metadata needed for AiAuthoringBundle (Agent Script).

# Action Definition (place inside topic's actions: block)
{{action_name}}:
	description: "{{ActionDescription}}"
	inputs:
		{{input_1_name}}: {{input_1_type}}
			description: "{{Input1Description}}"
		{{input_2_name}}: {{input_2_type}}
			description: "{{Input2Description}}"
	outputs:
		{{output_1_name}}: {{output_1_type}}
			description: "{{Output1Description}}"
		success: boolean
			description: "Whether the operation succeeded"
		error_message: string
			description: "Error message if operation failed"
	target: "apex://{{ApexClassName}}"

# Usage in reasoning block:
#
# reasoning:
#    instructions: ->
#       | Help the user with their request.
#    actions:
#       invoke_{{action_name}}: @actions.{{action_name}}
#          with {{input_1_name}}=...  # LLM fills from conversation
#          with {{input_2_name}}=@variables.some_var  # From variable
#          set @variables.result = @outputs.{{output_1_name}}
#          set @variables.success = @outputs.success

# Common Apex Target Patterns:
# - apex://AccountService
# - apex://CaseService
# - apex://OrderService
# - apex://IntegrationService
# - apex://CalculationService

# Apex Class Requirements:
# - Must be global or public with sharing
# - Must have exactly ONE @InvocableMethod annotation
# - Use @InvocableVariable annotations on input/output wrapper class fields
# - No GenAiFunction metadata needed for AiAuthoringBundle (Agent Script)

# Error Handling Topic Template
# A topic with validation and guard clauses for critical operations
# This is a PARTIAL template - use within a complete agent file
#
# Usage: Replace {{placeholders}} with your values
# Note: Includes validation patterns and error handling

topic {{topic_name}}:
	label: "{{TopicLabel}}"
	description: "{{TopicDescription}} - includes validation and error handling"

	actions:
		{{action_name}}:
			description: "{{ActionDescription}}"
			inputs:
				{{input_name}}: {{input_type}}
					description: "{{InputDescription}}"
			outputs:
				success: boolean
					description: "Whether the operation succeeded"
				error_message: string
					description: "Error message if operation failed"
				{{output_name}}: {{output_type}}
					description: "{{OutputDescription}}"
			target: "{{ActionTarget}}"

	reasoning:
		instructions: ->
			# Validation guard clauses
			if @variables.{{required_field}} is None:
				set @variables.validation_passed = False
				| I need {{RequiredFieldDescription}} before I can proceed.
				| Please provide this information.

			if @variables.{{amount_field}} > {{MaxAmount}}:
				set @variables.validation_passed = False
				| The {{AmountFieldDescription}} exceeds the maximum of {{MaxAmount}}.
				| Would you like to:
				| - Use the maximum allowed amount
				| - Split into multiple operations
				| - Contact support for a higher limit

			if @variables.validation_passed == True:
				| All validations passed. Proceeding with the operation.

		actions:
			# Only available when validation passes
			execute_action: @actions.{{action_name}}
				with {{input_name}}=@variables.{{input_variable}}
				set @variables.operation_success = @outputs.success
				set @variables.result = @outputs.{{output_name}}
				available when @variables.validation_passed == True

			# Handle errors
			retry_operation: @utils.transition to @topic.{{topic_name}}
				available when @variables.operation_success == False

			back_to_menu: @utils.transition to @topic.topic_selector

# Escalation Setup Pattern
# Complete agent template with connection block for human escalation
#
# ★ When To Use This Pattern:
#   - Agent needs to transfer conversations to human agents
#   - Using Omni-Channel for routing
#   - Enhanced Chat or other messaging channels
#
# ★ Key Components:
#   1. connection messaging: block - defines routing destination
#   2. @utils.escalate action - triggers the transfer
#   3. escalation topic - handles the handoff flow
#
# ★ Prerequisites:
#   - Omni-Channel configured in Salesforce
#   - Queue/Skill created for routing
#   - Messaging channel active (Enhanced Chat, etc.)
#
# This is a COMPLETE template - customize for your use case

system:
	instructions: "You are a helpful customer service agent. Be professional, friendly, and helpful. If you cannot resolve an issue or the customer requests a human, transfer them to a live agent."
	messages:
		welcome: "Hello! I'm here to help you today. What can I assist you with?"
		error: "I apologize, but I encountered an issue. Let me connect you with a human agent."

config:
	agent_name: "{{AGENT_NAME}}"
	default_agent_user: "{{AGENT_USER_EMAIL}}"
	agent_label: "{{AGENT_LABEL}}"
	description: "Customer service agent with human escalation capability"

variables:
	# Required linked variables for messaging context
	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"

	# Escalation tracking variables
	escalation_requested: mutable boolean = False
		description: "Whether customer requested human agent"
	escalation_reason: mutable string
		description: "Reason for escalation"
	# ⚠️ Use 'number' not 'integer' - integer type is NOT supported in AiAuthoringBundle
	attempts_before_escalation: mutable number = 0
		description: "Number of attempts before escalating"

language:
	default_locale: "en_US"
	additional_locales: ""
	all_additional_locales: False

# ★ CONNECTION BLOCK - Required for @utils.escalate to work
# This defines where escalated conversations are routed
# Use singular 'connection' for one channel, plural 'connections' for multiple
connection messaging:
	# ⚠️ IMPORTANT: Only "OmniChannelFlow" is supported (not "queue", "skill", or "agent")
	outbound_route_type: "OmniChannelFlow"
	# API name of your Omni-Channel Flow
	outbound_route_name: "{{OMNI_CHANNEL_FLOW_NAME}}"
	# ⚠️ REQUIRED: escalation_message must be included when connection block is present
	escalation_message: "Transferring you to a human agent now..."
	# Optional: Allow agent to adapt responses during escalation
	adaptive_response_allowed: True

# ★ MULTI-CHANNEL EXAMPLE (use 'connections' plural for multiple channels)
# connections:
#    messaging:
#       outbound_route_type: "OmniChannelFlow"
#       outbound_route_name: "Chat_Support_Flow"
#       escalation_message: "Connecting you to chat support..."
#       adaptive_response_allowed: True
#    telephony:
#       outbound_route_type: "OmniChannelFlow"
#       outbound_route_name: "Phone_Support_Flow"
#       escalation_message: "Transferring to phone support..."
#       adaptive_response_allowed: False

# Entry point
start_agent topic_selector:
	label: "Topic Selector"
	description: "Routes users to appropriate topics based on intent"

	reasoning:
		instructions: ->
			| Greet the customer and determine their needs.
			| If they ask for a human or live agent, route to escalation.
			| Otherwise, try to help them directly.
		actions:
			go_help: @utils.transition to @topic.help
			go_escalation: @utils.transition to @topic.escalation
				available when @variables.escalation_requested == True

topic help:
	label: "Help"
	description: "Provides assistance to customers"

	reasoning:
		instructions: ->
			| Help the customer with their question.
			| If you cannot resolve their issue after 2-3 attempts, offer to connect them with a human.
			| If they explicitly ask for a human agent at any time, transfer immediately.
			|
			| Phrases that indicate escalation request:
			| - "talk to a human"
			| - "speak to someone"
			| - "real person"
			| - "live agent"
			| - "customer service representative"
			|
			| Track escalation reason if provided:
			set @variables.escalation_reason = ...
		actions:
			offer_escalation: @utils.transition to @topic.escalation

			immediate_escalation: @utils.transition to @topic.escalation

topic escalation:
	label: "Escalation"
	description: "Transfers conversation to human agent"

	reasoning:
		instructions: ->
			| The customer is being transferred to a human agent.
			| Acknowledge their request and apologize for any inconvenience.
			| Let them know a human will be with them shortly.
			|
			| Say something like:
			| "I understand you'd like to speak with a human agent. I'm connecting you now.
			| A customer service representative will be with you shortly. Thank you for your patience."
		actions:
			# ★ ESCALATION ACTION
			# This transfers the conversation to the queue defined in connection block
			transfer_to_human: @utils.escalate
				description: "Transfer to human agent when customer requests or issue cannot be resolved"

# ★ NOTE: Skill-Based and Queue-Based Routing
# ⚠️ As of Dec 2025, only "OmniChannelFlow" is supported for outbound_route_type
# "queue", "skill", and "agent" cause validation errors
# You must create an Omni-Channel Flow that routes to your desired queue/skill

# ★ Alternative: GenAiPlannerBundle Escalation with Reason
# If using GenAiPlannerBundle (not visible in Studio), you can use:
#
# actions:
#    escalate_with_reason: @utils.escalate with reason="Customer requested human assistance"
#
# NOTE: The "with reason" syntax only works in GenAiPlannerBundle!
# AiAuthoringBundle will fail with SyntaxError if you use it.

# ★ Troubleshooting Escalation:
#
# Issue: "escalate" action not recognized
# Fix: Add the connection messaging: block
#
# Issue: Transfer fails silently
# Fix: Verify Omni-Channel queue exists and has available agents
#
# Issue: SyntaxError: Unexpected 'with'
# Fix: You're using AiAuthoringBundle - remove "with reason" syntax
#
# Issue: Agent user lacks permissions
# Fix: Grant Omni-Channel permissions to the default_agent_user

# Flow-Based Action Template
# Define an action that calls a Salesforce Flow
# This is a PARTIAL template - define actions inside a topic block
#
# ⚠️ NOTE ON DEPLOYMENT METHODS:
#    - AiAuthoringBundle: `with`/`set` clauses ARE supported (TDD validated v1.7.0+)
#    - GenAiPlannerBundle: Full syntax including `with`/`set` also supported
#
# Both deployment methods support the Two-Level Action System:
#   Level 1: Action definition in topic `actions:` block (with target/inputs/outputs)
#   Level 2: Action invocation in `reasoning.actions:` block (with `with`/`set` clauses)
#
# Usage: Replace {{placeholders}} with your values
# Place this inside a topic's actions: block

# Action Definition (place inside topic's actions: block)
{{action_name}}:
	description: "{{ActionDescription}}"
	inputs:
		{{input_1_name}}: {{input_1_type}}
			description: "{{Input1Description}}"
		{{input_2_name}}: {{input_2_type}}
			description: "{{Input2Description}}"
	outputs:
		{{output_1_name}}: {{output_1_type}}
			description: "{{Output1Description}}"
		{{output_2_name}}: {{output_2_type}}
			description: "{{Output2Description}}"
	target: "flow://{{FlowApiName}}"

# Usage in reasoning block:
#
# ═══════════════════════════════════════════════════════════════════════════════
# ✅ Recommended Pattern — Level 2 invocation with `with`/`set` (works in both
#    AiAuthoringBundle and GenAiPlannerBundle, TDD validated v1.7.0+)
# ═══════════════════════════════════════════════════════════════════════════════
#
# reasoning:
#    instructions: ->
#       | Help the user with their request.
#    actions:
#       invoke_{{action_name}}: @actions.{{action_name}}
#          with {{input_1_name}}=...  # LLM fills from conversation
#          with {{input_2_name}}=@variables.some_var  # From variable
#          set @variables.result1 = @outputs.{{output_1_name}}
#          set @variables.result2 = @outputs.{{output_2_name}}
#
# ═══════════════════════════════════════════════════════════════════════════════
# Alternative: LLM auto-invoke based on action description (no explicit binding)
# ═══════════════════════════════════════════════════════════════════════════════
#
# reasoning:
#    instructions: ->
#       | Help the user with their request.
#       | Use the available actions when needed.
#    actions:
#       back_to_menu: @utils.transition to @topic.topic_selector

# Common Flow Target Patterns:
# - flow://Get_Account_Details
# - flow://Create_Case
# - flow://Update_Opportunity
# - flow://Send_Email_Notification
# - flow://Calculate_Discount

# Input/Output Types: string, number, boolean, list[string], object

# N-ary Boolean Conditions Template
# Demonstrates using 3+ conditions with and/or operators
#
# This is a PARTIAL template - integrate into a complete agent file
#
# ★ KEY CONCEPTS:
#
#   N-ary AND: All conditions must be true
#   N-ary OR:  At least one condition must be true
#   Grouping:  Use () for complex expressions
#
# ★ Supported Contexts:
#   - if statements in before_reasoning/after_reasoning
#   - available when clauses on actions
#
# ★ Common Mistake:
#   DO NOT nest if statements. Use N-ary and/or instead.
#   ❌ if a: if b: if c: (nested - INVALID)
#   ✅ if a and b and c:   (flat - CORRECT)

# ═══════════════════════════════════════════════════════════════
# PATTERN 1: Three+ AND conditions in lifecycle
# ═══════════════════════════════════════════════════════════════

# Example: Require multiple authentication checks
topic secure_action:
	label: "Secure Action"
	description: "Performs security-sensitive operations"

	before_reasoning:
		# All three conditions must be true
		if @variables.is_authenticated and @variables.has_permission and @variables.session_valid:
			transition to @topic.authorized_action
		# Otherwise stay in this topic

	reasoning:
		instructions: ->
			| User needs to authenticate before proceeding.

# ═══════════════════════════════════════════════════════════════
# PATTERN 2: Three+ OR conditions in lifecycle
# ═══════════════════════════════════════════════════════════════

# Example: Any elevated role gets access
topic admin_panel:
	label: "Admin Panel"
	description: "Administrative features"

	before_reasoning:
		# Any one of these roles grants access
		if @variables.is_admin or @variables.is_moderator or @variables.is_superuser:
			transition to @topic.admin_features
		# Non-admins redirected
		transition to @topic.access_denied

# ═══════════════════════════════════════════════════════════════
# PATTERN 3: N-ary conditions in available when
# ═══════════════════════════════════════════════════════════════

topic order_management:
	label: "Order Management"
	description: "Handles order operations"

	reasoning:
		instructions: ->
			| Help the customer with their order.
		actions:
			# Action available only when ALL conditions met
			process_return: @actions.handle_return
				description: "Process a return request"
				available when @variables.order_exists == True and @variables.within_return_window == True and @variables.item_eligible == True

			# Action available when ANY premium tier matches
			use_priority: @actions.priority_service
				description: "Use priority service queue"
				available when @variables.tier == "gold" or @variables.tier == "platinum" or @variables.tier == "enterprise"

			# Mixed: specific product AND any valid status
			expedite: @actions.expedite_order
				description: "Expedite the current order"
				available when @variables.product_type == "perishable" and (@variables.status == "pending" or @variables.status == "processing")

# ═══════════════════════════════════════════════════════════════
# PATTERN 4: Complex grouped conditions
# ═══════════════════════════════════════════════════════════════

topic smart_routing:
	label: "Smart Routing"
	description: "Routes based on complex criteria"

	before_reasoning:
		# Premium with any product type OR standard with warranty
		if (@variables.tier == "premium" and @variables.product_type != None) or (@variables.tier == "standard" and @variables.has_warranty == True):
			transition to @topic.priority_support

# ═══════════════════════════════════════════════════════════════
# ANTI-PATTERNS - DO NOT USE
# ═══════════════════════════════════════════════════════════════

# ❌ WRONG - Nested if statements (causes "Missing required element" error)
# before_reasoning:
#    if @variables.a == True:
#       if @variables.b == True:
#          if @variables.c == True:
#             transition to @topic.x

# ✅ CORRECT - Flat N-ary condition
# before_reasoning:
#    if @variables.a == True and @variables.b == True and @variables.c == True:
#       transition to @topic.x

# Topic with Actions Template
# A topic that integrates with external systems via Flow or Apex actions
# This is a PARTIAL template - use within a complete agent file
#
# Two-Level Action System:
#   Level 1: topic.actions block DEFINES actions (with target:, inputs:, outputs:)
#   Level 2: reasoning.actions block INVOKES them (with @actions.name, with/set)
#
# Usage: Replace {{placeholders}} with your values
# Note: Actions defined inside topic are local to that topic

topic {{topic_name}}:
	description: "{{TopicDescription}}"

	# Level 1: DEFINE actions available to this topic
	actions:
		{{action_name}}:
			description: "{{ActionDescription}}"
			inputs:
				{{input_name}}: {{input_type}}
					description: "{{InputDescription}}"
			outputs:
				{{output_name}}: {{output_type}}
					description: "{{OutputDescription}}"
			target: "{{ActionTarget}}"  # flow://FlowName or apex://ClassName

	reasoning:
		instructions: ->
			| {{TopicInstructions}}
			| Use the available actions to help the user.
			| Capture and communicate results clearly.

		# Level 2: INVOKE the actions defined above
		actions:
			invoke_action: @actions.{{action_name}}
				with {{input_name}}=...
				set @variables.{{result_variable}} = @outputs.{{output_name}}

			back_to_menu: @utils.transition to @topic.topic_selector
				description: "Return to main menu"

# Deterministic Routing Template (Zero-Hallucination Pattern)
# ============================================================
#
# This template demonstrates the zero-hallucination intent classification
# pattern using action output flags to control LLM behavior.
#
# Pattern: Classify intent deterministically, route without hallucination
# Use when: Critical routing decisions that must not be influenced by LLM creativity
#
# KEY PATTERN:
# In Agentforce Assets, set action outputs with:
# - is_displayable: False  (LLM cannot show this to user)
# - is_used_by_planner: True  (LLM can use for routing)
#
# This ensures the LLM routes based on classification but cannot
# generate hallucinated responses based on the classification data.

system:
   messages:
      welcome: "Hello! How can I help you today?"
      error: "I apologize, something went wrong. Let me try again."
   instructions: "You are a customer service agent. Route users to the correct department based on their intent."

config:
   agent_name: "DeterministicRoutingAgent"
   agent_label: "Smart Router Agent"
   description: "Agent demonstrating zero-hallucination intent routing pattern"
   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User

variables:
   # Intent classification (populated by action with is_displayable: False)
   classified_intent: mutable string = ""
      description: "Classification result - hidden from user responses"
   confidence_score: mutable number = 0
      description: "Classification confidence (0-100)"

   # Routing state
   needs_classification: mutable boolean = True
      description: "Whether user intent needs classification"
   low_confidence_warning: mutable boolean = False
      description: "Flag for low confidence routing"

start_agent topic_selector:
   description: "Classify intent and route deterministically"
   reasoning:
      instructions: ->
         # ====================================================
         # DETERMINISTIC ROUTING (based on classified_intent)
         # ====================================================

         # Route ONLY when classification is complete
         if @variables.needs_classification == False:

            # HIGH-CONFIDENCE ROUTING
            if @variables.confidence_score >= 80:
               if @variables.classified_intent == "billing":
                  transition to @topic.billing
               if @variables.classified_intent == "technical_support":
                  transition to @topic.technical_support
               if @variables.classified_intent == "sales":
                  transition to @topic.sales
               if @variables.classified_intent == "returns":
                  transition to @topic.returns

            # LOW-CONFIDENCE: Confirm with user
            if @variables.confidence_score < 80:
               set @variables.low_confidence_warning = True
               | I want to make sure I route you correctly.
               | It sounds like you need help with **{!@variables.classified_intent}**.
               | Is that correct?

         # INITIAL STATE: Ask for help topic
         if @variables.needs_classification == True:
            | I can help with billing, technical support, sales, or returns.
            | What do you need help with today?

      actions:
         # CRITICAL: This action's outputs must be configured in Agentforce Assets:
         # - classified_intent: is_displayable=False, is_used_by_planner=True
         # - confidence_score: is_displayable=False, is_used_by_planner=True
         #
         # This ensures LLM cannot hallucinate based on classification data
         classify_intent: @actions.Classify_User_Intent
            description: "Determine what the user needs help with"
            with user_message = ...  # LLM extracts from conversation
            set @variables.classified_intent = @outputs.intent
            set @variables.confidence_score = @outputs.confidence
            set @variables.needs_classification = False

         # Manual routing for low-confidence cases
         go_billing: @utils.transition to @topic.billing
            description: "Yes, I need billing help"
            available when @variables.low_confidence_warning == True and @variables.classified_intent == "billing"

         go_support: @utils.transition to @topic.technical_support
            description: "Yes, I need technical support"
            available when @variables.low_confidence_warning == True and @variables.classified_intent == "technical_support"

         go_sales: @utils.transition to @topic.sales
            description: "Yes, I need sales help"
            available when @variables.low_confidence_warning == True and @variables.classified_intent == "sales"

         go_returns: @utils.transition to @topic.returns
            description: "Yes, I need returns help"
            available when @variables.low_confidence_warning == True and @variables.classified_intent == "returns"

         # Reclassify if user said "no"
         reclassify: @utils.setVariables
            description: "That's not what I need - let me clarify"
            available when @variables.low_confidence_warning == True
            with needs_classification = True
            with classified_intent = ""
            with confidence_score = 0
            with low_confidence_warning = False

# ============================================================
# ROUTED TOPICS
# ============================================================

topic billing:
   description: "Handle billing inquiries"
   reasoning:
      instructions: |
         Help the customer with their billing question.
         You can view invoices, explain charges, or process payments.
      actions:
         back: @utils.transition to @topic.topic_selector
            description: "Return to main menu"
         escalate_now: @utils.escalate
            description: "Transfer to billing specialist"

topic technical_support:
   description: "Handle technical support issues"
   reasoning:
      instructions: |
         Help the customer with their technical issue.
         Troubleshoot problems and provide solutions.
      actions:
         back: @utils.transition to @topic.topic_selector
            description: "Return to main menu"
         escalate_now: @utils.escalate
            description: "Transfer to technical specialist"

topic sales:
   description: "Handle sales inquiries"
   reasoning:
      instructions: |
         Help the customer with sales questions.
         Provide product information and pricing.
      actions:
         back: @utils.transition to @topic.topic_selector
            description: "Return to main menu"
         escalate_now: @utils.escalate
            description: "Transfer to sales representative"

topic returns:
   description: "Handle return requests"
   reasoning:
      instructions: |
         Help the customer with their return request.
         Check eligibility and process returns.
      actions:
         back: @utils.transition to @topic.topic_selector
            description: "Return to main menu"
         escalate_now: @utils.escalate
            description: "Transfer to returns specialist"

# Escalation Pattern Template
# ===========================
#
# This template demonstrates the complete escalation pattern with:
# - Multi-channel connection blocks (messaging, voice, web)
# - Graceful handoff with escalation messages
# - Pre-escalation data gathering
# - OmniChannel routing configuration
#
# Pattern: Multi-channel escalation with context preservation
# Use when: Any agent that needs human handoff capabilities

system:
   messages:
      welcome: "Hello! I'm here to help. If I can't assist you, I can connect you with a specialist."
      error: "I apologize, something went wrong. Let me connect you with someone who can help."
   instructions: "You are a helpful agent. When you cannot resolve an issue, escalate to a human agent with full context."

config:
   agent_name: "EscalationPatternAgent"
   agent_label: "Escalation Demo Agent"
   description: "Agent demonstrating complete escalation patterns"
   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User

# ============================================================
# CONNECTION BLOCKS (Multi-Channel Escalation)
# ============================================================

connections:
   # Messaging channel (SMS, WhatsApp, etc.)
   connection messaging:
      escalation_message: "One moment, I'm transferring our conversation to a specialist who can better assist you."
      outbound_route_type: "OmniChannelFlow"
      outbound_route_name: "<flow://Escalate_Messaging_To_Agent>"
      adaptive_response_allowed: False

   # Voice channel
   connection voice:
      escalation_message: "Please hold while I transfer you to a specialist. They will have full context of our conversation."
      outbound_route_type: "Queue"
      outbound_route_name: "Customer_Support_Queue"
      adaptive_response_allowed: True

   # Web chat channel
   connection web:
      escalation_message: "Connecting you with a live agent now. They'll be with you shortly."
      outbound_route_type: "OmniChannelFlow"
      outbound_route_name: "<flow://Web_Chat_Escalation_Flow>"
      adaptive_response_allowed: False

variables:
   # Customer context
   customer_name: mutable string = ""
      description: "Customer's name for personalization"
   customer_issue: mutable string = ""
      description: "Summary of customer's issue"
   issue_category: mutable string = ""
      description: "Category of issue for routing"

   # Escalation state
   escalation_reason: mutable string = ""
      description: "Reason for escalation"
   attempts_before_escalation: mutable number = 0
      description: "Number of resolution attempts"
   ready_to_escalate: mutable boolean = False
      description: "Whether pre-escalation data is gathered"

start_agent entry:
   description: "Entry point - greet and assess needs"
   reasoning:
      instructions: |
         Greet the customer and understand their needs.
         Try to help directly, escalate if needed.
      actions:
         go_support: @utils.transition to @topic.support
            description: "Help with support issue"

# ============================================================
# SUPPORT TOPIC (With Escalation Triggers)
# ============================================================

topic support:
   description: "Attempt to resolve issue, escalate if unable"
   reasoning:
      instructions: ->
         # POST-ACTION: Check if escalation was triggered
         if @variables.ready_to_escalate == True:
            transition to @topic.pre_escalation

         # Track attempts
         | I'm here to help you with your issue.

         if @variables.attempts_before_escalation >= 2:
            | It seems like I'm having trouble resolving this.
            | Would you like me to connect you with a specialist?

      actions:
         # Attempt resolution
         try_resolve: @actions.Attempt_Resolution
            description: "Try to resolve the issue"
            with issue = ...  # LLM extracts from conversation
            set @variables.customer_issue = @outputs.issue_summary
            set @variables.issue_category = @outputs.category
            set @variables.attempts_before_escalation = @variables.attempts_before_escalation + 1

         # User-initiated escalation
         request_human: @utils.setVariables
            description: "I'd like to speak with a human"
            with escalation_reason = "Customer requested human agent"
            with ready_to_escalate = True

         # Agent-initiated escalation (after failed attempts)
         escalate_complex: @utils.setVariables
            description: "Connect me with a specialist"
            available when @variables.attempts_before_escalation >= 2
            with escalation_reason = "Unable to resolve after multiple attempts"
            with ready_to_escalate = True

# ============================================================
# PRE-ESCALATION TOPIC (Gather Context)
# ============================================================

topic pre_escalation:
   description: "Gather information before escalating"
   reasoning:
      instructions: ->
         # Ensure we have customer name for personalization
         if @variables.customer_name == "":
            | Before I transfer you, may I have your name so the specialist can address you properly?
         else:
            | Thank you, {!@variables.customer_name}. Let me prepare the transfer.

         # Display summary of what we'll share
         if @variables.customer_name != "" and @variables.customer_issue != "":
            | I'll share the following with the specialist:
            | - Your issue: {!@variables.customer_issue}
            | - Category: {!@variables.issue_category}
            | - Reason for transfer: {!@variables.escalation_reason}
            |
            | Ready to connect you now.
            transition to @topic.escalation

      actions:
         # Capture customer name
         save_name: @utils.setVariables
            description: "Save customer name"
            available when @variables.customer_name == ""
            with customer_name = ...  # LLM extracts name from response

         # Proceed to escalation
         proceed: @utils.transition to @topic.escalation
            description: "Proceed with transfer"
            available when @variables.customer_name != ""

         # Cancel escalation
         cancel_escalation: @utils.setVariables
            description: "Actually, let me try again with the bot"
            with ready_to_escalate = False
            with escalation_reason = ""
            run @utils.transition to @topic.support

# ============================================================
# ESCALATION TOPIC (Handoff)
# ============================================================

topic escalation:
   description: "Execute escalation to human agent"
   reasoning:
      instructions: ->
         # Log escalation context (this gets passed to human agent)
         run @actions.Log_Escalation_Context
            with customer_name = @variables.customer_name
            with issue_summary = @variables.customer_issue
            with category = @variables.issue_category
            with reason = @variables.escalation_reason
            with attempt_count = @variables.attempts_before_escalation

         | Transferring you now. Thank you for your patience!

      actions:
         # The actual escalation - uses connection block configuration
         handoff: @utils.escalate
            description: "Transfer to human agent"

# ============================================================
# OPTIONAL: SPECIALIZED ESCALATION QUEUES
# ============================================================

topic escalate_billing:
   description: "Escalate specifically to billing team"
   reasoning:
      instructions: |
         I'm connecting you with our billing specialists.
         They'll be able to help with your account questions.
      actions:
         # Note: In production, you'd configure this action
         # to route to a specific billing queue
         billing_handoff: @utils.escalate
            description: "Transfer to billing team"

topic escalate_technical:
   description: "Escalate specifically to technical support"
   reasoning:
      instructions: |
         I'm connecting you with our technical support team.
         They specialize in resolving complex technical issues.
      actions:
         tech_handoff: @utils.escalate
            description: "Transfer to technical support"

# Flow Action Lookup Template
# ============================
#
# This template demonstrates the pattern for calling Flow actions
# that return complex data types (SObjects, lists, custom types).
#
# Pattern: Data lookup and display using Flow actions
# Use when: Fetching records from Salesforce (Cases, Orders, Accounts)
#
# CRITICAL: When defining Flow action outputs in Agentforce Assets:
# - For SObject returns: complex_data_type_name = "lightning__recordInfoType"
# - For list[string]: complex_data_type_name = "lightning__textType"
# - For currency: complex_data_type_name = "lightning__currencyType"

system:
   messages:
      welcome: "Hello! I can help you look up order information."
      error: "I apologize, something went wrong retrieving your data."
   instructions: "You are a customer service agent helping users look up their orders."

config:
   agent_name: "FlowActionLookupAgent"
   agent_label: "Order Lookup Agent"
   description: "Agent demonstrating Flow action patterns with complex data types"
   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User

variables:
   # Customer context (from session)
   customer_id: linked string
      source: @session.customerId
      description: "Customer ID from session context"

   # Order data (populated by Flow action)
   order_id: mutable string = ""
      description: "Current order being viewed"
   order_status: mutable string = ""
      description: "Order status from lookup"
   order_total: mutable string = ""
      description: "Order total amount"
   order_date: mutable string = ""
      description: "Order date"

   # Error handling
   lookup_error: mutable boolean = False
      description: "Whether lookup encountered an error"

start_agent entry:
   description: "Entry point - welcome and route to order lookup"
   reasoning:
      instructions: |
         Welcome the customer and offer to help with order lookups.
      actions:
         go_lookup: @utils.transition to @topic.order_lookup
            description: "Start order lookup"

# ============================================================
# ORDER LOOKUP TOPIC (Flow Action Pattern)
# ============================================================

topic order_lookup:
   description: "Look up order details using Flow action"
   reasoning:
      instructions: ->
         # POST-ACTION CHECK: Display results if order was found
         if @variables.order_status != "":
            | **Order Details**
            | - Order ID: {!@variables.order_id}
            | - Status: {!@variables.order_status}
            | - Total: {!@variables.order_total}
            | - Date: {!@variables.order_date}
            |
            | Is there anything else you'd like to know about this order?

         # ERROR CHECK: Handle lookup failures
         if @variables.lookup_error == True:
            | I couldn't find that order. Please check the order ID and try again.
            set @variables.lookup_error = False

         # INITIAL STATE: Ask for order ID
         if @variables.order_id == "":
            | What order would you like me to look up?
            | Please provide your order ID.

      actions:
         # Flow action with SObject return type
         # In Agentforce Assets, set outputs.order_record complex_data_type_name = "lightning__recordInfoType"
         lookup_order: @actions.Get_Order_Details
            description: "Look up order by ID"
            with order_id = ...  # LLM extracts from user message
            include_in_progress_indicator: True
            progress_indicator_message: "Looking up your order..."
            set @variables.order_id = @outputs.order_id
            set @variables.order_status = @outputs.status
            set @variables.order_total = @outputs.total_amount
            set @variables.order_date = @outputs.order_date
            # Error handling: check if lookup failed
            if @outputs.found == False:
               set @variables.lookup_error = True

         # Flow action returning a list of strings
         # In Agentforce Assets, set outputs.product_names complex_data_type_name = "lightning__textType"
         get_items: @actions.Get_Order_Line_Items
            description: "Get list of items in the order"
            available when @variables.order_id != ""
            with order_id = @variables.order_id

         clear_search: @utils.setVariables
            description: "Search for a different order"
            with order_id = ""
            with order_status = ""
            with order_total = ""
            with order_date = ""

         escalate_now: @utils.escalate
            description: "Transfer to human agent"

# Hub-and-Spoke Architecture Template
# ====================================
#
# This template demonstrates the Hub-and-Spoke pattern where a central
# topic_selector (hub) routes conversations to specialized topics (spokes).
#
# Pattern: Multi-purpose agents handling distinct request types
# Use when: Users may have different intents (orders, support, returns)

system:
   messages:
      welcome: "Welcome! I can help with orders, returns, or general support."
      error: "I apologize, something went wrong. Let me try again."
   instructions: "You are a customer service agent for an e-commerce company."

config:
   agent_name: "HubAndSpokeAgent"
   agent_label: "Customer Service Agent"
   description: "Multi-purpose agent with hub-and-spoke architecture"
   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User

variables:
   customer_id: linked string
      source: @session.customerId
      description: "Customer ID from session"
   order_id: mutable string = ""
      description: "Current order being discussed"
   issue_resolved: mutable boolean = False
      description: "Whether the issue has been resolved"

# ============================================================
# HUB: Central Router
# ============================================================

start_agent topic_selector:
   description: "Route to appropriate topic based on user intent"
   reasoning:
      instructions: |
         Determine what the customer needs and route accordingly:
         - Order questions → orders topic
         - Return/refund requests → returns topic
         - General questions → support topic
      actions:
         check_order: @utils.transition to @topic.orders
            description: "Customer wants to check order status"
         process_return: @utils.transition to @topic.returns
            description: "Customer wants to return or refund"
         general_help: @utils.transition to @topic.support
            description: "General support questions"

# ============================================================
# SPOKE: Orders Topic
# ============================================================

topic orders:
   description: "Handle order status and tracking inquiries"
   reasoning:
      instructions: ->
         | Help the customer with their order inquiry.

         if @variables.order_id != "":
            | Current order: {!@variables.order_id}

      actions:
         lookup_order: @actions.get_order_status
            description: "Look up order details"
            with order_id = @variables.order_id
         back_to_hub: @utils.transition to @topic.topic_selector
            description: "Return to main menu"

# ============================================================
# SPOKE: Returns Topic
# ============================================================

topic returns:
   description: "Handle return and refund requests"
   reasoning:
      instructions: ->
         | Help the customer with their return or refund request.
         | Verify the order details before processing.

      actions:
         start_return: @actions.initiate_return
            description: "Start a return process"
         process_refund: @actions.process_refund
            description: "Process a refund"
         back_to_hub: @utils.transition to @topic.topic_selector
            description: "Return to main menu"

# ============================================================
# SPOKE: Support Topic
# ============================================================

topic support:
   description: "Handle general support questions"
   reasoning:
      instructions: |
         Help the customer with general questions.
         If the question requires specialized help, route appropriately.
      actions:
         escalate: @utils.escalate
            description: "Transfer to human agent"
         back_to_hub: @utils.transition to @topic.topic_selector
            description: "Return to main menu"

/**
 * Invocable Apex template for Agent Script action backing logic.
 *
 * Wire this class to an Agent Script action with:
 *     target: "apex://{{ClassName}}"
 *
 * The @InvocableVariable field names on Request and Result become the
 * action's input and output names in the .agent file. They must match
 * character-for-character — including case.
 *
 * STUB USAGE: To create a minimal stub for unblocking deployment,
 * delete the business logic in execute() and return hardcoded values.
 * Do not add mock data, conditional logic, or JSON serialization to
 * stubs — keep them minimal.
 *
 * Replace all {{placeholders}} before use.
 */
public with sharing class {{ClassName}} {

    // ─── INVOCABLE METHOD ────────────────────────────────────────────
    //
    // Must be: static, accept List<Request>, return List<Result>.
    // This signature supports bulkification when the action is called
    // for multiple records in a single transaction.

    @InvocableMethod(
        label='{{ActionLabel}}'
        description='{{ActionDescription}}'
    )
    public static List<Result> execute(List<Request> requests) {
        List<Result> results = new List<Result>();

        // ── Bulkification: collect IDs first, query once ──
        // Avoids SOQL-in-loop governor limit issues.
        Set<Id> recordIds = new Set<Id>();
        for (Request req : requests) {
            if (req.recordId != null) {
                recordIds.add(req.recordId);
            }
        }

        // ── USER_MODE ──
        // `USER_MODE` enforces the running user's FLS/CRUD permissions.
        // For service agents, the running user is the Einstein Agent User.
        // If the user lacks read access to queried objects, queries return
        // 0 rows with NO error — a silent failure. Verify object permissions
        // before relying on `USER_MODE` queries.

        // Static SOQL (Preferred): Use `WITH USER_MODE` clause:
        Map<Id, {{SObjectName}}> recordsById = new Map<Id, {{SObjectName}}>();
        if (!recordIds.isEmpty()) {
            recordsById = new Map<Id, {{SObjectName}}>(
                [SELECT Id, Name
                 FROM {{SObjectName}}
                 WHERE Id IN :recordIds
                 WITH USER_MODE]
            );
        }

        // Dynamic SOQL (Optional): Use `AccessLevel.USER_MODE` parameter. DO NOT use `WITH USER_MODE` clause!
        // WARNING! `WITH USER_MODE` inside a dynamic string causes:
        //   System.QueryException: unexpected token: 'WITH'
        //
        // WRONG:
        //   String q = 'SELECT Id, Name FROM {{SObjectName}} WHERE Id IN :recordIds WITH USER_MODE';
        //   recordsById = new Map<Id, {{SObjectName}}>(Database.query(q));
        //
        // RIGHT:
        //   String q = 'SELECT Id, Name FROM {{SObjectName}} WHERE Id IN :recordIds';
        //   recordsById = new Map<Id, {{SObjectName}}>(Database.query(q, AccessLevel.USER_MODE));

        // ── Process each request ──
        for (Request req : requests) {
            Result r = new Result();
            try {
                {{SObjectName}} record = recordsById.get(req.recordId);
                if (record == null) {
                    r = errorResult('Record not found: ' + req.recordId);
                } else {
                    // TODO: Replace with actual business logic
                    r.isSuccess = true;
                    r.outputMessage = 'Processed: ' + record.Name;
                    r.outputRecordId = record.Id;
                }
            } catch (Exception e) {
                r = errorResult(e.getMessage());
            }
            results.add(r);
        }

        return results;
    }

    // ─── REQUEST WRAPPER ─────────────────────────────────────────────
    //
    // Each @InvocableVariable becomes an action input in Agent Script.
    // The field name here must exactly match the input name in the
    // .agent file's action definition.
    //
    // Supported types: Boolean, Date, DateTime, Decimal, Double,
    //   Integer, Long, String, Id, Time, SObject types, List<T>

    public class Request {
        @InvocableVariable(
            label='Record ID'
            description='ID of the record to process'
            required=true
        )
        public Id recordId;

        @InvocableVariable(
            label='Operation Type'
            description='Type of operation to perform'
            required=false
        )
        public String operationType;

        @InvocableVariable(
            label='Amount'
            description='Numeric amount for calculations'
            required=false
        )
        public Decimal amount;
    }

    // ─── RESULT WRAPPER ──────────────────────────────────────────────
    //
    // Each @InvocableVariable becomes an action output in Agent Script.
    // The field name here must exactly match the output name in the
    // .agent file's action definition.
    //
    // Always include isSuccess and errorMessage for consistent error
    // handling. The agent can check isSuccess to decide what to tell
    // the user.

    public class Result {
        @InvocableVariable(
            label='Is Success'
            description='Whether the operation completed successfully'
        )
        public Boolean isSuccess;

        @InvocableVariable(
            label='Error Message'
            description='Error message if operation failed'
        )
        public String errorMessage;

        @InvocableVariable(
            label='Output Message'
            description='Human-readable result for the agent to relay'
        )
        public String outputMessage;

        @InvocableVariable(
            label='Output Record ID'
            description='ID of the processed or created record'
        )
        public Id outputRecordId;

        @InvocableVariable(
            label='Output Value'
            description='Primary result value'
        )
        public String outputValue;

        @InvocableVariable(
            label='Output Amount'
            description='Numeric result for calculations'
        )
        public Decimal outputAmount;

    }

    // ── Error factory ──────────────────────────────────────────────────
    //
    // Centralizes error construction so every failure path sets both
    // isSuccess = false and errorMessage consistently. Defined on the
    // outer class because Apex prohibits static methods in inner classes.

    private static Result errorResult(String message) {
        Result r = new Result();
        r.isSuccess = false;
        r.errorMessage = message;
        return r;
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Prompt Template: Basic Template

    Use Case: Create reusable prompts for Einstein/Agentforce
    - Standardize prompt patterns across org
    - Include variable bindings from records
    - Use in agents, flows, or Apex

    Template Types:
    - salesGeneration: Generate content (emails, summaries)
    - fieldCompletion: Suggest field values
    - recordSummary: Summarize records
    - flexPrompt: General purpose

    Setup Steps:
    1. Replace all {{placeholder}} values
    2. Define input variables and their sources
    3. Deploy to org
    4. Use in Agent Actions or Flows

    File Location: force-app/main/default/promptTemplates/{{TemplateName}}.promptTemplate-meta.xml
-->
<PromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- API Name -->
    <fullName>{{TemplateName}}</fullName>

    <!-- Display name -->
    <masterLabel>{{TemplateLabel}}</masterLabel>

    <!-- Description of template purpose -->
    <description>{{TemplateDescription}}</description>

    <!--
    Template Type:
    - salesGeneration: Generate sales content
    - fieldCompletion: Predict/suggest field values
    - recordSummary: Summarize record data
    - flexPrompt: General purpose (most flexible)
    -->
    <type>flexPrompt</type>

    <!-- Active status -->
    <isActive>true</isActive>

    <!--
    The Prompt Content:
    Use {!variableName} for variable substitution.
    Keep prompts clear, specific, and well-structured.
    -->
    <promptContent>
You are an AI assistant helping with {{UseCaseDescription}}.

Context:
{!contextVariable}

Task:
{{TaskDescription}}

Instructions:
1. {{Instruction1}}
2. {{Instruction2}}
3. {{Instruction3}}

Please provide a helpful response based on the context above.
    </promptContent>

    <!--
    Input Variables:
    Define variables that can be bound to record fields or runtime values.
    -->
    <promptTemplateVariables>
        <developerName>contextVariable</developerName>
        <promptTemplateVariableType>freeText</promptTemplateVariableType>
        <isRequired>true</isRequired>
    </promptTemplateVariables>

    <!--
    Variable Types:
    - freeText: User-provided text input
    - recordField: Bound to a specific field on a record
    - relatedList: Data from related records
    - resource: Static resource content

    Example recordField variable:
    <promptTemplateVariables>
        <developerName>accountName</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>Account</objectType>
        <fieldName>Name</fieldName>
        <isRequired>true</isRequired>
    </promptTemplateVariables>
    -->

    <!--
    USAGE IN AGENT ACTIONS:

    Option 1: Via GenAiFunction
    Create GenAiFunction with invocationTargetType="prompt"
    pointing to this template.

    Option 2: Via Flow
    Use "Prompt Template" action in Flow,
    then wrap Flow in Agent Script action.

    Option 3: Via Apex
    Use ConnectApi.Einstein.evaluatePrompt() method.
    -->
</PromptTemplate>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    GenAiFunction Template: Apex Invocation (Agent Builder UI / GenAiPlannerBundle ONLY)

    ⚠️ NOT NEEDED for AiAuthoringBundle (Agent Script).
    If using Agent Script (.agent files), use `target: "apex://ClassName"` directly
    in your topic's actions block. See SKILL.md for details.

    Use Case: Register Apex @InvocableMethod as an agent action in Agent Builder UI
    - Required ONLY for GenAiPlannerBundle / Agent Builder UI path
    - Works with GenAiPlugin (Topic) for organization

    Prerequisites:
    1. Apex class with @InvocableMethod annotation must be deployed first
    2. GenAiPlugin (Topic) to organize functions (optional but recommended)

    Setup Steps:
    1. Replace all {{placeholder}} values
    2. Deploy Apex class first
    3. Create input/schema.json and output/schema.json (see below)
    4. Deploy this GenAiFunction bundle
    5. Optionally deploy GenAiPlugin to group functions

    Bundle Structure:
    force-app/main/default/genAiFunctions/
    └── {{FunctionName}}/
        ├── {{FunctionName}}.genAiFunction-meta.xml   (this file)
        ├── input/
        │   └── schema.json                           (input parameters)
        └── output/
            └── schema.json                           (output parameters)

    IMPORTANT (API v66.0):
    - Only these XML elements are valid: description, invocationTarget,
      invocationTargetType, isConfirmationRequired, masterLabel
    - Do NOT use: <capability>, <genAiFunctionParameters>,
      <genAiFunctionInputs>, <genAiFunctionOutputs>, <developerName>
    - Input/output schemas go in schema.json files, NOT inline XML
-->
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>{{FunctionDescription}}</description>
    <invocationTarget>{{ApexClassName}}</invocationTarget>
    <invocationTargetType>apex</invocationTargetType>
    <isConfirmationRequired>{{true|false}}</isConfirmationRequired>
    <masterLabel>{{FunctionLabel}}</masterLabel>
</GenAiFunction>

<!--
    input/schema.json example:
    {
        "required": ["{{inputParam1}}"],
        "properties": {
            "{{inputParam1}}": {
                "title": "{{Input Param 1 Label}}",
                "description": "{{Input Param 1 Description}}",
                "lightning:type": "lightning__textType",
                "lightning:isPII": false,
                "copilotAction:isUserInput": true
            }
        },
        "lightning:type": "lightning__objectType"
    }

    output/schema.json example:
    {
        "properties": {
            "{{outputParam1}}": {
                "title": "{{Output Param 1 Label}}",
                "description": "{{Output Param 1 Description}}",
                "lightning:type": "lightning__textType",
                "lightning:isPII": false,
                "copilotAction:isDisplayable": true,
                "copilotAction:isUsedByPlanner": true
            }
        },
        "lightning:type": "lightning__objectType"
    }

    Lightning types:
    - lightning__textType           (String)
    - lightning__numberType         (Number/Decimal)
    - lightning__booleanType        (Boolean)
    - lightning__dateType           (Date)
    - lightning__dateTimeStringType (DateTime — TDD validated v2.1.0)
    - lightning__currencyType       (Currency)

    APEX CLASS REQUIREMENTS:
    - Must be global or public with sharing
    - Method must have @InvocableMethod annotation
    - Input/output use @InvocableVariable wrapper classes
    - Parameter names in schema.json must match @InvocableVariable field names
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    GenAiFunction Template: Flow Invocation (Agent Builder UI / GenAiPlannerBundle ONLY)

    ⚠️ NOT NEEDED for AiAuthoringBundle (Agent Script).
    If using Agent Script (.agent files), use `target: "flow://FlowApiName"` directly
    in your topic's actions block. See SKILL.md for details.

    Use Case: Register Autolaunched Flow as an agent action in Agent Builder UI
    - Required ONLY for GenAiPlannerBundle / Agent Builder UI path
    - Supports HTTP callouts via Flow HTTP actions
    - Works well with External Services

    Prerequisites:
    1. Autolaunched Flow must be deployed and active first
    2. Flow must have defined input/output variables

    Setup Steps:
    1. Replace all {{placeholder}} values
    2. Deploy Autolaunched Flow first
    3. Create input/schema.json and output/schema.json (see genai-function-apex.xml for format)
    4. Deploy this GenAiFunction bundle

    Bundle Structure:
    force-app/main/default/genAiFunctions/
    └── {{FunctionName}}/
        ├── {{FunctionName}}.genAiFunction-meta.xml   (this file)
        ├── input/
        │   └── schema.json                           (input parameters)
        └── output/
            └── schema.json                           (output parameters)

    IMPORTANT (API v66.0):
    - Only these XML elements are valid: description, invocationTarget,
      invocationTargetType, isConfirmationRequired, masterLabel
    - Do NOT use: <capability>, <genAiFunctionParameters>,
      <genAiFunctionInputs>, <genAiFunctionOutputs>, <developerName>
    - Input/output schemas go in schema.json files, NOT inline XML
-->
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>{{FunctionDescription}}</description>
    <invocationTarget>{{FlowApiName}}</invocationTarget>
    <invocationTargetType>flow</invocationTargetType>
    <isConfirmationRequired>{{true|false}}</isConfirmationRequired>
    <masterLabel>{{FunctionLabel}}</masterLabel>
</GenAiFunction>

<!--
    FLOW REQUIREMENTS:
    1. Flow Type: Autolaunched Flow (NOT Screen Flow)
    2. Input Variables: Must be marked "Available for input"
    3. Output Variables: Must be marked "Available for output"
    4. Variable names in schema.json must match Flow variable names exactly
    5. Flow must be Active

    See genai-function-apex.xml for input/schema.json and output/schema.json format examples.
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    GenAiPlugin Template: Agent Topic/Plugin Container

    Use Case: Organize GenAiFunctions into logical groups (Topics)
    - Groups related functions together
    - Provides topic-level instructions
    - Maps to Agent Script topic concepts

    Note: GenAiPlugin is the metadata equivalent of a "topic" in Agent Script.
    Use this when you want to organize functions deployed via metadata
    rather than Agent Script.

    Setup Steps:
    1. Replace all {{placeholder}} values
    2. Deploy GenAiFunctions first
    3. Deploy this GenAiPlugin

    File Location: force-app/main/default/genAiPlugins/{{PluginName}}.genAiPlugin-meta.xml
-->
<GenAiPlugin xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- Display name for the topic/plugin -->
    <masterLabel>{{PluginLabel}}</masterLabel>

    <!-- Description shown in Agent Builder -->
    <description>{{PluginDescription}}</description>

    <!-- Developer name (API name) -->
    <developerName>{{PluginDeveloperName}}</developerName>

    <!--
    Plugin Instructions:
    Natural language instructions for how the agent should use
    functions in this plugin. Similar to topic instructions in Agent Script.
    -->
    <pluginInstructions>
        {{Instructions for the agent on how to use functions in this topic.
        Include guidance on when to use specific functions,
        how to handle edge cases, and any constraints.}}
    </pluginInstructions>

    <!--
    Plugin Type:
    - Standard: Regular function grouping
    - Copilot: For Salesforce Copilot-specific plugins
    -->
    <pluginType>Standard</pluginType>

    <!--
    Associated Functions:
    List the GenAiFunction developer names that belong to this plugin.
    -->
    <genAiFunctions>
        <function>{{GenAiFunction1DeveloperName}}</function>
    </genAiFunctions>
    <genAiFunctions>
        <function>{{GenAiFunction2DeveloperName}}</function>
    </genAiFunctions>

    <!--
    AGENT BUILDER INTEGRATION:

    After deploying GenAiPlugin:
    1. Open Agent Builder in Setup
    2. Navigate to Topics
    3. Your plugin appears as a Topic
    4. Associated functions are available as Actions

    This provides an alternative to Agent Script for more
    complex deployments or when you need metadata-level control.
    -->
</GenAiPlugin>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Prompt Template: Record-Grounded Template

    Use Case: Prompts that use Salesforce record data for context
    - Ground responses in actual CRM data
    - Summarize records intelligently
    - Generate record-specific content

    Key Feature: Variables bound to record fields provide real data
    to the prompt, ensuring accuracy and relevance.

    Setup Steps:
    1. Replace all {{placeholder}} values
    2. Configure record field bindings
    3. Deploy to org

    File Location: force-app/main/default/promptTemplates/{{TemplateName}}.promptTemplate-meta.xml
-->
<PromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{TemplateName}}</fullName>
    <masterLabel>{{TemplateLabel}}</masterLabel>
    <description>{{TemplateDescription}}</description>

    <!-- Record summary type for record-grounded prompts -->
    <type>recordSummary</type>

    <isActive>true</isActive>

    <!--
    Primary Object:
    The main object this template operates on.
    -->
    <objectType>{{ObjectApiName}}</objectType>

    <!--
    Prompt with record field references:
    Use {!variableName} syntax for bound fields.
    -->
    <promptContent>
You are summarizing a {{ObjectLabel}} record for a sales representative.

Record Information:
- Name: {!recordName}
- Status: {!recordStatus}
- Owner: {!ownerName}
- Created Date: {!createdDate}
- Last Activity: {!lastActivityDate}

Additional Context:
{!additionalNotes}

Related Information:
{!relatedRecords}

Please provide a concise summary that highlights:
1. Current status and recent activity
2. Key metrics or important values
3. Recommended next steps
4. Any risks or concerns

Keep the summary under 200 words and focus on actionable insights.
    </promptContent>

    <!-- Record Name Field -->
    <promptTemplateVariables>
        <developerName>recordName</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>{{ObjectApiName}}</objectType>
        <fieldName>Name</fieldName>
        <isRequired>true</isRequired>
    </promptTemplateVariables>

    <!-- Status Field -->
    <promptTemplateVariables>
        <developerName>recordStatus</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>{{ObjectApiName}}</objectType>
        <fieldName>{{StatusFieldApiName}}</fieldName>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!-- Owner Name -->
    <promptTemplateVariables>
        <developerName>ownerName</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>{{ObjectApiName}}</objectType>
        <fieldName>Owner.Name</fieldName>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!-- Created Date -->
    <promptTemplateVariables>
        <developerName>createdDate</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>{{ObjectApiName}}</objectType>
        <fieldName>CreatedDate</fieldName>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!-- Last Activity Date -->
    <promptTemplateVariables>
        <developerName>lastActivityDate</developerName>
        <promptTemplateVariableType>recordField</promptTemplateVariableType>
        <objectType>{{ObjectApiName}}</objectType>
        <fieldName>LastActivityDate</fieldName>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!-- Free text for additional context -->
    <promptTemplateVariables>
        <developerName>additionalNotes</developerName>
        <promptTemplateVariableType>freeText</promptTemplateVariableType>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!-- Related records (could be from related list) -->
    <promptTemplateVariables>
        <developerName>relatedRecords</developerName>
        <promptTemplateVariableType>freeText</promptTemplateVariableType>
        <isRequired>false</isRequired>
    </promptTemplateVariables>

    <!--
    DATA CLOUD GROUNDING (Optional):

    For Data Cloud integration, add:
    <dataCloudConfig>
        <dataCloudObjectName>{{DataCloudObjectName}}</dataCloudObjectName>
        <retrievalStrategy>semantic</retrievalStrategy>
    </dataCloudConfig>

    This enables RAG (Retrieval Augmented Generation) with
    Data Cloud data for more contextual responses.
    -->
</PromptTemplate>

# Minimal Agent Script Starter Template
# =====================================
#
# This template provides the minimum required structure for an Agent Script.
# Use this as a starting point for simple, single-purpose agents.
#
# Required blocks: system, config, topic, start_agent
# File extension: .agent

system:
   messages:
      welcome: "Hello! How can I help you today?"
      error: "I apologize, but something went wrong. Let me try again."
   instructions: "You are a helpful assistant."

config:
   agent_name: "MinimalAgent"
   agent_label: "Minimal Agent"
   description: "A minimal agent template to get started"
   default_agent_user: "agent@yourorg.com"  # REQUIRED: Change to valid Einstein Agent User

# Optional: Add variables for state tracking
# variables:
#    counter: mutable number = 0
#    session_id: linked string
#       source: @session.sessionID

topic main:
   description: "Main conversation handler"
   reasoning:
      instructions: |
         Help the user with their request.
         Be friendly and helpful.

start_agent entry:
   description: "Entry point for all conversations"
   reasoning:
      instructions: |
         Greet the user and route to the main topic.
      actions:
         begin: @utils.transition to @topic.main
            description: "Start the main conversation"