Skip to content

4-Configure-AI-Template.md

Latest commit

 

History

History
380 lines (319 loc) · 12.6 KB

4-Configure-AI-Template.md

File metadata and controls

380 lines (319 loc) · 12.6 KB

4. Configure a Template

!!! tip "BY THE END OF THIS MODULE YOU WILL BE ABLE TO"

- [ ] Understand the purpose of `azure.yaml`
- [ ] Understand the structure of `azure.yaml`
- [ ] Understand the value of azd lifecycle `hooks`
- [ ] **Lab 4:** Explore and modify environment variables

!!! prompt "What is the azure.yaml file do? Use a codefence and explain it line by line"

  The `azure.yaml` file is the **configuration file for Azure Developer CLI (azd)**. It defines how your application should be deployed to Azure, including infrastructure, services, deployment hooks, and environment variables.

1. Purpose and Functionality

This azure.yaml file serves as the deployment blueprint for an AI agent application that:

  1. Validates environment before deployment
  2. Provisions Azure AI services (AI Hub, AI Project, Search, etc.)
  3. Deploys a Python application to Azure Container Apps
  4. Configures AI models for both chat and embedding functionality
  5. Sets up monitoring and tracing for the AI application
  6. Handles both new and existing Azure AI project scenarios

The file enables one-command deployment (azd up) of a complete AI agent solution with proper validation, provisioning, and post-deployment configuration.

??? info "Expand To View: azure.yaml"

  The `azure.yaml` file defines how Azure Developer CLI should deploy and manage this AI Agent application in Azure. Let's break it down line-by-line.

  ```yaml title="" linenums="0"

  # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
  # TODO: do we need hooks? 
  # TODO: do we need all of the variables?

  name: azd-get-started-with-ai-agents
  metadata:
  template: azd-get-started-with-ai-agents@1.0.2
  requiredVersions:
  azd: ">=1.14.0"

  hooks:
  preup:
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/validate_env_vars.sh; ./scripts/validate_env_vars.sh
        interactive: true
        continueOnError: false
  windows:
        shell: pwsh
        run: ./scripts/validate_env_vars.ps1
        interactive: true
        continueOnError: false      
  postprovision:
  windows:
        shell: pwsh
        run: ./scripts/write_env.ps1
        continueOnError: true
        interactive: true
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/write_env.sh; ./scripts/write_env.sh;
        continueOnError: true
        interactive: true
  postdeploy:
  windows:
        shell: pwsh
        run: ./scripts/postdeploy.ps1
        continueOnError: true
        interactive: true
  posix:
        shell: sh
        run: chmod u+r+x ./scripts/postdeploy.sh; ./scripts/postdeploy.sh;
        continueOnError: true
        interactive: true
  services:
  api_and_frontend:
  project: ./src
  language: py
  host: containerapp
  docker:
        image: api_and_frontend
        remoteBuild: true
  pipeline:
  variables:
  - AZURE_RESOURCE_GROUP
  - AZURE_AIHUB_NAME
  - AZURE_AIPROJECT_NAME
  - AZURE_AISERVICES_NAME
  - AZURE_SEARCH_SERVICE_NAME
  - AZURE_APPLICATION_INSIGHTS_NAME
  - AZURE_CONTAINER_REGISTRY_NAME
  - AZURE_KEYVAULT_NAME
  - AZURE_STORAGE_ACCOUNT_NAME
  - AZURE_LOG_ANALYTICS_WORKSPACE_NAME
  - USE_CONTAINER_REGISTRY
  - USE_APPLICATION_INSIGHTS
  - USE_AZURE_AI_SEARCH_SERVICE
  - AZURE_AI_AGENT_NAME
  - AZURE_AI_AGENT_ID
  - AZURE_AI_AGENT_DEPLOYMENT_NAME
  - AZURE_AI_AGENT_DEPLOYMENT_SKU
  - AZURE_AI_AGENT_DEPLOYMENT_CAPACITY
  - AZURE_AI_AGENT_MODEL_NAME
  - AZURE_AI_AGENT_MODEL_FORMAT
  - AZURE_AI_AGENT_MODEL_VERSION
  - AZURE_AI_EMBED_DEPLOYMENT_NAME
  - AZURE_AI_EMBED_DEPLOYMENT_SKU
  - AZURE_AI_EMBED_DEPLOYMENT_CAPACITY
  - AZURE_AI_EMBED_MODEL_NAME
  - AZURE_AI_EMBED_MODEL_FORMAT
  - AZURE_AI_EMBED_MODEL_VERSION
  - AZURE_AI_EMBED_DIMENSIONS
  - AZURE_AI_SEARCH_INDEX_NAME
  - AZURE_EXISTING_AIPROJECT_RESOURCE_ID
  - AZURE_EXISTING_AIPROJECT_ENDPOINT
  - AZURE_EXISTING_AGENT_ID
  - ENABLE_AZURE_MONITOR_TRACING
  - AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED
  ```

2. Deconstructing The File

Let's go through the file section by section, to understand what it does - and why.

2.1 Header and Schema (1-3)

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
  • Line 1: Provides YAML language server schema validation for IDE support and IntelliSense

2.2 Project Metadata (5-10)

name: azd-get-started-with-ai-agents
metadata:
  template: azd-get-started-with-ai-agents@1.0.2
requiredVersions:
  azd: ">=1.14.0"
  • Line 5: Defines the project name used by Azure Developer CLI
  • Lines 6-7: Specifies this is based on a template version 1.0.2
  • Lines 8-9: Requires Azure Developer CLI version 1.14.0 or higher

2.3 Deploy Hooks (11-40)

hooks:
  preup:
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/validate_env_vars.sh; ./scripts/validate_env_vars.sh
      interactive: true
      continueOnError: false
    windows:
      shell: pwsh
      run: ./scripts/validate_env_vars.ps1
      interactive: true
      continueOnError: false

  • Lines 11-20: Pre-deployment hook - runs before azd up

    - On Unix/Linux: Makes validation script executable and runs it
- On Windows: Runs PowerShell validation script
- Both are interactive and will stop deployment if they fail

  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/write_env.ps1
      continueOnError: true
      interactive: true
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/write_env.sh; ./scripts/write_env.sh;
      continueOnError: true
      interactive: true

  • Lines 21-30: Post-provision hook - runs after Azure resources are created

    • Executes environment variable writing scripts
    • Continues deployment even if these scripts fail (continueOnError: true)
  postdeploy:
    windows:
      shell: pwsh
      run: ./scripts/postdeploy.ps1
      continueOnError: true
      interactive: true
    posix:
      shell: sh
      run: chmod u+r+x ./scripts/postdeploy.sh; ./scripts/postdeploy.sh;
      continueOnError: true
      interactive: true

  • Lines 31-40: Post-deploy hook - runs after application deployment

    • Executes final setup scripts
    • Continues even if scripts fail

2.4 Service Config (41-48)

This configures the application service you are deploying.

services:
  api_and_frontend:
    project: ./src
    language: py
    host: containerapp
    docker:
      image: api_and_frontend
      remoteBuild: true

  • Line 42: Defines a service named "api_and_frontend"

  • Line 43: Points to the ./src directory for source code

  • Line 44: Specifies Python as the programming language

  • Line 45: Uses Azure Container Apps as the hosting platform

  • Lines 46-48: Docker configuration

    - Uses "api_and_frontend" as the image name
- Builds the Docker image remotely in Azure (not locally)

2.5 Pipeline Variables (49-76)

These are variables to help you run azd in CI/CD pipelines for automation

pipeline:
  variables:
    - AZURE_RESOURCE_GROUP
    - AZURE_AIHUB_NAME
    - AZURE_AIPROJECT_NAME
    - AZURE_AISERVICES_NAME
    - AZURE_SEARCH_SERVICE_NAME
    - AZURE_APPLICATION_INSIGHTS_NAME
    - AZURE_CONTAINER_REGISTRY_NAME
    - AZURE_KEYVAULT_NAME
    - AZURE_STORAGE_ACCOUNT_NAME
    - AZURE_LOG_ANALYTICS_WORKSPACE_NAME
    - USE_CONTAINER_REGISTRY
    - USE_APPLICATION_INSIGHTS
    - USE_AZURE_AI_SEARCH_SERVICE
    - AZURE_AI_AGENT_NAME
    - AZURE_AI_AGENT_ID
    - AZURE_AI_AGENT_DEPLOYMENT_NAME
    - AZURE_AI_AGENT_DEPLOYMENT_SKU
    - AZURE_AI_AGENT_DEPLOYMENT_CAPACITY
    - AZURE_AI_AGENT_MODEL_NAME
    - AZURE_AI_AGENT_MODEL_FORMAT
    - AZURE_AI_AGENT_MODEL_VERSION
    - AZURE_AI_EMBED_DEPLOYMENT_NAME
    - AZURE_AI_EMBED_DEPLOYMENT_SKU
    - AZURE_AI_EMBED_DEPLOYMENT_CAPACITY
    - AZURE_AI_EMBED_MODEL_NAME
    - AZURE_AI_EMBED_MODEL_FORMAT
    - AZURE_AI_EMBED_MODEL_VERSION
    - AZURE_AI_EMBED_DIMENSIONS
    - AZURE_AI_SEARCH_INDEX_NAME
    - AZURE_EXISTING_AIPROJECT_RESOURCE_ID
    - AZURE_EXISTING_AIPROJECT_ENDPOINT
    - AZURE_EXISTING_AGENT_ID
    - ENABLE_AZURE_MONITOR_TRACING
    - AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED

This section defines environment variables used during deployment, organized by category:

  • Azure Resource Names (Lines 51-60): - Core Azure service resource names e.g, Resource Group, AI Hub, AI Project, etc.-
  • Feature Flags (Lines 61-63): - Boolean variables to enable/disable specific Azure services
  • AI Agent Configuration (Lines 64-71): - Configuration for main AI agent including name, ID, deployment settings, model details-
  • AI Embedding Configuration (Lines 72-79): - Configuration for the embedding model used for vector search
  • Search and Monitoring (Lines 80-84): - Search index name, existing resource IDs, and monitoring/tracing settings

3. Know Env Variables

The following environment variables control your deployment's configuration and behavior, organized by their primary purpose. Most variables have sensible defaults, but you can customize them to match your specific requirements or existing Azure resources.

3.1 Required Variables

# Core Azure Configuration
AZURE_ENV_NAME                    # Environment name (used in resource naming)
AZURE_LOCATION                    # Deployment region
AZURE_SUBSCRIPTION_ID             # Target subscription
AZURE_RESOURCE_GROUP              # Resource group name
AZURE_PRINCIPAL_ID                # User principal for RBAC

# Resource Names (Auto-generated if not specified)
AZURE_AIHUB_NAME                  # Microsoft Foundry hub name
AZURE_AIPROJECT_NAME              # AI project name
AZURE_AISERVICES_NAME             # AI services account name
AZURE_STORAGE_ACCOUNT_NAME        # Storage account name
AZURE_CONTAINER_REGISTRY_NAME     # Container registry name
AZURE_KEYVAULT_NAME               # Key Vault name (if used)

3.2 Model Configuration

# Chat Model Configuration
AZURE_AI_AGENT_MODEL_NAME         # Default: gpt-4.1-mini
AZURE_AI_AGENT_MODEL_FORMAT       # Default: OpenAI (or Microsoft)
AZURE_AI_AGENT_MODEL_VERSION      # Default: latest available
AZURE_AI_AGENT_DEPLOYMENT_NAME    # Deployment name for chat model
AZURE_AI_AGENT_DEPLOYMENT_SKU     # Default: Standard
AZURE_AI_AGENT_DEPLOYMENT_CAPACITY # Default: 80 (thousands of TPM)

# Embedding Model Configuration  
AZURE_AI_EMBED_MODEL_NAME         # Default: text-embedding-3-small
AZURE_AI_EMBED_MODEL_FORMAT       # Default: OpenAI
AZURE_AI_EMBED_MODEL_VERSION      # Default: latest available
AZURE_AI_EMBED_DEPLOYMENT_NAME    # Deployment name for embeddings
AZURE_AI_EMBED_DEPLOYMENT_SKU     # Default: Standard
AZURE_AI_EMBED_DEPLOYMENT_CAPACITY # Default: 50 (thousands of TPM)

# Agent Configuration
AZURE_AI_AGENT_NAME               # Agent display name
AZURE_EXISTING_AGENT_ID           # Use existing agent (optional)

3.3 Feature Toggle

# Optional Services
USE_APPLICATION_INSIGHTS         # Default: true
USE_AZURE_AI_SEARCH_SERVICE      # Default: false
USE_CONTAINER_REGISTRY           # Default: true

# Monitoring and Tracing
ENABLE_AZURE_MONITOR_TRACING     # Default: false
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED # Default: false

# Search Configuration
AZURE_AI_SEARCH_INDEX_NAME       # Search index name
AZURE_SEARCH_SERVICE_NAME        # Search service name

3.4 AI Project Configuration

# Use Existing Resources
AZURE_EXISTING_AIPROJECT_RESOURCE_ID    # Full resource ID of existing AI project
AZURE_EXISTING_AIPROJECT_ENDPOINT       # Endpoint URL of existing project

3.5 Check Your Variables

Use the Azure Developer CLI to view and manage your environment variables:

# View all environment variables for current environment
azd env get-values

# Get a specific environment variable
azd env get-value AZURE_ENV_NAME

# Set an environment variable
azd env set AZURE_LOCATION eastus

# Set multiple variables from a .env file
azd env set --from-file .env
⚡