Infrastruttura di agenti ospitati con Azure Developer CLI

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

L'interfaccia della riga di comando Azure Developer (azd) può generare un'infrastruttura Bicep o Terraform dai servizi dichiarati in azure.yaml. Scegli Terraform con azd ai agent init --infra=terraform, o Bicep con --infra=bicep. L'esecuzione del comando azd provision applica l'infrastruttura selezionata.

Il provisioning dell'infrastruttura e la distribuzione dell'agente sono processi distinti. Terraform o Bicep gestisce le risorse di supporto di Azure; azd deploy crea la versione del piano dati per l'agente ospitato. Per gestire l'agente stesso con Terraform invece di azd, vedere Distribuire un agente ospitato con Terraform.

Di cosa viene effettuato il provisioning

Per impostazione predefinita, azd ai agent init non crea file di infrastruttura come codice. Usare --infra o --infra=bicep per aggiungere l'infrastruttura Bicep. Usare --infra=terraform per aggiungere l'infrastruttura Terraform e impostare infra.provider: terraform.

Quando si aggiunge l'infrastruttura Bicep, i modelli si basano sul repository azd-ai-starter-basic e creano le seguenti risorse di Azure:

Resource	Purpose
Gruppo di risorse	Organizza tutte le risorse. rg-<agent-name> denominato.
Account dei servizi di intelligenza artificiale	L'account Microsoft Foundry.
Progetto Fonderia	Ospita le funzionalità dell'agente e dell'intelligenza artificiale.
Implementazioni di modelli	I modelli usati dall'agente, ad esempio gpt-4.1-mini.
Registro dei container di Azure	Archivia le immagini del container dell'agente.
Application Insights	Monitoraggio e telemetria delle prestazioni dell'agente.
Area di lavoro di Log Analytics	Raccolta di log centralizzata.
Identità gestita	L'identità assegnata dal sistema del progetto che autentica il progetto di identità dell'agente per Microsoft Entra ID e contiene le assegnazioni di ruolo della piattaforma.

I modelli creano più risorse in modo condizionale, in base ai servizi e alle dipendenze dichiarati in azure.yaml:

• Impostazioni delle funzionalità dell'agente: dichiarare le risorse Azure che contengono lo stato dell'agente, i dati vettoriali e i file. Impostarli quando sono necessari agenti per usare lo spazio di archiviazione di cui si è proprietari.
• Grounding con Bing o Grounding con Ricerca personalizzata Bing: per lo strumento di ricerca Web.
• Azure AI Search: per il grounding della ricerca.
• Archiviazione di Azure - per le operazioni di file.

Struttura del progetto

Per Bicep, un progetto generato ha la struttura seguente:

infra/
|-- main.bicep                 # Main deployment template (subscription-scoped)
|-- main.parameters.json       # Parameter bindings to azd environment variables
|-- abbreviations.json         # Naming convention abbreviations
\-- core/
    |-- ai/                    # Foundry account, project, and connections
    |-- host/                  # Container registry
    |-- monitor/               # Application Insights and Log Analytics
    |-- search/                # Azure AI Search (conditional)
    \-- storage/               # Azure Storage (conditional)

Modalità di flusso dei parametri

Per Bicep, il file azd associa le variabili di ambiente main.parameters.json ai parametri:

{
  "environmentName": { "value": "${AZURE_ENV_NAME}" },
  "location": { "value": "${AZURE_LOCATION}" },
  "aiFoundryResourceName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
  "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS=[]}" }
}

Durante azd provision, azd recupera questi riferimenti ${VAR} dall'ambiente (.azure/<env>/.env) e li passa alla distribuzione di Bicep. Gli output della distribuzione, ad esempio l'endpoint del progetto Foundry, il nome della distribuzione modello e l'endpoint del registro contenitori, vengono riscritti nell'ambiente per essere usati da azd deploy, azd ai agent run e dai comandi della risorsa azd ai.

Infrastruttura Terraform

Per un nuovo progetto, azd ai agent init --infra=terraform genera file come i seguenti:

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

I servizi basati su contenitori possono anche generare container-registry.tf. I progetti esistenti possono mantenere la propria infrastruttura e ricevere un livello Foundry separato sotto infra/foundry/. Usare il layout generato effettivo anziché spostare i file tra i livelli.

La configurazione di Terraform effettua il provisioning dell'account Foundry, del progetto, delle distribuzioni di modelli e delle risorse correlate richieste dai servizi selezionati. La creazione del registro dei contenitori dipende dalla modalità di distribuzione e dalla configurazione dell'immagine.

main.tfvars.json associa gli input dell'infrastruttura ai valori azd environment. outputs.tf espone ad azd valori quali l'endpoint del progetto Foundry dopo il provisioning. Queste associazioni fanno parte del flusso di lavoro azd; non presupporre che un file di parametri generato funzioni invariato con un oggetto autonomo terraform apply.

Per personalizzare l'infrastruttura Terraform, modificare i file generati .tf , mantenere gli output necessari ai servizi dell'agente ed eseguire azd provision. Esaminare il piano Terraform prima di applicare le modifiche all'infrastruttura.

Stato di Terraform e CI/CD

I file generati non avviano un back-end con stato remoto. Per le distribuzioni in team, configurare il file di stato archiviato in Archiviazione di Azure, chiavi di stato separate per ogni ambiente e le autorizzazioni del back-end necessarie prima di configurare CI/CD.

Vedere Configurare CI/CD con Terraform per il flusso di distribuzione e Usare Terraform con azd per la configurazione back-end.

Limitazioni dell'espulsione di Terraform

Il percorso di estrazione Terraform non supporta la configurazione network: del servizio nell'estensione corrente degli agenti Foundry. Esaminare i vincoli di risorse esistenti prima di espellere un progetto che dispone già dell'infrastruttura. Ejection non è una migrazione generale dello stato da Bicep a Terraform e l'eliminazione delle risorse di produzione non è un prerequisito per adottare Terraform.

Risorse esistenti

I modelli di Bicep supportano la connessione alle risorse Azure esistenti anziché crearne di nuove. Ciò è utile quando il team ha già un'infrastruttura condivisa.

Risorsa esistente	Variabili di ambiente da impostare
Account dei servizi di intelligenza artificiale	AZURE_AI_ACCOUNT_NAME
Container Registry	AZURE_CONTAINER_REGISTRY_RESOURCE_ID e AZURE_CONTAINER_REGISTRY_ENDPOINT
Application Insights	APPLICATIONINSIGHTS_CONNECTION_STRING e APPLICATIONINSIGHTS_RESOURCE_ID

Impostare queste variabili con azd env set prima di eseguire azd provision.

Personalizzare l'infrastruttura

Il infra/ directory è un'infrastruttura standard azd. Per aggiungere o modificare risorse Bicep:

1. Modificare infra/main.bicep o aggiungere nuovi moduli in infra/core/.
2. Aggiungere nuovi parametri a main.parameters.json con i binding di ${VAR}.
3. Impostare le variabili di ambiente corrispondenti azd con azd env set.
4. Eseguire azd provision per applicare le modifiche.

Le modifiche apportate ai file di Bicep vengono mantenute tra le distribuzioni.

Restrizioni relative all'area geografica

Il main.bicep modello limita location alle regioni in cui gli agenti ospitati sono supportati. Se devi distribuire in un'area geografica non inclusa nell'elenco consentito, aggiorna il decoratore @allowed in main.bicep.

Contenuti correlati

• Informazioni di riferimento su azure.yaml per gli agenti ospitati
• Configurare CI/CD per gli agenti ospitati
• azd-ai-starter-basic repository