.NET: Add Foundry Memory Context Provider (#3522)

* Add Azure AI Foundry Memory Context Provider with unit tests

* Add FoundryMemory integration tests and sample application

* Fix ClearStoredMemoriesAsync to handle 404 gracefully and rename to EnsureStoredMemoriesDeletedAsync

* Refactor FoundryMemory: simplify architecture and add memory store creation

- Remove IFoundryMemoryOperations interface (was only for test mocking)
- Remove AIProjectClientMemoryOperations wrapper class
- Provider now directly uses AIProjectClient with internal extension methods
- Extension methods return actual response models instead of extracted values
- Remove WaitForUpdateCompletionAsync from provider (sample uses delay)
- Simplify EnsureMemoryStoreCreatedAsync to return Task instead of Task<bool>
- Add memory store creation with chat_model and embedding_model
- Add UpdateMemoriesResponse with SupersededBy and Error fields
- Simplify unit tests to focus on constructor validation and serialization
- Update sample to use simple delay for memory processing wait

* Add waiting operation for memory store updates

* Fix UTF-8 BOM encoding for FoundryMemory csproj files

* Update copilot instructions for UTF-8 BOM and fix sample API rename

* Fix UTF-8 BOM encoding for TestableAIProjectClient.cs

* Add missing response headers for TS

* Changing default embedding

* Using the SDK Models

* Program update

* Remove debugging code from sample

* Adapt FoundryMemoryProvider to new AIContextProvider API and add UTF-8 BOM instruction

- Override ProvideAIContextAsync/StoreAIContextAsync instead of removed virtual InvokingAsync/InvokedAsync
- Use ProviderSessionState<State> for session-scoped state management (matching Mem0Provider pattern)
- Replace constructor-based scope with stateInitializer delegate
- Remove Serialize method (no longer on base class)
- Add SearchInputMessageFilter, StorageInputMessageFilter, StateKey to options
- Update sample to use AIContextProviders list instead of AIContextProviderFactory
- Update unit and integration tests for new API
- Add UTF-8 BOM encoding and --tl:off instructions to dotnet/AGENTS.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Use DefaultAzureCredential in Foundry Memory sample

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review comments for FoundryMemoryProvider

- Move memoryStoreName from options to required constructor parameter
- Make FoundryMemoryProviderScope require non-null/whitespace scope in constructor
- Make Scope property read-only (getter only)
- Replace ConcurrentQueue with single last update ID to fix memory leak
- Only clear pending update ID after successful completion
- Add delete success logging
- Mark FoundryMemoryProvider with [Experimental] attribute
- Update unit tests for new API signatures

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Use Throw.IfNullOrWhitespace for scope and memoryStoreName validation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Roger Barreto
2026-02-20 11:25:06 +00:00
committed by GitHub
co-authored by Copilot
parent 0086d38f58
commit 0e2fcb1c7f
18 changed files with 1331 additions and 0 deletions
@@ -0,0 +1,132 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Extensions.Configuration;
using Shared.IntegrationTests;
namespace Microsoft.Agents.AI.FoundryMemory.IntegrationTests;
/// <summary>
/// Integration tests for <see cref="FoundryMemoryProvider"/> against a configured Azure AI Foundry Memory service.
/// </summary>
/// <remarks>
/// These integration tests are skipped by default and require a live Azure AI Foundry Memory service.
/// The tests need to be updated to use the new AIAgent-based API pattern.
/// Set <see cref="SkipReason"/> to null to enable them after configuring the service.
/// </remarks>
public sealed class FoundryMemoryProviderTests : IDisposable
{
private const string SkipReason = "Requires an Azure AI Foundry Memory service configured"; // Set to null to enable.
private readonly AIProjectClient? _client;
private readonly string? _memoryStoreName;
private readonly string? _deploymentName;
private bool _disposed;
public FoundryMemoryProviderTests()
{
IConfigurationRoot configuration = new ConfigurationBuilder()
.AddJsonFile(path: "testsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile(path: "testsettings.development.json", optional: true, reloadOnChange: true)
.AddEnvironmentVariables()
.AddUserSecrets<FoundryMemoryProviderTests>(optional: true)
.Build();
var foundrySettings = configuration.GetSection("FoundryMemory").Get<FoundryMemoryConfiguration>();
if (foundrySettings is not null &&
!string.IsNullOrWhiteSpace(foundrySettings.Endpoint) &&
!string.IsNullOrWhiteSpace(foundrySettings.MemoryStoreName))
{
this._client = new AIProjectClient(new Uri(foundrySettings.Endpoint), new AzureCliCredential());
this._memoryStoreName = foundrySettings.MemoryStoreName;
this._deploymentName = foundrySettings.DeploymentName ?? "gpt-4.1-mini";
}
}
[Fact(Skip = SkipReason)]
public async Task CanAddAndRetrieveUserMemoriesAsync()
{
// Arrange
FoundryMemoryProvider memoryProvider = new(
this._client!,
this._memoryStoreName!,
stateInitializer: _ => new(new FoundryMemoryProviderScope("it-user-1")));
AIAgent agent = await this._client!.CreateAIAgentAsync(this._deploymentName!,
options: new ChatClientAgentOptions { AIContextProviders = [memoryProvider] });
AgentSession session = await agent.CreateSessionAsync();
await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
// Act
AgentResponse resultBefore = await agent.RunAsync("What is my name?", session);
Assert.DoesNotContain("Caoimhe", resultBefore.Text);
await agent.RunAsync("Hello, my name is Caoimhe.", session);
await memoryProvider.WhenUpdatesCompletedAsync();
await Task.Delay(2000);
AgentResponse resultAfter = await agent.RunAsync("What is my name?", session);
// Cleanup
await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
// Assert
Assert.Contains("Caoimhe", resultAfter.Text);
}
[Fact(Skip = SkipReason)]
public async Task DoesNotLeakMemoriesAcrossScopesAsync()
{
// Arrange
FoundryMemoryProvider memoryProvider1 = new(
this._client!,
this._memoryStoreName!,
stateInitializer: _ => new(new FoundryMemoryProviderScope("it-scope-a")));
FoundryMemoryProvider memoryProvider2 = new(
this._client!,
this._memoryStoreName!,
stateInitializer: _ => new(new FoundryMemoryProviderScope("it-scope-b")));
AIAgent agent1 = await this._client!.CreateAIAgentAsync(this._deploymentName!,
options: new ChatClientAgentOptions { AIContextProviders = [memoryProvider1] });
AIAgent agent2 = await this._client!.CreateAIAgentAsync(this._deploymentName!,
options: new ChatClientAgentOptions { AIContextProviders = [memoryProvider2] });
AgentSession session1 = await agent1.CreateSessionAsync();
AgentSession session2 = await agent2.CreateSessionAsync();
await memoryProvider1.EnsureStoredMemoriesDeletedAsync(session1);
await memoryProvider2.EnsureStoredMemoriesDeletedAsync(session2);
// Act - add memory only to scope A
await agent1.RunAsync("Hello, I'm an AI tutor and my name is Caoimhe.", session1);
await memoryProvider1.WhenUpdatesCompletedAsync();
await Task.Delay(2000);
AgentResponse result1 = await agent1.RunAsync("What is your name?", session1);
AgentResponse result2 = await agent2.RunAsync("What is your name?", session2);
// Assert
Assert.Contains("Caoimhe", result1.Text);
Assert.DoesNotContain("Caoimhe", result2.Text);
// Cleanup
await memoryProvider1.EnsureStoredMemoriesDeletedAsync(session1);
await memoryProvider2.EnsureStoredMemoriesDeletedAsync(session2);
}
public void Dispose()
{
if (!this._disposed)
{
this._disposed = true;
}
}
}
@@ -0,0 +1,21 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<InjectSharedIntegrationTestCode>True</InjectSharedIntegrationTestCode>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.FoundryMemory\Microsoft.Agents.AI.FoundryMemory.csproj" />
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.Extensions.Configuration" />
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
<PackageReference Include="Microsoft.Extensions.Configuration.Json" />
<PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
</ItemGroup>
</Project>
@@ -0,0 +1,130 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
namespace Microsoft.Agents.AI.FoundryMemory.UnitTests;
/// <summary>
/// Tests for <see cref="FoundryMemoryProvider"/> constructor validation.
/// </summary>
/// <remarks>
/// Since <see cref="FoundryMemoryProvider"/> directly uses <see cref="Azure.AI.Projects.AIProjectClient"/>,
/// integration tests are used to verify the memory operations. These unit tests focus on:
/// - Constructor parameter validation
/// - State initializer validation
/// </remarks>
public sealed class FoundryMemoryProviderTests
{
[Fact]
public void Constructor_Throws_WhenClientIsNull()
{
// Act & Assert
ArgumentNullException ex = Assert.Throws<ArgumentNullException>(() => new FoundryMemoryProvider(
null!,
"store",
stateInitializer: _ => new(new FoundryMemoryProviderScope("test"))));
Assert.Equal("client", ex.ParamName);
}
[Fact]
public void Constructor_Throws_WhenStateInitializerIsNull()
{
// Arrange
using TestableAIProjectClient testClient = new();
// Act & Assert
ArgumentNullException ex = Assert.Throws<ArgumentNullException>(() => new FoundryMemoryProvider(
testClient.Client,
"store",
stateInitializer: null!));
Assert.Equal("stateInitializer", ex.ParamName);
}
[Fact]
public void Constructor_Throws_WhenMemoryStoreNameIsEmpty()
{
// Arrange
using TestableAIProjectClient testClient = new();
// Act & Assert
ArgumentException ex = Assert.Throws<ArgumentException>(() => new FoundryMemoryProvider(
testClient.Client,
"",
stateInitializer: _ => new(new FoundryMemoryProviderScope("test"))));
Assert.Equal("memoryStoreName", ex.ParamName);
}
[Fact]
public void Constructor_Throws_WhenMemoryStoreNameIsNull()
{
// Arrange
using TestableAIProjectClient testClient = new();
// Act & Assert
ArgumentNullException ex = Assert.Throws<ArgumentNullException>(() => new FoundryMemoryProvider(
testClient.Client,
null!,
stateInitializer: _ => new(new FoundryMemoryProviderScope("test"))));
Assert.Equal("memoryStoreName", ex.ParamName);
}
[Fact]
public void Scope_Throws_WhenScopeIsNull()
{
// Act & Assert
Assert.Throws<ArgumentNullException>(() => new FoundryMemoryProviderScope(null!));
}
[Fact]
public void Scope_Throws_WhenScopeIsEmpty()
{
// Act & Assert
Assert.Throws<ArgumentException>(() => new FoundryMemoryProviderScope(""));
}
[Fact]
public void StateInitializer_Throws_WhenScopeIsNull()
{
// Arrange
using TestableAIProjectClient testClient = new();
FoundryMemoryProvider sut = new(
testClient.Client,
"store",
stateInitializer: _ => new(null!));
// Act & Assert - state initializer validation is deferred to first use
Assert.Throws<ArgumentNullException>(() =>
{
// Force state initialization by creating a session-like scenario
// The validation happens inside the ValidateStateInitializer wrapper
try
{
// The stateInitializer wraps with validation, so calling it will throw
var field = typeof(FoundryMemoryProvider).GetField("_sessionState", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
var sessionState = field!.GetValue(sut);
var method = sessionState!.GetType().GetMethod("GetOrInitializeState");
method!.Invoke(sessionState, [null]);
}
catch (System.Reflection.TargetInvocationException tie) when (tie.InnerException is not null)
{
throw tie.InnerException;
}
});
}
[Fact]
public void Constructor_Succeeds_WithValidParameters()
{
// Arrange
using TestableAIProjectClient testClient = new();
// Act
FoundryMemoryProvider sut = new(
testClient.Client,
"my-store",
stateInitializer: _ => new(new FoundryMemoryProviderScope("user-456")));
// Assert
Assert.NotNull(sut);
}
}
@@ -0,0 +1,16 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
<JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.FoundryMemory\Microsoft.Agents.AI.FoundryMemory.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Azure.AI.Projects" />
<PackageReference Include="Microsoft.Extensions.Logging" />
</ItemGroup>
</Project>
@@ -0,0 +1,196 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
using System.ClientModel.Primitives;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Text.Json.Serialization;
using System.Threading;
using System.Threading.Tasks;
using Azure.AI.Projects;
using Azure.Core;
namespace Microsoft.Agents.AI.FoundryMemory.UnitTests;
/// <summary>
/// Creates a testable AIProjectClient with a mock HTTP handler.
/// </summary>
internal sealed class TestableAIProjectClient : IDisposable
{
private readonly HttpClient _httpClient;
public TestableAIProjectClient(
string? searchMemoriesResponse = null,
string? updateMemoriesResponse = null,
HttpStatusCode? searchStatusCode = null,
HttpStatusCode? updateStatusCode = null,
HttpStatusCode? deleteStatusCode = null,
HttpStatusCode? createStoreStatusCode = null,
HttpStatusCode? getStoreStatusCode = null)
{
this.Handler = new MockHttpMessageHandler(
searchMemoriesResponse,
updateMemoriesResponse,
searchStatusCode,
updateStatusCode,
deleteStatusCode,
createStoreStatusCode,
getStoreStatusCode);
this._httpClient = new HttpClient(this.Handler);
AIProjectClientOptions options = new()
{
Transport = new HttpClientPipelineTransport(this._httpClient)
};
// Using a valid format endpoint
this.Client = new AIProjectClient(
new Uri("https://test.services.ai.azure.com/api/projects/test-project"),
new MockTokenCredential(),
options);
}
public AIProjectClient Client { get; }
public MockHttpMessageHandler Handler { get; }
public void Dispose()
{
this._httpClient.Dispose();
this.Handler.Dispose();
}
}
/// <summary>
/// Mock HTTP message handler for testing.
/// </summary>
internal sealed class MockHttpMessageHandler : HttpMessageHandler
{
private readonly string? _searchMemoriesResponse;
private readonly string? _updateMemoriesResponse;
private readonly HttpStatusCode _searchStatusCode;
private readonly HttpStatusCode _updateStatusCode;
private readonly HttpStatusCode _deleteStatusCode;
private readonly HttpStatusCode _createStoreStatusCode;
private readonly HttpStatusCode _getStoreStatusCode;
public MockHttpMessageHandler(
string? searchMemoriesResponse = null,
string? updateMemoriesResponse = null,
HttpStatusCode? searchStatusCode = null,
HttpStatusCode? updateStatusCode = null,
HttpStatusCode? deleteStatusCode = null,
HttpStatusCode? createStoreStatusCode = null,
HttpStatusCode? getStoreStatusCode = null)
{
this._searchMemoriesResponse = searchMemoriesResponse ?? """{"memories":[]}""";
this._updateMemoriesResponse = updateMemoriesResponse ?? """{"update_id":"test-update-id","status":"queued"}""";
this._searchStatusCode = searchStatusCode ?? HttpStatusCode.OK;
this._updateStatusCode = updateStatusCode ?? HttpStatusCode.OK;
this._deleteStatusCode = deleteStatusCode ?? HttpStatusCode.NoContent;
this._createStoreStatusCode = createStoreStatusCode ?? HttpStatusCode.Created;
this._getStoreStatusCode = getStoreStatusCode ?? HttpStatusCode.NotFound;
}
public string? LastRequestUri { get; private set; }
public string? LastRequestBody { get; private set; }
public HttpMethod? LastRequestMethod { get; private set; }
protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
this.LastRequestUri = request.RequestUri?.ToString();
this.LastRequestMethod = request.Method;
if (request.Content != null)
{
#if NET472
this.LastRequestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
#else
this.LastRequestBody = await request.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
#endif
}
string path = request.RequestUri?.AbsolutePath ?? "";
// Route based on path and method
if (path.Contains("/memory-stores/") && path.Contains("/search") && request.Method == HttpMethod.Post)
{
return CreateResponse(this._searchStatusCode, this._searchMemoriesResponse);
}
if (path.Contains("/memory-stores/") && path.Contains("/memories") && request.Method == HttpMethod.Post)
{
return CreateResponse(this._updateStatusCode, this._updateMemoriesResponse);
}
if (path.Contains("/memory-stores/") && path.Contains("/scopes") && request.Method == HttpMethod.Delete)
{
return CreateResponse(this._deleteStatusCode, "");
}
if (path.Contains("/memory-stores") && request.Method == HttpMethod.Post)
{
return CreateResponse(this._createStoreStatusCode, """{"name":"test-store","status":"active"}""");
}
if (path.Contains("/memory-stores/") && request.Method == HttpMethod.Get)
{
return CreateResponse(this._getStoreStatusCode, """{"name":"test-store","status":"active"}""");
}
// Default response
return CreateResponse(HttpStatusCode.NotFound, "{}");
}
private static HttpResponseMessage CreateResponse(HttpStatusCode statusCode, string? content)
{
return new HttpResponseMessage(statusCode)
{
Content = new StringContent(content ?? "{}", Encoding.UTF8, "application/json")
};
}
}
/// <summary>
/// Mock token credential for testing.
/// </summary>
internal sealed class MockTokenCredential : TokenCredential
{
public override AccessToken GetToken(TokenRequestContext requestContext, CancellationToken cancellationToken)
{
return new AccessToken("mock-token", DateTimeOffset.UtcNow.AddHours(1));
}
public override ValueTask<AccessToken> GetTokenAsync(TokenRequestContext requestContext, CancellationToken cancellationToken)
{
return new ValueTask<AccessToken>(new AccessToken("mock-token", DateTimeOffset.UtcNow.AddHours(1)));
}
}
/// <summary>
/// Source-generated JSON serializer context for unit test types.
/// </summary>
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(TestState))]
[JsonSerializable(typeof(TestScope))]
internal sealed partial class TestJsonContext : JsonSerializerContext
{
}
/// <summary>
/// Test state class for deserialization tests.
/// </summary>
internal sealed class TestState
{
public TestScope? Scope { get; set; }
}
/// <summary>
/// Test scope class for deserialization tests.
/// </summary>
internal sealed class TestScope
{
public string? Scope { get; set; }
}