Aislar las sesiones del agente hospedado por usuario

Un único agente hospedado sirve a muchos usuarios desde un punto de conexión. En este artículo se muestra cómo Microsoft Foundry mantiene privadas las sesiones, conversaciones y datos almacenados de cada usuario y cómo ampliar ese aislamiento a los usuarios de su propia aplicación. Al final, podrá invocar un agente y confirmar que un usuario que llama no puede ver las sesiones, las conversaciones ni los datos almacenados de otro usuario.

Prerrequisitos

• Un agente hospedado implementado. Para implementar uno, consulte Implementación de un agente hospedado.
• Las extensiones de Azure Developer CLI Foundry para los pasos de la CLI. Consulte Instalar las extensiones de Foundry para Azure Developer CLI.
• Una sesión autenticada. Ejecute azd auth login, o inicie sesión con la credencial de Microsoft Entra que utiliza su SDK o cliente REST.
• El rol de usuario de Foundry en el proyecto.

Comprender el aislamiento por usuario

La plataforma identifica a cada usuario por su token de Microsoft Entra y mantiene sus datos privados y asociados únicamente a esa identidad, aunque todos accedan al mismo agente a través de un único punto de conexión compartido. Para cada usuario, los siguientes permanecen aislados:

• Conversaciones. El historial de conversación de cada usuario —los mensajes, las invocaciones de herramientas y las respuestas que encadenan a través del protocolo Responses— es privado para ese usuario. Un usuario no puede leer ni enumerar las conversaciones de otro usuario.
• Son sesiones. Cada llamador obtiene su propia sesión de forma predeterminada, por lo que las sesiones que un usuario puede enumerar y administrar no incluyen las sesiones de otro usuario.
• Datos almacenados. Los datos que almacena el agente para un usuario se limitan a ese usuario, por lo que no se devuelven a otro usuario.

Piense en él como un agente que atiende muchas áreas de trabajo privadas. Cada sesión también dispone de un sistema de archivos privado $HOME en su propio entorno aislado, que está aislado de forma predeterminada porque cada usuario tiene su propia sesión. Si en su lugar sitúa a varios usuarios en una sola sesión, ese entorno aislado se comparte; consulte Multiplexar varios usuarios en una sesión de agente hospedada. Para obtener más información sobre el modelo de sesión, consulte Agentes hospedados en Foundry Agent Service.

Entre los escenarios típicos se incluyen:

• Chat por usuario. Cada cliente que ha iniciado sesión obtiene su propio historial de conversaciones, sesiones y datos almacenados.
• Aplicaciones multiinquilino. Los usuarios de cada inquilino están aislados de los usuarios de cada otro inquilino.

Este aislamiento se obtiene de forma predeterminada. En las secciones siguientes se muestra la ruta de acceso predeterminada y, a continuación, cómo ampliarla a los usuarios que se autentican usted mismo.

Invocar un agente con aislamiento automático

Invoque al agente como la identidad con sesión iniciada. La plataforma crea una sesión asociada a esa identidad y devuelve su 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}`);

Aislar las sesiones de sus propios usuarios

Si la aplicación autentica a sus propios usuarios finales (por ejemplo, a través de Google, GitHub o un proveedor de identidades personalizado), un servicio de confianza puede indicar a Foundry a qué usuario final pertenece una solicitud, por lo que la plataforma aísla las sesiones por usuario final en lugar de por servicio de llamada.

El servicio envía el identificador estable del usuario final en el x-ms-user-identity encabezado . La plataforma trata el valor como una cadena opaca y limita la sesión a ella. El valor debe tener entre 1 y 256 caracteres y contener solo letras, dígitos y los caracteres . _ : - @; se rechazan otros valores.

Para aprobar x-ms-user-identity, la identidad que realiza la llamada debe tener el permiso Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action sobre el agente. Este permiso no se incluye en ningún rol integrado. Anteriormente lo incluía la acción de datos Microsoft.CognitiveServices/*, pero esa acción ya no lo concede. Concédalo explícitamente mediante la creación de un rol personalizado que incluya la acción de datos y la asignación de ese rol a la identidad del servicio de nivel intermedio. Quien llama, si no lo tiene, recibe un 403. Para ver los comandos de asignación y definición de roles personalizados, consulte Delegación de la identidad del usuario final.

Si un servicio contiene este permiso, pero no envía el encabezado a una solicitud, la plataforma limita esa sesión a la propia identidad del servicio en lugar de a un usuario final. El servicio puede mezclar llamadas delegadas y no delegadas, pero solo las solicitudes que incluyen x-ms-user-identity están aisladas por usuario 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);

Protección de la identidad del usuario final

Cuando usas el aislamiento delegado, tu servicio es el límite de confianza. Elija identificadores estables por usuario, únicos y difíciles de adivinar. Vuelva a usar el mismo valor para el mismo usuario para que sus sesiones se reanuden correctamente.

Comprobación del aislamiento

Confirme que dos identidades generan dos sesiones distintas:

1. Invoque al agente con una identidad y anote el valor devuelto agent_session_id.
2. Invoque al agente como una segunda identidad: la de otro usuario que haya iniciado sesión, o con un valor de x-ms-user-identity diferente, y anote su agent_session_id.
3. Confirme que los dos ID difieren y que, al listar las sesiones como cada identidad, solo se devuelven las sesiones de esa identidad.

Para ver el aislamiento de un extremo a otro, implemente el ejemplo del agente de toma de notas, que almacena notas por sesión en $HOME: las notas de cada identidad llegan a un archivo de sesión independiente que solo esa identidad puede enumerar o descargar a través de la API de archivos de sesión.

Visualización de sesiones entre usuarios

De forma predeterminada, cada llamador solo ve sus propias sesiones. Un administrador o automatización que contiene el rol Usuario de Foundry en el proyecto puede enumerar y administrar todas las sesiones del agente, independientemente de la identidad que la creó. Para administrar sesiones, consulte Administración de sesiones del agente hospedado.

Claves de aislamiento en el protocolo de contenedor 1.0.0 (en desuso)

Los agentes que usan la versión 1.0.0 del protocolo de contenedor utilizan el modelo anterior de clave de aislamiento, en el que la entidad que realiza la llamada proporciona una clave de aislamiento para delimitar el ámbito de las sesiones, en lugar de que la plataforma derive la identidad a partir del token de Microsoft Entra. Este modelo ( y el protocolo 1.0.0 en sí) están en desuso. Los agentes del protocolo 1.0.0 continúan funcionando hasta el 31 de julio de 2026; después, la plataforma bloquea las solicitudes a los agentes que todavía se ejecutan en el protocolo 1.0.0.

Actualice al protocolo 2.0.0 para obtener el aislamiento automático por usuario descrito anteriormente en este artículo. Protocol 2.0.0 requiere el SDK de AgentServer que lo admita: azure-ai-agentserver-core 2.0.0b7 o posterior para Python, o Azure.AI.AgentServer.Core 1.0.0-beta.26 o posterior para .NET. Las versiones anteriores usan el protocolo 1.0.0; actualícelos como parte de la actualización.

• Si permanece en el protocolo 1.0.0 por ahora, consulte Pasar claves de aislamiento a un agente hospedado para saber cómo funcionan las claves de aislamiento.
• Para actualizar, consulte Migración de agentes hospedados.

Solucionar problemas de aislamiento

Contenido relacionado

• Administre las sesiones del agente hospedado para enumerar, inspeccionar y eliminar sesiones, incluidas entre los usuarios.
• Multiplexar varios usuarios en una misma sesión de agente hospedado cuando varios usuarios comparten intencionadamente la misma sesión.
• Conceptos de identidad del agente en Microsoft Foundry para comprender cómo funcionan las identidades de agente y usuario.
• Invoque un agente hospedado con la CLI de Azure Developer para cada variante y opción de invocación.
• Ejemplo de agente de toma de notas para un agente ejecutable que almacena datos propiedad del usuario por sesión (Python y C#).