Azure AI Foundry Environment Variables Reference

Status: Production Ready ✅
Last Updated: 2024-10-29
Owner: Infrastructure Team

Overview

The Microsoft Agent Framework AzureAIAgentClient uses these environment variables for Azure AI Foundry connectivity in VNet-protected deployments with managed identity authentication.

Required Variables

1. AZURE_AI_PROJECT_ENDPOINT

• Purpose: AI Foundry Project endpoint URL for agent operations
• Format: https://<ai-project-name>.cognitiveservices.azure.com
• Source: substrate.bicep output aiProjectEndpoint
• Used By: AzureAIAgentClient initialization
• Example: https://ldfdev8-dev-aiproject.cognitiveservices.azure.com
• Set By: Apps layer Bicep deployment

Why This Matters: The SDK reads this internally to connect to AI Foundry Project.

2. AZURE_AI_SERVICES_ENDPOINT (Optional)

• Purpose: AI Services endpoint for direct API calls
• Format: https://<ai-services-name>.cognitiveservices.azure.com
• Source: substrate.bicep output aiServicesEndpoint
• Used By: Legacy code, may not be needed for AzureAIAgentClient
• Example: https://ldfdev8-dev-ai.cognitiveservices.azure.com

Note: AzureAIAgentClient primarily uses AZURE_AI_PROJECT_ENDPOINT.

3. AZURE_AI_MODEL_DEPLOYMENT_NAME

• Purpose: Model deployment name for agent creation
• Format: Simple string (e.g., gpt-4o, gpt-4o-mini, gpt-4-turbo)
• Source: ai-models.bicep output deploymentNames
• Used By: Agent create_agent() method, NOT client initialization
• Example: gpt-4o

Note: This is NOT used by the client constructor, only when creating agents.

4. AZURE_CLIENT_ID (Critical for Managed Identity)

• Purpose: User-assigned managed identity client ID for authentication
• Format: UUID (e.g., 12345678-1234-1234-1234-123456789012)
• Source: foundation.bicep output managedIdentityClientId
• Used By: DefaultAzureCredential to select specific managed identity
• Example: a3f5b8c9-1234-5678-90ab-cdef12345678

Why Critical: Without this, DefaultAzureCredential might try wrong identity or fail.

Network Configuration

5. APP_GATEWAY_URL (Optional)

• Purpose: Application Gateway public URL for CORS configuration
• Format: https://<fqdn>
• Source: Deployment script auto-detection
• Used By: API CORS middleware auto-configuration
• Example: https://ldfdev8-dev-appgw.eastus2.cloudapp.azure.com

Verification Commands

Check Environment Variables Inside Container

RG="ldfdev8-rg"
CONTAINER_GROUP="${RG%-rg}-dev-apps"

az container exec \
  --resource-group "$RG" \
  --name "$CONTAINER_GROUP" \
  --container-name api \
  --exec-command "env | grep AZURE | sort"

Expected Output:

AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
AZURE_AI_PROJECT_ENDPOINT=https://ldfdev8-dev-aiproject.cognitiveservices.azure.com
AZURE_AI_SERVICES_ENDPOINT=https://ldfdev8-dev-ai.cognitiveservices.azure.com
AZURE_CLIENT_ID=a3f5b8c9-1234-5678-90ab-cdef12345678

Test Managed Identity Token Acquisition

az container exec \
  --resource-group "$RG" \
  --name "$CONTAINER_GROUP" \
  --container-name api \
  --exec-command "python3 -c \"
from azure.identity import DefaultAzureCredential
import os
print(f'AZURE_CLIENT_ID: {os.getenv(\\\"AZURE_CLIENT_ID\\\", \\\"NOT SET\\\")}')
cred = DefaultAzureCredential()
token = cred.get_token('https://cognitiveservices.azure.com/.default')
print(f'✅ Token acquired successfully: {token.token[:20]}...')
\""

Expected Output:

AZURE_CLIENT_ID: a3f5b8c9-1234-5678-90ab-cdef12345678
✅ Token acquired successfully: eyJ0eXAiOiJKV1QiLCJ...

Test AI Foundry Endpoint Connectivity

# Extract endpoint from environment variable
ENDPOINT=$(az container show \
  --resource-group "$RG" \
  --name "$CONTAINER_GROUP" \
  --query "containers[?name=='api'].environmentVariables[?name=='AZURE_AI_PROJECT_ENDPOINT'].value | [0]" \
  -o tsv)

# Test connectivity from container
az container exec \
  --resource-group "$RG" \
  --name "$CONTAINER_GROUP" \
  --container-name api \
  --exec-command "curl -v $ENDPOINT"

Expected: HTTP 200 OK or 401 Unauthorized (auth required, but endpoint reachable)

Troubleshooting

Error: "context manager not available"

Cause: Missing service endpoint on ACI subnet OR network firewall blocking access

Diagnosis:

# Check if ACI subnet has Microsoft.CognitiveServices service endpoint
az network vnet subnet show \
  --resource-group "$RG" \
  --vnet-name "${RG%-rg}-vnet" \
  --name "aci-subnet" \
  --query "serviceEndpoints[?service=='Microsoft.CognitiveServices']" \
  -o table

# If empty → Missing service endpoint

Fix:

# Service endpoints defined in networking.bicep (lines 660-665)
# Redeploy Foundation layer:
./infrastructure/scripts/deploy-foundation.sh dev "$RG"

Prevention: Service endpoints are now included by default in ACI subnet configuration.

Error: "Forbidden" or "Access Denied"

Cause: Missing RBAC role "Azure AI User" on managed identity

Diagnosis:

IDENTITY_PRINCIPAL=$(az identity show \
  -n "${RG%-rg}-identity" \
  -g "$RG" \
  --query principalId -o tsv)

# Check for Azure AI User role
az role assignment list \
  --assignee "$IDENTITY_PRINCIPAL" \
  --query "[?contains(roleDefinitionName, 'Azure AI')].roleDefinitionName" \
  -o tsv

# Should show:
# Azure AI Administrator
# Azure AI User
# Azure AI Administrator  
# Azure AI User

# ❌ If missing "Azure AI User" → This is the problem

Fix: Add Azure AI User role (already implemented in ai-services.bicep lines 560-574)

# Redeploy Substrate layer (adds missing roles):
./infrastructure/scripts/deploy-substrate.sh dev "$RG"

Explanation: - "Azure AI Administrator" = management plane (create/delete resources) - "Azure AI User" = data plane (execute agents, invoke models) - Both are required for managed identity runtime operations

Error: "Invalid endpoint format"

Cause: AZURE_AI_PROJECT_ENDPOINT has wrong URL format

Diagnosis:

# Check actual endpoint value
az container show \
  --resource-group "$RG" \
  --name "$CONTAINER_GROUP" \
  --query "containers[?name=='api'].environmentVariables[?name=='AZURE_AI_PROJECT_ENDPOINT'].value | [0]" \
  -o tsv

Expected Formats: - Cognitive Services: https://<name>.cognitiveservices.azure.com - AI Foundry: https://<region>.api.azureml.ms

Fix: Check substrate.bicep output definition for aiProjectEndpoint (should use aiFoundryProject.properties.endpoint)

Error: Environment Variable Not Set

Symptom: Python code shows None or "NOT SET" for AZURE_* variables

Fix:

# Check Bicep parameter passing in apps.bicep lines 100-112
# Verify outputs from Substrate layer:
az deployment group show \
  --name "substrate-<timestamp>" \
  --resource-group "$RG" \
  --query "properties.outputs.{Project:aiProjectEndpoint.value, Services:aiServicesEndpoint.value}" \
  -o table

# If outputs are missing → Substrate deployment issue
./infrastructure/scripts/deploy-substrate.sh dev "$RG"

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│  ACI Container (API)                                    │
│                                                         │
│  Environment Variables:                                 │
│  ├─ AZURE_CLIENT_ID ──────────┐                        │
│  ├─ AZURE_AI_PROJECT_ENDPOINT─┤                        │
│  └─ AZURE_AI_MODEL_DEPLOYMENT─┘                        │
│                                │                        │
│  Python Code:                  │                        │
│  ┌────────────────────────┐   │                        │
│  │ DefaultAzureCredential │◄──┘ (uses AZURE_CLIENT_ID) │
│  └───────────┬────────────┘                            │
│              │ Get token for https://cognitiveservices │
│              ▼                                          │
│  ┌────────────────────────┐                            │
│  │ AzureAIAgentClient     │                            │
│  │ (reads AZURE_AI_       │                            │
│  │  PROJECT_ENDPOINT)     │                            │
│  └───────────┬────────────┘                            │
└──────────────┼──────────────────────────────────────────┘
               │ HTTPS (via service endpoint)
               ▼
┌──────────────────────────────────────────────┐
│  Azure AI Foundry Project                    │
│  (Private VNet access via service endpoint)  │
│                                              │
│  RBAC:                                       │
│  ├─ Azure AI Administrator (manage)         │
│  └─ Azure AI User (execute) ✅ Required     │
└──────────────────────────────────────────────┘

References

• Microsoft Agent Framework Documentation
• Azure AI Foundry RBAC Guide
• DefaultAzureCredential Documentation
• RBAC Setup Guide - Complete role assignments reference

---

Related Documentation: - RBAC Setup Guide - Role assignments and verification - ADR-047: Layer-Specific RBAC - AI Security Architecture