.NET: Bump Azure.AI.Projects to 2.1.0-beta.2 and add agent-endpoint AsAIAgent path (#5899)

* .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. * 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.
2026-06-16 21:04:09 +08:00 · 2026-05-18 21:20:56 +01:00
parent dff23a9413
commit aad20c2b33
25 changed files with 469 additions and 198 deletions
@@ -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" />
@@ -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
@@ -14,6 +14,7 @@ using Azure.Identity;
 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 @@ AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
 // 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();

@@ -46,10 +46,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -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
@@ -35,6 +35,7 @@ using Azure.AI.Projects;
 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 @@ AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)

 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();

@@ -39,10 +39,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -118,10 +118,10 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();

@@ -87,10 +87,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -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>
@@ -79,10 +79,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -1,7 +1,6 @@
 .env
 bin/
 obj/
-out/
 .vs/
 .vscode/
 *.user
@@ -66,9 +66,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -53,10 +53,10 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();

@@ -69,10 +69,10 @@ builder.Services.AddFoundryToolboxes(toolboxName);
 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();

@@ -55,9 +55,9 @@ builder.Services.AddDevTemporaryLocalContributorSetup(); // Local Docker debuggi
 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();
@@ -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;
+    }
+}
@@ -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 @@ using Microsoft.Agents.AI.Foundry;
 // 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 @@ AgentSession session = await agent.CreateSessionAsync();
 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();
@@ -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
 ```

@@ -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 @@ using Microsoft.Agents.AI.Foundry;
 // 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 @@ AgentSession session = await agent.CreateSessionAsync();
 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();
@@ -66,6 +66,42 @@ public static partial class AzureAIProjectChatClientExtensions
        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>
@@ -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 sealed class FoundryAgent : DelegatingAIAgent
            out var aiProjectClient))
    {
        this._aiProjectClient = aiProjectClient;
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
    }

    /// <summary>
@@ -106,11 +87,9 @@ public sealed class FoundryAgent : DelegatingAIAgent
    /// </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 sealed class FoundryAgent : DelegatingAIAgent
        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._projectOpenAIClient = CreateProjectLevelOpenAIClientFromAgentEndpoint(agentEndpoint, credential, clientOptions);
+        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._aiProjectClient = Throw.IfNull(aiProjectClient);
    }

    /// <summary>
@@ -146,7 +150,6 @@ public sealed class FoundryAgent : DelegatingAIAgent
        : base(WireClientHeaders(Throw.IfNull(innerAgent)))
    {
        this._aiProjectClient = Throw.IfNull(aiProjectClient);
-        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
    }

    #region Convenience methods
@@ -179,7 +182,7 @@ public sealed class FoundryAgent : DelegatingAIAgent
    /// <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 @@ public sealed class FoundryAgent : DelegatingAIAgent
            return this._aiProjectClient;
        }

-        if (serviceKey is null && serviceType == typeof(ProjectOpenAIClient))
-        {
-            return this._projectOpenAIClient;
-        }
-
        return base.GetService(serviceType, serviceKey);
    }

@@ -291,11 +289,10 @@ public sealed class FoundryAgent : DelegatingAIAgent

    /// <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 @@ public sealed class FoundryAgent : DelegatingAIAgent
        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 @@ public sealed class FoundryAgent : DelegatingAIAgent
        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 @@ public sealed class FoundryAgent : DelegatingAIAgent
        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,32 @@ public sealed class FoundryAgent : DelegatingAIAgent
        return new AIProjectClient(endpoint, credential, clientOptions);
    }

+    internal static AIProjectClientOptions? CreateProjectClientOptions(ProjectOpenAIClientOptions? clientOptions)
+    {
+        if (clientOptions is null)
+        {
+            return null;
+        }
+
+        // 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
 }
@@ -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" />
@@ -1380,6 +1380,133 @@ public sealed class AzureAIProjectChatClientExtensionsTests

    #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);
+    }
+
+    /// <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

    /// <summary>
@@ -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 class FoundryAgentTests
        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)
                {
@@ -431,23 +432,23 @@ public class FoundryAgentTests
    }

    [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 +456,7 @@ public class FoundryAgentTests
            model: "gpt-4o-mini",
            instructions: "Test");

-        Assert.NotNull(agent.GetService<ProjectOpenAIClient>());
+        Assert.Null(agent.GetService<ProjectOpenAIClient>());
    }

    [Fact]
@@ -665,21 +666,82 @@ public class FoundryAgentTests
    }

    [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);
    }

+    [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
@@ -762,13 +824,13 @@ public class FoundryAgentTests
        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);