Einrichten privater Netzwerke für den Foundry-Agent-Dienst

Der Foundry Agent Service bietet ein Standardsetup mit privater Netzwerkumgebung . Dieses Setup erstellt eine isolierte Netzwerkumgebung, die den sicheren Zugriff auf Daten ermöglicht und gleichzeitig die vollständige Kontrolle über Ihre Netzwerkinfrastruktur erhält.

Standardmäßig stellt das Standardsetup mit privaten Netzwerken folgendes sicher:

• Kein öffentlicher Ausgang: Die foundationale Infrastruktur bietet die richtige Authentifizierung und Sicherheit für Ihre Agents und Tools, ohne dass eine vertrauenswürdige Dienstumgehung erforderlich ist.
• Subnetzintegration: Sie stellen ein delegiertes Subnetz aus Ihrem virtuellen Netzwerk bereit. Die Plattform verbindet agent compute mit diesem Subnetz und ermöglicht die lokale Kommunikation mit Ihren Azure Ressourcen innerhalb desselben virtuellen Netzwerks.
• Zugriff auf private Ressourcen: Wenn Ihre Ressourcen im Internet als privat und nicht erkennbar gekennzeichnet sind, kann das Plattformnetzwerk weiterhin darauf zugreifen, wenn die erforderlichen Anmeldeinformationen und Autorisierung vorhanden sind.

Wenn Sie nicht über ein vorhandenes virtuelles Netzwerk verfügen, kann das Standardsetup mit privatem Netzwerkfluss die erforderliche Netzwerkinfrastruktur für Sie bereitstellen.

Voraussetzungen

• Ein Azure-Abonnement – Create one for free.

• Stellen Sie sicher, dass die Person, die das Konto und das Projekt erstellt, über die Rolle " Besitzer des Foundry-Kontos " im Abonnementbereich verfügt.

  Wichtig

  Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

• Der Benutzer, der dieses Setup erstellt, muss auch über Berechtigungen zum Zuweisen von Rollen zu erforderlichen Ressourcen verfügen (Azure Cosmos DB, Azure KI-Suche, Azure Storage).

  • Die integrierte Rolle ist rollenbasierter Zugriffsadministrator.
  • Alternativ erfüllt auch die Rolle " Besitzer " auf Abonnementebene diese Anforderung.
  • Die erforderliche Schlüsselberechtigung lautet: Microsoft.Authorization/roleAssignments/write

• Python 3,9 oder höher

• Nachdem die Agentumgebung konfiguriert wurde, stellen Sie sicher, dass jedem Teammitglied, das den Agent-Playground oder das SDK zum Erstellen oder Bearbeiten von Agents verwenden möchte, die integrierte RBAC-Rolle des Foundry User RBAC für das Projekt zugewiesen wurde.

  • Die mindeste Anzahl der erforderlichen Berechtigungen ist: Agents/*/read, agents/*/action, agents/*/delete

• Registrieren Sie Anbieter. Die folgenden Anbieter müssen registriert werden:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • So verwenden Sie das Bing Search-Tool: Microsoft.Bing

     az provider register --namespace 'Microsoft.KeyVault'
     az provider register --namespace 'Microsoft.CognitiveServices'
     az provider register --namespace 'Microsoft.Storage'
     az provider register --namespace 'Microsoft.MachineLearningServices'
     az provider register --namespace 'Microsoft.Search'
     az provider register --namespace 'Microsoft.Network'
     az provider register --namespace 'Microsoft.App'
     az provider register --namespace 'Microsoft.ContainerService'
     # only to use Grounding with Bing Search tool
     az provider register --namespace 'Microsoft.Bing'
  

Konfigurieren einer netzwerksicherten Umgebung

Sie können dieses Setup im Azure Portal erstellen oder mit Bicep oder Terraform bereitstellen.

Auf einer übergeordneten Ebene umfasst die Bereitstellung die folgenden Schritte:

1. Wählen Sie die Ziel-Azure-Region für Ihre Foundry-Ressourcen aus.
2. Entscheiden Sie, ob Sie Ihr eigenes VNet und Subnetz verwenden oder automatisch bereitgestellte Netzwerke verwenden möchten.
3. Wenn Sie Ihr eigenes VNet mitbringen, sammeln Sie Ihre VNet- und Subnetzressourcen-IDs.
4. Erstellen Sie das Setup im Azure-Portal, oder stellen Sie es mithilfe von Bicep oder Terraform bereit.
5. Überprüfen Sie die Bereitstellung (siehe Überprüfen der Bereitstellung).

Die Einrichtung stellt die folgenden Ressourcen bereit, sofern Sie nicht Ihre eigenen Ressourcen mitbringen:

• Ein Foundry-Konto und ein Foundry-Projekt.
• Die Bereitstellung eines gpt-4o-Modells.
• Azure Storage, Azure Cosmos DB und Azure KI-Suche zum Speichern von Dateien, Threads und Vektordaten.
• Diese Ressourcen sind mit Ihrem Projekt verbunden.
• Von Microsoft verwaltete Verschlüsselungsschlüssel für das Speicherkonto und das kognitive Konto (Foundry) werden standardmäßig verwendet.

Wählen Sie Ihre bevorzugte Bereitstellungsmethode mithilfe der folgenden Registerkarten aus.

Überprüfen Sie die Bereitstellung

Überprüfen Sie nach Abschluss der Bereitstellung, ob alle Ressourcen ordnungsgemäß konfiguriert sind:

1. Navigieren Sie im Azure-Portal zu Ihrem VNet > und überprüfen Sie, ob das Agent-Subnetz die Delegierung an anzeigt.
2. Öffentlichen Netzwerkzugriff überprüfen: Öffnen Sie jede Ressource (Foundry, Azure KI-Suche, Azure Storage, Azure Cosmos DB) und bestätigen Sie, dass der Öffentliche Netzwerkzugriff auf Deaktiviert gesetzt ist.
3. Überprüfen der DNS-Auflösung des privaten Endpunkts: Von einem Computer, der mit dem VNet verbunden ist, führen Sie die Ausführung nslookup für jeden Endpunkt aus, der in der Zusammenfassung der DNS-Zonenkonfigurationen aufgeführt ist.
4. Testen Sie die Agentkonnektivität: Greifen Sie über das VNet auf Ihr Foundry-Projekt zu (siehe Zugriff auf Ihre gesicherten Agents), und bestätigen Sie, dass Sie einen Agent erstellen und ausführen können.
5. Rollenzuweisungen konfigurieren: Führen Sie die folgenden Befehle aus, um die erforderlichen Rollen zuzuweisen. Die erste gewährt die Rolle „Operator für verwaltete Identität“ für die benutzerzugewiesene verwaltete Identität, und die zweite gewährt die Rolle „Netzwerkmitwirkender“ für das Remote-VNet für den mandantenübergreifenden Zugriff.

az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

Einschränkungen

• Einschränkung der VNET- und Subnetz-IP-Adresse:
  • Das delegierte Subnetz Ihres Agent-Diensts muss IP-Adressbereiche innerhalb der gültigen privaten RFC1918-IPv4-Adressbereiche aufweisen: 10.0.0.0/8, 172.16-31.0.0/12 oder 192.168.0.0/16, auch als private IP-Adressbereiche der Klasse A, Klasse B und Klasse C bezeichnet.
  • Private Class A IP-Adressbereiche (10.0.0.0/8) werden in jeder Region unterstützt, in der der Agentdienst verfügbar ist. Die aktuelle Liste finden Sie unter "Unterstützte Regionen".
  • Öffentliche IP-Bereiche wie 44.x.x.x CGNAT-Adressbereiche 100.64.0.0–100.127.255.255 werden für das delegierte Subnetz des Agentdiensts nicht unterstützt.
  • Stellen Sie sicher, dass sich die Adressräume Ihres VNET nicht mit vorhandenen Netzwerken in Ihrer Azure Umgebung oder reservierten IP-Bereichen wie den folgenden überlappen: 169.254.0.0/16, , , 172.30.0.0/16172.31.0.0/16192.0.2.0/240.0.0.0/8127.0.0.0/8100.100.0.0/17, 100.100.192.0/19, . 100.100.224.0/19100.64.0.0/11 Diese Anforderung schließt alle Adressräume ein, die Sie in Ihrem VNET haben und, falls Sie mehr als einen haben, auch gekoppelte VNETs.
• Exklusivität des Agent-Subnetzs: Das Agent-Subnetz kann nicht von mehreren Foundry-Ressourcen gemeinsam genutzt werden. Jede Foundry-Ressource muss ein dediziertes Agent-Subnetz verwenden.
• Agent-Subnetzgröße: Die empfohlene Größe des delegierten Agent-Subnetzes ist /24 (256 Adressen) aufgrund der Delegierung des Subnetzes an Microsoft.App/environments. Weitere Informationen zur Subnetzgröße finden Sie unter Configuring virtual networks for Azure Container Apps.
• Zulassungsliste für die Ausgangsfirewall des Agent-Subnetzes: Wenn Sie eine Azure Firewall mit Ihrem per privatem Netzwerk geschützten Standard-Agent integrieren, fügen Sie der Zulassungsliste die vollqualifizierten Domänennamen (Fully Qualified Domain Names, FQDNs) hinzu, die im Artikel „In Azure Firewall integrieren“ unter Managed Identity aufgeführt sind, oder fügen Sie das Service-Tag AzureActiveDirectory hinzu. Wenn Sie Netzwerksicherheitsgruppen (Network Security Groups, NSGs) auf das delegierte Agent-Subnetz oder verwandte Subnetze anwenden, konfigurieren Sie übereinstimmende ausgehende Zulassungsregeln für erforderliche Abhängigkeiten, einschließlich des AzureActiveDirectory-Diensttags für Microsoft Entra ID Authentifizierung. Wenn firewall- oder NSG-Regeln erforderliche Abhängigkeiten blockieren, können Agentbereitstellungs- und Laufzeitvorgänge fehlschlagen.
  • Stellen Sie sicher, dass in der Firewall keine TLS-Überprüfung erfolgt, die ein selbstsigniertes Zertifikat hinzufügen kann. Überprüfen Sie bei Fehlern, ob Datenverkehr in der Firewall landet und welcher Datenverkehr blockiert wird.
  • Für Quellcode-Agent-Bereitstellungen können sie auch die Bereitstellungsendpunkte zulassen, die in den Firewallanforderungen für private virtuelle Netzwerke aufgeführt sind.
• Die Foundry-Ressource muss in derselben Region wie das virtuelle Netzwerk (VNet) bereitgestellt werden. Andere Azure Ressourcen wie Azure Cosmos DB, Azure KI-Suche und Azure Storage können in verschiedenen Regionen bereitgestellt werden. Berücksichtigen Sie die Kostenauswirkungen von regionsübergreifenden Bereitstellungen.
• Verfügbarkeit der Region:
  • Unterstützte Regionen für Modellbereitstellungen finden Sie unter: Azure Unterstützung der OpenAI-Modellregion.
• Azure Blob Storage: Die Verwendung von Azure Blob Storage Dateien mit dem Tool "Dateisuche" wird nicht unterstützt.
• Einschränkungen der Codedolmetscherdatei: In einer BYO-Konfiguration (Private Network) funktioniert CodeDolmetscher nur in Szenarien, in denen Dateiuploads oder Downloads nicht einbezogen werden. Das Tool kann keine Dateien aus dem Speicherkonto in diesem Setup abrufen. Wenn Sie Dateien mit Code Interpreter verwenden müssen, müssen Sie das SDK verwenden, um explizit einen Container mit den erforderlichen Dateien zu erstellen und dann den container_id an Code Interpreter zu übergeben. Diese Problemumgehung ist nur über das SDK verfügbar; Die Benutzeroberfläche des Foundry-Portals unterstützt sie nicht.
• Bodenierung mit Bing Search: Nur die folgenden Regionen werden unterstützt: Westeuropa, Kanada Ost, Schweiz Nord, Spanien Zentral, VAE Nord, Korea Zentral, Polen Zentral, Südostasien, West-USA, West-USA 2, West-USA 3, Ost-USA, Ost-USA 2, Zentral-USA, Südindien, Japan Ost, VEREINIGTEs Königreich Süd, Frankreich Zentral, Norwegen Ost, Australien, Kanada, Zentral, Schweden, Südafrika Nord, Italien Nord, Brasilien Süd
• Löschen der Netzwerkeinspeisung: Wenn Sie Ihre Foundry-Ressource und Ihren Standardagent mit gesicherter Netzwerkeinrichtung löschen möchten, löschen Sie Ihre Foundry-Ressource und Ihr virtuelles Netzwerk zuletzt. Bevor Sie das virtuelle Netzwerk löschen, löschen und bereinigen Sie Ihre Foundry-Ressource.
• Injektion in ein virtuelles Netzwerk für gehostete Agents: Bei gehosteten Agents muss die Konfiguration des virtuellen Netzwerks (Netzwerkinjektion) angegeben werden, wenn Sie das Foundry-Konto erstmals erstellen. Das Hinzufügen einer Netzwerkinjektion zu einem bestehenden Foundry-Konto nach dessen Erstellung wird für gehostete Agenten nicht unterstützt.
• Die Registrierung eines gehosteten Agentcontainers hinter einem privaten Netzwerk: Für gehostete Agents hängt die Unterstützung für eine Azure Container Registry (ACR) hinter einem privaten Netzwerk (privater Endpunkt mit deaktiviertem öffentlichem Netzwerkzugriff) davon ab, wann das Foundry-Projekt erstellt wurde. Projekte, die nach dem 25. Juni 2026 erstellt wurden, unterstützen einen privaten ACR. Projekte, die vor diesem Datum erstellt wurden, erfordern, dass der ACR über seinen öffentlichen Endpunkt erreichbar ist, damit die Plattform das Image abrufen kann. Vorhandene Projekte sind nicht betroffen und verwenden weiterhin den Zugriff auf das öffentliche Netzwerk.

Architekturdiagramm

Überprüfen der bereitgestellten Netzwerkressourcen

Die folgenden Ressourcen werden automatisch bereitgestellt, wenn Sie Standardsetup mit privaten Netzwerken verwenden, es sei denn, Sie bringen eigene:

Netzwerkinfrastruktur

• Ein virtuelles Netzwerk (192.168.0.0/16)
• Agent-Subnetz (192.168.0.0/24): hostet den Agent-Client
• Subnetz des privaten Endpunkts (192.168.1.0/24): Hosting privater Endpunkte

Virtuelle Netzwerkfunktionen

Ihr virtuelles Netzwerk steuert, welche Endpunkte API-Aufrufe an Ihre Ressourcen tätigen können. Der Azure-Dienst lehnt API-Aufrufe von Geräten außerhalb Ihres definierten Netzwerks automatisch ab.

Netzwerkregeln

Alle Konten und ihre entsprechenden Projekte sind standardmäßig mit dem Flag "Deaktiviert" des öffentlichen Netzwerks geschützt, das explizite Konfiguration erfordert, um den Zugriff über private Endpunkte zu ermöglichen. Diese Regeln gelten für alle Protokolle, einschließlich REST und WebSocket.

Zusammenfassung der DNS-Zonenkonfigurationen

Verwenden Sie zum Erstellen einer bedingten Weiterleitung im DNS-Server an den Azure DNS Virtual Server die Liste der in der obigen Tabelle erwähnten Zonen. Die AZURE DNS IP-Adresse des virtuellen Servers ist 168.63.129.16.

Zugriff auf Ihre gesicherten Agents

Nachdem die Bereitstellung abgeschlossen ist, können Sie auf Ihr Foundry-Projekt hinter einem virtuellen Netzwerk zugreifen, indem Sie eine der folgenden Methoden verwenden:

• Azure VPN Gateway: Verbindet lokale Netzwerke über eine private Verbindung mit dem virtuellen Netzwerk. Die Verbindung erfolgt über das öffentliche Internet. Es gibt zwei Arten von VPN-Gateways, die Sie verwenden können:
  • Point-to-Site: Jeder Clientcomputer verwendet einen VPN-Client, um eine Verbindung mit dem virtuellen Netzwerk herzustellen.
  • Standort-zu-Standort: Ein VPN-Gerät verbindet das virtuelle Netzwerk mit Ihrem lokalen Netzwerk.
• ExpressRoute: Verbindet lokale Netzwerke über eine private Verbindung mit der Cloud. Die Verbindung erfolgt über einen Verbindungsanbieter.
• Azure Bastion: In diesem Szenario erstellen Sie einen Azure virtuellen Computer (manchmal als Sprungfeld bezeichnet) innerhalb des virtuellen Netzwerks. Anschließend stellen Sie mithilfe von Azure Bastion eine Verbindung mit dem virtuellen Computer her. Bastion ermöglicht es Ihnen, eine Verbindung mit dem virtuellen Computer über eine RDP- oder SSH-Sitzung über Ihren lokalen Webbrowser herzustellen. Anschließend verwenden Sie das Sprungfeld als Entwicklungsumgebung. Da es sich im virtuellen Netzwerk befindet, kann er direkt auf den Arbeitsbereich zugreifen.

Häufig gestellte Fragen

Welchen Adressbereich sollte ich für das virtuelle Gesamtnetzwerk verwenden?

Der Adressbereich des virtuellen Netzwerks kann ein beliebiger privater IP-Bereich sein, der ausreichend Adressraum sowohl für das Subnetz des delegierten Agents als auch für das private Endpunkt-Subnetz bietet.

Kann ich peering-verbundene virtuelle Netzwerke verwenden oder Ressourcen in verschiedenen virtuellen Netzwerken unterbringen?

Gekoppelte virtuelle Netzwerke werden unterstützt, aber die Datenübertragungskosten können steigen.

Können mehrere Foundry-Ressourcen dasselbe virtuelle Netzwerk und dasselbe Subnetz wiederverwenden?

Ja, dasselbe VNET, aber nicht dasselbe Subnetz. Mehrere Foundry-Ressourcen können dasselbe virtuelle Netzwerk wiederverwenden. Jede Foundry-Ressource erfordert jedoch ein eigenes dediziertes Agent-Laufzeit-Subnetz. Das Agent-Subnetz kann nicht für mehrere Foundry-Ressourcen freigegeben werden.

Muss sich das virtuelle Netzwerk in derselben Ressourcengruppe wie die Foundry-Ressource befinden?

Nein. Das virtuelle Netzwerk und die Foundry-Ressource müssen sich nicht in derselben Ressourcengruppe befinden, sie müssen sich jedoch in derselben Region befinden.

Handbuch zur Problembehandlung

In diesem Leitfaden finden Sie Informationen zum Beheben von Fehlern während oder nach einer Standard-Agent-Bereitstellung, unabhängig davon, ob Sie das Azure-Portal, Bicep oder Terraform verwendet haben.

Bereitstellungsfehler

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

Lösung: Die Bereitstellung aller Verbindungen mit allen Bring-your-Own-Ressourcen (BYO) erfordert Verbindungen mit allen BYO-Ressourcen. Sie können keinen gesicherten Standard-Agent in Foundry erstellen, ohne dass alle drei Ressourcen bereitgestellt wurden.

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

Lösung: Sie verwenden keinen geeigneten IP-Bereich für Ihr delegiertes Agent-Subnetz. Stellen Sie sicher, dass Sie einen gültigen privaten IP-Adressraum verwenden. Gültige RFC1918 Bereiche umfassen 10.0.0.0/8, 172.16-31.0.0/12und 192.168.0.0/16. Weitere Details sind in den obigen Einschränkungen aufgeführt.

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

Lösung: Sie fehlen die richtige Ressourcenregistrierung. Stellen Sie sicher, dass die erforderlichen Ressourcen in Ihrem Mandanten registriert sind.

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." Oder "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

Lösung: Dies ist ein Catch-All-Fehler. Erstellen Sie eine Supportticketanfrage, um Ihr Setup zu untersuchen. Überprüfen Sie den Funktionshost auf den Fehler.

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

Solution: Dieser Fehler wird angezeigt, wenn Sie versuchen, das gesicherte Standardvorlagensetup in Azure zu löschen und nicht ordnungsgemäß alle Ressourcen zu löschen. Eine Lösung besteht darin, im Azure Portal zur Seite "Foundry"-Ressource zu navigieren und Gelöschte Ressourcen verwalten auszuwählen. Löschen Sie von dort aus die Ressource, mit der der Agent für dieses virtuelle Netzwerk verknüpft war. Die andere Option besteht darin, das deleteCaphost.sh Skript in der gesicherten Standardvorlage auszuführen.

"Timeout of 60000ms exceeded" error when loading the Agent pages in the Foundry project

Solution: Das Foundry-Projekt hat Probleme bei der Kommunikation mit Azure Cosmos DB zum Erstellen von Agents. Überprüfen Sie die Verbindung mit Azure Cosmos DB (Privater Endpunkt und DNS).

DNS-Auflösung des privaten Endpunkts schlägt fehl

Lösung: Wenn Ressourcen nicht über private Endpunkte erreichbar sind, überprüfen Sie, ob jede private DNS-Zone mit Ihrem virtuellen Netzwerk verknüpft ist. Bestätigen Sie, dass bedingte Weiterleitungen auf die AZURE DNS IP-Adresse des virtuellen Servers 168.63.129.16 verweisen. Führen Sie auf einer Maschine, die mit dem VNet verbunden ist, nslookup <resource-fqdn> aus und stellen Sie sicher, dass jeder Name in eine private IP-Adresse aufgelöst wird.

Nächste Schritte

Sie haben jetzt erfolgreich ein netzwerksicheres Konto und projekt konfiguriert. Verwenden Sie die Schnellstartanleitung , um Ihren ersten Agent zu erstellen.

Weitere Informationen zur Konfiguration und Optionen für die Netzwerkisolation finden Sie unter Konfigurieren der Netzwerkisolation.

Viele Unternehmensumgebungen erfordern, dass Foundry, die Containerregistrierung und abhängige Dienste wie Application Insights und Storage nur über ein privates Netzwerk erreichbar sind. In diesem Abschnitt wird erläutert, wie azd gehostete Agenten provisioniert und bereitgestellt werden, deren Abhängigkeiten sich hinter privaten Endpunkten in einem virtuellen Netzwerk (VNet) befinden.

Sie erreichen die VNet-Integration, indem Sie die generierten infra/ Bicep-Vorlagen anpassen und azd innerhalb des VNets (oder mit Zugriff darauf) ausführen.

Wenn Sie einen Programmierassistenten wie GitHub Copilot verwenden, kann das Microsoft Foundry Skill dabei helfen, den richtigen Pfad für private Netzwerke auszuwählen und die erforderlichen azd, Bicep- oder Terraform-Schritte umzusetzen.

Voraussetzungen

• Ein initialisiertes gehostetes Agentprojekt. Informationen zum Erstellen finden Sie unter Initialisieren eines gehosteten Agent-Projekts mit der Azure Developer CLI.
• Die installierten Azure Developer CLI Foundry-Erweiterungen.
• Ein virtuelles Netzwerk (neu oder vorhanden) und die Berechtigung zum Erstellen privater Endpunkte und privater DNS-Zonen.
• Vertrautheit mit dem generierten Bicep-Code. Siehe gehostete Agent-Infrastruktur mit der Azure Developer CLI.

Was VNet-Schutz für eine azd-Bereitstellung bedeutet

Ein gehostetes Agentprojekt stellt mehrere Azure Ressourcen zur Bereitstellung. Sie können den öffentlichen Netzwerkzugriff auf jeden einzelnen deaktivieren und einen privaten Endpunkt in Ihrem VNet platzieren.

Wenn der Agentenendpunkt selbst privat sein soll, ist das eine plattformseitige Funktion, die heute außerhalb des Funktionsumfangs dieser Erweiterung liegt.

Was die Erweiterung tut und was nicht?

Wählen Sie Ihre Topologie.

Die meisten VNet-geschützten Bereitstellungen fallen in eine dieser Formen. Wählen Sie eins aus, bevor Sie Bicep bearbeiten:

• Greenfield, alles in einem neuen VNet. Führen Sie azd ai agent initaus, und fügen Sie dann private Endpunktmodule zum Gerüst infra/hinzu. Sie stellen sowohl das VNet als auch die Ressourcen in einer Bicep-Ausführung bereit.
• Brownfield, mit einem vorhandenen VNet verbinden. Identisch mit dem Greenfield-Ansatz, aber Sie verweisen auf das vorhandene VNet über Parameter, anstatt eines zu erstellen. Dies ist nützlich, wenn ein anderes Team das Netzwerk besitzt.
• Alle vorhandenen Ressourcen wiederverwenden. Ein Plattformteam hat das Foundry-Konto, ACR und Application Insights auf privaten Endpunkten vorab bereitgestellt. Sie bringen nur die Agentdefinition ein und verweisen die Umgebungsvariablen auf die vorhandenen Ressourcen. main.bicep erstellt nur das, was fehlt.

Topologien 2 und 3 sind die am häufigsten in regulierten Unternehmen. Topologie 1 eignet sich für eigenständige Pilotprojekte.

Anpassen des generierten Bicep-Codes

Das von infra/ generierte Verzeichnis azd ai agent init ist standardmäßiger azd Bicep-Code. Er gehört Ihnen, und Änderungen bleiben über Bereitstellungen hinweg erhalten. Die Standardvorlagen erstellen öffentliche Ressourcen, sodass Sie sie ersetzen oder erweitern, um private Endpunkte hinzuzufügen.

Hinzufügen von VNet- und Subnetzparametern

Fügen Sie Parameter hinzu infra/main.bicep , und binden Sie sie in infra/main.parameters.json:

// infra/main.bicep (excerpt)

@description('Resource ID of the existing virtual network. If empty, a new VNet is created.')
param vnetResourceId string = ''

@description('Name of the subnet hosting private endpoints.')
param privateEndpointSubnetName string = 'snet-pe'

@description('Disable public network access on data-plane resources.')
param disablePublicNetworkAccess bool = true

// infra/main.parameters.json (excerpt)
{
  "vnetResourceId":              { "value": "${AZURE_VNET_RESOURCE_ID=}" },
  "privateEndpointSubnetName":   { "value": "${AZURE_PE_SUBNET_NAME=snet-pe}" },
  "disablePublicNetworkAccess":  { "value": "${DISABLE_PUBLIC_NETWORK=true}" }
}

Festlegen der Umgebungsvariablen vor azd provision:

azd env set AZURE_VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd env set AZURE_PE_SUBNET_NAME snet-pe
azd env set DISABLE_PUBLIC_NETWORK true

Sperren jeder Ressource

Legen Sie für jede Ressource, die von den Vorlagen erstellt wird, publicNetworkAccess: 'Disabled' fest, und fügen Sie ein Modul für private Endpunkte hinzu. Das folgende Muster ist illustrativ. Passen Sie die Ressourcentypen und DNS-Zonen an Ihre Umgebung an.

// infra/core/ai/account.bicep (excerpt)
resource aiAccount 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  // ...existing properties...
  properties: {
    // ...existing properties...
    publicNetworkAccess: disablePublicNetworkAccess ? 'Disabled' : 'Enabled'
    networkAcls: {
      defaultAction: disablePublicNetworkAccess ? 'Deny' : 'Allow'
    }
  }
}

Fügen Sie ein privates Endpunktmodul hinzu, das das Konto mit dem VNet verkabelt:

module aiAccountPrivateEndpoint '../network/private-endpoint.bicep' = if (disablePublicNetworkAccess) {
  name: 'pe-ai-account'
  params: {
    name: 'pe-${aiAccount.name}'
    location: location
    subnetId: '${vnetResourceId}/subnets/${privateEndpointSubnetName}'
    privateLinkServiceId: aiAccount.id
    groupId: 'account'
    privateDnsZoneId: privateDnsZones.cognitiveServices
  }
}

Wiederholen Sie dieses Muster für die Ressourcen, die Sie privat machen möchten:

• AI Services-Konto: Gruppen-ID account. DNS-Zonen enthalten privatelink.cognitiveservices.azure.com, privatelink.openai.azure.comund privatelink.services.ai.azure.com, abhängig von der Datenebene.
• Containerregistrierung: Gruppen-ID registry. DNS-Zone privatelink.azurecr.io. Fügt einen Datenendpunkt pro Region hinzu.
• Application Insights: über einen Azure Monitor Private Link-Bereich. DNS-Zonen umfassen privatelink.monitor.azure.com, , privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.comund privatelink.agentsvc.azure-automation.net.
• Speicherkonto: Gruppen-IDs blob, file, queue, und table nach Bedarf. DNS-Zonen pro Dienst, z. B privatelink.blob.core.windows.net. .

Das Repository azd-ai-starter-basic, aus dem die Agent-Erweiterung das Gerüst erstellt, ist eine nützliche Referenz dafür, was standardmäßig erstellt wird. Erweitern Sie diese Module, anstatt sie zu ersetzen.

Ressourcen bereitstellen

azd provision

Nach der Bereitstellung ist jede Abhängigkeit in Ihrer Liste nur über ihren privaten Endpunkt erreichbar. Die öffentliche DNS-Auflösung gibt weiterhin den öffentlichen Hostnamen zurück, aber die privaten DNS-Zonen überschreiben sie innerhalb des VNet.

Führen Sie azd up innerhalb des VNet aus

Nachdem Sie den Zugriff auf das öffentliche Netzwerk deaktiviert haben, können Sie nicht mehr ausführen azd up oder azd deploy von einer öffentlichen Internetarbeitsstation aus. Die ARM-Steuerungsebene ist erreichbar, aber Datenebenenaufrufe an Foundry und ACR-Pushvorgänge schlagen mit 403 oder Fehlern aufgrund abgelehnter Verbindungen fehl. Verwenden Sie eines der folgenden Muster.

Selbstgehosteter GitHub Actions Runner

Stellen Sie eine Runner-VM oder einen in AKS gehosteten Runner in einem Subnetz desselben VNet bereit. Verweisen Sie Ihren Workflow mit runs-on: [self-hosted, agent-vnet] auf diesen Runner. Jeder azd ai Schritt löst dann die privaten DNS-Namen korrekt auf und wird über den privaten Endpunkt geleitet.

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

Azure DevOps selbstgehosteter Agent

Verwenden Sie dasselbe Muster für Azure DevOps. Installieren Sie den Agent in einem VNet-Subnetz, und richten Sie ihn mit der pool: name: agent-vnet Direktive aus. Die azd CLI und die Foundry-Erweiterung werden unverändert ausgeführt.

Bastion oder Jump-Host für einmalige Ausführungen

Für Ad-hoc-Ausführungen, z. B. für eine manuelle Reaktion auf Vorfälle oder eine außerplanmäßige Bereitstellung, verbinden Sie sich über Azure Bastion mit einem Jumphost innerhalb des VNet, installieren Sie dort azd und die Erweiterungen, und führen Sie azd von diesem Host aus. Halten Sie den Jump-Host minimal. Die langfristige Antwort ist CI.

Lokales Entwickeln für einen privaten Foundry-Endpunkt

Die lokale Entwicklung (azd ai agent run und azd ai agent invoke) kommuniziert über Loopback mit Ihrem lokalen Agent-Prozess und während invoke mit der Foundry-Datenebene für Tools, Modelle und Sitzungen. Wenn der Foundry-Endpunkt nur über ein VNet erreichbar ist, muss Ihr Entwicklungscomputer Netzwerkzugriff darauf haben. Zu den Optionen gehören:

• Ein Point-to-Site- oder Always-On-VPN, das Sie in den DNS-Bereich des VNet bringt.
• Azure Bastion für eine Entwicklungs-VM innerhalb des VNets. Führen Sie azd ai agent run auf dieser VM aus und leiten Sie die Ports 8088 und 8087 für den Inspektor durch den Bastion-Tunnel weiter.
• Eine Workstation im Unternehmensnetzwerk mit einer ExpressRoute- oder Hub-VNet-Verbindung zu dem Spoke, auf dem die privaten Endpunkte gehostet werden.

Die FOUNDRY_PROJECT_ENDPOINT Auflösung ändert sich nicht. Der Wert stammt weiterhin aus der aktiven azd-Umgebung oder der globalen Konfiguration. Wichtig ist, dass DNS den Endpunkt zur privaten statt zur öffentlichen IP-Adresse auflöst.

Mit einem privaten ACR kombinieren

Wenn sich sowohl der Foundry-Endpunkt als auch der ACR auf privaten Endpunkten im gleichen VNet befinden, gehen Sie wie folgt vor:

1. Führen Sie azd up innerhalb des VNet aus.
2. Legen Sie AZURE_CONTAINER_REGISTRY_ENDPOINT und AZURE_CONTAINER_REGISTRY_RESOURCE_ID so fest, dass sie auf die vorhandene private ACR verweisen, damit Bicep das Erstellen einer neuen öffentlichen ACR überspringt.
3. Stellen Sie sicher, dass die Agent-Identität über die Rolle AcrPull für die Registrierung verfügt. azd deploy behandelt dies automatisch, nachdem die Agentidentität erstellt wurde.

Ausführliche registrierungsspezifische Informationen finden Sie unter Bereitstellen eines gehosteten Agents mit einer privaten Azure Container Registry.

Diagnostizieren von Netzwerkproblemen

• azd ai agent doctor führt Prüfungen der Netzwerkerreichbarkeit gegen die Foundry-Datenebene aus. Innerhalb des VNets sind die Überprüfungen erfolgreich. Von außen scheitern sie deutlich. Verwenden Sie --local-only, um Remoteprüfungen zu überspringen, wenn Sie Probleme debuggen, die nicht mit dem Netzwerk zusammenhängen.
• azd ai agent invoke --output raw "ping" gibt die vollständige HTTP-Antwort aus. Ein Fehler „Verbindung abgelehnt“ oder „Host nicht gefunden“ weist hier auf ein DNS- oder Routingproblem hin, nicht auf ein Authentifizierungsproblem.
• Bei ACR-Pushfehlern gibt die CLI einen einfügebereiten az role assignment create-Befehl aus, wenn die Ursache eine fehlende Rolle und kein Netzwerkproblem ist.

Bekannte Einschränkungen

• Kein erstklassiges CLI-Flag. Die gesamte VNet-Verbindung besteht aus manueller Bicep-Anpassung sowie operativer Disziplin für Runner-Platzierung, DNS und RBAC.
• Der Agentendpunkt bleibt in dieser Vorschau öffentlich. Die Mandantenisolation auf einem öffentlichen Endpunkt erfolgt durch Isolieren von Sitzungen pro Benutzer, nicht durch Netzwerkdatenschutz.
• Regionseinschränkungen gelten. Gehostete Agents sind in einer festen Gruppe von Regionen verfügbar. VNet, ACR und Foundry-Konto sollten sich alle in einer dieser Regionen befinden oder mit einer dieser Regionen per Peering verbunden sein. Informationen zur Anforderung derselben Region zwischen der Foundry-Ressource und dem virtuellen Netzwerk finden Sie unter "Regionale Unterstützung für private Netzwerke". Führen Sie azd ai agent doctor zur Überprüfung aus.
• DNS ist der häufigste Fehlermodus. Bestätigen Sie die private DNS-Auflösung End-to-End, z. B. mit nslookup <endpoint> vom Runner oder der Entwicklungs-VM, bevor Sie davon ausgehen, dass das Problem bei RBAC liegt.

Verwandte Inhalte

• Bereitstellen eines gehosteten Agents mit einem privaten Azure Container Registry
• Gehostete Agentsitzungen pro Benutzer isolieren
• Gehostete Agent-Infrastruktur mit der Azure Developer CLI
• Diagnostizieren eines Projekts mit Agent-Arzt