.NET: [BREAKING] Make Foundry delegated user identity sticky on AgentSession

[Roger Barreto (rogerbarreto)]

Motivation & Context

Foundry binds a stored Responses continuation to the delegated user that created it. Reusing one Agent Framework AgentSession with a different x-ms-user-identity causes the platform to reject the continuation with HTTP 404. Because AgentSession represents that conversation continuity, the delegated identity should be bound to the session rather than supplied independently for every run.

This change makes the safe path the default: each application user receives a separate AgentSession, while several user sessions may still share the same Foundry hosted sandbox through agent_session_id.

Description & Review Guide

• What are the major changes?
  • Add an optional userIdentity parameter to FoundryAgent.CreateFoundryHostedAgentSessionAsync and persist it in the session state bag.
  • Read the persisted identity on every run and automatically send it as x-ms-user-identity.
  • Remove ChatOptions.WithFoundryHostedAgentUserIdentity, which allowed one session to change identities between runs.
  • Update unit tests, live integration coverage, and the UserIsolationAgent sample for the session-bound API.
• What is the impact of these changes?
  • Applications no longer need to repeat the delegated identity on every invocation.
  • Serialized sessions retain their delegated identity after restoration.
  • Applications must create a separate AgentSession for each user. Those sessions may still share one hosted sandbox.
• What do you want reviewers to focus on?
  • Confirm that session serialization preserves the identity and that the request wrapper reads only the session-bound value.
  • Confirm that adding userIdentity after the existing optional identifiers is the safest ordering for current positional callers.
  • Confirm that removing the experimental per-run helper is appropriate for preventing cross-user session reuse.

Related Issue

Fixes #8291

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

It removes a required per-run identity path and breaks existing positional cancellation-token calls.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Binds Foundry delegated identities to serialized AgentSession state and reuses them across requests.

Changes:

• Adds session-bound delegated identities.
• Removes per-run identity configuration.
• Updates tests, documentation, and the user-isolation sample.

File summaries

File	Description
dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs	Adds identity during session creation.
dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgentSessionExtensions.cs	Stores and exposes session identity.
dotnet/src/Microsoft.Agents.AI.Foundry/FoundryHostedRequestAgent.cs	Reads identity from the session.
dotnet/src/Microsoft.Agents.AI.Foundry/FoundryChatOptionsExtensions.cs	Removes per-run identity support.
dotnet/src/Microsoft.Agents.AI.Foundry/UserIdentityScope.cs	Updates scope documentation.
dotnet/src/Microsoft.Agents.AI.Foundry/UserIdentityPolicy.cs	Updates policy documentation.
dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryHostedRequestTests.cs	Tests persistence and reuse.
dotnet/tests/Foundry.Hosting.IntegrationTests/HostedSessionAndUserIdentityTests.cs	Tests live serialized-session behavior.
dotnet/tests/Foundry.Hosting.IntegrationTests/README.md	Documents integration coverage.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/UserIsolationAgent/Program.cs	Uses session-bound identities.
dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/UserIsolationAgent/README.md	Documents the revised sample.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 824ab8ec5bea
Model: gpt-5.6-sol-fast

Overview

The change binds delegated identity to serialized session state and consistently restores or clears the request-scoped AsyncLocal; focused unit and integration coverage protects those lifecycle invariants. The remaining risk is an avoidable source and binary compatibility break in the existing hosted-session creation API, separate from the intentionally removed per-run identity helper.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs