.NET: Bump MEAI to 10.5.1 and add Foundry per-call x-client header support

[Roger Barreto (rogerbarreto)]

Summary

Bumps Microsoft.Extensions.AI from 10.5.0 to 10.5.1 and replaces the brittle UserAgentResponsesClient subclass with a clean per-call x-client-* header pipeline built on the new MEAI 10.5.1 OpenAIRequestPolicies hook.

The motivating scenario is the multi-tenant SaaS overlay from the Foundry Hosted Agents design: a SaaS backend needs to attest the end-user identity (x-client-end-user-id) and chat surface (x-client-end-chat-id) on a per-RunAsync basis, without rebuilding the agent or the chat client.

Public surface

All in Microsoft.Agents.AI.Foundry, gated by [Experimental(MAAI001)].

` csharp
// Per-run carrier on ChatOptions
chatOptions.WithClientHeader("x-client-end-user-id", "alice");
chatOptions.WithClientHeaders(new[] {
KeyValuePair.Create("x-client-end-user-id", "alice"),
KeyValuePair.Create("x-client-end-chat-id", "chat-42"),
});

// Opt-in for customer-built agents
var agent = new ChatClientAgent(chatClient).AsBuilder().UseClientHeaders().Build();

// Foundry-built agents pre-wire automatically
var foundryAgent = new FoundryAgent(endpoint, credential, model, instructions);
`

• Header names must start with x-client- (case-insensitive); other names throw ArgumentException.
• Bulk WithClientHeaders validates all entries before mutating any (all-or-nothing).
• If the ChatOptions.AdditionalProperties carrier slot is already occupied by a non-dictionary value, throws InvalidOperationException.

Internals

• ClientHeadersAgent decorator snapshots the dict at scope-push time so concurrent runs sharing a ChatOptions reference do not cross-contaminate.
• ClientHeadersScope is an AsyncLocal<IReadOnlyDictionary<string,string>?> with LIFO using semantics.
• ClientHeadersPolicy singleton stamps headers with Headers.Set so per-call values overwrite same-name headers from earlier policies and double registration is value-stable.
• OpenAIRequestPoliciesReflection dedups against MEAI's private _entries field with graceful fallback. A CI-guardrail test asserts the field shape so future MEAI bumps fail loudly here rather than silently disabling dedup.

Hosting cleanup

• Deleted UserAgentResponsesClient (~115 lines) and its dummy throwing pipeline.
• HostedAgentUserAgentPolicy is now registered via OpenAIRequestPolicies in FoundryHostingExtensions.TryApplyUserAgent.

Tests

• 19 new unit tests in ClientHeadersExtensionsTests.cs covering validation, AsyncLocal isolation, snapshot semantics, end-to-end wire stamping, and shared-chat-client dedup.
• Updated OpenTelemetryAgentTests for MEAI 10.5.1 changes to web_search serialization and the reduced tool definition payload when sensitive data capture is disabled.

Verification

• Full solution build: 0 errors, 0 warnings.
• CI-parity dotnet format --verify-no-changes (Docker mcr.microsoft.com/dotnet/sdk:10.0) clean on all 5 changed projects.
• 5245 tests passing across Foundry, Foundry.Hosting, core AI, Abstractions, AzureAI.Persistent, OpenAI, Anthropic.

Notes

• Microsoft.Extensions.Compliance.Abstractions stays at 10.5.0 because no 10.5.1 release exists on nuget.org.
• The OpenAI bridge is reachable through Foundry today; if a non-Foundry consumer wants the same wire delivery, they reference Microsoft.Agents.AI.Foundry. Splitting the bridge into its own package can come later if there is demand.

[Copilot]

Pull request overview

Upgrades the .NET Foundry integration to Microsoft.Extensions.AI 10.5.1 and introduces a new per-run x-client-* header forwarding mechanism using MEAI's OpenAIRequestPolicies hook, while also replacing the old hosted User-Agent wrapper with pipeline policies.

Changes:

• Bumped MEAI packages to 10.5.1 and updated telemetry tests for the new serialized tool payload shape.
• Added ClientHeadersExtensions, ClientHeadersAgent, ClientHeadersScope, and ClientHeadersPolicy to carry per-call x-client-* headers from ChatOptions to outbound OpenAI requests.
• Removed the UserAgentResponsesClient wrapper and switched hosted User-Agent injection to direct OpenAIRequestPolicies registration.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.UnitTests/OpenTelemetryAgentTests.cs	Updated telemetry expectations for MEAI 10.5.1 tool serialization.
dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj	Excludes new client-header tests on older target frameworks.
dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/ClientHeadersExtensionsTests.cs	Adds extensive unit coverage for client-header validation, scoping, and wire stamping.
dotnet/tests/Microsoft.Agents.AI.Foundry.Hosting.UnitTests/UserAgentResponsesClientTests.cs	Removes tests for the deleted wrapper-based user-agent implementation.
dotnet/src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj	Suppresses MEAI experimental warnings for new APIs.
dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs	Pre-wires client-header policy/decorator in constructor-based Foundry agents and updates session access to walk the delegating chain.
dotnet/src/Microsoft.Agents.AI.Foundry/ClientHeadersScope.cs	Adds AsyncLocal scope carrier for per-call header propagation.
dotnet/src/Microsoft.Agents.AI.Foundry/ClientHeadersPolicy.cs	Adds outbound header-stamping policy plus reflection-based OpenAI policy dedup helpers.
dotnet/src/Microsoft.Agents.AI.Foundry/ClientHeadersExtensions.cs	Adds public API for attaching per-call client headers and opting agents into the pipeline.
dotnet/src/Microsoft.Agents.AI.Foundry/ClientHeadersAgent.cs	Adds delegating agent that snapshots and scopes client headers for each run.
dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/UserAgentResponsesClient.cs	Deletes the old ResponsesClient subclass wrapper.
dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs	Switches hosted user-agent injection to policy registration via OpenAIRequestPolicies.
dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/HostedAgentUserAgentPolicy.cs	Updates docs to reflect the new registration path.
dotnet/Directory.Packages.props	Bumps MEAI package versions to 10.5.1.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 82%

✓ Correctness

The PR replaces the reflection-heavy UserAgentResponsesClient subclass approach with the cleaner MEAI 10.5.1 OpenAIRequestPolicies hook. The service resolution chain (DelegatingAIAgent.GetService walks InerAgent) correctly finds ChatClientAgent through the new ClientHeadersAgent wrapper. The OpenTelemetry test updates match MEAI 10.5.1 behavioral changes (web_search gains a name field, function tools omit description/parameters when sensitive data is disabled). One minor correctness concern in the streaming path: when no client headers are present, the default(Scope) struct's Dispose will unconditionally set the AsyncLocal to null, which could clear an outer scope in hypothetical nested-agent scenarios.

✓ Security Reliability

This PR replaces fragile reflection-based ResponsesClient wrapping with MEAI 10.5.1's public OpenAIRequestPolicies hook and adds a new per-call x-client-* header pipeline. The design is sound: header validation restricts to the x-client- prefix, AsyncLocal isolates concurrent runs, reflection helpers degrade gracefully, and wire-level idempotency guards prevent double-stamping. One minor asymetry exists in the streaming path where a default(Scope) Dispose could theoretically clobber an outer AsyncLocal value, but the practical risk is negligible since ClientHeadersAgent is internal and UseClientHeaders deduplicates.

✓ Test Coverage

The PR introduces significant new functionality (ClientHeadersAgent, ClientHeadersPolicy, ClientHeadersScope, ClientHeadersExtensions) and replaces the old UserAgentResponsesClient approach with the MEAI 10.5.1 OpenAIRequestPolicies hook. Test coverage is strong: the new 706-line ClientHeadersExtensionsTests.cs file provides 19 tests covering input validation, decorator behavior, AsyncLocal scoping, pipeline policy stamping, reflection dedup, end-to-end wire validation, and idempotency. The deleted UserAgentResponsesClientTests.cs (452 lines) tested code that no longer exists. One moderate gap: the HostedAgentUserAgentPolicy retry-idempotency scenario previously tested in Polyfill_RetryWithinCall_DoesNotDuplicateSupplementInUserAgentAsync has no replacement test, though the policy code is unchanged and its Contains-check still provides the dedup guarantee.

✗ Design Approach

I found two design-level problems. First, the new client-header forwarding path is only wired into some Foundry construction paths, so callers get different behavior depending on which public AIProjectClient.AsAIAgent(...) overload they use. Second, the hosted User-Agent hook now registers its policy on every agent resolution, which is safe on the wire but causes duplicate pipeline entries to accumulate on long-lived agents.

Flagged Issues

• The new client-header bridge is only installed in the FoundryAgent constructor helpers changed here, but the existing public AIProjectClient.AsAIAgent(AgentReference|ProjectsAgentRecord|ProjectsAgentVersion) overloads still create a plain ChatClientAgent and pass it through the unchanged internal FoundryAgent(AIProjectClient, ChatClientAgent) constructor (AzureAIProjectChatClientExtensions.cs:54-66, 91-99, 124-132, 220-245; FoundryAgent.cs:104-108). Header forwarding should not depend on which public factory overload the caller picks — centralize this wiring in shared Foundry agent construction so all factory paths behave the same.

---

Automated review by rogerbarreto's agents