Microsoft Agent Framework Converstation&Memory Created: 23 Feb 2026 Updated: 23 Feb 2026

Session

AgentSession is the conversation state container used across agent runs. It holds the state needed to continue a multi-turn conversation and can be serialised to any durable medium so that conversations survive application restarts.

What AgentSession Contains

PropertyDescription
StateBagArbitrary state container for this session. Used by the agent and providers to store per-session data.

The C# AgentSession is an abstract base class. Concrete implementations (created via CreateSessionAsync()) may add additional state - for example, an id for remote chat history storage when service-managed history is used.

Built-in Usage Pattern

Create a session with CreateSessionAsync() and pass it to every RunAsync() call. The agent automatically loads and updates conversation history across turns using the session's state bag.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

AIAgent agent = new OpenAIClient("<your_api_key>")
.GetChatClient("gpt-4o-mini")
.AsIChatClient()
.AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");

AgentSession session = await agent.CreateSessionAsync();

AgentResponse first = await agent.RunAsync("My name is Alice.", session);
AgentResponse second = await agent.RunAsync("What is my name?", session);

Console.WriteLine(first.Text); // Agent greets and acknowledges
Console.WriteLine(second.Text); // Agent recalls "Alice" from history

Because the same session object is passed on both calls, the second message includes the full conversation history, so the agent remembers the name from the first turn.

Creating a Session from an Existing Service Conversation ID

When a conversation already exists on a remote service, you can attach a session to it by passing the existing conversation ID to CreateSessionAsync(). The exact overload depends on the agent type.

Using ChatClientAgent

// Attach to an existing conversation by its ID.
AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Using an A2AAgent

// Attach to an existing A2A task/context pair.
AgentSession session = await a2aAgent.CreateSessionAsync(contextId, taskId);

After attaching, all subsequent RunAsync() calls continue the existing conversation on the service side rather than starting a new one.

Serialization and Restoration

An AgentSession can be serialised to a JsonElement so it survives application restarts. Store the JSON in a file, database, or blob storage and deserialise it later to resume the conversation exactly where it left off.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;
using System.Text.Json;

AIAgent agent = new OpenAIClient("<your_api_key>")
.GetChatClient("gpt-4o-mini")
.AsIChatClient()
.AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");

// Phase 1: start a conversation and serialise the session
AgentSession session = await agent.CreateSessionAsync();

await agent.RunAsync("Remember that the project name is 'Phoenix'.", session);

// Serialise - the result is a plain JsonElement you can write anywhere.
JsonElement serialised = await agent.SerializeSessionAsync(session);
string json = serialised.GetRawText();

// Simulate persisting to durable storage (file, DB, blob, etc.).
// In a real application: File.WriteAllText("session.json", json);

// Phase 2: restore the session after a restart
JsonElement reloaded = JsonDocument.Parse(json).RootElement;
AgentSession resumed = await agent.DeserializeSessionAsync(reloaded);

AgentResponse answer = await agent.RunAsync("What is the project name?", resumed);
Console.WriteLine(answer.Text); // Agent still knows "Phoenix"

Important: Sessions are agent/service-specific. Reusing a session with a different agent configuration or provider can lead to invalid context.

Summary

ConceptAPIDescription
Create sessionagent.CreateSessionAsync()Creates a new, empty conversation session
Attach to existing conversationagent.CreateSessionAsync(conversationId)Attaches to an existing service-side conversation by ID
Run a turnagent.RunAsync(message, session)Sends a message and updates the session with the full exchange
Serialise sessionagent.SerializeSessionAsync(session)Returns a JsonElement snapshot of the full session state
Restore sessionagent.DeserializeSessionAsync(element)Restores an AgentSession from a snapshot

Required Packages

PackagePurpose
Microsoft.Agents.AIAIAgent, AgentSession, serialization
Microsoft.Extensions.AI.OpenAIAsIChatClient() and OpenAI integration


Share this lesson:

Details

Category
Microsoft Agent Framework
Sub: Converstation&Memory
View All Courses Back to Lessons

Navigation

Progress 12 / 45
Start 27% Complete
Hosted MCP Tools with Microsoft Agent Framework Context Providers
Statistics
3 Lessons in Converstation&Memory
9 SubCategories in Microsoft Agent Framework
45 Total Lessons in Microsoft Agent Framework