Deploy an Agentforce Agent from Sandbox to Production

Hey there,

To move an Agentforce agent from sandbox to production, retrieve its metadata from the sandbox with Salesforce CLI, then deploy it to production. In API v68, the --root-type-with-dependencies AiAgentDefinitionVersion flag brings the agent’s flow, Apex, and prompt template actions along for you.

That’s the happy path from Salesforce’s Move an Agent to a New Org guide. The trickier parts come after the deploy, so that’s where I spend most of this post.

Can both my orgs use the v68 method?

Only if both are on API v68. The guide says that while your sandbox is on Winter ’27 (v68) and production is still on Summer ’26 (v67), you keep using the previous metadata types.

So check both orgs first. It’s a quick check before you start.

You also need Einstein and Agentforce enabled in both orgs, and permission to publish and preview agents in each.

What does production need before the agent arrives?

An agent user. Salesforce Help’s Agentforce deployment best practices article says to create a user with the Einstein Agent license and the Einstein Agent User profile.

And if your target is a sandbox rather than production, Help says Data Cloud in Sandboxes must be enabled in production.

How do I set up the CLI project?

Update the CLI, log in to both orgs, and create a project with a sample manifest. The guide notes that you need the latest CLI to retrieve and deploy the latest metadata.

1sf update
2sf org login web --alias sandbox
3sf org login web --alias prod
4sf template generate project --name agent-move --template standard --manifest

What goes in package.xml?

Here’s Salesforce’s example manifest for all versions of an agent, with its XML comments removed:

1<Package xmlns="http://soap.sforce.com/2006/04/metadata">
2    <types>
3        <members>MyServiceAgent</members>
4        <name>AiAgentDefinition</name>
5    </types>
6    <types>
7        <members>MyServiceAgent#*</members>
8        <name>AiAgentDefinitionVersion</name>
9    </types>
10    <types>
11        <members>MyServiceAgent</members>
12        <name>AiAuthoringBundle</name>
13    </types>
14    <version>68.0</version>
15</Package>

The rules, straight from the guide:

• AiAgentDefinition must already exist in the target org or be in the same deploy.
• Include at least one AiAgentDefinitionVersion. Use MyAgent#2 for one version or MyAgent#* for all.
• Agents built with Agent Script must include their AiAuthoringBundle.
• Don’t deploy a version in the same package as its matching legacy BotVersion.

Here’s the easy one to miss: you don’t list the flows, Apex, or prompt templates, but you do list custom objects and fields the agent uses. The dependency flag only covers the actions.

How do I retrieve and deploy?

Retrieve from the sandbox:

1sf project retrieve start --manifest manifest/package.xml --root-type-with-dependencies AiAgentDefinitionVersion --target-org sandbox

Then deploy to production:

1sf project deploy start --manifest manifest/package.xml --root-type-with-dependencies AiAgentDefinitionVersion --target-org prod

One optional step in between. The retrieved files contain the sandbox agent user’s username. For a draft agent, you can use string replacement to swap in the production username. You can’t do it for a committed agent, because committed agents can’t be edited.

And don’t touch anything else in those files. The guide warns that deploying edited agent metadata can corrupt your org.

What do I do after the deploy?

This is the checklist I’d keep open in another tab:

• Set the agent user. For a committed agent, create a new version first, then add the user to it.
• Check permissions. The agent user needs access to whatever its actions touch. The guide’s example: if it reads a custom contact field, it needs view permission on that field.
• Add the permission sets. Help says to give the target org’s agent user the permission sets deployed from the source org.
• Fix flow references. Help says the deployed agent gets a new ID, so flows that reference it, like inbound Omni-Channel flows, need updating.
• Activate. Activate the agent and make sure deployed flows have the right version active.
• Republish web chat. If you use it, Help says to publish your Embedded Service web deployment.

Why are my later deploys blocked?

The documented cause: the agents in the two orgs no longer match. The guide says the agents in both orgs must match after a deploy, or future deployments are blocked.

If you create a new version in production, create a matching version in the sandbox. (Or better, make changes in the sandbox and deploy them.)

Is this on the Agentforce Specialist exam?

Yes. The exam guide has objectives on the considerations for deploying an agent, and a template, from sandbox to production. Testing, Deployment, and Maintenance is 10% of the exam.

More reading: Agentforce permissions setup, the Agentforce Builder walkthrough, and the Salesforce certification study guides.

And that’s a wrap: retrieve, deploy, then work the after-deploy list top to bottom.

Hope this helps!

Best,

Nick