Use Metadata to Move an Agent to a New Org

After you’ve created an agent in an org, you can move the agent to another org by retrieving and deploying its metadata. For example, to move an agent from a sandbox org to a production org, first retrieve the agent’s metadata from the sandbox org to your local machine. Then, deploy the agent’s metadata to the production org.

Agent metadata is updated in API v68. To use these metadata types to move agents between orgs, both orgs must be in API v68. While your sandbox org is in Winter ʼ27 and your production org is in Summer ʼ26, continue to use the previous metadata types. See Define Agent Metadata (v67 and Earlier).

Important

This document uses Salesforce CLI commands to retrieve and deploy the agent’s metadata. To use VS Code, see Salesforce Extensions for VS Code.

You can download this metadata deployment documentation to help your coding agents or deployment tools deploy Agentforce agents. See Download Agent Script Documentation.

Tip

Step 1: Set Up Your Local Development Environment

Install Salesforce CLI or run sf update to install the latest version.

You need the latest version of Salesforce CLI to retrieve and deploy the latest version of Salesforce metadata.

Important

Authorize your source and target orgs by using Salesforce CLI:

1sf org login web --alias <org alias>

When the login window appears, log in to your org and click Allow.

Ensure you’ve enabled Einstein and Agentforce in your source and target orgs.
Ensure that you have the required permissions to publish and preview an agent in your source and target orgs.

Step 2: Create a Salesforce DX project

Create a Salesforce DX project to define your package.xml manifest and contain the retrieved metadata. First, change to the directory where you want to store the project. Then, use sf template generate project.

In this example, we use the standard project template because we don’t need an example agent. We also use --manifest to create a sample package.xml file, which contains example metadata.

1sf template generate project --name <name> --template standard --manifest

A Salesforce DX project is created on your local machine in the <project name> directory; the project contains an example package.xml manifest file.

Step 3: Define Metadata in the Manifest File (v68 and Later)

Agent metadata is updated in API v68. To define an agent using API v67 and earlier, see Define Agent Metadata (v67 and Earlier).

Important

Create a manifest to define the metadata you want to retrieve. You can copy and edit the default manifest that was created in your project at manifest/package.xml:

Use #<number> to specify a specific agent version version
Use #* to specify all agent versions

Version to Specify	Example
Version 2 of MyAgent	`MyAgent#2`
All versions of MyAgent	`MyAgent#*`
All versions of ALL agents	`*`

The system automatically retrieves your agent’s flow, Apex, and prompt template actions, so you don’t need to define your agent’s actions. Add any other metadata types that your agent needs, such as Data 360 dependencies or custom objects.

The first time you deploy an agent in your target org, you must include the whole agent definition and not just a specific version.

Important

Example: Specify all Versions of MyServiceAgent

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    <version>68.0</version>
11</Package>

Example: Specify Version 2 and 3 of MyServiceAgent

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#2</members>
8        <members>MyServiceAgent#3</members>
9        <name>AiAgentDefinitionVersion</name>
10    </types>
11    <version>68.0</version>
12</Package>

Step 4: Retrieve Agent Metadata

After defining the metadata in your project’s manifest (for example, package.xml), retrieve the agent’s metadata to your local machine. Use the org’s alias that you configured when authorizing your org.

1sf project retrieve start --manifest manifest/package.xml --target-org <org alias>

Step 5: (Optional) Update Your Draft Agent's Username

Your retrieved metadata contains the agent username(s) from the source org. To enable your draft agent to run out-of-the-box on the target org, you can use string replacement to update the username with a target org’s username. Agents run in the context of a user, and the usernames on your source and target orgs are different. You can’t use string replacement to update a committed agent’s username, because committed agents can’t be edited.

Don’t modify any other agent metadata that you retrieved. Uploading edited metadata to an org can corrupt your org.

Important

If you deploy a draft agent to your target org without replacing the username, you’ll need to manually update the agent’s username before it can run on the target org.

See Example - Configure String Replacement for Agent Username.

Step 6: Deploy Agent Metadata to a New Org

Once you’ve retrieved your agent’s metadata to your local project, you can deploy the metadata to a new org.

Use the right deploy command for your project.

1sf project deploy start  --source-dir force-app --target-org my-target

Set the Agent User and Assign Permissions

Before using your agent in the new org, you must assign the agent user. If you didn’t configure the agent’s user during deployment, manually configure the agent’s user.

You can’t edit a committed agent. To add an agent user to a committed agent, first create a new agent version. Then, add the user to the new version.

After you’ve deployed an agent on your target org, the agents in both your source and target orgs must match or future deployments will be blocked. If you create a new version in your target org, create a corresponding version in your source org.

Tip

Ensure the agent user has sufficient permissions to carry out the agent’s tasks. For example, if the agent reads a custom contact field, the agent user must have view permission on the custom field.

To learn more about agent users, see create or assign the default agent user.