.NET: [BREAKING] Update message source code to match python. (#3805)

* Update message source code to match python.

* Apply suggestion from @Copilot

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

* Address PR comment

* Move setting of source information to extension method

* Add underscore for attribution key to indicate internal usage

* Stick to version 102 of the SDK since 103 is causing issues.

* Revert global.json change

* Fix unit test

---------

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

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

@@ -32,23 +32,23 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public abstract class AIContextProvider
 {
-    private readonly string _sourceName;
+    private readonly string _sourceId;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="AIContextProvider"/> class.
     /// </summary>
     protected AIContextProvider()
     {
-        this._sourceName = this.GetType().FullName!;
+        this._sourceId = this.GetType().FullName!;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="AIContextProvider"/> class with the specified source name.
+    /// Initializes a new instance of the <see cref="AIContextProvider"/> class with the specified source id.
     /// </summary>
-    /// <param name="sourceName">The source name to stamp on <see cref="ChatMessage.AdditionalProperties"/> for each messages produced by the <see cref="AIContextProvider"/>.</param>
-    protected AIContextProvider(string sourceName)
+    /// <param name="sourceId">The source id to stamp on <see cref="ChatMessage.AdditionalProperties"/> for each messages produced by the <see cref="AIContextProvider"/>.</param>
+    protected AIContextProvider(string sourceId)
     {
-        this._sourceName = sourceName;
+        this._sourceId = sourceId;
     }
 
     /// <summary>
@@ -76,27 +76,9 @@ public abstract class AIContextProvider
             return aiContext;
         }
 
-        aiContext.Messages = aiContext.Messages.Select(message =>
-        {
-            if (message.AdditionalProperties != null
-                // Check if the message was already tagged with this provider's source type
-                && message.AdditionalProperties.TryGetValue(AgentRequestMessageSourceType.AdditionalPropertiesKey, out var messageSourceType)
-                && messageSourceType is AgentRequestMessageSourceType typedMessageSourceType
-                && typedMessageSourceType == AgentRequestMessageSourceType.AIContextProvider
-                // Check if the message was already tagged with this provider's source
-                && message.AdditionalProperties.TryGetValue(AgentRequestMessageSource.AdditionalPropertiesKey, out var messageSource)
-                && messageSource is string typedMessageSource
-                && typedMessageSource == this._sourceName)
-            {
-                return message;
-            }
-
-            message = message.Clone();
-            message.AdditionalProperties ??= new();
-            message.AdditionalProperties[AgentRequestMessageSourceType.AdditionalPropertiesKey] = AgentRequestMessageSourceType.AIContextProvider;
-            message.AdditionalProperties[AgentRequestMessageSource.AdditionalPropertiesKey] = this._sourceName;
-            return message;
-        }).ToList();
+        aiContext.Messages = aiContext.Messages
+            .Select(message => message.AsAgentRequestMessageSourcedMessage(AgentRequestMessageSourceType.AIContextProvider, this._sourceId))
+            .ToList();
 
         return aiContext;
     }

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

@@ -1,16 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Extensions.AI;
-
-namespace Microsoft.Agents.AI;
-
-/// <summary>
-/// Provides a constant for the key used to store the source of the agent request message.
-/// </summary>
-public static class AgentRequestMessageSource
-{
-    /// <summary>
-    /// Provides the key used in <see cref="ChatMessage.AdditionalProperties"/> to store the source of the agent request message.
-    /// </summary>
-    public static readonly string AdditionalPropertiesKey = "Agent.RequestMessageSource";
-}

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

@@ -0,0 +1,102 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents attribution information for the source of an agent request message for a specific run, including the component type and
+/// identifier.
+/// </summary>
+/// <remarks>
+/// Use this struct to identify which component provided a message during an agent run.
+/// This is useful to allow filtering of messages based on their source, such as distinguishing between user input, middleware-generated messages, and chat history.
+/// </remarks>
+public readonly struct AgentRequestMessageSourceAttribution : IEquatable<AgentRequestMessageSourceAttribution>
+{
+    /// <summary>
+    /// Provides the key used in <see cref="ChatMessage.AdditionalProperties"/> to store the <see cref="AgentRequestMessageSourceAttribution"/>
+    /// associated with the agent request message.
+    /// </summary>
+    public static readonly string AdditionalPropertiesKey = "_attribution";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentRequestMessageSourceAttribution"/> struct with the specified source type and identifier.
+    /// </summary>
+    /// <param name="sourceType">The <see cref="AgentRequestMessageSourceType"/> of the component that provided the message.</param>
+    /// <param name="sourceId">The unique identifier of the component that provided the message.</param>
+    public AgentRequestMessageSourceAttribution(AgentRequestMessageSourceType sourceType, string? sourceId)
+    {
+        this.SourceType = sourceType;
+        this.SourceId = sourceId;
+    }
+
+    /// <summary>
+    /// Gets the type of component that provided the message for the current agent run.
+    /// </summary>
+    public AgentRequestMessageSourceType SourceType { get; }
+
+    /// <summary>
+    /// Gets the unique identifier of the component that provided the message for the current agent run.
+    /// </summary>
+    public string? SourceId { get; }
+
+    /// <summary>
+    /// Determines whether the specified <see cref="AgentRequestMessageSourceAttribution"/> is equal to the current instance.
+    /// </summary>
+    /// <param name="other">The <see cref="AgentRequestMessageSourceAttribution"/> to compare with the current instance.</param>
+    /// <returns><see langword="true"/> if the specified instance is equal to the current instance; otherwise, <see langword="false"/>.</returns>
+    public bool Equals(AgentRequestMessageSourceAttribution other)
+    {
+        return this.SourceType == other.SourceType &&
+               string.Equals(this.SourceId, other.SourceId, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// Determines whether the specified object is equal to the current instance.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current instance.</param>
+    /// <returns><see langword="true"/> if the specified object is equal to the current instance; otherwise, <see langword="false"/>.</returns>
+    public override bool Equals(object? obj)
+    {
+        return obj is AgentRequestMessageSourceAttribution other && this.Equals(other);
+    }
+
+    /// <summary>
+    /// Returns a hash code for the current instance.
+    /// </summary>
+    /// <returns>A hash code for the current instance.</returns>
+    public override int GetHashCode()
+    {
+        unchecked
+        {
+            int hash = 17;
+            hash = (hash * 31) + this.SourceType.GetHashCode();
+            hash = (hash * 31) + (this.SourceId?.GetHashCode() ?? 0);
+            return hash;
+        }
+    }
+
+    /// <summary>
+    /// Determines whether two <see cref="AgentRequestMessageSourceAttribution"/> instances are equal.
+    /// </summary>
+    /// <param name="left">The first instance to compare.</param>
+    /// <param name="right">The second instance to compare.</param>
+    /// <returns><see langword="true"/> if the instances are equal; otherwise, <see langword="false"/>.</returns>
+    public static bool operator ==(AgentRequestMessageSourceAttribution left, AgentRequestMessageSourceAttribution right)
+    {
+        return left.Equals(right);
+    }
+
+    /// <summary>
+    /// Determines whether two <see cref="AgentRequestMessageSourceAttribution"/> instances are not equal.
+    /// </summary>
+    /// <param name="left">The first instance to compare.</param>
+    /// <param name="right">The second instance to compare.</param>
+    /// <returns><see langword="true"/> if the instances are not equal; otherwise, <see langword="false"/>.</returns>
+    public static bool operator !=(AgentRequestMessageSourceAttribution left, AgentRequestMessageSourceAttribution right)
+    {
+        return !left.Equals(right);
+    }
+}

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

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
-using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI;
@@ -14,15 +13,10 @@ namespace Microsoft.Agents.AI;
 /// This type helps to identify whether a message came from outside the agent pipeline,
 /// whether it was produced by middleware, or came from chat history.
 /// </remarks>
-public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessageSourceType>
+public readonly struct AgentRequestMessageSourceType : IEquatable<AgentRequestMessageSourceType>
 {
     /// <summary>
-    /// Provides the key used in <see cref="ChatMessage.AdditionalProperties"/> to store the source type of the agent request message.
-    /// </summary>
-    public static readonly string AdditionalPropertiesKey = "Agent.RequestMessageSourceType";
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AgentRequestMessageSourceType"/> class.
+    /// Initializes a new instance of the <see cref="AgentRequestMessageSourceType"/> struct.
     /// </summary>
     /// <param name="value">The string value representing the source of the agent request message.</param>
     public AgentRequestMessageSourceType(string value) => this.Value = Throw.IfNullOrWhitespace(value);
@@ -30,7 +24,7 @@ public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessa
     /// <summary>
     /// Get the string value representing the source of the agent request message.
     /// </summary>
-    public string Value { get; }
+    public string Value { get { return field ?? External.Value; } }
 
     /// <summary>
     /// The message came from outside the agent pipeline (e.g., user input).
@@ -52,18 +46,8 @@ public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessa
     /// </summary>
     /// <param name="other">The <see cref="AgentRequestMessageSourceType"/> to compare to this instance.</param>
     /// <returns><see langword="true"/> if the value of the <paramref name="other"/> parameter is the same as the value of this instance; otherwise, <see langword="false"/>.</returns>
-    public bool Equals(AgentRequestMessageSourceType? other)
+    public bool Equals(AgentRequestMessageSourceType other)
     {
-        if (other is null)
-        {
-            return false;
-        }
-
-        if (ReferenceEquals(this, other))
-        {
-            return true;
-        }
-
         return string.Equals(this.Value, other.Value, StringComparison.Ordinal);
     }
 
@@ -72,7 +56,7 @@ public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessa
     /// </summary>
     /// <param name="obj">The object to compare to this instance.</param>
     /// <returns><see langword="true"/> if <paramref name="obj"/> is a <see cref="AgentRequestMessageSourceType"/> and its value is the same as this instance; otherwise, <see langword="false"/>.</returns>
-    public override bool Equals(object? obj) => this.Equals(obj as AgentRequestMessageSourceType);
+    public override bool Equals(object? obj) => obj is AgentRequestMessageSourceType other && this.Equals(other);
 
     /// <summary>
     /// Returns the hash code for this instance.
@@ -86,13 +70,8 @@ public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessa
     /// <param name="left">The first <see cref="AgentRequestMessageSourceType"/> to compare.</param>
     /// <param name="right">The second <see cref="AgentRequestMessageSourceType"/> to compare.</param>
     /// <returns><see langword="true"/> if the value of <paramref name="left"/> is the same as the value of <paramref name="right"/>; otherwise, <see langword="false"/>.</returns>
-    public static bool operator ==(AgentRequestMessageSourceType? left, AgentRequestMessageSourceType? right)
+    public static bool operator ==(AgentRequestMessageSourceType left, AgentRequestMessageSourceType right)
     {
-        if (left is null)
-        {
-            return right is null;
-        }
-
         return left.Equals(right);
     }
 
@@ -102,5 +81,5 @@ public sealed class AgentRequestMessageSourceType : IEquatable<AgentRequestMessa
     /// <param name="left">The first <see cref="AgentRequestMessageSourceType"/> to compare.</param>
     /// <param name="right">The second <see cref="AgentRequestMessageSourceType"/> to compare.</param>
     /// <returns><see langword="true"/> if the value of <paramref name="left"/> is different from the value of <paramref name="right"/>; otherwise, <see langword="false"/>.</returns>
-    public static bool operator !=(AgentRequestMessageSourceType? left, AgentRequestMessageSourceType? right) => !(left == right);
+    public static bool operator !=(AgentRequestMessageSourceType left, AgentRequestMessageSourceType right) => !(left == right);
 }

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

@@ -37,23 +37,23 @@ namespace Microsoft.Agents.AI;
 /// </remarks>
 public abstract class ChatHistoryProvider
 {
-    private readonly string _sourceName;
+    private readonly string _sourceId;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="ChatHistoryProvider"/> class.
     /// </summary>
     protected ChatHistoryProvider()
     {
-        this._sourceName = this.GetType().FullName!;
+        this._sourceId = this.GetType().FullName!;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ChatHistoryProvider"/> class with the specified source name.
+    /// Initializes a new instance of the <see cref="ChatHistoryProvider"/> class with the specified source id.
     /// </summary>
-    /// <param name="sourceName">The source name to stamp on <see cref="ChatMessage.AdditionalProperties"/> for each messages produced by the <see cref="ChatHistoryProvider"/>.</param>
-    protected ChatHistoryProvider(string sourceName)
+    /// <param name="sourceId">The source id to stamp on <see cref="ChatMessage.AdditionalProperties"/> for each messages produced by the <see cref="ChatHistoryProvider"/>.</param>
+    protected ChatHistoryProvider(string sourceId)
     {
-        this._sourceName = sourceName;
+        this._sourceId = sourceId;
     }
 
     /// <summary>
@@ -89,27 +89,7 @@ public abstract class ChatHistoryProvider
     {
         var messages = await this.InvokingCoreAsync(context, cancellationToken).ConfigureAwait(false);
 
-        return messages.Select(message =>
-        {
-            if (message.AdditionalProperties != null
-                // Check if the message was already tagged with this provider's source type
-                && message.AdditionalProperties.TryGetValue(AgentRequestMessageSourceType.AdditionalPropertiesKey, out var messageSourceType)
-                && messageSourceType is AgentRequestMessageSourceType typedMessageSourceType
-                && typedMessageSourceType == AgentRequestMessageSourceType.ChatHistory
-                // Check if the message was already tagged with this provider's source
-                && message.AdditionalProperties.TryGetValue(AgentRequestMessageSource.AdditionalPropertiesKey, out var messageSource)
-                && messageSource is string typedMessageSource
-                && typedMessageSource == this._sourceName)
-            {
-                return message;
-            }
-
-            message = message.Clone();
-            message.AdditionalProperties ??= new();
-            message.AdditionalProperties[AgentRequestMessageSourceType.AdditionalPropertiesKey] = AgentRequestMessageSourceType.ChatHistory;
-            message.AdditionalProperties[AgentRequestMessageSource.AdditionalPropertiesKey] = this._sourceName;
-            return message;
-        });
+        return messages.Select(message => message.AsAgentRequestMessageSourcedMessage(AgentRequestMessageSourceType.ChatHistory, this._sourceId));
     }
 
     /// <summary>

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

@@ -45,7 +45,7 @@ public static class ChatHistoryProviderExtensions
             innerProvider: provider,
             invokedMessagesFilter: (ctx) =>
             {
-                ctx.RequestMessages = ctx.RequestMessages.Where(x => x.GetAgentRequestMessageSource() != AgentRequestMessageSourceType.AIContextProvider);
+                ctx.RequestMessages = ctx.RequestMessages.Where(x => x.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider);
                 return ctx;
             });
     }

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

@@ -10,18 +10,66 @@ namespace Microsoft.Agents.AI;
 public static class ChatMessageExtensions
 {
     /// <summary>
-    /// Gets the source of the provided <see cref="ChatMessage"/> in the context of messages passed into an agent run.
+    /// Gets the source type of the provided <see cref="ChatMessage"/> in the context of messages passed into an agent run.
     /// </summary>
-    /// <param name="message">The <see cref="ChatMessage"/> for which we need the source.</param>
-    /// <returns>An <see cref="AgentRequestMessageSourceType"/> value indicating the source of the <see cref="ChatMessage"/>. Defaults to <see
+    /// <param name="message">The <see cref="ChatMessage"/> for which we need the source type.</param>
+    /// <returns>An <see cref="AgentRequestMessageSourceType"/> value indicating the source type of the <see cref="ChatMessage"/>. Defaults to <see
     /// cref="AgentRequestMessageSourceType.External"/> if no explicit source is defined.</returns>
-    public static AgentRequestMessageSourceType GetAgentRequestMessageSource(this ChatMessage message)
+    public static AgentRequestMessageSourceType GetAgentRequestMessageSourceType(this ChatMessage message)
     {
-        if (message.AdditionalProperties?.TryGetValue(AgentRequestMessageSourceType.AdditionalPropertiesKey, out var source) is true && source is AgentRequestMessageSourceType typedSource)
+        if (message.AdditionalProperties?.TryGetValue(AgentRequestMessageSourceAttribution.AdditionalPropertiesKey, out var attribution) is true
+            && attribution is AgentRequestMessageSourceAttribution typedAttribution)
         {
-            return typedSource;
+            return typedAttribution.SourceType;
         }
 
         return AgentRequestMessageSourceType.External;
     }
+
+    /// <summary>
+    /// Gets the source id of the provided <see cref="ChatMessage"/> in the context of messages passed into an agent run.
+    /// </summary>
+    /// <param name="message">The <see cref="ChatMessage"/> for which we need the source id.</param>
+    /// <returns>An <see cref="string"/> value indicating the source id of the <see cref="ChatMessage"/>. Defaults to <see langword="null"/>
+    /// if no explicit source id is defined.</returns>
+    public static string? GetAgentRequestMessageSourceId(this ChatMessage message)
+    {
+        if (message.AdditionalProperties?.TryGetValue(AgentRequestMessageSourceAttribution.AdditionalPropertiesKey, out var attribution) is true
+            && attribution is AgentRequestMessageSourceAttribution typedAttribution)
+        {
+            return typedAttribution.SourceId;
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Ensure that the provided message is tagged with the provided source type and source id in the context of a specific agent run.
+    /// </summary>
+    /// <param name="message">The message to tag.</param>
+    /// <param name="sourceType">The source type to tag the message with.</param>
+    /// <param name="sourceId">The source id to tag the message with.</param>
+    /// <returns>The tagged message.</returns>
+    /// <remarks>
+    /// If the message is already tagged with the provided source type and source id, it is returned as is.
+    /// Otherwise, a cloned message is returned with the appropriate tagging in the AdditionalProperties.
+    /// </remarks>
+    public static ChatMessage AsAgentRequestMessageSourcedMessage(this ChatMessage message, AgentRequestMessageSourceType sourceType, string? sourceId = null)
+    {
+        if (message.AdditionalProperties != null
+            // Check if the message was already tagged with the required source type and source id
+            && message.AdditionalProperties.TryGetValue(AgentRequestMessageSourceAttribution.AdditionalPropertiesKey, out var messageSourceAttribution)
+            && messageSourceAttribution is AgentRequestMessageSourceAttribution typedMessageSourceAttribution
+            && typedMessageSourceAttribution.SourceType == sourceType
+            && typedMessageSourceAttribution.SourceId == sourceId)
+        {
+            return message;
+        }
+
+        message = message.Clone();
+        message.AdditionalProperties ??= new();
+        message.AdditionalProperties[AgentRequestMessageSourceAttribution.AdditionalPropertiesKey] =
+            new AgentRequestMessageSourceAttribution(sourceType, sourceId);
+        return message;
+    }
 }

dotnet/src/Microsoft.Agents.AI.Mem0/Mem0Provider.cs

@@ -138,7 +138,7 @@ public sealed class Mem0Provider : AIContextProvider
         string queryText = string.Join(
             Environment.NewLine,
             context.RequestMessages
-                .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+                .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
                 .Where(m => !string.IsNullOrWhiteSpace(m.Text))
                 .Select(m => m.Text));
 
@@ -217,7 +217,7 @@ public sealed class Mem0Provider : AIContextProvider
             // Persist request and response messages after invocation.
             await this.PersistMessagesAsync(
                 context.RequestMessages
-                    .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+                    .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
                     .Concat(context.ResponseMessages ?? []),
                 cancellationToken).ConfigureAwait(false);
         }

dotnet/src/Microsoft.Agents.AI/Memory/ChatHistoryMemoryProvider.cs

@@ -189,7 +189,7 @@ public sealed class ChatHistoryMemoryProvider : AIContextProvider, IDisposable
         {
             // Get the text from the current request messages
             var requestText = string.Join("\n", context.RequestMessages
-                .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+                .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
                 .Where(m => m != null && !string.IsNullOrWhiteSpace(m.Text))
                 .Select(m => m.Text));
 
@@ -245,7 +245,7 @@ public sealed class ChatHistoryMemoryProvider : AIContextProvider, IDisposable
             var collection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
 
             List<Dictionary<string, object?>> itemsToStore = context.RequestMessages
-                .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+                .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
                 .Concat(context.ResponseMessages ?? [])
                 .Select(message => new Dictionary<string, object?>
                 {

dotnet/src/Microsoft.Agents.AI/TextSearchProvider.cs

@@ -118,7 +118,7 @@ public sealed class TextSearchProvider : AIContextProvider
         // Aggregate text from memory + current request messages.
         var sbInput = new StringBuilder();
         var requestMessagesText = context.RequestMessages
-            .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+            .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
             .Where(x => !string.IsNullOrWhiteSpace(x?.Text)).Select(x => x.Text);
         foreach (var messageText in this._recentMessagesText.Concat(requestMessagesText))
         {
@@ -182,7 +182,7 @@ public sealed class TextSearchProvider : AIContextProvider
         }
 
         var messagesText = context.RequestMessages
-            .Where(m => m.GetAgentRequestMessageSource() == AgentRequestMessageSourceType.External)
+            .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.External)
             .Concat(context.ResponseMessages ?? [])
             .Where(m =>
                 this._recentMessageRolesIncluded.Contains(m.Role) &&