.NET: Add factory delegate overload to MapAGUI for per-request agent resolution

[Ashutosh0x]

Motivation and Context

This PR implements Phase 1 of ADR-0029 — the factory delegate approach recommended by @javiercn for dynamic per-request agent resolution.

The problem (confirmed in source code)

All three hosting channels currently resolve the AIAgent and AgentSessionStore once at startup via endpoints.ServiceProvider:

// AGUIEndpointRouteBuilderExtensions.cs:59 — agent captured at startup
var agent = endpoints.ServiceProvider.GetRequiredKeyedService<AIAgent>(agentName);

// AGUIEndpointRouteBuilderExtensions.cs:105 — session store captured at startup  
var agentSessionStore = endpoints.ServiceProvider.GetKeyedService<AgentSessionStore>(aiAgent.Name);

// AGUIEndpointRouteBuilderExtensions.cs:115 — both captured in closure
var hostAgent = new AIHostAgent(aiAgent, agentSessionStore);

This singleton-capture prevents:

• Route-based multi-tenant hosting (/agents/{agentId}) — .NET: Support dynamic agent resolution in AG-UI endpoints (MapAGUI with factory delegate) #2988, .NET: Support dynamic agent resolution in AG-UI endpoints #3162
• Per-request session store scoping — @halllo's analysis on .NET: Support dynamic agent resolution in AG-UI endpoints #3162
• Claims-based agent selection — different tenants, different agents

The solution

New MapAGUI overload accepting a factory delegate:

app.MapAGUI(/agents/{agentId}, async (HttpContext context, CancellationToken ct) =>
{
    var agentId = context.GetRouteValue(agentId)?.ToString();
    return agentId switch
    {
        weather => weatherAgent,
        search => searchAgent,
        _ => null // 404
    };
});

Key implementation details:

• Agent resolved per-request via factory delegate (not at startup)
• AgentSessionStore resolved per-request from HttpContext.RequestServices (fixes singleton-capture)
• IsolationKeyScopedAgentSessionStore wrapping applied per-request
• Returns 404 when factory returns null, 400 for null input body
• Full XML documentation with trust model cross-reference
• 100% backward compatible — existing MapAGUI(pattern, agent) overloads unchanged

Design decisions

Following @javiercn's guidance on #6643:

• Uses the familiar minimal API factory pattern (no new abstractions)
• Per-request resolution via HttpContext.RequestServices (not IHttpContextAccessor)
• Consistent with how ASP.NET Core handles AddDbContext, AddAuthentication, etc.

Scope

This PR covers AG-UI only as the first channel. OpenAI Responses and A2A have different architectures (service-based vs delegate-based) and will follow in subsequent PRs once the pattern is validated.

References

• .NET: Support dynamic agent resolution in AG-UI endpoints (MapAGUI with factory delegate) #2988 — Original issue requesting dynamic agent selection
• .NET: Support dynamic agent resolution in AG-UI endpoints #3162 — Dynamic agent resolution in AG-UI endpoints (@TheEagleByte)
• .NET: MapAGUI supports per-request agent selection #2343 — Earlier per-request agent selection PR (@halllo)
• .NET: ADR for unified dynamic agent resolution across AG-UI, Responses, and A2A #6643 — ADR for unified dynamic agent resolution (this PR's design doc)
• @javiercn: 'the frameworks could simply put the HttpContext instance on the additional properties... you get to run your resolution logic within a delegating handler'
• @DeagleGross: 'can you please share the sample where overloads today dont allow you to do X' — this PR IS that sample

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass
• Is this a breaking change? No — additive overload only
• Related ADR: .NET: ADR for unified dynamic agent resolution across AG-UI, Responses, and A2A #6643

cc @javiercn @DeagleGross @westey-m @rogerbarreto

[Copilot]

Pull request overview

Adds an additive AG-UI hosting API for per-request agent resolution in the .NET ASP.NET Core AG-UI endpoint builder, avoiding startup-time singleton capture and enabling multi-tenant/dynamic routing scenarios.

Changes:

• Adds a new MapAGUI(pattern, Func<HttpContext, CancellationToken, ValueTask<AIAgent?>> agentFactory) overload for per-request agent selection.
• Resolves AgentSessionStore and SessionIsolationKeyProvider from HttpContext.RequestServices (per-request scope) instead of endpoints.ServiceProvider.
• Mirrors the existing AG-UI execution pipeline (run options, streaming, SSE result, and post-stream session save) for the factory-based overload.

[Ashutosh0x]

Good catch! Pushed 0131d01 addressing both review items:

1. Tests added — 3 new unit tests for the factory delegate overload:
   • MapAGUI_WithFactoryDelegate_MapsEndpoint_AtSpecifiedPattern
   • MapAGUI_WithNullFactory_ThrowsArgumentNullException
   • MapAGUI_WithFactoryDelegate_AndNullEndpoints_ThrowsArgumentNullException

These follow the same Moq + xUnit pattern used by the existing overload tests.

[Ashutosh0x]

Fixed! Extracted the shared execution pipeline into a private ExecuteAgentRequestAsync helper method. Both overloads now call into it:

• Static overload: resolves agent/session at startup, then calls ExecuteAgentRequestAsync
• Factory overload: resolves agent/session per-request, then calls ExecuteAgentRequestAsync

This ensures the message conversion, run options, streaming pipeline, and session save logic stay in sync when AG-UI behavior changes.