Share via

Clone your Microsoft Copilot Studio agent in Microsoft Visual Studio Code

When you clone an agent from Microsoft Copilot Studio using the extension, you download the agent definition and related component definitions from Copilot Studio to your local machine. You can edit these files by using Microsoft Visual Studio Code. The clone operation creates a local workspace with all agent files in a structured directory format.

Prerequisites

Before you get started cloning agents, there are some important prerequisites and considerations.

Choose a workspace location

Select an appropriate local folder for your agent files. This location is where the extension saves the agent files. Here are some important tips for choosing a location:

  • Ensure adequate disk space. A typical agent can range in size depending on the number of components.
  • Use a path without spaces if possible, though spaces are supported.
  • Consider using a location that's already tracked by Git.

Understand what gets cloned

When you clone an agent, the agent files are cloned locally in the location you choose, creating a structure definition like the following in the Visual Studio Code Explorer:

my-agent/
├── actions                   # Connectors
│   ├── DevOpsAction.mcs.yml  
│   └── GetItems.mcs.yml      
├── knowledge/files                # Knowledge sources
│   ├── source1.yaml
│   └── source2.yaml
├── topics/                   # Conversation topics
│   ├── greeting.mcs.yaml
│   ├── help.mcs.yaml
│   └── escalate.mcs.yaml
├── workflows/                    # Agent tools and actions
│   └── GetDevOpsItems
│       ├── metadata.yaml
│       └── workflow.json
│   └── GetMeetings
│       ├── metadata.yaml
│       └── workflow.json
├── trigger/                 # Event triggers
│   └── welcometrigger.mcs.yaml
├── agent.mcs.yaml                # Main agent definition
├── icon.png                      # Icon used for the agent, visible in test panel and in supported channels
├── settings.mcs.yml              # Configuration settings for the agent
└── connectioreferences.mcs.yml   # Connection References used by Connectors and other actions

Cloning methods

If you're using the extension for the first time, or even new to Visual Studio Code, the easiest way to clone an agent is to select Clone Agent when the Extension pane is open. However, this option isn't available when you already have an Agent cloned and open locally. The following methods can be used instead:

This is the most straightforward and recommended method to clone an agent.

  1. Open the Copilot Studio extension by selecting the Copilot Studio icon in the activity bar. You can also press Ctrl+Shift+P and enter "Copilot Studio: Focus on Agents View." The Copilot Studio pane opens in the sidebar.

  2. In the Agents pane, select your target environment from the dropdown list (for example, "Environment 1") to see a list of the agents in the environment.

    > Environment 1
  Environment 2
  Environment 3

  3. Select the agent to clone from the list. Agents display their last modified date. Right click on the agent name and select Clone agent.

    > Customer Support Agent
    HR Assistant
    Sales Agent
    IT Helpdesk Agent

    A file picker dialog opens.

  4. Navigate to your desired location in the file picker dialog or create a new folder and select Select Folder. The cloning process begins.

  5. Wait for the cloning process to complete. A progress notification appears displaying "Cloning agent: Customer Support Bot," followed by a success message "Agent Cloned successfully." This process usually takes 10-30 seconds.

  6. Verify that the cloning completed successfully. The agent folder opens in Visual Studio Code explorer, the source control pane shows a clean working tree, and the file window displays the name of your folder.

Method 3: Clone using the command palette

Use this method if you prefer keyboard-focused workflows.

  1. Open the command palette by pressing Ctrl+Shift+P.

  2. Type "Copilot Studio: Clone Agent" and press Enter. The command executes and prompts appear.

  3. Follow the prompts to select your environment, select the agent, choose the destination folder, and wait for the cloning to complete. The agent is cloned to your selected location.

Method 3: Clone using agent URL

This method is useful when someone shares an agent URL with you.

  1. Open your agent in the Copilot Studio web portal.

  2. Select Settings > Agent details, and copy the agent URL. The URL should have the format: https://copilotstudio.microsoft.com/environments/{guid}/bots/{guid}. The URL is now in your clipboard.

  3. Return to Visual Studio Code and open the Copilot Studio extension.

  4. Select Clone agent. The extension detects the URL in your clipboard and displays the agent marked as "(from clipboard)."

  5. Select the agent marked "(from clipboard)," select a destination folder, and wait for the cloning to complete. The agent is cloned to your selected location.

Common cloning scenarios

Here are a few common scenarios for when cloning agents is useful, with high-level details on the suggested workflow.

Scenario 1: Clone for solo development

Goal: Work on an agent by yourself

  1. Clone the agent to a local folder.

  2. Initialize a Git repository from Source Control in the navigation.

  3. Make changes locally.

  4. Make your commits.

  5. Apply the changes to Copilot Studio when ready.

Scenario 2: Clone for team collaboration

Goal: Multiple developers working on same agent

  1. The first developer clones the agent.

  2. The first developer initializes Git and pushes the content to a shared repository (GitHub, Azure DevOps).

  3. Other developers clone from the shared Git repository.

  4. Each developer runs Copilot Studio: Reattach Agent to connect their local folder to Copilot Studio.

  5. The team uses Git for collaboration and track changes, and uses the Visual Studio Code extension to work on the agent.

  6. Each developer then applies changes to Copilot Studio for testing or pushes to another downstream environment based on their software development lifecycle or automated pipelines.

Scenario 3: Clone multiple environments

Goal: Manage development, test, and production versions

The recommended approach for deployment with multiple environments is to use solutions. Consider an automated deployment process with organizational processes that are auditable and scalable, such as pipelines. For users who choose not to work with solutions, the Copilot Studio extension provides the capability to synchronize a Copilot Studio agent definition from a local machine to another environment. You should still consider the organizational process for moving technical assets to downstream environments to provide auditing, telemetry, and other critical components within the software development lifecycle when shipping software for your customers and end users.

  1. Clone the agent from the development environment to a local development folder.

  2. Make changes in the development folder.

  3. Apply those changes and test the changes in the same environment.

  4. Use Copilot Studio: Reattach Agent to connect the agent to the alternative environment.

  5. Test the agent in the Copilot Studio test pane.

Best practices

Do

  • Clone all agents to a consistent location.
  • Initialize Git right after cloning.
  • Use a meaningful folder name.
  • Check that the clone works before making changes.
  • Keep your clone location backed up (for example, in GitHub or Azure DevOps).
  • Document your clone location in your internal team wiki or docs.

Don't

  • Don't clone to temporary directories.
  • Don't clone multiple times to different locations. Doing so can cause confusion.

Next steps

After you clone your agent:

  • Last updated on