Solutions & Environment Variables

Why Solutions Matter

Up to now, we’ve been building and testing agents inside a single environment. But real enterprise deployments need multiple environments — development, staging, and production at minimum. How do you move an agent (and everything it depends on) from one environment to another without breaking things?

The answer is Dataverse solutions.

🏢 AgentForge scenario: Priya’s recruitment agent is tested and ready. But she has three clients, each with their own production environment. She can’t rebuild the agent from scratch three times. She needs to package it once and deploy it to each client’s environment — with client-specific settings like company name, API endpoints, and branding.

What Is a Dataverse Solution?

A solution is a container. It holds Power Platform components — agents, topics, cloud flows, connection references, environment variables, tables, and more. When you export a solution, everything inside it travels together as a single package.

There are two types:

• Unmanaged solutions — Think of these as editable drafts. You work in unmanaged solutions during development. Components can be modified directly.
• Managed solutions — Think of these as published, locked packages. You export a managed solution from dev and import it into staging or production. Components in a managed solution cannot be edited in the target environment — this protects the integrity of your deployment.

The ALM pattern is: build in unmanaged (dev) → export as managed → import managed into staging/production.

Question

What is the difference between unmanaged and managed solutions?

Click or press Enter to reveal answer

Answer

Unmanaged solutions are editable drafts used during development — components can be modified directly. Managed solutions are locked, published packages — exported from dev and imported into staging/production where components cannot be edited, protecting deployment integrity.

Click to flip back

Creating a Solution

Creating a solution in the Power Platform maker portal is straightforward:

1. Go to Solutions in the maker portal
2. Select New solution
3. Provide a display name, name (unique identifier), and publisher
4. Set the version number (important for tracking releases)
5. Save

The publisher is critical — it defines the prefix for all components in the solution (e.g., contoso_ or agentforge_). Always use a custom publisher for your organization. Never use the default publisher for production work, because it makes components harder to identify and manage across environments.

Adding existing agents to a solution

Your agent already exists in the environment — you just need to add it to your solution:

1. Open your solution
2. Select Add existing and choose the component type
3. For agents, select your agent from the list
4. Copilot Studio automatically detects dependencies — topics, knowledge sources, and flows that the agent needs

This dependency detection is important. If your agent uses a cloud flow for an HTTP action, the solution will prompt you to include that flow. Missing dependencies cause import failures in the target environment.

Question

Why should you never use the default publisher for production solutions?

Click or press Enter to reveal answer

Answer

The default publisher uses a generic prefix that makes components harder to identify and manage across environments. A custom publisher (e.g., 'agentforge_') clearly identifies which organization owns each component, which is essential when multiple solutions exist in the same environment.

Click to flip back

Environment Variables: The Key to Portable Agents

Here’s the problem Priya faces: her recruitment agent has a company name, an API endpoint for the client’s job board, and a support email address baked into the instructions and topics. If she imports the same solution into Client B’s environment, it still says “Client A” everywhere.

Environment variables solve this. Instead of hardcoding values, you reference a variable. The variable has a different value in each environment.

Environment variable types

Copilot Studio supports several types:

• Text — Strings like company names, URLs, email addresses
• Decimal number — Numeric values like thresholds, limits, retry counts
• Two options (Yes/No) — Feature flags, toggle settings on or off
• Data source — References to specific data connections
• Secret — Sensitive values like API keys, stored securely in Azure Key Vault

How they work

Each environment variable has two parts:

1. Definition — The variable’s schema (name, type, description, default value). This travels with the solution.
2. Current value — The actual value in a specific environment. This is set locally after import and does NOT travel with the solution.

This separation is the key insight. The definition says “there’s a variable called CompanyName of type Text.” The current value in dev might be “AgentForge Test Co.” while the current value in Client A’s production is “Pacific Mutual Insurance.”

Approach	How It Works	Pros	Cons
Hardcoded values	Type the value directly in instructions, topics, and flows	Simple, fast for prototyping	Must manually change every instance when deploying to a new environment — error-prone and doesn't scale
Environment variables	Reference a variable name; set the actual value per environment	Deploy same solution everywhere, change values without editing the agent, supports secrets via Key Vault	Slightly more setup upfront, requires documentation of which variables need values

Creating an environment variable

1. In your solution, select New and then choose Environment variable
2. Set the display name, name, type, and optionally a default value
3. Save — the variable is now available to reference in your agent’s topics, flows, and instructions

Using environment variables in your agent

In cloud flows, you reference environment variables directly as dynamic content. In Copilot Studio topics, you can use them in message nodes, conditions, and as parameters passed to actions.

For example, Priya’s welcome message changes from:

"Welcome to AgentForge Recruiting! How can I help you today?"

to:

"Welcome to {CompanyName} Recruiting! How can I help you today?"

where CompanyName is an environment variable with a different value per client.

Question

What are the two parts of every environment variable, and why is the separation important?

Click or press Enter to reveal answer

Answer

1) Definition — the variable's schema (name, type, default) that travels with the solution. 2) Current value — the actual value set locally in each environment. This separation lets you deploy the same solution package to multiple environments with different configurations without editing the agent.

Click to flip back

Priya’s Packaging Strategy

🏢 Priya defines her environment variables:

Variable	Type	Dev Value	Client A (Pacific Mutual)	Client B
CompanyName	Text	”Test Corp"	"Pacific Mutual Insurance"	"Northwind Traders”
JobBoardAPI	Text	”https://dev.api…"	"https://pm.api…"	"https://nw.api…”
SupportEmail	Text	”dev@agentforge.com"	"hr@pacificmutual.com"	"hr@northwind.com”
MaxResults	Number	5	10	15
EnableSalaryRange	Boolean	Yes	No	Yes
JobBoardAPIKey	Secret	(dev key)	(PM key)	(NW key)

She builds one solution. Exports it as managed. Imports it into each client’s environment. After import, she (or the client admin) sets the current values for each variable. The agent works perfectly for each client with zero code changes.

The secret type is especially important for API keys — the value is stored in Azure Key Vault, not in the solution package itself. This means credentials never travel in exported solution files.

Question

How does the 'secret' environment variable type differ from the 'text' type?

Click or press Enter to reveal answer

Answer

Secret environment variables store their values in Azure Key Vault rather than in the Dataverse environment. This means sensitive values like API keys never appear in exported solution files and are protected by Key Vault's access policies and audit logging.

Click to flip back

Knowledge Check

Priya needs to deploy the same agent to three clients, each with different API endpoints and company names. What is the BEST approach?

ACreate three separate agents, one per client, with hardcoded valuesBUse one solution with environment variables for client-specific valuesCUse one agent and change the hardcoded values before each importDStore all three clients' values in the agent and use conditions to select the right ones

Check Answer

Knowledge Check

After importing a managed solution into a production environment, a team member notices the agent still shows the dev company name. What is the most likely cause?

AThe managed solution is corrupted and needs to be re-exportedBThe environment variable current values were not set in the production environmentCEnvironment variables don't work in managed solutionsDThe agent needs to be republished after import

Check Answer

Knowledge Check

Which environment variable type should you use for storing an API key that authenticates to a client's external job board system?

AText — it's just a string valueBData source — it's a connection to an external systemCSecret — stored securely in Azure Key VaultDNumber — API keys are typically numeric tokens

Check Answer

Key Takeaways

• Dataverse solutions are containers that package agents and their dependencies for transport across environments
• Unmanaged solutions are for development; managed solutions are locked packages for staging and production
• Environment variables replace hardcoded values with per-environment configuration — essential for multi-tenant and multi-environment deployments
• Five variable types: text, number, boolean, data source, and secret (Key Vault backed)
• The variable definition travels with the solution; the current value is set locally per environment
• Always use a custom publisher — never the default — for production solutions

🎬 Video coming soon

Solutions & Environment Variables — Walkthrough