Configurare le risorse dell'agente standard

La configurazione dell'agente standard usa risorse di Azure a tenant singolo e 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 di Azure.
  • Si mantiene il controllo completo sulla residenza e l'accesso dei dati.

Suggerimento

Per una configurazione più semplice che usa risorse gestite da Microsoft, vedere Configurazione dell'ambiente e scegliere l'opzione di configurazione dell'agente di base.

Prerequisiti

Panoramica delle risorse

Importante

Le configurazioni standard richiedono l'uso di risorse BYO (Bring Your Own) in modo che tutti i dati dell'agente rimangano nel tenant di Azure:

Risorsa Cosa archivia
Archiviazione di Azure (archiviazione file BYO) File caricati dagli sviluppatori e dagli utenti finali
Ricerca di intelligenza artificiale di Azure (ricerca BYO) Archivi vettoriali creati dall'agente
Azure Cosmos DB (archiviazione thread BYO) Messaggi, cronologia conversazioni e metadati dell'agente

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

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

La configurazione standard effettua il provisioning di tre contenitori nell'account Cosmos DB, ognuno dei quali richiede 1000 UR/sec:

Contenitore Scopo
thread-message-store Conversazioni dell'utente finale
system-thread-message-store Messaggi di sistema interni
agent-entity-store Metadati dell'agente (istruzioni, strumenti, nome)

Per più progetti con lo stesso account Foundry, moltiplicare per il numero di progetti. Ad esempio, due progetti richiedono almeno 6000 UR/s (3 contenitori × 1000 UR/s × 2 progetti).

Isolamento dei dati a livello di 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.

Host di funzionalità

Gli host di funzionalità sono sotto-risorse sia nell'account che nel progetto che consentono l'interazione con il servizio Agent.

  • Host di funzionalità dell'account: ha un corpo della richiesta vuoto, ad eccezione del parametro capabilityHostKind="Agents".
  • Host funzionalità del progetto: specifica le risorse per l'archiviazione dello stato dell'agente, ovvero risorse multi-tenant gestite da Microsoft (configurazione di base) o di proprietà del cliente (configurazione standard) a tenant singolo. L'host di funzionalità del progetto funziona come impostazioni del progetto.

Limitazioni

  • Non è possibile aggiornare l'host di funzionalità dopo che è impostato per un progetto o un account.

Eseguire l'approvvigionamento delle risorse passo dopo passo

Nota

Il portale foundry supporta attualmente solo la configurazione dell'agente di base. Per configurare l'installazione dell'agente standard, usare i passaggi manuali o il modello Bicep descritto in questa sezione.

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
    • Risorsa di Ricerca AI di Azure
    • Risorsa di Azure Key Vault (usata per la gestione di segreti e stringhe di connessione per l'infrastruttura dell'agente)
    • [Facoltativo] Risorsa di applicazione Azure Insights
    • [Facoltativo] Risorsa Fonderia esistente

Fase 2: Creare le risorse e le connessioni per Foundry

  1. Creare una risorsa Microsoft Foundry.
  2. Creare connessioni a livello di account:
    • Creare una connessione account alla risorsa di Application Insights.
  3. Implementare gpt-4o o un altro modello compatibile con agenti.
  4. Creare un progetto.
  5. Creare connessioni di progetto:
    • [Se specificato] Connessione del progetto alla risorsa Foundry.
    • Connessione del progetto all'account di archiviazione di Azure.
    • Connessione del progetto alla risorsa di Ricerca intelligenza artificiale di Azure.
    • Connessione del progetto all'account Cosmos DB.

Fase 3: Assegnare ruoli 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).

  1. 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: Configurare gli host di funzionalità

  1. Impostare l'host di funzionalità dell'account con una sezione delle proprietà vuota.
  2. Impostare l'host di funzionalità del progetto con le connessioni Cosmos DB, Archiviazione di Azure e AI Search.

Fase 5: Assegnare autorizzazioni granulari per le risorse

  1. Assegnare l'identità gestita del progetto (sia SMI che UMI) ai ruoli seguenti negli ambiti delle risorse specificati:
    • Azure AI Search (assegnare prima o dopo la creazione del capability host):
      • Collaboratore ai dati dell'indice di ricerca
      • Collaboratore servizio di ricerca
    • Contenitore dell'Archiviazione BLOB di Azure: <workspaceId>-azureml-blobstore
      • Collaboratore dei dati di Storage Blob
    • Contenitore dell'Archiviazione BLOB di Azure: <workspaceId>-agents-blobstore
      • 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 6: Concedere l'accesso per sviluppatori

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

Importante

I ruoli RBAC 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 Bicep

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

Usare una risorsa OpenAI di 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 all'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 account Azure Cosmos DB per NoSQL per ogni account Foundry. Per i requisiti di velocità effettiva e il ridimensionamento multiprogetto, vedere Requisiti di velocità effettiva di Cosmos DB.

Nota

Una capacità di UR/s insufficiente nell'account Cosmos DB causa errori di provisioning degli host di capacità durante la distribuzione.

  1. Accedere all'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 Ricerca intelligenza artificiale di Azure esistente

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

    az login

  2. Esegui il comando seguente per ottenere l'ID risorsa di 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 lo stato dell'host di funzionalità sia Riuscito sia per l'account che per il progetto.
  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

Sintomo Causa Risoluzione
CapabilityHostProvisioningFailed o lo stato dell'host di funzionalità mostra Non riuscito Velocità effettiva di Cosmos DB insufficiente Verificare che l'account Cosmos DB abbia almeno 3000 UR/sec (1000 UR/sec per contenitore × 3 contenitori). Per più progetti, moltiplicare per il numero di progetti.
403 Forbidden quando l'agente legge o scrive file Assegnazioni di ruolo di archiviazione mancanti Verificare che l'identità gestita del progetto abbia il ruolo Collaboratore ai dati del BLOB di archiviazione nel contenitore <workspaceId>-azureml-blobstore e del ruolo Proprietario dei dati del BLOB di archiviazione nel contenitore <workspaceId>-agents-blobstore.
SearchIndexNotFound o 403 nelle operazioni di ricerca Ruoli di ricerca mancanti Verificare che l'identità gestita del progetto abbia sia il ruolo di Collaboratore ai dati dell'indice di ricerca sia quello di Collaboratore servizio di ricerca nella risorsa di Azure AI Search.
AuthorizationFailed durante la creazione o la modifica di agenti Ruolo utente mancante Assegna il ruolo Foundry User allo sviluppatore a livello di progetto.
La richiesta di aggiornamento all'host di funzionalità restituisce 400 BadRequest Aggiornamento non supportato Gli host di funzionalità non possono essere aggiornati dopo la creazione. Eliminare e ricreare il progetto se sono necessarie modifiche alla configurazione.

Contenuto correlato

  • Last updated on