15.3 Create and Use Environment Variables

Configuration that travels with ALM—not hard-coded values

When the same agent solution is promoted from Development to Test to Production, most logic should stay identical. What changes is where systems live: SharePoint site URLs, API base addresses, feature flags, Dataverse environment-specific parameters, and sometimes human-readable labels. Environment variables store those parameters as first-class solution components so you do not hard-code https://dev-api.contoso.com inside topics and then forget to change it in production.

AB-620 skill create and use environment variables sits beside solutions and pipelines: solutions move definitions; environment variables supply per-environment values; pipelines can prompt for or apply those values during deployment.

Four variable scopes—only one is ALM configuration

Copilot Studio makers use several variable families. Do not confuse them on the exam:

Environment variables are Power Platform concepts. Agents consume them like other variables in conditions, messages, and flow inputs, but authors cannot edit their values inside Copilot Studio. The Variables panel shows information and links to Power Apps for authoring. That read-only boundary is a frequent exam discriminator.

Types you should recognize

Environment variable types in Copilot Studio map to Power Apps types roughly as follows:

Connection references are related but not identical. A connection is the authenticated credential to a connector. A connection reference is the solution-aware pointer that apps/flows/agents use so each environment can bind its own connection. Data source environment variables often store parameters actions need (for example a SharePoint site), while the connection supplies who is calling. Exam stems that mention “wrong SharePoint site after import” usually want environment variables (or data source parameters), not rewriting the whole topic.

Create and package environment variables

Recommended workflow:

1. In the same unmanaged solution as the agent, Add existing → More → Environment variable, or create new environment variables in the solution from Power Apps / solution explorer.
2. Define schema name, display name, type, optional default value, and documentation for makers.
3. For secrets, use secret type and store values in the secure store patterns Power Platform supports—never paste production keys into topic messages or knowledge documents.
4. Reference the variable from topics, agent flows, HTTP actions, generative answer configuration, or channel settings that accept environment variables.
5. Before export, Add required objects so dependencies include the variables.
6. On import or pipeline deploy, set current values for the target environment.

If a feature requires the variable to exist in the target (for example channel display name suffix), Microsoft guidance stresses keeping the variable in the same solution as the agent. Variables that only exist in other solutions may appear in pickers in Dev but fail after deploy.

Using environment variables in agents and flows

In topics, pick environment variables from the variable browser similarly to globals—except you will not assign new values mid-conversation. Common patterns:

• Build an HTTP URL: concatenate env var base URL + path.
• Pass site ID or list name into a SharePoint/Power Platform connector action.
• Toggle a branch: if EnableReturnsTool is false, skip a tool topic.
• Supply a Teams / Microsoft 365 Copilot channel display name suffix so users see (Development) or (Test) while production stays clean.

In agent flows, environment variables keep flow actions portable: the flow definition is solution-aware; the URL or data source parameter changes per environment without editing the flow graph after every promote.

Publish rules (critical)

When an agent is published, it captures the environment variable values in effect for most types. If an administrator later changes a non-secret environment variable value, you must republish agents that depend on it for runtime to pick up the change. Secret environment variables are different: they are retrieved at runtime, so updating the secret does not require republish.

Connection references + environment variables together

A robust agent package usually includes both:

1. Connection references for ServiceNow, Dataverse, SharePoint, custom connectors, etc.
2. Environment variables for site collections, API hosts, environment labels, optional secrets.

During Power Platform Pipelines deployment, makers or admins are prompted to supply connections and environment variable values up front so the deployment does not land half-configured. That pre-validation is a major reason pipelines beat manual zip import for teams.

Scenario — Contoso order-status agent

Contoso’s order agent calls https://orders-dev.contoso.com in Dev and https://orders.contoso.com in production. The team creates string environment variable ctso_OrdersApiBaseUrl with Dev default, references it from a REST/HTTP tool and an agent flow, and includes it in CTSO Order Agents solution. Pipeline deploy to Test sets the Test URL; production deploy sets the production URL. No topic edit is required between environments. A separate secret variable holds a non-user key for a backend if delegated auth is not used; rotating that secret does not force republish, but changing the base URL does.

Troubleshooting environment variables

Environment variable validation errors can appear in test chat and publish, but they may not show as ordinary topic errors in the topic list because they are not topic variables.

Anti-patterns

• Hard-coding production URLs in instructions “just for now.”
• Storing passwords in knowledge files or adaptive card payloads.
• Creating env vars only in Default solution while the agent lives elsewhere.
• Expecting makers to edit env vars inside Copilot Studio topic nodes as if they were globals.
• Forgetting that pipelines and import wizards are the right moment to set target values—not a week after users report wrong data.

AB-620 takeaway

Environment variables make agent solutions environment-agnostic. Create typed variables in the agent’s solution, consume them as read-only configuration in Copilot Studio, pair them with connection references, set values per environment during deploy, and republish when non-secret values change. That is the configuration half of ALM; pipelines are the automation half.