How to Move a Copilot Studio Agent Between Environments

You may need to move a Copilot Studio agent from a development environment to a test or production environment. The export and import process transfers the agent definition, topics, entities, and settings without recreating the agent manually. This article explains the exact steps to export a Copilot Studio agent and import it into a target environment. It also covers common errors and limitations you will encounter during the transfer.

What the Export and Import Process Covers

Copilot Studio agents are stored inside Microsoft Dataverse environments. Each environment is an isolated database. Moving an agent between environments requires exporting the agent solution from the source environment and importing it into the target environment. The export captures the agent definition, all topics, entities, environment variable placeholders, and system settings. The import creates a new agent in the target environment with the same logical structure.

Export does not transfer actual environment variable values that contain secrets such as API keys or connection strings. You must manually enter these values in the target environment after import. The agent will not function correctly until the environment variables are populated with valid values. Also, any connector references that point to external services will need to be reconfigured in the target environment.

Before you start, confirm you have the System Customizer or System Administrator role in both the source and target environments. You also need access to the Copilot Studio app in both environments. The export and import operations are performed from the Copilot Studio interface, not from the Power Platform admin center.

Steps to Export a Copilot Studio Agent from the Source Environment

1. Open the agent in Copilot Studio
   Sign in to Copilot Studio at copilotstudio.microsoft.com. Switch to the source environment using the environment selector in the top-right corner. Open the agent you want to move.
2. Go to the Settings menu
   In the top navigation bar, click the gear icon labeled Settings. Do not click the ellipsis menu next to the agent name.
3. Select Export agent
   In the Settings pane, scroll to the Export section. Click Export agent. Copilot Studio prepares a solution package that contains the agent. This process may take a few seconds.
4. Download the .zip file
   When the export is complete, the browser downloads a .zip file. The file name follows the pattern AgentName_DateTime.zip. Do not rename or modify the .zip file contents. Keep the file in a secure location.

Steps to Import the Copilot Studio Agent into the Target Environment

1. Switch to the target environment
   In Copilot Studio, use the environment selector to switch to the target environment. Confirm the target environment is a Dataverse environment with the Copilot Studio license applied.
2. Open the Settings menu
   Click the gear icon in the top navigation bar. The Settings pane opens.
3. Select Import agent
   In the Settings pane, scroll to the Import section. Click Import agent. A file picker dialog opens.
4. Upload the exported .zip file
   Select the .zip file you downloaded in the export step. Click Open. Copilot Studio validates the package and begins the import. The import process may take several minutes depending on the agent complexity.
5. Configure environment variables
   After the import completes, the agent appears in the target environment. The agent will show a warning icon if environment variable values are missing. Open the agent and go to Settings > Environment variables. Enter the required values for each variable. For secrets, use Azure Key Vault references if available.
6. Publish the imported agent
   After configuring environment variables, publish the agent. Click Publish in the top navigation bar. The agent becomes available on the configured channels in the target environment.

Common Issues When Moving a Copilot Studio Agent

Import fails with a validation error about missing dependencies

This error occurs when the agent references custom connectors, Power Automate flows, or Dataverse tables that do not exist in the target environment. Before importing, ensure all dependent components are present in the target environment. Export and import the dependent solutions first, or recreate the missing components in the target environment.

Agent appears but does not respond to topics after import

The agent may be in a draft state or the environment variable values may be empty. Open the agent and verify the environment variables are populated. Then publish the agent. If the agent still does not respond, check the agent diagnostics in Copilot Studio for specific errors.

Connection references break after import

Connection references store authentication details for external services. These references are not transferred during export. After import, open each topic that uses a connection reference and reconfigure the connection. Use the same connector type and authentication method as the source environment.

Agent uses a different language or locale after import

The language and locale settings are part of the agent definition and are transferred during export. If the target environment has different default language settings, the agent retains its original language. To change the language, edit the agent settings after import.

Item	Export/Import Behavior	Manual Reconfiguration Needed
Agent definition and topics	Transferred completely	No
Environment variable placeholders	Transferred as empty placeholders	Yes — enter actual values
Environment variable secrets	Not transferred	Yes — enter new secrets
Connection references	Transferred but not authenticated	Yes — reconfigure each connection
Custom connectors	Not transferred	Yes — export and import separately
Power Automate flows	Not transferred	Yes — export and import separately
Dataverse table customizations	Not transferred	Yes — export and import separately

The export and import process moves the agent logic, but external dependencies remain in the source environment. Plan your environment migration by exporting all dependent solutions before moving the agent. After import, always test the agent in the target environment before routing real user traffic to it.

You can now move a Copilot Studio agent between environments using the built-in export and import functions. Next, review the environment variable values and connection references to ensure the agent functions correctly in the target environment. For advanced scenarios, consider using Azure DevOps pipelines to automate the export and import process for continuous integration and deployment.