Azure.yaml-Referenz für gehostete Agents

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Die azure.yaml Datei ist die einzelne Azure Developer CLI(azd)-Projektkonfiguration für ein gehostetes Agentprojekt. Sie deklariert Ihre Foundry-Ressourcen – das Projekt, modellieren Bereitstellungen, Verbindungen, Toolboxen, Fähigkeiten, Routinen und die Agents selbst – als eine Reihe von Diensten und teilt azd ihnen mit, wie sie bereitgestellt und bereitgestellt werden. Diese einheitliche Datei ersetzt das frühere Zwei-Dateimodell, das die Konfiguration zwischen agent.manifest.yaml und .agent.yaml

Informationen zum Verfassen und Erstellen dieser Datei schrittweise finden Sie unter "Autor azure.yaml" für gehostete Agents.

Wie azd azure.yaml verwendet

Die Azure Developer CLI optimiert den Entwickler-zu-Cloud-Workflow. Es behandelt zwei Dinge: Bereitstellen Azure Ressourcen, z. B. Foundry-Projekte, Modellbereitstellungen und Containerregistrierungen und Bereitstellen ihres Codes für diese Ressourcen. Für gehostete Agents fügt die azure.ai.agents Erweiterung agentspezifische Befehle wie azd ai agent init und azd ai agent run.

Jedes azd Projekt hat eine azure.yaml Datei im Stammverzeichnis. Bei Agentprojekten ist diese Datei die Quelle der Wahrheit sowohl für die Agentkonfiguration als auch für die Bereitstellungskonfiguration.

Environments

Eine Umgebung ist eine benannte Konfiguration, z dev. B. , stagingoder prod, die Einstellungen für eine bestimmte Bereitstellung speichert. Jede Umgebung verfolgt das Azure Abonnement und den Standort, die Ressourcengruppen- und Ressourcennamen und alle benutzerdefinierten Variablen, die Sie festlegen. Einstellungen werden lokal gespeichert in .azure/<env-name>/.env. Sie können über mehrere Umgebungen für dasselbe Projekt verfügen.

Kernbefehle

Befehl Was es bewirkt
azd provision Erstellt Azure Ressourcen, z. B. das Foundry-Projekt, Modellbereitstellungen und containerregistrierung.
azd deploy Packt die Quelle für einen Remotebuild, erstellt und veröffentlicht ein Containerimage oder stellt ein vordefiniertes Image bereit und erstellt dann die gehostete Agent-Version.
azd up Kombiniert provision und deploy in einem Einzigen Befehl.
azd down Löscht alle bereitgestellten Ressourcen.
azd env set Legt eine Umgebungsvariable fest, z. B azd env set MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME=gpt-5.4-mini. .

Erweiterungskompatibilität

Die azure.ai.agents Erweiterung stellt den azure.ai.agent Host bereit. Die azure.ai.projects Erweiterung stellt den azure.ai.project Host und den microsoft.foundry Infrastrukturanbieter bereit. Verwenden Sie azure.ai.agents version 1.0.0-beta.8 oder höher mit azure.ai.projects Version 1.0.0-beta.4 oder höher. Installations- und Upgradeanweisungen finden Sie unter Installieren der Azure Developer CLI Foundry-Erweiterungen.

Sie können die mindestkompatiblen Versionen 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"

Lebenszyklus des Dienstanbieters

Installieren Sie das microsoft.foundry Metapaket, wenn Ihr Projekt Verbindungen, Toolboxen, Fähigkeiten oder Routinen enthält. Es installiert die Anbietererweiterungen, die die entsprechenden azure.ai.* Hosts implementieren.

Diensthost Anbietererweiterung Angewendet während
azure.ai.project azure.ai.projects azd provision
azure.ai.connection azure.ai.connections azd provision
azure.ai.toolbox azure.ai.toolboxes azd deploy
azure.ai.agent azure.ai.agents azd deploy
azure.ai.skill azure.ai.skills azd deploy
azure.ai.routine azure.ai.routines azd deploy

Die Projekt- und Verbindungsanbieter wenden ihre Konfiguration während azd provisionder . Der Agent, die Toolbox, die Fähigkeit und die Routineanbieter wenden ihre Konfiguration während azd deployder Ausführung an. Führen Sie den Vorgang azd up aus, um beide Phasen abzuschließen. Wenn Sie einen Datenebenendienst entfernen, wird azure.yaml der Dienst nicht azd mehr verwaltet. Löschen Sie die Remoteressource separat, wenn Sie ihn nicht mehr benötigen.

  • azd down – Löscht die Ressourcengruppe, wenn die aktuelle Umgebung das Foundry-Projekt erstellt hat. Verlässt ein vorhandenes Projekt und seine Ressourcen. |
  • azd env set - Legt eine Umgebungsvariable fest, z. B azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. . |

Das Split-Service-Modell

Unter services, jeder Eintrag ist ein benannter Dienst mit einem host Feld, das die Art der Gießereiressource identifiziert, die deklariert wird. Dienste verweisen über das uses Feld, das ein Abhängigkeitsdiagramm bildet, das azd zur Bereitstellung und Bereitstellungszeit aufgelöst wird. Ein typisches Projekt verfügt über einen azure.ai.project Dienst, der die Modellbereitstellungen und einen azure.ai.agent Dienst besitzt, der davon abhängt.

Gastgeber Ressource Purpose
azure.ai.project Gießereiprojekt Besitzt Modellbereitstellungen und optionale private Netzwerke.
azure.ai.agent Gehosteter Agent oder Eingabeaufforderungs-Agent Trägt die Agentdefinition und deren Build- und Bereitstellungseinstellungen.
azure.ai.connection Projektverbindung Verknüpft das Projekt mit einer externen Ressource, z. B. einem MCP-Server oder einem Suchindex.
azure.ai.toolbox Toolbox (Foundry Toolset) Ein benanntes Bündel von verbindungsgestützten Tools, auf die Agents verweisen.
azure.ai.skill Skill Eine wiederverwendbare Verhaltensrichtlinie, die für alle Agenten freigegeben ist.
azure.ai.routine Routine Ein Trigger plus eine Aktion, die einen Agent aufruft.

Minimales Beispiel

# 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

Vollständiges Beispiel

Das folgende Projekt fügt eine Verbindung, eine Toolbox und ein privates Netzwerk hinzu.

# 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

Felder auf oberster Ebene

Field Erforderlich Description
name Yes Project Namen.
requiredVersions.extensions No Minimale Erweiterungsversionseinschränkungen, z. B azure.ai.agents: '>=0.1.0-preview'. .
metadata No Project Metadaten, z. B. der template Bezeichner.
services Yes Zuordnung von Dienstnamen zu Dienstkonfigurationen.
infra No Infrastruktur-as-Code-Einstellungen. Beim Auswerfen von IaC vorhanden.

Azure.ai.project-Dienst

Der Projektdienst stellt ein Foundry-Projekt bereit oder stellt eine Verbindung her und besitzt seine Modellbereitstellungen.

Field Description
host Muss azure.ai.project sein.
endpoint Endpunkt-URL eines vorhandenen Foundry-Projekts. Wenn festgelegt, wird eine Verbindung mit diesem Projekt hergestellt, azd anstatt ein neues Projekt bereitzustellen. Wenn sie weggelassen wird, azd wird ein neues Projekt festgelegt.
deployments Array von Modellbereitstellungen, die für das Projekt erstellt werden sollen.
network Optionales privates Netzwerk für das Konto, das das Projekt zurückgibt.

deployments

Field Description
name Bereitstellungsname.
model.format Modellformat, z. B OpenAI. .
model.name Modellname, z. B gpt-5.4-mini. .
model.version Modellversionszeichenfolge.
sku.name SKU-Name, z GlobalStandard. B. , Standardoder GlobalBatch.
sku.capacity SKU-Kapazität in Token pro Minute-Einheiten.

Ein Bereitstellungseintrag kann auch eine externe Datei sein: - $ref: ./deployments/embeddings.yaml.

network

Legen Sie diese Einstellung network fest, um ein netzwerkgeschütztes Konto bereitzustellen. Das peSubnet Feld ist erforderlich und richtet den privaten Kontoendpunkt ein. Fügen Sie agentSubnet die Agentlaufzeit in Ihr eigenes Subnetz ein (bringen Sie Ihr eigenes virtuelles Netzwerk), oder lassen Sie sie aus, um das Microsoft verwaltete Netzwerk zu verwenden. Eine vollständige exemplarische Vorgehensweise finden Sie unter private Netzwerke des gehosteten Agents.

Konfiguration des privaten Netzwerks

Verwenden Sie network den azure.ai.project Dienst, um den privaten Kontoendpunkt und den Agentausgang zu konfigurieren. Im folgenden Beispiel wird ein vom Kunden verwaltetes Subnetz für die Agentlaufzeit verwendet:

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}
Field Erforderlich Description
peSubnet Yes Das Subnetz für den privaten Endpunkt des Foundry-Kontos. Es erfordert vnet und name. Fügen Sie hinzu prefix , wann azd das Subnetz erstellt werden soll.
agentSubnet No Ein vom Kunden verwaltetes Subnetz für den Ausgang des gehosteten Agents. Sie erfordert vnet und namemuss ein anderes Subnetz im selben virtuellen Netzwerk sein wie peSubnet.
isolationMode No Der ausgehende Haltung für Microsoft verwalteten Ausgang. Verwenden Sie sie nur, wenn Sie es weglassen agentSubnet. Gültige Werte sind AllowInternetOutbound und AllowOnlyApprovedOutbound.
dns.resourceGroup No Die Ressourcengruppe, die vorhandene private DNS-Zonen enthält. Lassen Sie es weg, um die erforderlichen Zonen zu azd erstellen und zu verknüpfen.
dns.subscription No Das Abonnement, das vorhandene private DNS-Zonen enthält. Standardmäßig wird das Bereitstellungsabonnement verwendet.

Private Netzwerke deaktivieren den Zugriff auf öffentliche Datenebene für das Konto. Eine automatisch erstellte Azure Container Registry wird mit dieser Konfiguration nicht unterstützt. Verwenden Sie die Quellcodebereitstellung, oder geben Sie einen vordefinierten imageCode an.

azure.ai.agent-Dienst

Der Agentdienst trägt die Agentdefinition und die zugehörigen Build- und Bereitstellungseinstellungen. Es ist der Dienst, der das alte agent.yamlersetzt.

Field Description
host Muss azure.ai.agent sein.
kind Agent-Art. Wird hosted für containerisierte Agents verwendet, die aus der Quelle erstellt wurden.
name Name des Agenten. Durch die erneute Nutzung eines Namens wird eine neue Version des vorhandenen Agents erstellt.
displayName Optionaler benutzerfreundlicher Anzeigename.
description Optionale Beschreibung des Agenten.
project Pfad zum Agent-Quellverzeichnis, z. B src/my-agent. .
language Erstellen Sie die Sprache für gehostete Agents. Verwenden Sie docker.
uses Liste der Dienste, von der dieser Agent abhängig ist, z. B. projekt, verbindungen und Toolboxen.
protocols Aufrufprotokolle, die der Agent implementiert.
env Zuordnung von Umgebungsvariablen, die an den Container übergeben werden.
container Cpu- und Speichereinstellungen für Container.
startupCommand Befehl, der den Agentserver startet, z. B python main.py. . Wird für azd ai agent run die lokale Entwicklung und für den Containerstart verwendet.
toolboxes Liste der azure.ai.toolbox Dienstnamen, die der Agent zur Laufzeit verwendet.
codeConfiguration Die Einstellungen für die Quellbereitstellung (ZIP) werden bereitgestellt. Siehe Bereitstellen von Modi.
image Vordefinierte Containerimage-URL. Wenn festgelegt, azd stellt das Image direkt bereit und überspringt den Dockerfile-Build.
metadata Optionale Metadatenschlüssel-Wert-Paare.
agentCard Ermittlungsmetadaten auf Agentebene, einschließlich skills.

agentCard.skills und azure.ai.skill

agentCard.skills beschreibt die Funktionen eines Agents auf seiner Ermittlungskarte. Es stellt Metadaten für Clients bereit und erstellt oder fügt keine wiederverwendbaren Foundry-Fähigkeiten hinzu. Jede Kartenfähigkeit erfordert ein id, name, und description.

Ein azure.ai.skill Dienst erstellt eine versionierte Fähigkeit aus Anweisungen und optional zulässigen Tools. Deklarieren Sie sie separat unter services; ihre uses Listensteuerelement-Abhängigkeitsreihenfolge, aber sie füllt die Fähigkeit nicht agentCard.skills auf oder fügt sie an einen Agenten an. Wird agentCard.skills für Ermittlungsmetadaten und azure.ai.skill für wiederverwendbare Anweisungen verwendet.

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

Abschließen einer Ermittlungskarte

Hinzufügen version, , tagsund examples wenn Clients umfangreichere Ermittlungsmetadaten benötigen. Eine Karte erfordert mindestens description eine Fähigkeit. Jede Fähigkeit erfordert eine id, name, und 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.

Verantwortungsvolle KI-Richtlinien

Dient policies zum Zuordnen einer verantwortungsvollen KI-Richtlinie zum gehosteten Agent. Legen Sie raiPolicyName die vollständige ARM-Ressourcen-ID der Richtlinie fest:

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

Der rai_policy Typ und raiPolicyName sind erforderlich. Die Erweiterung wendet die erste gültige Richtlinie in der Liste auf die Konfiguration der verantwortlichen KI des gehosteten Agents an. Richtlinienerstellungs- und Verwaltungsleitlinien finden Sie unter Hinzufügen von Schutzläufen zu gehosteten Agents.

Speicherspeicher

Dient memoryStores zum Erstellen oder Wiederverwenden von Speicherspeichern für Gießerei vor der Bereitstellung. Jeder Speicher erfordert vorhandene Chatmodell- und Einbettungsmodellbereitstellungsnamen.

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
Field Erforderlich Description
name Yes Der Speichername.
description No Eine Beschreibung des Speichers.
chatModel Yes Die Chatmodellbereitstellung, die zum Verarbeiten von Speicherinhalten verwendet wird.
embeddingModel Yes Die Einbettungsmodellbereitstellung, die zum Verarbeiten von Speicherinhalten verwendet wird.
options.chatSummaryEnabled No Aktiviert den Chatzusammenfassungsspeicher.
options.userProfileEnabled No Aktiviert den Benutzerprofilspeicher.
options.proceduralMemoryEnabled No Aktiviert den prozeduralen Speicher.
options.defaultTtlSeconds No Legt den Standardaufbewahrungszeitraum in Sekunden fest. Wird ohne Ablauf festgelegt 0 .
options.userProfileDetails No Enthält Anleitungen zu den profildaten, die aufbewahrt werden sollen.

Vorhandene Stores werden während der Bereitstellung nicht aktualisiert. Wenn sich die deklarierte Definition vom vorhandenen Speicher unterscheidet, azd wird der Unterschied gemeldet. Durch das Deklarieren eines Speicherspeichers wird Ihr Agentcode nicht geändert oder ein Speichertool automatisch angefügt. Verbinden Sie Ihre Anwendung mit dem Speicherspeicher, indem Sie das Speichersuchtool oder speicherspeicher-APIs verwenden. Ausführliche Informationen finden Sie unter "Verwenden des Arbeitsspeichers mit Agents".

Konfigurieren eines Agentendpunkts

Dient agentEndpoint zum Konfigurieren der Protokolle und Autorisierungsschemas, die vom Agentendpunkt veröffentlicht wurden. Verwenden Sie eine Agentkarte mit einem A2A-Endpunkt, damit andere Agents die verfügbaren Funktionen ermitteln können.

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

Sie können auch definieren versionSelector.versionSelectionRules , wann Sie steuern müssen, welche Agentversion Endpunktdatenverkehr empfängt. Der Agentdienst überprüft endpunktbasierte Protokoll- und Autorisierungswerte während der Bereitstellung.

protocols

protocols:
    - protocol: responses
      version: 2.0.0
Protocol Description
responses OpenAI-Antwort-API. Umfasst die Verwaltung des Unterhaltungsverlaufs.
invocations Benutzerdefiniertes Nutzlastprotokoll. Keine integrierte Unterhaltungsverwaltung.
a2a Agent-zu-Agent-Protokoll für die Agent-Orchestrierung.

Die vollständige Protokollspezifikation finden Sie unter Vertrag für gehostete Agent-Laufzeit.

Zusätzliche Laufzeitprotokolle und Aktivitätsendpunkte

Zusätzlich zu responses, invocationsund a2a, gehosteten Agents Unterstützung invocations_ws für WebSocket-Aufrufe und activity für Microsoft 365- und Teams-Aktivitätsszenarien.

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

Fügen Sie activity für einen Aktivitäts-Agent die Konfiguration des öffentlichen Endpunkts hinzu, und verwenden Sie das erforderliche Bot Service Autorisierungsschema:

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

Das Aktivitätsprotokoll kann mit anderen Protokollen auf demselben Agentendpunkt koexistieren. Informationen zum Laufzeitprotokollverhalten finden Sie unter Was sind gehostete Agents?.

env

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

Die ${ } Syntax verweist auf azd Umgebungsvariablen aus .azure/<env>/.env.

Note

Deklarieren FOUNDRY_PROJECT_ENDPOINT Sie nicht in env. Die Plattform fügt sie automatisch in gehostete Container ein und azd ai agent run legt sie für die lokale Entwicklung fest. Das Deklarieren ist hier redundant und riskiert, den Plattformwert zu schattieren.

Plattformumgebung, Identität und Endpunkte

Die Plattform behält sich die FOUNDRY_ Präfixe vor AGENT_ . Lesen Sie Plattformvariablen, z FOUNDRY_PROJECT_ENDPOINT. B. aus Ihrem Anwendungscode, definieren oder überschreiben Sie sie jedoch nicht in env. Agentdefinierte Umgebungswerte sind Zeichenfolgen.

Jeder bereitgestellte gehostete Agent empfängt eine dedizierte Microsoft Entra ID Agentidentität und -endpunkt. Fügen Sie dem Agentdienst keinen Block hinzu identity . Die Agentidentität kann standardmäßig den Projektendpunkt und den Sitzungsspeicher verwenden. Weisen Sie die Identitätsrollen zu, wenn der Agent auf externe Ressourcen zugreifen muss. Ausführliche Informationen finden Sie unter Referenz zu Berechtigungen für gehostete Agent.

Die Protokolle, die Sie deklarieren, bestimmen die Endpunkte, die nach der Bereitstellung aktiv sind. Führen Sie die Ausführung aus azd ai agent show , um den bereitgestellten Agent und seine Endpunkt-URLs zu überprüfen.

Schreibt nach der Bereitstellung azd die folgenden Werte in die aktive Umgebung, wobei der normalisierte Dienstname anstelle von <SERVICE>:

  • AGENT_<SERVICE>_NAME
  • AGENT_<SERVICE>_VERSION
  • AGENT_<SERVICE>_ENDPOINT
  • AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT für aktivierte responses, invocationsund invocations_ws Protokolle

Verwenden Sie die protokollspezifische Ausgabe, wenn Ihre Anwendung oder Automatisierung eine Aufruf-URL benötigt. Der Basisendpunkt identifiziert die bereitgestellte Agentversion für Sitzungsverwaltungsvorgänge.

container

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

cpu Von "0.25" bis zu "4.0", und memory von 0.5Gi bis .8.0Gi

Quellcodebereitstellung

Legen Sie fest codeConfiguration , dass Quellcode anstelle eines Containerimages als ZIP-Datei bereitgestellt wird. Geben Sie einen Einstiegspunktdateinamen oder Assemblynamen an. azd kombiniert sie mit der ausgewählten Laufzeit, wenn sie die Version des gehosteten Agents erstellt.

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

Wird verwendet remote_build , um Abhängigkeiten aus den Projektquellen wiederherzustellen oder zu verwenden bundled , wenn die ZIP Linux-kompatible Abhängigkeiten enthält. Kombinieren Sie nicht codeConfiguration mit der imagebasierten Containerkonfiguration. Informationen zum Packen und Abhängigkeitsleitfaden finden Sie unter Bereitstellen eines gehosteten Agents aus dem Quellcode.

Containerbuilds und vorgefertigte Images

Verwenden Sie eine Dockerfile Unterversion project , um ein Containerimage zu erstellen oder festzulegen image , um ein vordefiniertes Image bereitzustellen:

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

Wenn ein und eins Dockerfileimage verfügbar ist, wählen Sie das vordefinierte Image in der interaktiven Bereitstellungsaufforderung aus. Legen Sie für die unbeaufsichtigte Bereitstellung in der aktiven azd Umgebung festtrue, AZD_AGENT_SKIP_ACR um das konfigurierte Image auszuwählen. Informationen zu Registrierungsberechtigungen und der Bereitstellung privater Registrierung finden Sie unter Bereitstellen eines gehosteten Agents mit einem privaten Azure Container Registry.

Metadaten- und Schemabeschränkungen

Verwenden Sie Zeichenfolgenwerte für bereitgestellte Agentmetadaten. Der authors Metadatenwert kann eine Liste von Zeichenfolgen sein. Verlassen Sie sich nicht auf displayNameden inputSchemabereitgestellten gehosteten Agent oder outputSchema konfigurieren Sie den bereitgestellten gehosteten Agent. Die einheitliche Konfiguration akzeptiert diese Felder, aber die Anforderung zum Erstellen des gehosteten Agents verwendet sie nicht.

azure.ai.connection service

Eine Verbindung verknüpft das Projekt mit einer externen Ressource. Der Dienstschlüssel ist der Verbindungsname, und der Dienst hängt vom Projekt ab uses.

Field Description
host Muss azure.ai.connection sein.
category Verbindungskategorie, z. CustomKeysB. , , ApiKey, AzureOpenAI, CognitiveSearchoder RemoteTool.
target Zielendpunkt-URL oder ARM-Ressourcen-ID.
authType Authentifizierungstyp, z ApiKey. B. , CustomKeys, AAD, , ManagedIdentityoder OAuth2.
credentials Anmeldeinformationen für die Verbindung. Werte können Verweise enthalten ${VAR} .
metadata Zusätzliche Metadaten als Schlüsselwertpaare.
github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

Verbindungsänderungen gelten während azd provision, nicht azd deploy. Speichern Sie Anmeldeinformationswerte in Ihrer azd Umgebung, und verweisen Sie darauf, ${VAR} statt geheime Schlüssel einzugeben azure.yaml.

Azure.ai.toolbox-Dienst

Eine Toolbox ist ein benanntes Bündel von Tools, auf die Agents verweisen. Verbindungsgestützte Tools nennen einen azure.ai.connection Dienst über das connection Feld.

Field Description
host Muss azure.ai.toolbox sein.
description Beschreibung der Toolbox.
tools Liste der Tools. Jeder Eintrag verfügt über ein type und, für verbindungsgestützte Tools, ein connection.
research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

Ein Agent verweist auf eine Toolbox, indem er den Namen des Toolboxdiensts zu beiden uses und deren toolboxes Liste hinzufügt.

Nutzen eines Toolboxendpunkts

Steuert in einem Projekt uses mit geteiltem Dienst die Bereitstellungsreihenfolge. Ihre Anwendung stellt zur Laufzeit eine Verbindung mit dem MCP-Endpunkt der Toolbox bereit. Übergeben Sie den Toolboxnamen oder endpunkt an envIhre Anwendung, und erstellen Sie dann den Consumerendpunkt aus FOUNDRY_PROJECT_ENDPOINT Ihrem Agentcode. Ein End-to-End-Beispiel finden Sie unter Verwenden einer Toolbox mit einem gehosteten Agent.

azure.ai.skill und azure.ai.routine services

Ein azure.ai.skill Dienst definiert eine wiederverwendbare Verhaltensrichtlinie, die agents anhand des Namens referenziert. Ein azure.ai.routine Dienst definiert einen Trigger (Zeitplan oder Ereignis) und eine Aktion, die einen Agent aufruft. Beide hängen von den Ressourcen ab, die sie verwenden uses. Weitere Informationen zum Hinzufügen von Tools für die Agentverwendung finden Sie unter Was ist Toolbox in Foundry? und Verwenden von Routinen.

Fähigkeiten und Routinen sind separate Ressourcen. Durch das Deklarieren eines Diensts wird der Lebenszyklus gesteuert, dem Agent aber nicht automatisch eine Fähigkeit zugeordnet oder ein Routineaktionsziel ableiten. Konfigurieren Sie die verbrauchende Anwendung oder Routineaktion explizit.

Abhängigkeiten mit Verwendungen

Das uses Feld deklariert die Dienste, von der ein bestimmter Dienst abhängt. azd verwendet dieses Diagramm, um die Bereitstellung zu bestellen und Verweise zu verdrahten, z. B. verbindungen und Toolboxen eines Agents.

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

Datei enthält $ref

Jeder Dienst- oder Listeneintrag kann durch einen Verweis auf eine externe YAML- oder JSON-Datei ersetzt werden. Relative Pfade werden aus der Datei aufgelöst, die die $refDatei enthält. Remote-URLs werden nicht unterstützt.

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

Die Datei enthält die Möglichkeit, große Agentdefinitionen in ihren eigenen Dateien zu speichern und Definitionen für alle Projekte freizugeben.

Behalten Sie die Kerndienstfelder im Stammeintrag azure.yaml bei, wenn Sie einen Dienst $refverwenden: host, , uses, project, , language, imageund docker. Platzieren Sie im Besitz von Anbieterdefinitionsfeldern, z kind. B. , name, descriptionund protocols, in der referenzierten Zuordnung. $ref löst lokale YAML- oder JSON-Dateien rekursiv auf; URLs und Referenzzyklen werden nicht unterstützt.

Variablenersetzung

Zwei Ersetzungsssyntaxen können in azure.yaml:

Syntax Behoben, wenn Nach dem, was
${VAR_NAME} azd provision oder azd deploy azd Umgebungsvariablen von .azure/<env>/.env, aufgelöst clientseitig.
${{ ... }} Zur Laufzeit Serverseitige Gießereiauflösung. azd durchläuft diese unberührt.

Infrastruktur und Bereitstellungsmodi

standardmäßig Bicep-weniger

azd ai agent initist standardmäßig bicep-weniger: Es schreibt kein Verzeichnis und infra/ synthetisiert azd die Infrastruktur von Ihren azure.yaml Diensten zur Bereitstellungszeit. Um Infrastruktur-as-Code-Dateien zu materialisieren, werfen Sie sie aus:

Befehl Result
azd ai agent init --infra Auswurf Bicep in ./infra/.
azd ai agent init --infra=bicep Ausjekte Bicep (explizit).
azd ai agent init --infra=terraform Ejects Terraform und Sets infra.provider: terraform.

Wenn infra sie azure.yamlvorhanden ist, azd werden diese Dateien anstelle der Synthesizing-Infrastruktur verwendet.

Bereitstellen von Modi

Ein gehosteter Agent wird in einem von zwei Modi bereitgestellt:

Modus So funktioniert es Wie man auswählt
code azd lädt Ihre Quelle als ZIP hoch und erstellt sie remote. Dies ist die Standardeinstellung für Python- und .NET Projekte. azd ai agent init --deploy-mode code
container azd erstellt ein Docker-Image von Ihrem Dockerfile und stellt es bereit. azd ai agent init --deploy-mode container

Für die Quellbereitstellung erfasst das codeConfiguration Feld im Agentdienst die Laufzeit und den Einstiegspunkt. Legen Sie für vorgefertigte Images das image Feld für den Agentdienst fest, und überspringen Sie den Dockerfile-Build.

Legacykonfigurationsmigration

Ältere Agentdefinitionen können Umgebungsvariablen unter schachteln.config: env Verschieben Sie im einheitlichen azure.yamlBereich die env Zuordnung zum Agentdienst:

# 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-Schemaüberprüfung

Fügen Sie den Schemaverweis für die automatische IDE-Vervollständigen hinzu:

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