AgentSession Class

Definition

Namespace:
Microsoft.Agents.AI
Assembly:
Microsoft.Agents.AI.Abstractions.dll
Package:
Microsoft.Agents.AI.Abstractions v1.13.0

Base abstraction for all agent threads.

public abstract class AgentSession
type AgentSession = class
Public MustInherit Class AgentSession
Inheritance
Object
AgentSession
Derived

Remarks

An AgentSession contains the state of a specific conversation with an agent which may include:

  • Conversation history or a reference to externally stored conversation history.
  • Memories or a reference to externally stored memories.
  • Any other state that the agent needs to persist across runs for a conversation.

An AgentSession may also have behaviors attached to it that may include:

  • Customized storage of state.
  • Data extraction from and injection into a conversation.
  • Chat history reduction, e.g. where messages needs to be summarized or truncated to reduce the size.
An AgentSession is always constructed by an AIAgent so that the AIAgent can attach any necessary behaviors to the AgentSession. See the CreateSessionAsync(CancellationToken) and DeserializeSessionAsync(JsonElement, JsonSerializerOptions, CancellationToken) methods for more information.

Because of these behaviors, an AgentSession may not be reusable across different agents, since each agent may add different behaviors to the AgentSession it creates.

To support conversations that may need to survive application restarts or separate service requests, an AgentSession can be serialized and deserialized, so that it can be saved in a persistent store. The AIAgent provides the SerializeSessionAsync(AgentSession, JsonSerializerOptions, CancellationToken) method to serialize the session to a JsonElement and the DeserializeSessionAsync(JsonElement, JsonSerializerOptions, CancellationToken) method can be used to deserialize the session.

Security considerations: Serialized sessions may contain conversation content, session identifiers, and other potentially sensitive data including PII. Developers should:

  • Treat serialized session data as sensitive and store it securely with appropriate access controls and encryption at rest.
  • Treat restoring a session from an untrusted source as equivalent to accepting untrusted input. A compromised storage backend could alter message roles to escalate trust, or inject adversarial content that influences LLM behavior.

Constructors

Name Description
AgentSession()

Initializes a new instance of the AgentSession class.
AgentSession(AgentSessionStateBag)

Initializes a new instance of the AgentSession class.

Properties

Name Description
StateBag

Gets any arbitrary state associated with this session.

Methods

Name Description
GetService(Type, Object)

Asks the AgentSession for an object of the specified type serviceType.
GetService<TService>(Object)

Asks the AgentSession for an object of type TService.

Extension Methods

Name Description
SetInMemoryChatHistory(AgentSession, List<ChatMessage>, String, JsonSerializerOptions)

Sets the in-memory chat message history for the specified agent session, replacing any existing messages.
TryGetInMemoryChatHistory(AgentSession, List<ChatMessage>, String, JsonSerializerOptions)

Attempts to retrieve the in-memory chat history messages associated with the specified agent session, if the agent is storing memories in the session using the InMemoryChatHistoryProvider

Applies to

See also