.NET: [BREAKING] Support scoped and transient agent lifetimes in Foundry Hosting - #10238

Motivation & Context

During review of #10132, westey (@westey-m) noted that Foundry hosting needs more options for configuring the agent DI scope (comment). This PR follows up on that.

Microsoft.Agents.AI.Hosting already lets callers choose a ServiceLifetime for agents and for session stores (#4476, issue #4457), and the generic OpenAI Responses host resolves agents from a scope that stays open for the whole streamed response (#8423). Foundry hosting had neither:

• AgentFrameworkResponseHandler is a singleton and resolved every agent and session store from the root IServiceProvider. It never created a scope.
• A Scoped agent therefore threw on every request when scope validation was on. When validation was off, it silently became one shared instance for the whole process.
• A Transient agent that implements IDisposable was kept alive by the root container until shutdown.
• Both readiness health checks also resolved agents from the root container, so a Scoped registration failed there too.
• A session store could only be passed as an object together with an agent, and that store also became the fallback store for every other agent.

The HTTP request scope cannot be reused for this. Background responses keep running after the HTTP response is sent, and a resilient recovery calls the handler again in a new process with no HTTP request at all.

Description & Review Guide

• What are the major changes?
  • AgentFrameworkResponseHandler.CreateAsync creates one AsyncServiceScope per call and resolves the agent and the session store from it. await using disposes the scope when the event stream ends, whether the run completes, fails, is cancelled, the client disconnects, or the run is handed off for recovery. This is the same pattern as HostedAgentResponseExecutor in the OpenAI host.
  • The hosted user-identity check now runs before any agent or store is created, so a rejected request never invokes a caller-supplied factory.
  • HostedStoredOutputHealthCheck and HostedWorkflowCheckpointingHealthCheck resolve agents inside a short-lived scope.
  • New AddFoundryResponses overloads on both IHostApplicationBuilder and IServiceCollection take an agent factory and a ServiceLifetime (Singleton by default, like AddAIAgent in Microsoft.Agents.AI.Hosting):

    // Existing, unchanged: one agent object for the process
    builder.AddFoundryResponses(myAgent);
    
    // New
    builder.AddFoundryResponses(
        "my-agent",
        sp => new MyAgent(sp.GetRequiredService<MyDbContext>()),
        ServiceLifetime.Scoped);

    • The agent is registered only under the name. There is no non-keyed registration that forwards to the keyed one, because Microsoft DI records a factory's result for disposal once per registration, and a forwarding registration would dispose the same object twice.
    • When no default agent exists yet, an internal FoundryDefaultAgentName records this agent's name, and the response handler routes requests without a matching agent name to it. The instance overload no longer takes the default slot when a factory agent already holds it.
    • An existing keyed registration takes precedence, matching the instance overload's TryAdd behavior. The factory call then adds nothing for the agent.
  • New AddFoundryAgentSessionStore overloads on both builders register a session store separately from agents, following the precedent of WithSessionStore in Microsoft.Agents.AI.Hosting. The store's lifetime is independent of the agent's, which is safe because the handler uses the store directly and passes the agent on every call:

    // For every agent without a store of its own. DI never disposes an object you pass in.
    builder.AddFoundryAgentSessionStore(mySessionStore);
    
    // A factory with its own lifetime (Singleton by default), optionally for one agent only.
    builder.AddFoundryAgentSessionStore(
        sp => new MySessionStore(sp.GetRequiredService<MyDbContext>()),
        ServiceLifetime.Scoped,
        agentName: "my-agent");

    • For each response, the handler uses the store registered under the agent's name, then the store registered for all agents, then the default store. A request answered by the default agent uses that agent's own store.
    • Calling it again for the same agent name, or again for all agents, replaces the earlier registration, including one made by AddFoundryResponses(agent, store) or directly in DI, in whatever order the methods are called.
  • Breaking behavior: AddFoundryResponses(agent, store) now registers store only under the agent's name. On main it also became the store for all agents. Without a store, it no longer registers a separate default store under the agent's name, so the agent falls back to the store registered for all agents.
  • Factory agents store sessions where the instance overload would put an agent with the same name registered in the same order: name:{agentName} for the agent that receives requests without a matching name, and key:{agentName} for every other agent. That holds for every lifetime. The handler checks at run time whether a non-keyed AIAgent took the default role, so such an agent never shares sessions with a factory agent of the same name.
  • Falling back from an agent's own store to the store registered for all agents is now the normal path, so that log message moves from Warning to Debug.
  • XML docs explain each lifetime, how a store is chosen, that moving an agent to a different store leaves its earlier sessions behind, and that the response scope is not the ASP.NET Core request scope. The Hosted-ChatClientAgent README gains an "Agent lifetime" section.
• What is the impact of these changes?

  • Singleton registrations behave exactly as before, because a scope returns the same root instance.

  • Scoped and Transient registrations now work, including keyed registrations made by hand and AddAIAgent(..., lifetime) from Microsoft.Agents.AI.Hosting.

  • Lifetime behavior, for agents and for stores registered with a factory:

    Lifetime	Created	Disposed
    Singleton	once per process	once, at app shutdown
    Scoped	once per response run	once, when that run's event stream ends, even after the HTTP request has returned
    Transient	on every lookup	once, when that run's event stream ends

  • Conversation state still comes from the saved session, not from the agent object. A new agent per turn therefore loses nothing.

  • Breaking behavior, only for apps that mix registration styles:

    1. AddFoundryResponses(agentA, storeA) plus another agent registered by hand: the other agent moves from storeA to the store registered for all agents, or the default store.
    2. A non-keyed AgentSessionStore registered by hand plus AddFoundryResponses(agentA) without a store: agent A moves from its own default store to the store registered by hand.

    In both cases the affected agent's earlier sessions stay in the old store and are no longer found. No error is raised; those conversations start without their history. Apps with a single agent, apps that add several agents with AddFoundryResponses(agent, ...), and apps that only use AddFoundryResponses() with agents registered by hand are not affected. No public API from main is removed or changed.

• What do you want reviewers to focus on?
  • The shape of the new public APIs: a separate AddFoundryAgentSessionStore with its own lifetime, replace semantics where the last call wins, and a store factory that does not receive the agent name.
  • The breaking store selection change for apps that mix registration styles.
  • Default routing for factory agents through FoundryDefaultAgentName instead of a forwarding DI registration, and the storage identity rule in ResolveAgent.
  • Whether the scope boundary (one scope per CreateAsync enumeration) is the right owner for steering and recovery.

Related Issue

Follow-up to deferred review feedback on #10132: #10132 (comment). Related to #4457 and #4476. No open PR covers this.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: investigation of the existing DI flow, implementation, tests, documentation, a security review of the new registration and resolution paths, and this PR description.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.