.NET: ADR for unified dynamic agent resolution across AG-UI, Responses, and A2A

[Ashutosh0x]

Motivation and Context

This ADR addresses the cross-channel consistency requirement raised by @javiercn on #3162:

'Before we move forward with this change, we'd rather have a broader discussion to establish the pattern here, as this needs to be applied not only to AG-UI but to Open AI responses and A2A and we'd rather do everything simultaneously.'

All three hosting channel endpoint builders (MapAGUI, MapOpenAIResponses, MapA2AHttpJson) currently resolve the AIAgent instance once at endpoint registration time. This singleton-capture prevents dynamic per-request agent resolution needed for multi-tenant platforms.

@halllo further identified that AgentSessionStore is also singleton-captured, breaking scoped/transient DI registrations.

Description

Proposes an IAgentResolver interface in the hosting core plus factory-delegate overloads for all three channel types:

1. IAgentResolver interface - shared DI-registered resolver for route-based/claims-based agent selection
2. Factory delegate overloads - inline Func<HttpContext, CancellationToken, ValueTask<AIAgent?>> for quick prototyping
3. Per-request session store resolution - fixes the singleton-capture bug by resolving from HttpContext.RequestServices

The ADR analyzes 3 options (HttpContextRoutingAgent workaround, factory delegates only, IAgentResolver + factory dual API) and recommends the dual API approach.

References

• .NET: Support dynamic agent resolution in AG-UI endpoints #3162 - .NET: Support dynamic agent resolution in AG-UI endpoints
• .NET: Support dynamic agent resolution in AG-UI endpoints (MapAGUI with factory delegate) #2988 - Original issue
• .NET: MapAGUI supports per-request agent selection #2343 - Earlier PR by @halllo

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass (no code changes, ADR only)
• Is this a breaking change? No - design proposal only

[Copilot]

Pull request overview

This PR adds a new Architecture Decision Record (ADR) proposing a unified approach to resolve AIAgent instances dynamically per request across the three .NET hosting channels (AG-UI, OpenAI Responses, A2A), addressing current endpoint-registration-time singleton capture that blocks multi-tenant routing and breaks scoped session store usage.

Changes:

• Introduces ADR-0029 documenting the problem (startup-time agent/session-store capture) and proposing a dual API: IAgentResolver (DI-based) plus factory delegate overloads.
• Specifies per-request AgentSessionStore resolution via HttpContext.RequestServices to support scoped/transient registrations.
• Documents expected error-handling behavior (404 on null resolution, 500 on exceptions, startup error if missing resolver).

[Ashutosh0x]

cc @javiercn — This ADR directly addresses the cross-channel consistency requirement you raised on #3162:

'Before we move forward with this change, we'd rather have a broader discussion to establish the pattern here, as this needs to be applied not only to AG-UI but to Open AI responses and A2A and we'd rather do everything simultaneously.'

I analyzed all three endpoint builders (MapAGUI, MapOpenAIResponses, MapA2AHttpJson) and found the same singleton-capture pattern in each. The ADR proposes a dual API approach — IAgentResolver interface for DI-registered resolvers + factory delegate overloads for inline resolution — that works identically across all three channel types.

Would love your architectural feedback, particularly on:

1. Whether the IAgentResolver abstraction captures the right granularity
2. Whether per-request AgentSessionStore resolution from HttpContext.RequestServices is the right fix for the scoping bug @halllo identified
3. Whether this should live in Microsoft.Agents.AI.Hosting or a more specific package

Happy to iterate based on your guidance!

[javiercn]

I don't feel strongly about what we do in this regard, provided we are consistent and that other folks like @DeagleGross and @ReubenBond @rogerbarreto or @westey-m are happy with the approach.

They might have different opinions on alternative ways in which this can be done/achieved.

That said, the IHttpContextAccessor pattern is not the end of the world, especially if the framework provided it. You can just wrap the agent, or the frameworks could simply put the HttpContext instance on the additional properties of the options, and you get to run your resolution logic within a delegating handler which you can already create with Use(...)

[Ashutosh0x]

Thanks @javiercn — really appreciate the feedback and the direction!

You're right that the IHttpContextAccessor pattern is pragmatic and already familiar to ASP.NET Core developers. Let me think through both approaches:

Option A: IHttpContextAccessor + Use(...) (your suggestion)

csharp app.MapAGUI(/agents/{agentId}, agent) .Use(async (context, next) => { var httpContext = context.HttpContext; var agentId = httpContext.GetRouteValue(agentId); // resolve agent from DI or factory var agent = resolver.Resolve(agentId); // set on additional properties httpContext.Items[ResolvedAgent] = agent; await next(context); });

Pros: No new abstractions needed, uses existing middleware pipeline, developers already know this pattern.

Cons: The initial agent parameter is still required at registration time (even if ignored at runtime), and the resolution logic is duplicated across each endpoint unless wrapped in a shared middleware.

Option B: IAgentResolver (ADR proposal)

Pros: Single abstraction, enforced consistency, testable via DI.

Cons: New interface to learn, more opinionated.

My take

Given your preference for consistency without being overly prescriptive, I think the best path forward is:

1. Add HttpContext to the options/additional properties (as you suggested) — this is a minimal, non-breaking change that unblocks dynamic resolution for all three channels
2. Document the Use(...) pattern as the recommended approach for per-request agent selection
3. Defer IAgentResolver as a potential future convenience layer if the community gravitates toward it

I'll update the ADR to incorporate this direction. Happy to defer to @DeagleGross, @ReubenBond, @rogerbarreto, and @westey-m on which approach feels most natural for the .NET hosting surface.

Also addressing Copilot's review — will fix the AddSingleton → AddScoped registration for resolvers that depend on scoped services (DbContext, etc.).

[Ashutosh0x]

Addressed Copilot's review — pushed ee49e2b5: changed AddSingleton<IAgentResolver> → AddScoped<IAgentResolver>.

This ensures resolvers that depend on scoped services (DbContext, per-request repositories) work correctly. Per-request resolution is the core intent of this ADR, so scoped lifetime is the natural fit.

Thanks for the catch @copilot!

[Ashutosh0x]

ADR Revised — Incorporating @javiercn's Feedback

Updated the ADR (commit a04a40fe) based on Javier's architectural guidance:

What Changed

1. Added Option 4 — Use(...) middleware + HttpContext on additional properties (Javier's suggestion). Full code examples showing both inline middleware and framework-level AgentRequestOptions approaches.

2. Restructured Decision Outcome as a phased approach:

   • Phase 1 (minimal, non-breaking): Expose HttpContext on options, document Use(...) pattern, fix per-request AgentSessionStore resolution
   • Phase 2 (if community demand): Factory delegate overloads + IAgentResolver convenience layer

3. Added Maintainer Feedback section with @javiercn's direct quote and key takeaways

4. Expanded consulted list per Javier's request: cc @DeagleGross @ReubenBond @rogerbarreto @westey-m

The revision prioritizes minimal framework changes using established ASP.NET Core patterns (middleware pipeline, IHttpContextAccessor) rather than introducing new abstractions.

Would love input from the team on whether Phase 1 captures the right scope. Happy to iterate further!

[DeagleGross]

Hey, thanks for filing and working on this! Recently not being an active contributor to agent-framework, but placed a couple of comments below. I am sure @westey-m can provide more insights here.

[DeagleGross]

I dont see this being much different from resolving AIAgent from the registered instances in the DI container. Default implementation of this will do basically same GetRequiredService(agentname) or similar. Is there any specific use-case where this is helping to solve some problem?

[Ashutosh0x]

Great question @DeagleGross! You are right that a default IAgentResolver would basically do GetRequiredService. The key difference is when and how the agent name is determined:

Today (DI only): The agent is resolved once at startup in MapAGUI(pattern, agent). You can register multiple named agents, but there is no hook to select between them per-request based on route data.

Where dynamic resolution adds value:

1. Route-based - /agents/{agentId} where agentId comes from the URL at request time
2. Claims-based - Different tenants get different agents based on JWT claims
3. Database-driven - Agent definitions stored in a DB, not statically in DI

That said, per @javiercn feedback, I have revised the ADR to deprioritize IAgentResolver in favor of Phase 1: expose HttpContext on options and use Use(...) middleware. This achieves the same result without a new abstraction. IAgentResolver is now Phase 2 only if community demand warrants it. Does that align with your thinking?

[DeagleGross]

This makes sense, but ideally for demo-purposes can you please share the sample where overloads today dont allow you to do X, and with the new overload you can do it? That will be a "proof" of why those overloads are important to exist

[Ashutosh0x]

Absolutely! Here is a concrete before/after:

Today — you CANNOT do this:
`csharp
// Goal: serve different agents based on URL
// e.g. GET /agents/weather/ag-ui vs GET /agents/search/ag-ui

// This does NOT work — agent is captured at startup:
app.MapAGUI(/agents/{agentId}, weatherAgent);
// ^ weatherAgent is always used, {agentId} route param is ignored
`

Workaround today — brittle HttpContextRoutingAgent:
csharp // You have to create a wrapper agent that overrides every method: public class RoutingAgent : AIAgent { private readonly IHttpContextAccessor _accessor; public override async Task<AgentResponse> RunAsync(...) { var ctx = _accessor.HttpContext; var id = ctx.GetRouteValue(agentId); var real = await _repo.GetAgent(id); return await real.RunAsync(...); // delegate everything } // Must also override: RunStreamingAsync, CreateSessionAsync, // GetSessionAsync, SerializeSession (not async!), etc. }

With factory delegate overload — clean and simple:
csharp app.MapAGUI(/agents/{agentId}, async (context, ct) => { var agentId = context.GetRouteValue(agentId)?.ToString(); return await agentRepo.GetAgentAsync(agentId, ct); }); // Session store also resolved per-request automatically

The core problem: today the agent is a startup-time constant, but multi-tenant platforms need it to be a request-time variable. The workaround requires duplicating the entire AIAgent surface area.

[Ashutosh0x]

Phase 1 Implementation PR Created

I've opened #6659 with the actual implementation of the factory delegate overload for MapAGUI, following the approach discussed here.

ADR (this PR) → Implementation (#6659)

The implementation resolves agents and session stores per-request from HttpContext.RequestServices instead of capturing at startup, exactly as proposed in the revised Phase 1 approach.