[Marco Minerva (marcominerva)]

Motivation & Context

AgentSessionStore now identifies sessions through AgentSessionStoreKey, which enables partitioning and session isolation. However, applications that only need a session identifier must wrap every call in new AgentSessionStoreKey(sessionId), which adds noise and increases the migration effort from the previous string-based API.

This PR adds string sessionId convenience overloads that create an unpartitioned AgentSessionStoreKey and forward to the key-based methods. The common case stays concise, while AgentSessionStoreKey remains the canonical, extensible API for partitioned scenarios.

Description & Review Guide

• What are the major changes?
  • Added non-virtual convenience overloads to AgentSessionStore:
    • GetSessionAsync(AIAgent, string, CancellationToken)
    • SaveSessionAsync(AIAgent, string, AgentSession, CancellationToken)
    • GetOrCreateSessionAsync(AIAgent, string, CancellationToken)
    • DeleteSessionAsync(AIAgent, string, CancellationToken)
  • Each overload calls new AgentSessionStoreKey(sessionId) and forwards to the corresponding key-based method, so sessionId validation (null/empty/whitespace) is the same as for AgentSessionStoreKey.
  • The issue proposes overloads for GetSessionAsync and SaveSessionAsync; equivalent overloads were also added for GetOrCreateSessionAsync and DeleteSessionAsync to keep the API surface consistent.
  • RS0026 (multiple overloads with optional parameters) is suppressed locally around each overload pair, following the existing pattern used for GetService in the same class.
  • XML doc crefs to GetSessionAsync were made explicit to avoid ambiguity between the overloads.
  • Updated PublicAPI.Unshipped.txt for all target frameworks and added unit tests that verify forwarding (key without partitions, same agent/session/cancellation token) and sessionId validation.
• What is the impact of these changes?
  • Implementations of AgentSessionStore are unaffected: they still override only the AgentSessionStoreKey-based methods, and the new overloads apply automatically to every store.
  • Callers that pass a target-typed new(...) or a null/default literal as the key argument now get an ambiguous call error (CS0121) and must use new AgentSessionStoreKey(...) explicitly. No such call sites exist in the repository, and the affected APIs are [Experimental] and not yet shipped (they are only listed in PublicAPI.Unshipped.txt).
• What do you want reviewers to focus on?
  • Whether the source-level ambiguity for target-typed new(...) is acceptable. [OverloadResolutionPriority] was considered, but it would require a polyfill for netstandard2.0/net472/net8.0 and is only honored by callers using C# 13 or later, so it was not added.

Related Issue

Fixes #8571

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: GitHub Copilot assisted with the unit tests and the comments in the code

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.

[Copilot]

🔵 Needs a closer look

Maintainer judgment is needed on the source-compatibility tradeoff: the new public overloads make existing target-typed new(...), null, and default key arguments ambiguous despite the API being experimental.

No open issues 🎉

What changed in this PR

Adds sessionId convenience overloads to the .NET AgentSessionStore, addressing #8571 while preserving key-based methods as the implementation path for partitioned sessions.

Changes:

• Adds non-virtual overloads for get, save, get-or-create, and delete operations that forward using unpartitioned keys.
• Adds tests for argument forwarding and invalid session identifiers.
• Updates all five target-framework API baselines and clarifies XML documentation references.

File	Description
dotnet/​tests/​Microsoft.Agents.AI.Abstractions.UnitTests/​AgentSessionStoreTests.cs	Tests forwarding and session identifier validation.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​PublicAPI/​netstandard2.0/​PublicAPI.Unshipped.txt	Records the four overloads for .NET Standard 2.0.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​PublicAPI/​net9.0/​PublicAPI.Unshipped.txt	Records the four overloads for .NET 9.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​PublicAPI/​net8.0/​PublicAPI.Unshipped.txt	Records the four overloads for .NET 8.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​PublicAPI/​net472/​PublicAPI.Unshipped.txt	Records the four overloads for .NET Framework 4.7.2.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​PublicAPI/​net10.0/​PublicAPI.Unshipped.txt	Records the four overloads for .NET 10.
dotnet/​src/​Microsoft.Agents.AI.Abstractions/​AgentSessionStore.cs	Implements and documents forwarding overloads with local analyzer suppressions.

_{Review effort: Balanced}

[Roger Barreto (rogerbarreto)]

I would keep AgentSessionStoreKey as the only input type. new(sessionId) already keeps simple calls concise while making named partitions discoverable, instead of encouraging callers to encode user/tenant dimensions into session ID strings.

Main concern: existing GetSessionAsync(agent, new(sessionId)) calls become ambiguous (CS0121). Callers using keys must then spell out new AgentSessionStoreKey(...). Convenience for string callers makes existing key-based calls more verbose.

Migration benefit also needs care. Previous conventional Hosting lookup created missing sessions; new string overload returns null. Restoring argument shape does not preserve behavior. Callers still need to choose between lookup and lookup-or-create.

RS0026 suppressions are required because both overloads declare optional cancellation parameters. They suppress API-design warnings, not compiler ambiguity.

Given limited benefit and these costs, I would prefer keeping one explicit key-based contract rather than adding these overloads.

[Marco Minerva (marcominerva)]

OK, this makes sense.