Configure environment variables for a hosted agent

Configure environment variables for your hosted agent by defining where values belong in azure.yaml, what the Microsoft Foundry platform provides automatically, and how azd environment integration works. You also learn how to add custom variables and handle local development secrets.

Note

Agent manifests (agent.manifest.yaml) and standalone agent definitions (agent.yaml) are deprecated. As of the Foundry azd extensions (azure.ai.agents 1.0.0-beta.1), all hosted agent configuration lives in a single azure.yaml. See Author azure.yaml for hosted agents.

Prerequisites

  • An initialized hosted agent project with an azure.yaml file. To create or update a project, see Author azure.yaml for hosted agents.
  • The azd Foundry extensions installed. For installation steps, see Install the azd Foundry extensions.
  • An authenticated Azure Developer CLI session. Run azd auth login if needed.
  • An active azd environment. Select or create one with azd env select or azd env new.

Define environment variables in azure.yaml

Define environment variables in the env map of the azure.ai.agent service in your project azure.yaml, not in your Dockerfile. This approach keeps your container image portable and lets you change configuration without rebuilding.

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    env:
      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
      MY_CUSTOM_VAR: ${MY_CUSTOM_VAR}

Use the ${VAR_NAME} syntax to reference azd environment variables. The platform resolves these variables at deploy time from .azure/<env>/.env.

Note

Why not the Dockerfile? Values baked into a Dockerfile are fixed at image build time and visible to anyone with access to the image. Using azure.yaml lets you change values per environment and keeps secrets out of the image layer.

Important

Don't declare FOUNDRY_PROJECT_ENDPOINT in the azure.yaml env map. The platform injects it automatically into hosted containers, and azd ai agent run sets it for local development from the active azd env. Declaring it explicitly is redundant and risks shadowing the platform-managed value.

Set azd environment variables

  1. Add or change a variable in your current azd environment:

    azd env set MY_CUSTOM_VAR=my-value

  2. View all current values:

    azd env get-values

    These values are stored in .azure/<env-name>/.env and resolved into your azure.yaml at deploy time.

Separate session uploads from trusted application files

Session file uploads write beneath $HOME, which defaults to /home/session. The platform persists these files across turns and idle periods. For file-transfer examples, see Session file operations.

Decide whether callers with upload access are also trusted to change your agent's code, configuration, or instructions. If they aren't, treat upload-writable contents of $HOME as untrusted input. Permission to upload data must not implicitly grant permission to replace trusted agent code or configuration.

Keep using $HOME for uploaded documents, generated outputs, and session state. Separate those uses from trusted application inputs:

  • Package application code, dependencies, and trusted configuration outside $HOME. Keep those locations protected from writes by upload callers.
  • Don't automatically import modules, load assemblies or plugins, or discover trusted configuration and startup files from upload-writable directories.
  • Review framework behavior as well as your own code. Working-directory changes and automatic discovery of .env files, skills, or agent instructions can introduce trust in uploaded files.
  • Configure runtime loading paths through deployment-controlled settings, not files that upload callers can replace.

Apply the Python startup setting or the C# deployment pattern below as part of this separation. Neither example is a complete code-execution boundary.

Important

Some skill and harness agents intentionally load instructions, discover capabilities, or execute tools from $HOME. Don't make their session directories read-only or remove required discovery paths without adapting the agent. When upload callers aren't trusted to provide those capabilities, separate trusted capability sources from uploaded data. If executing uploaded code is intentional, review the sandbox, agent identity permissions, and tool access for that trust model.

Configure Python startup

For Python hosted agents, set PYTHONNOUSERSITE to "1" in the agent's runtime environment. This setting disables Python's user-site package directory, which can otherwise reside beneath $HOME. Configure it for both source-code deployments and Python container images.

Add the setting to the existing agent service's env map:

services:
  my-agent:
    host: azure.ai.agent
    kind: hosted
    env:
      PYTHONNOUSERSITE: "1"

For SDK or REST deployments, include "PYTHONNOUSERSITE": "1" in the hosted agent definition's environment_variables map. This setting applies to the deployed Python runtime, regardless of the language you use to call the deployment API.

Configure the variable in the runtime environment before the Python interpreter starts. Setting os.environ or loading a .env file inside your Python application is too late to change that interpreter's startup behavior.

For a Python container image that you also run directly outside azd, set ENV PYTHONNOUSERSITE=1 before its Python startup command so that those runs use the same default. Keep the agent service's env setting for hosted deployment.

To check the interpreter's configuration in the same environment, run python -c "import site; print(site.ENABLE_USER_SITE)". The result should be False.

Install dependencies into the deployment's virtual environment or container image, not with pip install --user. Packages installed only in the user-site directory aren't available with this setting. Test imports and agent startup before promoting the new version.

You configure this setting; the platform doesn't inject it. It disables user-site loading, but doesn't prevent explicit imports, imports from the working directory, or tools that intentionally execute code. It doesn't remove upload-writable directories from PYTHONPATH. Keep those import paths and trusted configuration sources separate from uploaded data.

To apply the setting to an existing agent, create a new version with the updated environment and select that version for the endpoint. Existing sessions remain bound to their original version. Validate a new session on the updated version; changing documentation or local configuration doesn't update previously deployed versions. See Manage hosted agents.

Configure .NET application loading

.NET doesn't have a single environment variable equivalent to PYTHONNOUSERSITE that makes $HOME untrusted. Publish the application during the build, keep the published files outside upload-writable directories, and start the published DLL instead of restoring or building from session files.

The C# Hello World sample uses a multistage .NET 10 image and publishes its application to /app. The following Dockerfile uses that layout with an absolute entry-point path. Use the directory containing the sample's project file as the build context.

FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -r linux-musl-x64 --self-contained false \
    -p:PublishReadyToRun=true -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
WORKDIR /app
COPY --from=build /app .
EXPOSE 8088
ENTRYPOINT ["dotnet", "/app/hello-world.dll"]

The build produces the application and dependencies in /app; startup doesn't run dotnet build, dotnet restore, or dotnet run. Locating files outside $HOME isn't sufficient by itself: keep /app and runtime loading settings protected from upload callers.

In application code, use AppContext.BaseDirectory for image-bundled resources and $HOME for session data. Don't use the session working directory to locate trusted resources. The C# file-tools sample separates these roots.

For example, the following C# code reads both files as text, without loading either as executable code. It requires the sample's resources/contoso_q1_2026_report.txt in the published output and a data.csv upload in the session home.

using System;
using System.IO;

string bundledRoot = Path.Combine(AppContext.BaseDirectory, "resources");
string sessionRoot = Environment.GetEnvironmentVariable("HOME")
    ?? throw new InvalidOperationException("HOME is not set.");

string bundledReport = File.ReadAllText(
    Path.Combine(bundledRoot, "contoso_q1_2026_report.txt"));
string uploadedData = File.ReadAllText(
    Path.Combine(sessionRoot, "data.csv"));

Console.WriteLine($"Bundled report: {bundledReport.Length} characters");
Console.WriteLine($"Uploaded data: {uploadedData.Length} characters");

Reference: AppContext.BaseDirectory, Environment.GetEnvironmentVariable, Path.Combine, and File.ReadAllText.

AppContext.BaseDirectory selects a resource location; it doesn't validate file trust or constrain other loaders. Keep custom assembly, native library, plugin, and configuration loading paths out of upload-writable directories. If you configure DOTNET_STARTUP_HOOKS, DOTNET_ADDITIONAL_DEPS, or DOTNET_SHARED_STORE, use only deployment-controlled locations. See .NET dependency probing and .NET environment variables.

Changing DOTNET_CLI_HOME only changes the location of CLI supporting files; it doesn't prevent assembly loading from $HOME. Disabling diagnostics or adding a filesystem noexec option isn't a substitute for this separation.

For source-code deployments, use the published DLL as codeConfiguration.entryPoint with the supported .NET runtime. The container example doesn't configure the managed source-code build image. In either mode, review skills, harnesses, and other framework features that intentionally consume session files before changing their paths.

Review platform environment variables

The Foundry platform automatically injects the following environment variables into every hosted agent container at startup. These variables are read-only. Your agent code should consume them but never override them.

Foundry variables

Variable Description
FOUNDRY_HOSTING_ENVIRONMENT The platform injects a nonempty value when hosting in Foundry. Check for this variable to determine if the container is running in a Foundry context.
FOUNDRY_AGENT_NAME The agent's name, such as my-weather-agent.
FOUNDRY_AGENT_ID The ID of the agent.
FOUNDRY_AGENT_VERSION The agent's version.
FOUNDRY_PROJECT_ENDPOINT Foundry project endpoint, such as https://{account}.services.ai.azure.com/api/projects/{project}.
FOUNDRY_AGENT_SESSION_ID The agent's session ID.
FOUNDRY_PROJECT_ARM_ID The project's full ARM resource ID.
FOUNDRY_HOSTING_ENVIRONMENT Set to 1 when the agent is deployed in Foundry. Use this value to determine whether your agent is running in Foundry or another environment, such as a local environment.

Note

Reserved prefix: The platform reserves all AGENT_* and FOUNDRY_* environment variables for platform use and automatically injects them into the container.

During local development with azd ai agent run, azd sets FOUNDRY_PROJECT_ENDPOINT automatically from your azd environment so your agent code works the same locally and when deployed.

Network variables

Variable Default Description
PORT 8088 HTTP listen port. Set only when the platform requires a non-default port.
SSE_KEEPALIVE_INTERVAL Disabled SSE keep-alive comment interval in seconds.

Observability variables

Variable Description
APPLICATIONINSIGHTS_CONNECTION_STRING Azure Monitor connection string for telemetry export.
OTEL_EXPORTER_OTLP_ENDPOINT OTLP collector endpoint for OpenTelemetry.

Session file variables

Variable Default Description
HOME /home/session Filesystem path to persisted session data.

Add a new environment variable

  1. Define the variable in the env map for the azure.ai.agent service in azure.yaml.

    services:
  my-agent:
    host: azure.ai.agent
    environmentVariables:
      MY_API_URL: ${MY_API_URL}

  2. Set the value in your azd environment.

    azd env set MY_API_URL=https://api.example.com

  3. Redeploy the application.

    azd deploy

For local development, azd ai agent run also resolves ${VAR} from the azd environment, so the same setup works locally.

Handle sensitive values

For secrets such as API keys and tokens, don't bake values into your image or commit them to azure.yaml. Store secrets in a Foundry project connection, and reference connection values from your configuration when the platform supports that connection type.

Use secrets during local development

For local runs with azd ai agent run, set values as azd environment variables and reference them in azure.yaml. azd stores environment values in .azure/<env>/.env, which is gitignored by default, so they stay out of source control.

azd env set OPENAI_KEY <value>

services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

For secrets that shouldn't live in a local .env file, store them in a Foundry project connection and reference them with a ${{connections.<name>.credentials.<field>}} placeholder. The platform resolves the placeholder at runtime. See Run a hosted agent locally with the Azure Developer CLI for the local run workflow.

Related content

  • Last updated on