Isoler les sessions d’agent hébergées par utilisateur

Un seul agent hébergé sert de nombreux utilisateurs à partir d’un point de terminaison. Cet article vous montre comment Microsoft Foundry conserve les sessions, conversations et données stockées privées de chaque utilisateur, et comment étendre cette isolation aux utilisateurs de votre propre application. À la fin, vous pouvez appeler un agent et confirmer qu’un appelant ne peut pas voir les sessions, conversations ou données stockées d’un autre appelant.

Prerequisites

• Un agent hébergé déployé. Pour en déployer un, consultez Déployer un agent hébergé.
• Les extensions Azure Developer CLI Foundry, pour les étapes de l’interface CLI. Consultez Installez les extensions Foundry de l’interface de ligne de commande Azure Developer.
• Une session authentifiée. Exécutez azd auth login, ou connectez-vous avec les informations d’identification Entra de Microsoft qu’utilise votre SDK ou votre client REST.
• Le rôle Foundry User sur le projet.

Comprendre l’isolation par utilisateur

La plateforme identifie chaque appelant à partir de son jeton Microsoft Entra et garde ses données confidentielles et propres à cette identité, bien que tous les appelants accèdent au même agent via un point de terminaison unique partagé. Pour chaque utilisateur, les éléments suivants restent isolés :

• Conversations. L’historique des conversations de chaque utilisateur ( les messages, les appels d’outils et les réponses qu’ils filent via le protocole Réponses) est privé pour cet utilisateur. Un utilisateur ne peut pas lire ou répertorier les conversations d’un autre utilisateur.
• Sessions Chaque appelant obtient sa propre session par défaut, de sorte que les sessions qu’un utilisateur peut répertorier et gérer n’incluent pas les sessions d’un autre utilisateur.
• Données stockées. Les données que votre agent stocke pour un utilisateur sont limités à cet utilisateur, de sorte qu’il n’est pas retourné à un autre utilisateur.

Considérez-le comme un agent servant de nombreux espaces de travail privés. Chaque session obtient également un système de fichiers privé $HOME dans son propre bac à sable, isolé par défaut, car chaque utilisateur obtient sa propre session. Si vous placez plutôt plusieurs utilisateurs dans une session, ce bac à sable est partagé : consultez Multiplex plusieurs utilisateurs dans une session d’agent hébergée. Pour plus d’informations sur le modèle de session, consultez Agents hébergés dans Foundry Agent Service.

Les scénarios classiques sont les suivants :

• Conversation individuelle par utilisateur. Chaque client connecté obtient son propre historique de conversation, sessions et données stockées.
• Applications multi-locataires. Les utilisateurs de chaque locataire sont isolés des utilisateurs de chaque autre locataire.

Vous obtenez cette isolation par défaut. Les sections suivantes montrent le chemin d’accès par défaut, puis comment l’étendre aux utilisateurs que vous vous authentifiez vous-même.

Appeler un agent avec isolation automatique

Invoquez l’agent en tant qu’identité connectée. La plateforme crée une session associée à cette identité et renvoie son agent_session_id.

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

Isoler les sessions pour vos propres utilisateurs

Si votre application authentifie elle-même ses propres utilisateurs finaux, par exemple via Google, GitHub ou un fournisseur d’identité personnalisé, un service de confiance peut indiquer à Foundry à quel utilisateur final appartient une requête, afin que la plateforme isole les sessions par utilisateur final plutôt que par service appelant.

Le service envoie l’identificateur stable de l’utilisateur final dans l’en-tête x-ms-user-identity . La plateforme traite la valeur comme une chaîne de caractères opaque et associe la session à celle-ci. La valeur doit être de 1 à 256 caractères et contenir uniquement des lettres, des chiffres et des caractères . _ : - @; d’autres valeurs sont rejetées.

Pour transmettre x-ms-user-identity, l’identité appelante doit disposer de l’autorisation Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action sur l’agent. Cette autorisation n’est incluse dans aucun rôle intégré. Elle était auparavant incluse dans l’action de données Microsoft.CognitiveServices/*, mais cette action n’y donne plus droit. Accordez cette autorisation de manière explicite en créant un rôle personnalisé qui inclut l’autorisation de données, puis en attribuant ce rôle à l’identité de votre service intermédiaire. Un appelant sans cela reçoit un 403. Pour connaître les commandes de définition et d’attribution de rôle personnalisées, consultez Déléguer l’identité de l’utilisateur final.

Si un service contient cette autorisation, mais n’envoie pas l’en-tête sur une demande, la plateforme étend cette session à l’identité du service au lieu d’un utilisateur final. Votre service peut combiner des appels délégués et non délégués, mais seules les requêtes qui incluent x-ms-user-identity sont isolées par utilisateur final.

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

Sécuriser l’identité de l’utilisateur final

Lorsque vous utilisez l’isolation déléguée, votre service constitue la frontière de confiance. Choisissez des identificateurs stables par utilisateur, uniques et difficiles à deviner. Réutilisez la même valeur pour le même utilisateur afin que leurs sessions reprendnt correctement.

Vérifier l’isolation

Vérifiez que deux identités disposent de deux sessions distinctes :

1. Appelez l’agent en tant qu’identité et notez le retour agent_session_id.
2. Appelez l’agent en tant que deuxième identité - un utilisateur connecté différent ou une autre x-ms-user-identity valeur - et notez son agent_session_id.
3. Vérifiez que les deux identifiants sont différents et que, pour chaque identité, la liste des sessions ne renvoie que les sessions de cette identité.

Pour voir l’isolation de bout en bout, déployez l’exemple d’agent de prise de notes, qui stocke les notes par session sous $HOME: les notes de chaque identité atterrissent dans un fichier de session distinct que seule cette identité peut répertorier ou télécharger via l’API Fichiers de session.

Afficher les sessions de tous les utilisateurs

Par défaut, chaque appelant voit uniquement ses propres sessions. Un administrateur ou une automatisation qui contient le rôle Utilisateur Foundry sur le projet peut répertorier et gérer chaque session sur l’agent, quelle que soit l’identité qui l’a créée. Pour gérer les sessions, consultez Gérer les sessions d’agent hébergées.

Clés d’isolation du protocole de conteneur 1.0.0 (obsolète)

Les agents utilisant la version 1.0.0 du protocole de conteneur utilisent l’ancien modèle de clé d’isolation, dans lequel l’appelant fournit une clé d’isolation pour définir la portée des sessions, au lieu que la plateforme dérive l’identité du jeton Microsoft Entra. Ce modèle - et le protocole 1.0.0 lui-même - est déconseillé. Les agents sur le protocole 1.0.0 continuent de fonctionner jusqu’au 31 juillet 2026 ; par la suite, la plateforme bloque les demandes adressées aux agents qui s’exécutent toujours sur le protocole 1.0.0.

Effectuez une mise à niveau vers le protocole 2.0.0 pour obtenir l’isolation automatique par utilisateur décrite plus haut dans cet article. Le protocole 2.0.0 nécessite le SDK AgentServer qui le prend en charge - azure-ai-agentserver-core 2.0.0b7 ou version ultérieure pour Python, ou Azure.AI.AgentServer.Core 1.0.0-beta.26 ou version ultérieure pour .NET. Les versions antérieures utilisent le protocole 1.0.0 ; les mettre à jour dans le cadre de la mise à niveau.

• Si vous restez sur le protocole 1.0.0 pour l’instant, consultez Passer des clés d’isolation à un agent hébergé pour savoir comment fonctionnent les clés d’isolation.
• Pour effectuer la mise à niveau, consultez Migrer les agents hébergés.

Résoudre les problèmes d’isolation

Contenu connexe

• Gérez les sessions d’agent hébergées pour répertorier, inspecter et supprimer des sessions, notamment entre les utilisateurs.
• Multiplexer plusieurs utilisateurs dans une session d’agent hébergée lorsque plusieurs utilisateurs partagent intentionnellement une session.
• Concepts d’identité de l’agent dans Microsoft Foundry pour comprendre comment fonctionnent les identités des agents et des utilisateurs.
• Appelez un agent hébergé avec l’interface CLI Azure Développeur pour chaque variante et option d’appel.
• Exemple d’agent de prise de notes pour un agent exécutable qui stocke les données appartenant à l’utilisateur par session (Python et C#).