azure.yaml reference for hosted agents

Reference for the unified azd azure.yaml project file for hosted agents: services, host types, model deployments, agent configuration, dependencies, file includes, and infrastructure.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

The azure.yaml file is the single Azure Developer CLI (azd) project configuration for a hosted agent project. It declares your Foundry resources — the project, model deployments, connections, toolboxes, skills, routines, and the agents themselves — as a set of services, and it tells azd how to provision and deploy them. This unified file replaces the earlier two-file model that split configuration between agent.manifest.yaml and agent.yaml.

To learn how to compose and author this file step by step, see Author azure.yaml for hosted agents.

How azd uses azure.yaml

The Azure Developer CLI streamlines the developer-to-cloud workflow. It handles two things: provisioning Azure resources, such as Foundry projects, model deployments, and container registries; and deploying your code to those resources. For hosted agents, the azure.ai.agents extension adds agent-specific commands such as azd ai agent init and azd ai agent run.

Every azd project has an azure.yaml file at its root. For agent projects, this file is the source of truth for both the agent configuration and the deployment configuration.

Environments

An environment is a named configuration, such as dev, staging, or prod, that stores settings for a particular deployment. Each environment tracks the Azure subscription and location, the resource group and resource names, and any custom variables you set. Settings are stored locally in .azure/<env-name>/.env. You can have multiple environments for the same project.

Core commands

Command	What it does
azd provision	Creates Azure resources, such as the Foundry project, model deployments, and container registry.
azd deploy	Builds and packages your agent, uploads it, and creates the hosted agent version.
azd up	Combines provision and deploy in one command.
azd down	Deletes all provisioned resources.
azd env set	Sets an environment variable, for example azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini.

The split-service model

Under services, each entry is a named service with a host field that identifies the kind of Foundry resource it declares. Services reference each other through the uses field, which forms a dependency graph that azd resolves at provision and deploy time. A typical project has one azure.ai.project service that owns the model deployments and one azure.ai.agent service that depends on it.

Host	Resource	Purpose
azure.ai.project	Foundry project	Owns model deployments and optional private networking.
azure.ai.agent	Hosted or prompt agent	Carries the agent definition and its build and deploy settings.
azure.ai.connection	Project connection	Links the project to an external resource, such as an MCP server or a search index.
azure.ai.toolbox	Toolbox (Foundry Toolset)	A named bundle of connection-backed tools that agents reference.
azure.ai.skill	Skill	A reusable behavioral guideline shared across agents.
azure.ai.routine	Routine	A trigger plus an action that invokes an agent.

Minimal example

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
name: my-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 10

    my-agent:
        host: azure.ai.agent
        project: src/my-agent
        language: docker
        uses:
            - ai-project
        kind: hosted
        name: my-agent
        description: A hosted agent built from source.
        protocols:
            - protocol: responses
              version: 2.0.0
        env:
            FOUNDRY_MODEL_NAME: ${FOUNDRY_MODEL_NAME}
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Full example

The following project adds a connection, a toolbox, and private networking.

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
requiredVersions:
    extensions:
        azure.ai.agents: '>=0.1.0-preview'

name: research-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 50

    search-conn:
        host: azure.ai.connection
        uses:
            - ai-project
        category: CognitiveSearch
        target: https://my-search.search.windows.net
        authType: ApiKey
        credentials:
            key: ${SEARCH_API_KEY}

    research-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - search-conn
        description: Tools used by the research agent.
        tools:
            - type: azure_ai_search
              connection: search-conn
            - type: code_interpreter

    researcher:
        host: azure.ai.agent
        project: src/researcher
        language: docker
        uses:
            - ai-project
            - search-conn
            - research-tools
        kind: hosted
        name: researcher
        description: Hosted research agent built from source.
        startupCommand: python main.py
        toolboxes:
            - research-tools
        env:
            LOG_LEVEL: info
        protocols:
            - protocol: responses
              version: 2.0.0
        container:
            resources:
                cpu: "1.0"
                memory: 2Gi

infra:
    provider: bicep
    path: ./infra

Top-level fields

Field	Required	Description
name	Yes	Project name.
requiredVersions.extensions	No	Minimum extension version constraints, for example azure.ai.agents: '>=0.1.0-preview'.
metadata	No	Project metadata, such as the template identifier.
services	Yes	Map of service names to service configurations.
infra	No	Infrastructure-as-code settings. Present when you eject IaC.

azure.ai.project service

The project service provisions or connects to a Foundry project and owns its model deployments.

Field	Description
host	Must be azure.ai.project.
endpoint	Endpoint URL of an existing Foundry project. When set, azd connects to that project instead of provisioning a new one. When omitted, azd provisions a new project.
deployments	Array of model deployments to create on the project.
network	Optional private networking for the account that backs the project.

deployments

Field	Description
name	Deployment name.
model.format	Model format, for example OpenAI.
model.name	Model name, for example gpt-5.4-mini.
model.version	Model version string.
sku.name	SKU name, for example GlobalStandard, Standard, or GlobalBatch.
sku.capacity	SKU capacity in tokens-per-minute units.

A deployment entry can also be an external file include: - $ref: ./deployments/embeddings.yaml.

network

Set network to provision a network-secured account. The peSubnet field is required and establishes the account private endpoint. Add agentSubnet to inject the agent runtime into your own subnet (bring your own virtual network), or omit it to use the Microsoft-managed network. For a complete walkthrough, see Hosted agent private networking.

azure.ai.agent service

The agent service carries the agent definition and its build and deploy settings. It’s the service that replaces the old agent.yaml.

Field	Description
host	Must be azure.ai.agent.
kind	Agent kind. Use hosted for containerized agents built from source.
name	Agent name. Reusing a name creates a new version of the existing agent.
displayName	Optional human-friendly display name.
description	Optional description of the agent.
project	Path to the agent source directory, for example src/my-agent.
language	Build language for hosted agents. Use docker.
uses	List of services this agent depends on, such as the project, connections, and toolboxes.
protocols	Invocation protocols the agent implements.
env	Map of environment variables passed to the container.
container	Container CPU and memory settings.
startupCommand	Command that starts the agent server, for example python main.py. Used by azd ai agent run for local development and for container startup.
toolboxes	List of azure.ai.toolbox service names the agent uses at runtime.
codeConfiguration	Source (ZIP) deploy settings. See Deploy modes.
image	Prebuilt container image URL. When set, azd deploys the image directly and skips the Dockerfile build.
metadata	Optional metadata key-value pairs.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

Protocol	Description
responses	OpenAI Responses API. Includes conversation history management.
invocations	Custom payload protocol. No built-in conversation management.
a2a	Agent-to-agent protocol for agent orchestration.

For the full protocol specification, see Hosted agent runtime contract.

env

env:
    FOUNDRY_MODEL_NAME: ${FOUNDRY_MODEL_NAME}
    LOG_LEVEL: info

The ${ } syntax references azd environment variables from .azure/<env>/.env.

Don’t declare FOUNDRY_PROJECT_ENDPOINT in env. The platform injects it automatically into hosted containers, and azd ai agent run sets it for local development. Declaring it here is redundant and risks shadowing the platform value.

container

container:
    resources:
        cpu: "0.25"
        memory: 0.5Gi

Set cpu from "0.25" up to "4.0", and memory from 0.5Gi up to 8.0Gi.

azure.ai.connection service

A connection links the project to an external resource. The service key is the connection name, and the service depends on the project through uses.

Field	Description
host	Must be azure.ai.connection.
category	Connection category, for example CustomKeys, ApiKey, AzureOpenAI, CognitiveSearch, or RemoteTool.
target	Target endpoint URL or ARM resource ID.
authType	Authentication type, for example ApiKey, CustomKeys, AAD, ManagedIdentity, or OAuth2.
credentials	Credentials for the connection. Values can contain ${VAR} references.
metadata	Additional metadata as key-value pairs.

github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

azure.ai.toolbox service

A toolbox is a named bundle of tools that agents reference. Connection-backed tools name an azure.ai.connection service through the connection field.

Field	Description
host	Must be azure.ai.toolbox.
description	Description of the toolbox.
tools	List of tools. Each entry has a type and, for connection-backed tools, a connection.

research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

An agent references a toolbox by adding the toolbox service name to both uses and its toolboxes list.

azure.ai.skill and azure.ai.routine services

A azure.ai.skill service defines a reusable behavioral guideline that agents reference by name. A azure.ai.routine service defines a trigger (schedule or event) and an action that invokes an agent. Both depend on the resources they use through uses. For details, see Discover tools in Foundry Tools and Use routines.

Dependencies with uses

The uses field declares the services a given service depends on. azd uses this graph to order provisioning and to wire references, such as an agent’s connections and toolboxes.

uses:
    - ai-project
    - search-conn
    - research-tools

File includes with $ref

Any service or list entry can be replaced with a reference to an external YAML or JSON file. Relative paths resolve from the file that contains the $ref. Remote URLs aren’t supported.

services:
    triage:
        host: azure.ai.agent
        uses:
            - ai-project
        $ref: ./agents/triage.yaml

File includes let you keep large agent definitions in their own files and share definitions across projects.

Variable substitution

Two substitution syntaxes can appear in azure.yaml:

Syntax	Resolved when	By what
${VAR_NAME}	azd provision or azd deploy	azd environment variables from .azure/<env>/.env, resolved client-side.
${{ ... }}	At runtime	Foundry server-side resolution. azd passes these through untouched.

Infrastructure and deploy modes

Bicep-less by default

azd ai agent init is bicep-less by default: it doesn’t write an infra/ directory, and azd synthesizes the infrastructure from your azure.yaml services at provision time. To materialize infrastructure-as-code files, eject them:

Command	Result
azd ai agent init --infra	Ejects Bicep into ./infra/.
azd ai agent init --infra=bicep	Ejects Bicep (explicit).
azd ai agent init --infra=terraform	Ejects Terraform and sets infra.provider: terraform.

When infra is present in azure.yaml, azd uses those files instead of synthesizing infrastructure.

Deploy modes

A hosted agent deploys in one of two modes:

Mode	How it works	How to select
code	azd uploads your source as a ZIP and builds it remotely. This is the default for Python and .NET projects.	azd ai agent init --deploy-mode code
container	azd builds a Docker image from your Dockerfile and deploys it.	azd ai agent init --deploy-mode container

For source deploys, the codeConfiguration field on the agent service captures the runtime and entry point. For prebuilt images, set the image field on the agent service and skip the Dockerfile build.

JSON schema validation

Add the schema reference for IDE autocompletion:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

Related content

• Author azure.yaml for hosted agents
• Initialize a hosted agent project with the Azure Developer CLI
• Hosted agent infrastructure with the Azure Developer CLI
• Hosted agent runtime contract
• What are hosted agents?