add support for background responses

src/Libraries/.editorconfig

@@ -2936,7 +2936,7 @@ dotnet_diagnostic.S103.severity = suggestion
 # Title    : Files should not have too many lines of code
 # Category : Major Code Smell
 # Help Link: https://rules.sonarsource.com/csharp/RSPEC-104
-dotnet_diagnostic.S104.severity = warning
+dotnet_diagnostic.S104.severity = none
 
 # Title    : Finalizers should not throw exceptions
 # Category : Blocker Bug

src/Libraries/Microsoft.Extensions.AI.Abstractions/BackgroundResponsesOptions.cs

@@ -0,0 +1,35 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Options for configuring background responses.</summary>
+[Experimental("MEAI001")]
+public sealed class BackgroundResponsesOptions
+{
+    /// <summary>Gets or sets a value indicating whether the background responses are allowed.</summary>
+    /// <remarks>
+    /// <para>
+    /// Background responses allow running long-running operations or tasks asynchronously in the background that can be resumed by streaming APIs
+    /// and polled for completion by non-streaming APIs.
+    /// </para>
+    /// <para>
+    /// When this property is set to true, non-streaming APIs start a background operation and return an initial
+    /// response with a continuation token. Subsequent calls to the same API should be made in a polling manner with
+    /// the continuation token to get the final result of the operation.
+    /// </para>
+    /// <para>
+    /// When this property is set to true, streaming APIs also start a background operation and begin streaming
+    /// response updates until the operation is completed. If the streaming connection is interrupted, the
+    /// continuation token obtained from the last update should be supplied to a subsequent call to the same streaming API
+    /// to resume the stream from the point of interruption and continue receiving updates until the operation is completed.
+    /// </para>
+    /// <para>
+    /// This property only takes effect if the API it's used with supports background responses.
+    /// If the API does not support background responses, this property will be ignored.
+    /// </para>
+    /// </remarks>
+    public bool? Allow { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/CHANGELOG.md

@@ -5,6 +5,11 @@
 - Added protected copy constructors to options types (e.g. `ChatOptions`).
 - Fixed `EmbeddingGeneratorOptions`/`SpeechToTextOptions` `Clone` methods to correctly copy all properties.
 - Fixed `ToChatResponse` to not overwrite `ChatMessage/ChatResponse.CreatedAt` with older timestamps during coalescing. 
+- Added `[Experimental]` `ResponseContinuationToken` to represent a base class for continuation tokens.
+- Added `[Experimental]` `BackgroundResponsesOptions` to represent options for background responses.
+- Added `[Experimental]` `ChatOptions.BackgroundResponsesOptions` and `ChatOptions.ContinuationToken` properties to accept options for background responses and continuation token.
+- Added `[Experimental]` `ChatResponse.ContinuationToken` and `ChatResponseUpdate.ContinuationToken` to return continuation token for background responses.
+- Added `[Experimental]` `GetResponseAsync` and `GetStreamingResponseAsync` extension methods for `IChatClient` to continue background responses.
 
 ## 9.9.1
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatClientExtensions.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Shared.Diagnostics;
@@ -120,6 +121,34 @@ public static Task<ChatResponse> GetResponseAsync(
         return client.GetResponseAsync([chatMessage], options, cancellationToken);
     }
 
+    /// <summary>Gets a background response identified by the specified continuation token.</summary>
+    /// <param name="client">The chat client.</param>
+    /// <param name="continuationToken">The continuation token.</param>
+    /// <param name="options">The chat options to configure the request.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The background response.</returns>
+    /// <remarks>
+    /// The options provided should be the same as those used to start the background operation.
+    /// Using different options is not supported and may lead to unexpected results.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="continuationToken"/> is <see langword="null"/>.</exception>
+    [Experimental("MEAI001")]
+    public static Task<ChatResponse> GetResponseAsync(
+        this IChatClient client,
+        ResponseContinuationToken continuationToken,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(continuationToken);
+
+        ChatOptions chatOptions = options?.Clone() ?? new();
+        chatOptions.ContinuationToken = continuationToken;
+
+        return client.GetResponseAsync([], chatOptions, cancellationToken);
+    }
+
     /// <summary>Sends a user chat text message and streams the response messages.</summary>
     /// <param name="client">The chat client.</param>
     /// <param name="chatMessage">The text content for the chat message to send.</param>
@@ -159,4 +188,28 @@ public static IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
 
         return client.GetStreamingResponseAsync([chatMessage], options, cancellationToken);
     }
+
+    /// <summary>Gets a background streamed response identified by the specified continuation token and streams its messages.</summary>
+    /// <param name="client">The chat client.</param>
+    /// <param name="continuationToken">The continuation token.</param>
+    /// <param name="options">The chat options to configure the request.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The background response messages.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="continuationToken"/> is <see langword="null"/>.</exception>
+    [Experimental("MEAI001")]
+    public static IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        this IChatClient client,
+        ResponseContinuationToken continuationToken,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(client);
+        _ = Throw.IfNull(continuationToken);
+
+        ChatOptions chatOptions = options?.Clone() ?? new();
+        chatOptions.ContinuationToken = continuationToken;
+
+        return client.GetStreamingResponseAsync([], chatOptions, cancellationToken);
+    }
 }

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 
 namespace Microsoft.Extensions.AI;
@@ -27,6 +28,7 @@ protected ChatOptions(ChatOptions? other)
         AdditionalProperties = other.AdditionalProperties?.Clone();
         AllowMultipleToolCalls = other.AllowMultipleToolCalls;
         ConversationId = other.ConversationId;
+        ContinuationToken = other.ContinuationToken;
         FrequencyPenalty = other.FrequencyPenalty;
         Instructions = other.Instructions;
         MaxOutputTokens = other.MaxOutputTokens;
@@ -49,6 +51,14 @@ protected ChatOptions(ChatOptions? other)
         {
             Tools = [.. other.Tools];
         }
+
+        if (other.BackgroundResponsesOptions is not null)
+        {
+            BackgroundResponsesOptions = new BackgroundResponsesOptions
+            {
+                Allow = other.BackgroundResponsesOptions.Allow
+            };
+        }
     }
 
     /// <summary>Gets or sets an optional identifier used to associate a request with an existing conversation.</summary>
@@ -155,6 +165,26 @@ protected ChatOptions(ChatOptions? other)
     [JsonIgnore]
     public IList<AITool>? Tools { get; set; }
 
+    /// <summary>Gets or sets the options for configuring background responses.</summary>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public BackgroundResponsesOptions? BackgroundResponsesOptions { get; set; }
+
+    /// <summary>Gets or sets the continuation token for resuming and getting the result of the chat response identified by this token.</summary>
+    /// <remarks>
+    /// This property is used for background responses that can be activated via the <see cref="BackgroundResponsesOptions.Allow"/>
+    /// property if the <see cref="IChatClient"/> implementation supports them.
+    /// Streamed background responses, such as those returned by default by <see cref="IChatClient.GetStreamingResponseAsync"/>,
+    /// can be resumed if interrupted. This means that a continuation token obtained from the <see cref="ChatResponseUpdate.ContinuationToken"/> 
+    /// of an update just before the interruption occurred can be passed to this property to resume the stream from the point of interruption.
+    /// Non-streamed background responses, such as those returned by <see cref="IChatClient.GetResponseAsync"/>,
+    /// can be polled for completion by obtaining the token from the <see cref="ChatResponse.ContinuationToken"/> property 
+    /// and passing it to this property on subsequent calls to <see cref="IChatClient.GetResponseAsync"/>.
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public ResponseContinuationToken? ContinuationToken { get; set; }
+
     /// <summary>
     /// Gets or sets a callback responsible for creating the raw representation of the chat options from an underlying implementation.
     /// </summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs

@@ -88,6 +88,22 @@ public IList<ChatMessage> Messages
     /// <summary>Gets or sets usage details for the chat response.</summary>
     public UsageDetails? Usage { get; set; }
 
+    /// <summary>Gets or sets the continuation token for getting result of the background chat response.</summary>
+    /// <remarks>
+    /// <see cref="IChatClient"/> implementations that support background responses will return
+    /// a continuation token if background responses are allowed in <see cref="ChatOptions.BackgroundResponsesOptions"/>
+    /// and the result of the response has not been obtained yet. Otherwise, the token will be <see langword="null"/>.
+    /// <para>
+    /// This property should be used in conjunction with <see cref="ChatOptions.ContinuationToken"/> to 
+    /// continue to poll for the completion of the response. Pass this token to
+    /// <see cref="ChatOptions.ContinuationToken"/> on subsequent calls to <see cref="IChatClient.GetResponseAsync"/>
+    /// to poll for completion.
+    /// </para>
+    /// </remarks>
+    [Experimental("MEAI001")]
+    [JsonIgnore]
+    public ResponseContinuationToken? ContinuationToken { get; set; }
+
     /// <summary>Gets or sets the raw representation of the chat response from an underlying implementation.</summary>
     /// <remarks>
     /// If a <see cref="ChatResponse"/> is created to represent some underlying object from another object
@@ -143,6 +159,7 @@ public ChatResponseUpdate[] ToChatResponseUpdates()
                 ResponseId = ResponseId,
 
                 CreatedAt = message.CreatedAt ?? CreatedAt,
+                ContinuationToken = ContinuationToken,
             };
         }
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs

@@ -136,6 +136,21 @@ public IList<AIContent> Contents
     /// <inheritdoc/>
     public override string ToString() => Text;
 
+    /// <summary>Gets or sets the continuation token for resuming the streamed chat response of which this update is a part.</summary>
+    /// <remarks>
+    /// <see cref="IChatClient"/> implementations that support background responses will return
+    /// a continuation token on each update if background responses are enabled in <see cref="ChatOptions.BackgroundResponsesOptions"/>
+    /// and not all updates for the response have been streamed yet. Otherwise, the token will be <see langword="null"/>.
+    /// <para>
+    /// This property should be used for stream resumption, where the continuation token of the latest received update should be
+    /// passed to <see cref="ChatOptions.ContinuationToken"/> on subsequent calls to <see cref="IChatClient.GetStreamingResponseAsync"/>
+    /// to resume streaming from the point of interruption.
+    /// </para>
+    /// </remarks>
+    [JsonIgnore]
+    [Experimental("MEAI001")]
+    public ResponseContinuationToken? ContinuationToken { get; set; }
+
     /// <summary>Gets a <see cref="AIContent"/> object to display in the debugger display.</summary>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private AIContent? ContentForDebuggerDisplay