Informazioni di riferimento sulle autorizzazioni dell'agente ospitato

Quando si lavora con gli agenti hosted in Microsoft Foundry, è importante comprendere le varie autorizzazioni coinvolte. Esistono diverse classi di autorizzazioni coinvolte nello sviluppo dell'agente ospitato, che si estendono sul piano di controllo Azure Resource Manager e sul piano dati Foundry:

• Autorizzazioni concesse a utenti o entità che utilizzano le risorse foundry
• Autorizzazioni concesse al progetto Foundry
• Autorizzazioni concesse all'agente

Questo articolo è complementare al controllo degli accessi basato su Role per Microsoft Foundry, che introduce i concetti relativi al controllo degli accessi in base al ruolo e i ruoli predefiniti disponibili in Microsoft Foundry. Prima di procedere, è consigliabile acquisire familiarità con tale articolo. Questo articolo illustra le operazioni coinvolte nello sviluppo e nella distribuzione di agenti ospitati, le autorizzazioni necessarie per eseguire tali operazioni e quali ruoli predefiniti coprono tali autorizzazioni.

Per le attività di distribuzione e ciclo di vita end-to-end, vedere Distribuire un agente ospitato e Gestire il ciclo di vita dell'agente ospitato. Per il comportamento specifico dell'identità, vedere Identità dell'agente.

Ruoli in questo articolo

Azure AI Foundry autorizzazioni si estendono su due piani: il piano di controllo Azure Resource Manager (ARM) e il piano dati Foundry. I ruoli Proprietario e Collaboratore hanno autorizzazioni generali del piano di controllo ARM, ma non includono autorizzazioni del piano dati. Le operazioni del piano dati, ad esempio la creazione di agenti o l'interazione con essi, richiedono ruoli specifici di Azure AI Foundry come Azure utente di intelligenza artificiale, Azure ai Project Manager o Azure proprietario dell'intelligenza artificiale.

Questo articolo fa riferimento ai ruoli predefiniti seguenti. Per informazioni sulle definizioni di ruolo personalizzate, vedere Azure ruoli personalizzati.

Diagnosi rapida per sintomo

Usare questi collegamenti per passare direttamente alle sezioni che consentono di risolvere i problemi di autorizzazione comuni:

• Non è possibile creare l'agente: vedere Creazione dell'agente
• Agent non può accedere ai modelli: vedere Creazione dell'agente e Accesso facoltativo all'account
• Deployment ha esito negativo: vedere distribuzione dell'agente Hosted e Registro Azure Container setup
• Agent non è in grado di eseguire il pull delle immagini in fase di esecuzione: vedere Registro Azure Container setup
• L'interazione dell'agente ha esito negativo: vedere Interazione dell'agente
• L'assegnazione di ruolo non riesce: vedere Creazione di un'assegnazione di ruolo che richiede sezioni e configurazione delle connessioni
• Non pubblicare l'agente in Teams o M365 Copilot: vedere Azure servizio Bot setup

Architettura della soluzione agente ospitato

Una configurazione dell'agente ospitata completata prevede più risorse Azure, assegnazioni di identità e connessioni che interagiscono tra loro. Il diagramma seguente illustra i componenti chiave e le relative relazioni:

Foundry Account
├── Model Deployment
└── Foundry Project (has managed identity)
    ├── Hosted Agent
    │   └── Agent Version → references container image
    ├── Connection to Azure Container Registry
    └── Connection to Application Insights

Separate Azure Resources:
├── Azure Container Registry → contains container image
├── Application Insights → logs to Log Analytics Workspace
└── Log Analytics Workspace

Role assignments:
• Foundry Project → Azure AI User role on Foundry Account
• Hosted Agent → Azure AI User role on Foundry Project  
• Foundry Project → Container Registry Repository Reader role on Azure Container Registry
• Foundry Project → Log Analytics Data Reader role on Log Analytics Workspace

Optional (Teams / M365 Copilot publishing):
└── Azure Bot Service → connected to agent application (Channels auth mode)

Il diagramma precedente mostra come le risorse sono organizzate gerarchicamente e quali assegnazioni di ruolo consentono la comunicazione tra di esse. Le sezioni seguenti forniscono requisiti di configurazione dettagliati per ogni componente.

Risorse di Azure necessarie

Ogni distribuzione dell'agente ospitato richiede che queste risorse Azure siano configurate correttamente:

• Un account Foundry
  • Un'assegnazione di ruolo consente all'identità gestita del progetto di accedere all'account per l'accesso al modello. Azure AI User è il ruolo predefinito consigliato.
• Distribuzione di un modello (nell'account)
• Progetto Foundry (nell'account)
  • Il progetto ha un'identità gestita. Il progetto ottiene anche un progetto agente e un'identità dell'agente al momento della creazione del primo agente.
  • Un'assegnazione di ruolo consente all'identità dell'agente ospitato di accedere al progetto per l'accesso al modello. Azure AI User è il ruolo predefinito consigliato.
  • Le assegnazioni di ruolo consentono agli utenti client o alle entità di interagire con gli agenti nel progetto in fase di esecuzione. Azure AI User è il ruolo predefinito consigliato.
• Un agente ospitato (nel progetto)
  • L'agente ottiene automaticamente un progetto agente e un'identità dell'agente.
• Versione dell'agente (nell'oggetto agente ospitato)
• An Registro Azure Container (ACR)
  • Un'assegnazione di ruolo consente all'identità gestita del progetto di eseguire il pull delle immagini dal Registro di sistema. Il ruolo predefinito consigliato per il lettore del repository del Registro Azure Container è.
  • Un'assegnazione di ruolo consente a un utente o a un'entità servizio che distribuisce l'agente di eseguire il push delle immagini nel Registro di sistema. Container Registry Repository Writer è il ruolo predefinito consigliato.
• Un componente di Application Insights
• area di lavoro A Log Analytics (collegata al componente Application Insights)
  • Un'assegnazione di ruolo consente all'identità gestita del progetto di leggere i dati di telemetria per le valutazioni. Log Analytics Lettore dati è il ruolo predefinito consigliato.
• Diverse risorse di connessione (nel progetto):
  • Viene creata una connessione per il Registro Azure Container, usato dal progetto per il pull delle immagini.
  • Viene creata una connessione per Application Insights, che il progetto usa per generare dati di telemetria per i relativi agenti. Questa connessione non usa l'identità per impostazione predefinita.

Alcuni set di utenti o entità devono disporre dell'autorizzazione per creare e gestire queste risorse. Questo articolo presuppone una configurazione in cui le risorse Azure si trovano tutte all'interno dello stesso gruppo di risorse e mostra la concessione dell'accesso in scrittura su tale gruppo di risorse. Questo approccio al gruppo di risorse è una configurazione comune per molti team, ma la configurazione specifica può variare. Se si ha una strategia diversa per l'organizzazione delle risorse, potrebbe essere necessario suddividere le autorizzazioni tra i gruppi di risorse usati.

Questo elenco non include le risorse di rete. Tuttavia, l'utente o l'entità servizio che effettua il provisioning delle risorse Azure potrebbe anche richiedere l'autorizzazione per creare e gestire reti virtuali, subnet ed endpoint privati per proteggere le risorse.

Agent applications

Se si usano applicazioni agente, l'elenco include anche:

• Un'applicazione agente (nel progetto)
  • L'applicazione agente ottiene automaticamente un progetto agente e un'identità dell'agente. Ripetere le assegnazioni di ruolo per l'identità dell'agente ospitato con l'identità dell'agente dell'applicazione agente.
• Distribuzione dell'agente (nell'applicazione dell'agente)

Azure configurazione delle risorse

Configurazione dell'account Foundry

La creazione di un account Foundry richiede l'autorizzazione Microsoft.CognitiveServices/accounts/write nell'ambito del gruppo di risorse.

L'identità gestita del progetto deve accedere all'account Foundry per eseguire l'inferenza del modello tramite l'endpoint del progetto. L'accesso del progetto è coperto dal ruolo Azure AI User nell'ambito dell'account Foundry. Questa assegnazione di ruolo può essere creata automaticamente quando viene creato il progetto, a seconda delle autorizzazioni dell'utente o dell'entità servizio che crea il progetto.

Potrebbero essere necessarie altre assegnazioni di ruolo se il codice dell'agente accede direttamente all'endpoint OpenAI a livello di account o ad altre funzionalità a livello di account non proxy dall'endpoint del progetto. Per altre informazioni, vedere Accesso facoltativo all'account.

Model deployment

La creazione di una distribuzione di modelli richiede l'autorizzazione Microsoft.CognitiveServices/accounts/deployments/write nell'ambito dell'account Foundry.

Project setup

La creazione di un progetto Foundry richiede l'autorizzazione Microsoft.CognitiveServices/accounts/projects/write nell'ambito dell'account Foundry.

Se l'autore del progetto ha la possibilità di assegnare il ruolo Azure AI User nell'ambito dell'account, il sistema crea automaticamente due assegnazioni di ruolo:

• All'autore del progetto viene concesso il ruolo utente di intelligenza artificiale Azure nell'ambito dell'account Foundry.
• All'identità gestita del progetto viene concesso il ruolo utente di intelligenza artificiale Azure nell'ambito dell'account Foundry.

Per l'identità dell'agente nel progetto è necessaria un'assegnazione di ruolo simile. Per altre informazioni, vedere la sezione Creazione dell'agente .

Registro Azure Container configurazione

La creazione di un Registro Azure Container richiede l'autorizzazione Microsoft.ContainerRegistry/registries/write nell'ambito del gruppo di risorse.

L'identità gestita del progetto deve disporre delle autorizzazioni per eseguire il pull dell'immagine da Registro Azure Container. Esistono due ruoli predefiniti adatti a questa attività, che devono essere assegnati nell'ambito della risorsa del Registro Azure Container:

• Lettore del repository del Registro Container (preferito perché modella il pull come azione di dati)
• AcrPull

La creazione di tale assegnazione di ruolo richiede l'autorizzazione Microsoft.Authorization/roleAssignments/write nell'ambito del Registro Azure Container.

Per informazioni dettagliate sull'assegnazione dei ruoli in Azure, vedere Creare Azure assegnazioni di ruolo.

1 Questi ruoli hanno ma sono vincolati ad assegnare solo il ruolo />

Anche l'utente o l'entità servizio che esegue il push delle immagini nel Registro di sistema richiede un'assegnazione di ruolo. Per altre informazioni, vedere la sezione Distribuzione dell'agente ospitato .

Configurazione di Application Insights e Log Analytics

La creazione di una risorsa di Application Insights richiede l'autorizzazione Microsoft.Insights/components/write nell'ambito del gruppo di risorse.

La creazione di un'area di lavoro Log Analytics richiede l'autorizzazione Microsoft.OperationalInsights/workspaces/write nell'ambito del gruppo di risorse.

Se si prevede di usare la funzionalità di valutazione, l'identità gestita del progetto deve disporre delle autorizzazioni per la lettura dall'area di lavoro Log Analytics. È possibile abilitare questo accesso concedendo il ruolo Log Analytics Data Reader all'identità gestita del progetto nell'ambito dell'area di lavoro Log Analytics.

La creazione di tale assegnazione di ruolo richiede l'autorizzazione Microsoft.Authorization/roleAssignments/write nell'ambito dell'area di lavoro Log Analytics.

Per informazioni dettagliate sull'assegnazione dei ruoli in Azure, vedere Creare Azure assegnazioni di ruolo.

1 Questi ruoli hanno ma sono vincolati ad assegnare solo il ruolo />

Connections setup

La creazione di una connessione richiede l'autorizzazione Microsoft.CognitiveServices/accounts/projects/connections/write nell'ambito del progetto Foundry.

L'utente o l'entità servizio che crea le connessioni richiede anche le informazioni di connessione per il componente Application Insights e il registro contenitori. I dettagli della connessione possono essere forniti dall'utente o dall'entità servizio che ha creato tali risorse o tramite l'accesso in lettura su tali risorse.

Agent applications

Se si usano applicazioni agente, è necessario creare un'applicazione agente nel progetto Foundry. La creazione di un'applicazione agente richiede l'autorizzazione Microsoft.CognitiveServices/accounts/projects/applications/write nell'ambito del progetto Foundry.

agentDeployment gli oggetti sono anche risorse arm, ma vengono creati come parte del processo di distribuzione dell'agente ospitato. Per altre informazioni, vedere Distribuzione dell'agente ospitato.

Agent creation

Gli agenti vengono creati tramite un'operazione del piano dati. La creazione di un agente richiede l'autorizzazione Microsoft.CognitiveServices/accounts/AIServices/agents/write nell'ambito del progetto Foundry.

Poiché l'identità dell'agente potrebbe essere disponibile solo dopo la creazione dell'agente, alcune assegnazioni di ruolo non possono essere create fino a dopo questo punto. Per eseguire l'inferenza del modello con l'endpoint del progetto, l'identità dell'agente richiede le autorizzazioni seguenti nell'ambito del progetto Foundry:

• Microsoft.CognitiveServices/accounts/AIServices/responses/*
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/read (per le definizioni personalizzate usare Microsoft.CognitiveServices/accounts/AIServices/agents/*/read)
• Microsoft.CognitiveServices/accounts/AIServices/agents/storage/write (per le definizioni personalizzate usare Microsoft.CognitiveServices/accounts/AIServices/agents/*/write)

La creazione di tale assegnazione di ruolo richiede l'autorizzazione Microsoft.Authorization/roleAssignments/write nell'ambito del progetto Foundry.

Per informazioni dettagliate sull'assegnazione dei ruoli in Azure, vedere Creare Azure assegnazioni di ruolo.

1 Sia che hanno un vincolo che può assegnare solo il ruolo /> Azure AI Project Manager e Azure AI Account Owner non sarà in grado di assegnare tale ruolo personalizzato.

Accesso facoltativo all'account

Quando si usa Foundry SDK e l'endpoint del progetto per l'inferenza del modello, l'inferenza dei proxy di progetto chiama alla distribuzione a livello di account usando la propria identità gestita. Tuttavia, se il codice dell'agente ignora l'endpoint del progetto e chiama direttamente l'endpoint OpenAI a livello di account , ad esempio https://{account}.cognitiveservices.azure.com, l'identità dell'agente richiede uno dei ruoli seguenti nell'ambito dell'account:

• Utente OpenAI di Servizi cognitivi : copre solo le azioni di dati OpenAI.
• Azure Utente di intelligenza artificiale: include tutte le azioni sui dati cognitiveServices nell'account.

Le funzionalità a livello di account non sono proxy dall'endpoint del progetto. Queste funzionalità includono Speech, Content Safety, Visione artificiale, Document Intelligence, Language e Translator. Richiedono un'assegnazione di ruolo nell'ambito dell'account se l'agente accede direttamente. Per queste funzionalità, assegnare uno dei ruoli seguenti nell'ambito dell'account:

• Utente di Servizi cognitivi : illustra riconoscimento vocale, visione, linguaggio e altre funzionalità non OpenAI.
• Azure Utente di intelligenza artificiale: include tutte le azioni sui dati di CognitiveServices, tra cui OpenAI e le funzionalità elencate in precedenza, con una singola concessione.

Distribuzione dell'agente ospitato

Le operazioni di distribuzione dell'agente ospitato sono operazioni del piano di controllo. Per indicazioni dettagliate sulla distribuzione, vedere Distribuire un agente ospitato.

Eseguire il push di un'immagine nel Registro di sistema

L'utente o l'entità servizio che distribuisce l'agente deve disporre dell'autorizzazione per eseguire il push dell'immagine in Registro Azure Container. Esistono due ruoli predefiniti adatti a questa attività, che devono essere assegnati nell'ambito della risorsa del Registro Azure Container:

• Writer del repository del registro contenitori (preferito perché modella il push come azione di dati)
• AcrPush

Creare una nuova versione dell'agente

La creazione di un agente richiede l'autorizzazione Microsoft.CognitiveServices/accounts/AIServices/agents/write nell'ambito del progetto Foundry.

Se si usano applicazioni agente, è anche necessario creare un agentDeployment oggetto che faccia riferimento a una versione dell'agente appena distribuita. Si tratta di un'operazione del piano di gestione. La creazione di un oggetto agentDeployment richiede l'autorizzazione Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments/write nell'ambito dell'applicazione agente.

Aggiornare l'agente per usare la nuova versione

Se si usa l'endpoint dell'agente, la selezione della versione viene configurata nell'oggetto agente. L'aggiornamento dell'agente per l'uso della nuova versione richiede l'autorizzazione Microsoft.CognitiveServices/accounts/AIServices/agents/write nell'ambito del progetto Foundry.

Se invece si usa l'applicazione agente, la selezione della versione viene configurata nell'oggetto applicazione agente. L'aggiornamento dell'applicazione agente per l'uso del nuovo oggetto richiede l'autorizzazione />

Azure servizio Bot configurazione

La pubblicazione dell'agente in Microsoft Teams o Microsoft 365 Copilot è facoltativa. Quando si esegue questa operazione, il flusso di pubblicazione esegue operazioni del piano di controllo per creare una risorsa Azure servizio Bot e configurarne i canali, quindi aggiorna l'agente o l'applicazione agente per consentire le richieste da servizio Bot.

Creazione del servizio bot

La creazione della risorsa del servizio bot richiede l'autorizzazione Microsoft.BotService/botServices/write nell'ambito del gruppo di risorse.

Configuring channels

La configurazione dei canali Teams e Microsoft 365 Extensions nel servizio bot richiede l'autorizzazione Microsoft.BotService/botServices/channels/write nell'ambito della risorsa del servizio bot.

Aggiornamento dell'applicazione agente o agente

Il flusso di pubblicazione imposta i canali (Azure servizio Bot) come modalità di autenticazione nell'applicazione agente o agente. L'oggetto aggiornato dipende dallo scenario:

• Scenario dell'applicazione agent: l'oggetto applicazione agente viene aggiornato. Si tratta di un'operazione di scrittura del piano di controllo. Gli stessi requisiti di ruolo si applicano come documentato nelle applicazioni agent.
• Scenario endpoint agente: l'oggetto agente viene aggiornato. Si tratta di un'operazione di scrittura del piano dati. Gli stessi requisiti di ruolo si applicano come documentato in Creare una nuova versione dell'agente.

Per indicazioni dettagliate sulla pubblicazione in Teams o Copilot M365, vedere Publish per Microsoft 365 Copilot e Microsoft Teams.

Agent interaction

L'interazione con l'agente richiede che l'utente chiamante o l'entità servizio disponga di un'autorizzazione del piano dati. Per interagire con un'applicazione agent, è necessario Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action nell'ambito dell'applicazione agente.

Agent observability

Visualizzazione dei dati di telemetria

Per accedere ai dati di telemetria dell'agente sono necessarie autorizzazioni di lettura per la risorsa di Application Insights. Sono incluse la visualizzazione di tracce, log e metriche tramite il portale di Azure, il portale foundry, le API e gli strumenti di monitoraggio.

Assegnare il lettore di monitoraggio nell'ambito della risorsa di Application Insights. Le autorizzazioni */read in questo ruolo accedono ai dati dell'area di lavoro Log Analytics sottostanti senza richiedere un'assegnazione separata con ambito area di lavoro.

Se è necessario usare direttamente l'area di lavoro Log Analytics, assegnare anche Log Analytics Lettore nell'ambito dell'area di lavoro.

Visualizzazione dei costi nella valuta di fatturazione

La visualizzazione dei costi nella valuta di fatturazione nel portale foundry richiede l'autorizzazione Microsoft.Billing/billingProperty/read. Questa autorizzazione richiede una sottoscrizione o un'assegnazione con ambito account di fatturazione. L'ambito del gruppo di risorse non copre questa autorizzazione.

Questa autorizzazione è per la comodità di visualizzazione del portale e non è necessaria per la funzionalità dell'agente ospitato. È possibile omettere in modo sicuro questa autorizzazione per la maggior parte degli utenti.

Related content

• Agenti ospitati: informazioni sull'architettura e il ciclo di vita dell'agente ospitato.
• Controllo degli accessi in base al ruolo per Microsoft Foundry: esaminare i ruoli, gli ambiti e i modelli di assegnazione predefiniti.
• Identità agente: comprendere in che modo l'identità dell'agente e l'identità gestita del progetto differiscono.