.NET: [Breaking] Structured Output improvements (#3761)

* .NET: Delete AgentResponse.{Try}Deserialize<T> methods (#3518) * delete deserialize method of agent response * order usings * Update dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/AGUIClientServer/AGUIDojoServer/SharedState/SharedStateAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * .NET:[Breaking] Add support for structured output (#3658) * add support for so * restore lost xml comment part * fix using ordering * Update dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentStructuredOutput.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentStructuredOutput.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_SO_WithFormatResponseTests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * addressw pr review comments * address pr review feedback * address pr review comments * fix compilation issues after the latest merge with main * remove unnecessry options * remove RunAsync<object> methods * address code review feedback * address pr review feedback * make copy constructor protected * address pr review feedback --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * .NET: Add decorator for structured output support (#3694) * add decorator that adds structured output support to agents that don't natively support it. * Update dotnet/src/Microsoft.Agents.AI/StructuredOutput/StructuredOutputAgentResponse.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * Update dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * address pr review feedback --------- Co-authored-by: westey <164392973+westey-m@users.noreply.github.com> * .NET: Support primitives and arrays for SO (#3696) * wrap primitives and arrays * fix file encoding * address review comments * add adr * add missed change * fix compilation issue * address review comments * rename adr file name * reflect decision to have SO decorator as a reference implementation in samples * .NET: Move SO agent to samples (#3820) * move SO agent to samples * change file encoding * fix files encoding * .NET: Preserve caller context (#3803) * fix stuck orchestration * add previously removed RunAsync<T> method to DurableAIAgent * suppress IDE0005 warning * update changelog and remove unused constructor of AgentResponse<T> * updatge the changelog * address PR review feedback * .NET: Disable irrelevant integration test (#3913) * disable irrelevant integration test * Update dotnet/tests/AzureAI.IntegrationTests/AIProjectClientAgentStructuredOutputRunTests.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * forgotten change * address pr review feedback * disable intermittently failing integration test. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-02-13 17:03:51 +00:00
parent 3168eb4870
commit 9506fb28f6
50 changed files with 2751 additions and 594 deletions
@@ -13,6 +13,7 @@
 - Introduce Core method pattern for Session management methods on AIAgent ([#3699](https://github.com/microsoft/agent-framework/pull/3699))
 - Changed AIAgent.SerializeSession to AIAgent.SerializeSessionAsync ([#3879](https://github.com/microsoft/agent-framework/pull/3879))
 - Changed ChatHistory and AIContext Providers to have pipeline semantics ([#3806](https://github.com/microsoft/agent-framework/pull/3806))
+- Marked all `RunAsync<T>` overloads as `new`, added missing ones, and added support for primitives and arrays ([#3803](https://github.com/microsoft/agent-framework/pull/3803))

 ## v1.0.0-preview.251204.1

@@ -1,12 +1,11 @@
 // Copyright (c) Microsoft. All rights reserved.

-using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Text.Json;
-using System.Text.Json.Serialization.Metadata;
 using Microsoft.DurableTask;
 using Microsoft.DurableTask.Entities;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI.DurableTask;

@@ -114,7 +113,6 @@ public sealed class DurableAIAgent : AIAgent
        {
            enableToolCalls = durableOptions.EnableToolCalls;
            enableToolNames = durableOptions.EnableToolNames;
-            responseFormat = durableOptions.ResponseFormat;
        }
        else if (options is ChatClientAgentRunOptions chatClientOptions && chatClientOptions.ChatOptions?.Tools != null)
        {
@@ -122,6 +120,12 @@ public sealed class DurableAIAgent : AIAgent
            responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
        }

+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
        RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames)
        {
            OrchestrationId = this._context.InstanceId
@@ -168,108 +172,125 @@ public sealed class DurableAIAgent : AIAgent
    }

    /// <summary>
-    /// Runs the agent with a message and returns the deserialized output as an instance of <typeparamref name="T"/>.
+    /// Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type <typeparamref name="T"/>.
    /// </summary>
-    /// <param name="message">The message to send to the agent.</param>
-    /// <param name="session">The agent session to use.</param>
-    /// <param name="serializerOptions">Optional JSON serializer options.</param>
-    /// <param name="options">Optional run options.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    /// <typeparam name="T">The type of the output.</typeparam>
-    /// <exception cref="ArgumentException">
-    /// Thrown when the provided <paramref name="options"/> already contains a response schema.
-    /// Thrown when the provided <paramref name="options"/> is not a <see cref="DurableAgentRunOptions"/>.
-    /// </exception>
-    /// <exception cref="InvalidOperationException">
-    /// Thrown when the agent response is empty or cannot be deserialized.
-    /// </exception>
-    /// <returns>The output from the agent.</returns>
-    public async Task<AgentResponse<T>> RunAsync<T>(
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// This method is specific to durable agents because the Durable Task Framework uses a custom
+    /// synchronization context for orchestration execution, and all continuations must run on the
+    /// orchestration thread to avoid breaking the durable orchestration and potential deadlocks.
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default) =>
+        this.RunAsync<T>([], session, serializerOptions, options, cancellationToken);
+
+    /// <summary>
+    /// Runs the agent with a text message from the user, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The user message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentException"><paramref name="message"/> is <see langword="null"/>, empty, or contains only whitespace.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
        string message,
        AgentSession? session = null,
        JsonSerializerOptions? serializerOptions = null,
        AgentRunOptions? options = null,
        CancellationToken cancellationToken = default)
    {
-        return await this.RunAsync<T>(
-            messages: [new ChatMessage(ChatRole.User, message) { CreatedAt = DateTimeOffset.UtcNow }],
-            session,
-            serializerOptions,
-            options,
-            cancellationToken);
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>(new ChatMessage(ChatRole.User, message), session, serializerOptions, options, cancellationToken);
    }

    /// <summary>
-    /// Runs the agent with messages and returns the deserialized output as an instance of <typeparamref name="T"/>.
+    /// Runs the agent with a single chat message, requesting a response of the specified type <typeparamref name="T"/>.
    /// </summary>
-    /// <param name="messages">The messages to send to the agent.</param>
-    /// <param name="session">The agent session to use.</param>
-    /// <param name="serializerOptions">Optional JSON serializer options.</param>
-    /// <param name="options">Optional run options.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    /// <typeparam name="T">The type of the output.</typeparam>
-    /// <exception cref="ArgumentException">
-    /// Thrown when the provided <paramref name="options"/> already contains a response schema.
-    /// Thrown when the provided <paramref name="options"/> is not a <see cref="DurableAgentRunOptions"/>.
-    /// </exception>
-    /// <exception cref="InvalidOperationException">
-    /// Thrown when the agent response is empty or cannot be deserialized.
-    /// </exception>
-    /// <returns>The output from the agent.</returns>
-    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback to reflection-based deserialization is intentional for library flexibility with user-defined types.")]
-    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050", Justification = "Fallback to reflection-based deserialization is intentional for library flexibility with user-defined types.")]
-    public async Task<AgentResponse<T>> RunAsync<T>(
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The chat message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        ChatMessage message,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>([message], session, serializerOptions, options, cancellationToken);
+    }
+
+    /// <summary>
+    /// Runs the agent with a collection of chat messages, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="messages">The collection of messages to send to the agent for processing.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input messages and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new async Task<AgentResponse<T>> RunAsync<T>(
        IEnumerable<ChatMessage> messages,
        AgentSession? session = null,
        JsonSerializerOptions? serializerOptions = null,
        AgentRunOptions? options = null,
        CancellationToken cancellationToken = default)
    {
-        options ??= new DurableAgentRunOptions();
-        if (options is not DurableAgentRunOptions durableOptions)
-        {
-            throw new ArgumentException(
-                "Response schema is only supported with DurableAgentRunOptions when using durable agents. " +
-                "Cannot specify a response schema when calling RunAsync<T>.",
-                paramName: nameof(options));
-        }
+        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;

-        if (durableOptions.ResponseFormat is not null)
-        {
-            throw new ArgumentException(
-                "A response schema is already defined in the provided DurableAgentRunOptions. " +
-                "Cannot specify a response schema when calling RunAsync<T>.",
-                paramName: nameof(options));
-        }
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);

-        // Create the JSON schema for the response type
-        durableOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema<T>();
+        (responseFormat, bool isWrappedInObject) = StructuredOutputSchemaUtilities.WrapNonObjectSchema(responseFormat);

-        AgentResponse response = await this.RunAsync(messages, session, durableOptions, cancellationToken);
+        options = options?.Clone() ?? new DurableAgentRunOptions();
+        options.ResponseFormat = responseFormat;

-        // Deserialize the response text to the requested type
-        if (string.IsNullOrEmpty(response.Text))
-        {
-            throw new InvalidOperationException("Agent response is empty and cannot be deserialized.");
-        }
+        // ConfigureAwait(false) cannot be used here because the Durable Task Framework uses
+        // a custom synchronization context that requires all continuations to execute on the
+        // orchestration thread. Scheduling the continuation on an arbitrary thread would break
+        // the orchestration.
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken);

-        serializerOptions ??= DurableAgentJsonUtilities.DefaultOptions;
-
-        // Prefer source-generated metadata when available to support AOT/trimming scenarios.
-        // Fallback to reflection-based deserialization for types without source-generated metadata.
-        // This is necessary since T is a user-provided type that may not have [JsonSerializable] coverage.
-        JsonTypeInfo? typeInfo = serializerOptions.GetTypeInfo(typeof(T));
-        T? result = (typeInfo is JsonTypeInfo typedInfo
-            ? (T?)JsonSerializer.Deserialize(response.Text, typedInfo)
-            : JsonSerializer.Deserialize<T>(response.Text, serializerOptions))
-            ?? throw new InvalidOperationException($"Failed to deserialize agent response to type {typeof(T).Name}.");
-
-        return new DurableAIAgentResponse<T>(response, result);
-    }
-
-    private sealed class DurableAIAgentResponse<T>(AgentResponse response, T result)
-        : AgentResponse<T>(response.AsChatResponse())
-    {
-        public override T Result { get; } = result;
+        return new AgentResponse<T>(response, serializerOptions) { IsWrappedInObject = isWrappedInObject };
    }
 }
@@ -62,7 +62,6 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
        {
            enableToolCalls = durableOptions.EnableToolCalls;
            enableToolNames = durableOptions.EnableToolNames;
-            responseFormat = durableOptions.ResponseFormat;
            isFireAndForget = durableOptions.IsFireAndForget;
        }
        else if (options is ChatClientAgentRunOptions chatClientOptions)
@@ -71,6 +70,12 @@ internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient)
            responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
        }

+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
        RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames);
        AgentSessionId sessionId = durableSession.SessionId;

@@ -1,7 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.

-using Microsoft.Extensions.AI;
-
 namespace Microsoft.Agents.AI.DurableTask;

 /// <summary>
@@ -9,6 +7,25 @@ namespace Microsoft.Agents.AI.DurableTask;
 /// </summary>
 public sealed class DurableAgentRunOptions : AgentRunOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class.
+    /// </summary>
+    public DurableAgentRunOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class by copying values from the specified options.
+    /// </summary>
+    /// <param name="options">The options instance from which to copy values.</param>
+    private DurableAgentRunOptions(DurableAgentRunOptions options)
+        : base(options)
+    {
+        this.EnableToolCalls = options.EnableToolCalls;
+        this.EnableToolNames = options.EnableToolNames is not null ? new List<string>(options.EnableToolNames) : null;
+        this.IsFireAndForget = options.IsFireAndForget;
+    }
+
    /// <summary>
    /// Gets or sets whether to enable tool calls for this request.
    /// </summary>
@@ -19,11 +36,6 @@ public sealed class DurableAgentRunOptions : AgentRunOptions
    /// </summary>
    public IList<string>? EnableToolNames { get; set; }

-    /// <summary>
-    /// Gets or sets the response format for the agent's response.
-    /// </summary>
-    public ChatResponseFormat? ResponseFormat { get; set; }
-
    /// <summary>
    /// Gets or sets whether to fire and forget the agent run request.
    /// </summary>
@@ -33,4 +45,7 @@ public sealed class DurableAgentRunOptions : AgentRunOptions
    /// long-running tasks where the caller does not need to wait for the agent to complete the run.
    /// </remarks>
    public bool IsFireAndForget { get; set; }
+
+    /// <inheritdoc/>
+    public override AgentRunOptions Clone() => new DurableAgentRunOptions(this);
 }
@@ -17,6 +17,11 @@
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>

+  <PropertyGroup>
+    <InjectSharedThrow>true</InjectSharedThrow>
+    <InjectSharedStructuredOutput>true</InjectSharedStructuredOutput>
+  </PropertyGroup>
+  
  <!-- Durable Task dependencies -->
  <ItemGroup>
    <PackageReference Include="Microsoft.DurableTask.Client" />