.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
@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable IDE0005 // Using directive is unnecessary.
+
+using System;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Internal utilities for working with structured output JSON schemas.
+/// </summary>
+internal static class StructuredOutputSchemaUtilities
+{
+    private const string DataPropertyName = "data";
+
+    /// <summary>
+    /// Ensures the given response format has an object schema at the root, wrapping non-object schemas if necessary.
+    /// </summary>
+    /// <param name="responseFormat">The response format to check.</param>
+    /// <returns>A tuple containing the (possibly wrapped) response format and whether wrapping occurred.</returns>
+    /// <exception cref="InvalidOperationException">The response format does not have a valid JSON schema.</exception>
+    internal static (ChatResponseFormatJson ResponseFormat, bool IsWrappedInObject) WrapNonObjectSchema(ChatResponseFormatJson responseFormat)
+    {
+        if (responseFormat.Schema is null)
+        {
+            throw new InvalidOperationException("The response format must have a valid JSON schema.");
+        }
+
+        var schema = responseFormat.Schema.Value;
+        bool isWrappedInObject = false;
+
+        if (!SchemaRepresentsObject(responseFormat.Schema))
+        {
+            // For non-object-representing schemas, we wrap them in an object schema, because all
+            // the real LLM providers today require an object schema as the root. This is currently
+            // true even for providers that support native structured output.
+            isWrappedInObject = true;
+            schema = JsonSerializer.SerializeToElement(new JsonObject
+            {
+                { "$schema", "https://json-schema.org/draft/2020-12/schema" },
+                { "type", "object" },
+                { "properties", new JsonObject { { DataPropertyName, JsonElementToJsonNode(schema) } } },
+                { "additionalProperties", false },
+                { "required", new JsonArray(DataPropertyName) },
+            }, AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(JsonObject)));
+
+            responseFormat = ChatResponseFormat.ForJsonSchema(schema, responseFormat.SchemaName, responseFormat.SchemaDescription);
+        }
+
+        return (responseFormat, isWrappedInObject);
+    }
+
+    /// <summary>
+    /// Unwraps the <c>"data"</c> property from a JSON object that was previously wrapped by <see cref="WrapNonObjectSchema"/>.
+    /// </summary>
+    /// <param name="json">The JSON string to unwrap.</param>
+    /// <returns>The raw JSON text of the <c>"data"</c> property, or the original JSON if no wrapping is detected.</returns>
+    internal static string UnwrapResponseData(string json)
+    {
+        using var document = JsonDocument.Parse(json);
+        if (document.RootElement.ValueKind == JsonValueKind.Object &&
+            document.RootElement.TryGetProperty(DataPropertyName, out JsonElement dataElement))
+        {
+            return dataElement.GetRawText();
+        }
+
+        // If root is not an object or "data" property is not found, return the original JSON as a fallback
+        return json;
+    }
+
+    private static bool SchemaRepresentsObject(JsonElement? schema)
+    {
+        if (schema is not { } schemaElement)
+        {
+            return false;
+        }
+
+        if (schemaElement.ValueKind is JsonValueKind.Object)
+        {
+            foreach (var property in schemaElement.EnumerateObject())
+            {
+                if (property.NameEquals("type"u8))
+                {
+                    return property.Value.ValueKind == JsonValueKind.String
+                        && property.Value.ValueEquals("object"u8);
+                }
+            }
+        }
+
+        return false;
+    }
+
+    private static JsonNode? JsonElementToJsonNode(JsonElement element) =>
+        element.ValueKind switch
+        {
+            JsonValueKind.Null => null,
+            JsonValueKind.Array => JsonArray.Create(element),
+            JsonValueKind.Object => JsonObject.Create(element),
+            _ => JsonValue.Create(element)
+        };
+}