chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent that stores chat messages in a vector store using the ChatHistoryMemoryProvider.
+// It can then use the chat history from prior conversations to inform responses in new conversations.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.InMemory;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var embeddingDeploymentName = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL") ?? "text-embedding-3-large";
+
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create a vector store to store the chat messages in.
+// For demonstration purposes, we are using an in-memory vector store.
+// Replace this with a vector store implementation of your choice that can persist the chat history long term.
+VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
+{
+    // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+    // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+    // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+    EmbeddingGenerator = aiProjectClient
+        .GetProjectOpenAIClient()
+        .GetEmbeddingClient(embeddingDeploymentName)
+        .AsIEmbeddingGenerator()
+});
+
+// Create the agent and add the ChatHistoryMemoryProvider to store chat messages in the vector store.
+AIAgent agent = aiProjectClient
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are good at telling jokes." },
+        Name = "Joker",
+        AIContextProviders = [new ChatHistoryMemoryProvider(
+            vectorStore,
+            collectionName: "chathistory",
+            vectorDimensions: 3072,
+            // Callback to configure the initial state of the ChatHistoryMemoryProvider.
+            // The ChatHistoryMemoryProvider stores its state in the AgentSession and this callback
+            // will be called whenever the ChatHistoryMemoryProvider cannot find existing state in the session,
+            // typically the first time it is used with a new session.
+            session => new ChatHistoryMemoryProvider.State(
+                // Configure the scope values under which chat messages will be stored.
+                // In this case, we are using a fixed user ID and a unique session ID for each new session.
+                storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
+                // Configure the scope which would be used to search for relevant prior messages.
+                // In this case, we are searching for any messages for the user across all sessions.
+                searchScope: new() { UserId = "UID1" }))]
+    });
+
+// Start a new session for the agent conversation.
+AgentSession session = await agent.CreateSessionAsync();
+
+// Run the agent with the session that stores conversation history in the vector store.
+Console.WriteLine(await agent.RunAsync("I like jokes about Pirates. Tell me a joke about a pirate.", session));
+
+// Start a second session. Since we configured the search scope to be across all sessions for the user,
+// the agent should remember that the user likes pirate jokes.
+AgentSession? session2 = await agent.CreateSessionAsync();
+
+// Run the agent with the second session.
+Console.WriteLine(await agent.RunAsync("Tell me a joke that I might like.", session2));
@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Mem0\Microsoft.Agents.AI.Mem0.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use the Mem0Provider to persist and recall memories for an agent.
+// The sample stores conversation messages in a Mem0 service and retrieves relevant memories
+// for subsequent invocations, even across new sessions.
+
+using System.Net.Http.Headers;
+using System.Text.Json;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Mem0;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+var mem0ServiceUri = Environment.GetEnvironmentVariable("MEM0_ENDPOINT") ?? throw new InvalidOperationException("MEM0_ENDPOINT is not set.");
+var mem0ApiKey = Environment.GetEnvironmentVariable("MEM0_API_KEY") ?? throw new InvalidOperationException("MEM0_API_KEY is not set.");
+
+// Create an HttpClient for Mem0 with the required base address and authentication.
+using HttpClient mem0HttpClient = new();
+mem0HttpClient.BaseAddress = new Uri(mem0ServiceUri);
+mem0HttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", mem0ApiKey);
+
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = aiProjectClient
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
+        // The stateInitializer can be used to customize the Mem0 scope per session and it will be called each time a session
+        // is encountered by the Mem0Provider that does not already have Mem0Provider state stored on the session.
+        // If each session should have its own Mem0 scope, you can create a new id per session via the stateInitializer, e.g.:
+        // new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() }))
+        // In our case we are storing memories scoped by application and user instead so that memories are retained across threads.
+        AIContextProviders = [new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" }))]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+// Clear any existing memories for this scope to demonstrate fresh behavior.
+// Note that the ClearStoredMemoriesAsync method will clear memories
+// using the scope stored in the session, or provided via the stateInitializer.
+Mem0Provider mem0Provider = agent.GetService<Mem0Provider>()!;
+await mem0Provider.ClearStoredMemoriesAsync(session);
+
+Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
+Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
+
+Console.WriteLine("\nWaiting briefly for Mem0 to index the new memories...\n");
+await Task.Delay(TimeSpan.FromSeconds(2));
+
+Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
+
+Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
+AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
+Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
+
+Console.WriteLine("\n>> Start a new session that shares the same Mem0 scope\n");
+AgentSession newSession = await agent.CreateSessionAsync();
+Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));
@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Valkey\Microsoft.Agents.AI.Valkey.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using Valkey for persistent chat history with the Agent Framework.
+// ValkeyChatHistoryProvider persists conversation history across sessions using Valkey lists.
+//
+// Prerequisites:
+//   - A running Valkey server (any version):
+//       docker run -d --name valkey -p 6379:6379 valkey/valkey:latest
+//   - Azure OpenAI endpoint and deployment configured via environment variables
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Valkey;
+using Microsoft.Extensions.AI;
+using Valkey.Glide;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var valkeyConnection = Environment.GetEnvironmentVariable("VALKEY_CONNECTION") ?? "localhost:6379";
+
+var connection = await ConnectionMultiplexer.ConnectAsync(valkeyConnection);
+
+Console.WriteLine("=== ValkeyChatHistoryProvider — Persistent Chat History ===\n");
+
+var historyProvider = new ValkeyChatHistoryProvider(
+    connection,
+    _ => new ValkeyChatHistoryProvider.State($"sample-{Guid.NewGuid():N}"),
+    new ValkeyChatHistoryProviderOptions
+    {
+        KeyPrefix = "sample_chat",
+        MaxMessages = 20
+    });
+
+AIAgent historyAgent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(new ChatClientAgentOptions()
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful assistant that remembers our conversation." },
+        ChatHistoryProvider = historyProvider
+    });
+
+AgentSession session1 = await historyAgent.CreateSessionAsync();
+Console.WriteLine(await historyAgent.RunAsync("Hello! My name is Alex and I'm a software engineer.", session1));
+Console.WriteLine(await historyAgent.RunAsync("I'm working on a project using Valkey for caching.", session1));
+Console.WriteLine(await historyAgent.RunAsync("What do you remember about me?", session1));
+
+var messageCount = await historyProvider.GetMessageCountAsync(session1);
+Console.WriteLine($"\n  Stored {messageCount} messages in Valkey.\n");
+
+// Clean up
+connection.Dispose();
+
+Console.WriteLine("Done!");
@@ -0,0 +1,30 @@
+# Agent with Memory Using Valkey
+
+This sample demonstrates using Valkey for persistent chat history with the Agent Framework.
+
+## Components
+
+- **ValkeyChatHistoryProvider** — Persists conversation history across sessions using Valkey lists. Works with any Valkey or Redis OSS server (no search module required).
+
+## Prerequisites
+
+- Azure OpenAI endpoint and deployment
+- A running Valkey server (any version):
+
+```bash
+docker run -d --name valkey -p 6379:6379 valkey/valkey:latest
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL | (required) |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Model deployment name | `gpt-5.4-mini` |
+| `VALKEY_CONNECTION` | Valkey connection string | `localhost:6379` |
+
+## Running
+
+```bash
+dotnet run
+```
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AWSSDK.Extensions.Bedrock.MEAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Valkey\Microsoft.Agents.AI.Valkey.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using Valkey for persistent chat history with the Agent Framework,
+// powered by Amazon Bedrock.
+//
+// Prerequisites:
+//   - A running Valkey server (any version):
+//       docker run -d --name valkey -p 6379:6379 valkey/valkey:latest
+//   - AWS credentials configured (environment variables, AWS profile, or IAM role)
+//   - Access to an Amazon Bedrock model (e.g., Anthropic Claude)
+
+using Amazon;
+using Amazon.BedrockRuntime;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Valkey;
+using Microsoft.Extensions.AI;
+using Valkey.Glide;
+
+var awsRegion = Environment.GetEnvironmentVariable("AWS_REGION") ?? "us-east-1";
+var modelId = Environment.GetEnvironmentVariable("BEDROCK_MODEL_ID") ?? "anthropic.claude-3-5-sonnet-20241022-v2:0";
+var valkeyConnection = Environment.GetEnvironmentVariable("VALKEY_CONNECTION") ?? "localhost:6379";
+
+// Create the Bedrock runtime client.
+var bedrockRuntime = new AmazonBedrockRuntimeClient(RegionEndpoint.GetBySystemName(awsRegion));
+IChatClient chatClient = bedrockRuntime.AsIChatClient(modelId);
+
+var connection = await ConnectionMultiplexer.ConnectAsync(valkeyConnection);
+
+Console.WriteLine("=== ValkeyChatHistoryProvider — Persistent Chat History (Bedrock) ===\n");
+
+var historyProvider = new ValkeyChatHistoryProvider(
+    connection,
+    _ => new ValkeyChatHistoryProvider.State($"bedrock-sample-{Guid.NewGuid():N}"),
+    new ValkeyChatHistoryProviderOptions
+    {
+        KeyPrefix = "bedrock_chat",
+        MaxMessages = 20
+    });
+
+AIAgent historyAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
+{
+    ChatOptions = new() { Instructions = "You are a helpful assistant that remembers our conversation." },
+    ChatHistoryProvider = historyProvider
+});
+
+AgentSession session1 = await historyAgent.CreateSessionAsync();
+Console.WriteLine(await historyAgent.RunAsync("Hello! My name is Alex and I'm a software engineer.", session1));
+Console.WriteLine(await historyAgent.RunAsync("I'm working on a project using Valkey for caching.", session1));
+Console.WriteLine(await historyAgent.RunAsync("What do you remember about me?", session1));
+
+var messageCount = await historyProvider.GetMessageCountAsync(session1);
+Console.WriteLine($"\n  Stored {messageCount} messages in Valkey.\n");
+
+// Clean up
+connection.Dispose();
+
+Console.WriteLine("Done!");
@@ -0,0 +1,41 @@
+# Agent with Memory Using Valkey + Amazon Bedrock
+
+This sample demonstrates using Valkey for persistent chat history with the Agent Framework, powered by Amazon Bedrock via the `AWSSDK.Extensions.Bedrock.MEAI` adapter.
+
+## Components
+
+- **ValkeyChatHistoryProvider** — Persists conversation history across sessions using Valkey lists. Works with any Valkey or Redis OSS server (no search module required).
+- **Amazon Bedrock** — Provides the LLM via `AWSSDK.Extensions.Bedrock.MEAI`, which implements `IChatClient` from `Microsoft.Extensions.AI`.
+
+## Prerequisites
+
+- AWS credentials configured (environment variables, AWS CLI profile, or IAM role)
+- Access to an Amazon Bedrock model (e.g., Anthropic Claude 3.5 Sonnet)
+- A running Valkey server (any version):
+
+```bash
+docker run -d --name valkey -p 6379:6379 valkey/valkey:latest
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
+| `BEDROCK_MODEL_ID` | Bedrock model identifier | `anthropic.claude-3-5-sonnet-20241022-v2:0` |
+| `VALKEY_CONNECTION` | Valkey connection string | `localhost:6379` |
+| `AWS_ACCESS_KEY_ID` | AWS access key (if not using profile/role) | — |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key (if not using profile/role) | — |
+
+## Running
+
+```bash
+# Using default AWS credential chain (profile, env vars, or IAM role)
+dotnet run
+
+# Or with explicit credentials
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_REGION="us-east-1"
+dotnet run
+```
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use the FoundryMemoryProvider to persist and recall memories for an agent.
+// The sample stores conversation messages in a Microsoft Foundry memory store and retrieves relevant
+// memories for subsequent invocations, even across new sessions.
+//
+// Note: Memory extraction in Microsoft Foundry is asynchronous and takes time. This sample demonstrates
+// a simple polling approach to wait for memory updates to complete before querying.
+
+using System.Text.Json;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+
+string foundryEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string memoryStoreName = Environment.GetEnvironmentVariable("AZURE_AI_MEMORY_STORE_ID") ?? "memory-store-sample";
+string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+string embeddingModelName = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
+
+// Create an AIProjectClient for Foundry with Azure Identity authentication.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+DefaultAzureCredential credential = new();
+AIProjectClient projectClient = new(new Uri(foundryEndpoint), credential);
+
+// Get the ChatClient from the AIProjectClient's OpenAI property using the deployment name.
+// The stateInitializer can be used to customize the Foundry Memory scope per session and it will be called each time a session
+// is encountered by the FoundryMemoryProvider that does not already have state stored on the session.
+// If each session should have its own scope, you can create a new id per session via the stateInitializer, e.g.:
+// new FoundryMemoryProvider(projectClient, memoryStoreName, stateInitializer: _ => new(new FoundryMemoryProviderScope(Guid.NewGuid().ToString())), ...)
+// In our case we are storing memories scoped by user so that memories are retained across sessions.
+FoundryMemoryProvider memoryProvider = new(
+    projectClient,
+    memoryStoreName,
+    stateInitializer: _ => new(new FoundryMemoryProviderScope("sample-user-123")));
+
+ChatClientAgent agent = projectClient.AsAIAgent(
+    new ChatClientAgentOptions()
+    {
+        Name = "TravelAssistantWithFoundryMemory",
+        ChatOptions = new()
+        {
+            ModelId = deploymentName,
+            Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details."
+        },
+        AIContextProviders = [memoryProvider]
+    });
+
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine("\n>> Setting up Foundry Memory Store\n");
+
+// Ensure the memory store exists (creates it with the specified models if needed).
+await memoryProvider.EnsureMemoryStoreCreatedAsync(deploymentName, embeddingModelName, "Sample memory store for travel assistant");
+
+// Clear any existing memories for this scope to demonstrate fresh behavior.
+await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
+
+Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
+Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
+
+// Memory extraction in Microsoft Foundry is asynchronous and takes time to process.
+// WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
+Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
+await memoryProvider.WhenUpdatesCompletedAsync();
+
+Console.WriteLine("Updates completed.\n");
+
+Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
+
+Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
+AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
+Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
+
+Console.WriteLine("\n>> Start a new session that shares the same Foundry Memory scope\n");
+
+Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
+await memoryProvider.WhenUpdatesCompletedAsync();
+
+AgentSession newSession = await agent.CreateSessionAsync();
+Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));
@@ -0,0 +1,57 @@
+# Agent with Memory Using Microsoft Foundry
+
+This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories across sessions.
+
+## Features Demonstrated
+
+- Creating a `FoundryMemoryProvider` with Azure Identity authentication
+- Automatic memory store creation if it doesn't exist
+- Multi-turn conversations with automatic memory extraction
+- Memory retrieval to inform agent responses
+- Session serialization and deserialization
+- Memory persistence across completely new sessions
+
+## Prerequisites
+
+1. Azure subscription with Microsoft Foundry project
+2. Azure OpenAI resource with a chat model deployment (e.g., gpt-5.4-mini) and an embedding model deployment (e.g., text-embedding-ada-002)
+3. .NET 10.0 SDK
+4. Azure CLI logged in (`az login`)
+
+## Environment Variables
+
+```bash
+# Microsoft Foundry project endpoint and memory store name
+export FOUNDRY_PROJECT_ENDPOINT="https://your-account.services.ai.azure.com/api/projects/your-project"
+export AZURE_AI_MEMORY_STORE_ID="my_memory_store"
+
+# Model deployment names (models deployed in your Foundry project)
+export FOUNDRY_MODEL="gpt-5.4-mini"
+export AZURE_AI_EMBEDDING_DEPLOYMENT_NAME="text-embedding-ada-002"
+```
+
+## Run the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The agent will:
+1. Create the memory store if it doesn't exist (using the specified chat and embedding models)
+2. Learn your name (Taylor), travel destination (Patagonia), timing (November), companions (sister), and interests (scenic viewpoints)
+3. Wait for Foundry Memory to index the memories
+4. Recall those details when asked about the trip
+5. Demonstrate memory persistence across session serialization/deserialization
+6. Show that a brand new session can still access the same memories
+
+## Key Differences from Mem0
+
+| Aspect | Mem0 | Microsoft Foundry Memory |
+|--------|------|------------------------|
+| Authentication | API Key | Azure Identity (DefaultAzureCredential) |
+| Scope | ApplicationId, UserId, AgentId, ThreadId | Single `Scope` string |
+| Memory Types | Single memory store | User Profile + Chat Summary |
+| Hosting | Mem0 cloud or self-hosted | Microsoft Foundry managed service |
+| Store Creation | N/A (automatic) | Explicit via `EnsureMemoryStoreCreatedAsync` |
@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,133 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+
+namespace SampleApp;
+
+/// <summary>
+/// A <see cref="ChatHistoryProvider"/> that keeps a bounded window of recent messages in session state
+/// (via <see cref="InMemoryChatHistoryProvider"/>) and overflows older messages to a vector store
+/// (via <see cref="ChatHistoryMemoryProvider"/>). When providing chat history, it searches the vector
+/// store for relevant older messages and prepends them as a memory context message.
+/// </summary>
+/// <remarks>
+/// Only non-system messages are counted towards the session state limit and overflow mechanism. System messages are always retained in session state and are not included in the vector store.
+/// Function calls and function results are also dropped when truncation happens, both from in-memory state, and they are also not persisted to the vector store.
+/// </remarks>
+internal sealed class BoundedChatHistoryProvider : ChatHistoryProvider, IDisposable
+{
+    private readonly InMemoryChatHistoryProvider _chatHistoryProvider;
+    private readonly ChatHistoryMemoryProvider _memoryProvider;
+    private readonly TruncatingChatReducer _reducer;
+    private readonly string _contextPrompt;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BoundedChatHistoryProvider"/> class.
+    /// </summary>
+    /// <param name="maxSessionMessages">The maximum number of non-system messages to keep in session state before overflowing to the vector store.</param>
+    /// <param name="vectorStore">The vector store to use for storing and retrieving overflow chat history.</param>
+    /// <param name="collectionName">The name of the collection for storing overflow chat history in the vector store.</param>
+    /// <param name="vectorDimensions">The number of dimensions to use for the chat history vector store embeddings.</param>
+    /// <param name="stateInitializer">A delegate that initializes the memory provider state, providing the storage and search scopes.</param>
+    /// <param name="contextPrompt">Optional prompt to prefix memory search results. Defaults to a standard memory context prompt.</param>
+    public BoundedChatHistoryProvider(
+        int maxSessionMessages,
+        VectorStore vectorStore,
+        string collectionName,
+        int vectorDimensions,
+        Func<AgentSession?, ChatHistoryMemoryProvider.State> stateInitializer,
+        string? contextPrompt = null)
+    {
+        if (maxSessionMessages < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(maxSessionMessages), "maxSessionMessages must be non-negative.");
+        }
+
+        this._reducer = new TruncatingChatReducer(maxSessionMessages);
+        this._chatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            ChatReducer = this._reducer,
+            ReducerTriggerEvent = InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.AfterMessageAdded,
+            StorageInputRequestMessageFilter = msgs => msgs,
+        });
+        this._memoryProvider = new ChatHistoryMemoryProvider(
+            vectorStore,
+            collectionName,
+            vectorDimensions,
+            stateInitializer,
+            options: new ChatHistoryMemoryProviderOptions
+            {
+                SearchInputMessageFilter = msgs => msgs,
+                StorageInputRequestMessageFilter = msgs => msgs,
+            });
+        this._contextPrompt = contextPrompt
+            ?? "The following are memories from earlier in this conversation. Use them to inform your responses:";
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= this._chatHistoryProvider.StateKeys.Concat(this._memoryProvider.StateKeys).ToArray();
+
+    /// <inheritdoc />
+    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
+        InvokingContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Delegate to the inner provider's full lifecycle (retrieve, filter, stamp, merge with request messages).
+        var chatHistoryProviderInputContext = new InvokingContext(context.Agent, context.Session, []);
+        var allMessages = await this._chatHistoryProvider.InvokingAsync(chatHistoryProviderInputContext, cancellationToken).ConfigureAwait(false);
+
+        // Search the vector store for relevant older messages.
+        var aiContext = new AIContext { Messages = context.RequestMessages.ToList() };
+        var invokingContext = new AIContextProvider.InvokingContext(
+            context.Agent, context.Session, aiContext);
+
+        var result = await this._memoryProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
+
+        // Extract only the messages added by the memory provider (stamped with AIContextProvider source type).
+        var memoryMessages = result.Messages?
+            .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.AIContextProvider)
+            .ToList();
+
+        if (memoryMessages is { Count: > 0 })
+        {
+            var memoryText = string.Join("\n", memoryMessages.Select(m => m.Text).Where(t => !string.IsNullOrWhiteSpace(t)));
+
+            if (!string.IsNullOrWhiteSpace(memoryText))
+            {
+                var contextMessage = new ChatMessage(ChatRole.User, $"{this._contextPrompt}\n{memoryText}");
+                return new[] { contextMessage }.Concat(allMessages);
+            }
+        }
+
+        return allMessages;
+    }
+
+    /// <inheritdoc />
+    protected override async ValueTask StoreChatHistoryAsync(
+        InvokedContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Delegate storage to the in-memory provider. Its TruncatingChatReducer (AfterMessageAdded trigger)
+        // will automatically truncate to the configured maximum and expose any removed messages.
+        var innerContext = new InvokedContext(
+            context.Agent, context.Session, context.RequestMessages, context.ResponseMessages!);
+        await this._chatHistoryProvider.InvokedAsync(innerContext, cancellationToken).ConfigureAwait(false);
+
+        // Archive any messages that the reducer removed to the vector store.
+        if (this._reducer.RemovedMessages is { Count: > 0 })
+        {
+            var overflowContext = new AIContextProvider.InvokedContext(
+                context.Agent, context.Session, this._reducer.RemovedMessages, []);
+            await this._memoryProvider.InvokedAsync(overflowContext, cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        this._memoryProvider.Dispose();
+    }
+}
@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create a bounded chat history provider that keeps a configurable number of
+// recent messages in session state and automatically overflows older messages to a vector store.
+// When the agent is invoked, it searches the vector store for relevant older messages and
+// prepends them as a "memory" context message before the recent session history.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.InMemory;
+using SampleApp;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+var embeddingDeploymentName = Environment.GetEnvironmentVariable("FOUNDRY_EMBEDDING_MODEL") ?? "text-embedding-3-large";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create a vector store to store overflow chat messages.
+// For demonstration purposes, we are using an in-memory vector store.
+// Replace this with a persistent vector store implementation for production scenarios.
+VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
+{
+    EmbeddingGenerator = aiProjectClient
+        .GetProjectOpenAIClient()
+        .GetEmbeddingClient(embeddingDeploymentName)
+        .AsIEmbeddingGenerator()
+});
+
+var sessionId = Guid.NewGuid().ToString();
+
+// Create the BoundedChatHistoryProvider with a maximum of 4 non-system messages in session state.
+// It internally creates an InMemoryChatHistoryProvider with a TruncatingChatReducer and a
+// ChatHistoryMemoryProvider with the correct configuration to ensure overflow messages are
+// automatically archived to the vector store and recalled via semantic search.
+var boundedProvider = new BoundedChatHistoryProvider(
+    maxSessionMessages: 4,
+    vectorStore,
+    collectionName: "chathistory-overflow",
+    vectorDimensions: 3072,
+    session => new ChatHistoryMemoryProvider.State(
+        storageScope: new() { UserId = "UID1", SessionId = sessionId },
+        searchScope: new() { UserId = "UID1" }));
+
+// Create the agent with the bounded chat history provider.
+AIAgent agent = aiProjectClient
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { ModelId = deploymentName, Instructions = "You are a helpful assistant. Answer questions concisely." },
+        Name = "Assistant",
+        ChatHistoryProvider = boundedProvider,
+    });
+
+// Start a conversation. The first several exchanges will fill up the session state window.
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine("--- Filling the session window (4 messages max) ---\n");
+
+Console.WriteLine(await agent.RunAsync("My favorite color is blue.", session));
+Console.WriteLine(await agent.RunAsync("I have a dog named Max.", session));
+
+// At this point the session state holds 4 messages (2 user + 2 assistant).
+// The next exchange will push the oldest messages into the vector store.
+Console.WriteLine("\n--- Next exchange will trigger overflow to vector store ---\n");
+
+Console.WriteLine(await agent.RunAsync("What is the capital of France?", session));
+
+// The oldest messages about favorite color have now been archived to the vector store.
+// Ask the agent something that requires recalling the overflowed information.
+Console.WriteLine("\n--- Asking about overflowed information (should recall from vector store) ---\n");
+
+Console.WriteLine(await agent.RunAsync("What is my favorite color?", session));
@@ -0,0 +1,40 @@
+# Bounded Chat History with Vector Store Overflow
+
+This sample demonstrates how to create a custom `ChatHistoryProvider` that keeps a bounded window of recent messages in session state and automatically overflows older messages to a vector store. When the agent is invoked, it searches the vector store for relevant older messages and prepends them as memory context.
+
+## Concepts
+
+- **`TruncatingChatReducer`**: A custom `IChatReducer` that keeps the most recent N messages and exposes removed messages via a `RemovedMessages` property.
+- **`BoundedChatHistoryProvider`**: A custom `ChatHistoryProvider` that composes:
+  - `InMemoryChatHistoryProvider` for fast session-state storage (bounded by the reducer)
+  - `ChatHistoryMemoryProvider` for vector-store overflow and semantic search of older messages
+
+## Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- An Azure OpenAI resource with:
+  - A chat deployment (e.g., `gpt-5.4-mini`)
+  - An embedding deployment (e.g., `text-embedding-3-large`)
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `AZURE_OPENAI_ENDPOINT` | Your Azure OpenAI endpoint URL | *(required)* |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Chat model deployment name | `gpt-5.4-mini` |
+| `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` | Embedding model deployment name | `text-embedding-3-large` |
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+## How it Works
+
+1. The agent starts a conversation with a bounded session window of 4 non-system, non-function messages (i.e., user/assistant turns). System messages are always preserved, and function call/result messages are truncated and not preserved.
+2. As messages accumulate beyond the limit, the `TruncatingChatReducer` removes the oldest messages.
+3. The `BoundedChatHistoryProvider` detects the removed messages and stores them in a vector store via `ChatHistoryMemoryProvider`.
+4. On subsequent invocations, the provider searches the vector store for relevant older messages and prepends them as memory context, allowing the agent to recall information from earlier in the conversation.
@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// A truncating chat reducer that keeps the most recent messages up to a configured maximum,
+/// preserving any leading system message. Removed messages are exposed via <see cref="RemovedMessages"/>
+/// so that a caller can archive them (e.g. to a vector store).
+/// </summary>
+internal sealed class TruncatingChatReducer : IChatReducer
+{
+    private readonly int _maxMessages;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TruncatingChatReducer"/> class.
+    /// </summary>
+    /// <param name="maxMessages">The maximum number of non-system messages to retain.</param>
+    public TruncatingChatReducer(int maxMessages)
+    {
+        this._maxMessages = maxMessages > 0 ? maxMessages : throw new ArgumentOutOfRangeException(nameof(maxMessages));
+    }
+
+    /// <summary>
+    /// Gets the messages that were removed during the most recent call to <see cref="ReduceAsync"/>.
+    /// </summary>
+    public IReadOnlyList<ChatMessage> RemovedMessages { get; private set; } = [];
+
+    /// <inheritdoc />
+    public Task<IEnumerable<ChatMessage>> ReduceAsync(IEnumerable<ChatMessage> messages, CancellationToken cancellationToken)
+    {
+        _ = messages ?? throw new ArgumentNullException(nameof(messages));
+
+        ChatMessage? systemMessage = null;
+        Queue<ChatMessage> retained = new(capacity: this._maxMessages);
+        List<ChatMessage> removed = [];
+
+        foreach (var message in messages)
+        {
+            if (message.Role == ChatRole.System)
+            {
+                // Preserve the first system message outside the counting window.
+                systemMessage ??= message;
+            }
+            else if (!message.Contents.Any(c => c is FunctionCallContent or FunctionResultContent))
+            {
+                if (retained.Count >= this._maxMessages)
+                {
+                    removed.Add(retained.Dequeue());
+                }
+
+                retained.Enqueue(message);
+            }
+        }
+
+        this.RemovedMessages = removed;
+
+        IEnumerable<ChatMessage> result = systemMessage is not null
+            ? new[] { systemMessage }.Concat(retained)
+            : retained;
+
+        return Task.FromResult(result);
+    }
+}
@@ -0,0 +1,14 @@
+# Agent Framework Retrieval Augmented Generation (RAG)
+
+These samples show how to create an agent with the Agent Framework that uses Memory to remember previous conversations or facts from previous conversations.
+
+|Sample|Description|
+|---|---|
+|[Chat History memory](./AgentWithMemory_Step01_ChatHistoryMemory/)|This sample demonstrates how to enable an agent to remember messages from previous conversations.|
+|[Memory with MemoryStore](./AgentWithMemory_Step02_MemoryUsingMem0/)|This sample demonstrates how to create and run an agent that uses the Mem0 service to extract and retrieve individual memories.|
+|[Custom Memory Implementation](../../01-get-started/04_memory/)|This sample demonstrates how to create a custom memory component and attach it to an agent.|
+|[Memory with Microsoft Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories.|
+|[Bounded Chat History with Overflow](./AgentWithMemory_Step05_BoundedChatHistory/)|This sample demonstrates how to create a bounded chat history provider that overflows older messages to a vector store and recalls them as memories.|
+
+> **See also**: [Memory Search with Foundry Agents](../AgentProviders/foundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Microsoft Foundry agents.
+