8.1 Deploying an Agent from Sandbox to Production
Key Takeaways
- New Agentforce Builder agents use AiAuthoringBundle metadata for Agent Script, with Bot, BotVersion, and GenAiPlannerBundle created when a version is committed.
- Agent retrieval automatically includes flow, Apex, and prompt template actions, but other dependencies such as custom objects and Data 360 assets must be added to the manifest.
- The first deployment to a target org must include the whole agent definition, and later deployments are blocked unless source and target agent versions match.
- Agents run as a user, so the agent username must be replaced or assigned in the target org, and committed agents need a new version to change it.
- Data library changes can't be deployed from a sandbox, and MCP server registrations aren't packaged, so recreate or re-register them in the target org.
8.1 Deploying an Agent from Sandbox to Production
Quick Answer: Build and test agents in a sandbox, then move them as metadata: retrieve with a
package.xmlmanifest and deploy with Salesforce CLI / Agentforce DX, VS Code, DevOps Center, or a partner DevOps tool. Include dependencies, set the agent user for the target org, respect version matching and committed-version rules, and plan to recreate what doesn't deploy: data libraries, MCP server registrations, channel setup, and some Data 360 assets. Then test, commit, and activate in production.
Why Deploy Instead of Rebuilding
Rebuilding an agent by hand in production is error-prone and skips testing evidence. Treating agents as metadata gives you version control, code review, repeatable CI/CD, and the same configuration you validated in Testing Center.
Agent Metadata Types
| Metadata type | What it represents | Builder |
|---|---|---|
| AiAuthoringBundle | Design-time artifacts: the .agent Agent Script file plus a bundle descriptor, stored per version (for example AgentName_1, AgentName_2) | New Agentforce Builder only |
| Bot | Information common to all versions, such as agent type, settings like private-data logging, and agent-level context variables | Both |
| BotVersion | Version details, such as conversation variables, welcome message, and transfer message | Both |
| GenAiPlannerBundle | All data for each published (committed) version. In the new builder it bundles local subagents and actions, input and output schemas, and the agent graph and script | Both (replaced GenAiPlanner from API v64) |
| GenAiPlugin / GenAiFunction | Topics (subagents) and actions as separate metadata | Mainly legacy builder agents |
| GenAiPromptTemplate | Prompt templates used by actions | Both |
| AiEvaluationDefinition | Testing Center test definitions | Both |
Key points from Salesforce's metadata guidance:
- In the new builder, Bot and GenAiPlannerBundle are created automatically when a version is committed. AiAuthoringBundle, the agent script, and the agent graph exist only for new-builder agents.
- GenAiPlannerBundle versions auto-increment in commit order, so they don't necessarily match AiAuthoringBundle version numbers.
- The new bundled structure puts all version-specific local assets in one folder, which prevents missing-dependency errors.
- Metadata types evolve with API versions. Salesforce notes that the newest agent metadata requires both orgs on the same supported API version. While one org is a release ahead, keep using the previous types.
The Retrieve-and-Deploy Workflow
- Update Salesforce CLI and authorize both orgs.
- Create a Salesforce DX project with a manifest.
- Define the agent in
package.xml. Specify versions such asMyAgent#2(version 2),MyAgent#*(all versions), or*(all agents). - Retrieve. Salesforce automatically retrieves the agent's flow, Apex, and prompt template actions. Add other metadata the agent needs, such as custom objects and Data 360 dependencies.
- Handle the agent user. Retrieved metadata contains source-org usernames. Use string replacement to substitute the target org's agent username for draft agents. You can't do this for committed agents, because they can't be edited.
- Deploy with the appropriate
sf project deploy startcommand. The first deployment must include the whole agent definition, not just one version. - Configure in the target org: assign the agent user if it wasn't set during deployment, grant it permissions, and connect channels.
- Test, commit if needed, and activate.
For Agent Script-first development, Agentforce DX also offers commands such as sf agent publish authoring-bundle (creates the underlying agent metadata in an org) and sf agent activate.
Rules That Cause Deployment Failures
| Rule | Consequence |
|---|---|
| Agents in source and target must match after the first deployment | If you create a new version in the target, create the corresponding version in the source, or future deployments are blocked |
| Committed agents can't be edited | To add or change the agent user on a committed agent, create a new version first |
| Draft agents deployed without username replacement | You must manually update the agent's username before it can run |
| Don't hand-edit other retrieved agent metadata | Salesforce warns that uploading edited metadata can corrupt your org |
| Agent user permissions | The target agent user needs every permission the agent's actions require, such as FLS on a custom contact field |
| Target org readiness | Einstein and Agentforce must be enabled, and Data 360 must be set up if the agent depends on it |
What Doesn't Move with Agent Metadata
| Asset | What to do |
|---|---|
| Agentforce Data Library | Deploying library changes from a sandbox isn't supported. Recreate the library in the target org. Files aren't copied into sandboxes either |
| Data 360 search indexes and retrievers | Use data kits or recreate them. They aren't included with prompt template deployments |
| MCP server registrations | Registration metadata isn't packaged. Before deploying, register the MCP servers in the target org and allowlist the tools. After deploying, replace the MCP tool actions in the agent with the new ones from the asset library |
| Agent user record | Users aren't metadata. Create or select the agent user in the target org (for example with sf org create agent-user) and assign permission sets |
| Channel configuration | Set up Enhanced Chat deployments, messaging channels, email configurations, telephony, and Omni-Channel flow activation in the target org as needed |
| Permission set assignments | Assign permission sets to users in the target org |
Deployment Readiness Checklist
- Testing Center suites pass in the sandbox (default, quality, and custom scorers)
- Manifest includes the agent plus custom objects, fields, and Data 360 dependencies
- Prompt templates are active in source, and the plan covers activation in target (section 8.2)
- Flows referenced by actions will be active in target
- Target agent user exists with least-privilege permissions
- Data libraries, retrievers, and MCP registrations exist in target
- Channels and Omni-Channel flows are configured
- Rollback plan: keep the previous committed version so you can reactivate it
Scenario
An agent passes testing in a Developer Pro sandbox. The team retrieves ServiceAgent#3 and deploys to production. The deploy succeeds, but the agent can't run. Likely causes, in order:
- The agent username still points to the sandbox user. For a draft, replace it; for a committed version, create a new version with the correct user.
- The production agent user lacks permissions for a custom object the flow updates.
- The agent's data library doesn't exist in production, because libraries aren't deployable from sandboxes.
Exam Traps
- Flow, Apex, and prompt template actions retrieve with the agent, but custom objects and Data 360 dependencies need explicit manifest entries.
- Version mismatch blocks future deployments.
- MCP tool actions don't work out of the box after deployment until servers are registered and actions replaced.
- You can't deploy a data library from a sandbox.
An architect retrieves a committed agent version from a sandbox and deploys it to production, but the agent can't run because its agent username references a sandbox user. How should this be fixed?
When retrieving an agent's metadata with a package.xml manifest, which dependencies does Salesforce retrieve automatically?
After the first deployment, an admin creates a new agent version directly in production. What problem does Salesforce warn about?
An agent uses MCP tool actions registered in the sandbox. What must happen for those actions to work after deployment to production?