Expose streaming conversion utility methods

stephentoub · stephentoub · commit 463a4ab38ed0 · 2025-07-21T09:38:33.000-04:00
We're already exposing the non-streaming response conversions. Expose the streaming ones as well.
diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/MicrosoftExtensionsAIChatExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/MicrosoftExtensionsAIChatExtensions.cs
@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Threading;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
@@ -20,14 +21,28 @@ public static ChatTool AsOpenAIChatTool(this AIFunction function) =>
 
     /// <summary>Creates a sequence of OpenAI <see cref="ChatMessage"/> instances from the specified input messages.</summary>
     /// <param name="messages">The input messages to convert.</param>
+    /// <param name="options">The options employed while processing <paramref name="messages"/>.</param>
     /// <returns>A sequence of OpenAI chat messages.</returns>
-    public static IEnumerable<ChatMessage> AsOpenAIChatMessages(this IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages) =>
-        OpenAIChatClient.ToOpenAIChatMessages(Throw.IfNull(messages), chatOptions: null);
+    public static IEnumerable<ChatMessage> AsOpenAIChatMessages(this IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, ChatOptions? options = null) =>
+        OpenAIChatClient.ToOpenAIChatMessages(Throw.IfNull(messages), options);
 
     /// <summary>Creates a Microsoft.Extensions.AI <see cref="ChatResponse"/> from a <see cref="ChatCompletion"/>.</summary>
     /// <param name="chatCompletion">The <see cref="ChatCompletion"/> to convert to a <see cref="ChatResponse"/>.</param>
     /// <param name="options">The options employed in the creation of the response.</param>
     /// <returns>A converted <see cref="ChatResponse"/>.</returns>
     public static ChatResponse AsChatResponse(this ChatCompletion chatCompletion, ChatCompletionOptions? options = null) =>
         OpenAIChatClient.FromOpenAIChatCompletion(Throw.IfNull(chatCompletion), options);
+
+    /// <summary>
+    /// Creates a sequence of Microsoft.Extensions.AI <see cref="ChatResponseUpdate"/> instances from the specified
+    /// sequence of OpenAI <see cref="StreamingChatCompletionUpdate"/> instances.
+    /// </summary>
+    /// <param name="chatCompletionUpdates">The update instances.</param>
+    /// <param name="options">The options employed in the creation of the response.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A sequence of converted <see cref="ChatResponseUpdate"/> instances.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="chatCompletionUpdates"/> is <see langword="null"/>.</exception>
+    public static IAsyncEnumerable<ChatResponseUpdate> AsChatResponseUpdatesAsync(
+        this IAsyncEnumerable<StreamingChatCompletionUpdate> chatCompletionUpdates, ChatCompletionOptions? options = null, CancellationToken cancellationToken = default) =>
+        OpenAIChatClient.FromOpenAIStreamingChatCompletionAsync(Throw.IfNull(chatCompletionUpdates), options, cancellationToken);
 }
diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/MicrosoftExtensionsAIResponsesExtensions.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/MicrosoftExtensionsAIResponsesExtensions.cs
@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Threading;
 using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
@@ -20,14 +21,30 @@ public static ResponseTool AsOpenAIResponseTool(this AIFunction function) =>
 
     /// <summary>Creates a sequence of OpenAI <see cref="ResponseItem"/> instances from the specified input messages.</summary>
     /// <param name="messages">The input messages to convert.</param>
+    /// <param name="options">The options employed while processing <paramref name="messages"/>.</param>
     /// <returns>A sequence of OpenAI response items.</returns>
-    public static IEnumerable<ResponseItem> AsOpenAIResponseItems(this IEnumerable<ChatMessage> messages) =>
-        OpenAIResponsesChatClient.ToOpenAIResponseItems(Throw.IfNull(messages));
+    /// <exception cref="ArgumentNullException"><paramref name="messages"/> is <see langword="null"/>.</exception>
+    public static IEnumerable<ResponseItem> AsOpenAIResponseItems(this IEnumerable<ChatMessage> messages, ChatOptions? options = null) =>
+        OpenAIResponsesChatClient.ToOpenAIResponseItems(Throw.IfNull(messages), options);
 
     /// <summary>Creates a Microsoft.Extensions.AI <see cref="ChatResponse"/> from an <see cref="OpenAIResponse"/>.</summary>
     /// <param name="response">The <see cref="OpenAIResponse"/> to convert to a <see cref="ChatResponse"/>.</param>
     /// <param name="options">The options employed in the creation of the response.</param>
     /// <returns>A converted <see cref="ChatResponse"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="response"/> is <see langword="null"/>.</exception>
     public static ChatResponse AsChatResponse(this OpenAIResponse response, ResponseCreationOptions? options = null) =>
         OpenAIResponsesChatClient.FromOpenAIResponse(Throw.IfNull(response), options);
+
+    /// <summary>
+    /// Creates a sequence of Microsoft.Extensions.AI <see cref="ChatResponseUpdate"/> instances from the specified
+    /// sequence of OpenAI <see cref="StreamingResponseUpdate"/> instances.
+    /// </summary>
+    /// <param name="responseUpdates">The update instances.</param>
+    /// <param name="options">The options employed in the creation of the response.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A sequence of converted <see cref="ChatResponseUpdate"/> instances.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="responseUpdates"/> is <see langword="null"/>.</exception>
+    public static IAsyncEnumerable<ChatResponseUpdate> AsChatResponseUpdatesAsync(
+        this IAsyncEnumerable<StreamingResponseUpdate> responseUpdates, ResponseCreationOptions? options = null, CancellationToken cancellationToken = default) =>
+        OpenAIResponsesChatClient.FromOpenAIStreamingResponseUpdatesAsync(Throw.IfNull(responseUpdates), options, cancellationToken);
 }
diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs
@@ -289,7 +289,7 @@ private static List<ChatMessageContentPart> ToOpenAIChatContent(IList<AIContent>
         return null;
     }
 
-    private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingChatCompletionAsync(
+    internal static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingChatCompletionAsync(
         IAsyncEnumerable<StreamingChatCompletionUpdate> updates,
         ChatCompletionOptions? options,
         [EnumeratorCancellation] CancellationToken cancellationToken)
diff --git a/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs b/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs
@@ -72,7 +72,7 @@ public async Task<ChatResponse> GetResponseAsync(
         _ = Throw.IfNull(messages);
 
         // Convert the inputs into what OpenAIResponseClient expects.
-        var openAIResponseItems = ToOpenAIResponseItems(messages);
+        var openAIResponseItems = ToOpenAIResponseItems(messages, options);
         var openAIOptions = ToOpenAIResponseCreationOptions(options);
 
         // Make the call to the OpenAIResponseClient.
@@ -147,6 +147,15 @@ internal static ChatResponse FromOpenAIResponse(OpenAIResponse openAIResponse, R
                         message.Contents.Add(fcc);
                         break;
 
+                    case FunctionCallOutputResponseItem functionCallOutput:
+                        message.Contents.Add(new FunctionResultContent(
+                            functionCallOutput.CallId,
+                            functionCallOutput.FunctionOutput)
+                        {
+                            RawRepresentation = outputItem,
+                        });
+                        break;
+
                     default:
                         message.Contents.Add(new()
                         {
@@ -166,16 +175,22 @@ internal static ChatResponse FromOpenAIResponse(OpenAIResponse openAIResponse, R
     }
 
     /// <inheritdoc />
-    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
-        IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
     {
         _ = Throw.IfNull(messages);
 
-        // Convert the inputs into what OpenAIResponseClient expects.
-        var openAIResponseItems = ToOpenAIResponseItems(messages);
+        var openAIResponseItems = ToOpenAIResponseItems(messages, options);
         var openAIOptions = ToOpenAIResponseCreationOptions(options);
 
-        // Make the call to the OpenAIResponseClient and process the streaming results.
+        var streamingUpdates = _responseClient.CreateResponseStreamingAsync(openAIResponseItems, openAIOptions, cancellationToken);
+
+        return FromOpenAIStreamingResponseUpdatesAsync(streamingUpdates, openAIOptions, cancellationToken);
+    }
+
+    internal static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingResponseUpdatesAsync(
+        IAsyncEnumerable<StreamingResponseUpdate> streamingResponseUpdates, ResponseCreationOptions? options, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
         DateTimeOffset? createdAt = null;
         string? responseId = null;
         string? conversationId = null;
@@ -184,14 +199,15 @@ public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         ChatRole? lastRole = null;
         Dictionary<int, MessageResponseItem> outputIndexToMessages = [];
         Dictionary<int, FunctionCallInfo>? functionCallInfos = null;
-        await foreach (var streamingUpdate in _responseClient.CreateResponseStreamingAsync(openAIResponseItems, openAIOptions, cancellationToken).ConfigureAwait(false))
+
+        await foreach (var streamingUpdate in streamingResponseUpdates.WithCancellation(cancellationToken).ConfigureAwait(false))
         {
             switch (streamingUpdate)
             {
                 case StreamingResponseCreatedUpdate createdUpdate:
                     createdAt = createdUpdate.Response.CreatedAt;
                     responseId = createdUpdate.Response.Id;
-                    conversationId = openAIOptions.StoredOutputEnabled is false ? null : responseId;
+                    conversationId = options?.StoredOutputEnabled is false ? null : responseId;
                     modelId = createdUpdate.Response.Model;
                     goto default;
 
@@ -478,8 +494,10 @@ private ResponseCreationOptions ToOpenAIResponseCreationOptions(ChatOptions? opt
     }
 
     /// <summary>Convert a sequence of <see cref="ChatMessage"/>s to <see cref="ResponseItem"/>s.</summary>
-    internal static IEnumerable<ResponseItem> ToOpenAIResponseItems(IEnumerable<ChatMessage> inputs)
+    internal static IEnumerable<ResponseItem> ToOpenAIResponseItems(IEnumerable<ChatMessage> inputs, ChatOptions? options)
     {
+        _ = options; // currently unused
+
         foreach (ChatMessage input in inputs)
         {
             if (input.Role == ChatRole.System ||
diff --git a/test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIConversionTests.cs b/test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIConversionTests.cs
@@ -6,6 +6,7 @@
 using System.ComponentModel;
 using System.Linq;
 using System.Text.Json;
+using System.Threading.Tasks;
 using OpenAI.Assistants;
 using OpenAI.Chat;
 using OpenAI.Realtime;
@@ -77,8 +78,10 @@ private static void ValidateSchemaParameters(BinaryData parameters)
         Assert.Equal("The name parameter", nameProperty.GetProperty("description").GetString());
     }
 
-    [Fact]
-    public void AsOpenAIChatMessages_ProducesExpectedOutput()
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public void AsOpenAIChatMessages_ProducesExpectedOutput(bool withOptions)
     {
         Assert.Throws<ArgumentNullException>("messages", () => ((IEnumerable<ChatMessage>)null!).AsOpenAIChatMessages());
 
@@ -99,17 +102,31 @@ public void AsOpenAIChatMessages_ProducesExpectedOutput()
             new(ChatRole.Assistant, "The answer is 42."),
         ];
 
-        var convertedMessages = messages.AsOpenAIChatMessages().ToArray();
+        ChatOptions? options = withOptions ? new ChatOptions { Instructions = "You talk like a parrot." } : null;
+
+        var convertedMessages = messages.AsOpenAIChatMessages(options).ToArray();
 
-        Assert.Equal(5, convertedMessages.Length);
+        int index = 0;
+        if (withOptions)
+        {
+            Assert.Equal(6, convertedMessages.Length);
+
+            index = 1;
+            SystemChatMessage instructionsMessage = Assert.IsType<SystemChatMessage>(convertedMessages[0]);
+            Assert.Equal("You talk like a parrot.", Assert.Single(instructionsMessage.Content).Text);
+        }
+        else
+        {
+            Assert.Equal(5, convertedMessages.Length);
+        }
 
-        SystemChatMessage m0 = Assert.IsType<SystemChatMessage>(convertedMessages[0]);
+        SystemChatMessage m0 = Assert.IsType<SystemChatMessage>(convertedMessages[index]);
         Assert.Equal("You are a helpful assistant.", Assert.Single(m0.Content).Text);
 
-        UserChatMessage m1 = Assert.IsType<UserChatMessage>(convertedMessages[1]);
+        UserChatMessage m1 = Assert.IsType<UserChatMessage>(convertedMessages[index + 1]);
         Assert.Equal("Hello", Assert.Single(m1.Content).Text);
 
-        AssistantChatMessage m2 = Assert.IsType<AssistantChatMessage>(convertedMessages[2]);
+        AssistantChatMessage m2 = Assert.IsType<AssistantChatMessage>(convertedMessages[index + 2]);
         Assert.Single(m2.Content);
         Assert.Equal("Hi there!", m2.Content[0].Text);
         var tc = Assert.Single(m2.ToolCalls);
@@ -121,11 +138,11 @@ public void AsOpenAIChatMessages_ProducesExpectedOutput()
             ["param2"] = 42
         }), JsonSerializer.Deserialize<JsonElement>(tc.FunctionArguments.ToMemory().Span)));
 
-        ToolChatMessage m3 = Assert.IsType<ToolChatMessage>(convertedMessages[3]);
+        ToolChatMessage m3 = Assert.IsType<ToolChatMessage>(convertedMessages[index + 3]);
         Assert.Equal("callid123", m3.ToolCallId);
         Assert.Equal("theresult", Assert.Single(m3.Content).Text);
 
-        AssistantChatMessage m4 = Assert.IsType<AssistantChatMessage>(convertedMessages[4]);
+        AssistantChatMessage m4 = Assert.IsType<AssistantChatMessage>(convertedMessages[index + 4]);
         Assert.Equal("The answer is 42.", Assert.Single(m4.Content).Text);
     }
 
@@ -216,4 +233,69 @@ public void AsChatResponse_ConvertsOpenAIChatCompletion()
         Assert.Equal("http://example.com/image.png", Assert.IsType<UriContent>(message.Contents[1]).Uri.ToString());
         Assert.Equal("functionName", Assert.IsType<FunctionCallContent>(message.Contents[2]).Name);
     }
+
+    [Fact]
+    public async Task AsChatResponse_ConvertsOpenAIStreamingChatCompletionUpdates()
+    {
+        Assert.Throws<ArgumentNullException>("chatCompletionUpdates", () => ((IAsyncEnumerable<StreamingChatCompletionUpdate>)null!).AsChatResponseUpdatesAsync());
+
+        List<ChatResponseUpdate> updates = [];
+        await foreach (var update in CreateUpdates().AsChatResponseUpdatesAsync())
+        {
+            updates.Add(update);
+        }
+
+        ChatResponse response = updates.ToChatResponse();
+
+        Assert.Equal("id", response.ResponseId);
+        Assert.Equal(ChatFinishReason.ToolCalls, response.FinishReason);
+        Assert.Equal("model123", response.ModelId);
+        Assert.Equal(new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero), response.CreatedAt);
+        Assert.NotNull(response.Usage);
+        Assert.Equal(1, response.Usage.InputTokenCount);
+        Assert.Equal(2, response.Usage.OutputTokenCount);
+        Assert.Equal(3, response.Usage.TotalTokenCount);
+
+        ChatMessage message = Assert.Single(response.Messages);
+        Assert.Equal(ChatRole.Assistant, message.Role);
+
+        Assert.Equal(3, message.Contents.Count);
+        Assert.Equal("Hello, world!", Assert.IsType<TextContent>(message.Contents[0]).Text);
+        Assert.Equal("http://example.com/image.png", Assert.IsType<UriContent>(message.Contents[1]).Uri.ToString());
+        Assert.Equal("functionName", Assert.IsType<FunctionCallContent>(message.Contents[2]).Name);
+
+        static async IAsyncEnumerable<StreamingChatCompletionUpdate> CreateUpdates()
+        {
+            await Task.Yield();
+            yield return OpenAIChatModelFactory.StreamingChatCompletionUpdate(
+                "id",
+                new ChatMessageContent(
+                    ChatMessageContentPart.CreateTextPart("Hello, world!"),
+                    ChatMessageContentPart.CreateImagePart(new Uri("http://example.com/image.png"))),
+                null,
+                [OpenAIChatModelFactory.StreamingChatToolCallUpdate(0, "id", ChatToolCallKind.Function, "functionName", BinaryData.FromString("test"))],
+                ChatMessageRole.Assistant,
+                null, null, null, OpenAI.Chat.ChatFinishReason.ToolCalls, new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero),
+                "model123", null, OpenAIChatModelFactory.ChatTokenUsage(2, 1, 3));
+        }
+    }
+
+    [Fact]
+    public void AsChatResponse_ConvertsOpenAIResponse()
+    {
+        Assert.Throws<ArgumentNullException>("response", () => ((OpenAIResponse)null!).AsChatResponse());
+
+        // The OpenAI library currently doesn't provide any way to create an OpenAIResponse instance,
+        // as all constructors/factory methods currently are internal. Update this test when such functionality is available.
+    }
+
+    [Fact]
+    public void AsChatResponseUpdatesAsync_ConvertsOpenAIStreamingResponseUpdates()
+    {
+        Assert.Throws<ArgumentNullException>("responseUpdates", () => ((IAsyncEnumerable<StreamingResponseUpdate>)null!).AsChatResponseUpdatesAsync());
+
+        // The OpenAI library currently doesn't provide any way to create a StreamingResponseUpdate instance,
+        // as all constructors/factory methods currently are internal. Update this test when such functionality is available.
+    }
+
 }

Original file line number	Diff line number	Diff line change
`@@ -289,7 +289,7 @@ private static List<ChatMessageContentPart> ToOpenAIChatContent(IList<AIContent>`
`289`	`289`	`return null;`
`290`	`290`	`}`
`291`	`291`
`292`		`- private static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingChatCompletionAsync(`
	`292`	`+ internal static async IAsyncEnumerable<ChatResponseUpdate> FromOpenAIStreamingChatCompletionAsync(`
`293`	`293`	`IAsyncEnumerable<StreamingChatCompletionUpdate> updates,`
`294`	`294`	`ChatCompletionOptions? options,`
`295`	`295`	`[EnumeratorCancellation] CancellationToken cancellationToken)`