Use Metadata to Move an Agent to a New Org

After you've created an agent in an org, either by using the Agentforce UI or Agentforce DX, 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.

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

1. Install Salesforce CLI.

   To test your setup, run sf search and see the list of CLI commands.

2. Authorize your source and target orgs by using Salesforce CLI:

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

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

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.

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

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.

• Draft (uncommitted) agents and agent versions are represented by AiAuthoringBundle. A draft agent is editable until it's committed.
• Committed agents and agent versions are represented by AiAuthoringBundle, plus Bot and BotVersion. A committed agent can't be changed; to change a committed agent, create a new version.
• Legacy agents don't have a commit stage, and are represented by Bot and BotVersion (not AiAuthoringBundle). You can edit and overwrite an active legacy agent.

For more details, see Agent Metadata: A Shallow Dive and Agentforce Metadata Types.

Use these examples to get started:

• Replace the version number (for example, <version>65.0</version>) with your required metadata version. Your project's sample package.xml manifest contains the most recent version number.
• Add any other metadata types that your agent needs, such as Data 360 dependencies.

To define a single agent version, make these changes to your manifest.

1. Instead of Bot, which is the top-level representation of an agent, use BotVersion, which represents the configuration for a specific agent version. Include the agent version's name and version number. For example:

2. Instead of using the agent's name to specify AiAuthoringBundle and GenAiPlannerBundle, use the agent's versioned name. For example:

Use these steps to specify the correct versions for your agent's metadata.

When you save an agent version, Agentforce creates AiAuthoringBundle metadata. When you commit an agent version, Agentforce creates Bot/BotVersion metadata. If you save more versions than you commit, the version of your AiAuthoringBundle won't match the version of your Bot/BotVersion.

For example, this agent has 11 versions of an agent and 7 committed version. Therefore, the agent's metadata contains 11 versions of AiAuthoringBundle and 7 versions of Bot and BotVersion. You'll need to specify the correct version numbers to match the correct AiAuthoringBundle to the correct Bot and BotVersion.

To find the matching Bot version, open the AiAuthoringBundle folder for your desired version. In the agent version's bundle-meta.xml file, the target metadata shows the version to use for the GenAiPlannerBundle and BotVersion.

For example, version 9 of the agent "TestAgentFromSource" uses version 7 of GenAiPlannerBundle and BotVersion.

Use these versions to specify your manifest, for example Manifest for Different Bot/AiAuthoringBundle Versions

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.

For more information about retrieving and deploying metadata, see Basic Retrieval and Deployment of Metadata: A Refresher.

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. For example, to deploy all source files in your project's force-app directory to an org with alias my-target:

Before using your agent in the new org, you must create or assign the default agent user.

Then, 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.