SfSkills Domains Docs GitHub

Home / agentforce / agentforce-prompt-versioning

agentforce-prompt-versioning

Version Prompt Templates and agent topic (now subagent) prompts: source-control shape, change review, model-version pinning, A/B, and rollback. Trigger keywords: prompt template versioning, prompt changelog, prompt rollback, A/B prompt test, agentforce prompt release. NOT for the CMDT-backed binding that swaps the live template version without a redeploy — use agentforce/prompt-template-versioning. NOT for authoring the template itself — use agentforce/prompt-builder-templates. NOT for prompt engineering tips, general LLM fine-tuning, or Classify / Einstein Generate studio UI walkthroughs.

Open the skill folder on GitHub

Agentforce Prompt Versioning

This skill is the repository lifecycle for prompt templates: layout, change records, model pinning, drift detection, and ownership. The runtime flip — how the live version changes, what rollback costs in wall-clock time, and how to run two variants concurrently — is agentforce/prompt-template-versioning. The two meet at activeVersionIdentifier.

Why Version Prompts

A prompt is executable configuration whose behaviour cannot be verified by reading it. That makes the record of why a version exists more load-bearing than for ordinary code, where the code is its own documentation.

Source Of Truth And File Shape

GenAiPromptTemplate lives in force-app/main/default/genAiPromptTemplates/ with suffix .genAiPromptTemplate, minimum API version 60.0. The fact that determines everything else about the layout:

All versions of a template live in one file. templateVersions is an array on the template — not a file per version. activeVersionIdentifier names the live one.

Per-version fields inside each GenAiPromptTemplateVersion: versionNumber, versionIdentifier, status (Published/Draft), content, primaryModel, inputs, outputSchema, responseFormat (HTML/JSON/MarkDown), isCitationEnabled, and templateDataProviders.

So git history is per template and the changelog is per version. Neither substitutes for the other.

The repo is authoritative — but state it and detect it. Both drift directions are silent (a UI edit does not fail; the deploy that reverts it does not fail either), so a convention alone is not a control. See the nightly drift check below.

Naming And Version Strategy

Contract-breaking means: a new required input, a changed responseFormat or outputSchema, new or removed templateDataProviders, or a changed primaryModel. None of these fail at deploy time — a new required input fails at invocation.

Changelog Convention

PROMPTS_CHANGELOG.md at repo root, keyed by versionIdentifier. Four sections, contract impact first because it is the only one a release manager must read:

## 2026-08-10 — Sales_Email v4  (versionIdentifier: e5f6g7h8)

### Contract impact: NONE
inputs unchanged · responseFormat unchanged · outputSchema n/a ·
templateDataProviders unchanged · primaryModel unchanged
=> one-field activation flip; no consumer deployment required

### What changed
Removed the "As an AI assistant" preamble; added an instruction to name the
most recent Opportunity stage change; shortened closing guidance to 1 sentence.

### Why
Sales ops sampled 80 drafts (2026-07): reps deleted the opening line in 60%.

### Measured before promotion
Golden suite 48/48 (unchanged) · median draft 214 -> 168 words ·
canary 10% / 5 working days / n=41 reps: send-without-edit 38% -> 51% ·
no adverse latency change

### Rollback
Revert activeVersionIdentifier to a1b2c3d4 (v3), deploy.
Measured 6 min in the 2026-08-04 rehearsal. v3 retained until 2026-10-01.

Numbers with sample sizes are the point. "Improved tone" records a belief; a reader six months later must be able to disagree with the conclusion.

Model Pinning

The field is primaryModel on GenAiPromptTemplateVersion. Verify any model identifier against what the org offers — a plausible-but-wrong value deploys and then behaves unexpectedly.

Pin per template, not per org, and only where reproducibility is a stated requirement: parsed output, regulated wording, customer-facing copy. Leave the platform default where a human reviews every output anyway.

Pinning is a commitment to re-evaluate quarterly. A stale pin produces no error — output simply stops improving while the platform default's does. Record the outcome either way; "evaluated and declined because X, reconsider Q2" is a completed review.

A/B And Rollback

Only one version of a template can be active at a time, and there is no platform-level traffic split. Concurrent variants therefore need two templates plus a resolver you write — the mechanics live in agentforce/prompt-template-versioning. What belongs here is the record: which variants ran, over what period, with what result.

Rollback availability is a retention decision. Keep at least two prior versions with a dated retirement; an inactive version costs only file size, and the weeks right after a promotion — when the cleanup instinct fires — are exactly when the rollback is most likely to be needed.

  1. Inventory templates. Assign two owners each in CODEOWNERS — the business

    owner of the wording and the engineer who owns the envelope. The failure modes split the same way.

  2. One file per template under genAiPromptTemplates/, all versions inside.

    Put a structural-diff command in the PR template so envelope changes surface before anyone opens a 400-line prose diff.

  3. Write the change record with contract impact first and measurements with

    sample sizes.

  4. Decide primaryModel pinning per template, and schedule the quarterly

    re-evaluation with a named owner. Do not pin without the capacity to review.

  5. Inject policy values (refundWindowDays) as inputs rather than embedding

    them in prose — unless the exact sentence is itself the reviewed artefact.

  6. Run a nightly sf project retrieve start --metadata GenAiPromptTemplate plus

    git diff --exit-code, with a written resolution rule per drift direction. Run it again after every production deploy as release verification.

  7. Put GenAiPromptTemplate early in package.xml — the Metadata API deploys in

    file order and the template must exist before referencing types such as AiAgentScorerDefinition.

Official Sources Used

Dependencies

Package files