Plan reuseable agent components

Four agents at the same company each need to raise a service ticket. If every team wires its own connector sequence, the ticket payload drifts inside a quarter and each change costs four edits. Build the sequence once and let all four reference it, and you have the subject of this page: what you factor out of an agent, what shape you factor it into, and what carries it to the other agents and environments that need it.

Two terms carry the rest of the page. A reusable module is the unit you factor shared logic into, and the ones this page plans for are a child topic, an agent flow, a tool (whichever mechanism that tool uses), a knowledge source, an entity, and a child agent. A reuse container is what carries modules beyond the agent that created them, and there are two: a component collection, which shares components between agents inside one environment, and a Power Platform solution, which moves them between environments. Every planning question on this subject resolves into those two decisions, taken in that order.

If you already ship Power Platform work, the container half will look familiar, because publishers, managed layers and environment variables behave here exactly as they do for apps and flows. The half that is specific to Copilot Studio is the module half, and it is the half that decides whether a platform team can release a shared ticket flow on a monthly cadence while four product teams keep shipping weekly.

Why the order matters

When you create an agent, the agent is created within a Power Platform solution^[1] automatically. You therefore have a container before you have anything worth reusing, which is exactly what makes the wrong order tempting: the packaging already exists, so teams treat packaging as the whole answer and never factor the logic out. Packaging a duplicate is still a duplicate. The solution just carries four copies of the ticket sequence instead of one shared module.

The neighbouring planning pages own the adjacent slices. Plan integration with enterprise systems decides which tool mechanism reaches a given backend, and plan identity strategy decides whose identity runs the call. This page takes those answers as given and asks a different question: how many agents, and how many environments, get to use the result. The pipeline mechanics live further along the guide, in create an ALM solution and parameterize agent environments; what stays here is the design decision that has to be right before any pipeline runs.

The figure below shows the nesting the rest of the page assumes: agent components sit inside a component collection, a collection can be carried by a solution, and the solution is what crosses an environment boundary.

Three module shapes carry the reuse requirements this section plans for, and you choose between them by what the shared logic is, not by how often it runs. Shared conversation, meaning the messages and questions the user sees, becomes a child topic. A fixed sequence of system actions becomes an agent flow. A single call into one system becomes a tool. Choosing wrongly shows up at runtime. An agent flow has no conversation nodes of its own, so the only user input it gets under generative orchestration is whatever the agent generates a question for to fill its inputs^[2], and a business sequence left spread across topic nodes runs in the order the orchestrator plans, because when the agent selects multiple tools, agents, or topics it calls them in sequence.

Shared conversation becomes a child topic

Microsoft's guidance names the trigger for this one directly: when multiple topics share conversation messages or logic nodes, group them in a new topic instead of duplicating their content^[3], so that a single update reflects on every topic that redirects to it. Topics used this way need no trigger phrases of their own; the same guidance calls them reusable, bite-size topics and treats them as a distinct category from the entry-point topics that users trigger by utterance.

The caller reaches the child with a Redirect node, and the first thing that catches people out is the menu. You add it from Topic management > Go to another topic, and the node that lands on the canvas is the Redirect node. One node, two names, and the documentation calls the node Redirect throughout. When the conversation reaches the end of the destination topic, it resumes in the originating topic by default^[4], so nodes placed after the Redirect node do run. An End current topic node inside the child returns control to the caller immediately, which is how a condition branch exits early without ending the conversation.

One precondition is easy to miss. A topic whose status is Off does not trigger at all, including when another topic redirects to it, and the topic checker reports an error against the caller. Turning a shared topic off to work on it quietly breaks every dependent until you turn it back on. The figure below traces a single redirect so the contract points are visible.

A fixed sequence becomes an agent flow

Agent flows are deterministic: they execute actions following a rule-based path, and the same input always produces the same output^[5]. Determinism is the property you are buying when you move a transaction out of topic nodes, and it is why copying the same series of connector nodes into each topic to preserve execution order is the wrong fix. That habit also fails for a second reason under generative orchestration, where the plan, not your canvas, decides what runs next.

A flow can be added to an agent as a tool only when it meets a set of conditions, and Microsoft publishes them across several articles rather than in one list: it must have the When an agent calls the flow trigger and a Respond to the agent action, be configured to respond in real time with the Asynchronous response toggle set to Off, be published^[6], be a solution flow stored in a solution in the same Power Platform environment as the agent^[7], and answer inside the synchronous response window, whose published length Microsoft's own pages disagree on; create agent flows carries that contract in full. Work that genuinely takes longer is not blocked, only relocated: actions placed after the Respond to the agent action continue to run^[7] up to the flow run duration limit of 30 days.

A single system call becomes a tool

Everything else is a tool, and the tool mechanism you choose is whichever one the target system already publishes. Copilot Studio lists them as a connector (prebuilt or custom), an agent flow, a prompt, a REST API, a Model Context Protocol server, and computer use, with Azure Bot Service skills and client tools as two further mechanisms that add tool-like behaviour.

Adding a tool and exposing a tool are separate acts, and the second one is the reuse boundary. Tools added to an agent are available for automatic orchestration throughout your agent's conversations^[8]. Add the same flow inside a topic instead and it only becomes available to that topic^[6]. One flow, two boundaries, and the difference is a design choice rather than a property of the flow.

The control that decides which boundary you get sits on the tool's configuration page under Additional details: Allow agent to decide dynamically when to use the tool. When it is selected, the agent can use generative orchestration to determine when to use the tool; when it is not selected, the agent only uses the tool when a topic calls it explicitly. It is selected by default when generative orchestration is enabled, so an agent-level tool is broadly reusable unless you narrow it on purpose. Narrowing is the right call when the step has to land at one specific point, for example immediately after a Question node that captured a confirmation.

Classic orchestration removes the choice entirely. With generative orchestration turned off, tools can only be called explicitly from within a topic^[2], so every tool is topic-scoped whether or not that was the intent.

Breadth also has a ceiling. When using generative orchestration, the orchestrator can handle a maximum of 128 tools per agent, and Microsoft recommends limiting an agent to no more than 25 to 30 for best performance and results. Child agents run their own orchestration and manage their own set of up to 128 tools, which is the structural answer when one agent's tool list outgrows the recommendation. The figure below sets out the three outcomes.

A reusable module is only reusable while its module contract holds — this guide's name for the four things dependents bind to, which Microsoft documents separately rather than as one published list: parameter names, parameter types, the module name, and the description. Treat all four as an interface other components bind to, because they are.

Parameter binding is by name. Topic input and output parameters each require a name, a data type and a description, and a redirecting topic maps values into them one by one^[9]. Types are sticky in a different way: a variable's type is set the first time you assign a value, and after that the type is fixed and you cannot assign a value of any other type^[10]. Because dependents bind by name, adding a parameter leaves the existing mappings intact, while renaming one means finding and updating every dependent that maps it.

Deletion is the sharp edge. If you remove a global variable that other topics use, the references to it show as Unknown^[11], you get a warning before confirming, and topics containing those references might stop working. The same shape applies to any contract member: find every dependent first, fix them, then remove.

Descriptions are a runtime interface, not documentation

Under generative orchestration the agent selects one or more tools, topics, other agents, or knowledge sources for each message, and the most important factor in that selection is the description^[2], with names and parameter names and descriptions as further factors. That makes description drift a runtime defect rather than a documentation defect. Microsoft states the failure mode plainly: if multiple topics have similar descriptions, your agent might invoke them all to answer a question, and the fix is to test thoroughly and revise the overlapping descriptions.

The same guidance gives the shape of a good one. Use a descriptive and unique name that is a short phrase, avoid generic or ambiguous names, keep the description to one or two sentences, and use specific language to prevent ambiguity between similar topics and tools. It also helps to indicate what a module cannot do, which is how two neighbouring capabilities stay distinguishable: a current-weather topic that says it does not get forecasts for future days, beside a forecast topic that says it does not get today's conditions. The documented anti-example is the prepopulated one nobody edits, a tool named Answer Question described as a tool that can answer questions, which gives the orchestrator nothing to discriminate on.

Version compatible things together

Because dependents bind to the contract and not to a build, a shared collection and the agents that reference it have to move as a matched set. Microsoft's own ALM walkthrough^[12] makes that explicit: the test environment imports the same collection versions as development, and production imports stable versions such as v1.0. That makes promoting the shared module and its dependents together the safe default, and keeping the change compatible the fallback when you cannot.

One current limitation belongs to the contract too. Tools and topics do not yet support custom entities^[2], meaning closed lists and regex entities, as input parameters; to collect that kind of value you use a Question node inside a topic instead.

Once the module exists, the question becomes how far it has to travel, and Copilot Studio answers with two containers that do different jobs.

A component collection is a set of reusable agent components whose main benefit is that you can share it among multiple agents within an environment^[12]. Microsoft's list of the components it can hold is written as an inclusive one: topics, knowledge, tools, child agents, model context protocols, connectors, flows, and entities. Two behaviours matter more than the click path. First, when you add components from an agent to a collection, the components are moved to the collection and the agent references the components within the collection^[13], so the collection becomes their home rather than holding a copy. Second, any component dependencies are automatically selected and added with them, and you can exclude dependencies only if you have set a primary agent for the collection.

The primary agent is worth understanding before you plan around it. It is a single agent that owns the components, it is what lets you build a smaller collection without every dependency, and you cannot set one while the collection has multiple connected agents. If you do not set a primary agent, the collection is owned by the environment and must have access to the dependencies itself. Editing rights are separate again: to edit a collection or add one to an agent you must be its creator or hold the system customizer or system admin role, while other agent authors can see and use the collection but cannot change the components inside it.

When the collection is not enough

Exporting a collection from the Component collections workspace is one click, and the export is packaged as a versioned managed solution. That is the right shape for consumers and the wrong shape for the team that still edits the assets, because managed components arrive under a managed layer, meaning the importing environment can use them but cannot edit them in place. Microsoft's own instruction is to use solutions for complex collections, naming connectors and environment variables as the examples^[13], and a solution is also how you produce an unmanaged export at all.

The solution path adds the controls a release needs. You choose the publisher, and the guidance is to create a single publisher and use it consistently across all environments. You choose the version, which Copilot Studio increments automatically and which appears in the exported file name in the form SolutionName_Version_SolutionType.zip. You choose Managed or Unmanaged at export time. The ALM golden rules compress the rest: always work in the context of solutions, use a custom publisher and prefix, create separate solutions only if you need to deploy components independently, and export and deploy solutions as managed unless you are setting up a development environment^[12].

The default solution is a starting point, not a delivery mechanism

Copilot Studio agents are created in the default solution automatically, and to export, import, and manage agents between environments you need to create and use a custom solution^[1]. Flows are the case that misleads people, because the platform genuinely does accept the loose arrangement: to be available to agents, flows must be stored in a solution in the same Power Platform environment, and flows can be added to the Default Solution for use with agents, or moved into a different solution^[7]. A shared flow left in the default solution therefore runs fine in development and never reaches the release, because the default solution can't be exported^[14], which is why a project solution is the plan rather than a formality.

Adding the agent is also not the same as adding its parts. If you add components such as topics or flows to your agent after creating the solution, you must also add them to the agent in your unmanaged solution before you export^[15], which is what the Advanced > Add required objects command is for, and the same command exists for workflows and environment variables. The single most common reason an import fails is that the solution does not contain some required components. The figure below shows the shape of a promotion once the collection has a solution around it.

Planning reuse means planning the gaps as well, because several agent settings are not solution-aware and therefore never arrive with the import. Copilot Studio names them: Azure Application Insights settings, manual authentication settings, Direct Line and Web channel security settings, deployed channels, and sharing^[12], whether that sharing is with other makers or with end users. Each one becomes a post-deployment step in the downstream environment, and the import documentation adds two more: configure user authentication for the agent again^[15], and publish the imported agent before it can be shared.

That list is why a reuse plan for an enterprise agent is never only a packaging plan. If the agent depends on channel security, on a manually configured service provider, or on Application Insights telemetry, those are runbook items for every environment the package lands in.

Constraints that bite at export time

Four more rules shape what you can package, and all four are cheaper to design around than to discover during a release.

• You cannot export managed solutions. A solution is unmanaged when created, and if you change it to managed you have to create a new solution to export from.
• You cannot export a solution containing an agent with periods in the name of any of its topics, which makes topic naming a packaging constraint rather than a style preference.
• Removing an agent from a solution does not remove its components from the solution; you remove those separately. The matching warning is stronger: do not remove unmanaged agent components such as topics directly from the solution unless you also remove the agent, because changing an agent's components from the solution rather than through the Copilot Studio authoring surface causes export and import to fail.
• Custom connectors have an ordering rule. You must import custom connectors first, then the connection reference with the agent solution. A connection reference is the solution component that points at a connection, and it is the connection — not the connection reference — that stores the authentication credential^[16]; the target environment supplies a connection for each connection reference during import, which is why the connection reference is the second half of that pair rather than the first.

One more caveat sits on the collection side rather than the solution side. If you uploaded files as knowledge sources for an agent, adding those files to a component collection removes them from the originating agent, with the workaround being to move them back. Treat file knowledge as a transfer of ownership, not a share.

The last reuse decision is what you deliberately leave outside the module. Anything that differs between environments belongs in an environment variable, and anything that differs between conversations belongs in a variable of conversation scope. Confusing the two is one of the most reliably testable errors on this subject, because both look like a stored value and neither behaves like the other.

Variables in Copilot Studio exist at four scopes: topic, global, system, and environment^[10]. Environment variables are a Power Platform concept created outside Copilot Studio, they are read-only inside it, and they exist so that an application can move between environments unchanged apart from the few external references that differ. Administrators change their values in Power Apps; agent authors cannot.

Publish time versus runtime

Here is the distinction that decides a rotation design. The published version of an agent includes the environment variable values you set when you publish it, so whenever an administrator updates one you must republish any agent that uses it for the change to take effect at runtime. There is exactly one exception: you do not need to republish when the value of an environment variable of type secret changes, because unlike other environment variables, secret variables are retrieved at runtime. The figure below contrasts the two paths.

That runtime read is not free of prerequisites. A secret environment variable references a secret in Azure Key Vault, and to authorize Copilot Studio to read the vault you assign the Key Vault Secrets User role to the Microsoft Copilot Studio Service application^[17], then scope access with tags on the secret: AllowedEnvironments with the allowed environment IDs to authorize every agent in those environments, or a per-agent tag whose value is an entry in the form {envId}/{schemaName}. Both take comma-separated values. The per-agent tag is one to check rather than memorise, because the two Microsoft articles that document it disagree: the Copilot Studio page calls it AllowedAgents, while the Power Apps article on Key Vault-backed environment variables^[18] still calls it AllowedBots, a leftover from the bot-to-agent renaming. The tiebreaker is operational rather than editorial: the error the agent raises when the tag is missing states the exact tag name and value to add, so read the error and copy it. Two further details follow from the runtime read: the Dialog runtime caches a secret value for five minutes and caches unsuccessful reads for 30 seconds, so a rotation is not instantaneous, and Microsoft warns that anyone who can edit the agent in the environment could add a Message node that returns the secret's value.

Global variables are session state

Global variables sit at the other end. They are available in all topics across the entire agent, they apply during a single user session^[11], and a value persists until the session ends or a Clear variable values node resets it, which is what the Reset Conversation system topic does when a user says something like start over. They are writable from any topic, their names must be unique across all topics, and they can be set from external sources when a host page already knows something about the user.

That profile makes them right for a partly finished quote and wrong for a service endpoint. A deployment setting stored in a global variable is not read-only, does not survive the session, and cannot be changed by an administrator without editing the agent. The deeper mechanics of variable scope live on manage variables; what a reuse plan needs is only the boundary: configuration in environment variables, conversation state in global variables.

Question stems on this subject usually describe an organisation that already has duplication and ask for the change that removes it, or describe a package that already exists and ask what is missing. Both shapes reward reading for the boundary being crossed.

When a stem says several agents reuse a set of shared topics, a prompt and a flow, and that the set is released on its own cadence, the discriminator is the release cadence, not the sharing. Sharing inside one environment is a component collection; an independent release across environments needs the collection added to a custom solution so it can be versioned and promoted. When the stem instead says makers keep creating agents in the default solution and the release lead has to hunt for components before every deployment, the answer is a project solution used from the start, because the default solution is where agents land automatically and is not a delivery boundary.

When a stem describes a fixed sequence that must run identically every time, expect distractors that duplicate connector nodes across topics to preserve order. The correct answer builds the sequence as an agent flow and adds it as a tool. When the stem says the step must run at one specific point, immediately after a Question node, the discriminator flips: the flow goes into that topic, because a flow added to a topic only becomes available to that topic. When the stem says many conversation paths may need it and the orchestrator must select it, the tool goes to agent level with dynamic selection left on.

Credential rotation questions turn on one word. If the value lives in a secret environment variable, rotating the Key Vault value takes effect without republishing; any answer that requires republishing every consuming agent is the distractor. If the stem is about a value that changes during a conversation, the answer is a global variable, and the distractor is an environment variable, which is read-only in Copilot Studio.

Finally, watch for stems about a tool the agent picks at the wrong moment. When two modules have overlapping descriptions, the agent may invoke both, so the fix is to rewrite the names and descriptions to be specific, including what each one does not do. Under generative orchestration the selection runs on descriptions, so adding trigger phrases does not address a description problem, and turning a shared topic off is worse than neutral: an Off topic stops triggering through redirects too.