.NET: Add support for background responses

docs/design/python-package-setup.md

@@ -175,7 +175,7 @@ Sub-packages are comprised of two parts, the code itself and the dependencies, t
 - Subpackage naming should also follow this, so in principle a package name is `<vendor/folder>-<feature/brand>`, so `google-gemini`, `azure-purview`, `microsoft-copilotstudio`, etc. For smaller vendors, where it's less likely to have a multitude of connectors, we can skip the feature/brand part, so `mem0`, `redis`, etc.
 - For Microsoft services we will have two vendor folders, `azure` and `microsoft`, where `azure` contains all Azure services, while `microsoft` contains other Microsoft services, such as Copilot Studio Agents.
 
-This setup was discussed at length and the decision is captured in [ADR-0007](../decisions/0007-python-subpackages.md).
+This setup was discussed at length and the decision is captured in [ADR-0008](../decisions/0008-python-subpackages.md).
 
 #### Evolving the package structure
 For each of the advanced components, we have two reason why we may split them into a folder, with an `__init__.py` and optionally a `_files.py`:

dotnet/agent-framework-dotnet.slnx

@@ -57,6 +57,7 @@
     <Project Path="samples/GettingStarted/Agents/Agent_Step14_Middleware/Agent_Step14_Middleware.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
     <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
@@ -162,8 +163,14 @@
   <Folder Name="/Solution Items/docs/" />
   <Folder Name="/Solution Items/docs/decisions/">
     <File Path="../docs/decisions/0001-agent-run-response.md" />
-    <File Path="../docs/decisions/0001-agent-tools.md" />
-    <File Path="../docs/decisions/0002-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0002-agent-tools.md" />
+    <File Path="../docs/decisions/0003-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0004-foundry-sdk-extensions.md" />
+    <File Path="../docs/decisions/0005-python-naming-conventions.md" />
+    <File Path="../docs/decisions/0006-userapproval.md" />
+    <File Path="../docs/decisions/0007-agent-filtering-middleware.md" />
+    <File Path="../docs/decisions/0008-python-subpackages.md" />
+    <File Path="../docs/decisions/0009-support-long-running-operations.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />

dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use background responses with ChatClientAgent and OpenAI Responses.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+     .GetOpenAIResponseClient(deploymentName)
+     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
+
+// Enable background responses (only supported by OpenAI Responses at this time).
+AgentRunOptions options = new() { AllowBackgroundResponses = true };
+
+AgentThread thread = agent.GetNewThread();
+
+// Start the initial run.
+AgentRunResponse response = await agent.RunAsync("Tell me a joke about a pirate.", thread, options);
+
+// Poll until the response is complete.
+while (response.ContinuationToken is { } token)
+{
+    // Wait before polling again.
+    await Task.Delay(TimeSpan.FromSeconds(2));
+
+    // Continue with the token.
+    options.ContinuationToken = token;
+
+    response = await agent.RunAsync(thread, options);
+}
+
+// Display the result.
+Console.WriteLine(response.Text);
+
+// Reset options and thread for streaming.
+options = new() { AllowBackgroundResponses = true };
+thread = agent.GetNewThread();
+
+AgentRunResponseUpdate? lastReceivedUpdate = null;
+// Start streaming.
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync("Tell me a joke about a pirate.", thread, options))
+{
+    // Output each update.
+    Console.Write(update.Text);
+
+    // Track last update.
+    lastReceivedUpdate = update;
+
+    // Simulate connection loss after first piece of content received.
+    if (update.Text.Length > 0)
+    {
+        break;
+    }
+}
+
+// Resume from interruption point.
+options.ContinuationToken = lastReceivedUpdate?.ContinuationToken;
+
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(thread, options))
+{
+    // Output each update.
+    Console.Write(update.Text);
+}

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

@@ -0,0 +1,22 @@
+# What This Sample Shows
+
+This sample demonstrates how to use background responses with ChatCompletionAgent and OpenAI Responses for long-running operations. Background responses support:
+
+- **Polling for completion** - Non-streaming APIs can start a background operation and return a continuation token. Poll with the token until the response completes.
+- **Resuming after interruption** - Streaming APIs can be interrupted and resumed from the last update using the continuation token.
+
+> **Note:** Background responses are currently only supported by OpenAI Responses.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- OpenAI api key
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```

dotnet/samples/GettingStarted/Agents/README.md

@@ -42,6 +42,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Using middleware with an agent](./Agent_Step14_Middleware/)|This sample demonstrates how to use middleware with an agent|
 |[Using plugins with an agent](./Agent_Step15_Plugins/)|This sample demonstrates how to use plugins with an agent|
 |[Reducing chat history size](./Agent_Step16_ChatReduction/)|This sample demonstrates how to reduce the chat history to constrain its size, where chat history is maintained locally|
+|[Background responses](./Agent_Step17_BackgroundResponses/)|This sample demonstrates how to use background responses for long-running operations with polling and resumption support|
 
 ## Running the samples from the console
 

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

@@ -10,9 +10,6 @@ namespace Microsoft.Agents.AI;
 /// </summary>
 /// <remarks>
 /// <para>
-/// This class currently has no options, but may be extended in the future to include additional configuration settings.
-/// </para>
-/// <para>
 /// Implementations of <see cref="AIAgent"/> may provide subclasses of <see cref="AgentRunOptions"/> with additional options specific to that agent type.
 /// </para>
 /// </remarks>
@@ -33,5 +30,48 @@ public AgentRunOptions()
     public AgentRunOptions(AgentRunOptions options)
     {
         _ = Throw.IfNull(options);
+        this.ContinuationToken = options.ContinuationToken;
+        this.AllowBackgroundResponses = options.AllowBackgroundResponses;
     }
+
+    /// <summary>
+    /// Gets or sets the continuation token for resuming and getting the result of the agent response identified by this token.
+    /// </summary>
+    /// <remarks>
+    /// This property is used for background responses that can be activated via the <see cref="AllowBackgroundResponses"/>
+    /// property if the <see cref="AIAgent"/> implementation supports them.
+    /// Streamed background responses, such as those returned by default by <see cref="AIAgent.RunStreamingAsync(AgentThread?, AgentRunOptions?, System.Threading.CancellationToken)"/>
+    /// can be resumed if interrupted. This means that a continuation token obtained from the <see cref="AgentRunResponseUpdate.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="AIAgent.RunAsync(AgentThread?, AgentRunOptions?, System.Threading.CancellationToken)"/>,
+    /// can be polled for completion by obtaining the token from the <see cref="AgentRunResponse.ContinuationToken"/> property
+    /// and passing it via this property on subsequent calls to <see cref="AIAgent.RunAsync(AgentThread?, AgentRunOptions?, System.Threading.CancellationToken)"/>.
+    /// </remarks>
+    public object? ContinuationToken { get; set; }
+
+    /// <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 may 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 may 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 that has one 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 implementation it's used with supports background responses.
+    /// If the implementation does not support background responses, this property will be ignored.
+    /// </para>
+    /// </remarks>
+    public bool? AllowBackgroundResponses { get; set; }
 }

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

@@ -74,6 +74,7 @@ public AgentRunResponse(ChatResponse response)
         this.RawRepresentation = response;
         this.ResponseId = response.ResponseId;
         this.Usage = response.Usage;
+        this.ContinuationToken = response.ContinuationToken;
     }
 
     /// <summary>
@@ -159,6 +160,23 @@ public IList<ChatMessage> Messages
     /// </value>
     public string? ResponseId { get; set; }
 
+    /// <summary>
+    /// Gets or sets the continuation token for getting the result of a background agent response.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="AIAgent"/> implementations that support background responses will return
+    /// a continuation token if background responses are allowed in <see cref="AgentRunOptions.AllowBackgroundResponses"/>
+    /// and the result of the response has not been obtained yet. If the response has completed and the result has been obtained,
+    /// the token will be <see langword="null"/>.
+    /// <para>
+    /// This property should be used in conjunction with <see cref="AgentRunOptions.ContinuationToken"/> to
+    /// continue to poll for the completion of the response. Pass this token to
+    /// <see cref="AgentRunOptions.ContinuationToken"/> on subsequent calls to <see cref="AIAgent.RunAsync(AgentThread?, AgentRunOptions?, System.Threading.CancellationToken)"/>
+    /// to poll for completion.
+    /// </para>
+    /// </remarks>
+    public object? ContinuationToken { get; set; }
+
     /// <summary>
     /// Gets or sets the timestamp indicating when this response was created.
     /// </summary>
@@ -234,7 +252,7 @@ public AgentRunResponseUpdate[] ToAgentRunResponseUpdates()
         {
             extra = new AgentRunResponseUpdate
             {
-                AdditionalProperties = this.AdditionalProperties
+                AdditionalProperties = this.AdditionalProperties,
             };
 
             if (this.Usage is { } usage)

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

@@ -42,6 +42,7 @@ response.RawRepresentation as ChatResponse ??
                 RawRepresentation = response,
                 ResponseId = response.ResponseId,
                 Usage = response.Usage,
+                ContinuationToken = response.ContinuationToken,
             };
     }
 
@@ -74,6 +75,7 @@ responseUpdate.RawRepresentation as ChatResponseUpdate ??
                 RawRepresentation = responseUpdate,
                 ResponseId = responseUpdate.ResponseId,
                 Role = responseUpdate.Role,
+                ContinuationToken = responseUpdate.ContinuationToken,
             };
     }
 

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

@@ -78,6 +78,7 @@ public AgentRunResponseUpdate(ChatResponseUpdate chatResponseUpdate)
         this.RawRepresentation = chatResponseUpdate;
         this.ResponseId = chatResponseUpdate.ResponseId;
         this.Role = chatResponseUpdate.Role;
+        this.ContinuationToken = chatResponseUpdate.ContinuationToken;
     }
 
     /// <summary>Gets or sets the name of the author of the response update.</summary>
@@ -148,6 +149,21 @@ public IList<AIContent> Contents
     /// <summary>Gets or sets a timestamp for the response update.</summary>
     public DateTimeOffset? CreatedAt { get; set; }
 
+    /// <summary>
+    /// Gets or sets the continuation token for resuming the streamed agent response of which this update is a part.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="AIAgent"/> implementations that support background responses will return
+    /// a continuation token on each update if background responses are allowed in <see cref="AgentRunOptions.AllowBackgroundResponses"/>
+    /// except for the last update, for which 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="AgentRunOptions.ContinuationToken"/> on subsequent calls to <see cref="AIAgent.RunStreamingAsync(AgentThread?, AgentRunOptions?, System.Threading.CancellationToken)"/>
+    /// to resume streaming from the point of interruption.
+    /// </para>
+    /// </remarks>
+    public object? ContinuationToken { get; set; }
+
     /// <inheritdoc/>
     public override string ToString() => this.Text;