Isolate hosted agent sessions per user

Keep each user’s Microsoft Foundry hosted agent sessions, conversations, and stored data private, and extend isolation to your own application’s users.

A single hosted agent serves many users from one endpoint. This article shows you how Microsoft Foundry keeps each user’s sessions, conversations, and stored data private, and how to extend that isolation to the users of your own application. By the end, you can invoke an agent and confirm that one caller can’t see another caller’s sessions, conversations, or stored data.

Prerequisites

• A deployed hosted agent. To deploy one, see Deploy a hosted agent.
• The Azure Developer CLI Foundry extensions, for the CLI steps. See Install the Azure Developer CLI Foundry extensions.
• An authenticated session. Run azd auth login, or sign in with the Microsoft Entra credential your SDK or REST client uses.
• The Foundry User role on the project.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Understand per-user isolation

The platform identifies each caller from their Microsoft Entra token and keeps their data private to that identity, even though every caller reaches the same agent through one shared endpoint. For each user, the following stay isolated:

• Conversations. Each user’s conversation history - the messages, tool calls, and responses they thread through the Responses protocol - is private to that user. One user can’t read or list another user’s conversations.
• Sessions. Each caller gets their own session by default, so the sessions one user can list and manage don’t include another user’s sessions.
• Stored data. Data your agent stores for a user is scoped to that user, so it isn’t returned to a different user.

Think of it as one agent serving many private workspaces. Each session also gets a private $HOME filesystem in its own sandbox, isolated by default because each user gets their own session. If you instead place several users in one session, that sandbox is shared - see Multiplex multiple users in one hosted agent session. For more about the session model, see Hosted agents in Foundry Agent Service.

Typical scenarios include:

• Per-user chat. Each signed-in customer gets their own conversation history, sessions, and stored data.
• Multi-tenant apps. Each tenant’s users are isolated from every other tenant’s users.

You get this isolation by default. The following sections show the default path, then how to extend it to users that you authenticate yourself.

Invoke an agent with automatic isolation

Invoke the agent as the signed-in identity. The platform creates a session scoped to that identity and returns its agent_session_id.

Isolate sessions for your own users

If your application authenticates its own end users - for example, through Google, GitHub, or a custom identity provider - a trusted service can tell Foundry which end user a request belongs to, so the platform isolates sessions per end user instead of per calling service.

The service sends the end user’s stable identifier in the x-ms-user-identity header. The platform treats the value as an opaque string and scopes the session to it. The value must be 1–256 characters and contain only letters, digits, and the characters . _ : - @; other values are rejected.

To pass x-ms-user-identity, the calling identity must hold the Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action permission on the agent. This permission is not included in any built-in role. It was previously covered by the Microsoft.CognitiveServices/* data action, but that action no longer grants it. Grant it explicitly by creating a custom role that includes the data action and assigning that role to your middle-tier service’s identity. A caller without it receives a 403. For the custom role definition and assignment commands, see Delegate the end-user identity.

If a service holds this permission but doesn’t send the header on a request, the platform scopes that session to the service’s own identity instead of an end user. Your service can mix delegated and non-delegated calls, but only requests that include x-ms-user-identity are isolated per end user.

Within delegation, the platform doesn’t fence one delegated end user from another. It enforces a hard boundary only between delegated and non-delegated callers - it lets any of your delegated users into a session your app created. Give each user their own session ID; if you route two users to the same session, they can see each other’s data. To deliberately share one session, see Multiplex multiple users in one hosted agent session.

Secure the end-user identity

When you use delegated isolation, your service is the trust boundary. Choose identifiers that are stable per user, unique, and hard to guess. Reuse the same value for the same user so their sessions resume correctly.

Derive the x-ms-user-identity value from an authenticated, server-side identity - never from a value the browser or client supplies directly. Otherwise, a caller can set the header to another user’s identifier and read that user’s data. Any service with the delegation permission can act on behalf of any end user, so grant it only to services you trust.

Verify isolation

Confirm that two identities get two separate sessions:

1. Invoke the agent as one identity and note the returned agent_session_id.
2. Invoke the agent as a second identity - a different signed-in user, or a different x-ms-user-identity value - and note its agent_session_id.
3. Confirm the two IDs differ, and that listing sessions as each identity returns only that identity’s sessions.

To see isolation end to end, deploy the note-taking agent sample, which stores notes per session under $HOME: each identity’s notes land in a separate session file that only that identity can list or download through the Session Files API.

View sessions across users

By default, each caller sees only their own sessions. An administrator or automation that holds the Foundry User role on the project can list and manage every session on the agent, regardless of which identity created it. To manage sessions, see Manage hosted agent sessions.

Isolation keys on container protocol 1.0.0 (deprecated)

Agents on container protocol version 1.0.0 use the earlier isolation-key model, in which the caller supplies an isolation key to scope sessions instead of the platform deriving identity from the Microsoft Entra token. This model - and protocol 1.0.0 itself - is deprecated. Agents on protocol 1.0.0 continue to work until July 31, 2026; afterward, the platform blocks requests to agents that still run on protocol 1.0.0.

Upgrade to protocol 2.0.0 to get the automatic per-user isolation described earlier in this article. Protocol 2.0.0 requires the AgentServer SDK that supports it - azure-ai-agentserver-core 2.0.0b7 or later for Python, or Azure.AI.AgentServer.Core 1.0.0-beta.26 or later for .NET. Earlier versions use protocol 1.0.0; update them as part of the upgrade.

• If you remain on protocol 1.0.0 for now, see Pass isolation keys to a hosted agent for how isolation keys work.
• To upgrade, see Migrate hosted agents.

Troubleshoot isolation

Symptom	Likely cause	What to try
403 or session_not_accessible when accessing a session	The session belongs to a different identity.	Use the same identity that created the session, or hold the Foundry User role to see other identities’ sessions.
403 on a request that sets x-ms-user-identity	The caller lacks the UserIdentityImpersonation permission, which is no longer granted by built-in roles.	Create a custom role that includes the Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action data action and assign it to the calling service.
Local runs don’t isolate sessions	Local runs don’t enforce isolation.	Test isolation against a deployed agent. Local mode (--local, azd ai agent run) targets a single user.

Related content

• Manage hosted agent sessions to list, inspect, and delete sessions, including across users.
• Multiplex multiple users in one hosted agent session when several users intentionally share one session.
• Agent identity concepts in Microsoft Foundry to understand how agent and user identities work.
• Invoke a hosted agent with the Azure Developer CLI for every invoke variant and option.
• Note-taking agent sample for a runnable agent that stores user-owned data per session (Python and C#).