Edit

Deploy to a Microsoft Foundry or Azure Machine Learning studio online endpoint

The Azure Developer CLI (azd) enables you to deploy to an Azure Machine Learning studio or Microsoft Foundry online endpoint. azd supports the following features, which are described in the sections ahead:

Prerequisites

To work with Microsoft Foundry or Azure Machine Learning studio online endpoints, you need:

The Foundry Starter template can help create all the required infrastructure to get started with Foundry endpoints.

Configure the online endpoint

Configure support for online endpoints in the services section of the azure.yaml file:

  • Set the host value to ai.endpoint.
  • The config section for ai.endpoint supports the following configurations:
    • workspace: The name of the Microsoft Foundry workspace. Supports azd environment variable substitutions and syntax.
      • If not specified, azd looks for an environment variable with the name AZUREAI_PROJECT_NAME.
    • environment: Optional custom configuration for ML environments. azd creates a new environment version from the referenced YAML file definition.
    • flow: Optional custom configuration for flows. azd creates a new prompt flow from the specified file path.
    • model: Optional custom configuration for ML models. azd creates a new model version from the referenced YAML file definition.
    • deployment: Required configuration for online endpoint deployments. azd creates a new online deployment to the associated online endpoint from the referenced YAML file definition.

Consider the following sample azure.yaml file that configures these features:

name: contoso-chat
metadata:
  template: contoso-chat@0.0.1-beta
services:
  chat:
    # Referenced new ai.endpoint host type
    host: ai.endpoint
    # New config flow for AI project configuration
    config:
      # The name of the Foundry workspace
      workspace: ${AZUREAI_PROJECT_NAME}
      # Optional: Path to custom ML environment manifest
      environment:
        path: deployment/docker/environment.yml
      # Optional: Path to your prompt flow folder that contains the flow manifest
      flow:
        path: ./contoso-chat
      # Optional: Path to custom model manifest
      model:
        path: deployment/chat-model.yaml
        overrides:
          "properties.azureml.promptflow.source_flow_id": ${AZUREAI_FLOW_NAME}
      # Required: Path to deployment manifest
      deployment:
        path: deployment/chat-deployment.yaml
        environment:
          PRT_CONFIG_OVERRIDE: deployment.subscription_id=${AZURE_SUBSCRIPTION_ID},deployment.resource_group=${AZURE_RESOURCE_GROUP},deployment.workspace_name=${AZUREAI_PROJECT_NAME},deployment.endpoint_name=${AZUREAI_ENDPOINT_NAME},deployment.deployment_name=${AZUREAI_DEPLOYMENT_NAME}

The config.deployment section is required and creates a new online deployment to the associated online endpoint from the referenced YAML file definition. This functionality handles the following:

  • Associated environment and model are referenced when available.
  • azd waits for the deployment to enter a terminal provisioning state.
  • On successful deployments, all traffic is shifted to the new deployment version.
  • All previous deployments are deleted to free up compute for future deployments.

Explore configuration options

Each supported feature for AI/ML online endpoints supports customizations for your specific scenario using the options described in the following sections.

Flow

The flow configuration section is optional and supports the following values:

  • name: The name of the flow. Defaults to <service-name>-flow-<timestamp> if not specified.

  • path: The relative path to a folder that contains the flow manifest.

  • overrides: Any custom overrides to apply to the flow.

    Note

    Each call to azd deploy creates a new timestamped flow.

Environment

The environment configuration section is optional and supports the following values:

  • name: The name of the custom environment. Defaults to <service-name>-environment if not specified.

  • path: The relative path to a custom environment yaml manifest.

  • overrides: Any custom overrides to apply to the environment.

    Note

    Each call to azd deploy creates a new environment version.

Model

The model configuration section is optional and supports the following values:

  • name: The name of the custom model. Defaults to <service-name>-model if not specified.

  • path: The relative path to a custom model YAML manifest.

  • overrides: Any custom overrides to apply to the model.

    Note

    Each call to azd deploy creates a new model version.

Deployment

The deployment configuration section is required and supports the following values:

  • name: The name of the custom deployment. Defaults to <service-name>-deployment if not specified.

  • path: The relative path to a custom deployment yaml manifest.

  • environment: A map of key value pairs to set environment variables for the deployment. Supports environment variable substitutions from OS/AZD environment variables using ${VAR_NAME} syntax.

  • overrides: Any custom overrides to apply to the deployment.

    Note

    Only supports managed online deployments.

AgentSchema and agent.yaml

AgentSchema is an open specification for defining AI agents in a code-first YAML format. An agent.yaml file describes an agent's configuration, including its model, instructions, tools, and connections. AgentSchema serves as a unified exchange format between Microsoft Copilot Studio, Microsoft Foundry, and other platforms.

AgentSchema supports two primary formats:

  • AgentDefinition — A complete, concrete specification of an agent that can be executed directly. Use this format for single-purpose agents where all configuration values are known and fixed.
  • AgentManifest — A parameterized template for creating agents dynamically. Use this format for reusable agent patterns where values like model names, connections, or instructions are configured at runtime using {{parameter}} syntax.

Example agent.yaml

The following example shows a hosted agent.yaml definition that azd can deploy to Microsoft Foundry. The schema annotation at the top tells YAML-aware editors to validate against the published AgentSchema:

# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml

kind: hosted
name: customer-support
description: Handles customer inquiries and support requests
protocols:
  - protocol: responses
    version: v1
code_configuration:
  runtime: python_3_14
  entry_point: main.py

This example uses kind: hosted with a code_configuration block, which tells azd to package your source code as a ZIP and let Foundry manage the runtime. To deploy a prebuilt container image instead, replace code_configuration with an image field that points to an image in Azure Container Registry.

Using agent.yaml with azd

The azure.yaml schema supports the azure.ai.agent host type for deploying agents to Microsoft Foundry. When you set host to azure.ai.agent, azd reads the agent.yaml file in your service directory and uses its kind field to determine how to deploy the agent. For more information, see the azure.yaml schema reference.

Supported kind values

The kind field at the top of agent.yaml selects the deployment shape. azd validates this field against the values in the following table and rejects any other value at deploy time.

kind What azd deploys When to use
hosted A Foundry-hosted agent. The deployment sub-mode depends on the fields you include in the file: add code_configuration for code deploy (ZIP upload, Foundry-managed runtime), or add image for container deploy (your prebuilt image from Azure Container Registry). Most agents created by azd ai agent init. Use code deploy when you want Foundry to manage the runtime; use container deploy when you need full control over the image.

Note

AgentSchema is a broader specification than what azd deploys today. If you see other kind values in the AgentSchema reference (for example, prompt-only agent definitions), those formats aren't supported by azd and aren't accepted by azd deploy.

For more information about AgentSchema, see the following resources:

Related content

Request help

For information on how to file a bug, request help, or propose a new feature for the Azure Developer CLI, please visit the troubleshooting and support page.

  • Last updated on