Isolar as sessões do agente alojado por utilizador

Um único agente alojado serve muitos utilizadores a partir de um único endpoint. Este artigo mostra-lhe como a Microsoft Foundry mantém privadas as sessões, conversas e dados armazenados de cada utilizador, e como estender esse isolamento aos utilizadores da sua própria aplicação. No final, pode invocar um agente e confirmar que um dos chamadores não consegue ver as sessões, conversas ou dados armazenados de outro.

Pré-requisitos

• Um agente alojado destacado. Para implementar um, veja Implementar um agente alojado.
• As extensões do Azure Developer CLI Foundry, para as etapas da CLI. Consulte Instalar as extensões do Azure Developer CLI Foundry.
• Uma sessão autenticada. Execute azd auth login, ou inicie sessão com a credencial Microsoft Entra que o seu SDK ou cliente REST utiliza.
• A função de utilizador do Foundry no projeto.

Compreenda o isolamento por utilizador

A plataforma identifica cada chamador a partir do seu token Microsoft Entra e mantém os seus dados privados para essa identidade, mesmo que todos os chamadores contactem o mesmo agente através de um ponto final partilhado. Para cada utilizador, os seguintes permanecem isolados:

• Conversas. O histórico de conversas de cada utilizador – as mensagens, chamadas de ferramentas e respostas que transmitem através do protocolo Respostas – é privado para esse utilizador. Um utilizador não consegue ler ou listar as conversas de outro utilizador.
• Sessões. Cada chamador tem a sua própria sessão por defeito, por isso as sessões que um utilizador pode listar e gerir não incluem as sessões de outro utilizador.
• Dados armazenados. Os dados que o seu agente armazena para um utilizador são atribuídos a esse utilizador, por isso não são devolvidos a outro utilizador.

Imagine-o como um agente que serve muitos espaços de trabalho privados. Cada sessão também recebe um sistema de ficheiros privado $HOME no seu próprio ambiente isolado, isolado por predefinição, uma vez que cada utilizador tem a sua própria sessão. Se, em vez disso, colocar vários utilizadores na mesma sessão, essa sandbox é partilhada - consulte Multiplexar vários utilizadores numa sessão de agente alojado. Para saber mais sobre o modelo de sessão, consulte Agentes alojados no Foundry Agent Service.

Cenários típicos incluem:

• Chat por utilizador. Cada cliente com sessão iniciada tem o seu próprio histórico de conversas, sessões e dados armazenados.
• Aplicações multicliente. Os utilizadores de cada inquilino estão isolados dos utilizadores de todos os outros inquilinos.

Tens este isolamento por defeito. As secções seguintes mostram o percurso predefinido e, em seguida, como o alargar aos utilizadores que autentica diretamente.

Invocar um agente com isolamento automático

Invocar o agente como identidade assinada. A plataforma cria uma sessão associada a essa identidade e devolve o respetivo 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}`);

Isolar sessões para os seus próprios utilizadores

Se a sua aplicação autenticar os seus próprios utilizadores finais – por exemplo, através do Google, GitHub ou um fornecedor de identidade personalizada – um serviço de confiança pode indicar à Foundry a que utilizador final pertence um pedido, de modo que a plataforma isola sessões por utilizador final em vez de por serviço que chama.

O serviço envia o identificador estável do utilizador final no x-ms-user-identity cabeçalho. A plataforma trata o valor como uma string opaca e restringe o âmbito da sessão a esse valor. O valor deve ser de 1 a 256 caracteres e conter apenas letras, dígitos e os caracteres . _ : - @; outros valores são rejeitados.

Para transmitir x-ms-user-identity, a identidade chamadora tem de possuir a permissão Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action no agente. Esta permissão não está incluída em nenhuma função incorporada. Era anteriormente abrangido pela ação de dados Microsoft.CognitiveServices/*, mas essa ação já não a atribui. Conceda essa permissão explicitamente, criando uma função personalizada que inclua a ação de dados e atribuindo essa função à identidade do seu serviço de camada intermédia. Um invocador sem isso recebe um 403. Para os comandos personalizados de definição e atribuição de papéis, veja Delegar a identidade do utilizador final.

Se um serviço detém esta permissão mas não envia o cabeçalho num pedido, a plataforma atribui essa sessão à identidade do serviço em vez de ao utilizador final. O seu serviço pode misturar chamadas delegadas e não delegadas, mas apenas os pedidos que incluem x-ms-user-identity são isolados por utilizador 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);

Proteger a identidade do utilizador final

Quando usa isolamento delegado, o seu serviço é o limite de confiança. Escolha identificadores que sejam estáveis por utilizador, únicos e difíceis de adivinhar. Reutilize o mesmo valor para o mesmo utilizador para que as sessões retomem corretamente.

Verificar isolamento

Confirma que duas identidades têm duas sessões separadas:

1. Invoque o agente com uma identidade e anote o valor devolvido agent_session_id.
2. Chame o agente como uma segunda identidade — um utilizador com sessão iniciada diferente ou um valor de x-ms-user-identity diferente — e tome nota do respetivo agent_session_id.
3. Confirme que os dois IDs diferem e que listar sessões como cada identidade devolve apenas as sessões dessa identidade.

Para ver isolamento de ponta a ponta, implemente o sample do agente de tomada de notas, que armazena notas por sessão em $HOME: as notas de cada identidade ficam num ficheiro de sessão separado que só essa identidade pode listar ou descarregar através da API de Ficheiros de Sessão.

Ver sessões entre utilizadores

Por defeito, cada chamador vê apenas as suas próprias sessões. Um administrador ou uma automação com a função Foundry User no projeto pode listar e gerir todas as sessões do agente, independentemente da identidade que a tenha criado. Para gerir sessões, consulte Gerir sessões de agentes alojados.

Chaves de isolamento do protocolo de contentor 1.0.0 (obsoleto)

Os agentes com a versão 1.0.0 do protocolo de contentor utilizam o modelo anterior de chave de isolamento, no qual o autor da chamada fornece uma chave de isolamento para delimitar o âmbito das sessões, em vez de a plataforma derivar a identidade a partir do token Microsoft Entra. Este modelo – e o próprio protocolo 1.0.0 – está obsoleto. Os agentes no protocolo 1.0.0 continuam a trabalhar até 31 de julho de 2026; Depois, a plataforma bloqueia pedidos para agentes que ainda funcionam no protocolo 1.0.0.

Atualize para o protocolo 2.0.0 para obter o isolamento automático por utilizador descrito anteriormente neste artigo. O Protocolo 2.0.0 requer o SDK AgentServer que o suporta - azure-ai-agentserver-core 2.0.0b7 ou posterior para Python, ou Azure.AI.AgentServer.Core 1.0.0-beta.26 ou posterior para .NET. Versões anteriores utilizam o protocolo 1.0.0; Atualize-os como parte da atualização.

• Se continuar no protocolo 1.0.0 por agora, veja Passar chaves de isolamento a um agente hospedado para ver como funcionam as chaves de isolamento.
• Para atualizar, veja Migrar agentes hospedados.

Isolamento de resolução de problemas

Conteúdo relacionado

• Gerir sessões de agentes alojadas para listar, inspecionar e eliminar sessões, incluindo entre utilizadores.
• Multiplexe múltiplos utilizadores numa sessão de agente alojada quando vários utilizadores partilham intencionalmente uma sessão.
• Conceitos de identidade de agente no Microsoft Foundry para compreender como funcionam as identidades de agente e utilizador.
• Invoque um agente hospedado com o Azure Developer CLI para cada variante e opção de invocação.
• Amostra de agente de tomada de notas para um agente executável que armazena dados de propriedade do utilizador por sessão (Python e C#).