Open an existing Copilot Studio agent for local development (preview)

[This article is prerelease documentation and is subject to change.]

Open an existing Copilot Studio agent for local development by cloning it from the cloud or registering a definition that's already on your machine. This article explains how to choose between a cloud clone, a Git clone, and local registration, and how to verify the result before deployment.

Choose the correct starting path for your agent

Starting point Action Result Example commands (abbreviated)
Cloud agent exists. Clone it into an empty workspace. Downloaded content, cloud tracking, synchronization baseline, and a generated develop deployment. msagent agent create --mcs-clone-agent-id '<agent-id>' ...
Definition exists in Git. Clone the repository, then register the definition. Local registration; a clean checkout without synchronization state is disconnected. git clone <repository-url>, then msagent agent init --mcs-agent-source '<workspace-path>' ...
Definition exists locally. Register its existing workspace. Local registration; a valid existing workspace baseline can supply its connection. msagent agent init --mcs-agent-source '<workspace-path>' ...
No agent exists. Create a new agent. Local definition; cloud creation happens at deployment. msagent agent create --agent-type MCSAgent ...

Clone from Copilot Studio

  1. Find the source environment with environment list, then discover its cloud agents with agent list:

    msagent env list
    msagent agent list --environment-id '<source-environment-id>' --limit 50
    

    Check the environment and cloud ID, not only the display name.

  2. Clone into a new, empty project using agent create:

    msagent agent create --agent-type MCSAgent `
      --mcs-clone-agent-id '<source-cloud-agent-id>' `
      --mcs-clone-environment-id '<source-environment-id>' `
      --project 'C:\AgentProjects\ConnectedVisitorGuide'
    

    Alternatively, replace the ID selector with --mcs-clone-agent-schemaname '<source-schema-name>'; don't supply both selectors. Clone inherits the source name unless you supply --agent-name. It doesn't accept a new --schema-name.

  3. Inspect agent show, deployment list, and deployment show:

    msagent agent show --project 'C:\AgentProjects\ConnectedVisitorGuide'
    msagent deployment list --project 'C:\AgentProjects\ConnectedVisitorGuide'
    msagent deployment show --project 'C:\AgentProjects\ConnectedVisitorGuide' `
      --agent-name '<inherited-agent-name>' --deployment-name develop
    
  4. Inspect the downloaded definition and generated .mcs tracking in the editor. Compare the reported source environment and agent with Copilot Studio.

Important

A same-environment cloud clone remains associated with the source cloud agent. Renaming its local display name doesn't create an independent cloud copy. Deployment can update that source. For an independent target, use a deliberately chosen deployment environment and review creation/adoption behavior in deploy an agent.

Note

Support for forking an existing agent with the CLI is planned for a future release. Stay up to date through the CLI GitHub repository.

Register a definition already on disk

  1. Inspect the definition's README and authoring shape. For an agent, the source directory must hold exactly one unregistered workspace with a readable schema identity.

    For example, a source directory for a CLI-scaffolded agent might look like this:

    C:\AgentProjects\VisitorGuide\
      README.md
      visitor-guide\
        agent.sync.yaml
        settings.mcs.yml
    

    In this example, visitor-guide is the single agent workspace. Its settings.mcs.yml contains the agent's schema identity and settings. The README describes the project; the workspace folder name can vary.

  2. With the intended environment selected, use agent init:

    msagent agent init --agent-name 'Visitor Guide' `
      --mcs-agent-source 'C:\AgentProjects\VisitorGuide'
    
  3. Inspect agent show and deployment list, using the project root that registration reports:

    msagent agent show --project 'C:\AgentProjects\VisitorGuide'
    msagent deployment list --project 'C:\AgentProjects\VisitorGuide'
    

Registering the definition lets the CLI work with the files on your machine. It doesn't create or deploy an agent in Copilot Studio. Add the .mcs folder to your repository's .gitignore so that local connection information isn't committed. Files cloned from Git usually don't include the .mcs connection information, so registration alone doesn't reconnect them to an existing cloud agent.

To deploy to a new target, create a deployment. To update an existing Copilot Studio agent, clone that agent into a separate empty workspace, then bring your changes from Git into that connected workspace. Keep connection information local—don't copy another developer's .config or .mcs folders.

Next steps