Package an agent and its dependencies in a solution

  • 10 minutes

Your environment plan gives each release of an agent a place to go, and the package you build determines whether the agent arrives there complete. In this unit, you learn how to structure a custom solution with your own publisher, choose a managed or unmanaged solution for each environment, add an agent and its required objects on the standard harness, and choose a solution for an agent on the GitHub Copilot harness.

Structure a custom solution for an agent

A Power Platform solution is a container that carries an agent and its customizations from one environment to another. To export an agent, import it into another environment, or deploy it with a pipeline, you need a custom solution, which is a solution you create for your own work. Always work in the context of that solution as you create and change components, so everything you build is in the solution when you export it.

Set up a publisher and prefix

Every solution has a publisher, and the publisher of the solution where you create a component owns that component. Each publisher also has a prefix, which is added to the name of each new component you create in the publisher's solutions, such as a table. Set up both before you create any components:

Setting What to do Why it matters
Publisher Create your own publisher instead of using the default one. Give it a name that identifies who built the solution, and use it in every environment. Ownership of a component can move between solutions from the same publisher, but not between publishers.
Prefix Choose a prefix that identifies your organization. The default publisher's prefix is randomly assigned, such as cr8a3. Prefixes help avoid naming collisions when solutions from different publishers share an environment. You can't change a component's name after you create it.

Decide how many solutions you need

Start with one solution that holds the agent and the components it depends on. Create separate solutions only when you need to deploy components independently.

On the standard harness, component collections offer another way to share components. A component collection is a set of reusable agent components, such as topics, knowledge, and tools, that several agents in the same environment can use. Collections move to other environments in solutions, so the team that maintains a collection can release it on its own schedule, independent of the agents that use it.

Choose a solution type for each environment

Every solution is either unmanaged or managed, and each type belongs in different environments. A solution's type is separate from whether an environment is a managed environment.

Solution type Where it belongs How it behaves
Unmanaged The development environment You create and change components in it. It's the source for everything you release.
Managed Test, production, and any other environment that isn't a development environment for the solution You can't edit its components directly. Deleting it removes all the customizations it contains.

To deploy, export the unmanaged solution from development as managed, and treat the managed file as the build artifact that moves to test and production. Export as unmanaged when you set up another development environment or check the solution into source control.

Two constraints shape how you work with managed solutions:

  • You can export an unmanaged solution as managed, but you can't export a managed solution.
  • You can't import a managed solution into the environment that holds the unmanaged solution it came from. To test the managed version, you import it into a separate environment.

Add a standard harness agent to a solution

On the standard harness, Copilot Studio adds each new agent to a default solution automatically. To move the agent between environments, add it to your custom solution. Exporting and importing agents in solutions requires at least the System Customizer security role.

Add the agent

To add an existing agent from the Copilot Studio solution explorer:

  1. On the side bar, select the three dots (…), and then select Solutions.
  2. Open your custom solution.
  3. Select Add existing > Agent > Agent.
  4. In the Add existing agents list, select the agent, and then select Add.

To have Copilot Studio create future agents in your custom solution by default, select Set preferred solution in the solution explorer, and then choose that solution.

Add the components the agent depends on

Components that you add to the agent later also need to go into the solution before you export. For example, suppose the HR agent gains a flow that looks up leave balances, and the flow reads an environment variable, which is a setting stored as its own solution component. The next export needs the flow and the environment variable along with the agent. To add them:

  1. In the Objects pane, find the agent under Agents, select the three dots (⋮), and then select Advanced > Add required objects.
  2. Find the agent's flows in the Objects pane, and run Add required objects on them the same way.
  3. If the solution doesn't have the environment variables yet, select Add existing > More > Environment variable, select the variables, and then select Next > Add. If the solution already has them, run Add required objects to confirm that it has every dependency.

If the agent uses a custom connector, import the custom connector into the target environment first. Then import the agent solution with its connection reference, which is a solution component that refers to a connection for a specific connector.

Prevent export and import failures

Follow these rules to keep an agent's solution ready to export and import:

  • Required objects: A solution that's missing required components is the most common cause of a failed import. Run Add required objects before every export.
  • Topic changes: Change topics only through normal authoring in Copilot Studio. Removing or changing an agent's components directly in the solution causes export and import to fail.
  • Component removal: Remove components from the solution only when you also remove the agent. Removing the agent leaves its components in the solution, so remove them as a separate step.
  • Topic names: A topic with a period (.) in its name blocks the export.

If an import fails, select Download log file to get an XML file that describes the cause.

Check the agent after import

Some agent properties don't transfer with the solution:

  • The Conversation ID, CDS Bot ID, and Environment ID
  • Topic-level and node-level comments
  • The agent's icon and channel details, which can arrive empty
  • Some topics and knowledge sources that are stored as separate resources or Dataverse tables, depending on how they're created or linked

After a successful import, publish the agent before you share it.

Choose a solution for a GitHub Copilot harness agent

On the GitHub Copilot harness, you place an agent in a solution through its settings. The Solution and Schema name settings on the Agent details tab are editable only until you save the agent for the first time. The harness is also a one-time choice, because an agent can't be transferred from one harness to the other. Make both choices as part of creating the agent:

  1. Create your custom solution and its publisher.
  2. Create the agent on the GitHub Copilot harness.
  3. Before you save the agent, select the three dots (…) in the agent designer toolbar, select Settings, and then select the Agent details tab.
  4. In the Solution field, select your custom solution.
  5. Save the agent. After the first save, the settings on the Agent details tab are read-only.

Values that change from one environment to the next, such as the URL of a service the agent calls, still need a home outside the agent so the same package works in every environment.