Shiva S (Shivakishore14) · Oct 23, 2026 · Oct 23, 2026
@@ -7,6 +7,8 @@
 #     python/
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 # Copy the in-tree agent-framework packages we need. Order matters for editable

@@ -68,6 +68,12 @@ Follow the instructions in the
 [Running the Agent Host Locally](../../foundry-hosted-agents//README.md#running-the-agent-host-locally)
 section of the README in the Foundry Hosted Agent directory.
 
+The image and hosted deployment definitions set `PYTHONNOUSERSITE=1`; see the
+[Python startup configuration](../../foundry-hosted-agents/README.md#python-startup-configuration).
+This controls Python user-site loading only and does not
+change the hypervisor requirement or make this sample supported on the default
+Foundry runtime.
+
 ## Interacting with the agent
 
 Send a POST request to the server with a JSON body containing an `"input"`

@@ -16,6 +16,8 @@ template:
     - protocol: responses
       version: 1.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:

@@ -19,5 +19,7 @@ resources:
     cpu: "1"
     memory: 2Gi
 environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: gpt-4.1-mini
@@ -5,6 +5,30 @@ This directory contains samples that demonstrate how to use hosted [Agent Framew
 > [IMPORTANT] Migrating from Protocol version 1.0.0 to 2.0.0: Foundry Hosting Agents service has been updated to use Protocol version 2.0.0. If your application is using Protocol version 1.0.0, please upgrade to Protocol version 2.0.0 in your `agent.manifest.yaml` or `agent.yaml` and upgrade to the latest `agent-framework-foundry-hosting` package. `agent-framework-foundry-hosting==1.0.0a260625` is the last version that supports Protocol version 1.0.0.
 >
 > The `agent-framework-foundry-hosting` Python API surface is intended to remain stable, but protocol 1.0.0 and 2.0.0 are incompatible.
+
+## Python startup configuration
+
+The deployment YAML files in these samples explicitly configure
+`PYTHONNOUSERSITE` with the string value `"1"` before the remote Python
+interpreter starts. Each Python Dockerfile also sets `ENV PYTHONNOUSERSITE=1`
+so directly running an image without its YAML keeps the same startup setting.
+The Telegram direct-code sample sets it in `azure.yaml` instead.
+
+This setting is configured by the customer in the sample deployment, not
+automatically injected by Foundry or Agent Framework. It disables Python
+user-site loading, not all code execution, and does not configure other
+language runtimes. Existing deployments need a newly deployed agent version
+to pick up the setting; editing a local YAML file does not update a running
+version.
+
+Install dependencies in a virtual environment or the container image's
+system site-packages, not with `pip install --user`. The samples' `pip` and
+`uv` installation paths do not require user-site packages.
+
+Keep this setting in the deployment environment or Python Dockerfile, rather
+than adding it to individual run commands. Setting `os.environ` or loading a
+`.env` file from application code is too late for Python startup.
+
 ## Samples
 
 ### Responses API

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -107,6 +107,9 @@ native workflow API is published. From `python/`, run:
 uv run --no-sync python samples/04-hosting/foundry-hosted-agents/invocations/basic/workflow.py
 ```
 
+For deployment environment settings, see the
+[Python startup configuration](../../README.md#python-startup-configuration).
+
 After that release, the script's PEP 723 metadata also supports
 `uv run --script --prerelease=allow workflow.py`. Do not change a
 `pyproject.toml` to install sample-only imports. This entrypoint does not read

@@ -15,6 +15,8 @@ template:
     - protocol: invocations
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:

@@ -7,3 +7,6 @@ protocols:
 resources:
   cpu: "0.25"
   memory: "0.5Gi"
+environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -15,6 +15,8 @@ template:
     - protocol: invocations
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:

@@ -7,3 +7,6 @@ protocols:
 resources:
   cpu: "0.25"
   memory: "0.5Gi"
+environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
@@ -20,6 +20,8 @@ services:
       Telegram bot routed through API Management to an Agent Framework agent
       using the Foundry Invocations 2.0 protocol.
     environmentVariables:
+      - name: PYTHONNOUSERSITE
+        value: "1"
       - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
         value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
       - name: AZURE_COSMOS_ENDPOINT

@@ -22,6 +22,7 @@ def test_direct_code_invocations_2_configuration() -> None:
         "runtime": "python_3_13",
     }
     assert service["protocols"] == [{"protocol": "invocations", "version": "2.0.0"}]
+    assert {"name": "PYTHONNOUSERSITE", "value": "1"} in service["environmentVariables"]
 
 
 def test_dependencies_use_sample_local_pyproject() -> None:

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -18,6 +18,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: AZURE_SEARCH_ENDPOINT

@@ -8,6 +8,8 @@ resources:
   cpu: "0.25"
   memory: "0.5Gi"
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: AZURE_SEARCH_ENDPOINT

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -23,6 +23,8 @@ downstream service ID.
 
 Run one entry point at a time. The deployment manifest targets `main.py`; select another script to deploy a different
 mode. Set `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL` in `.env`, then run `python main.py`.
+For deployment environment configuration, see the
+[Python startup configuration](../../README.md#python-startup-configuration).
 Follow the [parent hosting guide](../../README.md) for local and deployed setup.
 
 ## Outer response storage and background

@@ -15,6 +15,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:

@@ -8,5 +8,7 @@ resources:
   cpu: "0.25"
   memory: "0.5Gi"
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -15,6 +15,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: AZURE_COSMOS_ENDPOINT

@@ -8,6 +8,8 @@ resources:
   cpu: "0.25"
   memory: "0.5Gi"
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: AZURE_COSMOS_ENDPOINT

@@ -6,6 +6,8 @@ FROM mcr.microsoft.com/dotnet/runtime:10.0 AS dotnet
 
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 # libicu is required by the .NET runtime for globalization support.

@@ -17,6 +17,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:

@@ -8,5 +8,7 @@ resources:
   cpu: '0.25'
   memory: '0.5Gi'
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -15,6 +15,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: TOOLBOX_NAME

@@ -8,6 +8,8 @@ resources:
   cpu: "0.25"
   memory: "0.5Gi"
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: TOOLBOX_NAME

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -18,6 +18,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: MEMORY_STORE_NAME

@@ -8,6 +8,8 @@ resources:
   cpu: "0.25"
   memory: "0.5Gi"
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: MEMORY_STORE_NAME

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app

@@ -198,6 +198,9 @@ azd deploy --all
 azd ai agent run
 ```
 
+For deployment environment settings, see the
+[Python startup configuration](../../README.md#python-startup-configuration).
+
 The agent host will start on `http://localhost:8088`.
 
 #### Invoke the local agent

@@ -15,6 +15,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: TOOLBOX_ENDPOINT

@@ -7,6 +7,8 @@ resources:
   cpu: "0.25"
   memory: 0.5Gi
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: TOOLBOX_ENDPOINT

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app

@@ -27,6 +27,8 @@ template:
     cpu: "0.25"
     memory: 0.5Gi
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: TOOLBOX_ENDPOINT

@@ -8,6 +8,8 @@ resources:
   cpu: "0.25"
   memory: 0.5Gi
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: TOOLBOX_ENDPOINT

@@ -1,5 +1,7 @@
 FROM python:3.12-slim
 
+ENV PYTHONNOUSERSITE=1
+
 WORKDIR /app
 
 COPY . user_agent/

@@ -15,6 +15,8 @@ template:
     - protocol: responses
       version: 2.0.0
   environment_variables:
+    - name: PYTHONNOUSERSITE
+      value: "1"
     - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
       value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
     - name: GITHUB_PAT

@@ -7,6 +7,8 @@ resources:
   cpu: "0.25"
   memory: 0.5Gi
 environment_variables:
+  - name: PYTHONNOUSERSITE
+    value: "1"
   - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
     value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
   - name: GITHUB_PAT