Study guide

8.1 Deploying an Agent from Sandbox to Production

Salesforce Certified Agentforce Specialist Exam

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Exam Overview & How Agentforce Agents Work

1.1 Agentforce Specialist (AI-201) Exam Facts & Spring '26 Blueprint 1.2 How an Agent Works & the Building Blocks of Agent Script 1.3 Hybrid Reasoning: Agent Script in Canvas View and Script View

2 Chapter 2: Deterministic Control, Topics (Subagents) & Actions

2.1 Deterministic Behavior: Filters, Variables & Template Expressions 2.2 Standard and Custom Topics (Subagents) 2.3 Standard and Custom Agent Actions

3 Chapter 3: Agent Types, Security Context, Channels & Agent API

3.1 When to Use an Employee Agent or a Service Agent 3.2 Security Context: Who the Agent Runs As and How It Affects Actions 3.3 Connecting Agents to Channels: Digital Experiences, Email, Voice & Slack 3.4 When to Use the Agent API

4 Chapter 4: Prompt Builder Fundamentals

4.1 When to Use Prompt Builder 4.2 Access Controls Governing Prompt Templates 4.3 Prompt Template Types: Field Generation, Flex & More 4.4 Creating, Activating & Executing Prompt Templates

5 Chapter 5: Grounding, Prompt Best Practices, Trust Layer & Model Access

5.1 Choosing the Right Grounding Technique 5.2 Best Practices for Writing Effective Prompts 5.3 Einstein Trust Layer Security and Privacy Features 5.4 Managing and Preventing Access to Specific Models

6 Chapter 6: Data 360 Fundamentals for Agentforce

6.1 Agentforce Data Library: Types and Concepts 6.2 Chunking: Breaking Content Into Retrievable Units 6.3 Indexing and Search Types: Vector, Hybrid & Keyword 6.4 Retrievers: Individual, Ensemble & Filtered Retrieval

7 Chapter 7: Testing Agents with Testing Center

7.1 Testing an Agent with Testing Center 7.2 How Testing Center Evaluations Work

8 Chapter 8: Deploying Agents and Prompt Templates

8.1 Deploying an Agent from Sandbox to Production 8.2 Deploying Prompt Templates from Sandbox to Production

9 Chapter 9: Governance and Observability

9.1 Managing and Monitoring Agents 9.2 Agent Analytics and Agent Optimization

10 Chapter 10: Multi-Agent Orchestration, MCP & A2A

10.1 When a Multi-Agent Architecture Is Appropriate 10.2 Open Multi-Agent Protocols: MCP and A2A

8.1 Deploying an Agent from Sandbox to Production

Key Takeaways Explain This Topic AI

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.

Last updated: September 2026

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.xml manifest 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 as MyAgent#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 start command. 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.

Loading diagram... Sandbox-to-production agent deployment