How to Create a Solution in Copilot Studio (Step-by-Step)

Last spring, I built a procurement agent for a 500-person manufacturing company. Employees could use it to submit purchase requests, check order status, and find the right supplier. In my dev environment, it worked beautifully.

Then the procurement manager asked, “So when can we roll this out?”

That’s when it hit me: the agent wasn’t built inside a custom solution. It was sitting in the default solution, tangled up with dozens of unrelated components. Its flows pointed to a test SharePoint site. A spending limit was hard-coded into three separate topics. Moving it to production would have meant rebuilding half the project.

I see this on client projects all the time, and it’s an easy mistake to make. The fix is to build your agent in a proper solution in Copilot Studio.

In this guide, I’ll walk you through exactly how I set it up:

• Creating a publisher
• Building the agent inside the solution
• Adding flows and environment variables
• Moving the package from dev to test to production

By the end, you’ll have a repeatable process for shipping agents with confidence, without the last-minute scramble.

What Is a Solution in Copilot Studio?

A solution is a package that holds everything your agent needs. That includes the agent itself, its topics, agent flows, connection references, environment variables, and any Dataverse tables it uses. You build in the solution, then move the whole package from one environment to another.

This process of building, testing, and releasing in stages is called application lifecycle management, or ALM. Solutions are how Power Platform does ALM. If you’ve used solutions with Power Apps, it’s the same idea. My guide to Dataverse solutions covers the basics from the Power Apps side.

Default Solution vs Custom Solution

When you create an agent without thinking about solutions, Copilot Studio drops it into a default solution. Every environment has one. It’s a catch-all bucket that holds every customization anyone has made.

The problem is simple. You can’t export the default solution. So if your agent lives only there, you have no clean way to move it. To export, import, or deploy an agent between environments, you need a custom solution in Copilot Studio.

Managed vs Unmanaged Solutions

Solutions come in two flavors, and understanding them saves a lot of pain later.

Type	Where it’s used	Can you edit it?	Can you export it?
Unmanaged	Development environments	Yes	Yes, as managed or unmanaged
Managed	Test and production environments	No, components are locked	No

Here’s how I explain it to clients. The unmanaged solution is your source code. You build and change things there. The managed solution is the finished product you ship. It’s locked so nobody can quietly edit the production agent.

Every new solution starts as unmanaged. When you’re ready to release, you export that unmanaged solution as managed and import it into test or production.

Before You Start

You need a few things in place before creating the solution:

• A development environment with Dataverse – Solutions live in Microsoft Dataverse, so your environment needs a database.
• The right security role – You need at least the System Customizer role to export and import agents with solutions.
• Separate target environments – You can’t import a managed solution into the same environment that holds its original unmanaged version. Plan for at least a test and a production environment.

For the procurement project, I used three environments: Procurement-DEV, Procurement-TEST, and Procurement-PROD.

Step 1: Open the Solution Explorer in Copilot Studio

Copilot Studio has its own solution explorer, so you don’t need to open Power Apps.

1. Open Copilot Studio and make sure you’re in your development environment.
2. On the left side bar, select the three dots (…).
3. Select Solutions.

The solution explorer opens in a new browser tab. Your security roles carry over, so you can only do what Power Apps would let you do.

Step 2: Create a Solution Publisher

Every solution has a publisher. The publisher identifies who owns the components. More importantly, it sets the prefix that gets added to the name of every custom component you create.

Why does the prefix matter? Say you create an environment variable called ApprovalLimit. With a prefix of nbm, its real name becomes nbm_ApprovalLimit. That prefix tells everyone which team built it and prevents name clashes with other solutions.

If you skip this step, your components get the default publisher’s random prefix, something like cr8a3_. Six months later, nobody knows what cr8a3_ means.

To create a publisher:

1. In the solution explorer, select New solution.
2. In the New solution pane, select New publisher under Publisher.
3. Fill in the Properties tab.
4. Select Save.

Here are the values I used for the manufacturing client:

Field	Value I used	Notes
Display name	Northbridge Procurement Team	The friendly name people see
Name	NorthbridgeProcurement	Unique name, no spaces
Description	Publisher for procurement agents and flows	Optional but helpful
Prefix	nbm	Added to every custom component
Choice value prefix	Auto-generated number	Used when you add options to choice columns

A few rules apply to the prefix. It must be 2 to 8 characters long. It can contain only letters and numbers. It must start with a letter, and it can’t start with “mscrm.”

Choose carefully, because components can’t be renamed later. I use one publisher per client and reuse it in every environment.

Step 3: Create the Custom Solution

With the publisher ready, it’s time to create the custom solution in Copilot Studio. You’re back on the New solution pane. Fill in the solution details:

Field	Value I used
Display name	Procurement Request Agent
Name	ProcurementRequestAgent
Publisher	Northbridge Procurement Team
Version	1.0.0.0
Set as your preferred solution	Checked

The Name field fills in automatically from the display name. You can edit it before saving, but not after. It can only contain letters, numbers, and underscores.

The Version follows a four-part format, like 1.0.0.0. It becomes part of the file name when you export, so it’s a handy way to track releases.

Expand More options to add a short description. It helps the next admin who opens the environment.

Select Create. The solution opens, and it’s empty. That’s expected.

Step 4: Set Your Preferred Solution

A preferred solution is the solution where Copilot Studio puts new agents and components by default. If you checked the box in the last step, you’re already done.

If you didn’t, here’s how to set it:

1. Open the solution explorer.
2. Select Set preferred solution on the top menu bar, above the list of solutions.
3. Choose your new solution and save.

When you don’t set one, new components land in the Common Data Services Default Solution. That’s exactly what we’re trying to avoid. I covered the Power Apps side of this in my post on setting a preferred solution in Power Platform.

Pro Tip: In my experience, forgetting the preferred solution is the number one reason agents break after import. Someone adds a new topic or tool, it quietly goes into the default solution, and the imported agent is missing pieces. I set the preferred solution before I create a single component, and I remind every maker on the team to do the same.

Step 5: Create the Agent Inside the Solution

Now create your agent. Because the preferred solution is set, Copilot Studio places the new agent and its components right inside it.

You can also pick the solution directly when you create an agent. On the Copilot Studio Home page, select the gear icon in the description box. Under Advanced settings in Agent settings, choose your solution. Then build the agent as usual. If you need a refresher on building agents, see my guide to creating an agent in Copilot Studio.

To double-check, open the agent and select Settings, then Agent details, then View solution. It should show your custom solution. If it shows the default solution, the mapping is wrong, and new components won’t sync.

Step 6: Add an Existing Agent to the Solution

What if your agent already exists in the default solution, like mine did? You can pull it into the custom solution.

1. Open your custom solution in the solution explorer.
2. Select Add existing, then Agent, then Agent again.
3. In the Add existing agents list, pick your agent.
4. Select Add.

Adding the agent doesn’t automatically pull in everything it depends on. So after adding it, do this:

1. In the Objects pane, find your agent under Agents.
2. Select the three dots (⋮) next to it.
3. Select Advanced, then Add required objects.

This adds topics, flows, and other pieces the agent needs. I run it before every export. It takes five seconds and prevents most failed imports.

One warning here. Don’t remove topics or other agent components directly from the solution. Always change topics through the normal Copilot Studio authoring screens. Removing them from the solution directly can make export and import fail.

Step 7: Add Flows, Connection References, and Environment Variables

This is where a demo agent becomes a real, movable one.

Agent Flows

My procurement agent used an agent flow to create purchase requests in a SharePoint list and send approval emails. If you haven’t built one, here’s how to create an agent flow in Copilot Studio.

If you build flows while the preferred solution is set, they go into the solution automatically. For older flows, open the solution, find them in the Objects pane, and run Add required objects on them too.

Connection References

A connection reference is a pointer to a connection, like “the SharePoint connection” or “the Outlook connection.” The flow uses the reference, not the actual login. When you import the solution into a new environment, you just point each reference at a connection that exists there.

So you never rebuild flows after a move. In test, the SharePoint reference uses a test account. In production, it uses the production account.

If you need to swap connections later, my guide on changing a connection reference in Power Automate walks through it. If users hit permission errors after import, check out this fix for the connection reference read access error.

If your agent uses a custom connector, import the custom connector first. Then import the solution with the connection reference and the agent.

Environment Variables

An environment variable stores a setting that changes between environments. Instead of hard-coding a value, you store it once and read it wherever you need it.

For the procurement agent, I created these:

Display name	Data type	Dev value	Prod value
Procurement Site URL	Text	Test SharePoint site	Live procurement site
Approval Limit	Decimal number	500	2500
Finance Mailbox	Text	Test mailbox	Live finance mailbox

To add them to the solution:

1. Open your solution.
2. Select Add existing, then More, then Environment variable.
3. Pick the variables, select Next, then Add.

You can also create new ones from inside the solution. My post on environment variables in Power Platform covers the creation steps and data types in detail.

In Copilot Studio, environment variables are read-only. You can read them in topics, but you can’t change them from the agent. In a Power Fx formula, you reference them with the Environment. prefix. Here’s the condition I used to decide whether a request needs manager approval:

Topic.RequestAmount > Environment.nbm_ApprovalLimit

When you type Environment. in the formula editor, pick your variable from the list rather than typing the name by hand.

Two things catch people out with environment variables in agents:

• Republish after changes – A published agent uses the values from when you published it. If an admin updates a value, you need to republish the agent. The exception is the Secret type, which is read at runtime.
• Remove the current value before export – Include the definition in the solution, but not the dev value. Select the variable, then under Current Value, select … and Remove from this solution. The value stays in dev, and the import screen asks for a fresh value in each target.

If you manage many environments, you can even set environment variables using PowerShell instead of clicking through each one.

Step 8: Export the Solution as Managed

When the agent is ready for testing, export the solution in Copilot Studio.

1. Open the solution explorer and select your unmanaged solution.
2. Select Export solution. The Before you export pane opens.
3. Select Publish all changes. Only published components are exported, so don’t skip this.
4. Select Next.
5. Check the Version number. It increments automatically, like 1.0.0.1.
6. Under Export as, pick Managed for test and production.
7. Optionally turn on Run solution checker on export.
8. Select Export.

When it’s done, a .zip file downloads to your browser’s download folder.

I also export an Unmanaged copy of every release and store it in source control. That’s my backup if the dev environment ever gets reset or deleted. Keep in mind that a single solution can’t be larger than 95 MB.

Step 9: Import into Test, Then Production

Now import the solution in Copilot Studio by switching to your test environment.

1. Open the solution explorer in the target environment.
2. Select Import solution. The Import a solution pane opens.
3. Browse to the .zip file and select Next.
4. Choose a connection for each connection reference.
5. Enter a value for each environment variable.
6. Select Import.

If the import fails, select Download log file. It’s an XML file that explains what went wrong. The most common cause is a missing required component. That’s why I keep repeating the Add required objects step.

After a successful import, a few manual steps remain:

• Reconfigure authentication – Set up user authentication for the imported agent again.
• Publish the agent – The imported agent must be published before you can share it.

Once test signs off, repeat the same import in production using the same managed .zip file. Don’t re-export for production. The file you tested is the file you ship. Then you can publish the agent to a live website or any other channel.

Shipping Updates

The agent keeps changing after go-live, so your solution in Copilot Studio needs a repeatable release process. For each release, I follow the same loop:

1. Make changes in dev inside the unmanaged solution.
2. Run Add required objects on the agent.
3. Export as managed with a higher version number.
4. Import into test, then production, as an upgrade.

An imported solution only reflects the agent’s state at the moment you exported it. New topics or tools you add in dev won’t appear in production until you export and import again.

Pipelines Basics: Automating Dev to Production

Manual export and import works fine for one agent. Once you have several, pipelines in Power Platform save a lot of time. A pipeline is a preconfigured route, like Dev to Test to Prod, that deploys your solution in a few clicks.

You’ll find it in the Copilot Studio solution explorer. Select Pipelines underneath the list of solutions.

Here’s what pipelines do for you:

• Prevalidation – Missing dependencies are flagged before deployment starts.
• Connections and variables upfront – You provide connection references and environment variable values before the deployment runs.
• Automatic backups – Both managed and unmanaged copies are stored in the pipelines host for every deployment.
• No skipping stages – The same artifact must pass through each stage in order, so nobody bypasses testing.

A few setup rules apply. An admin sets up a host environment, which should be a production environment. Developer environments can serve as dev and QA stages without being managed. Every other environment in the pipeline must be a Managed Environment, which needs premium licenses. Microsoft started turning on Managed Environments automatically for pipeline targets in February 2026.

Pipelines only run from an unmanaged solution in a development environment. You can’t run them from the default solution or from managed solutions. They also deploy managed solutions only, and the default import behavior is an upgrade.

Things to Keep in Mind

• The default solution can’t be exported – Always build agents in a custom solution if they’ll ever leave the dev environment.
• Set the preferred solution first – Components created before you set it end up in the default solution and get left behind on export.
• Topic names can’t contain periods – A solution with a topic named something like “Order status v1.2” won’t export.
• Don’t edit managed agents in production – Make every change in dev and ship it through a new managed version.
• Not everything travels – Things like topic comments, conversation IDs, and channel details don’t move with the agent. Plan to reconfigure them after import.
• Data isn’t included – Solutions carry components, not the rows inside Dataverse tables. Move reference data separately.

Frequently Asked Questions

A solution in Copilot Studio turns your agent from a one-off build into something you can test, ship, and update with confidence. Set up the publisher and preferred solution first, keep settings in environment variables, and let managed solutions do the heavy lifting in production. I hope you found this article helpful.

You May Also Like

• Create a SharePoint list item using Copilot Studio
• Create an agent flow with natural language
• Create a multi-agent setup in Copilot Studio
• Add event triggers in Microsoft Copilot Studio
• Use a SharePoint list as a knowledge source in Copilot Studio