.NET: Support a message only AIContextProvider as an AIAgent Decorator

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/Program.cs

@@ -2,8 +2,9 @@
 
 // This sample shows multiple middleware layers working together with Azure OpenAI:
 // chat client (global/per-request), agent run (PII filtering and guardrails),
-// function invocation (logging and result overrides), and human-in-the-loop
-// approval workflows for sensitive function calls.
+// function invocation (logging and result overrides), human-in-the-loop
+// approval workflows for sensitive function calls, and MessageAIContextProvider
+// middleware for injecting additional context messages into the agent pipeline.
 
 using System.ComponentModel;
 using System.Text.RegularExpressions;
@@ -96,6 +97,20 @@ static string GetDateTime()
 
 Console.WriteLine($"Per-request middleware response: {response}");
 
+// MessageAIContextProvider middleware that injects additional messages into the agent request.
+// This allows any AIAgent (not just ChatClientAgent) to benefit from MessageAIContextProvider-based
+// context enrichment. Multiple providers can be passed to Use and they are called in sequence,
+// each receiving the output of the previous one.
+Console.WriteLine("\n\n=== Example 5: MessageAIContextProvider middleware ===");
+
+var contextProviderAgent = originalAgent
+    .AsBuilder()
+    .Use([new DateTimeContextProvider()])
+    .Build();
+
+var contextResponse = await contextProviderAgent.RunAsync("Is it almost time for lunch?");
+Console.WriteLine($"Context-enriched response: {contextResponse}");
+
 // Function invocation middleware that logs before and after function calls.
 async ValueTask<object?> FunctionCallMiddleware(AIAgent agent, FunctionInvocationContext context, Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next, CancellationToken cancellationToken)
 {
@@ -259,3 +274,23 @@ async Task<ChatResponse> PerRequestChatClientMiddleware(IEnumerable<ChatMessage>
 
     return response;
 }
+
+/// <summary>
+/// A <see cref="MessageAIContextProvider"/> that injects the current date and time into the agent's context.
+/// This is a simple example of how to use a MessageAIContextProvider to enrich agent messages
+/// via the <see cref="AIAgentBuilder.Use(MessageAIContextProvider[])"/> extension method.
+/// </summary>
+internal sealed class DateTimeContextProvider : MessageAIContextProvider
+{
+    protected override ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(
+        InvokingContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine("DateTimeContextProvider - Injecting current date/time context");
+
+        return new ValueTask<IEnumerable<ChatMessage>>(
+            [
+                new ChatMessage(ChatRole.User, $"For reference, the current date and time is: {DateTimeOffset.Now}")
+            ]);
+    }
+}

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/README.md

@@ -14,6 +14,7 @@ This sample demonstrates how to add middleware to intercept:
 5. Per‑request chat client middleware
 6. Per‑request function pipeline with approval
 7. Combining agent‑level and per‑request middleware
+8. MessageAIContextProvider middleware via `AIAgentBuilder.Use(...)` for injecting additional context messages
 
 ## Function Invocation Middleware
 

dotnet/samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Program.cs

@@ -150,13 +150,12 @@ private static void AddTodoItem(AgentSession? session, string item)
     }
 
     /// <summary>
-    /// An <see cref="AIContextProvider"/> which searches for upcoming calendar events and adds them to the AI context.
+    /// A <see cref="MessageAIContextProvider"/> which searches for upcoming calendar events and adds them to the AI context.
     /// </summary>
-    internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : AIContextProvider
+    internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : MessageAIContextProvider
     {
-        protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask<IEnumerable<MEAI.ChatMessage>> ProvideMessagesAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
-            var inputContext = context.AIContext;
             var events = await loadNextThreeCalendarEvents();
 
             StringBuilder outputMessageBuilder = new();
@@ -166,18 +165,7 @@ protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext
                 outputMessageBuilder.AppendLine($" - {calendarEvent}");
             }
 
-            return new()
-            {
-                Instructions = inputContext.Instructions,
-                Messages =
-                    (inputContext.Messages ?? [])
-                    .Concat(
-                    [
-                        new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
-                    ])
-                    .ToList(),
-                Tools = inputContext.Tools
-            };
+            return [new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())];
         }
     }
 }

dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs

@@ -34,9 +34,6 @@ public abstract class AIContextProvider
     private static IEnumerable<ChatMessage> DefaultExternalOnlyFilter(IEnumerable<ChatMessage> messages)
         => messages.Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External);
 
-    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> _provideInputMessageFilter;
-    private readonly Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> _storeInputMessageFilter;
-
     /// <summary>
     /// Initializes a new instance of the <see cref="AIContextProvider"/> class.
     /// </summary>
@@ -46,10 +43,20 @@ protected AIContextProvider(
         Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideInputMessageFilter = null,
         Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
     {
-        this._provideInputMessageFilter = provideInputMessageFilter ?? DefaultExternalOnlyFilter;
-        this._storeInputMessageFilter = storeInputMessageFilter ?? DefaultExternalOnlyFilter;
+        this.ProvideInputMessageFilter = provideInputMessageFilter ?? DefaultExternalOnlyFilter;
+        this.StoreInputMessageFilter = storeInputMessageFilter ?? DefaultExternalOnlyFilter;
     }
 
+    /// <summary>
+    /// Gets the filter function to apply to input messages before providing context via <see cref="ProvideAIContextAsync"/>.
+    /// </summary>
+    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> ProvideInputMessageFilter { get; }
+
+    /// <summary>
+    /// Gets the filter function to apply to request messages before storing context via <see cref="StoreAIContextAsync"/>.
+    /// </summary>
+    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> StoreInputMessageFilter { get; }
+
     /// <summary>
     /// Gets the key used to store the provider state in the <see cref="AgentSession.StateBag"/>.
     /// </summary>
@@ -120,7 +127,7 @@ protected virtual async ValueTask<AIContext> InvokingCoreAsync(InvokingContext c
             new AIContext
             {
                 Instructions = inputContext.Instructions,
-                Messages = inputContext.Messages is not null ? this._provideInputMessageFilter(inputContext.Messages) : null,
+                Messages = inputContext.Messages is not null ? this.ProvideInputMessageFilter(inputContext.Messages) : null,
                 Tools = inputContext.Tools
             });
 
@@ -254,7 +261,7 @@ protected virtual ValueTask InvokedCoreAsync(InvokedContext context, Cancellatio
             return default;
         }
 
-        var subContext = new InvokedContext(context.Agent, context.Session, this._storeInputMessageFilter(context.RequestMessages), context.ResponseMessages!);
+        var subContext = new InvokedContext(context.Agent, context.Session, this.StoreInputMessageFilter(context.RequestMessages), context.ResponseMessages!);
         return this.StoreAIContextAsync(subContext, cancellationToken);
     }
 

dotnet/src/Microsoft.Agents.AI.Abstractions/MessageAIContextProvider.cs

@@ -0,0 +1,203 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides an abstract base class for components that enhance AI context during agent invocations by supplying additional chat messages.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A message AI context provider is a component that participates in the agent invocation lifecycle by:
+/// <list type="bullet">
+/// <item><description>Listening to changes in conversations</description></item>
+/// <item><description>Providing additional messages to agents during invocation</description></item>
+/// <item><description>Processing invocation results for state management or learning</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Context providers operate through a two-phase lifecycle: they are called at the start of invocation via
+/// <see cref="AIContextProvider.InvokingAsync"/> to provide context, and optionally called at the end of invocation via
+/// <see cref="AIContextProvider.InvokedAsync"/> to process results.
+/// </para>
+/// </remarks>
+public abstract class MessageAIContextProvider : AIContextProvider
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MessageAIContextProvider"/> class.
+    /// </summary>
+    /// <param name="provideInputMessageFilter">An optional filter function to apply to input messages before providing messages via <see cref="ProvideMessagesAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    /// <param name="storeInputMessageFilter">An optional filter function to apply to request messages before storing messages via <see cref="AIContextProvider.StoreAIContextAsync"/>. If not set, defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages.</param>
+    protected MessageAIContextProvider(
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideInputMessageFilter = null,
+        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputMessageFilter = null)
+        : base(provideInputMessageFilter, storeInputMessageFilter)
+    {
+    }
+
+    /// <inheritdoc/>
+    protected override async ValueTask<AIContext> ProvideAIContextAsync(AIContextProvider.InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        // Call ProvideMessagesAsync directly to return only additional messages.
+        // The base AIContextProvider.InvokingCoreAsync handles merging with the original input and stamping.
+        return new AIContext
+        {
+            Messages = await this.ProvideMessagesAsync(
+                new InvokingContext(context.Agent, context.Session, context.AIContext.Messages ?? []),
+                cancellationToken).ConfigureAwait(false)
+        };
+    }
+
+    /// <summary>
+    /// Called at the start of agent invocation to provide additional messages.
+    /// </summary>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the <see cref="IEnumerable{ChatMessage}"/> to be used by the agent during this invocation.</returns>
+    /// <remarks>
+    /// <para>
+    /// Implementers can load any additional messages required at this time, such as:
+    /// <list type="bullet">
+    /// <item><description>Retrieving relevant information from knowledge bases</description></item>
+    /// <item><description>Adding system instructions or prompts</description></item>
+    /// <item><description>Injecting contextual messages from conversation history</description></item>
+    /// </list>
+    /// </para>
+    /// </remarks>
+    public ValueTask<IEnumerable<ChatMessage>> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        => this.InvokingCoreAsync(Throw.IfNull(context), cancellationToken);
+
+    /// <summary>
+    /// Called at the start of agent invocation to provide additional messages.
+    /// </summary>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the <see cref="IEnumerable{ChatMessage}"/> to be used by the agent during this invocation.</returns>
+    /// <remarks>
+    /// <para>
+    /// Implementers can load any additional messages required at this time, such as:
+    /// <list type="bullet">
+    /// <item><description>Retrieving relevant information from knowledge bases</description></item>
+    /// <item><description>Adding system instructions or prompts</description></item>
+    /// <item><description>Injecting contextual messages from conversation history</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// The default implementation of this method filters the input messages using the configured provide-input message filter
+    /// (which defaults to including only <see cref="AgentRequestMessageSourceType.External"/> messages),
+    /// then calls <see cref="ProvideMessagesAsync"/> to get additional messages,
+    /// stamps any messages with <see cref="AgentRequestMessageSourceType.AIContextProvider"/> source attribution,
+    /// and merges the returned messages with the original (unfiltered) input messages.
+    /// For most scenarios, overriding <see cref="ProvideMessagesAsync"/> is sufficient to provide additional messages,
+    /// while still benefiting from the default filtering, merging and source stamping behavior.
+    /// However, for scenarios that require more control over message filtering, merging or source stamping, overriding this method
+    /// allows you to directly control the full <see cref="IEnumerable{ChatMessage}"/> returned for the invocation.
+    /// </para>
+    /// </remarks>
+    protected virtual async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        var inputMessages = context.RequestMessages;
+
+        // Create a filtered context for ProvideMessagesAsync, filtering input messages
+        // to exclude non-external messages (e.g. chat history, other AI context provider messages).
+        var filteredContext = new InvokingContext(
+            context.Agent,
+            context.Session,
+            this.ProvideInputMessageFilter(inputMessages));
+
+        var providedMessages = await this.ProvideMessagesAsync(filteredContext, cancellationToken).ConfigureAwait(false);
+
+        // Stamp and merge provided messages.
+        providedMessages = providedMessages.Select(m => m.WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!));
+        return inputMessages.Concat(providedMessages);
+    }
+
+    /// <summary>
+    /// When overridden in a derived class, provides additional messages to be merged with the input messages for the current invocation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method is called from <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>.
+    /// Note that <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/> can be overridden to directly control messages merging and source stamping, in which case
+    /// it is up to the implementer to call this method as needed to retrieve the additional messages.
+    /// </para>
+    /// <para>
+    /// In contrast with <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>, this method only returns additional messages to be merged with the input,
+    /// while <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/> is responsible for returning the full merged <see cref="IEnumerable{ChatMessage}"/> for the invocation.
+    /// </para>
+    /// </remarks>
+    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>
+    /// A task that represents the asynchronous operation. The task result contains an <see cref="IEnumerable{ChatMessage}"/>
+    /// with additional messages to be merged with the input messages.
+    /// </returns>
+    protected virtual ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<IEnumerable<ChatMessage>>([]);
+    }
+
+    /// <summary>
+    /// Contains the context information provided to <see cref="InvokingCoreAsync(InvokingContext, CancellationToken)"/>.
+    /// </summary>
+    /// <remarks>
+    /// This class provides context about the invocation before the underlying AI model is invoked, including the messages
+    /// that will be used. Message AI Context providers can use this information to determine what additional messages
+    /// should be provided for the invocation.
+    /// </remarks>
+    public new sealed class InvokingContext
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InvokingContext"/> class with the specified request messages.
+        /// </summary>
+        /// <param name="agent">The agent being invoked.</param>
+        /// <param name="session">The session associated with the agent invocation.</param>
+        /// <param name="requestMessages">The messages to be used by the agent for this invocation.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="requestMessages"/> is <see langword="null"/>.</exception>
+        public InvokingContext(
+            AIAgent agent,
+            AgentSession? session,
+            IEnumerable<ChatMessage> requestMessages)
+        {
+            this.Agent = Throw.IfNull(agent);
+            this.Session = session;
+            this.RequestMessages = Throw.IfNull(requestMessages);
+        }
+
+        /// <summary>
+        /// Gets the agent that is being invoked.
+        /// </summary>
+        public AIAgent Agent { get; }
+
+        /// <summary>
+        /// Gets the agent session associated with the agent invocation.
+        /// </summary>
+        public AgentSession? Session { get; }
+
+        /// <summary>
+        /// Gets the messages that will be used by the agent for this invocation. <see cref="ChatHistoryProvider"/> instances can modify
+        /// and return or return a new message list to add additional messages for the invocation.
+        /// </summary>
+        /// <value>
+        /// A collection of <see cref="ChatMessage"/> instances representing the messages that will be used by the agent for this invocation.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// If multiple <see cref="ChatHistoryProvider"/> instances are used in the same invocation, each <see cref="ChatHistoryProvider"/>
+        /// will receive the messages returned by the previous <see cref="ChatHistoryProvider"/> allowing them to build on top of each other's context.
+        /// </para>
+        /// <para>
+        /// The first <see cref="ChatHistoryProvider"/> in the invocation pipeline will receive the
+        /// caller provided messages.
+        /// </para>
+        /// </remarks>
+        public IEnumerable<ChatMessage> RequestMessages { get; set { field = Throw.IfNull(value); } }
+    }
+}