Agent Deployment Checklist
A single checklist is the artifact that prevents post-deployment incidents. Organized into five blocks: functional tests green, adversarial tests green, observability live, rollback rehearsed, stakeholders signed-off.
Adoption Signals
Every production activation; every material config change (new Invocable, new channel, new persona). Use this skill any time someone asks whether the agent is ready for production.
- Required for any change that adds a new tool to the agent's toolbox or expands record-access scope.
- Run before enabling a new channel (Service Cloud, Slack, Experience Cloud) — channel context changes the prompt-injection threat model.
What Makes Agent Deployment Different
Three platform behaviours, none of which apply to an ordinary Salesforce
release, and all of which are documented in
Retrieve and Deploy Agent Metadata:
- A committed agent cannot be edited. "You can't edit a committed agent.
Instead, create and edit a new version." There is no quick-fix path — a
hotfix costs a full release cycle, so plan the incident response accordingly.
- Two version counters must be paired by hand. Saves increment
AiAuthoringBundle; commits increment Bot/BotVersion. If you save more
than you commit they diverge and you must specify both numbers explicitly.
- Observability is not retroactive. Session Tracing records only
conversations occurring after the data model is set up, so it is a
pre-activation prerequisite rather than an incident response.
Also: the manifest needs API version 66.0 or later for GenAiPlannerBundle
and the new agent metadata types — sourced from
The New Agentforce Metadata and Development Lifecycle,
not from the Retrieve and Deploy Agent Metadata guide page cited above, whose
own example shows <version>65.0</version>. Wildcards on ApexClass/Flows/
GenAiPromptTemplates cause deploy timeouts, deploying a lone BotVersion
requires the full agent to be present already, and retrieved agent metadata must
not be hand-edited.
Recommended Workflow
- Functional.
sf agent test run --wait green on the routing, golden, and
adversarial AiEvaluationDefinition suites. Record the run id on the
activation record.
- Security. Adversarial suite green; PII classification register reviewed
against the channel set this activation covers. A channel is part of the
approved condition, not a later configuration tweak.
- Runtime user. Verify the agent user in the target org for Apex class
access, object CRUD, field-level access, Flow and Named Credential
access, record sharing, and the Data Cloud User permission set. Confirm by
invoking each action once as that user — the only check that covers CRUD,
FLS, and sharing together. This is the most common cause of "deploy
succeeded, agent broken."
- Observability. Session Tracing and the Session Tracing Data Model enabled
before activation, proven with synthetic traffic that appears in the trace
data. Alert rules fired at least once and receipt confirmed by the on-call
person.
- Rollback. Rehearsed in a Partial or Full sandbox with a recorded refresh
age. Capture the measured duration and the inventory of what did not
revert — Apex, custom fields, and activated prompt templates stay at the new
version.
- Sign-off. Business owner, security, and SRE lookups populated on
Agent_Activation__c, with a validation rule that blocks save when any gate
result is null.
Key Considerations
- The checklist is enforced by a validation rule on the activation record, not
by a document. A checklist that cannot block is a memory aid, and memory aids
fail under exactly the pressure that makes the rows matter.
- Rollback reverts the agent and nothing that shipped with it. Prefer additive
action changes so the rollback surface stays one artefact wide.
- Retaining the prior version is the rollback plan, because a committed
version cannot be edited. Retire old versions on a date, not on instinct.
- Sign-off must be queryable, immutable, and linked to a specific version. Chat
is none of the three.
Worked Examples (see references/examples.md)
- Rollback rehearsal — Agent v2 activation.
- Stakeholder sign-off record — Quarterly audit.
Common Gotchas (see references/gotchas.md)
- Staging differs from prod — Rehearsal green, prod rollback fails.
- Alert rules not enabled until after go-live — First incident is observed by a customer.
- Sign-off via Slack, no record — Post-mortem cannot reconstruct the decision chain.
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
- Verbal sign-offs.
- Skipping rollback rehearsal because 'the change is small'.
- Dashboards deployed post-activation.
Official Sources Used
1---2name: agent-deployment-checklist3description: "Canonical go-live checklist for Agentforce deployments with rehearsed rollback and stakeholder sign-off records. NOT for the technical pre-prod verification behind those sign-off rows — cost telemetry, rate limits, canary rollout, latency benchmarks — use agentforce/agentforce-production-readiness-checklist. NOT for general Salesforce release management — use devops/release-management."4category: agentforce5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Reliability9triggers:10 - "is my agent ready for production"11 - "agentforce go-live checklist"12 - "what sign-offs does agent deploy need"13 - "agent rollback rehearsal"14tags:15 - agentforce16 - deployment17 - checklist18 - go-live19inputs:20 - "Agent configuration export"21 - "test results"22 - "runbooks"23outputs:24 - "Signed checklist"25 - "activation record"26dependencies: []27version: 1.0.128author: Pranav Nagrecha29updated: 2026-08-1430metadata:31 source: https://skillmd.com/skills/pranavnagrecha/agent-deployment-checklist32---3334# Agent Deployment Checklist3536A single checklist is the artifact that prevents post-deployment incidents. Organized into five blocks: functional tests green, adversarial tests green, observability live, rollback rehearsed, stakeholders signed-off.3738## Adoption Signals3940Every production activation; every material config change (new Invocable, new channel, new persona). Use this skill any time someone asks whether the agent is ready for production.4142- Required for any change that adds a new tool to the agent's toolbox or expands record-access scope.43- Run before enabling a new channel (Service Cloud, Slack, Experience Cloud) — channel context changes the prompt-injection threat model.4445## What Makes Agent Deployment Different4647Three platform behaviours, none of which apply to an ordinary Salesforce48release, and all of which are documented in49[Retrieve and Deploy Agent Metadata](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-dx-deploy-metadata.html):50511. **A committed agent cannot be edited.** *"You can't edit a committed agent.52 Instead, create and edit a new version."* There is no quick-fix path — a53 hotfix costs a full release cycle, so plan the incident response accordingly.542. **Two version counters must be paired by hand.** Saves increment55 `AiAuthoringBundle`; commits increment `Bot`/`BotVersion`. If you save more56 than you commit they diverge and you must specify both numbers explicitly.573. **Observability is not retroactive.** Session Tracing records only58 conversations occurring after the data model is set up, so it is a59 pre-activation prerequisite rather than an incident response.6061Also: the manifest needs **API version 66.0 or later** for `GenAiPlannerBundle`62and the new agent metadata types — sourced from63[The New Agentforce Metadata and Development Lifecycle](https://developer.salesforce.com/blogs/2025/03/the-new-agentforce-metadata-and-development-lifecycle),64not from the *Retrieve and Deploy Agent Metadata* guide page cited above, whose65own example shows `<version>65.0</version>`. Wildcards on `ApexClass`/`Flows`/66`GenAiPromptTemplates` cause deploy timeouts, deploying a lone `BotVersion`67requires the full agent to be present already, and retrieved agent metadata must68not be hand-edited.6970## Recommended Workflow71721. **Functional.** `sf agent test run --wait` green on the routing, golden, and73 adversarial `AiEvaluationDefinition` suites. Record the run id on the74 activation record.752. **Security.** Adversarial suite green; PII classification register reviewed76 against the *channel set this activation covers*. A channel is part of the77 approved condition, not a later configuration tweak.783. **Runtime user.** Verify the agent user in the target org for Apex class79 access, object CRUD, **field-level** access, Flow and Named Credential80 access, record sharing, and the Data Cloud User permission set. Confirm by81 invoking each action once as that user — the only check that covers CRUD,82 FLS, and sharing together. This is the most common cause of "deploy83 succeeded, agent broken."844. **Observability.** Session Tracing and the Session Tracing Data Model enabled85 *before* activation, proven with synthetic traffic that appears in the trace86 data. Alert rules fired at least once and receipt confirmed by the on-call87 person.885. **Rollback.** Rehearsed in a Partial or Full sandbox with a recorded refresh89 age. Capture the measured duration **and** the inventory of what did *not*90 revert — Apex, custom fields, and activated prompt templates stay at the new91 version.926. **Sign-off.** Business owner, security, and SRE lookups populated on93 `Agent_Activation__c`, with a validation rule that blocks save when any gate94 result is null.9596## Key Considerations9798- The checklist is enforced by a validation rule on the activation record, not99 by a document. A checklist that cannot block is a memory aid, and memory aids100 fail under exactly the pressure that makes the rows matter.101- Rollback reverts the agent and nothing that shipped with it. Prefer additive102 action changes so the rollback surface stays one artefact wide.103- Retaining the prior version *is* the rollback plan, because a committed104 version cannot be edited. Retire old versions on a date, not on instinct.105- Sign-off must be queryable, immutable, and linked to a specific version. Chat106 is none of the three.107108## Worked Examples (see `references/examples.md`)109110- *Rollback rehearsal* — Agent v2 activation.111- *Stakeholder sign-off record* — Quarterly audit.112113## Common Gotchas (see `references/gotchas.md`)114115- **Staging differs from prod** — Rehearsal green, prod rollback fails.116- **Alert rules not enabled until after go-live** — First incident is observed by a customer.117- **Sign-off via Slack, no record** — Post-mortem cannot reconstruct the decision chain.118119## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)120121- Verbal sign-offs.122- Skipping rollback rehearsal because 'the change is small'.123- Dashboards deployed post-activation.124125## Official Sources Used126127- Retrieve and Deploy Agent Metadata — https://developer.salesforce.com/docs/ai/agentforce/guide/agent-dx-deploy-metadata.html128- Agentforce Metadata Types — https://developer.salesforce.com/docs/ai/agentforce/references/agents-metadata-tooling/agents-metadata.html129- Manage an Agent (Agentforce DX) — https://developer.salesforce.com/docs/ai/agentforce/guide/agent-dx-manage.html130- Set Up Agentforce Session Tracing — https://help.salesforce.com/s/articleView?id=ai.generative_ai_session_trace_setup.htm&type=5131- Run Agent Tests (Agentforce DX) — https://developer.salesforce.com/docs/ai/agentforce/guide/agent-dx-test-run.html132- Agentforce Testing Center — https://help.salesforce.com/s/articleView?id=ai.agent_testing_center.htm&type=5