Configurare le risorse dell'agente standard

La configurazione dell'agente standard usa risorse di Azure a tenant singolo gestite dal cliente per archiviare lo stato dell'agente e mantenere tutti i dati dell'agente sotto il controllo. Usare la configurazione standard quando è necessaria la sovranità dei dati completa, la conformità ai criteri di sicurezza aziendali o l'isolamento a livello di progetto.

In questa configurazione:

• Gli stati dell'agente (conversazioni, risposte) vengono archiviati nelle proprie risorse Azure.
• Si mantiene il controllo completo sulla residenza e l'accesso dei dati.

Prerequisiti

• Sottoscrizione Azure. Crearne uno gratuitamente.
• Un account Azure Cosmos DB per NoSQL. Per i requisiti di velocità effettiva, vedere Requisiti di velocità effettiva di Cosmos DB.
• Un account Archiviazione di Azure.
• Una risorsa Azure AI Search.
• Risorsa Azure Key Vault per la gestione dei segreti.
• interfaccia della riga di comando di Azure versione 2.50 o successiva. Eseguire az --version per verificare.
• Autorizzazioni per l'identità che esegue una distribuzione delle impostazioni di funzionalità. Oltre ad aver creato l'account e il progetto, questa identità deve disporre di Storage Blob Data Contributor nell'account di archiviazione e Cosmos DB Operator nell'account Cosmos DB. Azure AI Search non richiede un ruolo del chiamante. Vedere Configurare le impostazioni delle funzionalità dell'agente.
• Un modello compatibile con gli agenti distribuito, ad esempio gpt-4o.

Panoramica delle risorse

Tutti i dati elaborati dal servizio Foundry Agent vengono archiviati automaticamente inattivi in queste risorse, consentendo di soddisfare i requisiti di conformità e gli standard di sicurezza aziendali.

Requisiti di velocità effettiva di Cosmos DB

Il Azure Cosmos DB per NoSQL account deve avere un limite di velocità effettiva totale di almeno 3000 UR/s. Sono supportate sia la velocità effettiva con provisioning che le modalità serverless.

La configurazione Standard effettua il provisioning di cinque contenitori, ognuno dei quali richiede 1000 UR/sec:

thread-message-store, system-thread-message-storee agent-entity-store fanno parte dell'installazione standard del servizio Foundry Agent (versione classica).

Servizio agenti Foundry (nuovo) usa agent-definitions-v1 e run-state-v1.

I contenitori meno recenti appartengono all'esperienza classica e non vengono usati dal nuovo runtime.

isolamento dei dati a livello progetto

L'installazione standard applica l'isolamento dei dati a livello di progetto per impostazione predefinita. Vengono forniti automaticamente due contenitori di archiviazione blob nel tuo account di archiviazione: uno per i file e uno per i dati di sistema temporanei (blocchi, incorporamenti). Viene effettuato il provisioning di tre contenitori nell'account Cosmos DB: uno per i thread utente, uno per i messaggi di sistema e uno per i dati di configurazione dell'agente, ad esempio istruzioni, strumenti e nomi. Questo comportamento predefinito riduce la complessità della configurazione, applicando comunque limiti di dati rigorosi tra i progetti.

Impostazioni delle funzionalità

Le impostazioni delle funzionalità sono proprietà dell'account Foundry e del progetto che dichiarano quali risorse di Azure ospitano lo stato dell'agente, i dati vettoriali e i file. Impostarli nell'account per stabilire le impostazioni predefinite per i progetti ed eseguire l'override di un singolo archivio in un progetto quando tale progetto necessita di una risorsa diversa.

Agent Service predispone l'infrastruttura sottostante necessaria e le connessioni alle tue risorse durante il processo di provisioning. Queste connessioni gestite da impostazioni di funzionalità non sono modificabili durante l'uso, quindi non è possibile modificarle o eliminarle direttamente. Non è anche possibile aggiornare le impostazioni delle funzionalità in un progetto esistente. Per modificare le risorse usate da un progetto, eliminare e ricreare il progetto con le impostazioni desiderate.

Per l'elenco completo delle impostazioni, le autorizzazioni e gli esempi di Bicep, vedere Configurare le impostazioni delle funzionalità dell'agente.

Eseguire l'approvvigionamento delle risorse passo dopo passo

Provisioning manuale

Seguire questa procedura per effettuare manualmente il provisioning di tutte le risorse necessarie per la configurazione dell'agente standard. Attendere circa 30-45 minuti per il processo di provisioning completo.

Fase 1: Creare risorse dipendenti

1. Creare o riutilizzare le risorse seguenti. È possibile creare nuove risorse o passare l'ID risorsa di quelli esistenti:
   • Account Azure Cosmos DB for NoSQL
   • Account di archiviazione di Azure
   • Azure AI Search risorsa
   • risorsa di Azure Key Vault (usata per la gestione di segreti e stringhe di connessione per l'infrastruttura dell'agente)
   • [Facoltativa] Risorsa di applicazione Azure Insights
   • [Facoltativo] Risorsa Fonderia esistente

Fase 2: Creare risorse e impostazioni delle funzionalità di Foundry

2. Creare una risorsa Microsoft Foundry.
3. Creare connessioni a livello di account:
   • Creare una connessione account alla risorsa di Application Insights.
4. Implementare gpt-4o o un altro modello compatibile con agenti.
5. Impostare le impostazioni di funzionalità nell'account, facendo riferimento agli ID risorsa dell'account Cosmos DB, al servizio Azure AI Search e all'account di archiviazione.
6. Creare un progetto. Il progetto eredita le impostazioni delle funzionalità dell'account, a meno che non si sovrascrivano quelle di un singolo negozio. Il servizio Agent effettua il provisioning dell'infrastruttura sottostante necessaria e delle connessioni alle risorse come parte di questo passaggio.

Fase 3: Assegnare ruoli di runtime all'identità gestita del progetto

L'identità gestita del progetto include sia l'identità gestita assegnata dal sistema (SMI) che l'identità gestita assegnata dall'utente (UMI). Questi ruoli regolano l'accesso di runtime per gli agenti in esecuzione. Sono separate dalle autorizzazioni di cui l'identità di distribuzione ha bisogno, e l'una non sostituisce l'altra.

7. Assegnare l'identità gestita del progetto (per SMI) ai ruoli seguenti:
   • Operatore Cosmos DB a livello di account per la risorsa Cosmos DB.
   • Collaboratore account di archiviazione a livello di account per la risorsa account di archiviazione.

Fase 4: Assegnare autorizzazioni granulari per le risorse

8. Assegnare l'identità gestita del progetto (sia SMI che UMI) ai ruoli seguenti negli ambiti delle risorse specificati:
   • Azure AI Search:
     • Collaboratore ai dati dell'indice di ricerca
     • Collaboratore servizio di ricerca
   • Container di Archiviazione BLOB di Azure: <workspaceId>-azureml-blobstore
     • Collaboratore dei dati di Storage Blob
   • Container di Archiviazione BLOB di Azure: <workspaceId>-azureml-agent
     • Proprietario dei dati dei BLOB di archiviazione
   • Cosmos DB per database NoSQL: enterprise_memory
     • Contributore dati integrato di Cosmos DB
     • Ambito: livello di database per coprire tutti i contenitori (non è necessaria alcuna assegnazione di ruolo specifica del contenitore).

Fase 5: Concedere l'accesso per sviluppatori

9. Assegnare a tutti gli sviluppatori che devono creare o modificare agenti nel progetto il ruolo Foundry User a livello di progetto.

   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.

Usare un modello di Bicep

Usare un account Azure OpenAI, un account Archiviazione di Azure esistente, un account Azure Cosmos DB per NoSQL o una risorsa Azure AI Search specificando l'ID completo della risorsa Azure Resource Manager (ARM) nel file del modello standard dell'agente.

Usare una risorsa OpenAI Azure esistente

1. Seguire la procedura descritta in Configurazione dell'ambiente per ottenere l'ID risorsa dell'account Foundry Tools.

2. Nel file modello di agente standard sostituire il segnaposto seguente:

   existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}
   

Usare un account di Archiviazione di Azure esistente per l'archiviazione file

1. Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con l'account di archiviazione:

   az login
   

2. Eseguire il comando seguente per ottenere l'ID risorsa dell'account di archiviazione:

   az storage account show --resource-group <your-resource-group> --name <your-storage-account> --query "id" --output tsv
   

   L'output si trova nel valore aiStorageAccountResourceID necessario nel modello.

3. Nel file modello di agente standard sostituire il segnaposto seguente:

   aiStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}
   

Usare un account esistente di Azure Cosmos DB per NoSQL per l'archiviazione dei thread

Viene creato un Azure Cosmos DB per NoSQL account per ogni account Foundry. Per i requisiti di velocità effettiva e il ridimensionamento multiprogetto, vedere Requisiti di velocità effettiva di Cosmos DB.

1. Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con l'account Cosmos DB:

   az login
   

2. Eseguire il comando seguente per ottenere l'ID risorsa dell'account Azure Cosmos DB:

   az cosmosdb show --resource-group <your-resource-group> --name <your-cosmosdb-account> --query "id" --output tsv
   

   L'output si trova nel valore cosmosDBResourceId necessario nel modello.

3. Nel file modello di agente standard sostituire il segnaposto seguente:

   cosmosDBResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{cosmosDbAccountName}
   

Usare una risorsa di Azure AI Search esistente

1. Accedere al interfaccia della riga di comando di Azure e selezionare la sottoscrizione con la risorsa di ricerca:

   az login
   

2. Eseguire il comando seguente per ottenere l'ID risorsa Azure AI Search:

   az search service show --resource-group <your-resource-group> --name <your-search-service> --query "id" --output tsv
   

3. Nel file modello di agente standard sostituire il segnaposto seguente:

   aiSearchServiceResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}
   

Verificare la configurazione

Dopo aver completato il provisioning, verificare che la configurazione funzioni correttamente:

1. Nel portale di Azure passare al progetto Foundry e verificare che tutte le connessioni (Archiviazione, Cosmos DB, Ricerca di intelligenza artificiale) siano visualizzate nelle impostazioni del progetto.
2. Verificare che un get sul progetto restituisca le impostazioni di funzionalità previste, inclusi i valori ereditati dall'account.
3. Verificare le assegnazioni di ruolo passando alla pagina Controllo di accesso (IAM) di ogni risorsa e confermando che l'identità gestita del progetto ha i ruoli previsti.
4. Creare un agente di test per confermare la funzionalità end-to-end.

Risolvere i problemi comuni

Contenuto correlato

• Configura l'ambiente per il servizio Foundry Agent
• Configurare le impostazioni delle funzionalità dell'agente
• Modello Bicep di configurazione standard dell'agente