Informazioni di riferimento su azure.yaml per gli agenti ospitati

Il azure.yaml file è il singolo Azure configurazione del progetto dell'interfaccia della riga di comando per sviluppatori (azd) per un progetto agente ospitato. Dichiara le risorse foundry, ovvero il progetto, le distribuzioni di modelli, le connessioni, le caselle degli strumenti, le competenze, le routine e gli agenti stessi, come set di servizi, e spiega azd come effettuare il provisioning e distribuirli. Questo file unificato sostituisce il modello a due file precedente che suddivide la configurazione tra agent.manifest.yaml e agent.yaml.

Per informazioni su come comporre e creare questo file in modo dettagliato, vedere Creare azure.yaml per gli agenti ospitati.

Come azd usa azure.yaml

L'interfaccia della riga di comando per sviluppatori Azure semplifica il flusso di lavoro da sviluppatore a cloud. Gestisce due aspetti: il provisioning Azure risorse, ad esempio i progetti Foundry, le distribuzioni di modelli e i registri contenitori e la distribuzione del codice in tali risorse. Per gli agenti ospitati, l'estensione aggiunge comandi specifici dell'agente azure.ai.agents , azd ai agent init ad esempio e azd ai agent run.

Ogni azd progetto ha un azure.yaml file nella radice. Per i progetti dell'agente, questo file è l'origine della verità sia per la configurazione dell'agente che per la configurazione della distribuzione.

Environments

Un ambiente è una configurazione denominata, ad esempio dev, stagingo prod, che archivia le impostazioni per una distribuzione specifica. Ogni ambiente tiene traccia della sottoscrizione e della posizione Azure, del gruppo di risorse e dei nomi delle risorse e delle variabili personalizzate impostate. Le impostazioni vengono archiviate localmente in .azure/<env-name>/.env. È possibile avere più ambienti per lo stesso progetto.

Comandi principali

Compatibilità delle estensioni

L'estensione azure.ai.agents fornisce l'host azure.ai.agent . L'estensione azure.ai.projects fornisce l'host azure.ai.project e il microsoft.foundry provider di infrastruttura. Usare azure.ai.agents la versione o una versione 1.0.0-beta.8 successiva con azure.ai.projects la versione 1.0.0-beta.4 o successiva. Per istruzioni sull'installazione e l'aggiornamento, vedere Installare le estensioni foundry dell'interfaccia della riga di comando per sviluppatori Azure.

È possibile dichiarare le versioni minime compatibili in azure.yaml:

requiredVersions:
    azd: ">=1.27.1"
    extensions:
        azure.ai.agents: ">=1.0.0-beta.8"
        azure.ai.projects: ">=1.0.0-beta.4"

Ciclo di vita del provider di servizi

Installare il meta-pacchetto quando il microsoft.foundry progetto include connessioni, casella degli strumenti, competenze o routine. Installa le estensioni del provider che implementano gli host corrispondenti azure.ai.* .

I provider di progetto e di connessione applicano la configurazione durante azd provision. Gli agenti, la casella degli strumenti, le competenze e i provider di routine applicano la configurazione durante azd deploy. Eseguire azd up per completare entrambe le fasi. La rimozione di un servizio del piano dati non azure.yaml consente di gestirla azd . Eliminare separatamente la risorsa remota quando non è più necessaria.

• azd down - Elimina il gruppo di risorse quando l'ambiente corrente ha creato il progetto Foundry. Lascia un progetto esistente e le relative risorse. |
• azd env set - Imposta una variabile di ambiente, ad esempio azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

Modello split-service

In servicesogni voce è un servizio denominato con un host campo che identifica il tipo di risorsa Foundry dichiarata. I servizi fanno riferimento tra loro tramite il uses campo , che costituisce un grafico delle dipendenze che azd risolve in fase di provisioning e distribuzione. Un progetto tipico dispone di un azure.ai.project servizio proprietario delle distribuzioni del modello e di un azure.ai.agent servizio che dipende da esso.

Esempio minimo

# 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:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Esempio completo

Il progetto seguente aggiunge una connessione, una casella degli strumenti e una rete privata.

# 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

Campi di primo livello

servizio azure.ai.project

Il servizio di progetto effettua il provisioning o si connette a un progetto Foundry e possiede le distribuzioni del modello.

deployments

Una voce di distribuzione può anche essere un file esterno: - $ref: ./deployments/embeddings.yaml.

network

Impostare network per effettuare il provisioning di un account protetto dalla rete. Il peSubnet campo è obbligatorio e stabilisce l'endpoint privato dell'account. Aggiungere agentSubnet per inserire il runtime dell'agente nella propria subnet (bring your own virtual network) o ometterlo per usare la rete gestita da Microsoft. Per una procedura dettagliata completa, vedere Rete privata dell'agente ospitato.

Configurazione di rete privata

Usare network nel azure.ai.project servizio per configurare l'endpoint privato dell'account e l'uscita dell'agente. L'esempio seguente usa una subnet gestita dal cliente per il runtime dell'agente:

services:
    ai-project:
        host: azure.ai.project
        network:
            peSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: private-endpoint-subnet
            agentSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: agent-subnet
            dns:
                resourceGroup: ${PRIVATE_DNS_RESOURCE_GROUP}
                subscription: ${PRIVATE_DNS_SUBSCRIPTION_ID}

La rete privata disabilita l'accesso al piano dati pubblico per l'account. Un Registro Azure Container creato automaticamente non è supportato con questa configurazione. Usare la distribuzione del codice sorgente o specificare un oggetto predefinito image.

servizio azure.ai.agent

Il servizio agente contiene la definizione dell'agente e le relative impostazioni di compilazione e distribuzione. Si tratta del servizio che sostituisce il vecchio agent.yaml.

agentCard.skills e azure.ai.skill

agentCard.skills descrive le funzionalità di un agente nella scheda di individuazione. Fornisce metadati per i client e non crea o collega una competenza Foundry riutilizzabile. Ogni competenza della scheda richiede un idoggetto , namee description.

Un azure.ai.skill servizio crea una competenza con controllo delle versioni da istruzioni e strumenti facoltativi consentiti. Dichiararla separatamente in services; il relativo uses elenco controlla l'ordine di dipendenza, ma non popola agentCard.skills o associa la competenza a un agente. Usare agentCard.skills per i metadati di individuazione e azure.ai.skill per istruzioni riutilizzabili.

agentCard:
    description: Research agent discovery card.
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.

services:
    code-review:
        host: azure.ai.skill
        uses:
            - ai-project
        instructions: ./skills/code-review.md

Completare una scheda di individuazione

Aggiungere version, tagse examples quando i client necessitano di metadati di individuazione più avanzati. Una scheda richiede almeno una description competenza. Ogni competenza richiede un idoggetto , namee description.

agentCard:
    description: Research agent discovery card.
    version: "1.0"
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.
          tags:
              - research
          examples:
              - Research current product guidance.

Criteri di IA responsabili

Usare policies per associare un criterio di intelligenza artificiale responsabile all'agente ospitato. Impostare raiPolicyName sull'ID risorsa ARM completo dei criteri:

policies:
    - type: rai_policy
      raiPolicyName: ${RAI_POLICY_RESOURCE_ID}

Il rai_policy tipo e raiPolicyName sono obbligatori. L'estensione applica i primi criteri validi nell'elenco alla configurazione dell'intelligenza artificiale responsabile dell'agente ospitato. Per indicazioni sulla creazione e la gestione dei criteri, vedere Aggiungere protezioni agli agenti ospitati.

Memorie

Usare memoryStores per creare o riutilizzare archivi di memoria Foundry prima della distribuzione. Ogni archivio richiede nomi di distribuzione di modelli di chat e incorporamento esistenti.

memoryStores:
    - name: customer-memory
      description: Stores durable customer context.
      chatModel: gpt-5.4-mini
      embeddingModel: text-embedding-3-large
      options:
          chatSummaryEnabled: true
          userProfileEnabled: true
          proceduralMemoryEnabled: false
          defaultTtlSeconds: 0

Gli archivi esistenti non vengono aggiornati durante la distribuzione. Se la definizione dichiarata è diversa dall'archivio esistente, azd segnala la differenza. La dichiarazione di un archivio di memoria non modifica il codice dell'agente o collega automaticamente uno strumento di memoria. Connettere l'applicazione all'archivio di memoria usando lo strumento di ricerca della memoria o le API dell'archivio memoria. Per informazioni dettagliate, vedere Usare la memoria con gli agenti.

Configurare un endpoint agente

Usare agentEndpoint per configurare i protocolli e gli schemi di autorizzazione pubblicati dall'endpoint dell'agente. Usare una scheda agente con un endpoint A2A in modo che altri agenti possano individuare le funzionalità esposte.

agentEndpoint:
    protocols:
        - responses
        - a2a
    authorizationSchemes:
        - type: Entra

È anche possibile definire versionSelector.versionSelectionRules quando è necessario controllare la versione dell'agente che riceve il traffico degli endpoint. Il servizio Agent convalida i valori di autorizzazione e protocollo endpoint durante la distribuzione.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

Per la specifica completa del protocollo, vedere Contratto di runtime dell'agente ospitato.

Protocolli di runtime aggiuntivi ed endpoint attività

Oltre a responses, invocationse a2a, gli agenti ospitati supportano invocations_ws le chiamate WebSocket e activity per gli scenari di attività di Microsoft 365 e Teams.

protocols:
    - protocol: invocations_ws
      version: 2.0.0
    - protocol: activity
      version: 2.0.0

Per un agente attività, aggiungere activity alla configurazione dell'endpoint pubblico e usare lo schema di autorizzazione servizio Bot richiesto:

agentEndpoint:
    protocols:
        - activity
    authorizationSchemes:
        - type: BotServiceRbac

Il protocollo Activity può coesistere con altri protocolli nello stesso endpoint dell'agente. Per il comportamento del protocollo di runtime, vedere Che cosa sono gli agenti ospitati?.

Env

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

La ${ } sintassi fa riferimento alle azd variabili di ambiente da .azure/<env>/.env.

Ambiente della piattaforma, identità ed endpoint

La piattaforma riserva i FOUNDRY_ prefissi e AGENT_ . Leggere le variabili della piattaforma, ad esempio FOUNDRY_PROJECT_ENDPOINT, dal codice dell'applicazione, ma non definirle o eseguirne l'override in env. I valori di ambiente definiti dall'agente sono stringhe.

Ogni agente ospitato distribuito riceve un'identità e un endpoint dell'agente Microsoft Entra ID dedicati. Non aggiungere un identity blocco al servizio agente. L'identità dell'agente può usare l'endpoint del progetto e l'archiviazione sessione per impostazione predefinita. Assegnare i ruoli aggiuntivi di identità quando l'agente deve accedere a risorse esterne. Per informazioni dettagliate, vedere Informazioni di riferimento sulle autorizzazioni dell'agente ospitato.

I protocolli dichiarati determinano gli endpoint attivi dopo la distribuzione. Eseguire azd ai agent show per esaminare l'agente distribuito e gli URL degli endpoint.

Dopo la distribuzione, azd scrive i valori seguenti nell'ambiente attivo, usando il nome del servizio normalizzato al posto di <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINTper protocolli , invocationse invocations_ws abilitati responses

Usare l'output specifico del protocollo quando l'applicazione o l'automazione richiede un URL di chiamata. L'endpoint di base identifica la versione dell'agente distribuita per le operazioni di gestione della sessione.

container

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

Configurare cpu da "0.25" a "4.0"e memory da 0.5Gi a 8.0Gi.

Distribuzione del codice sorgente

Impostare codeConfiguration per distribuire il codice sorgente come zip anziché come immagine del contenitore. Specificare un nome file o un nome di assembly del punto di ingresso. azd lo combina con il runtime selezionato quando crea la versione dell'agente ospitato.

codeConfiguration:
    runtime: python_3_13
    entryPoint: main.py
    dependencyResolution: remote_build

Usare remote_build per ripristinare le dipendenze dalle origini del progetto o usare bundled quando il file ZIP contiene dipendenze compatibili con Linux. Non combinare codeConfiguration con la configurazione del contenitore basata su immagini. Per indicazioni sulla creazione di pacchetti e sulle dipendenze, vedere Distribuire un agente ospitato dal codice sorgente.

Compilazione di contenitori e immagini predefinite

Usare un oggetto Dockerfile in project per compilare un'immagine del contenitore o impostare image per distribuire un'immagine predefinita:

image: myregistry.azurecr.io/agents/researcher:1.2.3

Quando un Dockerfile e un image sono entrambi disponibili, scegliere l'immagine predefinita nel prompt della distribuzione interattiva. Per la distribuzione automatica, impostare su AZD_AGENT_SKIP_ACRtrue nell'ambiente attivo azd per selezionare l'immagine configurata. Per le autorizzazioni del Registro di sistema e la distribuzione del Registro di sistema privato, vedere Distribuire un agente ospitato con un Registro Azure Container privato.

Limitazioni dei metadati e dello schema

Usare i valori stringa per i metadati dell'agente distribuiti. Il authors valore dei metadati può essere un elenco di stringhe. Non basarsi su displayName, inputSchemao outputSchema per configurare l'agente ospitato distribuito. La configurazione unificata accetta questi campi, ma la richiesta di creazione dell'agente ospitato non li usa.

servizio azure.ai.connection

Una connessione collega il progetto a una risorsa esterna. La chiave del servizio è il nome della connessione e il servizio dipende dal progetto tramite uses.

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

Le modifiche alla connessione si applicano durante azd provision, non azd deploy. Archiviare i valori delle credenziali nell'ambiente azd e farvi riferimento invece ${VAR} di inserire segreti in azure.yaml.

servizio azure.ai.toolbox

Una casella degli strumenti è un bundle denominato di strumenti a cui fanno riferimento gli agenti. Gli strumenti supportati dalla connessione denominano un azure.ai.connection servizio tramite il connection campo .

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

Un agente fa riferimento a una casella degli strumenti aggiungendo il nome del servizio della casella degli strumenti sia uses al relativo toolboxes elenco.

Utilizzare un endpoint della casella degli strumenti

In un progetto split-service controlla uses l'ordine di distribuzione. L'applicazione si connette all'endpoint MCP della casella degli strumenti in fase di esecuzione. Passare il nome o l'endpoint della casella degli strumenti all'applicazione tramite env, quindi costruire l'endpoint consumer dal FOUNDRY_PROJECT_ENDPOINT codice dell'agente. Per un esempio end-to-end, vedere Usare una casella degli strumenti con un agente ospitato.

azure.ai.skill e azure.ai.routine services

Un azure.ai.skill servizio definisce una linea guida comportamentale riutilizzabile a cui fanno riferimento gli agenti in base al nome. Un azure.ai.routine servizio definisce un trigger (pianificazione o evento) e un'azione che richiama un agente. Entrambi dipendono dalle risorse usate tramite uses. Per altre informazioni sull'aggiunta di strumenti per l'uso dell'agente, vedere Che cos'è La casella degli strumenti in Foundry? e Usare routine.

Le competenze e le routine sono risorse separate. La dichiarazione del servizio controlla il ciclo di vita, ma non associa automaticamente una competenza all'agente o dedurre una destinazione di azione di routine. Configurare l'applicazione di utilizzo o l'azione di routine in modo esplicito.

Dipendenze con usi

Il uses campo dichiara i servizi da cui dipende un determinato servizio. azd usa questo grafico per ordinare il provisioning e collegare riferimenti, ad esempio connessioni e casella degli strumenti di un agente.

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

File include con $ref

Qualsiasi voce di servizio o elenco può essere sostituita con un riferimento a un file YAML o JSON esterno. I percorsi relativi vengono risolti dal file che contiene .$ref Gli URL remoti non sono supportati.

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

I file includono consentono di mantenere definizioni di agenti di grandi dimensioni nei propri file e condividere definizioni tra progetti.

Mantenere i campi del servizio di base nella voce radice azure.yaml quando si usa un servizio$ref: host, uses, projectlanguage, image, e docker. Inserire i campi di definizione di proprietà del provider, ad esempio kind, namedescription, e protocols, nel mapping a cui si fa riferimento. $ref risolve i file YAML o JSON locali in modo ricorsivo; Gli URL e i cicli di riferimento non sono supportati.

Sostituzione di variabili

In è possibile visualizzare due sintassi di sostituzione:azure.yaml

Modalità di infrastruttura e distribuzione

Bicep meno per impostazione predefinita

azd ai agent init è minore di bicep per impostazione predefinita: non scrive una infra/ directory e azd sintetizza l'infrastruttura dai azure.yaml servizi in fase di provisioning. Per materializzare i file di infrastruttura come codice, espellerli:

Quando infra è presente in azure.yaml, azd usa tali file invece di sintetizzare l'infrastruttura.

Modalità di distribuzione

Un agente ospitato viene distribuito in una delle due modalità seguenti:

Per le distribuzioni di origine, il codeConfiguration campo nel servizio agente acquisisce il runtime e il punto di ingresso. Per le immagini predefinite, impostare il image campo nel servizio agente e ignorare la compilazione Dockerfile.

Migrazione della configurazione legacy

Le definizioni dell'agente meno recenti possono annidare le variabili di ambiente in config: env. Nell'oggetto unificato azure.yamlspostare il env mapping al servizio agente:

# Legacy
services:
    my-agent:
        host: azure.ai.agent
        config:
            env:
                MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

# Unified azure.yaml
services:
    my-agent:
        host: azure.ai.agent
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

Convalida dello schema JSON

Aggiungere il riferimento allo schema per il completamento automatico dell'IDE:

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

Contenuti correlati

• Creare azure.yaml per gli agenti ospitati
• Inizializzare un progetto agente ospitato con l'interfaccia della riga di comando per sviluppatori di Azure
• Infrastruttura dell'agente ospitato con l'interfaccia della riga di comando per sviluppatori di Azure
• Contratto di runtime dell'agente ospitato
• Che cosa sono gli agenti ospitati?