naslaginformatie over azure.yaml voor gehoste agents

Het azure.yaml bestand is de enkele Azure Developer CLI-projectconfiguratie (azd) voor een gehost agentproject. Het declareert uw Foundry-resources: het project, modelimplementaties, verbindingen, werksets, vaardigheden, routines en de agents zelf, als een set services, en geeft aan azd hoe ze moeten worden ingericht en geïmplementeerd. Dit geïntegreerde bestand vervangt het eerdere model met twee bestanden dat de configuratie tussen agent.manifest.yaml en agent.yaml.

Zie Author azure.yaml voor gehoste agents voor meer informatie over het opstellen en ontwerpen van dit bestand.

Hoe azd gebruikmaakt van azure.yaml

De Azure Developer CLI stroomlijnt de werkstroom voor ontwikkelaars naar de cloud. Er worden twee dingen afgehandeld: het inrichten van Azure resources, zoals Foundry-projecten, modelimplementaties en containerregisters; en het implementeren van uw code op die resources. Voor gehoste agents voegt de azure.ai.agents extensie agentspecifieke opdrachten toe, zoals azd ai agent init en azd ai agent run.

Elk azd project heeft een azure.yaml bestand in de hoofdmap. Voor agentprojecten is dit bestand de bron van waarheid voor zowel de agentconfiguratie als de implementatieconfiguratie.

Environments

Een omgeving is een benoemde configuratie, zoals dev, stagingof prod, waarmee instellingen voor een bepaalde implementatie worden opgeslagen. Elke omgeving houdt het Azure abonnement en locatie, de resourcegroep en resourcenamen en eventuele aangepaste variabelen bij die u instelt. Instellingen worden lokaal opgeslagen in .azure/<env-name>/.env. U kunt meerdere omgevingen voor hetzelfde project hebben.

Kernopdrachten

Extensiecompatibiliteit

De azure.ai.agents extensie biedt de azure.ai.agent host. De azure.ai.projects extensie biedt de azure.ai.project host en de microsoft.foundry infrastructuurprovider. Gebruik azure.ai.agents versie 1.0.0-beta.8 of hoger met azure.ai.projects versie 1.0.0-beta.4 of hoger. Zie De Azure Developer CLI Foundry-extensies installeren voor installatie- en upgrade-instructies.

U kunt de minimaal compatibele versies declareren 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"

Levenscyclus van serviceproviders

Installeer het microsoft.foundry metapakket wanneer uw project verbindingen, werksets, vaardigheden of routines bevat. Hiermee worden de providerextensies geïnstalleerd die de bijbehorende azure.ai.* hosts implementeren.

De project- en verbindingsproviders passen hun configuratie toe tijdens azd provision. De agent, werkset, vaardigheid en routineproviders passen hun configuratie toe tijdens azd deploy. Uitvoeren azd up om beide fasen te voltooien. Als u een gegevensvlakservice verwijdert, azure.yaml kunt azd u deze niet meer beheren. Verwijder de externe resource afzonderlijk wanneer u deze niet meer nodig hebt.

• azd down - Verwijdert de resourcegroep wanneer de huidige omgeving het Foundry-project heeft gemaakt. Laat een bestaand project en de bijbehorende resources behouden. |
• azd env set - Hiermee stelt u een omgevingsvariabele in, bijvoorbeeld azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

Het split-servicemodel

Onder servicesis elke vermelding een benoemde service met een host veld dat het type Foundry-resource identificeert dat wordt declareren. Services verwijzen naar elkaar via het uses veld, dat een afhankelijkheidsgrafiek vormt die azd wordt omgezet tijdens de inrichting en implementatietijd. Een typisch project heeft één azure.ai.project service die eigenaar is van de modelimplementaties en één azure.ai.agent service die ervan afhankelijk is.

Minimaal voorbeeld

# 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

Volledig voorbeeld

In het volgende project worden een verbinding, een werkset en privénetwerken toegevoegd.

# 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

Velden op het hoogste niveau

azure.ai.project-service

De projectservice richt een Foundry-project in of maakt verbinding met een Foundry-project en is eigenaar van de modelimplementaties.

deployments

Een implementatievermelding kan ook een extern bestand zijn: - $ref: ./deployments/embeddings.yaml.

network

Ingesteld network om een met het netwerk beveiligd account in te richten. Het peSubnet veld is vereist en stelt het privé-eindpunt van het account in. Voeg agentSubnet de agentruntime toe aan uw eigen subnet (bring your own virtual network) of laat deze weg om het Microsoft beheerde netwerk te gebruiken. Zie Hosted Agent Private Networking voor een volledig overzicht.

Configuratie van privénetwerk

Gebruik network op de azure.ai.project service om het privé-eindpunt van het account en het uitgaand verkeer van de agent te configureren. In het volgende voorbeeld wordt een door de klant beheerd subnet gebruikt voor de agentruntime:

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}

Met privénetwerken wordt de toegang tot openbare gegevensvlakken voor het account uitgeschakeld. Een automatisch gemaakte Azure Container Registry wordt niet ondersteund met deze configuratie. Gebruik de broncode-implementatie of geef een vooraf gedefinieerde imagewaarde op.

azure.ai.agent-service

De agentservice heeft de definitie van de agent en de bijbehorende build- en implementatie-instellingen. Het is de service die de oude agent.yamlvervangt.

agentCard.skills en azure.ai.skill

agentCard.skills beschrijft de mogelijkheden van een agent in de detectiekaart. Het biedt metagegevens voor clients en maakt of koppelt geen herbruikbare Foundry-vaardigheid. Voor elke kaartvaardigheid is een id, nameen description.

Een azure.ai.skill service maakt een versie-vaardigheid op basis van instructies en optionele toegestane hulpprogramma's. Declareer deze afzonderlijk onder services; de uses lijst bepaalt de afhankelijkheidsvolgorde, maar de vaardigheid wordt niet ingevuld agentCard.skills of gekoppeld aan een agent. Gebruiken agentCard.skills voor detectiemetagegevens en azure.ai.skill voor herbruikbare instructies.

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

Een detectiekaart voltooien

Voeg versiontoe, tagsen examples wanneer clients uitgebreidere detectiemetagegevens nodig hebben. Een kaart vereist een description en ten minste één vaardigheid. Voor elke vaardigheid is een id, nameen 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.

Verantwoord AI-beleid

Gebruik policies dit om een verantwoord AI-beleid te koppelen aan de gehoste agent. Ingesteld raiPolicyName op de volledige ARM-resource-id van het beleid:

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

Het rai_policy type en raiPolicyName zijn vereist. De extensie past het eerste geldige beleid in de lijst toe op de hosted-agent Responsible AI-configuratie. Zie Kaders voor gehoste agents toevoegen voor richtlijnen voor het maken en beheren van beleid.

Geheugenopslag

Gebruik memoryStores dit om Foundry-geheugenarchieven te maken of opnieuw te gebruiken vóór de implementatie. Voor elke winkel zijn bestaande implementatienamen voor chatmodellen en insluitingsmodellen vereist.

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

Bestaande winkels worden niet bijgewerkt tijdens de implementatie. Als de gedeclareerde definitie verschilt van het bestaande archief, azd rapporteert u het verschil. Als u een geheugenarchief declareren, wordt uw agentcode niet gewijzigd of wordt automatisch een geheugenhulpprogramma gekoppeld. Verbind uw toepassing met het geheugenarchief met behulp van het hulpprogramma voor geheugenzoekopdrachten of API's voor geheugenopslag. Zie Geheugen gebruiken met agents voor meer informatie.

Een agenteindpunt configureren

Gebruik agentEndpoint dit om de protocollen en autorisatieschema's te configureren die zijn gepubliceerd door het eindpunt van de agent. Gebruik een agentkaart met een A2A-eindpunt, zodat andere agents de mogelijkheden kunnen detecteren die u beschikbaar maakt.

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

U kunt ook definiëren wanneer u wilt bepalen versionSelector.versionSelectionRules welke agentversie eindpuntverkeer ontvangt. Agent Service valideert het eindpuntprotocol en de autorisatiewaarden tijdens de implementatie.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

Zie Hosted Agent Runtime-contract voor de volledige protocolspecificatie.

Aanvullende runtimeprotocollen en activiteitseindpunten

Naast responses, invocationsen a2agehoste agents ondersteuning invocations_ws voor WebSocket-aanroepen en activity voor Microsoft 365- en Teams-activiteitsscenario's.

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

Voeg voor een activiteitsagent toe activity aan de configuratie van het openbare eindpunt en gebruik het vereiste Bot Service autorisatieschema:

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

Het activiteitsprotocol kan naast andere protocollen op hetzelfde agenteindpunt bestaan. Zie Wat zijn gehoste agents voor runtimeprotocolgedrag?

Env

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

De ${ } syntaxis verwijst naar azd omgevingsvariabelen van .azure/<env>/.env.

Platformomgeving, identiteit en eindpunten

Het platform reserveert de FOUNDRY_ en AGENT_ voorvoegsels. Lees platformvariabelen, zoals FOUNDRY_PROJECT_ENDPOINT, uit uw toepassingscode, maar definieer of overschrijf ze niet in env. Door de agent gedefinieerde omgevingswaarden zijn tekenreeksen.

Elke geïmplementeerde gehoste agent ontvangt een toegewezen Microsoft Entra ID agentidentiteit en eindpunt. Voeg geen blok toe identity aan de agentservice. De agentidentiteit kan standaard gebruikmaken van het projecteindpunt en de sessieopslag. Wijs de identiteit extra rollen toe wanneer de agent toegang nodig heeft tot externe resources. Zie De referentie voor gehoste agentmachtigingen voor meer informatie.

De protocollen die u declareert, bepalen welke eindpunten actief zijn na de implementatie. Voer deze opdracht uit azd ai agent show om de geïmplementeerde agent en de bijbehorende eindpunt-URL's te inspecteren.

Na de implementatie azd worden de volgende waarden naar de actieve omgeving geschreven met behulp van de genormaliseerde servicenaam in plaats van <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT voor ingeschakelde responses, invocationsen invocations_ws protocollen

Gebruik de protocolspecifieke uitvoer wanneer uw toepassing of automatisering een aanroep-URL nodig heeft. Het basiseindpunt identificeert de geïmplementeerde agentversie voor sessiebeheerbewerkingen.

container

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

Instellen cpu van "0.25" tot "4.0", en memory van 0.5Gi tot 8.0Gi.

Broncode-implementatie

Ingesteld codeConfiguration om broncode te implementeren als een ZIP in plaats van een containerinstallatiekopieën. Geef één bestandsnaam of assemblynaam op voor het beginpunt. azd combineert deze met de geselecteerde runtime wanneer de gehoste agentversie wordt gemaakt.

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

Gebruik remote_build dit om afhankelijkheden van de projectbronnen te herstellen of te gebruiken bundled wanneer de ZIP linux-compatibele afhankelijkheden bevat. Combineer niet codeConfiguration met containerconfiguratie op basis van installatiekopieën. Zie Een gehoste agent implementeren vanuit broncode voor richtlijnen voor pakketten en afhankelijkheid.

Container-builds en vooraf gemaakte installatiekopieën

Gebruik een Dockerfile under project om een containerinstallatiekopieën te bouwen of om een vooraf gemaakte installatiekopieën image te implementeren:

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

Wanneer een Dockerfile en een image beide beschikbaar zijn, kiest u de vooraf gemaakte installatiekopieën in de interactieve implementatieprompt. Voor implementatie zonder toezicht stelt u in de actieve azd omgeving in AZD_AGENT_SKIP_ACRtrue om de geconfigureerde installatiekopieën te selecteren. Zie Een gehoste agent implementeren met een privé-Azure Container Registry voor registermachtigingen en privéregisterimplementatie.

Beperkingen voor metagegevens en schema's

Gebruik tekenreekswaarden voor geïmplementeerde metagegevens van agents. De waarde van de authors metagegevens kan een lijst met tekenreeksen zijn. Vertrouw niet op displayNamede geïmplementeerde gehoste agent of inputSchemaoutputSchema configureer de geïmplementeerde gehoste agent. De geïntegreerde configuratie accepteert deze velden, maar de aanvraag voor het maken van een gehoste agent gebruikt deze niet.

azure.ai.connection-service

Een verbinding koppelt het project aan een externe resource. De servicesleutel is de verbindingsnaam en de service is afhankelijk van het project.uses

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

Verbindingswijzigingen zijn van toepassing tijdens azd provision, niet azd deploy. Sla referentiewaarden op in uw azd omgeving en verwijs ernaar in ${VAR} plaats van geheimen in azure.yamlte plaatsen.

azure.ai.toolbox-service

Een werkset is een benoemde bundel hulpprogramma's waarnaar agents verwijzen. Hulpprogramma's met verbindingssteun noemen een azure.ai.connection service via het connection veld.

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

Een agent verwijst naar een werkset door de naam van de werksetservice toe te voegen aan zowel uses als de toolboxes lijst.

Een werkseteindpunt gebruiken

In een split-serviceproject uses bepaalt u de implementatievolgorde. Uw toepassing maakt tijdens runtime verbinding met het MCP-eindpunt van de werkset. Geef de naam of het eindpunt van de werkset door aan uw toepassing door enven bouw vervolgens het consumenteneindpunt vanuit FOUNDRY_PROJECT_ENDPOINT uw agentcode. Zie Een werkset gebruiken met een gehoste agent voor een end-to-end-voorbeeld.

azure.ai.skill en azure.ai.routine-services

Een azure.ai.skill service definieert een herbruikbare gedragsrichtlijn waarnaar agents verwijzen op naam. Een azure.ai.routine service definieert een trigger (planning of gebeurtenis) en een actie die een agent aanroept. Beide zijn afhankelijk van de resources die ze gebruiken.uses Zie Wat is Toolbox in Foundry? en Use routines voor meer informatie over het toevoegen van hulpprogramma's voor het gebruik van agents.

Vaardigheden en routines zijn afzonderlijke resources. Het declareren van een service bepaalt de levenscyclus, maar koppelt niet automatisch een vaardigheid aan de agent of leid een routineactiedoel af. Configureer de verbruikende toepassing of routineactie expliciet.

Afhankelijkheden met gebruik

Het uses veld declareert de services waarop een bepaalde service is gebaseerd. azd gebruikt deze grafiek om inrichtings- en draadverwijzingen te ordenen, zoals verbindingen en werksets van een agent.

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

Bestand bevat met $ref

Elke service- of lijstvermelding kan worden vervangen door een verwijzing naar een extern YAML- of JSON-bestand. Relatieve paden worden omgezet uit het bestand met de $ref. Externe URL's worden niet ondersteund.

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

Met het bestand kunt u grote agentdefinities in hun eigen bestanden bewaren en definities voor verschillende projecten delen.

Bewaar de basisservicevelden in de hoofdvermelding azure.yaml wanneer u een service $refgebruikt: host, uses, languageproject, , imageen docker. Plaats definitievelden van de provider, zoals kind, name, descriptionen protocols, in de toewijzing waarnaar wordt verwezen. $ref lost lokale YAML- of JSON-bestanden recursief op; URL's en referentiecycli worden niet ondersteund.

Variabele vervanging

Er kunnen twee vervangingssyntaxis worden weergegeven in azure.yaml:

Infrastructuur en implementatiemodi

standaard Bicep

azd ai agent init is standaard bicep-less: er wordt geen map geschreven infra/ en azd wordt de infrastructuur tijdens de inrichting gesynthetiseert van uw azure.yaml services. Als u infrastructuur als codebestanden wilt materialiseren, moet u ze uitwerpen:

Wanneer infra aanwezig is, azure.yamlazd gebruikt u deze bestanden in plaats van infrastructuur te synthetiseren.

Modi implementeren

Een gehoste agent wordt geïmplementeerd in een van de twee modi:

Voor bron-implementaties legt het codeConfiguration veld op de agentservice de runtime en het toegangspunt vast. Stel voor vooraf gedefinieerde installatiekopieën het image veld in de agentservice in en sla de Dockerfile-build over.

Verouderde configuratiemigratie

Oudere agentdefinities kunnen omgevingsvariabelen nesten onder config: env. Verplaats de env toewijzing in de geïntegreerde azure.yamlservice naar de agentservice:

# 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}

JSON-schemavalidatie

Voeg de schemaverwijzing voor automatisch aanvullen van IDE toe:

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

Verwante inhoud

• Azure.yaml ontwerpen voor gehoste agents
• Een gehost agentproject initialiseren met de Azure Developer CLI
• Gehoste agentinfrastructuur met de Azure Developer CLI
• Runtimecontract van gehoste agent
• Wat zijn gehoste agenten?