Configurare la rete privata per il servizio Foundry Agent

Il servizio Foundry Agent offre un'installazione standard con ambiente di rete privato . Questa configurazione crea un ambiente di rete isolato che consente l'accesso sicuro ai dati mantenendo al contempo il controllo completo sull'infrastruttura di rete.

Per impostazione predefinita, l'installazione standard con rete privata garantisce:

• Nessuna uscita pubblica: l'infrastruttura fornisce già autenticazione e sicurezza appropriate per agenti e strumenti, senza necessità di aggirare servizi autorizzati.
• Integrazione della subnet: viene fornita una subnet delegata dalla rete virtuale. La piattaforma connette il calcolo dell'agente a questa subnet, abilitando la comunicazione locale con le risorse di Azure all'interno della stessa rete virtuale.
• Accesso alle risorse private: se le risorse sono contrassegnate come private e nondiscoverable da Internet, la rete della piattaforma può comunque accedervi quando sono presenti le credenziali e l'autorizzazione necessarie.

Se non si dispone di una rete virtuale esistente, la Configurazione standard con il processo di rete privata può provisionare automaticamente l'infrastruttura di rete necessaria.

Prerequisiti

• Una sottoscrizione di Azure: crearne una gratuitamente.

• Verificare che la persona che crea l'account e il progetto abbia il ruolo proprietario dell'account Foundry nell'ambito della sottoscrizione.

  Importante

  I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

• L'utente che crea questa configurazione deve avere anche le autorizzazioni per assegnare ruoli alle risorse necessarie (Azure Cosmos DB, Ricerca di intelligenza artificiale di Azure, Archiviazione di Azure).

  • Il ruolo predefinito necessario è Amministratore degli accessi in base al ruolo.
  • In alternativa, avere il ruolo Proprietario a livello di sottoscrizione soddisfa anche questo requisito.
  • L'autorizzazione della chiave necessaria è: Microsoft.Authorization/roleAssignments/write

• Python 3.9 o versione successiva

• Una volta configurato l'ambiente dell'agente, assicurarsi che a ogni membro del team che desidera usare Agent Playground o l'SDK per creare o modificare agenti sia stato assegnato il ruolo predefinito Foundry UserRBAC per il progetto.

  • Il set minimo di autorizzazioni necessarie è: agents/*/read, agents/*/action, agents/*/delete

• Registrare i fornitori. I provider seguenti devono essere registrati:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • Per usare lo strumento Ricerca Bing: 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'
  

Configurare un ambiente protetto dalla rete

È possibile creare questa configurazione nel portale di Azure o distribuirla usando Bicep o Terraform.

A livello generale, la distribuzione prevede questi passaggi:

1. Scegli l'area di Azure di destinazione per le risorse Foundry.
2. Decidere se utilizzare la propria rete virtuale (VNet) e subnet, o optare per una rete auto-provisionata.
3. Se si usa la propria rete virtuale, raccogliere gli ID risorsa della rete virtuale e della subnet.
4. Creare la configurazione nel portale di Azure o distribuirla usando Bicep o Terraform.
5. Verificare la distribuzione (vedere Verificare la distribuzione).

La configurazione fornisce le seguenti risorse (a meno che non si utilizzino i propri):

• Un account Foundry e un progetto Foundry.
• Distribuzione del modello gpt-4o.
• Archiviazione di Azure, Azure Cosmos DB e Azure AI Search per l'archiviazione di file, thread e dati vettoriali.
• Queste risorse sono connesse al progetto.
• Le chiavi di crittografia gestite da Microsoft per l'account di archiviazione e l'account cognitivo (Foundry) vengono usate per impostazione predefinita.

Selezionare il metodo di distribuzione preferito usando le schede seguenti:

Verificare la distribuzione

Al termine della distribuzione, verificare che tutte le risorse siano configurate correttamente:

1. Confermare la delega della subnet: nel portale di Azure, andare alla rete virtuale >Subnet e verificare che la subnet dell'agente mostri la delega a Microsoft.App/environments.
2. Controllare l'accesso alla rete pubblica: aprire ogni risorsa (Foundry, Ricerca intelligenza artificiale di Azure, Archiviazione di Azure, Azure Cosmos DB) e verificare che l'accesso alla rete pubblica sia impostato su Disabilitato.
3. Convalidare la risoluzione DNS dell'endpoint privato: da un computer connesso alla rete virtuale, eseguire nslookup su ogni endpoint elencato nel riepilogo delle configurazioni della zona DNS.
4. Connettività dell'agente di test: accedere al progetto Foundry dall'interno della rete virtuale (vedere Accedere agli agenti protetti) e verificare di poter creare ed eseguire un agente.
5. Configurare le assegnazioni di ruolo: eseguire i comandi seguenti per assegnare i ruoli necessari. Il primo assegna il ruolo Managed Identity Operator all'identità gestita assegnata dall'utente e il secondo assegna il ruolo Network Contributor sulla rete virtuale remota per l'accesso tra tenant.

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>"

Limitazioni

• Limitazione dell'indirizzo IP della rete virtuale e della subnet:
  • La subnet delegata del servizio agente deve avere intervalli IP entro intervalli IPv4 privati validi RFC1918: 10.0.0.0/8, 172.16-31.0.0/12o 192.168.0.0/16 noti anche come intervalli IP della classe privata A, classe B e classe C.
  • Gli intervalli di indirizzi IP privati di Classe A (10.0.0.0/8) sono supportati in tutte le aree geografiche in cui il servizio Agent è disponibile. Per l'elenco corrente, vedere Aree supportate.
  • Gli intervalli di IP pubblici come 44.x.x.x e gli intervalli di indirizzi CGNAT 100.64.0.0–100.127.255.255 non sono supportati per la subnet delegata del servizio agente.
  • Assicurarsi che gli spazi di indirizzi della rete virtuale non si sovrappongano ad alcuna rete esistente nell'ambiente Azure o a intervalli IP riservati come i seguenti: 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/17100.100.192.0/19, , . 100.100.224.0/19100.64.0.0/11 Il requisito include tutti gli spazi di indirizzamento presenti nella propria VNET, se sono più di uno, e nelle VNET in peering.
• Esclusività della subnet dell'agente: la subnet dell'agente non può essere condivisa da più risorse Foundry. Ogni risorsa di Foundry deve utilizzare una sottorete agente dedicata.
• Dimensioni della subnet dell'agente: le dimensioni consigliate della subnet dell'agente delegato sono /24 (256 indirizzi) a causa della delega della subnet a Microsoft.App/environments. Per altre informazioni sul dimensionamento delle subnet, vedere Configurazione delle reti virtuali per le app contenitore di Azure.
• Elenco degli elementi consentiti del firewall di uscita della subnet dell'agente: se si integra Firewall di Azure con l'agente standard protetto tramite rete privata, aggiungere all'elenco degli elementi consentiti i nomi di dominio completi (FQDN) elencati nella sezione Identità gestita dell'articolo Integrare con Firewall di Azure oppure aggiungere il tag di servizio AzureActiveDirectory. Se si applicano gruppi di sicurezza di rete (NSG) alla subnet dell'agente delegato o alle subnet correlate, configurare le regole di autorizzazione in uscita corrispondenti per le dipendenze necessarie, incluso il tag del servizio AzureActiveDirectory per l'autenticazione Microsoft Entra ID. Se le regole del firewall o dell’NSG bloccano le dipendenze necessarie, il provisioning degli agenti e le operazioni in fase di esecuzione possono avere esito negativo.
  • Verificare che non venga eseguita alcuna ispezione TLS nel firewall che potrebbe aggiungere un certificato autofirmato. In caso di malfunzionamenti, controllare se il traffico raggiunge il firewall e quale traffico viene filtrato.
  • Per le distribuzioni dell'agente di codice sorgente, consentire anche gli endpoint di distribuzione elencati in Requisiti del firewall per le reti virtuali private.
• La risorsa Foundry deve essere distribuita nella stessa area della rete virtuale . Altre risorse di Azure, ad esempio Azure Cosmos DB, Ricerca di intelligenza artificiale di Azure e Archiviazione di Azure, possono essere distribuite in aree diverse. Prendere in considerazione le implicazioni sui costi delle distribuzioni tra aree.
• Disponibilità dell'area:
  • Per le aree supportate per le distribuzioni di modelli, vedere Supporto dell'area del modello OpenAI di Azure.
• Archiviazione BLOB di Azure: l'uso dei file di Archiviazione BLOB di Azure con lo strumento Ricerca file non è supportato.
• Limitazioni dei file dell'interprete del codice: in una configurazione BYO (Private Network), l'interprete del codice funziona solo in scenari che non comportano caricamenti o download di file. Lo strumento non può recuperare i file dall'account di archiviazione in questa configurazione. Se è necessario usare i file con l'interprete del codice, è necessario usare l'SDK per creare un contenitore in modo esplicito con i file necessari e quindi passare container_id a Interprete di codice. Questa soluzione alternativa è disponibile solo tramite l'SDK; L'interfaccia utente del portale foundry non la supporta.
• Connessione con Bing Search: sono supportate solo le seguenti regioni: Europa Occidentale, Canada Orientale, Svizzera Settentrionale, Spagna Centrale, UAE Nord, Corea Centrale, Polonia Centrale, Asia Sud-orientale, Stati Uniti Occidentali, Stati Uniti Occidentali 2, Stati Uniti Occidentali 3, Stati Uniti Orientali, Stati Uniti Orientali 2, Stati Uniti Centrali, India Meridionale, Giappone Orientale, Regno Unito Meridionale, Francia Centrale, Norvegia Est, Australia Orientale, Canada Centrale, Svezia Centrale, Sud Africa Settentrionale, Italia Settentrionale, Brasile Meridionale
• Eliminare l'injection di rete: se si desidera eliminare la risorsa Foundry e l'agente standard con la configurazione di rete protetta, eliminare prima la risorsa Foundry e la rete virtuale come ultima cosa. Prima di eliminare la rete virtuale, eliminare e rimuovere la risorsa Foundry.
• Inserimento della rete virtuale dell'agente ospitato: per gli agenti ospitati, la configurazione della rete virtuale (inserimento di rete) deve essere inclusa quando si crea per la prima volta l'account Foundry. Non è supportata l'aggiunta dell'iniezione di rete a un account Foundry esistente dopo la creazione dell'account per gli agenti ospitati.
• Registro contenitori per agenti ospitati in una rete privata: Per gli agenti ospitati, il supporto per un Registro Azure Container (ACR) in una rete privata (endpoint privato con accesso alla rete pubblica disabilitato) dipende dal momento in cui è stato creato il progetto Foundry. I progetti creati dopo il 25 giugno 2026 supportano un'istanza privata di Azure Container Registry. I progetti creati prima di tale data richiedono che l'ACR sia raggiungibile tramite il relativo endpoint pubblico, in modo che la piattaforma possa recuperare l'immagine. I progetti esistenti non sono interessati e continuano a usare l'accesso alla rete pubblica.

Diagramma dell'architettura

Esaminare le risorse di rete fornite

Il provisioning delle risorse seguenti viene eseguito automaticamente quando si usa la configurazione standard con rete privata, a meno che non si adottino le proprie configurazioni:

Infrastruttura di rete

• Una rete virtuale (192.168.0.0/16)
• Subnet agente (192.168.0.0/24): ospita il client dell'agente
• Subnet endpoint privato (192.168.1.0/24): ospita endpoint privati

Funzionalità di rete virtuale

La rete virtuale controlla quali endpoint possono effettuare chiamate API alle risorse. Il servizio di Azure rifiuta automaticamente le chiamate API dai dispositivi all'esterno della rete definita.

Regole di rete

Tutti gli account e i relativi progetti sono protetti per impostazione predefinita con il flag Accesso alla rete pubblica Disabilitato , che richiede una configurazione esplicita per consentire l'accesso tramite endpoint privati. Queste regole si applicano a tutti i protocolli, inclusi REST e WebSocket.

Riepilogo delle configurazioni della zona DNS

Per creare un server d'inoltro condizionale nel server DNS nel server virtuale DNS di Azure, usare l'elenco delle zone indicate nella tabella precedente. L'indirizzo IP del server virtuale DNS di Azure è 168.63.129.16.

Accedere agli agenti protetti

Al termine della distribuzione, è possibile accedere al progetto Foundry dietro una rete virtuale usando uno dei metodi seguenti:

• Gateway VPN di Azure: connette le reti locali alla rete virtuale tramite una connessione privata. La connessione viene effettuata tramite la rete Internet pubblica. Esistono due tipi di gateway VPN che è possibile usare:
  • Da punto a sito: ogni computer client usa un client VPN per connettersi alla rete virtuale.
  • Da sito a sito: un dispositivo VPN connette la rete virtuale alla rete locale.
• ExpressRoute: connette le reti locali nel cloud tramite una connessione privata. La connessione viene effettuata tramite un provider di connettività.
• Azure Bastion: in questo scenario si crea una macchina virtuale di Azure (talvolta denominata jump box) all'interno della rete virtuale. Connettersi quindi alla macchina virtuale usando Azure Bastion. Bastion consente di connettersi alla macchina virtuale usando una sessione RDP o SSH dal Web browser locale. Usare quindi il jump box come ambiente di sviluppo. Poiché si trova all'interno della rete virtuale, può accedere direttamente all'area di lavoro.

Domande frequenti

Quale intervallo di indirizzi è necessario usare per la rete virtuale complessiva?

L'intervallo di indirizzi della rete virtuale può essere qualsiasi intervallo IP privato che lascia spazio di indirizzi sufficiente sia per la subnet dell'agente delegato che per la subnet dell'endpoint privato.

È possibile usare reti virtuali con peering o posizionare risorse in reti virtuali diverse?

Le reti virtuali con peering sono supportate, ma i costi di trasferimento dei dati possono aumentare.

Più risorse Foundry possono riutilizzare la stessa rete virtuale e la stessa subnet?

Sì, la stessa rete virtuale, ma non la stessa subnet. Più risorse foundry possono riutilizzare la stessa rete virtuale. Tuttavia, ogni risorsa Foundry richiede una subnet dedicata per il runtime dell'agente. La subnet dell'agente non può essere condivisa tra più risorse Foundry.

La rete virtuale deve trovarsi nello stesso gruppo di risorse della risorsa Foundry?

No. La rete virtuale e la risorsa Foundry non devono trovarsi nello stesso gruppo di risorse, ma devono trovarsi nella stessa area.

Guida alla risoluzione dei problemi

Fare riferimento a questa guida per risolvere gli errori durante o dopo una distribuzione dell'agente Standard, indipendentemente dal fatto che sia stato usato il portale di Azure, Bicep o Terraform.

Errori di distribuzione

"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."

Soluzione: fornire tutte le connessioni a tutte le risorse BYO (Bring Your Own), richiede connessioni a tutte le risorse BYO. Non è possibile creare un agente standard protetto in Foundry senza tutte e tre le risorse fornite.

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

Soluzione: non si usa un intervallo IP appropriato per la subnet dell'agente delegato. Verificare di usare uno spazio indirizzi IP privato valido. Gli intervalli di RFC1918 validi includono 10.0.0.0/8, 172.16-31.0.0/12e 192.168.0.0/16. Altri dettagli sono riportati nelle limitazioni precedenti.

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

Soluzione: manca la registrazione corretta delle risorse. Assicurati che le risorse necessarie siano registrate nel tuo tenant.

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

Soluzione: Questo è un errore onnicomprensivo. Creare una richiesta di ticket di supporto per analizzare la configurazione. Controllare l'host della funzionalità per l'errore.

"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."

Soluzione: questo errore viene visualizzato quando si tenta di eliminare la configurazione del modello standard protetto in Azure e non è stata eliminata correttamente tutte le risorse. Una soluzione consiste nel passare alla pagina delle risorse Foundry nel portale di Azure e selezionare Gestisci risorse eliminate. Da qui eliminare la risorsa a cui è stato associato l'agente per questa rete virtuale. L'altra opzione consiste nell'eseguire lo deleteCaphost.sh script nel modello standard protetto.

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

Soluzione: il progetto Foundry presenta problemi di comunicazione con Azure Cosmos DB per la creazione di agenti. Verificare la connettività ad Azure Cosmos DB (endpoint privato e DNS).

La risoluzione DNS dell'endpoint privato ha esito negativo

Soluzione: se le risorse non sono raggiungibili tramite endpoint privati, verificare che ogni zona DNS privata sia collegata alla rete virtuale. Verificare che i server d'inoltro condizionale puntino all'indirizzo 168.63.129.16IP del server virtuale DNS di Azure. Da un computer connesso alla rete virtuale, eseguire nslookup <resource-fqdn> e verificare che ogni nome si risolva in un indirizzo IP privato.

Passaggi successivi

È stato configurato correttamente un account e un progetto protetti dalla rete. Usare la guida introduttiva per creare il primo agente.

Per altre informazioni sulla configurazione e le opzioni di isolamento della rete, vedere Configurare l'isolamento di rete.

Molti ambienti aziendali richiedono che Foundry, il registro contenitori e i servizi dipendenti, ad esempio Application Insights e Archiviazione, siano raggiungibili solo da una rete privata. Questa sezione illustra come effettuare il provisioning e la distribuzione di agenti ospitati azd le cui dipendenze si trovano dietro gli endpoint privati in una rete virtuale.

Si ottiene l'integrazione rete virtuale personalizzando i modelli Bicep infra/ sottoposti a scaffolding ed eseguendo azd dall'interno della rete virtuale (o da un ambiente con accesso alla rete virtuale).

Se si usa un agente di codifica come GitHub Copilot, la competenza Microsoft Foundry può aiutare a scegliere il percorso di rete privata corretto e applicare i passaggi necessariazd, Bicep o Terraform.

Prerequisiti

• Progetto di agente ospitato inizializzato. Per crearne uno, vedere Inizializzare un progetto agente ospitato con l'interfaccia della riga di comando per sviluppatori di Azure.
• Le estensioni Foundry per Azure Developer CLI sono installate.
• Una rete virtuale (nuova o esistente) e l'autorizzazione per creare endpoint privati e zone DNS private.
• Familiarità con il Bicep sottoposto a scaffolding. Vedi Infrastruttura degli agenti ospitati con Azure Developer CLI.

Che cosa significa la protezione della rete virtuale per una distribuzione azd

Un progetto agente ospitato effettua il provisioning di diverse risorse Azure. È possibile disabilitare l'accesso alla rete pubblica in ognuno di essi e inserire un endpoint privato nella rete virtuale.

Se hai bisogno che l'endpoint dell'agente sia privato di per sé, si tratta di una funzionalità lato piattaforma che attualmente esula dall'ambito di questa estensione.

Cosa fa e non fa l'estensione

Scegli la topologia

La maggior parte delle distribuzioni protette dalla rete virtuale rientra in una di queste forme. Selezionarne una prima di modificare Bicep:

• Greenfield, tutto all'interno di una nuova rete virtuale. Eseguire azd ai agent init, quindi aggiungere i moduli di endpoint privato alla directory infra/ sottoposta a scaffolding. Si esegue il provisioning sia della rete virtuale sia delle risorse con un'unica esecuzione Bicep.
• Brownfield, collegarsi a una rete virtuale esistente. Uguale all'approccio greenfield, ma si fa riferimento alla rete virtuale esistente tramite parametri anziché crearne uno. Ciò è utile quando un team diverso è proprietario della rete.
• Riutilizzare tutte le risorse esistenti. Il team della piattaforma ha preconfigurato l'account Foundry, ACR e Application Insights su endpoint privati. Si porta solo la definizione dell'agente e si puntano le variabili di ambiente alle risorse esistenti. main.bicep crea solo ciò che manca.

Le topologie 2 e 3 sono le più comuni nelle aziende regolamentate. La topologia 1 si adatta ai progetti pilota autonomi.

Personalizzare il Bicep sottoposto a scaffolding

La directory infra/ generata da azd ai agent init è una directory Bicep azd standard. Ne hai il controllo e le modifiche persistono tra una distribuzione e l'altra. I modelli predefiniti creano risorse pubbliche, in modo da sostituirle o aumentarle per aggiungere endpoint privati.

Aggiungere parametri di rete virtuale e subnet

Aggiungere parametri a infra/main.bicep e associarli 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}" }
}

Impostare le variabili di ambiente prima di 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

Bloccare ogni risorsa

Per ogni risorsa creata dai modelli, impostare publicNetworkAccess: 'Disabled' e aggiungere un modulo endpoint privato. Il modello seguente è illustrativo. Adattare i tipi di risorse e le zone DNS all'ambiente.

// 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'
    }
  }
}

Aggiungere un modulo endpoint privato che collega l'account alla rete virtuale:

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

Ripetere questo modello per le risorse da rendere private:

• Account dei servizi di intelligenza artificiale: ID gruppo account. Le zone DNS includono privatelink.cognitiveservices.azure.com, privatelink.openai.azure.come privatelink.services.ai.azure.com, a seconda del piano dati.
• Registro dei contenitori: ID gruppo registry. Zona DNS privatelink.azurecr.io. Aggiunge un endpoint di dati per regione.
• Application Insights: tramite un ambito collegamento privato di Monitoraggio di Azure. Le zone DNS includono privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.come privatelink.agentsvc.azure-automation.net.
• Account di archiviazione: ID gruppo blob, file, queue e table secondo necessità. Zone DNS per servizio, ad esempio privatelink.blob.core.windows.net.

Il repository azd-ai-starter-basic, che l’estensione agente sottopone a scaffolding, è un utile riferimento per capire cosa viene creato per impostazione predefinita. Aumentare tali moduli anziché sostituirli.

Effettuare il provisioning delle risorse

azd provision

Dopo il provisioning, ogni dipendenza presente nell'elenco è raggiungibile solo tramite il proprio endpoint privato. La risoluzione DNS pubblica restituisce comunque il nome host pubblico, ma le zone DNS private ne eseguono l'override all'interno della rete virtuale.

Eseguire azd up dall'interno della rete virtuale

Dopo aver disabilitato l'accesso alla rete pubblica, non è possibile eseguire azd up o azd deploy da una workstation Internet pubblica. Il piano di controllo ARM è raggiungibile, ma le chiamate al piano dati per il push di Foundry e Registro Azure Container non riescono con 403 o errori di connessione rifiutata. Usare uno dei modelli seguenti.

Strumento di esecuzione di GitHub Actions self-hosted

Effettuare il provisioning di una VM runner, o di un runner ospitato in AKS, in una subnet della stessa VNet. Indirizzare il flusso di lavoro allo strumento di esecuzione con runs-on: [self-hosted, agent-vnet]. Ogni azd ai passaggio risolve quindi correttamente i nomi DNS privati ed esegue il push attraverso l'endpoint privato.

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

Agente self-hosted di Azure DevOps

Usare lo stesso modello per Azure DevOps. Installare l'agente in una subnet di VNet e indirizzarlo con la direttiva pool: name: agent-vnet. La CLI azd e l'estensione Foundry funzionano senza modifiche.

Bastion oppure jump host per esecuzioni una tantum

Per esecuzioni ad hoc, ad esempio una risposta manuale agli incidenti o una distribuzione fuori ciclo, connettersi tramite Azure Bastion a un jump host all'interno della VNet, installare azd e le estensioni lì, quindi eseguire azd da tale host. Ridurre al minimo il jump host. La risposta a lungo termine è CI.

Sviluppo locale con un endpoint Foundry privato

Lo sviluppo locale (azd ai agent run e azd ai agent invoke) comunica con il processo dell'agente locale attraverso il loopback e con il piano dati di Foundry per strumenti, modelli e sessioni durante invoke. Quando l'endpoint di Foundry è accessibile solo tramite VNet, deve esserci connettività di rete dalla macchina di sviluppo. Le opzioni includono:

• Una VPN da punto a sito o sempre attiva che colloca il client nell'ambito DNS della VNet.
• Azure Bastion per una macchina virtuale di sviluppo all'interno della rete virtuale. Eseguire azd ai agent run sulla VM e le porte di inoltro 8088 e 8087 per il controllo, tramite il tunnel Bastion.
• Una postazione di lavoro nella rete aziendale con un percorso ExpressRoute o hub-VNet verso lo spoke che ospita gli endpoint privati.

La FOUNDRY_PROJECT_ENDPOINT risoluzione non cambia. Il valore proviene comunque dall'ambiente attivo azd o dalla configurazione globale. Ciò che conta è che DNS risolve l'endpoint nell'IP privato anziché in quello pubblico.

Combinare con un Registro Azure Container privato

Se sia l'endpoint di Foundry sia l'ACR usano endpoint privati nella stessa VNet, procedere come segue:

1. Eseguire azd up dall'interno della rete virtuale.
2. Imposta AZURE_CONTAINER_REGISTRY_ENDPOINT e AZURE_CONTAINER_REGISTRY_RESOURCE_ID in modo che puntino all'ACR privato esistente, così che Bicep salti la creazione di un nuovo ACR pubblico.
3. Assicurarsi che l'identità dell'agente abbia il ruolo AcrPull nel registro. azd deploy gestisce automaticamente questa operazione dopo la creazione dell'identità dell'agente.

Per informazioni dettagliate specifiche del Registro di sistema, vedere Distribuire un agente ospitato con un Registro Azure Container privato.

Diagnosticare i problemi di rete

• azd ai agent doctor esegue controlli di raggiungibilità di rete sul piano dati Foundry. Dall'interno della VNet, i controlli hanno esito positivo. Dall'esterno, falliscono chiaramente. Usare --local-only per ignorare i controlli remoti quando si esegue il debug di problemi non di rete.
• azd ai agent invoke --output raw "ping" esegue il dump della risposta HTTP completa. Un errore di connessione rifiutata o di host inesistente qui indica un problema di DNS o di instradamento, non un problema di autenticazione.
• Per gli errori di push del Registro Azure Container, l'interfaccia della riga di comando genera un comando pronto da incollare az role assignment create quando la causa è l'assenza di un ruolo e non un problema di rete.

Limitazioni note

• Nessun flag di prima classe dell'interfaccia della riga di comando. Tutta la configurazione della rete virtuale richiede la personalizzazione manuale di Bicep, oltre alla disciplina operativa per il posizionamento dello strumento di esecuzione, il DNS e il controllo degli accessi in base al ruolo (RBAC).
• L'endpoint dell'agente rimane pubblico in questa anteprima. L'isolamento del tenant in un endpoint pubblico viene eseguito isolando le sessioni per utente, non la privacy della rete.
• Si applicano vincoli di area. Gli agenti ospitati sono disponibili in un set fisso di aree. La rete virtuale, il Registro Azure Container e l'account Foundry devono trovarsi tutti in una di queste aree oppure essere in peering con una di esse. Per il requisito della stessa area tra la risorsa Foundry e la relativa rete virtuale, vedere Supporto a livello di area per la rete privata. Eseguire azd ai agent doctor per convalidare.
• DNS è la modalità di errore più comune. Verificare il completamento della risoluzione del DNS privato, ad esempio con nslookup <endpoint> dallo strumento di esecuzione o dalla macchina virtuale di sviluppo, prima di supporre che il problema sia il controllo degli accessi in base al ruolo.

Contenuti correlati

• Distribuire un agente ospitato con un Registro Azure Container privato
• Isolare le sessioni dell'agente ospitato per utente
• Infrastruttura di agenti ospitati con Azure Developer CLI
• Diagnosticare un progetto con Agent Doctor