.NET: Add MapAGUI overload that resolves the agent per request via a factory

[darthmolen]

Summary

Adds a MapAGUI overload that resolves the agent per request via a factory delegate, instead of capturing a single AIAgent at startup from the root service provider.

public static IEndpointConventionBuilder MapAGUI(
    this IEndpointRouteBuilder endpoints,
    string agentName,
    [StringSyntax("route")] string pattern,
    Func<IServiceProvider, string, AIAgent> createAgentDelegate)

Motivation

The existing MapAGUI overloads resolve one keyed AIAgent once at map time (endpoints.ServiceProvider.GetRequiredKeyedService<AIAgent>(name)). Hosts that must build the agent per request — for per-request authentication, scoped tool/MCP sessions, or conversation-scoped configuration — have no supported entry point and must work around it (e.g. a singleton facade AIAgent that re-resolves a real agent on each run).

This overload invokes the factory once per request with the request's IServiceProvider (HttpContext.RequestServices) and the agent name, so request-scoped services resolve correctly. It mirrors the existing AddAIAgent(name, Func<IServiceProvider, string, AIAgent>) delegate shape.

Details

• The keyed AgentSessionStore lookup and the ThreadId trust model are unchanged; the store is resolved per request from HttpContext.RequestServices using agentName as the key.
• The shared request-handling body is factored into a private HandleRunAsync reused by both the instance and factory overloads (no behavior change to the existing path).
• Argument null-checks for endpoints, agentName, and createAgentDelegate; the factory returning null throws a clear InvalidOperationException.

Tests

Adds unit tests: the overload maps an endpoint; it defers resolution (factory not invoked and no keyed AIAgent resolved at map time, unlike the startup-capture overloads); and a null-factory guard. All 38 tests in Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests pass on net8.0/net9.0/net10.0.

Closes #2988
Related to #5209

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new MapAGUI overload that creates an AIAgent per request via a factory delegate, and refactors the shared request-handling logic into a helper to reduce duplication.

Changes:

• Added MapAGUI overload accepting Func<IServiceProvider, string, AIAgent> for per-request agent resolution.
• Refactored endpoint handler body into HandleRunAsync and reused it from existing overload(s).
• Added unit tests for the new overload (mapping, deferral behavior, and null delegate guard).

Reviewed changes

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

File	Description
dotnet/tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/AGUIEndpointRouteBuilderExtensionsTests.cs	Adds new unit tests targeting the new factory-delegate MapAGUI overload and its mapping-time behavior.
dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/AGUIEndpointRouteBuilderExtensions.cs	Introduces the per-request factory-delegate overload and extracts shared request processing into HandleRunAsync.

[darthmolen]

@microsoft-github-policy-service agree

[hansmbakker]

This would be helpful! I had to add IServiceScopeFactory scopeFactory to my tools to be able to use scopes with Entity Framework in them, and if I understand this PR correctly that workaround would become redundant then.