GenAiPromptTemplateActv Metadata Type in SFDX

Architectural Overview#

The GenAiPromptTemplateActv metadata type represents the active version pointer for Generative AI prompt templates in Salesforce Prompt Builder and Einstein Studio. When prompt engineers author generative prompt templates (GenAiPromptTemplate), each save produces an immutable versioned iteration. Runtime invocations from Flow, Apex, or Lightning record pages do not invoke drafts; they bind exclusively to the activated version defined by GenAiPromptTemplateActv.

In modern Agentforce and Einstein 1 DevOps architectures, managing template activation through metadata ensures reproducible delivery across development, staging, and production orgs without manual administrative toggling.

Directory and File Conventions#

GenAiPromptTemplateActv components are stored in the genAiPromptTemplateActvs directory in SFDX source format.

Key Metadata Fields#

The XML schema for GenAiPromptTemplateActv contains the following attributes:

Declarative XML and Package Manifest Examples#

Below is an example of an activation metadata file binding version 2 of an Account Summarizer prompt template:

<?xml version="1.0" encoding="UTF-8"?>
<GenAiPromptTemplateActv xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Account Summary Active Version</masterLabel>
    <promptTemplate>Account_Summary_Generator</promptTemplate>
    <versionNumber>2</versionNumber>
</GenAiPromptTemplateActv>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Account_Summary_Generator</members>
        <name>GenAiPromptTemplate</name>
    </types>
    <types>
        <members>Account_Summary_Actv</members>
        <name>GenAiPromptTemplateActv</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment via SF CLI#

Retrieve and deploy prompt template activations using modern Salesforce CLI commands:

# Retrieve prompt template and activation metadata
sf project retrieve start --metadata "GenAiPromptTemplate:Account_Summary_Generator" "GenAiPromptTemplateActv:Account_Summary_Actv"

# Deploy in a single transactional manifest
sf project deploy start --manifest manifest/package.xml --target-org staging-org

Senior Architect Best Practices and Gotchas#

• Atomic Deployment: Deploying GenAiPromptTemplateActv without including the target GenAiPromptTemplate version will fail if the version has not yet landed in the destination environment.
• Dependency Ordering: Flows or Apex classes invoking the prompt template via ConnectApi should be deployed either alongside or after the prompt template activation.
• Rollback Strategy: Rolling back an active prompt template requires deploying a GenAiPromptTemplateActv file pointing to the previous stable versionNumber.
• Scratch Org Setup: Ensure Einstein Generative AI features are enabled in project-scratch-def.json before deploying GenAI metadata types.

Frequently asked questions

What is the primary role of GenAiPromptTemplateActv?

It binds a specific version number of a prompt template to the active state so Einstein AI runtime executes that exact prompt template version.

Why should prompt activations be deployed as metadata?

Deploying activation metadata eliminates manual activation steps in target environments, ensuring continuous delivery pipelines maintain consistency.

What happens if GenAiPromptTemplateActv references an undeployed version?

The deployment fails with an error stating that the specified prompt template version number does not exist in the target org.

Can multiple versions of a prompt template be active simultaneously?

No. Only one version of a prompt template can be active at a time, governed by the active version metadata definition.