.NET: dotnet: Add hosted-agent User-Agent supplement to outgoing requests

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/AgentFrameworkResponseHandler.cs

@@ -297,6 +297,7 @@ private AIAgent ResolveAgent(CreateResponse request)
             var agent = this._serviceProvider.GetKeyedService<AIAgent>(agentName);
             if (agent is not null)
             {
+                FoundryHostingExtensions.TryApplyUserAgent(agent);
                 return FoundryHostingExtensions.ApplyOpenTelemetry(agent);
             }
 
@@ -310,12 +311,13 @@ private AIAgent ResolveAgent(CreateResponse request)
         var defaultAgent = this._serviceProvider.GetService<AIAgent>();
         if (defaultAgent is not null)
         {
+            FoundryHostingExtensions.TryApplyUserAgent(defaultAgent);
             return FoundryHostingExtensions.ApplyOpenTelemetry(defaultAgent);
         }
 
         var errorMessage = string.IsNullOrEmpty(agentName)
             ? "No agent name specified in the request (via agent.name or metadata[\"entity_id\"]) and no default AIAgent is registered."
-            : $"Agent '{agentName}' not found. Ensure it is registered via AddAIAgent(\"{agentName}\", ...) or as a default AIAgent.";
+            : $"Agent '{agentName}' not found. Ensure it is registered via AddFoundryResponses(services, agent) or services.AddKeyedSingleton<AIAgent>(\"{agentName}\", ...).";
 
         throw new InvalidOperationException(errorMessage);
     }
@@ -352,7 +354,7 @@ private AgentSessionStore ResolveSessionStore(CreateResponse request)
 
         var errorMessage = string.IsNullOrEmpty(agentName)
             ? "No agent name specified in the request (via agent.name or metadata[\"entity_id\"]) and no default AgentSessionStore is registered."
-            : $"Agent '{agentName}' not found. Ensure it is registered via AddAIAgent(\"{agentName}\", ...) or as a default AgentSessionStore.";
+            : $"AgentSessionStore for agent '{agentName}' not found. Ensure it is registered via AddFoundryResponses(services, agent, agentSessionStore) or services.AddKeyedSingleton<AgentSessionStore>(\"{agentName}\", ...).";
 
         throw new InvalidOperationException(errorMessage);
     }

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/DelegatingResponsesClient.cs

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using OpenAI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001, SCME0001
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// A <see cref="ResponsesClient"/> subclass that delegates every protocol-level request to a
+/// wrapped <see cref="ResponsesClient"/>. Before each call, a
+/// <see cref="HostedAgentUserAgentPolicy"/> is added to the per-call
+/// <see cref="RequestOptions"/> so the wrapped client's pipeline appends the hosted-agent
+/// <c>User-Agent</c> segment on the wire.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The streaming overloads MEAI binds via reflection (<c>internal CreateResponseStreamingAsync(CreateResponseOptions, RequestOptions)</c>
+/// and <c>internal GetResponseStreamingAsync(GetResponseOptions, RequestOptions)</c>) bottom out
+/// in calls to the public-virtual non-streaming protocol overloads on <see langword="this"/>. Overriding those
+/// non-streaming overloads is therefore sufficient to intercept both streaming and non-streaming traffic.
+/// </para>
+/// <para>
+/// The base pipeline supplied to <see cref="ResponsesClient(ClientPipeline, OpenAIClientOptions)"/>
+/// is a dummy pipeline whose terminal transport throws if invoked. Every override on this class
+/// delegates to the inner client BEFORE any code path reaches <see cref="ResponsesClient.Pipeline"/>, so the dummy is
+/// never expected to run; the throwing transport surfaces any unexpected escape route loudly.
+/// </para>
+/// </remarks>
+internal sealed class DelegatingResponsesClient : ResponsesClient
+{
+    private readonly ResponsesClient _inner;
+
+    public DelegatingResponsesClient(ResponsesClient inner)
+        : base(BuildDummyPipeline(), new OpenAIClientOptions { Endpoint = inner?.Endpoint })
+    {
+        this._inner = inner ?? throw new ArgumentNullException(nameof(inner));
+    }
+
+    public override async Task<ClientResult> CreateResponseAsync(BinaryContent content, RequestOptions? options = null)
+        => await this._inner.CreateResponseAsync(content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CreateResponse(BinaryContent content, RequestOptions? options = null)
+        => this._inner.CreateResponse(content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetResponseAsync(string responseId, IEnumerable<IncludedResponseProperty>? include, bool? stream, int? startingAfter, bool? includeObfuscation, RequestOptions options)
+        => await this._inner.GetResponseAsync(responseId, include, stream, startingAfter, includeObfuscation, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetResponse(string responseId, IEnumerable<IncludedResponseProperty>? include, bool? stream, int? startingAfter, bool? includeObfuscation, RequestOptions options)
+        => this._inner.GetResponse(responseId, include, stream, startingAfter, includeObfuscation, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> DeleteResponseAsync(string responseId, RequestOptions options)
+        => await this._inner.DeleteResponseAsync(responseId, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult DeleteResponse(string responseId, RequestOptions options)
+        => this._inner.DeleteResponse(responseId, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> CancelResponseAsync(string responseId, RequestOptions options)
+        => await this._inner.CancelResponseAsync(responseId, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CancelResponse(string responseId, RequestOptions options)
+        => this._inner.CancelResponse(responseId, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetInputTokenCountAsync(string contentType, BinaryContent content, RequestOptions? options = null)
+        => await this._inner.GetInputTokenCountAsync(contentType, content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetInputTokenCount(string contentType, BinaryContent content, RequestOptions? options = null)
+        => this._inner.GetInputTokenCount(contentType, content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> CompactResponseAsync(string contentType, BinaryContent content, RequestOptions? options = null)
+        => await this._inner.CompactResponseAsync(contentType, content, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult CompactResponse(string contentType, BinaryContent content, RequestOptions? options = null)
+        => this._inner.CompactResponse(contentType, content, AddUserAgentPolicy(options));
+
+    public override async Task<ClientResult> GetResponseInputItemCollectionPageAsync(string responseId, int? limit, string order, string after, string before, RequestOptions options)
+        => await this._inner.GetResponseInputItemCollectionPageAsync(responseId, limit, order, after, before, AddUserAgentPolicy(options)).ConfigureAwait(false);
+
+    public override ClientResult GetResponseInputItemCollectionPage(string responseId, int? limit, string order, string after, string before, RequestOptions options)
+        => this._inner.GetResponseInputItemCollectionPage(responseId, limit, order, after, before, AddUserAgentPolicy(options));
+
+    private static RequestOptions AddUserAgentPolicy(RequestOptions? options)
+    {
+        options ??= new RequestOptions();
+        options.AddPolicy(HostedAgentUserAgentPolicy.Instance, PipelinePosition.PerCall);
+        return options;
+    }
+
+    private static ClientPipeline BuildDummyPipeline()
+    {
+        var options = new ClientPipelineOptions
+        {
+            Transport = new ThrowingTransport(),
+        };
+        return ClientPipeline.Create(options, default, default, default);
+    }
+
+    private sealed class ThrowingTransport : PipelineTransport
+    {
+        private const string Message =
+            "DelegatingResponsesClient transport invoked bypassed the override-and-delegate design. This exception should be unreachable and should never be thrown following the correct usage of DelegatingResponsesClient.";
+
+        protected override PipelineMessage CreateMessageCore() => throw new InvalidOperationException(Message);
+        protected override void ProcessCore(PipelineMessage message) => throw new InvalidOperationException(Message);
+        protected override ValueTask ProcessCoreAsync(PipelineMessage message) => throw new InvalidOperationException(Message);
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/HostedAgentUserAgentPolicy.cs

@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Pipeline policy that appends the hosted-agent <c>User-Agent</c> segment
+/// (e.g. <c>"foundry-hosting/agent-framework-dotnet/{version}"</c>) to outgoing requests.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The supplement value is computed once from the Microsoft.Agents.AI.Foundry.Hosting
+/// assembly's informational version. The policy is idempotent on retries: if the segment
+/// is already present in the <c>User-Agent</c> header, the policy does not append it again.
+/// </para>
+/// <para>
+/// This policy is added at request time (per-call <see cref="PipelinePosition"/>)
+/// by <see cref="DelegatingResponsesClient"/> when invoking the wrapped
+/// <see cref="OpenAI.Responses.ResponsesClient"/>. It is only registered when an agent is
+/// resolved by the Foundry hosting layer.
+/// </para>
+/// </remarks>
+internal sealed class HostedAgentUserAgentPolicy : PipelinePolicy
+{
+    public static HostedAgentUserAgentPolicy Instance { get; } = new HostedAgentUserAgentPolicy();
+
+    private static readonly string s_supplementValue = CreateSupplementValue();
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override async ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        AppendHeader(message);
+        await ProcessNextAsync(message, pipeline, currentIndex).ConfigureAwait(false);
+    }
+
+    private static void AppendHeader(PipelineMessage message)
+    {
+        if (message.Request.Headers.TryGetValue("User-Agent", out var existing) && !string.IsNullOrEmpty(existing))
+        {
+            // Guard against double-append on retries or when the policy
+            // is registered on multiple pipeline positions.
+            if (existing.Contains(s_supplementValue))
+            {
+                return;
+            }
+
+            message.Request.Headers.Set("User-Agent", $"{existing} {s_supplementValue}");
+        }
+        else
+        {
+            message.Request.Headers.Set("User-Agent", s_supplementValue);
+        }
+    }
+
+    private static string CreateSupplementValue()
+    {
+        const string Name = "foundry-hosting/agent-framework-dotnet";
+
+        if (typeof(HostedAgentUserAgentPolicy).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
+        {
+            int pos = version.IndexOf('+');
+            if (pos >= 0)
+            {
+                version = version.Substring(0, pos);
+            }
+
+            if (version.Length > 0)
+            {
+                return $"{Name}/{version}";
+            }
+        }
+
+        return Name;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/ServiceCollectionExtensions.cs

@@ -3,16 +3,15 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
-using System.Threading.Tasks;
 using Azure.AI.AgentServer.Responses;
 using Azure.Core;
 using Azure.Identity;
-using Microsoft.AspNetCore.Builder;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Shared.DiagnosticIds;
+using OpenAI.Responses;
 
 namespace Microsoft.Agents.AI.Foundry.Hosting;
 
@@ -36,7 +35,7 @@ public static class FoundryHostingExtensions
     /// <para>
     /// Example:
     /// <code>
-    /// builder.AddAIAgent("my-agent", ...);
+    /// builder.Services.AddKeyedSingleton&lt;AIAgent&gt;("my-agent", myAgent);
     /// builder.Services.AddFoundryResponses();
     ///
     /// var app = builder.Build();
@@ -181,13 +180,6 @@ public static IEndpointRouteBuilder MapFoundryResponses(this IEndpointRouteBuild
     {
         ArgumentNullException.ThrowIfNull(endpoints);
         endpoints.MapResponsesServer(prefix);
-
-        if (endpoints is IApplicationBuilder app)
-        {
-            // Ensure the middleware is added to the pipeline
-            app.UseMiddleware<AgentFrameworkUserAgentMiddleware>();
-        }
-
         return endpoints;
     }
 
@@ -216,46 +208,85 @@ internal static AIAgent ApplyOpenTelemetry(AIAgent agent)
                     .Build();
     }
 
-    private sealed class AgentFrameworkUserAgentMiddleware(RequestDelegate next)
+    /// <summary>
+    /// Attempts to wrap the agent's underlying <see cref="ResponsesClient"/>
+    /// with a <see cref="DelegatingResponsesClient"/> so every outgoing Responses-API request
+    /// carries the hosted-agent <c>User-Agent</c> segment.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Best-effort and idempotent. The method is a no-op when:
+    /// <list type="bullet">
+    /// <item><description><paramref name="agent"/> exposes no <see cref="IChatClient"/>;</description></item>
+    /// <item><description>the chat client is not backed by MEAI's internal <c>OpenAIResponsesChatClient</c> (e.g., a non-OpenAI provider or a custom impl);</description></item>
+    /// <item><description>the inner <see cref="ResponsesClient"/> is already a <see cref="DelegatingResponsesClient"/>.</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// Works for any <see cref="ResponsesClient"/>-derived inner client — both the Foundry-specific
+    /// <see cref="Azure.AI.Extensions.OpenAI.ProjectResponsesClient"/> and the native OpenAI
+    /// <see cref="ResponsesClient"/> obtained from <see cref="OpenAI.OpenAIClient"/>. The wrapper preserves
+    /// the inner client's pipeline (Transport, RetryPolicy, NetworkTimeout, OrganizationId / ProjectId /
+    /// UserAgentApplicationId, custom policies) because every override delegates to the inner instance.
+    /// </para>
+    /// <para>
+    /// Returns the same <paramref name="agent"/> instance unchanged. Mutation happens via
+    /// reflection on MEAI's private <c>_responseClient</c> field; the agent itself is not wrapped.
+    /// </para>
+    /// </remarks>
+    internal static AIAgent TryApplyUserAgent(AIAgent agent)
     {
-        private static readonly string s_userAgentValue = CreateUserAgentValue();
+        var chatClient = agent.GetService<IChatClient>();
+        if (chatClient is null)
+        {
+            return agent;
+        }
 
-        public async Task InvokeAsync(HttpContext context)
+        var meaiType = s_meaiResponsesChatClientType;
+        if (meaiType is null)
         {
-            var headers = context.Request.Headers;
-            var userAgent = headers.UserAgent.ToString();
+            return agent;
+        }
 
-            if (string.IsNullOrEmpty(userAgent))
-            {
-                headers.UserAgent = s_userAgentValue;
-            }
-            else if (!userAgent.Contains(s_userAgentValue, StringComparison.OrdinalIgnoreCase))
-            {
-                headers.UserAgent = $"{userAgent} {s_userAgentValue}";
-            }
+        var meaiInstance = chatClient.GetService(meaiType);
+        if (meaiInstance is null)
+        {
+            return agent;
+        }
 
-            await next(context).ConfigureAwait(false);
+        var field = s_meaiResponseClientField;
+        if (field is null)
+        {
+            return agent;
         }
 
-        private static string CreateUserAgentValue()
+        var current = field.GetValue(meaiInstance) as ResponsesClient;
+        if (current is null or DelegatingResponsesClient)
         {
-            const string Name = "agent-framework-dotnet";
+            return agent;
+        }
 
-            if (typeof(AgentFrameworkUserAgentMiddleware).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion is string version)
-            {
-                int pos = version.IndexOf('+');
-                if (pos >= 0)
-                {
-                    version = version.Substring(0, pos);
-                }
+        field.SetValue(meaiInstance, new DelegatingResponsesClient(current));
+        return agent;
+    }
 
-                if (version.Length > 0)
-                {
-                    return $"{Name}/{version}";
-                }
-            }
+    /// <summary>
+    /// MEAI's internal <c>OpenAIResponsesChatClient</c> type, resolved once via reflection.
+    /// <see langword="null"/> if the type cannot be found (e.g., MEAI version drift).
+    /// </summary>
+    [UnconditionalSuppressMessage("Trimming", "IL2026:RequiresUnreferencedCode",
+        Justification = "MEAI's OpenAIResponsesChatClient is referenced through MicrosoftExtensionsAIResponsesExtensions and survives trimming.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2073:RequiresUnreferencedCode",
+        Justification = "MEAI's OpenAIResponsesChatClient is referenced through MicrosoftExtensionsAIResponsesExtensions and survives trimming.")]
+    private static readonly Type? s_meaiResponsesChatClientType =
+        typeof(MicrosoftExtensionsAIResponsesExtensions).Assembly.GetType("Microsoft.Extensions.AI.OpenAIResponsesChatClient");
 
-            return Name;
-        }
-    }
+    /// <summary>
+    /// MEAI's internal <c>_responseClient</c> field on <c>OpenAIResponsesChatClient</c>,
+    /// resolved once via reflection. <see langword="null"/> if the field cannot be found.
+    /// </summary>
+    [UnconditionalSuppressMessage("Trimming", "IL2080:RequiresDynamicallyAccessedMembers",
+        Justification = "OpenAIResponsesChatClient and its private fields are preserved by the polyfill design; MEAI does the same reflection internally.")]
+    private static readonly FieldInfo? s_meaiResponseClientField =
+        s_meaiResponsesChatClientType?.GetField("_responseClient", BindingFlags.NonPublic | BindingFlags.Instance);
 }