Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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. Bazd 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>_NAMEAGENT_<SERVICE>_VERSIONAGENT_<SERVICE>_ENDPOINT-
AGENT_<SERVICE>_<PROTOCOL>_ENDPOINTfür aktivierteresponses,invocationsundinvocations_wsProtokolle
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