.NET: Is Singleton the intended lifetime for agents, tools and AIContextProviders, or just the default?

[Paulo Pozeti (ppozeti)]

AddAIAgent defaults to ServiceLifetime.Singleton, WithAITool(AITool) always registers a keyed singleton, and the WithAITool factory overload throws if a tool is shorter-lived than its agent. I cannot find anywhere in the docs or docs/decisions that explains whether this is the intended lifetime model or only the historical default.

Searching for related discussions/issues I found:

• The AIAgent and AIContextProvider remarks say instances are shared across many conversations and must keep per-session state in AgentSession. That suggests a stateless-definition model where Singleton is the natural choice.
• The accepted answer in Best practice for handling per-user chat history with DI in agent-based REST APIs #4930 says "the agent should be a singleton, not per-request", citing only the parameter default.
• .NET: Allow specifying the lifetime of agents when registering via AddAIAgent in Hosting #4457 / .NET: Add ServiceLifetime support for Hosting DI registration #4476 added the ServiceLifetime parameter because "we cannot assume that all agent dependencies (e.g. function tools) will always be singletons".
• .NET: [Bug]: Protocol hosting ignores AIAgent lifetimes and lacks consistent request-time selection #7733 is fixing the hosting endpoints so scoped and transient agents resolve per request.

To me is clear that agents/tools being singleton isn't part of the design at all, and it's up for us, the consumers, to handle our scopes however we like. But some people might look at everything using Singleton and think that this is a framework design pattern, not a choice.

The question is: "agents, tools and context providers are stateless and shared, state lives in the session" the design intent, or is Singleton a convenience default carried over from AddChatClient? Can we make it more explicit in the docs?

[Junaid Hussnain (Junaid-PK)]

I think the current public contract supports both readings, but at different levels:

1. The object model is session-state-oriented and concurrency-capable. AIAgent explicitly says one instance may participate in multiple concurrent conversations, while CreateSessionAsync creates a fresh, independent conversation session. AIContextProvider is even more explicit: it is used with many sessions and must put session-specific data in AgentSession.StateBag, not instance fields.

2. Singleton is a hosting default, not a required agent lifetime. Every AddAIAgent overload exposes ServiceLifetime; the custom-factory overload defaults it to Singleton but registers the selected lifetime.

3. The tool rule is DI lifetime safety, not “tools must always be Singleton.” Passing an already-created AITool instance registers that one object as a keyed Singleton. The factory overload instead inherits the agent lifetime unless one is supplied, then rejects only a shorter-lived tool to avoid a captive dependency.

That gives this compatibility table:

Agent	Valid tool lifetimes
Singleton	Singleton
Scoped	Singleton, Scoped
Transient	Singleton, Scoped, Transient

So my reading is: session-specific mutable state belongs in AgentSession, and shared instances must be concurrency-safe; Singleton is the convenient/default lifetime for that reusable graph, but scoped and transient agents/tools are intentionally supported. A scoped or transient registration does not change the session-state contract—it changes how often the service graph is constructed.

The docs would benefit from stating those two rules separately: (a) the concurrency/session-state contract for agent and context-provider implementations, and (b) the DI lifetime compatibility rule for hosted registrations. That would avoid turning a default into an apparent requirement.