15.2 Add Existing Agents to a Solution

From “agent exists” to “agent is portable”

Many teams create a useful agent first and discover ALM later. AB-620 explicitly tests add existing agents to a solution: open a custom unmanaged solution, pull the agent in, pull required objects, then export. Packaging is incomplete if you only add the agent row and leave topics, flows, or environment variables behind.

Prerequisites and access

• Work in the development environment that already contains the agent.
• Use a custom unmanaged solution (section 15.1)—not a managed package you are trying to re-export.
• Hold at least System Customizer (or equivalent solution privileges).
• Know that solution explorer rights mirror Power Apps solution rights for the same user.

Step-by-step: add an existing agent

1. Open Solutions in Copilot Studio.
2. Open (or create) your custom unmanaged solution.
3. Select Add existing → Agent → Agent again (UI may nest the component type).
4. In Add existing agents, select the agent(s) to package → Add.
5. With the agent selected under Objects → Agents, open … → Advanced → Add required objects.
6. Review the objects list: topics, workflows/flows, environment variables, connection references, and other dependencies should appear.
7. Export only after required objects succeed and a smoke test still works in Dev.

If you later author new topics, tools, or flows on the agent, run Add required objects again before the next export. New components do not magically attach to the solution container.

Dependency map for Copilot Studio agents

Think of the agent as a root component with a tree of dependents:

Not every property is portable. Microsoft documents that topic-level and node-level comments do not export, and some identity/runtime properties (conversation IDs, environment IDs, certain channel details, icons) may be empty after import. Plan post-import setup time.

Missing dependency failures (and how to fix them)

When import fails, the UI offers a download log (XML) describing missing components. Typical root causes:

Important packaging warning: Removing an agent from a solution does not remove its components from that solution. Remove leftover topics, flows, and variables deliberately. Conversely, do not delete unmanaged agent topics directly from the solution explorer as a shortcut—edit through the Copilot Studio authoring UI. Direct solution-level surgery can corrupt export/import.

Classic chatbots, skills, and special cases

For classic chatbot skills scenarios, documentation sometimes instructs removing a skill environment variable’s current value from the solution before export so target environments supply their own value. The modern agent pattern is similar in spirit: ship the definition of environment variables and connection references, not production secrets hard-coded as if they were universal.

If the agent uses component collections, adding new components to a collection requires updating every unmanaged solution that references the collection—again with Add required objects on the collection.

Large agents (for example very high topic counts) may need the classic export experience for reliability. That is an operational detail, but it shows up when exam stems mention failed export on large solutions.

After import: the steps people forget

1. Open the imported agent from the solution Agents list (opens Copilot Studio).
2. Recreate or reselect connections for connection references.
3. Set environment variable current values for that environment.
4. Reconfigure user authentication as needed for the target environment.
5. Validate knowledge sources and tool endpoints against test data—not production write systems on first try.
6. Publish the agent; unpublished imports are not ready to share.
7. Allow time for assets such as icons to appear consistently (can lag).

Upgrade vs update of an existing managed agent follows standard Power Platform solution upgrade rules. If a hotfix created an unmanaged layer in production, inspect solution layers and remove the unmanaged layer when the managed upgrade should win.

Scenario — Fabrikam support agent trapped in Default

Fabrikam’s support agent grew for six months in the Default solution with ServiceNow knowledge, a custom connector for order status, three agent flows, and two child agents. The release manager creates Fab Support Agents unmanaged solution, Add existing the parent agent, runs Add required objects twice after discovering missing flows, separately ensures the custom connector is solution-aware, and exports managed to Test. Import fails once because a new topic added that morning was not required-objected—after a third pass, import succeeds, connections are re-authenticated, and evaluation runs. That sequence is the exam story for “add existing agents.”

Decision guide for AB-620 stems

Anti-patterns

• Exporting without Add required objects “because the agent chats fine in Dev.”
• Treating the Default solution as the permanent home and selectively exporting random components.
• Hand-editing solution XML to “fix” dependencies without understanding Dataverse relationships.
• Assuming multi-agent A2A or Foundry integrations package every remote agent definition into one zip—remote systems may remain external configuration.
• Skipping post-import authentication and publish, then blaming “broken ALM.”

AB-620 takeaway

Adding an existing agent is a dependency assembly task, not a single checkbox. Use Add existing, repeatedly Add required objects, respect connector import order, fix failures from the import log, and complete connection, environment variable, auth, and publish steps in each target environment. Portable agents are complete solutions—not orphan agent records.