From 137a79686f91a0430eee3f5b1d7a3c565c841955 Mon Sep 17 00:00:00 2001
From: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
Date: Fri, 15 May 2026 15:43:29 +0100
Subject: [PATCH 1/2] .NET: Bump Azure.AI.Projects to 2.1.0-beta.2 and add
 agent-endpoint AsAIAgent path

Bumps Azure.AI.Projects to 2.1.0-beta.2 with the matching transitive pins (Azure.Core 1.55.0, System.ClientModel 1.11.0).

Foundry agent endpoint plumbing:
* FoundryAgent now routes the agent-endpoint constructor through the new GetProjectResponsesClientForAgentEndpoint helper.
* Adds an internal FoundryAgent ctor that takes an existing AIProjectClient plus a parsed agent endpoint so the public extension does not need to construct a second project client.
* Adds public AIProjectClient.AsAIAgent(Uri agentEndpoint, ...) extension. This is the path consumer samples are expected to use for hosted agents because version selection happens server-side.
* Trims the dangling "If you want to construct a FoundryAgent against a project endpoint..." sentence from ParseAgentEndpoint.

Unit tests:
* Four new tests in AzureAIProjectChatClientExtensionsTests cover the AIProjectClient.AsAIAgent(Uri agentEndpoint, ...) overload. 263/263 pass.

Consumer samples (Using-Samples):
* SimpleAgent and SessionFilesClient now read AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_AGENT_NAME (both required, throw on missing), derive the agent endpoint with new Uri($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai"), then call aiProjectClient.AsAIAgent(agentEndpoint, ...).
* SessionFilesClient README updated.

Contributor samples (responses/*):
* New HostedContributorRouteExtensions.MapDevTemporaryLocalAgentEndpoint() wildcard route extension so localhost contributor servers accept the per-agent OpenAI endpoint shape the production Hosted runtime exposes.
* All 11 contributor Program.cs files call MapDevTemporaryLocalAgentEndpoint() with a contributor-only warning comment.
* Hosted-Files and Hosted-AzureSearchRag were importing Hosted_Shared_Contributor_Setup but never calling AddDevTemporaryLocalContributorSetup(). Both now call it so HostedSessionIsolationKeyProvider resolves correctly in dev.
* Hosted-AzureSearchRag, Hosted-Files, Hosted-MemoryAgent csprojs drop stale VersionOverride="2.1.0-beta.1" pins.
* Hosted-AzureSearchRag and Hosted-Files csprojs add ProjectReference to Hosted_Shared_Contributor_Setup.
* Hosted-Observability/.dockerignore removed the out/ exclusion that was blocking COPY out/ . in Dockerfile.contributor.

Verified:
* Full solution-scoped build of changed projects: green.
* Scoped CI-parity dotnet format via WSL2 + Docker (mcr.microsoft.com/dotnet/sdk:10.0) over every changed csproj: clean.
* Foundry unit tests: 263/263.
* Contributor docker smoke for 8 hosted samples (publish + docker build + docker run + curl POST to the wildcard route): HTTP 200 / 500 with route matched.
* End-to-end smoke against the real Azure Foundry project with a fresh bearer token: Hosted-Files contributor container served HTTP 200, the agent invoked ListBundledFiles, and returned the expected file name.
---
 dotnet/Directory.Packages.props               |   6 +-
 .../HostedAzureSearchRag.csproj               |   3 +-
 .../Hosted-AzureSearchRag/Program.cs          |  10 +-
 .../Hosted-ChatClientAgent/Program.cs         |   9 +-
 .../responses/Hosted-Files/HostedFiles.csproj |   5 +-
 .../responses/Hosted-Files/Program.cs         |  10 +-
 .../responses/Hosted-FoundryAgent/Program.cs  |   9 +-
 .../responses/Hosted-LocalTools/Program.cs    |   8 +-
 .../responses/Hosted-McpTools/Program.cs      |   9 +-
 .../HostedMemoryAgent.csproj                  |   2 +-
 .../responses/Hosted-MemoryAgent/Program.cs   |   9 +-
 .../Hosted-Observability/.dockerignore        |   1 -
 .../responses/Hosted-Observability/Program.cs |   8 +-
 .../responses/Hosted-TextRag/Program.cs       |   8 +-
 .../responses/Hosted-Toolbox/Program.cs       |   8 +-
 .../Hosted-Workflow-Simple/Program.cs         |   8 +-
 .../HostedContributorRouteExtensions.cs       |  41 ++++
 .../SessionFilesClient/Program.cs             |  29 +--
 .../SessionFilesClient/README.md              |  10 +-
 .../Using-Samples/SimpleAgent/Program.cs      |  27 +--
 .../AzureAIProjectChatClientExtensions.cs     |  36 ++++
 .../FoundryAgent.cs                           | 177 ++++++++----------
 .../Foundry.Hosting.IntegrationTests.csproj   |   2 +-
 ...AzureAIProjectChatClientExtensionsTests.cs |  81 ++++++++
 .../FoundryAgentTests.cs                      |  20 +-
 25 files changed, 341 insertions(+), 195 deletions(-)
 create mode 100644 dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorRouteExtensions.cs

diff --git a/dotnet/Directory.Packages.props b/dotnet/Directory.Packages.props
index 75106b5fcb..2121be9207 100644
--- a/dotnet/Directory.Packages.props
+++ b/dotnet/Directory.Packages.props
@@ -26,10 +26,10 @@
     <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
     <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
     <PackageVersion Include="Azure.Search.Documents" Version="12.0.0" />
-    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.2" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Core" Version="1.53.0" />
+    <PackageVersion Include="Azure.Core" Version="1.55.0" />
     <PackageVersion Include="Azure.Identity" Version="1.21.0" />
     <PackageVersion Include="DotNetEnv" Version="3.1.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.5.0" />
@@ -44,7 +44,7 @@
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageVersion Include="System.ClientModel" Version="1.10.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.11.0" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj
index 3b648ffbcb..98f3f57bd4 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/HostedAzureSearchRag.csproj
@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Azure.Search.Documents" />
     <PackageReference Include="DotNetEnv" />
@@ -22,6 +22,7 @@
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
   </ItemGroup>
 
   <!-- For end-users: uncomment the PackageReference below and remove the ProjectReferences above
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Program.cs
index c933d91f87..4b97324134 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/Program.cs
@@ -14,6 +14,7 @@
 using Azure.Search.Documents;
 using Azure.Search.Documents.Models;
 using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
@@ -66,14 +67,15 @@
 // Host the agent as a Foundry Hosted Agent using the Responses API.
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs
index f77f361f36..b4b08ba5a8 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/Program.cs
@@ -46,10 +46,9 @@ You are a helpful AI assistant hosted as a Foundry Hosted Agent.
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj
index fe36ca8ba2..ce9de7bfbd 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/HostedFiles.csproj
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <TargetFrameworks>net10.0</TargetFrameworks>
@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="DotNetEnv" />
   </ItemGroup>
@@ -28,6 +28,7 @@
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <ProjectReference Include="..\Hosted_Shared_Contributor_Setup\Hosted_Shared_Contributor_Setup.csproj" />
   </ItemGroup>
 
   <!-- For end-users: uncomment the PackageReference below and remove the ProjectReference above
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs
index aba8f4ebef..3f79a0eb7d 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs
@@ -35,6 +35,7 @@
 using Azure.Core;
 using Azure.Identity;
 using DotNetEnv;
+using Hosted_Shared_Contributor_Setup;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
@@ -175,14 +176,15 @@ numbers and figures verbatim from the file.
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddFoundryResponses(agent);
+builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debugging only - must not be used in production.
 
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Program.cs
index 116ff21496..f83a67f66d 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/Program.cs
@@ -39,10 +39,9 @@
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Program.cs
index 7f839c2f10..8a665d38a3 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/Program.cs
@@ -118,10 +118,10 @@ politely let them know you specialize in Seattle hotel recommendations.
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Program.cs
index 297cf87ce1..1eed2126f7 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/Program.cs
@@ -87,10 +87,9 @@ Be concise and provide direct answers with relevant links.
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj
index 21ce81f2b5..9113d2d9e2 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/HostedMemoryAgent.csproj
@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="DotNetEnv" />
   </ItemGroup>
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/Program.cs
index af1115bf32..22bfd316b3 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/Program.cs
@@ -79,10 +79,9 @@
 var app = builder.Build();
 app.MapFoundryResponses();
 
-// In Development, also map the OpenAI-compatible route that AIProjectClient uses.
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/.dockerignore b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/.dockerignore
index b8ab55e777..37739c9e09 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/.dockerignore
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/.dockerignore
@@ -1,7 +1,6 @@
 .env
 bin/
 obj/
-out/
 .vs/
 .vscode/
 *.user
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/Program.cs
index 2ebfc9715e..fa57fc03a2 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/Program.cs
@@ -66,9 +66,9 @@ string GetWeather(
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Program.cs
index cfd952d5af..a374f81fd7 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/Program.cs
@@ -53,10 +53,10 @@
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Program.cs
index a880ac5c27..3f6c0a70a7 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Program.cs
@@ -69,10 +69,10 @@ Use the available tools to answer user questions.
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/Program.cs
index 55406810dc..d0fb8ee129 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Workflow-Simple/Program.cs
@@ -55,9 +55,9 @@
 var app = builder.Build();
 app.MapFoundryResponses();
 
-if (app.Environment.IsDevelopment())
-{
-    app.MapFoundryResponses("openai/v1");
-}
+// Contributor-only: in Development, also map the per-agent OpenAI route shape that live Foundry uses
+// so a local REPL client can target this server via AIProjectClient.AsAIAgent(Uri agentEndpoint).
+// Do not use this in production. Hosted Foundry agents only support the agent-endpoint path.
+app.MapDevTemporaryLocalAgentEndpoint();
 
 app.Run();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorRouteExtensions.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorRouteExtensions.cs
new file mode 100644
index 0000000000..991eff507e
--- /dev/null
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted_Shared_Contributor_Setup/HostedContributorRouteExtensions.cs
@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.Hosting;
+
+namespace Hosted_Shared_Contributor_Setup;
+
+/// <summary>
+/// Routing helpers for contributor samples that host a Foundry-managed agent locally.
+/// </summary>
+public static class HostedContributorRouteExtensions
+{
+    /// <summary>
+    /// In Development, maps the per-agent OpenAI route shape that live Foundry uses
+    /// (<c>/api/projects/{project}/agents/{agentName}/endpoint/protocols/openai/responses</c>) on top
+    /// of the default <c>MapFoundryResponses()</c> so a local REPL client can reach the agent through
+    /// <c>AIProjectClient.AsAIAgent(Uri agentEndpoint)</c>, which is the only supported consumption path
+    /// for Foundry-hosted agents.
+    ///
+    /// <para>
+    /// The <c>{project}</c> and <c>{agentName}</c> segments are route-parameter wildcards on the server
+    /// side; the handler does not consume them, so any value sent by the client is accepted.
+    /// </para>
+    ///
+    /// <para><b>For local contributor debugging only and should not be used in production.</b></para>
+    /// </summary>
+    /// <param name="app">The <see cref="WebApplication"/> to attach the routes to.</param>
+    /// <returns>The same <see cref="WebApplication"/> for chaining.</returns>
+    public static WebApplication MapDevTemporaryLocalAgentEndpoint(this WebApplication app)
+    {
+        ArgumentNullException.ThrowIfNull(app);
+
+        if (app.Environment.IsDevelopment())
+        {
+            app.MapFoundryResponses("api/projects/{project}/agents/{agentName}/endpoint/protocols/openai");
+        }
+
+        return app;
+    }
+}
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/Program.cs
index e05e025c0d..0c2ba2d038 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/Program.cs
@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.ClientModel.Primitives;
-using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Azure.Identity;
 using DotNetEnv;
@@ -11,28 +10,34 @@
 // Load .env file if present (for local development)
 Env.TraversePath().Load();
 
-Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
-    ?? "http://localhost:8088");
+// AZURE_AI_PROJECT_ENDPOINT is the Foundry project endpoint. Shape:
+//   https://<host>/api/projects/<project>
+Uri projectEndpoint = new(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
 
-var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
-    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+// AZURE_AI_AGENT_NAME is the registered server-side agent name.
+string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
+    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");
 
-// ── Create an agent-framework agent backed by the remote Hosted-Files agent ──
+// Derive the per-agent OpenAI endpoint that hosted Foundry agents require.
+Uri agentEndpoint = new($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai");
+
+// ── Create an agent-framework agent backed by the remote agent endpoint ──────
 
 var options = new AIProjectClientOptions();
 
-if (agentEndpoint.Scheme == "http")
+if (projectEndpoint.Scheme == "http")
 {
     // For local HTTP dev: tell AIProjectClient the endpoint is HTTPS (to satisfy
     // BearerTokenPolicy's TLS check), then swap the scheme back to HTTP right
     // before the request hits the wire.
-
+    projectEndpoint = new UriBuilder(projectEndpoint) { Scheme = "https" }.Uri;
     agentEndpoint = new UriBuilder(agentEndpoint) { Scheme = "https" }.Uri;
     options.AddPolicy(new HttpSchemeRewritePolicy(), PipelinePosition.BeforeTransport);
 }
 
-var aiProjectClient = new AIProjectClient(agentEndpoint, new AzureCliCredential(), options);
-FoundryAgent agent = aiProjectClient.AsAIAgent(new AgentReference(agentName));
+var aiProjectClient = new AIProjectClient(projectEndpoint, new AzureCliCredential(), options);
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentEndpoint);
 
 AgentSession session = await agent.CreateSessionAsync();
 
@@ -41,10 +46,10 @@
 Console.ForegroundColor = ConsoleColor.Cyan;
 Console.WriteLine($"""
     ══════════════════════════════════════════════════════════
-    Session Files Client                                    
+    Session Files Client
     Connected to: {agentEndpoint}
     Try: "Give me the total revenue in the contoso file."
-    Type a message or 'quit' to exit                        
+    Type a message or 'quit' to exit
     ══════════════════════════════════════════════════════════
     """);
 Console.ResetColor();
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/README.md b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/README.md
index dbf9262ae8..356416596a 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/README.md
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient/README.md
@@ -13,18 +13,18 @@ The agent's container-side `ListFiles` and `ReadFile` tools surface the bundled
 ## Configuration
 
 ```env
-AGENT_ENDPOINT=http://localhost:8088
-AGENT_NAME=hosted-files
+AZURE_AI_PROJECT_ENDPOINT=https://<host>/api/projects/<project>
+AZURE_AI_AGENT_NAME=hosted-files
 ```
 
-`AGENT_ENDPOINT` defaults to `http://localhost:8088`. Override with the deployed agent endpoint when chatting against Foundry.
+Both are required. `AZURE_AI_PROJECT_ENDPOINT` is the Foundry project endpoint URL and `AZURE_AI_AGENT_NAME` is the registered server-side agent name. The sample builds the per-agent OpenAI endpoint URL from these.
 
 ## Run
 
 ```bash
 cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SessionFilesClient
-$env:AGENT_ENDPOINT = "http://localhost:8088"
-$env:AGENT_NAME = "hosted-files"
+$env:AZURE_AI_PROJECT_ENDPOINT = "http://localhost:8088/api/projects/local"
+$env:AZURE_AI_AGENT_NAME = "hosted-files"
 dotnet run
 ```
 
diff --git a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs
index 5d9c003dfa..eedf136abb 100644
--- a/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs
+++ b/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Using-Samples/SimpleAgent/Program.cs
@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.ClientModel.Primitives;
-using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Azure.Identity;
 using DotNetEnv;
@@ -11,28 +10,34 @@
 // Load .env file if present (for local development)
 Env.TraversePath().Load();
 
-Uri agentEndpoint = new(Environment.GetEnvironmentVariable("AGENT_ENDPOINT")
-    ?? "http://localhost:8088");
+// AZURE_AI_PROJECT_ENDPOINT is the Foundry project endpoint. Shape:
+//   https://<host>/api/projects/<project>
+Uri projectEndpoint = new(Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set."));
 
-var agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
-    ?? throw new InvalidOperationException("AGENT_NAME is not set.");
+// AZURE_AI_AGENT_NAME is the registered server-side agent name.
+string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
+    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");
+
+// Derive the per-agent OpenAI endpoint that hosted Foundry agents require.
+Uri agentEndpoint = new($"{projectEndpoint}/agents/{agentName}/endpoint/protocols/openai");
 
 // ── Create an agent-framework agent backed by the remote agent endpoint ──────
 
 var options = new AIProjectClientOptions();
 
-if (agentEndpoint.Scheme == "http")
+if (projectEndpoint.Scheme == "http")
 {
     // For local HTTP dev: tell AIProjectClient the endpoint is HTTPS (to satisfy
     // BearerTokenPolicy's TLS check), then swap the scheme back to HTTP right
     // before the request hits the wire.
-
+    projectEndpoint = new UriBuilder(projectEndpoint) { Scheme = "https" }.Uri;
     agentEndpoint = new UriBuilder(agentEndpoint) { Scheme = "https" }.Uri;
     options.AddPolicy(new HttpSchemeRewritePolicy(), PipelinePosition.BeforeTransport);
 }
 
-var aiProjectClient = new AIProjectClient(agentEndpoint, new AzureCliCredential(), options);
-FoundryAgent agent = aiProjectClient.AsAIAgent(new AgentReference(agentName));
+var aiProjectClient = new AIProjectClient(projectEndpoint, new AzureCliCredential(), options);
+FoundryAgent agent = aiProjectClient.AsAIAgent(agentEndpoint);
 
 AgentSession session = await agent.CreateSessionAsync();
 
@@ -41,9 +46,9 @@
 Console.ForegroundColor = ConsoleColor.Cyan;
 Console.WriteLine($"""
     ══════════════════════════════════════════════════════════
-    Simple Agent Sample                                     
+    Simple Agent Sample
     Connected to: {agentEndpoint}
-    Type a message or 'quit' to exit                        
+    Type a message or 'quit' to exit
     ══════════════════════════════════════════════════════════
     """);
 Console.ResetColor();
diff --git a/dotnet/src/Microsoft.Agents.AI.Foundry/AzureAIProjectChatClientExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Foundry/AzureAIProjectChatClientExtensions.cs
index 1f0f0a6e5f..8feb3bd465 100644
--- a/dotnet/src/Microsoft.Agents.AI.Foundry/AzureAIProjectChatClientExtensions.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Foundry/AzureAIProjectChatClientExtensions.cs
@@ -66,6 +66,42 @@ public static FoundryAgent AsAIAgent(
         return new FoundryAgent(aiProjectClient, innerAgent);
     }
 
+    /// <summary>
+    /// Wraps an existing server side hosted agent as a <see cref="FoundryAgent"/> using the provided
+    /// <see cref="AIProjectClient"/> and an agent-specific endpoint URI.
+    /// </summary>
+    /// <param name="aiProjectClient">The <see cref="AIProjectClient"/> to use for project-level operations. Cannot be <see langword="null"/>.</param>
+    /// <param name="agentEndpoint">
+    /// The agent-specific endpoint URI of shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
+    /// The agent name is parsed from this URI and the active agent version is resolved server side
+    /// from the endpoint's administrator-controlled version selector. Cannot be <see langword="null"/>.
+    /// </param>
+    /// <param name="tools">The tools to use when interacting with the agent. This is required when using prompt agent definitions with tools.</param>
+    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/> used by the agent.</param>
+    /// <param name="services">An optional <see cref="IServiceProvider"/> to use for resolving services required by the <see cref="AIFunction"/> instances being invoked.</param>
+    /// <returns>A <see cref="FoundryAgent"/> instance that routes calls through the supplied agent endpoint.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="aiProjectClient"/> or <paramref name="agentEndpoint"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
+    /// <remarks>
+    /// Agent version selection is controlled by the Foundry administrator through the endpoint's
+    /// version selector and cannot be overridden by the caller. Use the
+    /// <see cref="AsAIAgent(AIProjectClient, AgentReference, IList{AITool}?, Func{IChatClient, IChatClient}?, IServiceProvider?)"/>
+    /// overload when an explicit agent version pin is required.
+    /// </remarks>
+    public static FoundryAgent AsAIAgent(
+        this AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        IList<AITool>? tools = null,
+        Func<IChatClient, IChatClient>? clientFactory = null,
+        IServiceProvider? services = null)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
+        return new FoundryAgent(aiProjectClient, agentEndpoint, tools, clientFactory, services);
+    }
+
     /// <summary>
     /// Uses an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="AIProjectClient"/> and <see cref="ProjectsAgentRecord"/>.
     /// </summary>
diff --git a/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs b/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
index 6174e1b149..816d56302a 100644
--- a/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
@@ -40,27 +40,9 @@ namespace Microsoft.Agents.AI.Foundry;
 public sealed class FoundryAgent : DelegatingAIAgent
 {
     /// <summary>
-    /// Default OAuth scope for the Azure AI resource. Matches the scope used by
-    /// <c>Azure.AI.Extensions.OpenAI</c>'s internal authentication helper so the bearer token is
-    /// accepted by the Foundry control plane.
+    /// The cached <see cref="AIProjectClient"/> supplied to or constructed by the active constructor.
     /// </summary>
-    private const string AzureAiResourceScope = "https://ai.azure.com/.default";
-
-    /// <summary>
-    /// The cached <see cref="AIProjectClient"/> when one was supplied or constructed by the active
-    /// constructor. Null when the agent was constructed via the agent-endpoint constructor, which
-    /// does not build a full <see cref="AIProjectClient"/>.
-    /// </summary>
-    private readonly AIProjectClient? _aiProjectClient;
-
-    /// <summary>
-    /// Project-scoped <see cref="ProjectOpenAIClient"/>. Always non-null. Used for project-level
-    /// operations such as <see cref="CreateConversationSessionAsync(CancellationToken)"/>.
-    /// In agent-endpoint mode this is built directly from the project root derived from the
-    /// supplied agent endpoint; in project-endpoint mode it is the cached client returned by
-    /// <see cref="AIProjectClient"/>.
-    /// </summary>
-    private readonly ProjectOpenAIClient _projectOpenAIClient;
+    private readonly AIProjectClient _aiProjectClient;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="FoundryAgent"/> class using the direct Responses API path.
@@ -94,7 +76,6 @@ public FoundryAgent(
             out var aiProjectClient))
     {
         this._aiProjectClient = aiProjectClient;
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
     }
 
     /// <summary>
@@ -106,11 +87,9 @@ public FoundryAgent(
     /// </param>
     /// <param name="credential">The authentication credential.</param>
     /// <param name="clientOptions">
-    /// Optional configuration for the underlying <see cref="ProjectOpenAIClient"/>. When supplied:
+    /// Optional configuration for the underlying <see cref="ProjectResponsesClient"/>. When supplied:
     /// <list type="bullet">
     ///   <item><description>The instance is passed through to the per-agent client; pipeline policies added via <c>AddPolicy(...)</c> on it execute on the per-agent traffic.</description></item>
-    ///   <item><description><c>Endpoint</c> and <see cref="ProjectOpenAIClientOptions.AgentName"/> are owned by this constructor and are overwritten with values derived from <paramref name="agentEndpoint"/>; any caller value is replaced.</description></item>
-    ///   <item><description>For the project-level conversations client a separate fresh options bag is built that copies only <see cref="ClientPipelineOptions.RetryPolicy"/>, <see cref="ClientPipelineOptions.NetworkTimeout"/>, <see cref="ClientPipelineOptions.Transport"/>, and <c>UserAgentApplicationId</c>; pipeline policies added via <c>AddPolicy(...)</c> do <strong>not</strong> propagate to the conversations pipeline.</description></item>
     /// </list>
     /// </param>
     /// <param name="tools">Optional tools to use when interacting with the agent.</param>
@@ -134,9 +113,34 @@ public FoundryAgent(
         IList<AITool>? tools = null,
         Func<IChatClient, IChatClient>? clientFactory = null,
         IServiceProvider? services = null)
-        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services))
+        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services, out var aiProjectClient))
+    {
+        this._aiProjectClient = aiProjectClient;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FoundryAgent"/> class from an agent-specific
+    /// endpoint while reusing an existing <see cref="AIProjectClient"/>.
+    /// </summary>
+    /// <param name="aiProjectClient">An existing <see cref="AIProjectClient"/> rooted at the same project as <paramref name="agentEndpoint"/>.</param>
+    /// <param name="agentEndpoint">
+    /// The agent-specific endpoint URI. Must be of the shape
+    /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>.
+    /// </param>
+    /// <param name="tools">Optional tools to use when interacting with the agent.</param>
+    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/>.</param>
+    /// <param name="services">Optional service provider for resolving dependencies required by AI functions.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="aiProjectClient"/> or <paramref name="agentEndpoint"/> is null.</exception>
+    /// <exception cref="ArgumentException"><paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
+    internal FoundryAgent(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        IList<AITool>? tools = null,
+        Func<IChatClient, IChatClient>? clientFactory = null,
+        IServiceProvider? services = null)
+        : base(BuildAgentEndpointInnerAgent(aiProjectClient, agentEndpoint, clientOptions: null, tools, clientFactory, services))
     {
-        this._projectOpenAIClient = CreateProjectLevelOpenAIClientFromAgentEndpoint(agentEndpoint, credential, clientOptions);
+        this._aiProjectClient = Throw.IfNull(aiProjectClient);
     }
 
     /// <summary>
@@ -146,7 +150,6 @@ internal FoundryAgent(AIProjectClient aiProjectClient, ChatClientAgent innerAgen
         : base(WireClientHeaders(Throw.IfNull(innerAgent)))
     {
         this._aiProjectClient = Throw.IfNull(aiProjectClient);
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
     }
 
     #region Convenience methods
@@ -179,7 +182,7 @@ public ValueTask<AgentSession> CreateSessionAsync(string conversationId, Cancell
     /// <returns>A <see cref="ChatClientAgentSession"/> linked to the newly created server-side conversation.</returns>
     public async Task<ChatClientAgentSession> CreateConversationSessionAsync(CancellationToken cancellationToken = default)
     {
-        var conversationsClient = this._projectOpenAIClient.GetProjectConversationsClient();
+        var conversationsClient = this._aiProjectClient.ProjectOpenAIClient.GetProjectConversationsClient();
 
         var conversation = (await conversationsClient.CreateProjectConversationAsync(options: null, cancellationToken).ConfigureAwait(false)).Value;
 
@@ -201,11 +204,6 @@ private ChatClientAgent GetInnerChatClientAgent() =>
             return this._aiProjectClient;
         }
 
-        if (serviceKey is null && serviceType == typeof(ProjectOpenAIClient))
-        {
-            return this._projectOpenAIClient;
-        }
-
         return base.GetService(serviceType, serviceKey);
     }
 
@@ -291,11 +289,10 @@ private static AIAgent WireClientHeaders(ChatClientAgent innerAgent)
 
     /// <summary>
     /// Builds the inner <see cref="ChatClientAgent"/> for the agent-endpoint constructor by
-    /// constructing a per-agent <see cref="ProjectOpenAIClient"/> via the
-    /// <c>ProjectOpenAIClient(AuthenticationPolicy, ProjectOpenAIClientOptions)</c>
-    /// constructor with <see cref="ProjectOpenAIClientOptions.AgentName"/> set. This routes the
-    /// outbound URL through the per-agent endpoint shape that the Foundry service expects for
-    /// hosted agents and lets the SDK auto-append the <c>api-version</c> query string.
+    /// constructing a project-scoped <see cref="ProjectOpenAIClient"/> and using
+    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
+    /// This routes the outbound URL through the per-agent endpoint shape that the Foundry service
+    /// expects for hosted agents and lets the SDK auto-append the <c>api-version</c> query string.
     /// Caller-supplied <paramref name="clientOptions"/> are passed through to the per-agent
     /// client with <c>Endpoint</c> and
     /// <see cref="ProjectOpenAIClientOptions.AgentName"/> overridden by values derived from
@@ -308,22 +305,44 @@ private static AIAgent CreateInnerAgentFromAgentEndpoint(
         ProjectOpenAIClientOptions? clientOptions,
         IList<AITool>? tools,
         Func<IChatClient, IChatClient>? clientFactory,
-        IServiceProvider? services)
+        IServiceProvider? services,
+        out AIProjectClient outClient)
     {
         Throw.IfNull(agentEndpoint);
         Throw.IfNull(credential);
 
+        var (_, projectRoot) = ParseAgentEndpoint(agentEndpoint);
+        outClient = CreateProjectClient(projectRoot, credential, CreateProjectClientOptions(clientOptions));
+
+        return BuildAgentEndpointInnerAgent(outClient, agentEndpoint, clientOptions, tools, clientFactory, services);
+    }
+
+    /// <summary>
+    /// Builds the inner <see cref="ChatClientAgent"/> for an agent endpoint against a pre-built
+    /// <see cref="AIProjectClient"/>. The caller is responsible for ensuring the supplied client
+    /// is rooted at the same project as <paramref name="agentEndpoint"/>; the agent name is
+    /// parsed from the endpoint URI and passed to
+    /// <see cref="ProjectOpenAIClient.GetProjectResponsesClientForAgentEndpoint(string, string?, ProjectOpenAIClientOptions?)"/>.
+    /// </summary>
+    private static AIAgent BuildAgentEndpointInnerAgent(
+        AIProjectClient aiProjectClient,
+        Uri agentEndpoint,
+        ProjectOpenAIClientOptions? clientOptions,
+        IList<AITool>? tools,
+        Func<IChatClient, IChatClient>? clientFactory,
+        IServiceProvider? services)
+    {
+        Throw.IfNull(aiProjectClient);
+        Throw.IfNull(agentEndpoint);
+
         var (agentName, _) = ParseAgentEndpoint(agentEndpoint);
 
         var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
-        perAgentOptions.Endpoint = agentEndpoint;
-        perAgentOptions.AgentName = agentName;
         perAgentOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
 
-        var authPolicy = new BearerTokenPolicy(credential, AzureAiResourceScope);
-        var perAgentClient = new ProjectOpenAIClient(authPolicy, perAgentOptions);
-
-        IChatClient chatClient = perAgentClient.GetProjectResponsesClient().AsIChatClient();
+        IChatClient chatClient = aiProjectClient.ProjectOpenAIClient
+            .GetProjectResponsesClientForAgentEndpoint(agentName, options: perAgentOptions)
+            .AsIChatClient();
         if (clientFactory is not null)
         {
             chatClient = clientFactory(chatClient);
@@ -339,57 +358,6 @@ private static AIAgent CreateInnerAgentFromAgentEndpoint(
         return WireClientHeaders(new ChatClientAgent(chatClient, agentOptions, services: services));
     }
 
-    /// <summary>
-    /// Builds the project-scoped <see cref="ProjectOpenAIClient"/> for the agent-endpoint
-    /// constructor by deriving the project root from the supplied agent endpoint and constructing
-    /// a fresh client without <see cref="ProjectOpenAIClientOptions.AgentName"/> so the SDK
-    /// appends the standard <c>/openai/v1</c> suffix expected for project-level surfaces such as
-    /// conversations.
-    /// </summary>
-    /// <remarks>
-    /// Only the four observable primitive properties (<see cref="ClientPipelineOptions.RetryPolicy"/>,
-    /// <see cref="ClientPipelineOptions.NetworkTimeout"/>, <see cref="ClientPipelineOptions.Transport"/>,
-    /// and <c>UserAgentApplicationId</c>) are copied from the caller's options bag. Pipeline
-    /// policies added via <c>AddPolicy</c> on the caller bag do not propagate because
-    /// <see cref="ClientPipelineOptions"/> does not publicly enumerate its policies. The MEAI
-    /// user-agent policy is appended last.
-    /// </remarks>
-    private static ProjectOpenAIClient CreateProjectLevelOpenAIClientFromAgentEndpoint(
-        Uri agentEndpoint,
-        AuthenticationTokenProvider credential,
-        ProjectOpenAIClientOptions? clientOptions)
-    {
-        var (_, projectRoot) = ParseAgentEndpoint(agentEndpoint);
-
-        var projectOptions = new ProjectOpenAIClientOptions();
-        if (clientOptions is not null)
-        {
-            if (clientOptions.RetryPolicy is not null)
-            {
-                projectOptions.RetryPolicy = clientOptions.RetryPolicy;
-            }
-
-            if (clientOptions.NetworkTimeout is not null)
-            {
-                projectOptions.NetworkTimeout = clientOptions.NetworkTimeout;
-            }
-
-            if (clientOptions.Transport is not null)
-            {
-                projectOptions.Transport = clientOptions.Transport;
-            }
-
-            if (!string.IsNullOrEmpty(clientOptions.UserAgentApplicationId))
-            {
-                projectOptions.UserAgentApplicationId = clientOptions.UserAgentApplicationId;
-            }
-        }
-
-        projectOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
-
-        return new ProjectOpenAIClient(projectRoot, credential, projectOptions);
-    }
-
     /// <summary>
     /// Parses an agent endpoint URI of shape
     /// <c>https://&lt;host&gt;/.../projects/&lt;project&gt;/agents/&lt;agentName&gt;/endpoint/protocols/openai</c>
@@ -417,8 +385,7 @@ internal static (string AgentName, Uri ProjectRoot) ParseAgentEndpoint(Uri agent
         if (idx < 0)
         {
             throw new ArgumentException(
-                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'. " +
-                "If you want to construct a FoundryAgent against a project endpoint, use the (Uri projectEndpoint, AuthenticationTokenProvider credential, string model, string instructions, ...) constructor instead.",
+                $"Expected an agent endpoint of shape 'https://<host>/.../projects/<project>/agents/<agentName>/endpoint/protocols/openai' but got '{agentEndpoint}'.",
                 nameof(agentEndpoint));
         }
 
@@ -461,5 +428,19 @@ private static AIProjectClient CreateProjectClient(Uri endpoint, AuthenticationT
         return new AIProjectClient(endpoint, credential, clientOptions);
     }
 
+    private static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
+    {
+        if (clientOptions is null)
+        {
+            return null;
+        }
+
+        return new AIProjectClientOptions
+        {
+            Transport = clientOptions.Transport,
+            UserAgentApplicationId = clientOptions.UserAgentApplicationId,
+        };
+    }
+
     #endregion
 }
diff --git a/dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj b/dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj
index f5842f730c..6f1236e7b4 100644
--- a/dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj
+++ b/dotnet/tests/Foundry.Hosting.IntegrationTests/Foundry.Hosting.IntegrationTests.csproj
@@ -20,7 +20,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Azure.Search.Documents" />
     <PackageReference Include="Microsoft.Extensions.AI" />
diff --git a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
index e96cbdc487..7b01f8a79b 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
@@ -1380,6 +1380,87 @@ public void AsAIAgent_WithServerHostedTools_AddsToolsToAgentOptions()
 
     #endregion
 
+    #region AsAIAgent(AIProjectClient, Uri agentEndpoint) Tests
+
+    private const string TestAgentEndpointUrl = "https://test.services.ai.azure.com/api/projects/test-project/agents/it-happy-path/endpoint/protocols/openai";
+
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) throws ArgumentNullException when AIProjectClient is null.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_WithNullClient_ThrowsArgumentNullException()
+    {
+        // Arrange
+        AIProjectClient? client = null;
+
+        // Act & Assert
+        var exception = Assert.Throws<ArgumentNullException>(() =>
+            client!.AsAIAgent(new Uri(TestAgentEndpointUrl)));
+
+        Assert.Equal("aiProjectClient", exception.ParamName);
+    }
+
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) throws ArgumentNullException when agentEndpoint is null.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_WithNullEndpoint_ThrowsArgumentNullException()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+
+        // Act & Assert
+        var exception = Assert.Throws<ArgumentNullException>(() =>
+            client.AsAIAgent((Uri)null!));
+
+        Assert.Equal("agentEndpoint", exception.ParamName);
+    }
+
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) populates Name/Id from the parsed endpoint slug
+    /// and exposes the supplied <see cref="AIProjectClient"/> via <see cref="AIAgent.GetService{TService}(object?)"/>.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_PopulatesNameAndIdFromSlugAndReusesProjectClient()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+
+        // Act
+        var agent = client.AsAIAgent(new Uri(TestAgentEndpointUrl));
+
+        // Assert
+        Assert.NotNull(agent);
+        Assert.IsType<FoundryAgent>(agent);
+        Assert.Equal("it-happy-path", agent.Name);
+        Assert.Equal("it-happy-path", agent.Id);
+        Assert.Same(client, agent.GetService<AIProjectClient>());
+    }
+
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) applies the supplied client factory exactly once.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_WithClientFactory_AppliesFactoryCorrectly()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+        TestChatClient? testChatClient = null;
+
+        // Act
+        var agent = client.AsAIAgent(
+            new Uri(TestAgentEndpointUrl),
+            clientFactory: (innerClient) => testChatClient = new TestChatClient(innerClient));
+
+        // Assert
+        Assert.NotNull(agent);
+        var retrievedTestClient = agent.GetService<TestChatClient>();
+        Assert.NotNull(retrievedTestClient);
+        Assert.Same(testChatClient, retrievedTestClient);
+    }
+
+    #endregion
+
     #region Helper Methods
 
     /// <summary>
diff --git a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
index 01184031e8..4ccd1296c5 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
@@ -431,23 +431,23 @@ public void AgentEndpointConstructor_PopulatesNameAndIdFromEndpointSlug()
     }
 
     [Fact]
-    public void AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull()
+    public void AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNull()
     {
         FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
 
-        Assert.NotNull(agent.GetService<ProjectOpenAIClient>());
+        Assert.Null(agent.GetService<ProjectOpenAIClient>());
     }
 
     [Fact]
-    public void AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNull()
+    public void AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNonNull()
     {
         FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
 
-        Assert.Null(agent.GetService<AIProjectClient>());
+        Assert.NotNull(agent.GetService<AIProjectClient>());
     }
 
     [Fact]
-    public void ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull()
+    public void ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNull()
     {
         FoundryAgent agent = new(
             s_testEndpoint,
@@ -455,7 +455,7 @@ public void ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonN
             model: "gpt-4o-mini",
             instructions: "Test");
 
-        Assert.NotNull(agent.GetService<ProjectOpenAIClient>());
+        Assert.Null(agent.GetService<ProjectOpenAIClient>());
     }
 
     [Fact]
@@ -665,18 +665,14 @@ public void AgentEndpointConstructor_OverridesCallerEndpointAndAgentName()
     }
 
     [Fact]
-    public void AgentEndpointConstructor_PropagatesUserAgentApplicationId_ToProjectLevelClient()
+    public void AgentEndpointConstructor_PreservesUserAgentApplicationId()
     {
-        // The MEAI policy adds its own User-Agent header so we cannot reliably observe the OpenAI SDK's
-        // application-id stamp in the outbound request. Verify the value is propagated onto the
-        // project-level client's options via the public ProjectOpenAIClient surface.
         ProjectOpenAIClientOptions opts = new() { UserAgentApplicationId = "my-app-id" };
 
         FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
 
-        ProjectOpenAIClient? projectClient = agent.GetService<ProjectOpenAIClient>();
-        Assert.NotNull(projectClient);
         // Caller's UserAgentApplicationId is preserved on the per-agent options bag verbatim.
+        Assert.NotNull(agent);
         Assert.Equal("my-app-id", opts.UserAgentApplicationId);
     }
 

From 7d233b9bc8081731d11648f8e30795a0301c5076 Mon Sep 17 00:00:00 2001
From: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
Date: Fri, 15 May 2026 17:44:46 +0100
Subject: [PATCH 2/2] Address PR review: forward pipeline settings; add UTs

- CreateProjectClientOptions also carries RetryPolicy, NetworkTimeout, ClientLoggingOptions, MessageLoggingPolicy (was Transport+UserAgentApplicationId only).

- Make CreateProjectClientOptions internal so tests can verify the copy directly.

- Add AsAIAgent(Uri) UTs covering tools forwarding to inner ChatOptions and null tools handling.

- Add CreateProjectClientOptions UTs covering null caller and full pipeline-settings copy.
---
 .../FoundryAgent.cs                           | 17 ++++-
 ...AzureAIProjectChatClientExtensionsTests.cs | 46 ++++++++++++
 .../FoundryAgentTests.cs                      | 72 ++++++++++++++++++-
 3 files changed, 130 insertions(+), 5 deletions(-)

diff --git a/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs b/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
index 816d56302a..30bfc84d9a 100644
--- a/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Foundry/FoundryAgent.cs
@@ -428,18 +428,31 @@ private static AIProjectClient CreateProjectClient(Uri endpoint, AuthenticationT
         return new AIProjectClient(endpoint, credential, clientOptions);
     }
 
-    private static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
+    internal static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
     {
         if (clientOptions is null)
         {
             return null;
         }
 
-        return new AIProjectClientOptions
+        // Copy pipeline behavior the caller configured on the per-agent options bag onto the
+        // project-level options bag so the agent endpoint client honors it. UserAgentApplicationId
+        // is project-level (not derived from the agent endpoint), so it must be carried through too.
+        var projectOptions = new AIProjectClientOptions
         {
             Transport = clientOptions.Transport,
+            RetryPolicy = clientOptions.RetryPolicy,
+            NetworkTimeout = clientOptions.NetworkTimeout,
+            MessageLoggingPolicy = clientOptions.MessageLoggingPolicy,
             UserAgentApplicationId = clientOptions.UserAgentApplicationId,
         };
+
+        if (clientOptions.ClientLoggingOptions is not null)
+        {
+            projectOptions.ClientLoggingOptions = clientOptions.ClientLoggingOptions;
+        }
+
+        return projectOptions;
     }
 
     #endregion
diff --git a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
index 7b01f8a79b..2996be725d 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/AzureAIProjectChatClientExtensionsTests.cs
@@ -1459,6 +1459,52 @@ public void AsAIAgent_WithAgentEndpoint_WithClientFactory_AppliesFactoryCorrectl
         Assert.Same(testChatClient, retrievedTestClient);
     }
 
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) forwards the supplied tools to the inner
+    /// <see cref="ChatClientAgent"/>'s <see cref="ChatOptions.Tools"/>.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_ForwardsToolsToInnerChatOptions()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+        var tool1 = AIFunctionFactory.Create(() => "result-1", "tool_1", "First test tool.");
+        var tool2 = AIFunctionFactory.Create(() => "result-2", "tool_2", "Second test tool.");
+        List<AITool> tools = [tool1, tool2];
+
+        // Act
+        var agent = client.AsAIAgent(new Uri(TestAgentEndpointUrl), tools: tools);
+
+        // Assert
+        Assert.NotNull(agent);
+        ChatOptions? chatOptions = GetAgentChatOptions(agent);
+        Assert.NotNull(chatOptions);
+        Assert.NotNull(chatOptions!.Tools);
+        Assert.Equal(2, chatOptions.Tools!.Count);
+        Assert.Same(tool1, chatOptions.Tools[0]);
+        Assert.Same(tool2, chatOptions.Tools[1]);
+    }
+
+    /// <summary>
+    /// Verify that AsAIAgent(Uri agentEndpoint) accepts a null tools argument without throwing
+    /// and produces an agent whose inner <see cref="ChatOptions.Tools"/> is null.
+    /// </summary>
+    [Fact]
+    public void AsAIAgent_WithAgentEndpoint_WithNullTools_DoesNotThrow()
+    {
+        // Arrange
+        AIProjectClient client = this.CreateTestAgentClient();
+
+        // Act
+        var agent = client.AsAIAgent(new Uri(TestAgentEndpointUrl), tools: null);
+
+        // Assert
+        Assert.NotNull(agent);
+        ChatOptions? chatOptions = GetAgentChatOptions(agent);
+        Assert.NotNull(chatOptions);
+        Assert.Null(chatOptions!.Tools);
+    }
+
     #endregion
 
     #region Helper Methods
diff --git a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
index 4ccd1296c5..11f36c2797 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/FoundryAgentTests.cs
@@ -2,6 +2,7 @@
 
 using System;
 using System.ClientModel.Primitives;
+using System.Collections.Generic;
 using System.Net;
 using System.Net.Http;
 using System.Text;
@@ -356,7 +357,7 @@ public async Task Constructor_UserAgentHeaderAddedToRequestsAsync()
         bool userAgentFound = false;
         using HttpHandlerAssert httpHandler = new(request =>
         {
-            if (request.Headers.TryGetValues("User-Agent", out System.Collections.Generic.IEnumerable<string>? values))
+            if (request.Headers.TryGetValues("User-Agent", out IEnumerable<string>? values))
             {
                 foreach (string value in values)
                 {
@@ -676,6 +677,71 @@ public void AgentEndpointConstructor_PreservesUserAgentApplicationId()
         Assert.Equal("my-app-id", opts.UserAgentApplicationId);
     }
 
+    [Fact]
+    public void CreateProjectClientOptions_NullCallerOptions_ReturnsNull()
+    {
+        Assert.Null(FoundryAgent.CreateProjectClientOptions(null));
+    }
+
+    [Fact]
+    public void CreateProjectClientOptions_CarriesPipelineSettingsAndUserAgent()
+    {
+        // Arrange
+        var transport = new FakePipelineTransport();
+        var retryPolicy = new FakeRetryPolicy();
+        var messageLoggingPolicy = new FakeMessageLoggingPolicy();
+        var clientLoggingOptions = new ClientLoggingOptions { EnableLogging = false };
+        var networkTimeout = TimeSpan.FromSeconds(42);
+
+        ProjectOpenAIClientOptions callerOptions = new()
+        {
+            UserAgentApplicationId = "my-app-id",
+            Transport = transport,
+            RetryPolicy = retryPolicy,
+            MessageLoggingPolicy = messageLoggingPolicy,
+            ClientLoggingOptions = clientLoggingOptions,
+            NetworkTimeout = networkTimeout,
+        };
+
+        // Act
+        AIProjectClientOptions? projectOptions = FoundryAgent.CreateProjectClientOptions(callerOptions);
+
+        // Assert: every settable pipeline behavior the caller configured is forwarded
+        // onto the project-level options bag, not silently dropped.
+        Assert.NotNull(projectOptions);
+        Assert.Equal("my-app-id", projectOptions!.UserAgentApplicationId);
+        Assert.Same(transport, projectOptions.Transport);
+        Assert.Same(retryPolicy, projectOptions.RetryPolicy);
+        Assert.Same(messageLoggingPolicy, projectOptions.MessageLoggingPolicy);
+        Assert.Same(clientLoggingOptions, projectOptions.ClientLoggingOptions);
+        Assert.Equal(networkTimeout, projectOptions.NetworkTimeout);
+    }
+
+    private sealed class FakeRetryPolicy : PipelinePolicy
+    {
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+            => ProcessNext(message, pipeline, currentIndex);
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+            => ProcessNextAsync(message, pipeline, currentIndex);
+    }
+
+    private sealed class FakeMessageLoggingPolicy : PipelinePolicy
+    {
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+            => ProcessNext(message, pipeline, currentIndex);
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+            => ProcessNextAsync(message, pipeline, currentIndex);
+    }
+
+    private sealed class FakePipelineTransport : PipelineTransport
+    {
+        protected override PipelineMessage CreateMessageCore() => throw new NotSupportedException();
+        protected override void ProcessCore(PipelineMessage message) => throw new NotSupportedException();
+        protected override ValueTask ProcessCoreAsync(PipelineMessage message) => throw new NotSupportedException();
+    }
+
     #endregion
 
     #region ParseAgentEndpoint tests
@@ -758,13 +824,13 @@ private sealed class HeaderStampPolicy : PipelinePolicy
         private readonly string _value;
         public HeaderStampPolicy(string name, string value) { this._name = name; this._value = value; }
 
-        public override void Process(PipelineMessage message, System.Collections.Generic.IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
         {
             message.Request.Headers.Set(this._name, this._value);
             ProcessNext(message, pipeline, currentIndex);
         }
 
-        public override ValueTask ProcessAsync(PipelineMessage message, System.Collections.Generic.IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
         {
             message.Request.Headers.Set(this._name, this._value);
             return ProcessNextAsync(message, pipeline, currentIndex);