Isolare le sessioni dell'agente ospitato per utente

Un singolo agente ospitato serve molti utenti da un endpoint. Questo articolo illustra come Microsoft Foundry mantiene private le sessioni, le conversazioni e i dati archiviati di ogni utente e come estendere tale isolamento agli utenti della propria applicazione. Alla fine, è possibile richiamare un agente e confermare che un chiamante non può visualizzare sessioni, conversazioni o dati archiviati di un altro chiamante.

Prerequisites

Important

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.

Comprendere l'isolamento per utente

La piattaforma identifica ogni chiamante dal token Microsoft Entra e mantiene i dati privati per tale identità, anche se ogni chiamante raggiunge lo stesso agente tramite un endpoint condiviso. Per ogni utente, quanto segue rimane isolato:

  • Conversazioni. La cronologia della conversazione di ogni utente, ovvero i messaggi, le chiamate agli strumenti e le risposte che threadano tramite il protocollo Risposte, è privata per tale utente. Un utente non può leggere o elencare le conversazioni di un altro utente.
  • Sessioni. Ogni chiamante ottiene la propria sessione per impostazione predefinita, quindi le sessioni che un utente può elencare e gestire non includono sessioni di un altro utente.
  • Dati archiviati. I dati archiviati dall'agente per un utente hanno come ambito tale utente, quindi non vengono restituiti a un utente diverso.

Si pensi a un agente che gestisce molte aree di lavoro private. Ogni sessione dispone anche di un file system privato $HOME all'interno della propria sandbox, isolato per impostazione predefinita poiché ogni utente dispone della propria sessione. Se invece si inserisce più utenti in una sessione, tale sandbox viene condivisa. Vedere Multiplex multiple users in una sessione dell'agente ospitato. Per altre informazioni sul modello di sessione, vedere Agenti ospitati nel servizio agente Foundry.

Gli scenari tipici includono:

  • Chat per utente. Ogni cliente connesso ottiene la propria cronologia delle conversazioni, le sessioni e i dati archiviati.
  • Applicazioni multi-tenant. Gli utenti di ogni tenant sono isolati dagli utenti di ogni altro tenant.

Questo isolamento è disponibile per impostazione predefinita. Le sezioni seguenti illustrano il percorso predefinito, quindi come estenderlo agli utenti autenticati manualmente.

Richiamare un agente con isolamento automatico

Richiamare l'agente come identità di accesso. La piattaforma crea una sessione associata a tale identità e restituisce agent_session_id.

azd ai agent invoke "Summarize the latest support tickets"

La sessione appartiene all'identità proveniente da azd auth login. Un utente connesso diverso che esegue lo stesso comando ottiene una sessione privata separata.

Configurare le variabili condivise usate dagli esempi REST:

BASE_URL="https://my-account.services.ai.azure.com/api/projects/my-project"
API_VERSION="v1"
RESOURCE="https://ai.azure.com"
AGENT_NAME="my-agent"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --body '{
        "input": "Summarize the latest support tickets",
        "stream": false
    }'

Il token Microsoft Entra nella richiesta identifica il chiamante. Il payload di risposta include agent_session_id, creato dalla piattaforma e associato a tale identità.

openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Summarize the latest support tickets",
)
session_id = response.model_extra.get("agent_session_id")
print(f"Session: {session_id}")

Il client OpenAI esegue l'autenticazione con la credenziale Microsoft Entra del chiamante, quindi la sessione ha come ambito tale identità.

Isolare le sessioni per i propri utenti

Se l'applicazione autentica i propri utenti finali, ad esempio tramite Google, GitHub o un provider di identità personalizzato, un servizio attendibile può indicare a Foundry a quale utente finale appartiene una richiesta, quindi la piattaforma isola le sessioni per utente finale anziché per ogni servizio chiamante.

Il servizio invia l'identificatore stabile dell'utente finale nell'intestazione x-ms-user-identity . La piattaforma tratta il valore come una stringa opaca e limita la sessione a tale valore. Il valore deve essere composto da 1 a 256 caratteri e deve contenere solo lettere, cifre e caratteri . _ : - @. Gli altri valori vengono rifiutati.

Per passare x-ms-user-identity, l'identità chiamante deve contenere l'autorizzazione Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action per l'agente. Questa autorizzazione non è inclusa in alcun ruolo predefinito. In precedenza era coperto dall'azione sui dati Microsoft.CognitiveServices/*, ma tale azione non lo concede più. Concedilo esplicitamente creando un ruolo personalizzato che includa l'azione sui dati e assegnando tale ruolo all'identità del servizio di livello intermedio. Chi chiama senza di esso riceve un 403. Per i comandi di definizione e assegnazione del ruolo personalizzati, vedere Delegare l'identità dell'utente finale.

Se un servizio dispone di questa autorizzazione ma non invia l'header in una richiesta, la piattaforma limita quella sessione all'identità del servizio stesso anziché a quella di un utente finale. Il servizio può combinare chiamate delegate e non delegate, ma solo le richieste che includono x-ms-user-identity sono isolate per ogni utente finale.

Avvertimento

All'interno della delega, la piattaforma non delimita un utente finale delegato da un altro. Applica un limite rigido solo tra i chiamanti delegati e non delegati, consentendo a qualsiasi utente delegato di accedere a una sessione creata dall'app. Assegnare a ogni utente il proprio ID sessione; se si instradano due utenti alla stessa sessione, possono visualizzare i dati degli altri. Per condividere deliberatamente una sessione, vedi Gestire più utenti in un'unica sessione di un agente ospitato.

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "x-ms-user-identity=<stable-end-user-id>" \
    --body '{
        "input": "Summarize my open tickets",
        "stream": false
    }'

Sostituire <stable-end-user-id> con l'identificatore assegnato dal servizio all'utente finale connesso, ad esempio un ID utente con ambito tenant.

openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Summarize my open tickets",
    extra_headers={"x-ms-user-identity": "<stable-end-user-id>"},
)

Sostituire <stable-end-user-id> con l'identificatore assegnato dal servizio all'utente finale connesso. La sessione ha come ambito l'utente finale anziché il servizio chiamante.

Azure Developer CLI richiama l'agente usando la tua identità con cui hai effettuato l'accesso, quindi non trasmette un'identità delegata dell'utente finale. Usa il percorso REST o l'SDK dal tuo servizio per inviare x-ms-user-identity.

Proteggere l'identità dell'utente finale

Quando si usa l'isolamento delegato, il servizio è il limite di attendibilità. Scegliere gli identificatori stabili per utente, univoci e difficili da indovinare. Riutilizzare lo stesso valore per lo stesso utente in modo che le sessioni riprendano correttamente.

Important

Derivare il valore da un'identità x-ms-user-identity autenticata sul lato server: mai da un valore fornito direttamente dal browser o dal client. In caso contrario, un chiamante può impostare l'intestazione sull'identificatore di un altro utente e leggere i dati dell'utente. Qualsiasi servizio con l'autorizzazione di delega può agire per conto di qualsiasi utente finale, quindi concederlo solo ai servizi attendibili.

Verificare l'isolamento

Verificare che due identità ottengano due sessioni separate:

  1. Richiamare l'agente usando un'identità e prendere nota del agent_session_id restituito.
  2. Richiama l'agente con una seconda identità, ovvero un altro utente connesso o un valore x-ms-user-identity diverso, e prendi nota del suo agent_session_id.
  3. Conferma che i due ID siano diversi e che, elencando le sessioni per ciascuna identità, vengano restituite solo le sessioni di quella stessa identità.

Per vedere l'isolamento end-to-end, distribuire l'esempio di agente per prendere appunti, che archivia le note per sessione in $HOME: le note di ogni identità vengono salvate in un file di sessione separato che solo quella identità può elencare o scaricare tramite l'API dei file di sessione.

Visualizzare le sessioni tra gli utenti

Per impostazione predefinita, ogni chiamante vede solo le proprie sessioni. Un amministratore o un'automazione che ha il ruolo Foundry User nel progetto può elencare e gestire tutte le sessioni sull'agente, indipendentemente dall'identità che le ha create. Per gestire le sessioni, vedere Gestire le sessioni dell'agente ospitato.

Chiavi di isolamento nel protocollo contenitore 1.0.0 (deprecato)

Gli agenti che usano il protocollo container versione 1.0.0 adottano il modello precedente basato sulla chiave di isolamento, in cui il chiamante fornisce una chiave di isolamento per definire l'ambito delle sessioni, invece che dalla piattaforma, che ricava l'identità dal token Microsoft Entra. Questo modello, e il protocollo 1.0.0 stesso, sono deprecati. Gli agenti sul protocollo 1.0.0 continuano a funzionare fino al 31 luglio 2026; successivamente, la piattaforma blocca le richieste agli agenti che continuano a essere eseguiti sul protocollo 1.0.0.

Eseguire l'aggiornamento al protocollo 2.0.0 per ottenere l'isolamento automatico per utente descritto in precedenza in questo articolo. Il protocollo 2.0.0 richiede AgentServer SDK che la supporta: azure-ai-agentserver-core 2.0.0b7 o versione successiva per Python o Azure.AI.AgentServer.Core 1.0.0-beta.26 o versione successiva per .NET. Le versioni precedenti usano il protocollo 1.0.0; aggiornarli come parte dell'aggiornamento.

Risolvere i problemi di isolamento

Sintomo Causa possibile Cosa provare
403 o session_not_accessible quando si accede a una sessione La sessione appartiene a un'identità diversa. Usare la stessa identità che ha creato la sessione o mantenere il ruolo Utente Foundry per visualizzare le sessioni di altre identità.
403 su una richiesta che imposta x-ms-user-identity Il chiamante non dispone dell'autorizzazione UserIdentityImpersonation , che non è più concessa dai ruoli predefiniti. Creare un ruolo personalizzato che includa l'azione dati Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action e assegnarlo al servizio chiamante.
Le esecuzioni locali non isolano le sessioni Le esecuzioni in locale non impongono l'isolamento. Testare l'isolamento rispetto a un agente distribuito. La modalità locale (--local, azd ai agent run) è destinata a un singolo utente.

Contenuti correlati

  • Last updated on