test: Add unit tests for Handoff FunctionCall/Result matching fix

fix: Synthesized Handoff FunctionResult is never sent to agent
When we receive a handoff request from the agent, we need to service it outside of the Agent Loop to terminate the loop. What this means is that we take ownership of terminating the call by feeding the result back into the agent on a subsequent invocation. When we refactored Handoff to support HITL and make use of AgentSession, we inadvertantly removed this step, causing subsequent invocations to the Handoff agent to fail (first works, but breaks the state). The fix is to be more precise about the agent's bookmark when concatenating the result of agent invocation to the shared conversation history.
2026-06-16 21:04:09 +08:00 · 2026-05-08 14:52:11 -04:00 · 2026-05-08 14:34:48 -04:00 · 2026-05-08 14:29:03 -04:00 · 2026-05-08 17:16:03 +00:00 · 2026-05-08 14:46:52 +00:00
26 changed files with 2883 additions and 983 deletions
@@ -25,7 +25,7 @@
    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
    <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.AI.Projects" Version="2.0.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.1.0-beta.1" />
    <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" />
@@ -30,7 +30,8 @@
      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
      "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
-      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj",
+      "src\\Microsoft.Agents.AI.Hyperlight\\Microsoft.Agents.AI.Hyperlight.csproj"
    ]
  }
 }
@@ -1,14 +1,14 @@
 <Project>
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.4.0</VersionPrefix>
+    <VersionPrefix>1.5.0</VersionPrefix>
    <RCNumber>1</RCNumber>
-    <DateSuffix>260505</DateSuffix>
+    <DateSuffix>260507</DateSuffix>
    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
    <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.4.0</GitTag>
+    <GitTag>1.5.0</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -8,6 +8,11 @@
 // even if the process is interrupted mid-loop, but may also result in chat history that is not
 // yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
 //
+// Additionally, this sample demonstrates the MessageInjectingChatClient feature, which allows tool
+// code to inject new user messages during the function execution loop. When a tool or anything else enqueues
+// a message via MessageInjectingChatClient.EnqueueMessages during the tool execution loop, the PerServiceCallChatHistoryPersistingChatClient
+// detects the pending message before the next service call and includes the injected message in the request.
+//
 // To use end-of-run persistence instead (atomic run semantics), remove the
 // RequirePerServiceCallChatHistoryPersistence = true setting (or set it to false). End-of-run
 // persistence is the default behavior.
@@ -54,6 +59,37 @@ static string GetTime([Description("The city name.")] string city) =>
        _ => $"{city}: time data not available."
    };

+// This tool demonstrates message injection during the function execution loop.
+// When called, it checks travel advisories for a city. If an advisory is active, it uses
+// the ambient run context to resolve MessageInjectingChatClient and injects a follow-up user message
+// asking for alternative destinations. The model will process this injected message on the next
+// service call — even though the parent FunctionInvokingChatClient loop would otherwise stop.
+[Description("Check current travel advisories for a city.")]
+static string CheckTravelAdvisory([Description("The city name.")] string city)
+{
+    // Simulated travel advisory data.
+    var advisory = city.ToUpperInvariant() switch
+    {
+        "LONDON" => "Travel advisory: Severe fog warnings in London. Flights may be delayed or cancelled.",
+        "SEATTLE" => "Travel advisory: Heavy rainfall expected. Flooding possible in low-lying areas.",
+        _ => null
+    };
+
+    if (advisory is null)
+    {
+        return $"{city}: No active travel advisories.";
+    }
+
+    // When an advisory is found, inject a follow-up question so the model automatically
+    // suggests alternatives without the user needing to ask.
+    var runContext = AIAgent.CurrentRunContext!;
+    runContext.Agent.GetService<MessageInjectingChatClient>()?.EnqueueMessages(
+        runContext.Session!,
+        [new ChatMessage(ChatRole.User, $"Given the travel advisory for {city}, what alternative cities would you recommend instead?")]);
+
+    return advisory;
+}
+
 // Create the agent — per-service-call persistence is enabled via RequirePerServiceCallChatHistoryPersistence.
 // The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
 // history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
@@ -65,10 +101,11 @@ AIAgent agent = chatClient.AsAIAgent(
    {
        Name = "WeatherAssistant",
        RequirePerServiceCallChatHistoryPersistence = true,
+        EnableMessageInjection = true,
        ChatOptions = new()
        {
-            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
-            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
+            Instructions = "You are a helpful travel assistant. When asked about cities, call the appropriate tools for each city.",
+            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime), AIFunctionFactory.Create(CheckTravelAdvisory)]
        },
    });

@@ -109,6 +146,18 @@ async Task RunNonStreamingAsync()
    response = await agent.RunAsync(FollowUp2, session);
    PrintAgentResponse(response.Text);
    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop.
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    response = await agent.RunAsync(TravelPrompt, session);
+    PrintAgentResponse(response.Text);
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }

 async Task RunStreamingAsync()
@@ -181,6 +230,30 @@ async Task RunStreamingAsync()

    Console.WriteLine();
    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
+
+    // Fourth turn — demonstrates message injection during the function loop (streaming).
+    // The CheckTravelAdvisory tool detects an advisory for London and injects a follow-up
+    // user message asking for alternative cities. After the tool completes, the internal loop
+    // in PerServiceCallChatHistoryPersistingChatClient detects the pending injected message
+    // and calls the service again, so the model answers the follow-up automatically.
+    const string TravelPrompt = "I'm planning to travel to London next week. Check if there are any travel advisories.";
+    PrintUserMessage(TravelPrompt);
+
+    Console.ForegroundColor = ConsoleColor.Cyan;
+    Console.Write("\n[Agent] ");
+    Console.ResetColor();
+
+    await foreach (var update in agent.RunStreamingAsync(TravelPrompt, session))
+    {
+        Console.Write(update);
+
+        // During streaming we should be able to see updates to the chat history
+        // before the full run completes, as each service call is made and persisted.
+        PrintChatHistory(session, "During travel advisory run", ref lastChatHistorySize, ref lastConversationId);
+    }
+
+    Console.WriteLine();
+    PrintChatHistory(session, "After travel advisory run", ref lastChatHistorySize, ref lastConversationId);
 }

 void PrintUserMessage(string message)
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
@@ -11,7 +11,7 @@

  <ItemGroup>
    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
  </ItemGroup>

 </Project>
@@ -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>
@@ -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="ModelContextProtocol" VersionOverride="1.2.0" />
    <PackageReference Include="DotNetEnv" />
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
@@ -31,7 +31,7 @@

  <ItemGroup>
    <PackageReference Include="Azure.AI.AgentServer.Responses" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.Identity" />
    <PackageReference Include="ModelContextProtocol" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
@@ -2,6 +2,7 @@

 using System;
 using System.ClientModel;
+using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Threading;
@@ -38,7 +39,28 @@ namespace Microsoft.Agents.AI.Foundry;
 [Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public sealed class FoundryAgent : DelegatingAIAgent
 {
-    private readonly AIProjectClient _aiProjectClient;
+    /// <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.
+    /// </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;

    /// <summary>
    /// Initializes a new instance of the <see cref="FoundryAgent"/> class using the direct Responses API path.
@@ -72,30 +94,49 @@ public sealed class FoundryAgent : DelegatingAIAgent
            out var aiProjectClient))
    {
        this._aiProjectClient = aiProjectClient;
+        this._projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="FoundryAgent"/> class from an agent-specific endpoint.
    /// </summary>
-    /// <param name="agentEndpoint">The agent-specific endpoint URI (must contain the agent name in the path).</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="credential">The authentication credential.</param>
-    /// <param name="clientOptions">Optional configuration options for the <see cref="AIProjectClient"/>.</param>
+    /// <param name="clientOptions">
+    /// Optional configuration for the underlying <see cref="ProjectOpenAIClient"/>. 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>
    /// <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="agentEndpoint"/> or <paramref name="credential"/> is null.</exception>
+    /// <exception cref="ArgumentException"><paramref name="agentEndpoint"/> does not match the expected agent-endpoint shape.</exception>
+    /// <remarks>
+    /// This is the lightweight constructor for invoking an existing Foundry hosted agent when the
+    /// caller already has the per-agent endpoint URL. It populates <see cref="ChatClientAgentOptions.Id"/>
+    /// and <see cref="ChatClientAgentOptions.Name"/> from the agent name parsed out of the endpoint
+    /// path; <c>Description</c>, <c>Instructions</c>, <c>Temperature</c>, and <c>TopP</c> are not
+    /// populated. Callers that need those fields hydrated from server-side state should use
+    /// <c>AIProjectClient.AsAIAgent(ProjectsAgentVersion)</c> or
+    /// <c>AIProjectClient.AsAIAgent(ProjectsAgentRecord)</c> instead.
+    /// </remarks>
    public FoundryAgent(
        Uri agentEndpoint,
        AuthenticationTokenProvider credential,
-        AIProjectClientOptions? clientOptions = null,
+        ProjectOpenAIClientOptions? clientOptions = null,
        IList<AITool>? tools = null,
        Func<IChatClient, IChatClient>? clientFactory = null,
        IServiceProvider? services = null)
-        : base(CreateInnerAgentFromEndpoint(
-            CreateProjectClient(agentEndpoint, credential, clientOptions),
-            agentEndpoint, tools, clientFactory, services,
-            out var aiProjectClient))
+        : base(CreateInnerAgentFromAgentEndpoint(agentEndpoint, credential, clientOptions, tools, clientFactory, services))
    {
-        this._aiProjectClient = aiProjectClient;
+        this._projectOpenAIClient = CreateProjectLevelOpenAIClientFromAgentEndpoint(agentEndpoint, credential, clientOptions);
    }

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

    #region Convenience methods
@@ -137,9 +179,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._aiProjectClient
-            .GetProjectOpenAIClient()
-            .GetProjectConversationsClient();
+        var conversationsClient = this._projectOpenAIClient.GetProjectConversationsClient();

        var conversation = (await conversationsClient.CreateProjectConversationAsync(options: null, cancellationToken).ConfigureAwait(false)).Value;

@@ -161,6 +201,11 @@ public sealed class FoundryAgent : DelegatingAIAgent
            return this._aiProjectClient;
        }

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

@@ -238,47 +283,181 @@ public sealed class FoundryAgent : DelegatingAIAgent
            OpenAIRequestPoliciesReflection.AddPolicyIfMissing(
                policies,
                ClientHeadersPolicy.Instance,
-                System.ClientModel.Primitives.PipelinePosition.PerCall);
+                PipelinePosition.PerCall);
        }

        return new ClientHeadersAgent(innerAgent);
    }

-    private static AIAgent CreateInnerAgentFromEndpoint(
-        AIProjectClient aiProjectClient,
+    /// <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.
+    /// 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
+    /// <paramref name="agentEndpoint"/>; any policies the caller added via <c>AddPolicy</c>
+    /// remain in effect on the per-agent pipeline. The MEAI user-agent policy is appended last.
+    /// </summary>
+    private static AIAgent CreateInnerAgentFromAgentEndpoint(
        Uri agentEndpoint,
+        AuthenticationTokenProvider credential,
+        ProjectOpenAIClientOptions? clientOptions,
        IList<AITool>? tools,
        Func<IChatClient, IChatClient>? clientFactory,
-        IServiceProvider? services,
-        out AIProjectClient outClient)
+        IServiceProvider? services)
    {
-        outClient = aiProjectClient;
+        Throw.IfNull(agentEndpoint);
+        Throw.IfNull(credential);

-        AgentReference agentReference = agentEndpoint.Segments[^1].TrimEnd('/');
+        var (agentName, _) = ParseAgentEndpoint(agentEndpoint);

-        ChatClientAgentOptions agentOptions = new()
-        {
-            Name = agentReference.Name,
-            ChatOptions = new() { Tools = tools },
-        };
+        var perAgentOptions = clientOptions ?? new ProjectOpenAIClientOptions();
+        perAgentOptions.Endpoint = agentEndpoint;
+        perAgentOptions.AgentName = agentName;
+        perAgentOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);

-        IChatClient chatClient = new AzureAIProjectChatClient(aiProjectClient, agentReference, defaultModelId: null, agentOptions.ChatOptions);
+        var authPolicy = new BearerTokenPolicy(credential, AzureAiResourceScope);
+        var perAgentClient = new ProjectOpenAIClient(authPolicy, perAgentOptions);

+        IChatClient chatClient = perAgentClient.GetProjectResponsesClient().AsIChatClient();
        if (clientFactory is not null)
        {
            chatClient = clientFactory(chatClient);
        }

+        ChatClientAgentOptions agentOptions = new()
+        {
+            Id = agentName,
+            Name = agentName,
+            ChatOptions = new() { Tools = tools },
+        };
+
        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>
+    /// and returns the agent name and the derived project-root URI.
+    /// </summary>
+    /// <remarks>
+    /// Single source of truth for both agent-name extraction and project-root derivation.
+    /// Tolerates trailing slash, casing variants on <c>/agents/</c> and the suffix segment, and
+    /// strips query string and fragment. Throws <see cref="ArgumentException"/> for inputs that
+    /// do not match the expected shape.
+    /// </remarks>
+    /// <exception cref="ArgumentException">
+    /// The endpoint is missing the <c>/agents/</c> segment, has an empty agent name, or has a
+    /// suffix other than <c>/endpoint/protocols/openai</c>.
+    /// </exception>
+    internal static (string AgentName, Uri ProjectRoot) ParseAgentEndpoint(Uri agentEndpoint)
+    {
+        Throw.IfNull(agentEndpoint);
+
+        const string AgentsSegment = "/agents/";
+        const string ExpectedSuffix = "/endpoint/protocols/openai";
+
+        var path = agentEndpoint.AbsolutePath.TrimEnd('/');
+        var idx = path.IndexOf(AgentsSegment, StringComparison.OrdinalIgnoreCase);
+        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.",
+                nameof(agentEndpoint));
+        }
+
+        var afterAgents = path.Substring(idx + AgentsSegment.Length);
+        var nextSlash = afterAgents.IndexOf('/');
+        if (nextSlash <= 0)
+        {
+            throw new ArgumentException(
+                $"Agent endpoint '{agentEndpoint}' is missing the '<agentName>{ExpectedSuffix}' suffix.",
+                nameof(agentEndpoint));
+        }
+
+        var agentName = afterAgents.Substring(0, nextSlash);
+        var suffix = afterAgents.Substring(nextSlash);
+        if (!string.Equals(suffix, ExpectedSuffix, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException(
+                $"Agent endpoint '{agentEndpoint}' has an unexpected suffix '{suffix}'. Expected '{ExpectedSuffix}'.",
+                nameof(agentEndpoint));
+        }
+
+        var rootPath = path.Substring(0, idx);
+        var projectRoot = new UriBuilder(agentEndpoint)
+        {
+            Path = rootPath,
+            Query = string.Empty,
+            Fragment = string.Empty,
+        }.Uri;
+
+        return (agentName, projectRoot);
+    }
+
    private static AIProjectClient CreateProjectClient(Uri endpoint, AuthenticationTokenProvider credential, AIProjectClientOptions? clientOptions = null)
    {
        Throw.IfNull(endpoint);
        Throw.IfNull(credential);

        clientOptions ??= new AIProjectClientOptions();
-        clientOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, System.ClientModel.Primitives.PipelinePosition.PerCall);
+        clientOptions.AddPolicy(RequestOptionsExtensions.UserAgentPolicy, PipelinePosition.PerCall);
        return new AIProjectClient(endpoint, credential, clientOptions);
    }

@@ -1,7 +1,10 @@
 <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
-    <IsReleased>true</IsReleased>
+    <!-- Preview while we depend on Azure.AI.Projects 2.1.0-beta.1 for hosted-agent routing
+         (ProjectOpenAIClientOptions.AgentName, the (AuthenticationPolicy, options) ctor, and
+         related per-agent endpoint surface). Flip back to IsReleased=true once Azure.AI.Projects
+         ships a stable 2.1.0. -->
    <InjectSharedThrow>true</InjectSharedThrow>
    <NoWarn>$(NoWarn);OPENAI001</NoWarn>
  </PropertyGroup>
@@ -266,7 +266,33 @@ internal sealed class HandoffAgentExecutor :
                    sharedState.Conversation.AddMessages(incomingMessages);
                }

-                newConversationBookmark = sharedState.Conversation.AddMessages(result.Response.Messages);
+                if (result.IsHandoffRequested)
+                {
+                    int preHandoffMessageCount = result.Response.Messages.Count - 1;
+                    newConversationBookmark = sharedState.Conversation.AddMessages(result.Response.Messages.Take(preHandoffMessageCount));
+
+                    // The following message contains the Handoff FunctionCallResult which should be added to the conversation history with
+                    // the caveat that we need to get it back next time _this_ agent is invoked because we need to feed the FunctionCallResult
+                    // back to the agent. So ignore the bookmark update.
+                    ChatMessage handoffCallResultMessage = result.Response.Messages[preHandoffMessageCount];
+
+                    if (handoffCallResultMessage.Role != ChatRole.Tool)
+                    {
+                        throw new InvalidOperationException("The last message in a handoff response must be a Tool message containing the Handoff FunctionCallResult.");
+                    }
+
+                    if (handoffCallResultMessage.Contents.Count != 1 ||
+                        handoffCallResultMessage.Contents[0] is not FunctionResultContent)
+                    {
+                        throw new InvalidOperationException("The Tool message in a handoff response must contain exactly one content item of type FunctionResultContent.");
+                    }
+
+                    _ = sharedState.Conversation.AddMessage(handoffCallResultMessage);
+                }
+                else
+                {
+                    newConversationBookmark = sharedState.Conversation.AddMessages(result.Response.Messages);
+                }

                return new ValueTask();
            },
@@ -376,39 +402,28 @@ internal sealed class HandoffAgentExecutor :
        List<AgentResponseUpdate> updates = [];
        List<FunctionCallContent> candidateRequests = [];

-        await this.InvokeWithStateAsync(
-            async (state, ctx, ct) =>
+        this._session ??= await this._agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+
+        IAsyncEnumerable<AgentResponseUpdate> agentStream =
+            this._agent.RunStreamingAsync(messages, this._session, this._agentOptions, cancellationToken);
+
+        await foreach (AgentResponseUpdate update in agentStream.ConfigureAwait(false))
+        {
+            await AddUpdateAsync(update, cancellationToken).ConfigureAwait(false);
+
+            collector.ProcessAgentResponseUpdate(update, CollectHandoffRequestsFilter);
+
+            bool CollectHandoffRequestsFilter(FunctionCallContent candidateHandoffRequest)
            {
-                this._session ??= await this._agent.CreateSessionAsync(ct).ConfigureAwait(false);
-
-                IAsyncEnumerable<AgentResponseUpdate> agentStream =
-                    this._agent.RunStreamingAsync(messages,
-                                                  this._session,
-                                                  options: this._agentOptions,
-                                                  cancellationToken: ct);
-
-                await foreach (AgentResponseUpdate update in agentStream.ConfigureAwait(false))
+                bool isHandoffRequest = this._handoffFunctionNames.Contains(candidateHandoffRequest.Name);
+                if (isHandoffRequest)
                {
-                    await AddUpdateAsync(update, ct).ConfigureAwait(false);
-
-                    collector.ProcessAgentResponseUpdate(update, CollectHandoffRequestsFilter);
-
-                    bool CollectHandoffRequestsFilter(FunctionCallContent candidateHandoffRequest)
-                    {
-                        bool isHandoffRequest = this._handoffFunctionNames.Contains(candidateHandoffRequest.Name);
-                        if (isHandoffRequest)
-                        {
-                            candidateRequests.Add(candidateHandoffRequest);
-                        }
-
-                        return !isHandoffRequest;
-                    }
+                    candidateRequests.Add(candidateHandoffRequest);
                }

-                return state;
-            },
-            context,
-            cancellationToken: cancellationToken).ConfigureAwait(false);
+                return !isHandoffRequest;
+            }
+        }

        if (candidateRequests.Count > 1)
        {
@@ -3,13 +3,14 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
 using Microsoft.Extensions.AI;

 namespace Microsoft.Agents.AI.Workflows.Specialized.Magentic;

 internal sealed class StreamingToolCallResultPairMatcher
 {
-    private enum CallType
+    internal enum CallType
    {
        Function,
        McpServerTool
@@ -17,7 +18,7 @@ internal sealed class StreamingToolCallResultPairMatcher

    private record CallSummaryKey(CallType Type, string CallId);

-    private struct ToolCallSummary(CallType callType, string callId, string name)
+    internal struct ToolCallSummary(CallType callType, string callId, string name)
    {
        public CallType CallType => callType;

@@ -28,6 +29,12 @@ internal sealed class StreamingToolCallResultPairMatcher

    private readonly Dictionary<CallSummaryKey, ToolCallSummary> _callSummaries = new();

+    public bool HasUnmatchedCalls => this._callSummaries.Count > 0;
+
+    public IEnumerable<ToolCallSummary> UnmatchedCalls => this.HasUnmatchedCalls
+                                                        ? this._callSummaries.Values.ToList()
+                                                        : [];
+
    private void Collect(CallType callType, string callId, string name, string callContentTypeName, string resultContentTypeName)
    {
        CallSummaryKey key = new(callType, callId);
@@ -151,6 +151,36 @@ public sealed class ChatClientAgentOptions
    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
    public bool RequirePerServiceCallChatHistoryPersistence { get; set; }

+    /// <summary>
+    /// Gets or sets a value indicating whether to include a <see cref="MessageInjectingChatClient"/>
+    /// in the chat client pipeline.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When set to <see langword="true"/>, a <see cref="MessageInjectingChatClient"/> is added to the pipeline
+    /// between the <see cref="FunctionInvokingChatClient"/> and the inner client. This enables external code
+    /// (such as tool delegates) to inject messages into the function execution loop via the
+    /// <see cref="MessageInjectingChatClient"/> class, which can be resolved from the chat client using
+    /// <c>GetService&lt;MessageInjectingChatClient&gt;()</c>.
+    /// </para>
+    /// <para>
+    /// This setting can be used independently of <see cref="RequirePerServiceCallChatHistoryPersistence"/>,
+    /// however it is recommended to also enable per-service-call persistence when using message injection
+    /// so that injected messages are persisted to chat history between service calls.
+    /// </para>
+    /// <para>
+    /// When setting the <see cref="UseProvidedChatClientAsIs"/> setting to <see langword="true"/> and
+    /// <see cref="EnableMessageInjection"/> to <see langword="true"/>, ensure that your custom chat client stack
+    /// includes a <see cref="MessageInjectingChatClient"/>. You can add one manually via the
+    /// <see cref="ChatClientBuilderExtensions.UseMessageInjection"/> extension method.
+    /// </para>
+    /// </remarks>
+    /// <value>
+    /// Default is <see langword="false"/>.
+    /// </value>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public bool EnableMessageInjection { get; set; }
+
    /// <summary>
    /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
    /// </summary>
@@ -168,5 +198,6 @@ public sealed class ChatClientAgentOptions
            WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
            ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
            RequirePerServiceCallChatHistoryPersistence = this.RequirePerServiceCallChatHistoryPersistence,
+            EnableMessageInjection = this.EnableMessageInjection,
        };
 }
@@ -114,4 +114,38 @@ public static class ChatClientBuilderExtensions
    {
        return builder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
    }
+
+    /// <summary>
+    /// Adds a <see cref="MessageInjectingChatClient"/> to the chat client pipeline.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This decorator enables external code (such as tool delegates) to inject messages into the function
+    /// execution loop. It should be positioned between the <see cref="FunctionInvokingChatClient"/> and
+    /// the <see cref="PerServiceCallChatHistoryPersistingChatClient"/> (or the leaf <see cref="IChatClient"/>)
+    /// in the pipeline.
+    /// </para>
+    /// <para>
+    /// The <see cref="MessageInjectingChatClient"/> can be retrieved from the chat client via
+    /// <c>GetService&lt;MessageInjectingChatClient&gt;</c> to enqueue messages from tool delegates or other code.
+    /// </para>
+    /// <para>
+    /// This extension method is intended for use with custom chat client stacks when
+    /// <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="true"/>.
+    /// When <see cref="ChatClientAgentOptions.UseProvidedChatClientAsIs"/> is <see langword="false"/> (the default),
+    /// the <see cref="ChatClientAgent"/> automatically includes this decorator in the pipeline when
+    /// <see cref="ChatClientAgentOptions.RequirePerServiceCallChatHistoryPersistence"/> is <see langword="true"/>.
+    /// </para>
+    /// <para>
+    /// This decorator only works within the context of a running <see cref="ChatClientAgent"/> and will throw an
+    /// exception if used in any other stack.
+    /// </para>
+    /// </remarks>
+    /// <param name="builder">The <see cref="ChatClientBuilder"/> to add the decorator to.</param>
+    /// <returns>The <paramref name="builder"/> for chaining.</returns>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public static ChatClientBuilder UseMessageInjection(this ChatClientBuilder builder)
+    {
+        return builder.Use(innerClient => new MessageInjectingChatClient(innerClient));
+    }
 }
@@ -63,13 +63,21 @@ public static class ChatClientExtensions
            });
        }

-        // PerServiceCallChatHistoryPersistingChatClient is only injected when RequirePerServiceCallChatHistoryPersistence is enabled.
-        // It is registered after FunctionInvokingChatClient so that it sits between FIC and the leaf client.
+        // MessageInjectingChatClient is injected when EnableMessageInjection is enabled.
+        // It is registered after FunctionInvokingChatClient so that it sits between FIC and the inner client.
        // ChatClientBuilder.Build applies factories in reverse order, making the first Use() call outermost.
-        // By adding our decorator second, the resulting pipeline is:
-        //   FunctionInvokingChatClient → PerServiceCallChatHistoryPersistingChatClient → leaf IChatClient
-        // This allows the decorator to simulate service-stored chat history by loading history before
-        // each service call, persisting after each call, and returning a sentinel ConversationId.
+        // MessageInjectingChatClient enables injecting messages during the function loop and looping when needed.
+        if (options?.EnableMessageInjection is true)
+        {
+            chatBuilder.Use(innerClient => new MessageInjectingChatClient(innerClient));
+        }
+
+        // PerServiceCallChatHistoryPersistingChatClient is injected when RequirePerServiceCallChatHistoryPersistence is enabled.
+        // It is registered after MessageInjectingChatClient (if present) so it sits closest to the leaf client.
+        // The resulting pipeline is:
+        //   FunctionInvokingChatClient → [MessageInjectingChatClient] → [PerServiceCallChatHistoryPersistingChatClient] → leaf IChatClient
+        // PerServiceCallChatHistoryPersistingChatClient simulates service-stored chat history by loading history
+        // before each service call, persisting after each call, and returning a sentinel ConversationId.
        if (options?.RequirePerServiceCallChatHistoryPersistence is true)
        {
            chatBuilder.Use(innerClient => new PerServiceCallChatHistoryPersistingChatClient(innerClient));
@@ -0,0 +1,320 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A delegating chat client that supports injecting messages into the function execution loop.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This decorator enables external code (such as tool delegates) to enqueue messages that will be
+/// sent to the underlying model at the next opportunity. It sits between the <see cref="FunctionInvokingChatClient"/>
+/// and the <see cref="PerServiceCallChatHistoryPersistingChatClient"/> (or the leaf <see cref="IChatClient"/>)
+/// in a <see cref="ChatClientAgent"/> pipeline.
+/// </para>
+/// <para>
+/// The injected messages queue is stored per-session in the <see cref="AgentSession.StateBag"/>, ensuring
+/// isolation between concurrent sessions.
+/// </para>
+/// <para>
+/// After each service call, if no actionable <see cref="FunctionCallContent"/> is returned but injected
+/// messages are pending, the decorator loops internally and calls the inner client again with the new
+/// messages. When actionable function calls are present, control returns to the parent
+/// <see cref="FunctionInvokingChatClient"/> loop.
+/// </para>
+/// <para>
+/// This chat client must be used within the context of a running <see cref="ChatClientAgent"/>. It retrieves the
+/// current session from <see cref="AIAgent.CurrentRunContext"/>, which is set automatically when an agent's
+/// <see cref="AIAgent.RunAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/> or
+/// <see cref="AIAgent.RunStreamingAsync(IEnumerable{ChatMessage}, AgentSession?, AgentRunOptions?, CancellationToken)"/>
+/// method is called.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class MessageInjectingChatClient : DelegatingChatClient
+{
+    /// <summary>
+    /// The key used to store the pending injected messages queue in the session's <see cref="AgentSessionStateBag"/>.
+    /// </summary>
+    internal const string PendingMessagesStateKey = "MessageInjectingChatClient.PendingInjectedMessages";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MessageInjectingChatClient"/> class.
+    /// </summary>
+    /// <param name="innerClient">The underlying chat client that will handle the core operations.</param>
+    public MessageInjectingChatClient(IChatClient innerClient)
+        : base(innerClient)
+    {
+    }
+
+    /// <inheritdoc/>
+    public override async Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var session = GetRequiredSession();
+        var queue = GetOrCreateQueue(session);
+
+        var newMessages = DrainInjectedMessages(queue, messages as IList<ChatMessage> ?? messages.ToList());
+
+        // Loop to process injected messages: after each service call, if no actionable function calls
+        // are pending but new messages have been injected into the queue, we call the service again
+        // so the model can process them. The loop exits when the response contains actionable
+        // function calls (handed off to the parent FunctionInvokingChatClient) or the queue is empty.
+        while (true)
+        {
+            var response = await base.GetResponseAsync(newMessages, options, cancellationToken).ConfigureAwait(false);
+
+            // If the response contains actionable function calls, the parent FunctionInvokingChatClient
+            // loop will iterate — return immediately so it can process them.
+            if (HasActionableFunctionCalls(response.Messages))
+            {
+                return response;
+            }
+
+            // No actionable function calls. If there are pending injected messages, loop again
+            // to send them to the service. Otherwise, we're done.
+            bool queueEmpty;
+            lock (queue)
+            {
+                queueEmpty = queue.Count == 0;
+            }
+
+            if (queueEmpty)
+            {
+                return response;
+            }
+
+            // Propagate any ConversationId returned by the service so subsequent iterations
+            // continue within the same conversation.
+            UpdateOptionsForNextIteration(ref options, response.ConversationId);
+
+            newMessages = DrainInjectedMessages(queue, Array.Empty<ChatMessage>());
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var session = GetRequiredSession();
+        var queue = GetOrCreateQueue(session);
+
+        var newMessages = DrainInjectedMessages(queue, messages as IList<ChatMessage> ?? messages.ToList());
+
+        // Loop to process injected messages: after each service call, if no actionable function calls
+        // are pending but new messages have been injected into the queue, we call the service again
+        // so the model can process them. The loop exits when the response contains actionable
+        // function calls (handed off to the parent FunctionInvokingChatClient) or the queue is empty.
+        while (true)
+        {
+            bool hasActionableFunctionCalls = false;
+            string? lastConversationId = null;
+
+            var enumerator = base.GetStreamingResponseAsync(newMessages, options, cancellationToken).GetAsyncEnumerator(cancellationToken);
+            try
+            {
+                while (await enumerator.MoveNextAsync().ConfigureAwait(false))
+                {
+                    var update = enumerator.Current;
+
+                    // Check each update for actionable function call content as it streams through.
+                    if (!hasActionableFunctionCalls && HasActionableFunctionCalls(update))
+                    {
+                        hasActionableFunctionCalls = true;
+                    }
+
+                    // Track the latest ConversationId from the stream.
+                    if (update.ConversationId is not null)
+                    {
+                        lastConversationId = update.ConversationId;
+                    }
+
+                    yield return update;
+                }
+            }
+            finally
+            {
+                await enumerator.DisposeAsync().ConfigureAwait(false);
+            }
+
+            // If the response contains actionable function calls, the parent FunctionInvokingChatClient
+            // loop will iterate — return immediately so it can process them.
+            if (hasActionableFunctionCalls)
+            {
+                yield break;
+            }
+
+            // No actionable function calls. If there are pending injected messages, loop again
+            // to send them to the service. Otherwise, we're done.
+            bool queueEmpty;
+            lock (queue)
+            {
+                queueEmpty = queue.Count == 0;
+            }
+
+            if (queueEmpty)
+            {
+                yield break;
+            }
+
+            // Propagate any ConversationId returned by the service so subsequent iterations
+            // continue within the same conversation.
+            UpdateOptionsForNextIteration(ref options, lastConversationId);
+
+            newMessages = DrainInjectedMessages(queue, Array.Empty<ChatMessage>());
+        }
+    }
+
+    /// <summary>
+    /// Enqueues one or more messages to be used at the next opportunity.
+    /// </summary>
+    /// <remarks>
+    /// This method is thread-safe and can be called concurrently from tool delegates or other code
+    /// while the function execution loop is in progress. The enqueued messages will be picked up
+    /// at the next opportunity.
+    /// </remarks>
+    /// <param name="session">The agent session to enqueue messages for.</param>
+    /// <param name="messages">The messages to enqueue.</param>
+    public void EnqueueMessages(AgentSession session, IEnumerable<ChatMessage> messages)
+    {
+        Throw.IfNull(session);
+        Throw.IfNull(messages);
+
+        var queue = GetOrCreateQueue(session);
+
+        lock (queue)
+        {
+            foreach (var message in messages)
+            {
+                queue.Add(message);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets or creates the pending injected messages queue from the session's <see cref="AgentSessionStateBag"/>.
+    /// </summary>
+    private static List<ChatMessage> GetOrCreateQueue(AgentSession session)
+    {
+        if (session.StateBag.TryGetValue<List<ChatMessage>>(PendingMessagesStateKey, out var queue))
+        {
+            return queue!;
+        }
+
+        var newQueue = new List<ChatMessage>();
+        session.StateBag.SetValue(PendingMessagesStateKey, newQueue);
+        return newQueue;
+    }
+
+    /// <summary>
+    /// Gets the current <see cref="AgentSession"/> from the run context.
+    /// </summary>
+    private static AgentSession GetRequiredSession()
+    {
+        var runContext = AIAgent.CurrentRunContext
+            ?? throw new InvalidOperationException(
+                $"{nameof(MessageInjectingChatClient)} can only be used within the context of a running AIAgent. " +
+                "Ensure that the chat client is being invoked as part of an AIAgent.RunAsync or AIAgent.RunStreamingAsync call.");
+
+        return runContext.Session
+            ?? throw new InvalidOperationException(
+                $"{nameof(MessageInjectingChatClient)} requires a session. " +
+                "The current run context does not have a session.");
+    }
+
+    /// <summary>
+    /// Drains all pending injected messages from the queue and returns a new list combining
+    /// the original messages with the drained messages. The original list is never modified.
+    /// </summary>
+    private static IList<ChatMessage> DrainInjectedMessages(List<ChatMessage> queue, IList<ChatMessage> newMessages)
+    {
+        lock (queue)
+        {
+            if (queue.Count == 0)
+            {
+                return newMessages;
+            }
+
+            var combined = new List<ChatMessage>(newMessages);
+            combined.AddRange(queue);
+            queue.Clear();
+            return combined;
+        }
+    }
+
+    /// <summary>
+    /// Determines whether any message in the list contains a <see cref="FunctionCallContent"/>
+    /// that is not marked as <see cref="FunctionCallContent.InformationalOnly"/>.
+    /// </summary>
+    private static bool HasActionableFunctionCalls(IList<ChatMessage> responseMessages)
+    {
+        for (int i = 0; i < responseMessages.Count; i++)
+        {
+            var contents = responseMessages[i].Contents;
+            for (int j = 0; j < contents.Count; j++)
+            {
+                if (contents[j] is FunctionCallContent fcc && !fcc.InformationalOnly)
+                {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Determines whether a streaming update contains a <see cref="FunctionCallContent"/>
+    /// that is not marked as <see cref="FunctionCallContent.InformationalOnly"/>.
+    /// </summary>
+    private static bool HasActionableFunctionCalls(ChatResponseUpdate update)
+    {
+        var contents = update.Contents;
+        for (int i = 0; i < contents.Count; i++)
+        {
+            if (contents[i] is FunctionCallContent fcc && !fcc.InformationalOnly)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Propagates the <paramref name="conversationId"/> from the service response into
+    /// <paramref name="options"/> so that subsequent loop iterations continue within the
+    /// same conversation. Clones <paramref name="options"/> before mutating to avoid
+    /// affecting the caller's instance.
+    /// </summary>
+    private static void UpdateOptionsForNextIteration(ref ChatOptions? options, string? conversationId)
+    {
+        if (options is null)
+        {
+            if (conversationId is not null)
+            {
+                options = new() { ConversationId = conversationId };
+            }
+        }
+        else if (options.ConversationId != conversationId)
+        {
+            options = options.Clone();
+            options.ConversationId = conversationId;
+        }
+    }
+}
@@ -9,7 +9,7 @@
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" />
    <PackageReference Include="Azure.AI.AgentServer.Responses" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Microsoft.AspNetCore.TestHost" />
    <PackageReference Include="OpenTelemetry" />
    <PackageReference Include="OpenTelemetry.Exporter.InMemory" />
@@ -7,6 +7,7 @@ using System.Net.Http;
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
+using Azure.AI.Extensions.OpenAI;
 using Azure.AI.Projects;
 using Microsoft.Extensions.AI;

@@ -184,7 +185,7 @@ public class FoundryAgentTests

        // Act: this AsAIAgent path constructs FoundryAgent via its internal
        // (AIProjectClient, ChatClientAgent) constructor, which previously bypassed pre-wiring.
-        var agent = projectClient.AsAIAgent(new Azure.AI.Extensions.OpenAI.AgentReference("agent-name"));
+        var agent = projectClient.AsAIAgent(new AgentReference("agent-name"));

        // Assert
        Assert.NotNull(agent.GetService<ClientHeadersAgent>());
@@ -398,4 +399,379 @@ public class FoundryAgentTests
    }

    #endregion
+
+    #region Agent-endpoint constructor tests
+
+    private const string TestAgentEndpoint = "https://test.services.ai.azure.com/api/projects/test-project/agents/it-happy-path/endpoint/protocols/openai";
+    private static readonly Uri s_testAgentEndpoint = new(TestAgentEndpoint);
+
+    [Fact]
+    public void AgentEndpointConstructor_NullEndpoint_ThrowsArgumentNullException()
+    {
+        ArgumentNullException ex = Assert.Throws<ArgumentNullException>(() =>
+            new FoundryAgent(agentEndpoint: null!, credential: new FakeAuthenticationTokenProvider()));
+        Assert.Equal("agentEndpoint", ex.ParamName);
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_NullCredential_ThrowsArgumentNullException()
+    {
+        ArgumentNullException ex = Assert.Throws<ArgumentNullException>(() =>
+            new FoundryAgent(agentEndpoint: s_testAgentEndpoint, credential: null!));
+        Assert.Equal("credential", ex.ParamName);
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_PopulatesNameAndIdFromEndpointSlug()
+    {
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
+
+        Assert.Equal("it-happy-path", agent.Name);
+        Assert.Equal("it-happy-path", agent.Id);
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull()
+    {
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
+
+        Assert.NotNull(agent.GetService<ProjectOpenAIClient>());
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_GetServiceAIProjectClient_ReturnsNull()
+    {
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider());
+
+        Assert.Null(agent.GetService<AIProjectClient>());
+    }
+
+    [Fact]
+    public void ProjectEndpointConstructor_GetServiceProjectOpenAIClient_ReturnsNonNull()
+    {
+        FoundryAgent agent = new(
+            s_testEndpoint,
+            new FakeAuthenticationTokenProvider(),
+            model: "gpt-4o-mini",
+            instructions: "Test");
+
+        Assert.NotNull(agent.GetService<ProjectOpenAIClient>());
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_AppliesClientFactoryOnce()
+    {
+        int count = 0;
+        FoundryAgent agent = new(
+            s_testAgentEndpoint,
+            new FakeAuthenticationTokenProvider(),
+            clientFactory: c => { count++; return c; });
+
+        Assert.Equal(1, count);
+        Assert.NotNull(agent);
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_RunAsync_RoutesThroughPerAgentResponsesUrlAsync()
+    {
+        Uri? capturedUri = null;
+        using HttpHandlerAssert handler = new(req =>
+        {
+            capturedUri = req.RequestUri;
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        await agent.RunAsync("Hello");
+
+        Assert.NotNull(capturedUri);
+        string path = capturedUri!.AbsolutePath;
+        Assert.Contains("/agents/it-happy-path/endpoint/protocols/openai/responses", path, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("/openai/v1/responses", path, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("api-version=v1", capturedUri.Query, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_RunStreamingAsync_RoutesThroughPerAgentResponsesUrlAsync()
+    {
+        Uri? capturedUri = null;
+        bool sawStreamTrue = false;
+        using HttpHandlerAssert handler = new(async req =>
+        {
+            capturedUri = req.RequestUri;
+            if (req.Content is not null)
+            {
+                string body = await req.Content.ReadAsStringAsync().ConfigureAwait(false);
+                if (body.Contains("\"stream\":true", StringComparison.Ordinal))
+                {
+                    sawStreamTrue = true;
+                }
+            }
+
+            // Minimal SSE response; xUnit assertion only cares about the URL/body shape.
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("data: [DONE]\n\n", Encoding.UTF8, "text/event-stream"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        try
+        {
+            await foreach (var _ in agent.RunStreamingAsync("Hello"))
+            {
+                // drain
+            }
+        }
+        catch
+        {
+            // SSE parse errors are acceptable; we only assert the request shape.
+        }
+
+        Assert.NotNull(capturedUri);
+        Assert.Contains("/agents/it-happy-path/endpoint/protocols/openai/responses", capturedUri!.AbsolutePath, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("api-version=v1", capturedUri.Query, StringComparison.OrdinalIgnoreCase);
+        Assert.True(sawStreamTrue, "Expected request body to include \"stream\":true.");
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_CreateConversationSessionAsync_RoutesThroughProjectLevelUrlAsync()
+    {
+        Uri? capturedUri = null;
+        using HttpHandlerAssert handler = new(req =>
+        {
+            capturedUri = req.RequestUri;
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("{\"id\":\"conv_123\"}", Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        try
+        {
+            _ = await agent.CreateConversationSessionAsync();
+        }
+        catch
+        {
+            // Underlying SDK may attempt extra parsing on the minimal response. We only assert URL routing.
+        }
+
+        Assert.NotNull(capturedUri);
+        string path = capturedUri!.AbsolutePath;
+        Assert.Contains("/api/projects/test-project/openai/v1/conversations", path, StringComparison.OrdinalIgnoreCase);
+        Assert.DoesNotContain("/agents/", path, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_StampsMeaiUserAgentHeaderAsync()
+    {
+        bool meaiSeen = false;
+        using HttpHandlerAssert handler = new(req =>
+        {
+            if (req.Headers.TryGetValues("User-Agent", out var values))
+            {
+                foreach (string v in values)
+                {
+                    if (v.IndexOf("MEAI/", StringComparison.OrdinalIgnoreCase) >= 0)
+                    {
+                        meaiSeen = true;
+                    }
+                }
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        await agent.RunAsync("Hello");
+
+        Assert.True(meaiSeen, "Expected MEAI/x.y.z to appear in the User-Agent header on the agent-endpoint pipeline.");
+    }
+
+    [Fact]
+    public async Task AgentEndpointConstructor_PassesThroughCallerPolicyOnPerAgentPipelineAsync()
+    {
+        // Direct switch to ProjectOpenAIClientOptions means caller-supplied pipeline policies
+        // (added via AddPolicy) actually flow through to the per-agent traffic. Assert that a
+        // tag-stamping policy executes on each outbound per-agent request.
+        bool tagSeen = false;
+        using HttpHandlerAssert handler = new(req =>
+        {
+            if (req.Headers.TryGetValues("X-Test-Tag", out var values))
+            {
+                foreach (string v in values)
+                {
+                    if (v == "tag-1")
+                    {
+                        tagSeen = true;
+                    }
+                }
+            }
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(TestDataUtil.GetOpenAIDefaultResponseJson(), Encoding.UTF8, "application/json"),
+            };
+        });
+#pragma warning disable CA5399
+        using HttpClient http = new(handler);
+#pragma warning restore CA5399
+        ProjectOpenAIClientOptions opts = new() { Transport = new HttpClientPipelineTransport(http) };
+        opts.AddPolicy(new HeaderStampPolicy("X-Test-Tag", "tag-1"), PipelinePosition.PerCall);
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+        await agent.RunAsync("Hello");
+
+        Assert.True(tagSeen, "Expected caller-supplied per-call policy to execute on the per-agent pipeline.");
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_OverridesCallerEndpointAndAgentName()
+    {
+        // The caller may set Endpoint/AgentName on the options bag; we must override both with
+        // values derived from agentEndpoint so the URL routing is correct regardless.
+        ProjectOpenAIClientOptions opts = new()
+        {
+            Endpoint = new Uri("https://wrong.example.com/openai/v1"),
+            AgentName = "wrong-agent",
+        };
+
+        FoundryAgent agent = new(s_testAgentEndpoint, new FakeAuthenticationTokenProvider(), clientOptions: opts);
+
+        Assert.Equal("it-happy-path", agent.Name);
+        Assert.Equal(s_testAgentEndpoint, opts.Endpoint);
+        Assert.Equal("it-happy-path", opts.AgentName);
+    }
+
+    [Fact]
+    public void AgentEndpointConstructor_PropagatesUserAgentApplicationId_ToProjectLevelClient()
+    {
+        // 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.Equal("my-app-id", opts.UserAgentApplicationId);
+    }
+
+    #endregion
+
+    #region ParseAgentEndpoint tests
+
+    [Fact]
+    public void ParseAgentEndpoint_StandardShape_Parses()
+    {
+        var (name, root) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p1/agents/a1/endpoint/protocols/openai"));
+        Assert.Equal("a1", name);
+        Assert.Equal("https://h.example.com/api/projects/p1", root.AbsoluteUri.TrimEnd('/'));
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_TrailingSlash_Parses()
+    {
+        var (name, root) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p1/agents/a1/endpoint/protocols/openai/"));
+        Assert.Equal("a1", name);
+        Assert.Equal("https://h.example.com/api/projects/p1", root.AbsoluteUri.TrimEnd('/'));
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_UppercaseAgentsSegment_Parses()
+    {
+        var (name, _) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p1/Agents/a1/endpoint/protocols/openai"));
+        Assert.Equal("a1", name);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_SpecialCharsInName_Parses()
+    {
+        var (name, _) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p/agents/it-happy_path-1/endpoint/protocols/openai"));
+        Assert.Equal("it-happy_path-1", name);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_QueryAndFragmentStripped()
+    {
+        var (_, root) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p/agents/a/endpoint/protocols/openai?x=1#frag"));
+        Assert.Equal(string.Empty, root.Query);
+        Assert.Equal(string.Empty, root.Fragment);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_SovereignCloudHostNoApiPrefix_Parses()
+    {
+        var (name, root) = FoundryAgent.ParseAgentEndpoint(new Uri("https://h.cognitive.microsoft.us/projects/p/agents/a1/endpoint/protocols/openai"));
+        Assert.Equal("a1", name);
+        Assert.Equal("https://h.cognitive.microsoft.us/projects/p", root.AbsoluteUri.TrimEnd('/'));
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_MissingAgentsSegment_Throws()
+    {
+        ArgumentException ex = Assert.Throws<ArgumentException>(() =>
+            FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p1/openai/v1")));
+        Assert.Equal("agentEndpoint", ex.ParamName);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_WrongSuffix_Throws()
+    {
+        ArgumentException ex = Assert.Throws<ArgumentException>(() =>
+            FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p/agents/a1/openai/v1")));
+        Assert.Equal("agentEndpoint", ex.ParamName);
+    }
+
+    [Fact]
+    public void ParseAgentEndpoint_EmptyAgentName_Throws()
+    {
+        ArgumentException ex = Assert.Throws<ArgumentException>(() =>
+            FoundryAgent.ParseAgentEndpoint(new Uri("https://h.example.com/api/projects/p/agents//endpoint/protocols/openai")));
+        Assert.Equal("agentEndpoint", ex.ParamName);
+    }
+
+    #endregion
+
+    private sealed class HeaderStampPolicy : PipelinePolicy
+    {
+        private readonly string _name;
+        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)
+        {
+            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)
+        {
+            message.Request.Headers.Set(this._name, this._value);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
 }
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <CentralPackageTransitivePinningEnabled>false</CentralPackageTransitivePinningEnabled>
@@ -7,7 +7,7 @@

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" />
-    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+    <PackageReference Include="Azure.AI.Projects" />
  </ItemGroup>

  <ItemGroup>
@@ -0,0 +1,493 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+using Moq.Protected;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for <see cref="MessageInjectingChatClient"/>.
+/// </summary>
+public class MessageInjectingChatClientTests
+{
+    /// <summary>
+    /// Verifies that <see cref="MessageInjectingChatClient"/> is resolvable via GetService when the decorator is active.
+    /// </summary>
+    [Fact]
+    public void GetService_ReturnsMessageInjectingChatClient_WhenDecoratorActive()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            EnableMessageInjection = true,
+        });
+
+        // Act
+        var injector = agent.ChatClient.GetService<MessageInjectingChatClient>();
+
+        // Assert
+        Assert.NotNull(injector);
+    }
+
+    /// <summary>
+    /// Verifies that <see cref="MessageInjectingChatClient"/> is null when the decorator is not active.
+    /// </summary>
+    [Fact]
+    public void GetService_ReturnsNull_WhenDecoratorNotActive()
+    {
+        // Arrange
+        Mock<IChatClient> mockService = new();
+        ChatClientAgent agent = new(mockService.Object, options: new());
+
+        // Act
+        var injector = agent.ChatClient.GetService<MessageInjectingChatClient>();
+
+        // Assert
+        Assert.Null(injector);
+    }
+
+    /// <summary>
+    /// Verifies that messages enqueued on the session before RunAsync are included in the service call messages.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_IncludesInjectedMessages_WhenEnqueuedBeforeCallAsync()
+    {
+        // Arrange
+        List<ChatMessage> capturedMessages = [];
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+                capturedMessages.AddRange(msgs))
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        });
+
+        // Create session and enqueue a message directly onto the session's StateBag queue before calling RunAsync
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        var queue = new List<ChatMessage>();
+        queue.Add(new ChatMessage(ChatRole.User, "injected message"));
+        session!.StateBag.SetValue("MessageInjectingChatClient.PendingInjectedMessages", queue);
+
+        // Act
+        await agent.RunAsync([new(ChatRole.User, "original")], session);
+
+        // Assert — the service should have received both the original and injected messages
+        Assert.Contains(capturedMessages, m => m.Text == "original");
+        Assert.Contains(capturedMessages, m => m.Text == "injected message");
+    }
+
+    /// <summary>
+    /// Verifies that the queue is drained after a call (messages are not re-delivered on subsequent calls).
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DrainsQueue_MessagesNotRedeliveredAsync()
+    {
+        // Arrange
+        List<ChatMessage> capturedMessages = [];
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Callback((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+                capturedMessages.AddRange(msgs))
+            .ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]));
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        });
+
+        // Create session and enqueue a message directly onto the session's StateBag queue
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        var queue = new List<ChatMessage>();
+        queue.Add(new ChatMessage(ChatRole.User, "injected once"));
+        session!.StateBag.SetValue("MessageInjectingChatClient.PendingInjectedMessages", queue);
+
+        // Act
+        await agent.RunAsync([new(ChatRole.User, "first call")], session);
+
+        // Assert — the injected message was included in the service call
+        Assert.Contains(capturedMessages, m => m.Text == "injected once");
+
+        // Assert — the session's queue is now empty (drained)
+        Assert.Empty(queue);
+    }
+
+    /// <summary>
+    /// Verifies that the internal loop fires when no actionable FunctionCallContent is returned
+    /// but there are pending injected messages in the queue.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_LoopsInternally_WhenNoActionableFCCButPendingMessagesAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        Mock<IChatClient> mockService = new();
+        MessageInjectingChatClient? injectorRef = null;
+        ChatClientAgentSession? sessionRef = null;
+
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    // First call — simulate that something enqueues a message (e.g., a provider or background task)
+                    injectorRef!.EnqueueMessages(sessionRef!, [new ChatMessage(ChatRole.User, "injected during first call")]);
+                }
+
+                // Return a plain text response (no FunctionCallContent) to trigger the internal loop
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, $"response {serviceCallCount}")]));
+            });
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        });
+
+        injectorRef = agent.ChatClient.GetService<MessageInjectingChatClient>()!;
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        sessionRef = session;
+        await agent.RunAsync([new(ChatRole.User, "original")], session);
+
+        // Assert — should have made 2 service calls (internal loop triggered by the injected message)
+        Assert.Equal(2, serviceCallCount);
+    }
+
+    /// <summary>
+    /// Verifies that the internal loop does NOT fire when the response contains actionable
+    /// FunctionCallContent, even if there are pending injected messages.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DoesNotLoopInternally_WhenActionableFCCPresentAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        Mock<IChatClient> mockService = new();
+        MessageInjectingChatClient? injectorRef = null;
+        ChatClientAgentSession? sessionRef = null;
+
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    // Enqueue a message during the first call
+                    injectorRef!.EnqueueMessages(sessionRef!, [new ChatMessage(ChatRole.User, "injected")]);
+                    // Return a response with an actionable FunctionCallContent
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant,
+                        [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>())])]));
+                }
+
+                // Subsequent calls return plain text (the FCC loop will call back after tool execution)
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "final")]));
+            });
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        var tool = AIFunctionFactory.Create(() => "tool result", "myTool", "A test tool");
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Tools = [tool] },
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        injectorRef = agent.ChatClient.GetService<MessageInjectingChatClient>()!;
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        sessionRef = session;
+        await agent.RunAsync([new(ChatRole.User, "original")], session);
+
+        // Assert — The first service call returned actionable FCC, so no internal injected-message loop
+        // occurred there. The FCC loop invokes the tool and calls the service again (second call).
+        // The injected message should be picked up by the second service call (drained at start of
+        // GetResponseAsync), but no extra internal loop should fire. Exactly 2 service calls expected.
+        Assert.Equal(2, serviceCallCount);
+    }
+
+    /// <summary>
+    /// Verifies that the internal loop fires when the response contains only InformationalOnly
+    /// FunctionCallContent (which are not actionable) and there are pending injected messages.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_LoopsInternally_WhenOnlyInformationalOnlyFCCAndPendingMessagesAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        Mock<IChatClient> mockService = new();
+        MessageInjectingChatClient? injectorRef = null;
+        ChatClientAgentSession? sessionRef = null;
+
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+            {
+                serviceCallCount++;
+                if (serviceCallCount == 1)
+                {
+                    // Enqueue a message during the first call
+                    injectorRef!.EnqueueMessages(sessionRef!, [new ChatMessage(ChatRole.User, "injected")]);
+                    // Return a response with InformationalOnly FCC (not actionable)
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant,
+                        [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>()) { InformationalOnly = true }])]));
+                }
+
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "final")]));
+            });
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        });
+
+        injectorRef = agent.ChatClient.GetService<MessageInjectingChatClient>()!;
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        sessionRef = session;
+        await agent.RunAsync([new(ChatRole.User, "original")], session);
+
+        // Assert — InformationalOnly FCC is NOT actionable, so internal loop should trigger
+        Assert.Equal(2, serviceCallCount);
+    }
+
+    /// <summary>
+    /// Verifies that when the inner client returns a ConversationId on the first call, the
+    /// MessageInjectingChatClient propagates it to options on subsequent loop iterations.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_PropagatesConversationId_AcrossInternalLoopIterationsAsync()
+    {
+        // Arrange
+        int serviceCallCount = 0;
+        List<string?> capturedConversationIds = [];
+        MessageInjectingChatClient? injectorRef = null;
+        ChatClientAgentSession? sessionRef = null;
+
+        Mock<IChatClient> mockService = new();
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> _, ChatOptions? opts, CancellationToken _) =>
+            {
+                serviceCallCount++;
+                capturedConversationIds.Add(opts?.ConversationId);
+
+                if (serviceCallCount == 1)
+                {
+                    // First call: inject a message and return a ConversationId
+                    injectorRef!.EnqueueMessages(sessionRef!, [new ChatMessage(ChatRole.User, "injected")]);
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "first response")])
+                    {
+                        ConversationId = "conv-123",
+                    });
+                }
+
+                // Second call (from loop): should have the propagated ConversationId
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "second response")]));
+            });
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            EnableMessageInjection = true,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        injectorRef = agent.ChatClient.GetService<MessageInjectingChatClient>()!;
+
+        // Act
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        sessionRef = session;
+        await agent.RunAsync([new(ChatRole.User, "hello")], session);
+
+        // Assert — The second call should have received the ConversationId propagated from the first response
+        Assert.Equal(2, serviceCallCount);
+        Assert.Null(capturedConversationIds[0]); // First call: no ConversationId yet
+        Assert.Equal("conv-123", capturedConversationIds[1]); // Second call: propagated from first response
+    }
+
+    /// <summary>
+    /// Verifies that a session with pending injected messages can be serialized and deserialized,
+    /// and that the deserialized session correctly delivers the injected messages on the next run.
+    /// </summary>
+    [Fact]
+    public async Task RunAsync_DeliversInjectedMessages_AfterSessionSerializationRoundTripAsync()
+    {
+        // Arrange
+        List<ChatMessage> capturedMessagesFirstRun = [];
+        List<ChatMessage> capturedMessagesSecondRun = [];
+        int runCount = 0;
+        Mock<IChatClient> mockService = new();
+        MessageInjectingChatClient? injectorRef = null;
+        ChatClientAgentSession? sessionRef = null;
+
+        mockService.Setup(
+            s => s.GetResponseAsync(
+                It.IsAny<IEnumerable<ChatMessage>>(),
+                It.IsAny<ChatOptions>(),
+                It.IsAny<CancellationToken>()))
+            .Returns((IEnumerable<ChatMessage> msgs, ChatOptions? _, CancellationToken _) =>
+            {
+                if (runCount == 1)
+                {
+                    capturedMessagesFirstRun.AddRange(msgs);
+
+                    // Inject a message during the first run — this will remain pending (not drained)
+                    // because we return an actionable FCC that causes the parent loop to take over.
+                    injectorRef!.EnqueueMessages(sessionRef!, [new ChatMessage(ChatRole.User, "injected before serialization")]);
+
+                    // Return actionable FCC so the injection loop does NOT drain the message
+                    return Task.FromResult(new ChatResponse([new(ChatRole.Assistant,
+                        [new FunctionCallContent("call1", "myTool", new Dictionary<string, object?>())])]));
+                }
+
+                // Second run (after deserialization) — capture what messages come through
+                capturedMessagesSecondRun.AddRange(msgs);
+                return Task.FromResult(new ChatResponse([new(ChatRole.Assistant, "final response")]));
+            });
+
+        Mock<ChatHistoryProvider> mockChatHistoryProvider = new(null, null, null);
+        mockChatHistoryProvider.SetupGet(p => p.StateKeys).Returns(["TestChatHistoryProvider"]);
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask<IEnumerable<ChatMessage>>>("InvokingCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokingContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns((ChatHistoryProvider.InvokingContext ctx, CancellationToken _) =>
+                new ValueTask<IEnumerable<ChatMessage>>(ctx.RequestMessages.ToList()));
+        mockChatHistoryProvider
+            .Protected()
+            .Setup<ValueTask>("InvokedCoreAsync", ItExpr.IsAny<ChatHistoryProvider.InvokedContext>(), ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask());
+
+        var tool = AIFunctionFactory.Create(() => "tool result", "myTool", "A test tool");
+
+        ChatClientAgent agent = new(mockService.Object, options: new()
+        {
+            ChatOptions = new() { Tools = [tool] },
+            ChatHistoryProvider = mockChatHistoryProvider.Object,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            EnableMessageInjection = true,
+        }, services: new ServiceCollection().BuildServiceProvider());
+
+        injectorRef = agent.ChatClient.GetService<MessageInjectingChatClient>()!;
+
+        // Act — First run: inject a message that stays pending
+        var session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+        sessionRef = session;
+        runCount = 1;
+        await agent.RunAsync([new(ChatRole.User, "first run message")], session);
+
+        // Serialize the session and deserialize into a new instance
+        var serialized = await agent.SerializeSessionAsync(session!);
+        var deserializedSession = await agent.DeserializeSessionAsync(serialized) as ChatClientAgentSession;
+
+        // Second run on the deserialized session — the injected message should be delivered
+        runCount = 2;
+        sessionRef = deserializedSession;
+        await agent.RunAsync([new(ChatRole.User, "second run message")], deserializedSession);
+
+        // Assert — the second run should include the injected message from before serialization
+        Assert.Contains(capturedMessagesSecondRun, m => m.Text == "injected before serialization");
+        Assert.Contains(capturedMessagesSecondRun, m => m.Text == "second run message");
+    }
+}
@@ -3,18 +3,14 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Reflection;
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
 using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
-using FluentAssertions;
 using Microsoft.Agents.AI.Workflows.InProc;
-using Microsoft.Agents.AI.Workflows.Specialized;
 using Microsoft.Extensions.AI;
-using Microsoft.Extensions.Logging;

 #pragma warning disable SYSLIB1045 // Use GeneratedRegex
 #pragma warning disable RCS1186 // Use Regex instance instead of static method
@@ -36,72 +32,6 @@ public class AgentWorkflowBuilderTests
        Assert.Throws<ArgumentNullException>("agents", () => AgentWorkflowBuilder.BuildConcurrent(null!));
    }

-    [Fact]
-    public void BuildHandoffs_InvalidArguments_Throws()
-    {
-        Assert.Throws<ArgumentNullException>("initialAgent", () => AgentWorkflowBuilder.CreateHandoffBuilderWith(null!));
-
-        var agent = new DoubleEchoAgent("agent");
-        var handoffs = AgentWorkflowBuilder.CreateHandoffBuilderWith(agent);
-        Assert.NotNull(handoffs);
-
-        Assert.Throws<ArgumentNullException>("from", () => handoffs.WithHandoff(null!, new DoubleEchoAgent("a2")));
-        Assert.Throws<ArgumentNullException>("to", () => handoffs.WithHandoff(new DoubleEchoAgent("a2"), null!));
-
-        Assert.Throws<ArgumentNullException>("from", () => handoffs.WithHandoffs(null!, new DoubleEchoAgent("a2")));
-        Assert.Throws<ArgumentNullException>("from", () => handoffs.WithHandoffs([null!], new DoubleEchoAgent("a2")));
-        Assert.Throws<ArgumentNullException>("to", () => handoffs.WithHandoffs(new DoubleEchoAgent("a2"), null!));
-        Assert.Throws<ArgumentNullException>("to", () => handoffs.WithHandoffs(new DoubleEchoAgent("a2"), [null!]));
-
-        var noDescriptionAgent = new ChatClientAgent(new MockChatClient(delegate { return new(); }));
-        Assert.Throws<ArgumentException>("to", () => handoffs.WithHandoff(agent, noDescriptionAgent));
-
-        var emptyDescriptionAgent = new MockChatClient(delegate { return new(); }).AsAIAgent(description: "");
-        Assert.Throws<ArgumentException>("to", () => handoffs.WithHandoff(agent, emptyDescriptionAgent));
-
-        var emptyNameAgent = new MockChatClient(delegate { return new(); }).AsAIAgent(name: "");
-        Assert.Throws<ArgumentException>("to", () => handoffs.WithHandoff(agent, emptyNameAgent));
-    }
-
-    private sealed class NullLogger : ILogger
-    {
-        public IDisposable? BeginScope<TState>(TState state) where TState : notnull
-        {
-            return null;
-        }
-
-        public bool IsEnabled(LogLevel logLevel)
-        {
-            return false;
-        }
-
-        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
-        {
-        }
-    }
-
-    [Fact]
-    public void BuildHandoffs_DelegatingAIAgent_DoesNotThrow()
-    {
-        DoubleEchoAgent agent = new("agent");
-        HandoffWorkflowBuilder handoffs = AgentWorkflowBuilder.CreateHandoffBuilderWith(agent);
-        Assert.NotNull(handoffs);
-
-        ChatClientAgent instructionsOnlyAgent = new MockChatClient(delegate { return new(); }).AsAIAgent(instructions: "instructions");
-        LoggingAgent delegatingAgent = new(instructionsOnlyAgent, new NullLogger());
-
-        handoffs.WithHandoff(agent, delegatingAgent);
-
-        // get the _targets field from the HandoffWorkflowBuilder (need to use the base type)
-        FieldInfo field = typeof(HandoffWorkflowBuilder).BaseType!.GetField("_targets", BindingFlags.Instance | BindingFlags.NonPublic)!;
-        Dictionary<AIAgent, HashSet<HandoffTarget>>? targets = field.GetValue(handoffs) as Dictionary<AIAgent, HashSet<HandoffTarget>>;
-
-        targets.Should().NotBeNull();
-
-        HandoffTarget target = targets[agent].Single();
-        target.Reason.Should().Be("instructions");
-    }
-
    [Fact]
    public void BuildGroupChat_InvalidArguments_Throws()
    {
@@ -287,628 +217,6 @@ public class AgentWorkflowBuilderTests
        }
    }

-    [Fact]
-    public async Task Handoffs_NoTransfers_ResponseServedByOriginalAgentAsync()
-    {
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            ChatMessage message = Assert.Single(messages);
-            Assert.Equal("abc", Assert.IsType<TextContent>(Assert.Single(message.Contents)).Text);
-
-            return new(new ChatMessage(ChatRole.Assistant, "Hello from agent1"));
-        }));
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, new ChatClientAgent(new MockChatClient(delegate
-            {
-                Assert.Fail("Should never be invoked.");
-                return new();
-            }), description: "nop"))
-            .Build();
-
-        (string updateText, List<ChatMessage>? result, _, _) = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "abc")]);
-
-        Assert.Equal("Hello from agent1", updateText);
-        Assert.NotNull(result);
-
-        Assert.Equal(2, result.Count);
-
-        Assert.Equal(ChatRole.User, result[0].Role);
-        Assert.Equal("abc", result[0].Text);
-
-        Assert.Equal(ChatRole.Assistant, result[1].Role);
-        Assert.Equal("Hello from agent1", result[1].Text);
-    }
-
-    [Fact]
-    public async Task Handoffs_OneTransfer_ResponseServedBySecondAgentAsync()
-    {
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            ChatMessage message = Assert.Single(messages);
-            Assert.Equal("abc", Assert.IsType<TextContent>(Assert.Single(message.Contents)).Text);
-
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var nextAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-            new(new ChatMessage(ChatRole.Assistant, "Hello from agent2"))),
-            name: "nextAgent",
-            description: "The second agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, nextAgent)
-            .Build();
-
-        (string updateText, List<ChatMessage>? result, _, _) = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "abc")]);
-
-        Assert.Equal("Hello from agent2", updateText);
-        Assert.NotNull(result);
-
-        Assert.Equal(4, result.Count);
-
-        Assert.Equal(ChatRole.User, result[0].Role);
-        Assert.Equal("abc", result[0].Text);
-
-        Assert.Equal(ChatRole.Assistant, result[1].Role);
-        Assert.Equal("", result[1].Text);
-        Assert.Contains("initialAgent", result[1].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[2].Role);
-        Assert.Contains("initialAgent", result[2].AuthorName);
-
-        Assert.Equal(ChatRole.Assistant, result[3].Role);
-        Assert.Equal("Hello from agent2", result[3].Text);
-        Assert.Contains("nextAgent", result[3].AuthorName);
-    }
-
-    [Fact]
-    public async Task Handoffs_OneTransfer_HandoffTargetDoesNotReceiveHandoffFunctionMessagesAsync()
-    {
-        // Regression test for https://github.com/microsoft/agent-framework/issues/3161
-        // When a handoff occurs, the target agent should receive the original user message
-        // but should NOT receive the handoff function call or tool result messages from the
-        // source agent, as these confuse the target LLM into ignoring the user's question.
-
-        List<ChatMessage>? capturedNextAgentMessages = null;
-
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var nextAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedNextAgentMessages = messages.ToList();
-            return new(new ChatMessage(ChatRole.Assistant, "The derivative of x^2 is 2x."));
-        }),
-            name: "nextAgent",
-            description: "The second agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, nextAgent)
-            .Build();
-
-        _ = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "What is the derivative of x^2?")]);
-
-        Assert.NotNull(capturedNextAgentMessages);
-
-        // The target agent should see the original user message
-        Assert.Contains(capturedNextAgentMessages, m => m.Role == ChatRole.User && m.Text == "What is the derivative of x^2?");
-
-        // The target agent should NOT see the handoff function call or tool result from the source agent
-        Assert.DoesNotContain(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name.StartsWith("handoff_to_", StringComparison.Ordinal)));
-        Assert.DoesNotContain(capturedNextAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent frc && frc.Result?.ToString() == "Transferred."));
-    }
-
-    [Fact]
-    public async Task Handoffs_TwoTransfers_HandoffTargetsDoNotReceiveHandoffFunctionMessagesAsync()
-    {
-        // Regression test for https://github.com/microsoft/agent-framework/issues/3161
-        // With two hops (initial -> second -> third), each target agent should receive the
-        // original user message and text responses from prior agents (as User role), but
-        // NOT any handoff function call or tool result messages.
-
-        List<ChatMessage>? capturedSecondAgentMessages = null;
-        List<ChatMessage>? capturedThirdAgentMessages = null;
-
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            // Return both a text message and a handoff function call
-            return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to second agent"), new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedSecondAgentMessages = messages.ToList();
-
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            // Return both a text message and a handoff function call
-            return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to third agent"), new FunctionCallContent("call2", transferFuncName)]));
-        }), name: "secondAgent", description: "The second agent");
-
-        var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedThirdAgentMessages = messages.ToList();
-            return new(new ChatMessage(ChatRole.Assistant, "Hello from agent3"));
-        }),
-            name: "thirdAgent",
-            description: "The third / final agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, secondAgent)
-            .WithHandoff(secondAgent, thirdAgent)
-            .Build();
-
-        (string updateText, _, _, _) = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "abc")]);
-
-        Assert.Contains("Hello from agent3", updateText);
-
-        // Second agent should see the original user message and initialAgent's text as context
-        Assert.NotNull(capturedSecondAgentMessages);
-        Assert.Contains(capturedSecondAgentMessages, m => m.Text == "abc");
-        Assert.Contains(capturedSecondAgentMessages, m => m.Text!.Contains("Routing to second agent"));
-        Assert.DoesNotContain(capturedSecondAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name.StartsWith("handoff_to_", StringComparison.Ordinal)));
-        Assert.DoesNotContain(capturedSecondAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent));
-
-        // Third agent should see the original user message and both prior agents' text as context
-        Assert.NotNull(capturedThirdAgentMessages);
-        Assert.Contains(capturedThirdAgentMessages, m => m.Text == "abc");
-        Assert.Contains(capturedThirdAgentMessages, m => m.Text!.Contains("Routing to second agent"));
-        Assert.Contains(capturedThirdAgentMessages, m => m.Text!.Contains("Routing to third agent"));
-        Assert.DoesNotContain(capturedThirdAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name.StartsWith("handoff_to_", StringComparison.Ordinal)));
-        Assert.DoesNotContain(capturedThirdAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent));
-    }
-
-    [Fact]
-    public async Task Handoffs_FilteringNone_HandoffTargetReceivesAllMessagesIncludingToolCallsAsync()
-    {
-        // With filtering set to None, the target agent should see everything including
-        // handoff function calls and tool results.
-
-        List<ChatMessage>? capturedNextAgentMessages = null;
-
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var nextAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedNextAgentMessages = messages.ToList();
-            return new(new ChatMessage(ChatRole.Assistant, "response"));
-        }),
-            name: "nextAgent",
-            description: "The second agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, nextAgent)
-            .WithToolCallFilteringBehavior(HandoffToolCallFilteringBehavior.None)
-            .Build();
-
-        _ = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "hello")]);
-
-        Assert.NotNull(capturedNextAgentMessages);
-        Assert.Contains(capturedNextAgentMessages, m => m.Text == "hello");
-
-        // With None filtering, handoff function calls and tool results should be visible
-        Assert.Contains(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name.StartsWith("handoff_to_", StringComparison.Ordinal)));
-        Assert.Contains(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionResultContent));
-    }
-
-    [Fact]
-    public async Task Handoffs_FilteringAll_HandoffTargetDoesNotReceiveAnyToolCallsAsync()
-    {
-        // With filtering set to All, the target agent should see no function calls or tool
-        // results at all — not even non-handoff ones from prior conversation history.
-
-        List<ChatMessage>? capturedNextAgentMessages = null;
-
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing you now"), new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var nextAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedNextAgentMessages = messages.ToList();
-            return new(new ChatMessage(ChatRole.Assistant, "response"));
-        }),
-            name: "nextAgent",
-            description: "The second agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, nextAgent)
-            .WithToolCallFilteringBehavior(HandoffToolCallFilteringBehavior.All)
-            .Build();
-
-        // Input includes a pre-existing non-handoff tool call in the conversation history
-        List<ChatMessage> input =
-        [
-            new(ChatRole.User, "What's the weather? Also help me with math."),
-            new(ChatRole.Assistant, [new FunctionCallContent("toolcall1", "get_weather")]) { AuthorName = "initialAgent" },
-            new(ChatRole.Tool, [new FunctionResultContent("toolcall1", "sunny")]),
-            new(ChatRole.Assistant, "The weather is sunny. Now let me route your math question.") { AuthorName = "initialAgent" },
-        ];
-
-        _ = await RunWorkflowAsync(workflow, input);
-
-        Assert.NotNull(capturedNextAgentMessages);
-
-        // With All filtering, NO function calls or tool results should be visible
-        Assert.DoesNotContain(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent));
-        Assert.DoesNotContain(capturedNextAgentMessages, m => m.Role == ChatRole.Tool);
-
-        // But text content should still be visible
-        Assert.Contains(capturedNextAgentMessages, m => m.Text!.Contains("What's the weather"));
-        Assert.Contains(capturedNextAgentMessages, m => m.Text!.Contains("Routing you now"));
-    }
-
-    [Fact]
-    public async Task Handoffs_FilteringHandoffOnly_PreservesNonHandoffToolCallsAsync()
-    {
-        // With HandoffOnly filtering (the default), non-handoff function calls and tool
-        // results should be preserved while handoff ones are stripped.
-
-        List<ChatMessage>? capturedNextAgentMessages = null;
-
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var nextAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            capturedNextAgentMessages = messages.ToList();
-            return new(new ChatMessage(ChatRole.Assistant, "response"));
-        }),
-            name: "nextAgent",
-            description: "The second agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, nextAgent)
-            .WithToolCallFilteringBehavior(HandoffToolCallFilteringBehavior.HandoffOnly)
-            .Build();
-
-        // Input includes a pre-existing non-handoff tool call in the conversation history
-        List<ChatMessage> input =
-        [
-            new(ChatRole.User, "What's the weather? Also help me with math."),
-            new(ChatRole.Assistant, [new FunctionCallContent("toolcall1", "get_weather")]) { AuthorName = "initialAgent" },
-            new(ChatRole.Tool, [new FunctionResultContent("toolcall1", "sunny")]),
-            new(ChatRole.Assistant, "The weather is sunny. Now let me route your math question.") { AuthorName = "initialAgent" },
-        ];
-
-        _ = await RunWorkflowAsync(workflow, input);
-
-        Assert.NotNull(capturedNextAgentMessages);
-
-        // Handoff function calls and their tool results should be filtered
-        Assert.DoesNotContain(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name.StartsWith("handoff_to_", StringComparison.Ordinal)));
-
-        // Non-handoff function calls and their tool results should be preserved
-        Assert.Contains(capturedNextAgentMessages, m => m.Contents.Any(c => c is FunctionCallContent fcc && fcc.Name == "get_weather"));
-        Assert.Contains(capturedNextAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent frc && frc.CallId == "toolcall1"));
-    }
-
-    [Fact]
-    public async Task Handoffs_TwoTransfers_ResponseServedByThirdAgentAsync()
-    {
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            ChatMessage message = Assert.Single(messages);
-            Assert.Equal("abc", Assert.IsType<TextContent>(Assert.Single(message.Contents)).Text);
-
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            // Only a handoff function call.
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            // Second agent should receive the conversation so far (including previous assistant + tool messages eventually).
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call2", transferFuncName)]));
-        }), name: "secondAgent", description: "The second agent");
-
-        var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-            new(new ChatMessage(ChatRole.Assistant, "Hello from agent3"))),
-            name: "thirdAgent",
-            description: "The third / final agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, secondAgent)
-            .WithHandoff(secondAgent, thirdAgent)
-            .Build();
-
-        (string updateText, List<ChatMessage>? result, _, _) = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "abc")]);
-
-        Assert.Equal("Hello from agent3", updateText);
-        Assert.NotNull(result);
-
-        // User + (assistant empty + tool) for each of first two agents + final assistant with text.
-        Assert.Equal(6, result.Count);
-
-        Assert.Equal(ChatRole.User, result[0].Role);
-        Assert.Equal("abc", result[0].Text);
-
-        Assert.Equal(ChatRole.Assistant, result[1].Role);
-        Assert.Equal("", result[1].Text);
-        Assert.Contains("initialAgent", result[1].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[2].Role);
-        Assert.Contains("initialAgent", result[2].AuthorName);
-
-        Assert.Equal(ChatRole.Assistant, result[3].Role);
-        Assert.Equal("", result[3].Text);
-        Assert.Contains("secondAgent", result[3].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[4].Role);
-        Assert.Contains("secondAgent", result[4].AuthorName);
-
-        Assert.Equal(ChatRole.Assistant, result[5].Role);
-        Assert.Equal("Hello from agent3", result[5].Text);
-        Assert.Contains("thirdAgent", result[5].AuthorName);
-    }
-
-    [Fact]
-    public async Task Handoffs_TwoTransfers_SecondAgentUserApproval_ResponseServedByThirdAgentAsync()
-    {
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            ChatMessage message = Assert.Single(messages);
-            Assert.Equal("abc", Assert.IsType<TextContent>(Assert.Single(message.Contents)).Text);
-
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            // Only a handoff function call.
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        bool secondAgentInvoked = false;
-
-        const string SomeOtherFunctionCallId = "call2first";
-
-        AIFunction someOtherFunction = new ApprovalRequiredAIFunction(AIFunctionFactory.Create(SomeOtherFunction));
-
-        var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            if (!secondAgentInvoked)
-            {
-                secondAgentInvoked = true;
-                return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent(SomeOtherFunctionCallId, someOtherFunction.Name)]));
-            }
-
-            // Second agent should receive the conversation so far (including previous assistant + tool messages eventually).
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call2", transferFuncName)]));
-        }), name: "secondAgent", description: "The second agent", tools: [someOtherFunction]);
-
-        var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-            new(new ChatMessage(ChatRole.Assistant, "Hello from agent3"))),
-            name: "thirdAgent",
-            description: "The third / final agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, secondAgent)
-            .WithHandoff(secondAgent, thirdAgent)
-            .Build();
-
-        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
-        const ExecutionEnvironment Environment = ExecutionEnvironment.InProcess_Lockstep;
-
-        (string updateText, List<ChatMessage>? result, CheckpointInfo? lastCheckpoint, List<RequestInfoEvent> requests) =
-            await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "abc")], Environment, checkpointManager);
-
-        Assert.Null(result);
-        Assert.NotNull(requests);
-
-        requests.Should().HaveCount(1);
-        ExternalRequest request = requests[0].Request;
-
-        ToolApprovalRequestContent approvalRequest =
-            request.Data.As<ToolApprovalRequestContent>().Should().NotBeNull()
-                                                              .And.Subject.As<ToolApprovalRequestContent>();
-
-        approvalRequest.ToolCall.CallId.Should().Be(SomeOtherFunctionCallId);
-
-        ExternalResponse response = request.CreateResponse(approvalRequest.CreateResponse(false, "Denied"));
-
-        (updateText, result, _, requests) =
-            await RunWorkflowCheckpointedAsync(workflow, response, Environment, checkpointManager, lastCheckpoint);
-
-        Assert.Equal("Hello from agent3", updateText);
-        Assert.NotNull(result);
-
-        // User + (assistant empty + tool) for each of first two agents + final assistant with text.
-        Assert.Equal(10, result.Count);
-
-        Assert.Equal(ChatRole.User, result[0].Role);
-        Assert.Equal("abc", result[0].Text);
-
-        Assert.Equal(ChatRole.Assistant, result[1].Role);
-        Assert.Equal("", result[1].Text);
-        Assert.Contains("initialAgent", result[1].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[2].Role);
-        Assert.Contains("initialAgent", result[2].AuthorName);
-
-        // Non-handoff tool invocation (and user denial)
-        Assert.Equal(ChatRole.Assistant, result[3].Role);
-        Assert.Equal("", result[3].Text);
-        Assert.Contains("secondAgent", result[3].AuthorName);
-
-        Assert.Equal(ChatRole.User, result[4].Role);
-        Assert.Equal("", result[4].Text);
-
-        // Rejected tool call
-        Assert.Equal(ChatRole.Assistant, result[5].Role);
-        Assert.Equal("", result[5].Text);
-        Assert.Contains("secondAgent", result[5].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[6].Role);
-        Assert.Contains("secondAgent", result[6].AuthorName);
-
-        // Handoff invocation
-        Assert.Equal(ChatRole.Assistant, result[7].Role);
-        Assert.Equal("", result[7].Text);
-        Assert.Contains("secondAgent", result[7].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[8].Role);
-        Assert.Contains("secondAgent", result[8].AuthorName);
-
-        Assert.Equal(ChatRole.Assistant, result[9].Role);
-        Assert.Equal("Hello from agent3", result[9].Text);
-        Assert.Contains("thirdAgent", result[9].AuthorName);
-
-        static bool SomeOtherFunction() => true;
-    }
-
-    [Fact]
-    public async Task Handoffs_TwoTransfers_SecondAgentToolCall_ResponseServedByThirdAgentAsync()
-    {
-        var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            ChatMessage message = Assert.Single(messages);
-            Assert.Equal("abc", Assert.IsType<TextContent>(Assert.Single(message.Contents)).Text);
-
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            // Only a handoff function call.
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "initialAgent");
-
-        bool secondAgentInvoked = false;
-
-        const string SomeOtherFunctionName = "SomeOtherFunction";
-        const string SomeOtherFunctionCallId = "call2first";
-
-        JsonElement otherFunctionSchema = AIFunctionFactory.Create(() => true).JsonSchema;
-        AIFunctionDeclaration someOtherFunction = AIFunctionFactory.CreateDeclaration(SomeOtherFunctionName, "Another function", otherFunctionSchema);
-
-        var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            if (!secondAgentInvoked)
-            {
-                secondAgentInvoked = true;
-                return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent(SomeOtherFunctionCallId, SomeOtherFunctionName)]));
-            }
-
-            // Second agent should receive the conversation so far (including previous assistant + tool messages eventually).
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call2", transferFuncName)]));
-        }), name: "secondAgent", description: "The second agent", tools: [someOtherFunction]);
-
-        var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
-            new(new ChatMessage(ChatRole.Assistant, "Hello from agent3"))),
-            name: "thirdAgent",
-            description: "The third / final agent");
-
-        var workflow =
-            AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
-            .WithHandoff(initialAgent, secondAgent)
-            .WithHandoff(secondAgent, thirdAgent)
-            .Build();
-
-        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
-        const ExecutionEnvironment Environment = ExecutionEnvironment.InProcess_Lockstep;
-
-        (string updateText, List<ChatMessage>? result, CheckpointInfo? lastCheckpoint, List<RequestInfoEvent> requests) =
-            await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "abc")], Environment, checkpointManager);
-
-        Assert.Null(result);
-        Assert.NotNull(requests);
-
-        requests.Should().HaveCount(1);
-        ExternalRequest request = requests[0].Request;
-
-        FunctionCallContent functionCall = request.Data.As<FunctionCallContent>().Should().NotBeNull()
-                                                                                 .And.Subject.As<FunctionCallContent>();
-
-        functionCall.CallId.Should().Be(SomeOtherFunctionCallId);
-        functionCall.Name.Should().Be(SomeOtherFunctionName);
-
-        ExternalResponse response = request.CreateResponse(new FunctionResultContent(functionCall.CallId, true));
-
-        (updateText, result, _, requests) =
-            await RunWorkflowCheckpointedAsync(workflow, response, Environment, checkpointManager, lastCheckpoint);
-
-        Assert.Equal("Hello from agent3", updateText);
-        Assert.NotNull(result);
-
-        // User + (assistant empty + tool) for each of first two agents + final assistant with text.
-        Assert.Equal(8, result.Count);
-
-        Assert.Equal(ChatRole.User, result[0].Role);
-        Assert.Equal("abc", result[0].Text);
-
-        Assert.Equal(ChatRole.Assistant, result[1].Role);
-        Assert.Equal("", result[1].Text);
-        Assert.Contains("initialAgent", result[1].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[2].Role);
-        Assert.Contains("initialAgent", result[2].AuthorName);
-
-        // Non-handoff tool invocation
-        Assert.Equal(ChatRole.Assistant, result[3].Role);
-        Assert.Equal("", result[3].Text);
-        Assert.Contains("secondAgent", result[3].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[4].Role);
-        Assert.Contains("secondAgent", result[4].AuthorName);
-
-        // Handoff invocation
-        Assert.Equal(ChatRole.Assistant, result[5].Role);
-        Assert.Equal("", result[5].Text);
-        Assert.Contains("secondAgent", result[5].AuthorName);
-
-        Assert.Equal(ChatRole.Tool, result[6].Role);
-        Assert.Contains("secondAgent", result[6].AuthorName);
-
-        Assert.Equal(ChatRole.Assistant, result[7].Role);
-        Assert.Equal("Hello from agent3", result[7].Text);
-        Assert.Contains("thirdAgent", result[7].AuthorName);
-    }
-
    [Theory]
    [InlineData(1)]
    [InlineData(2)]
@@ -955,178 +263,8 @@ public class AgentWorkflowBuilderTests
        }
    }

-    [Fact]
-    public async Task Handoffs_ReturnToPrevious_DisabledByDefault_SecondTurnRoutesViaCoordinatorAsync()
-    {
-        int coordinatorCallCount = 0;
-
-        var coordinator = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            coordinatorCallCount++;
-            if (coordinatorCallCount == 1)
-            {
-                string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-                Assert.NotNull(transferFuncName);
-                return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-            }
-            return new(new ChatMessage(ChatRole.Assistant, "coordinator responded on turn 2"));
-        }), name: "coordinator");
-
-        var specialist = new ChatClientAgent(new MockChatClient((messages, options) =>
-            new(new ChatMessage(ChatRole.Assistant, "specialist responded"))),
-            name: "specialist", description: "The specialist agent");
-
-        var workflow = AgentWorkflowBuilder.CreateHandoffBuilderWith(coordinator)
-            .WithHandoff(coordinator, specialist)
-            .Build();
-
-        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
-        const ExecutionEnvironment Environment = ExecutionEnvironment.InProcess_Lockstep;
-
-        // Turn 1: coordinator hands off to specialist
-        WorkflowRunResult result = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "book an appointment")], Environment, checkpointManager);
-        Assert.Equal(1, coordinatorCallCount);
-
-        // Turn 2: without ReturnToPrevious, coordinator should be invoked again
-        _ = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "my id is 12345")], Environment, checkpointManager, result.LastCheckpoint);
-        Assert.Equal(2, coordinatorCallCount);
-    }
-
-    [Fact]
-    public async Task Handoffs_ReturnToPrevious_Enabled_SecondTurnRoutesDirectlyToSpecialistAsync()
-    {
-        int coordinatorCallCount = 0;
-        int specialistCallCount = 0;
-
-        var coordinator = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            coordinatorCallCount++;
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-        }), name: "coordinator");
-
-        var specialist = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            specialistCallCount++;
-            return new(new ChatMessage(ChatRole.Assistant, "specialist responded"));
-        }), name: "specialist", description: "The specialist agent");
-
-        var workflow = AgentWorkflowBuilder.CreateHandoffBuilderWith(coordinator)
-            .WithHandoff(coordinator, specialist)
-            .EnableReturnToPrevious()
-            .Build();
-
-        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
-        const ExecutionEnvironment Environment = ExecutionEnvironment.InProcess_Lockstep;
-
-        // Turn 1: coordinator hands off to specialist
-        WorkflowRunResult result = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "book an appointment")], Environment, checkpointManager);
-        Assert.Equal(1, coordinatorCallCount);
-        Assert.Equal(1, specialistCallCount);
-
-        // Turn 2: with ReturnToPrevious, specialist should be invoked directly, coordinator should NOT be called again
-        _ = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "my id is 12345")], Environment, checkpointManager, result.LastCheckpoint);
-        Assert.Equal(1, coordinatorCallCount); // coordinator NOT called again
-        Assert.Equal(2, specialistCallCount);  // specialist called again
-    }
-
-    [Fact]
-    public async Task Handoffs_ReturnToPrevious_Enabled_BeforeAnyHandoff_RoutesViaInitialAgentAsync()
-    {
-        int coordinatorCallCount = 0;
-
-        var coordinator = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            coordinatorCallCount++;
-            return new(new ChatMessage(ChatRole.Assistant, "coordinator responded"));
-        }), name: "coordinator");
-
-        var specialist = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            Assert.Fail("Specialist should not be invoked.");
-            return new();
-        }), name: "specialist", description: "The specialist agent");
-
-        var workflow = AgentWorkflowBuilder.CreateHandoffBuilderWith(coordinator)
-            .WithHandoff(coordinator, specialist)
-            .EnableReturnToPrevious()
-            .Build();
-
-        // First turn with no prior handoff: should route to initial (coordinator) agent
-        _ = await RunWorkflowAsync(workflow, [new ChatMessage(ChatRole.User, "hello")]);
-        Assert.Equal(1, coordinatorCallCount);
-    }
-
-    [Fact]
-    public async Task Handoffs_ReturnToPrevious_Enabled_AfterHandoffBackToCoordinator_NextTurnRoutesViaCoordinatorAsync()
-    {
-        int coordinatorCallCount = 0;
-        int specialistCallCount = 0;
-
-        var coordinator = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            coordinatorCallCount++;
-            if (coordinatorCallCount == 1)
-            {
-                // First call: hand off to specialist
-                string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-                Assert.NotNull(transferFuncName);
-                return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", transferFuncName)]));
-            }
-            // Subsequent calls: respond without handoff
-            return new(new ChatMessage(ChatRole.Assistant, "coordinator responded"));
-        }), name: "coordinator");
-
-        var specialist = new ChatClientAgent(new MockChatClient((messages, options) =>
-        {
-            specialistCallCount++;
-            // Specialist hands back to coordinator
-            string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
-            Assert.NotNull(transferFuncName);
-            return new(new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call2", transferFuncName)]));
-        }), name: "specialist", description: "The specialist agent");
-
-        var workflow = AgentWorkflowBuilder.CreateHandoffBuilderWith(coordinator)
-            .WithHandoff(coordinator, specialist)
-            .WithHandoff(specialist, coordinator)
-            .EnableReturnToPrevious()
-            .Build();
-
-        CheckpointManager checkpointManager = CheckpointManager.CreateInMemory();
-        const ExecutionEnvironment Environment = ExecutionEnvironment.InProcess_Lockstep;
-
-        // Turn 1: coordinator → specialist → coordinator (specialist hands back)
-        WorkflowRunResult result = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "book an appointment")], Environment, checkpointManager);
-        Assert.Equal(2, coordinatorCallCount); // called twice: initial handoff + receiving handback
-        Assert.Equal(1, specialistCallCount);  // specialist called once, then handed back
-
-        // Turn 2: after handoff back to coordinator, should route to coordinator (not specialist)
-        _ = await RunWorkflowCheckpointedAsync(workflow, [new ChatMessage(ChatRole.User, "never mind")], Environment, checkpointManager, result.LastCheckpoint);
-        Assert.Equal(3, coordinatorCallCount); // coordinator called again on turn 2
-        Assert.Equal(1, specialistCallCount);  // specialist NOT called
-    }
-
    private sealed record WorkflowRunResult(string UpdateText, List<ChatMessage>? Result, CheckpointInfo? LastCheckpoint, List<RequestInfoEvent> PendingRequests);

-    private static Task<WorkflowRunResult> RunWorkflowCheckpointedAsync(
-        Workflow workflow, List<ChatMessage> input, ExecutionEnvironment executionEnvironment, CheckpointManager checkpointManager, CheckpointInfo? fromCheckpoint = null)
-    {
-        InProcessExecutionEnvironment environment = executionEnvironment.ToWorkflowExecutionEnvironment()
-                                                                        .WithCheckpointing(checkpointManager);
-
-        return RunWorkflowCheckpointedAsync(workflow, input, environment, fromCheckpoint);
-    }
-
-    private static Task<WorkflowRunResult> RunWorkflowCheckpointedAsync(
-        Workflow workflow, ExternalResponse response, ExecutionEnvironment executionEnvironment, CheckpointManager checkpointManager, CheckpointInfo? fromCheckpoint = null)
-    {
-        InProcessExecutionEnvironment environment = executionEnvironment.ToWorkflowExecutionEnvironment()
-                                                                        .WithCheckpointing(checkpointManager);
-
-        return RunWorkflowCheckpointedAsync(workflow, response, environment, fromCheckpoint);
-    }
-
    private static async Task<WorkflowRunResult> RunWorkflowCheckpointedAsync(
        Workflow workflow, List<ChatMessage> input, InProcessExecutionEnvironment environment, CheckpointInfo? fromCheckpoint = null)
    {
@@ -1140,18 +278,6 @@ public class AgentWorkflowBuilderTests
        return await ProcessWorkflowRunAsync(run);
    }

-    private static async Task<WorkflowRunResult> RunWorkflowCheckpointedAsync(
-        Workflow workflow, ExternalResponse response, InProcessExecutionEnvironment environment, CheckpointInfo? fromCheckpoint = null)
-    {
-        await using StreamingRun run =
-            fromCheckpoint != null ? await environment.ResumeStreamingAsync(workflow, fromCheckpoint)
-                                   : await environment.OpenStreamingAsync(workflow);
-
-        await run.SendResponseAsync(response);
-
-        return await ProcessWorkflowRunAsync(run);
-    }
-
    private static async Task<WorkflowRunResult> ProcessWorkflowRunAsync(StreamingRun run)
    {
        StringBuilder sb = new();
@@ -1212,22 +338,4 @@ public class AgentWorkflowBuilderTests
            }
        }
    }
-
-    private sealed class MockChatClient(Func<IEnumerable<ChatMessage>, ChatOptions?, ChatResponse> responseFactory) : IChatClient
-    {
-        public Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default) =>
-            Task.FromResult(responseFactory(messages, options));
-
-        public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
-            IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
-        {
-            foreach (var update in (await this.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false)).ToChatResponseUpdates())
-            {
-                yield return update;
-            }
-        }
-
-        public object? GetService(Type serviceType, object? serviceKey = null) => null;
-        public void Dispose() { }
-    }
 }
Author	SHA1	Message	Date
Jacob Alber	aeb2e124c7	test: Add unit tests for Handoff FunctionCall/Result matching fix	2026-05-08 14:52:11 -04:00
Jacob Alber	f8c6320cb9	fix: Synthesized Handoff FunctionResult is never sent to agent When we receive a handoff request from the agent, we need to service it outside of the Agent Loop to terminate the loop. What this means is that we take ownership of terminating the call by feeding the result back into the agent on a subsequent invocation. When we refactored Handoff to support HITL and make use of AgentSession, we inadvertantly removed this step, causing subsequent invocations to the Handoff agent to fail (first works, but breaks the state). The fix is to be more precise about the agent's bookmark when concatenating the result of agent invocation to the shared conversation history.	2026-05-08 14:34:48 -04:00
Jacob Alber	4377806ee5	test: Split out Handoff Orchestration tests	2026-05-08 14:29:03 -04:00
westeyandGitHub	0557b5782b	.NET: Add IChatMessageInjector for message injection during function loop (#5679 ) * Adding the ability to inject messages during the function call loop * Split message injection functionality * Remove interface, since it is not required not that we split the chat client. * Address conversation id propogation * Fix formatting issue	2026-05-08 17:16:03 +00:00
Roger BarretoandGitHub	eb709d8fc9	.NET: Update FoundryAgent to address HostedAgents strict URL routing (#5677 ) * .NET: Foundry agent-endpoint constructor uses ProjectOpenAIClient directly to fix hosted-agent URL routing Fixes the experimental FoundryAgent(Uri agentEndpoint, AuthenticationTokenProvider, ...) constructor so it actually works against Foundry hosted agents. The previous implementation routed through AzureAIProjectChatClient, which internally called aiProjectClient.GetProjectOpenAIClient().GetProjectResponsesClientForAgent(...). For an agent-endpoint URL of the canonical shape https://<host>/api/projects/<project>/agents/<agentName>/endpoint/protocols/openai the chain produced POST https://<host>/api/projects/<project>/openai/v1/responses (project-level path, no /agents/ segment). The Foundry service rejects this with HTTP 400 "Hosted agents can only be called through the agent endpoint: .../agents/<agentName>/endpoint/protocols/openai/responses". The constructor also extracted the agent name via agentEndpoint.Segments[^1].TrimEnd('/'), which returns "openai" (the last segment), not the agent name. What changed - Public ctor signature: clientOptions parameter type changed from AIProjectClientOptions? to ProjectOpenAIClientOptions?. The constructor is fundamentally building a ProjectOpenAIClient; accepting AIProjectClientOptions was a leaky abstraction whose translation silently dropped any pipeline policies the caller added via AddPolicy(...). With the direct type, caller policies pass through to the per-agent traffic verbatim. - Per-agent client construction: `new ProjectOpenAIClient(BearerTokenPolicy, ProjectOpenAIClientOptions)` with Endpoint and AgentName set, then `GetProjectResponsesClient().AsIChatClient()`. The SDK auto-appends ?api-version=v1 when AgentName is set. - New private static ParseAgentEndpoint helper: single source of truth for both agent-name extraction and project-root derivation. Tolerates trailing slash, case variants on /agents/ and the suffix segment, strips query/fragment, and throws ArgumentException with paramName=nameof(agentEndpoint) for malformed input. - Project-level client (used by CreateConversationSessionAsync) is built fresh from the derived project root with primitive properties copied (RetryPolicy/NetworkTimeout/Transport/UserAgentApplicationId) plus MEAI UA. - New GetService<ProjectOpenAIClient>() entry alongside the existing GetService<AIProjectClient>() (the latter returns null in agent-endpoint mode since no AIProjectClient is constructed on that path). - Endpoint and AgentName on caller-supplied ProjectOpenAIClientOptions are overridden by values derived from agentEndpoint. Compatibility - FoundryAgent is [Experimental(OPENAI001)]. No GA surface touched. The Foundry project does not maintain PublicAPI..txt baselines so there is no shipped baseline to update. - The Microsoft.Agents.AI.Foundry csproj pins Azure.AI.Projects to VersionOverride 2.1.0-beta.1 (matching what the IT and hosting projects already use); the central pin in Directory.Packages.props stays at 2.0.0. - WireClientHeaders from PR #5652 is invoked on the agent-endpoint path so per-call x-client- headers behave identically across both ctors. Tests - 23 new unit tests in FoundryAgentTests.cs: - 12 for the agent-endpoint constructor (URL routing for non-streaming and streaming, conversations URL shape, MEAI UA stamping, caller-policy passthrough on the per-agent pipeline, Endpoint/AgentName override semantics, GetService matrix, ProjectOpenAIClient propagation, UserAgentApplicationId propagation, null-arg validation, ID/Name slug) - 9 for ParseAgentEndpoint (standard shape, trailing slash, casing, sovereign-cloud host without /api/projects/ literal prefix, special chars in agent name, query/fragment stripping, three negative cases) - 2 null-arg tests for the public ctor - All 250 Microsoft.Agents.AI.Foundry.UnitTests pass (was 221 baseline plus 29 from PR #5652 plus 23 new in this PR equals 273; pre-existing tests collapsed by the rebase merge keep the total at 250). - All 225 Microsoft.Agents.AI.Foundry.Hosting.UnitTests pass; no behavioral change to the hosting layer. - dotnet build clean across net8/9/10/netstandard2.0/net472 with TreatWarningsAsErrors=true. - dotnet format --verify-no-changes clean for the touched src and test projects. * .NET: Bump central Azure.AI.Projects pin to 2.1.0-beta.1 and flip Microsoft.Agents.AI.Foundry to preview Required to fix the NU1109 downgrade chain that broke CI on the agent-endpoint constructor rewire (#5677). Microsoft.Agents.AI.Foundry now depends on ProjectOpenAIClientOptions.AgentName and the (AuthenticationPolicy, options) constructor that only exist in Azure.AI.Projects 2.1.0-beta.1. Changes: * Directory.Packages.props: Azure.AI.Projects 2.0.0 -> 2.1.0-beta.1. * Microsoft.Agents.AI.Foundry.csproj: drop IsReleased=true so the package ships as preview (matches the beta SDK we now depend on). Add a comment noting the flip is temporary and should revert once Azure.AI.Projects ships a stable 2.1.0. * Drop redundant VersionOverride="2.1.0-beta.1" from the 10 csprojs that had it as a workaround; the central pin now suffices. Verified: * dotnet build agent-framework-dotnet.slnx --warnaserror clean across all TFMs. * Microsoft.Agents.AI.Foundry.UnitTests 250/250 pass. * Microsoft.Agents.AI.Foundry.Hosting.UnitTests 211/211 pass. * dotnet format --verify-no-changes clean for the touched src and test projects.	2026-05-08 14:46:52 +00:00
westeyandGitHub	226c004b53	Add hyperlight to release slnf (#5695 )	2026-05-08 09:28:35 +00:00
Jacob AlberandGitHub	3aae3cb9de	Update version for release (#5703 )	2026-05-08 00:17:44 +00:00