Gehoste agentsessies per gebruiker isoleren

Eén gehoste agent dient veel gebruikers van één eindpunt. In dit artikel leest u hoe Microsoft Foundry de sessies, gesprekken en opgeslagen gegevens van elke gebruiker privé houdt en hoe u deze isolatie kunt uitbreiden naar de gebruikers van uw eigen toepassing. Aan het einde kunt u een agent aanroepen en bevestigen dat de ene beller de sessies, gesprekken of opgeslagen gegevens van een andere beller niet kan zien.

Prerequisites

• Een uitgerolde gehoste agent. Zie Een gehoste agent implementeren om er een te implementeren.
• De Azure Developer CLI Foundry-extensies voor de CLI-stappen. Zie De Azure Developer CLI Foundry-extensies installeren.
• Een geverifieerde sessie. Voer azd auth login uit, of meld u aan met de Microsoft Entra-aanmeldingsgegevens die uw SDK of REST-client gebruikt.
• De rol Foundry User in het project.

Meer informatie over isolatie per gebruiker

Het platform identificeert elke beller van hun Microsoft Entra token en bewaart hun gegevens privé voor die identiteit, ook al bereikt elke beller dezelfde agent via één gedeeld eindpunt. Voor elke gebruiker blijft het volgende geïsoleerd:

• Gesprekken. De gespreksgeschiedenis van elke gebruiker, de berichten, hulpprogramma-aanroepen en antwoorden die ze via het protocol Antwoorden threaden, is privé voor die gebruiker. Een gebruiker kan de gesprekken van een andere gebruiker niet lezen of vermelden.
• Sessies. Elke beller krijgt standaard een eigen sessie, dus de sessies die één gebruiker kan vermelden en beheren, bevatten geen sessies van een andere gebruiker.
• Opgeslagen gegevens. Gegevens die door uw agent worden opgeslagen voor een gebruiker, vallen binnen het bereik van die gebruiker, zodat deze niet worden geretourneerd naar een andere gebruiker.

U kunt het beschouwen als één agent die veel privéwerkruimten bedient. Elke sessie krijgt ook een privébestandssysteem $HOME in een eigen sandbox, die standaard wordt geïsoleerd omdat elke gebruiker een eigen sessie krijgt. Als u in plaats daarvan meerdere gebruikers in één sessie plaatst, wordt die sandbox gedeeld. Zie Multiplex meerdere gebruikers in één gehoste agentsessie. Zie Gehoste agents in Foundry Agent Service voor meer informatie over het sessiemodel.

Enkele gangbare scenario's zijn:

• Chat per gebruiker. Elke aangemelde klant krijgt hun eigen gespreksgeschiedenis, sessies en opgeslagen gegevens.
• Apps met meerdere tenants. De gebruikers van elke tenant zijn geïsoleerd van de gebruikers van elke andere tenant.

U krijgt deze isolatie standaard. In de volgende secties ziet u het standaardpad en hoe u het uitbreidt naar gebruikers die u zelf verifieert.

Een agent aanroepen met automatische isolatie

Roep de agent op met de identiteit waarmee u bent aangemeld. Het platform maakt een sessie die aan die identiteit is gekoppeld en geeft de bijbehorende agent_session_id terug.

azd ai agent invoke "Summarize the latest support tickets"

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
    }'

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}")

const openAIClient = project.getOpenAIClient({
    azureConfig: { allowPreview: true, agentName: "my-agent" },
});

const response = await openAIClient.responses.create({
    input: "Summarize the latest support tickets",
});
const sessionId = (response as any).agent_session_id;
console.log(`Session: ${sessionId}`);

Sessies isoleren voor uw eigen gebruikers

Als uw toepassing zijn eigen eindgebruikers verifieert, bijvoorbeeld via Google, GitHub of een aangepaste id-provider, kan een vertrouwde service Foundry vertellen tot welke eindgebruiker een aanvraag behoort, zodat het platform sessies per eindgebruiker in plaats van per aanroepservice isoleert.

De service verzendt de stabiele id van de eindgebruiker in de x-ms-user-identity header. Het platform behandelt de waarde als een ondoorzichtige string en koppelt de sessie eraan. De waarde moet 1-256 tekens zijn en mag alleen letters, cijfers en de tekens . _ : - @bevatten; andere waarden worden geweigerd.

Om x-ms-user-identity door te geven, moet de aanroepende identiteit over de machtiging Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action voor de agent beschikken. Deze machtiging is niet opgenomen in een ingebouwde rol. Dit viel eerder onder de Microsoft.CognitiveServices/* data-actie, maar die actie kent dit niet langer toe. Ken deze expliciet toe door een aangepaste rol te maken die de data-actie bevat en die rol toe te wijzen aan de identiteit van uw service in de tussenlaag. Een oproeper zonder dit krijgt een 403. Zie De identiteit van de eindgebruiker delegeren voor de aangepaste roldefinitie- en toewijzingsopdrachten.

Als een service over deze toestemming beschikt maar de header niet meestuurt in een aanvraag, beperkt het platform die sessie tot de eigen identiteit van de service in plaats van tot die van een eindgebruiker. Uw service kan gedelegeerde en niet-gedelegeerde aanroepen combineren, maar alleen aanvragen waarin x-ms-user-identity is opgenomen, worden per eindgebruiker geïsoleerd.

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
    }'

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>"},
)

const openAIClient = project.getOpenAIClient({
    azureConfig: { allowPreview: true, agentName: "my-agent" },
});

const response = await openAIClient.responses.create(
    { input: "Summarize my open tickets" },
    { headers: { "x-ms-user-identity": "<stable-end-user-id>" } },
);
console.log(response.output_text);

De identiteit van de eindgebruiker beveiligen

Wanneer u gedelegeerde isolatie gebruikt, is uw service de grens van de vertrouwensrelatie. Kies id's die stabiel zijn per gebruiker, uniek en moeilijk te raden. Gebruik dezelfde waarde voor dezelfde gebruiker opnieuw, zodat de sessies correct worden hervat.

Isolatie controleren

Controleer of twee identiteiten twee afzonderlijke sessies krijgen:

1. Roep de agent aan met één identiteit en noteer de teruggegeven agent_session_id.
2. Roep de agent aan als een tweede identiteit, een andere aangemelde gebruiker of een andere x-ms-user-identity waarde, en noteer het agent_session_id.
3. Controleer of de twee ID's verschillen en of, wanneer de sessies voor elke identiteit afzonderlijk worden opgevraagd, alleen de sessies van die identiteit worden geretourneerd.

Als u isolatie end-to-end wilt zien, implementeert u het voorbeeld van de notitieagent, waarin notities per sessie worden opgeslagen: $HOMEde notities van elke identiteit komen terecht in een afzonderlijk sessiebestand dat alleen die identiteit kan weergeven of downloaden via de Sessiebestanden-API.

Sessies voor alle gebruikers weergeven

Standaard ziet elke beller alleen hun eigen sessies. Een beheerder of automatisering met de rol Foundry User op het project kan alle sessies op de agent weergeven en beheren, ongeacht door welke identiteit deze zijn gemaakt. Zie Gehoste agentsessies beheren om sessies te beheren.

Isolatiesleutels op containerprotocol 1.0.0 (afgeschaft)

Agents met containerprotocolversie 1.0.0 gebruiken het eerdere model met isolatiesleutels, waarbij de aanroeper een isolatiesleutel opgeeft om sessies af te bakenen, in plaats van dat het platform de identiteit afleidt uit het Microsoft Entra-token. Dit model - en protocol 1.0.0 zelf - is afgeschaft. Agents op protocol 1.0.0 blijven werken tot 31 juli 2026; daarna blokkeert het platform aanvragen voor agents die nog steeds worden uitgevoerd op protocol 1.0.0.

Voer een upgrade uit naar protocol 2.0.0 om de automatische isolatie per gebruiker op te halen die eerder in dit artikel is beschreven. Protocol 2.0.0 vereist de AgentServer SDK die deze ondersteunt: azure-ai-agentserver-core 2.0.0b7 of hoger voor Python, of Azure.AI.AgentServer.Core 1.0.0-beta.26 of hoger voor .NET. Eerdere versies maken gebruik van protocol 1.0.0; werk ze bij als onderdeel van de upgrade.

• Als u voorlopig protocol 1.0.0 blijft gebruiken, raadpleegt u Isolatiesleutels doorgeven aan een gehoste agent voor hoe isolatiesleutels werken.
• Zie Gehoste agents migreren om een upgrade uit te voeren.

Problemen met isolatie oplossen

Verwante inhoud

• Sessies van gehoste agents beheren om sessies weer te geven, te inspecteren en te verwijderen, ook voor verschillende gebruikers.
• Multiplex meerdere gebruikers in één gehoste agentsessie wanneer meerdere gebruikers opzettelijk één sessie delen.
• Concepten van agentidentiteiten in Microsoft Foundry om te begrijpen hoe agent- en gebruikersidentiteiten werken.
• Roep een gehoste agent aan met de Azure Developer CLI voor elke aanroepvariant en -optie.
• Voorbeeld van notitieagent voor een uitvoerbare agent waarin gegevens van gebruikers per sessie worden opgeslagen (Python en C#).