Sitzungen gehosteter Agents pro Benutzer isolieren

Ein einzelner gehosteter Agent dient vielen Benutzern von einem Endpunkt aus. In diesem Artikel erfahren Sie, wie Microsoft Foundry die Sitzungen, Unterhaltungen und gespeicherten Daten privat hält und wie Sie diese Isolation auf die Benutzer Ihrer eigenen Anwendung erweitern. Am Ende können Sie einen Agent aufrufen und bestätigen, dass ein Anrufer die Sitzungen, Unterhaltungen oder gespeicherten Daten eines anderen Anrufers nicht sehen kann.

Voraussetzungen

  • Ein installierter gehosteter Agent. Informationen zum Bereitstellen finden Sie unter Bereitstellen eines gehosteten Agents.
  • Die Azure Developer CLI Foundry-Erweiterungen, für die CLI-Schritte. Weitere Informationen finden Sie unter Installieren der Azure Developer CLI Foundry-Erweiterungen.
  • Eine authentifizierte Sitzung. Führen Sie azd auth login aus, oder melden Sie sich mit der Microsoft Entra-Anmeldeinformation an, die Ihr SDK oder REST-Client verwendet.
  • Die Foundry-User-Rolle im Projekt.

Wichtig

Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

Die Isolierung pro Benutzer verstehen

Die Plattform identifiziert jeden Anrufer anhand seines Microsoft Entra-Tokens und hält die zugehörigen Daten auf diese Identität beschränkt, obwohl alle Anrufer über einen gemeinsam genutzten Endpunkt denselben Agenten erreichen. Für alle Benutzenden bleibt Folgendes isoliert:

  • Gespräche. Der Unterhaltungsverlauf jedes Benutzers – nachrichten, Toolaufrufe und Antworten, die sie über das Antwortprotokoll threaden – ist für diesen Benutzer privat. Ein Benutzer kann die Unterhaltungen eines anderen Benutzers nicht lesen oder auflisten.
  • Sitzungen. Jeder Anrufer erhält standardmäßig eine eigene Sitzung, sodass die Sitzungen, die ein Benutzer auflisten und verwalten kann, keine Sitzungen eines anderen Benutzers enthalten.
  • Gespeicherte Daten. Daten, die Ihr Agent für einen Benutzer speichert, ist auf diesen Benutzer festgelegt, sodass er nicht an einen anderen Benutzer zurückgegeben wird.

Stellen Sie sich dies als ein Agent vor, der viele private Arbeitsbereiche bedient. Jede Sitzung erhält außerdem ein privates $HOME Dateisystem in einer eigenen Sandbox, standardmäßig isoliert, da jeder Benutzer eine eigene Sitzung erhält. Wenn Sie stattdessen mehrere Benutzer in einer Sitzung platzieren, wird diese Sandbox freigegeben – siehe Multiplex mehrere Benutzer in einer gehosteten Agentsitzung. Weitere Informationen zum Sitzungsmodell finden Sie unter Gehostete Agents im Foundry Agent Service.

Zu den typischen Szenarien gehören:

  • Benutzerspezifischer Chat. Jeder angemeldete Kunde erhält seinen eigenen Unterhaltungsverlauf, Sitzungen und gespeicherte Daten.
  • Mehrmandantenfähige Apps. Die Benutzer jedes Mandanten sind von den Benutzern jedes anderen Mandanten isoliert.

Sie erhalten diese Isolation standardmäßig. Die folgenden Abschnitte zeigen zunächst den Standardpfad und anschließend, wie er auf Benutzer erweitert wird, die Sie selbst authentifizieren.

Aufrufen eines Agents mit automatischer Isolierung

Rufen Sie den Agent unter der angemeldeten Identität auf. Die Plattform erstellt eine für diese Identität geltende Sitzung und gibt ihr agent_session_id zurück.

azd ai agent invoke "Summarize the latest support tickets"

Die Sitzung gehört zur Identität von azd auth login. Ein anderer angemeldeter Benutzer, der denselben Befehl ausführt, erhält eine separate private Sitzung.

Richten Sie die freigegebenen Variablen ein, die von den REST-Beispielen verwendet werden:

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

Das Microsoft Entra-Token für die Anforderung identifiziert den Aufrufer. Die Antwortnutzlast enthält die agent_session_id, die von der Plattform erstellt und auf diese Identität beschränkt wurde.

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

Der OpenAI-Client authentifiziert sich mit den Microsoft Entra Anmeldeinformationen des Aufrufers, sodass die Sitzung auf diese Identität festgelegt ist.

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}`);

Der OpenAI-Client authentifiziert sich mit den Microsoft Entra Anmeldeinformationen des Aufrufers, sodass die Sitzung auf diese Identität festgelegt ist.

Isolieren Sie Sitzungen für Ihre eigenen Benutzer

Wenn Ihre Anwendung seine eigenen Endbenutzer authentifiziert – z. B. über Google, GitHub oder einen benutzerdefinierten Identitätsanbieter – kann ein vertrauenswürdiger Dienst foundry mitteilen, zu welchem Endbenutzer eine Anforderung gehört, sodass die Plattform Sitzungen pro Endbenutzer statt pro Anrufdienst isoliert.

Der Dienst sendet den stabilen Bezeichner des Endbenutzers im x-ms-user-identity Header. Die Plattform behandelt den Wert als intransparente Zeichenfolge und ordnet die Sitzung diesem Wert zu. Der Wert muss 1 bis 256 Zeichen sein und nur Buchstaben, Ziffern und die Zeichen . _ : - @enthalten. Andere Werte werden abgelehnt.

Um x-ms-user-identity zu übergeben, muss die aufrufende Identität über die Berechtigung Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action für den Agent verfügen. Diese Berechtigung ist nicht in einer integrierten Rolle enthalten. Sie wurde zuvor von der Microsoft.CognitiveServices/* Datenaktion abgedeckt, aber diese Aktion gewährt sie nicht mehr. Erteilen Sie sie explizit, indem Sie eine benutzerdefinierte Rolle erstellen, die die Datenaktion enthält, und diese Rolle der Identität Ihres mittleren Diensts zuweisen. Ein Anrufer ohne dies erhält eine 403. Informationen zu den benutzerdefinierten Rollendefinitions- und Zuweisungsbefehlen finden Sie unter Delegieren der Endbenutzeridentität.

Wenn ein Dienst diese Berechtigung besitzt, den Header jedoch bei einer Anfrage nicht mitsendet, beschränkt die Plattform diese Sitzung auf die eigene Identität des Dienstes statt auf die eines Endbenutzers. Ihr Dienst kann delegierte und nicht delegierte Aufrufe mischen, aber nur Anfragen, die x-ms-user-identity enthalten, werden für jeden Endbenutzer getrennt isoliert.

Warnung

Innerhalb der Delegation schirmt die Plattform einen delegierten Endbenutzer nicht von einem anderen ab. Sie erzwingt eine feste Grenze nur zwischen delegierten und nicht delegierten Anrufern . Dadurch kann jeder Ihrer delegierten Benutzenden in eine von Ihrer App erstellte Sitzung gelangen. Weisen Sie jedem Benutzer seine eigene Sitzungs-ID zu; Wenn Sie zwei Benutzer an dieselbe Sitzung weiterleiten, können sie die Daten der anderen sehen. Um eine Sitzung gezielt zu teilen, siehe Mehrere Benutzer in einer gehosteten Agentensitzung zusammenführen.

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

Ersetzen Sie <stable-end-user-id> durch den Bezeichner, den Ihr Dienst dem angemeldeten Endbenutzer zuweist, z. B. eine mandantenbezogene Benutzer-ID.

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

Ersetzen Sie <stable-end-user-id> durch den Bezeichner, den Ihr Dienst dem angemeldeten Endbenutzer zuweist. Die Sitzung ist auf diesen Endbenutzer und nicht auf den aufrufenden Dienst begrenzt.

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);

Ersetzen Sie <stable-end-user-id> durch den Bezeichner, den Ihr Dienst dem angemeldeten Endbenutzer zuweist. Die Sitzung ist auf diesen Endbenutzer und nicht auf den aufrufenden Dienst begrenzt.

Die Azure Developer CLI ruft den Agent als eigene angemeldete Identität auf, sodass keine delegierte Endbenutzeridentität übergeben wird. Verwenden Sie den REST- oder SDK-Pfad Ihres Dienstes, um x-ms-user-identity zu senden.

Sichern der Endbenutzeridentität

Wenn Sie delegierte Isolation verwenden, ist Ihr Dienst die Vertrauensgrenze. Wählen Sie Bezeichner aus, die pro Benutzer stabil, eindeutig und schwer zu erraten sind. Verwenden Sie denselben Wert für denselben Benutzer wieder, damit ihre Sitzungen ordnungsgemäß fortgesetzt werden.

Wichtig

Leiten Sie den x-ms-user-identity Wert von einer authentifizierten serverseitigen Identität ab – niemals von einem Wert, den der Browser oder client direkt bereitstellt. Andernfalls kann ein Aufrufer die Kopfzeile auf den Bezeichner eines anderen Benutzers festlegen und die Daten dieses Benutzers lesen. Jeder Dienst mit der Delegierungsberechtigung kann im Auftrag eines beliebigen Endbenutzers handeln, gewähren Sie diese daher nur Diensten, denen Sie vertrauen.

Überprüfen der Isolation

Vergewissern Sie sich, dass zwei Identitäten zwei separate Sitzungen zugewiesen werden:

  1. Rufen Sie den Agent unter einer Identität auf, und notieren Sie sich die zurückgegebene agent_session_id.
  2. Rufen Sie den Agent unter einer zweiten Identität auf – einer anderen angemeldeten Benutzerin bzw. einem anderen angemeldeten Benutzer oder einem anderen x-ms-user-identity-Wert – und notieren Sie den zugehörigen agent_session_id.
  3. Vergewissern Sie sich, dass die beiden IDs unterschiedlich sind und dass beim Auflisten der Sitzungen für jede Identität jeweils nur die Sitzungen dieser Identität zurückgegeben werden.

Um die durchgängige Isolation zu sehen, stellen Sie das Beispiel des Notizagenten bereit, das Notizen pro Sitzung unter $HOME speichert: Die Notizen jeder Identität landen in einer separaten Sitzungsdatei, die nur von dieser Identität über die Session Files API aufgelistet oder heruntergeladen werden kann.

Anzeigen von Sitzungen für alle Benutzer

Standardmäßig sieht jeder Anrufer nur eigene Sitzungen. Ein Administrator oder eine Automatisierung, der die Rolle " Foundry User " im Projekt enthält, kann jede Sitzung auf dem Agent auflisten und verwalten, unabhängig davon, welche Identität sie erstellt hat. Informationen zum Verwalten von Sitzungen finden Sie unter "Verwalten von gehosteten Agentsitzungen".

Isolationsschlüssel für Containerprotokoll 1.0.0 (veraltet)

Agents mit Containerprotokollversion 1.0.0 verwenden das frühere Modell mit Isolationsschlüssel, bei dem der Aufrufer einen Isolationsschlüssel bereitstellt, um Sitzungen abzugrenzen, anstatt dass die Plattform die Identität aus dem Microsoft Entra-Token ableitet. Dieses Modell - und protokoll 1.0.0 selbst - ist veraltet. Agenten am Protokoll 1.0.0 arbeiten bis zum 31. Juli 2026 weiterhin; danach blockiert die Plattform Anforderungen an Agents, die weiterhin auf Protokoll 1.0.0 ausgeführt werden.

Aktualisieren Sie auf Protokoll 2.0.0, um die automatische Isolation pro Benutzer zu erhalten, die weiter oben in diesem Artikel beschrieben wird. Protokoll 2.0.0 erfordert das AgentServer SDK, das es unterstützt – azure-ai-agentserver-core 2.0.0b7 oder höher für Python oder Azure.AI.AgentServer.Core 1.0.0-beta.26 oder höher für .NET. Frühere Versionen verwenden Protokoll 1.0.0; aktualisieren Sie sie als Teil des Upgrades.

Fehler bei der Isolierung beheben

Symptom Wahrscheinliche Ursache Was Sie testen sollten
403 oder session_not_accessible beim Zugriff auf eine Sitzung Die Sitzung gehört zu einer anderen Identität. Verwenden Sie dieselbe Identität, die die Sitzung erstellt hat, oder halten Sie die Rolle "Foundry User" gedrückt, um die Sitzungen anderer Identitäten anzuzeigen.
403 bei einer Anforderung, die x-ms-user-identity festlegt Der Aufrufer hat nicht die Berechtigung UserIdentityImpersonation, die nicht mehr durch vordefinierte Rollen gewährt wird. Erstellen Sie eine benutzerdefinierte Rolle, die die Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action Datenaktion enthält, und weisen Sie sie dem aufrufenden Dienst zu.
Lokale Ausführungen isolieren keine Sitzungen. Lokale Läufe setzen keine Isolation durch. Testen Sie die Isolation mit einem bereitgestellten Agent. Der lokale Modus (--local, azd ai agent run) zielt auf einen einzelnen Benutzer ab.

Verwandte Inhalte

  • Last updated on