.Net: Rename OnNewMessage callback to OnIntermediateMessage (microsoft#11328)

westey-m · glorious-beard · commit 3b597fefa8ee · 2025-04-06T16:26:24.000-07:00
### Motivation and Context A concern was raised bout confusion between OnNewMessage on the thread and on the invoke options, so renaming the invoke option callback to try and avoid confusion. ### Description Rename OnNewMessage callback to OnIntermediateMessage ### Contribution Checklist  - [ ] The code builds clean without any errors or warnings - [ ] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [ ] All unit tests pass, and I have added new tests where possible - [ ] I didn't break anyone 😄
diff --git a/dotnet/samples/Concepts/Agents/AzureAIAgent_Streaming.cs b/dotnet/samples/Concepts/Agents/AzureAIAgent_Streaming.cs
@@ -111,7 +111,7 @@ Task OnNewMessage(ChatMessageContent message)
 
         bool isFirst = false;
         bool isCode = false;
-        await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new AgentInvokeOptions() { OnNewMessage = OnNewMessage }))
+        await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new AgentInvokeOptions() { OnIntermediateMessage = OnNewMessage }))
         {
             if (string.IsNullOrEmpty(response.Content))
             {
diff --git a/dotnet/samples/Concepts/Agents/OpenAIAssistant_Streaming.cs b/dotnet/samples/Concepts/Agents/OpenAIAssistant_Streaming.cs
@@ -107,7 +107,7 @@ Task OnNewMessage(ChatMessageContent message)
 
         bool isFirst = false;
         bool isCode = false;
-        await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new() { OnNewMessage = OnNewMessage }))
+        await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new() { OnIntermediateMessage = OnNewMessage }))
         {
             if (string.IsNullOrEmpty(response.Content))
             {
diff --git a/dotnet/src/Agents/Abstractions/AgentInvokeOptions.cs b/dotnet/src/Agents/Abstractions/AgentInvokeOptions.cs
@@ -28,7 +28,7 @@ public AgentInvokeOptions(AgentInvokeOptions options)
         this.KernelArguments = options.KernelArguments;
         this.Kernel = options.Kernel;
         this.AdditionalInstructions = options.AdditionalInstructions;
-        this.OnNewMessage = options.OnNewMessage;
+        this.OnIntermediateMessage = options.OnIntermediateMessage;
     }
 
     /// <summary>
@@ -56,5 +56,5 @@ public AgentInvokeOptions(AgentInvokeOptions options)
     /// when invoking the agent with streaming.
     /// </para>
     /// </remarks>
-    public Func<ChatMessageContent, Task>? OnNewMessage { get; init; } = null;
+    public Func<ChatMessageContent, Task>? OnIntermediateMessage { get; init; } = null;
 }
diff --git a/dotnet/src/Agents/AzureAI/AzureAIAgent.cs b/dotnet/src/Agents/AzureAI/AzureAIAgent.cs
@@ -205,9 +205,9 @@ async IAsyncEnumerable<ChatMessageContent> InternalInvokeAsync()
             {
                 // The thread and the caller should be notified of all messages regardless of visibility.
                 await this.NotifyThreadOfNewMessage(azureAIAgentThread, message, cancellationToken).ConfigureAwait(false);
-                if (options?.OnNewMessage is not null)
+                if (options?.OnIntermediateMessage is not null)
                 {
-                    await options.OnNewMessage(message).ConfigureAwait(false);
+                    await options.OnIntermediateMessage(message).ConfigureAwait(false);
                 }
 
                 if (isVisible)
@@ -326,9 +326,9 @@ public async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageContent>> In
         {
             await this.NotifyThreadOfNewMessage(azureAIAgentThread, newMessage, cancellationToken).ConfigureAwait(false);
 
-            if (options?.OnNewMessage is not null)
+            if (options?.OnIntermediateMessage is not null)
             {
-                await options.OnNewMessage(newMessage).ConfigureAwait(false);
+                await options.OnIntermediateMessage(newMessage).ConfigureAwait(false);
             }
         }
     }
diff --git a/dotnet/src/Agents/Core/ChatCompletionAgent.cs b/dotnet/src/Agents/Core/ChatCompletionAgent.cs
@@ -86,9 +86,9 @@ public override async IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> In
             async (m) =>
             {
                 await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, m, cancellationToken).ConfigureAwait(false);
-                if (options?.OnNewMessage is not null)
+                if (options?.OnIntermediateMessage is not null)
                 {
-                    await options.OnNewMessage(m).ConfigureAwait(false);
+                    await options.OnIntermediateMessage(m).ConfigureAwait(false);
                 }
             },
             options?.KernelArguments,
@@ -116,9 +116,9 @@ public override async IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> In
             {
                 await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, result, cancellationToken).ConfigureAwait(false);
 
-                if (options?.OnNewMessage is not null)
+                if (options?.OnIntermediateMessage is not null)
                 {
-                    await options.OnNewMessage(result).ConfigureAwait(false);
+                    await options.OnIntermediateMessage(result).ConfigureAwait(false);
                 }
             }
 
@@ -170,9 +170,9 @@ public override async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageCon
             async (m) =>
             {
                 await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, m, cancellationToken).ConfigureAwait(false);
-                if (options?.OnNewMessage is not null)
+                if (options?.OnIntermediateMessage is not null)
                 {
-                    await options.OnNewMessage(m).ConfigureAwait(false);
+                    await options.OnIntermediateMessage(m).ConfigureAwait(false);
                 }
             },
             options?.KernelArguments,
diff --git a/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs b/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs
@@ -430,9 +430,9 @@ async IAsyncEnumerable<ChatMessageContent> InternalInvokeAsync()
             {
                 // The thread and the caller should be notified of all messages regardless of visibility.
                 await this.NotifyThreadOfNewMessage(openAIAssistantAgentThread, message, cancellationToken).ConfigureAwait(false);
-                if (options?.OnNewMessage is not null)
+                if (options?.OnIntermediateMessage is not null)
                 {
-                    await options.OnNewMessage(message).ConfigureAwait(false);
+                    await options.OnIntermediateMessage(message).ConfigureAwait(false);
                 }
 
                 if (isVisible)
@@ -578,9 +578,9 @@ public async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageContent>> In
         {
             await this.NotifyThreadOfNewMessage(openAIAssistantAgentThread, newMessage, cancellationToken).ConfigureAwait(false);
 
-            if (options?.OnNewMessage is not null)
+            if (options?.OnIntermediateMessage is not null)
             {
-                await options.OnNewMessage(newMessage).ConfigureAwait(false);
+                await options.OnIntermediateMessage(newMessage).ConfigureAwait(false);
             }
         }
     }
diff --git a/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeConformance/ChatCompletionAgentInvokeTests.cs b/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeConformance/ChatCompletionAgentInvokeTests.cs
@@ -35,7 +35,7 @@ public virtual async Task InvokeWithPluginAndManualInvokeAsync()
             options: new()
             {
                 KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(autoInvoke: false) }),
-                OnNewMessage = (message) =>
+                OnIntermediateMessage = (message) =>
                 {
                     notifiedMessages.Add(message);
                     return Task.CompletedTask;
@@ -63,7 +63,7 @@ public virtual async Task InvokeWithPluginAndManualInvokeAsync()
             options: new()
             {
                 KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(autoInvoke: false) }),
-                OnNewMessage = (message) =>
+                OnIntermediateMessage = (message) =>
                 {
                     notifiedMessages.Add(message);
                     return Task.CompletedTask;
diff --git a/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeConformance/InvokeTests.cs b/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeConformance/InvokeTests.cs
@@ -170,7 +170,7 @@ public virtual async Task InvokeWithPluginNotifiesForAllMessagesAsync()
             options: new()
             {
                 KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }),
-                OnNewMessage = (message) =>
+                OnIntermediateMessage = (message) =>
                 {
                     notifiedMessages.Add(message);
                     return Task.CompletedTask;
diff --git a/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeStreamingConformance/InvokeStreamingTests.cs b/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/InvokeStreamingConformance/InvokeStreamingTests.cs
@@ -175,7 +175,7 @@ public virtual async Task InvokeStreamingWithPluginNotifiesForAllMessagesAsync()
             options: new()
             {
                 KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }),
-                OnNewMessage = (message) =>
+                OnIntermediateMessage = (message) =>
                 {
                     notifiedMessages.Add(message);
                     return Task.CompletedTask;

Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,7 @@ Task OnNewMessage(ChatMessageContent message)`
`111`	`111`
`112`	`112`	`bool isFirst = false;`
`113`	`113`	`bool isCode = false;`
`114`		`- await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new AgentInvokeOptions() { OnNewMessage = OnNewMessage }))`
	`114`	`+ await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new AgentInvokeOptions() { OnIntermediateMessage = OnNewMessage }))`
`115`	`115`	`{`
`116`	`116`	`if (string.IsNullOrEmpty(response.Content))`
`117`	`117`	`{`
Original file line number	Diff line number	Diff line change
`@@ -107,7 +107,7 @@ Task OnNewMessage(ChatMessageContent message)`
`107`	`107`
`108`	`108`	`bool isFirst = false;`
`109`	`109`	`bool isCode = false;`
`110`		`- await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new() { OnNewMessage = OnNewMessage }))`
	`110`	`+ await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread, new() { OnIntermediateMessage = OnNewMessage }))`
`111`	`111`	`{`
`112`	`112`	`if (string.IsNullOrEmpty(response.Content))`
`113`	`113`	`{`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ public AgentInvokeOptions(AgentInvokeOptions options)`
`28`	`28`	`this.KernelArguments = options.KernelArguments;`
`29`	`29`	`this.Kernel = options.Kernel;`
`30`	`30`	`this.AdditionalInstructions = options.AdditionalInstructions;`
`31`		`- this.OnNewMessage = options.OnNewMessage;`
	`31`	`+ this.OnIntermediateMessage = options.OnIntermediateMessage;`
`32`	`32`	`}`
`33`	`33`
`34`	`34`	`/// <summary>`
`@@ -56,5 +56,5 @@ public AgentInvokeOptions(AgentInvokeOptions options)`
`56`	`56`	`/// when invoking the agent with streaming.`
`57`	`57`	`/// </para>`
`58`	`58`	`/// </remarks>`
`59`		`- public Func<ChatMessageContent, Task>? OnNewMessage { get; init; } = null;`
	`59`	`+ public Func<ChatMessageContent, Task>? OnIntermediateMessage { get; init; } = null;`
`60`	`60`	`}`
Original file line number	Diff line number	Diff line change
`@@ -205,9 +205,9 @@ async IAsyncEnumerable<ChatMessageContent> InternalInvokeAsync()`
`205`	`205`	`{`
`206`	`206`	`// The thread and the caller should be notified of all messages regardless of visibility.`
`207`	`207`	`await this.NotifyThreadOfNewMessage(azureAIAgentThread, message, cancellationToken).ConfigureAwait(false);`
`208`		`- if (options?.OnNewMessage is not null)`
	`208`	`+ if (options?.OnIntermediateMessage is not null)`
`209`	`209`	`{`
`210`		`- await options.OnNewMessage(message).ConfigureAwait(false);`
	`210`	`+ await options.OnIntermediateMessage(message).ConfigureAwait(false);`
`211`	`211`	`}`
`212`	`212`
`213`	`213`	`if (isVisible)`
`@@ -326,9 +326,9 @@ public async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageContent>> In`
`326`	`326`	`{`
`327`	`327`	`await this.NotifyThreadOfNewMessage(azureAIAgentThread, newMessage, cancellationToken).ConfigureAwait(false);`
`328`	`328`
`329`		`- if (options?.OnNewMessage is not null)`
	`329`	`+ if (options?.OnIntermediateMessage is not null)`
`330`	`330`	`{`
`331`		`- await options.OnNewMessage(newMessage).ConfigureAwait(false);`
	`331`	`+ await options.OnIntermediateMessage(newMessage).ConfigureAwait(false);`
`332`	`332`	`}`
`333`	`333`	`}`
`334`	`334`	`}`
Original file line number	Diff line number	Diff line change
`@@ -86,9 +86,9 @@ public override async IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> In`
`86`	`86`	`async (m) =>`
`87`	`87`	`{`
`88`	`88`	`await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, m, cancellationToken).ConfigureAwait(false);`
`89`		`- if (options?.OnNewMessage is not null)`
	`89`	`+ if (options?.OnIntermediateMessage is not null)`
`90`	`90`	`{`
`91`		`- await options.OnNewMessage(m).ConfigureAwait(false);`
	`91`	`+ await options.OnIntermediateMessage(m).ConfigureAwait(false);`
`92`	`92`	`}`
`93`	`93`	`},`
`94`	`94`	`options?.KernelArguments,`
`@@ -116,9 +116,9 @@ public override async IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> In`
`116`	`116`	`{`
`117`	`117`	`await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, result, cancellationToken).ConfigureAwait(false);`
`118`	`118`
`119`		`- if (options?.OnNewMessage is not null)`
	`119`	`+ if (options?.OnIntermediateMessage is not null)`
`120`	`120`	`{`
`121`		`- await options.OnNewMessage(result).ConfigureAwait(false);`
	`121`	`+ await options.OnIntermediateMessage(result).ConfigureAwait(false);`
`122`	`122`	`}`
`123`	`123`	`}`
`124`	`124`
`@@ -170,9 +170,9 @@ public override async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageCon`
`170`	`170`	`async (m) =>`
`171`	`171`	`{`
`172`	`172`	`await this.NotifyThreadOfNewMessage(chatHistoryAgentThread, m, cancellationToken).ConfigureAwait(false);`
`173`		`- if (options?.OnNewMessage is not null)`
	`173`	`+ if (options?.OnIntermediateMessage is not null)`
`174`	`174`	`{`
`175`		`- await options.OnNewMessage(m).ConfigureAwait(false);`
	`175`	`+ await options.OnIntermediateMessage(m).ConfigureAwait(false);`
`176`	`176`	`}`
`177`	`177`	`},`
`178`	`178`	`options?.KernelArguments,`
Original file line number	Diff line number	Diff line change
`@@ -430,9 +430,9 @@ async IAsyncEnumerable<ChatMessageContent> InternalInvokeAsync()`
`430`	`430`	`{`
`431`	`431`	`// The thread and the caller should be notified of all messages regardless of visibility.`
`432`	`432`	`await this.NotifyThreadOfNewMessage(openAIAssistantAgentThread, message, cancellationToken).ConfigureAwait(false);`
`433`		`- if (options?.OnNewMessage is not null)`
	`433`	`+ if (options?.OnIntermediateMessage is not null)`
`434`	`434`	`{`
`435`		`- await options.OnNewMessage(message).ConfigureAwait(false);`
	`435`	`+ await options.OnIntermediateMessage(message).ConfigureAwait(false);`
`436`	`436`	`}`
`437`	`437`
`438`	`438`	`if (isVisible)`
`@@ -578,9 +578,9 @@ public async IAsyncEnumerable<AgentResponseItem<StreamingChatMessageContent>> In`
`578`	`578`	`{`
`579`	`579`	`await this.NotifyThreadOfNewMessage(openAIAssistantAgentThread, newMessage, cancellationToken).ConfigureAwait(false);`
`580`	`580`
`581`		`- if (options?.OnNewMessage is not null)`
	`581`	`+ if (options?.OnIntermediateMessage is not null)`
`582`	`582`	`{`
`583`		`- await options.OnNewMessage(newMessage).ConfigureAwait(false);`
	`583`	`+ await options.OnIntermediateMessage(newMessage).ConfigureAwait(false);`
`584`	`584`	`}`
`585`	`585`	`}`
`586`	`586`	`}`
Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@ public virtual async Task InvokeWithPluginAndManualInvokeAsync()`
`35`	`35`	`options: new()`
`36`	`36`	`{`
`37`	`37`	`KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(autoInvoke: false) }),`
`38`		`- OnNewMessage = (message) =>`
	`38`	`+ OnIntermediateMessage = (message) =>`
`39`	`39`	`{`
`40`	`40`	`notifiedMessages.Add(message);`
`41`	`41`	`return Task.CompletedTask;`
`@@ -63,7 +63,7 @@ public virtual async Task InvokeWithPluginAndManualInvokeAsync()`
`63`	`63`	`options: new()`
`64`	`64`	`{`
`65`	`65`	`KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(autoInvoke: false) }),`
`66`		`- OnNewMessage = (message) =>`
	`66`	`+ OnIntermediateMessage = (message) =>`
`67`	`67`	`{`
`68`	`68`	`notifiedMessages.Add(message);`
`69`	`69`	`return Task.CompletedTask;`
Original file line number	Diff line number	Diff line change
`@@ -170,7 +170,7 @@ public virtual async Task InvokeWithPluginNotifiesForAllMessagesAsync()`
`170`	`170`	`options: new()`
`171`	`171`	`{`
`172`	`172`	`KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }),`
`173`		`- OnNewMessage = (message) =>`
	`173`	`+ OnIntermediateMessage = (message) =>`
`174`	`174`	`{`
`175`	`175`	`notifiedMessages.Add(message);`
`176`	`176`	`return Task.CompletedTask;`
Original file line number	Diff line number	Diff line change
`@@ -175,7 +175,7 @@ public virtual async Task InvokeStreamingWithPluginNotifiesForAllMessagesAsync()`
`175`	`175`	`options: new()`
`176`	`176`	`{`
`177`	`177`	`KernelArguments = new KernelArguments(new PromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }),`
`178`		`- OnNewMessage = (message) =>`
	`178`	`+ OnIntermediateMessage = (message) =>`
`179`	`179`	`{`
`180`	`180`	`notifiedMessages.Add(message);`
`181`	`181`	`return Task.CompletedTask;`