chore: import upstream snapshot with attribution

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/Program.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.Extensions.Options;
+using OpenAI.Chat;
+using RecipeAssistant;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options =>
+    options.SerializerOptions.TypeInfoResolverChain.Add(RecipeSerializerContext.Default));
+builder.Services.AddAGUIServer();
+
+// Configure to listen on port 8888
+builder.WebHost.UseUrls("http://localhost:8888");
+
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
+WebApplication app = builder.Build();
+
+string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+// Get JsonSerializerOptions
+var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;
+
+// Create base agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+AIAgent baseAgent = chatClient.AsAIAgent(
+    name: "RecipeAgent",
+    instructions: """
+        You are a helpful recipe assistant. When users ask you to create or suggest a recipe,
+        respond with a complete AgentState JSON object that includes:
+        - recipe.title: The recipe name
+        - recipe.cuisine: Type of cuisine (e.g., Italian, Mexican, Japanese)
+        - recipe.ingredients: Array of ingredient strings with quantities
+        - recipe.steps: Array of cooking instruction strings
+        - recipe.prep_time_minutes: Preparation time in minutes
+        - recipe.cook_time_minutes: Cooking time in minutes
+        - recipe.skill_level: One of "beginner", "intermediate", or "advanced"
+
+        Always include all fields in the response. Be creative and helpful.
+        """);
+
+// Wrap with state management middleware
+AIAgent agent = new SharedStateAgent(baseAgent, jsonOptions.SerializerOptions);
+
+// Map the AG-UI agent endpoint
+app.MapAGUIServer("/", agent);
+
+await app.RunAsync();

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5253",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7047;http://localhost:5253",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/RecipeModels.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace RecipeAssistant;
+
+// State wrapper
+internal sealed class AgentState
+{
+    [JsonPropertyName("recipe")]
+    public RecipeState Recipe { get; set; } = new();
+}
+
+// Recipe state model
+internal sealed class RecipeState
+{
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    [JsonPropertyName("cuisine")]
+    public string Cuisine { get; set; } = string.Empty;
+
+    [JsonPropertyName("ingredients")]
+    public List<string> Ingredients { get; set; } = [];
+
+    [JsonPropertyName("steps")]
+    public List<string> Steps { get; set; } = [];
+
+    [JsonPropertyName("prep_time_minutes")]
+    public int PrepTimeMinutes { get; set; }
+
+    [JsonPropertyName("cook_time_minutes")]
+    public int CookTimeMinutes { get; set; }
+
+    [JsonPropertyName("skill_level")]
+    public string SkillLevel { get; set; } = string.Empty;
+}
+
+// JSON serialization context
+[JsonSerializable(typeof(AgentState))]
+[JsonSerializable(typeof(RecipeState))]
+[JsonSerializable(typeof(System.Text.Json.JsonElement))]
+internal sealed partial class RecipeSerializerContext : JsonSerializerContext;

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AspNetCore\Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs

@@ -0,0 +1,159 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using AGUI.Abstractions;
+using AGUI.Server;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace RecipeAssistant;
+
+internal sealed class SharedStateAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public SharedStateAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+    }
+
+    protected override Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, session, options, cancellationToken)
+            .ToAgentResponseAsync(cancellationToken);
+    }
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Check if the client sent state in the request
+        if (options is not ChatClientAgentRunOptions { ChatOptions: { } chatOptions } chatRunOptions ||
+            !chatOptions.TryGetRunAgentInput(out RunAgentInput? agentInput) ||
+            agentInput.State is not { ValueKind: JsonValueKind.Object } state)
+        {
+            // No state management requested, pass through to inner agent
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                yield return update;
+            }
+            yield break;
+        }
+
+        // Check if state has properties (not empty {})
+        bool hasProperties = false;
+        foreach (JsonProperty _ in state.EnumerateObject())
+        {
+            hasProperties = true;
+            break;
+        }
+
+        if (!hasProperties)
+        {
+            // Empty state - treat as no state
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                yield return update;
+            }
+            yield break;
+        }
+
+        // First run: Generate structured state update
+        var firstRunOptions = new ChatClientAgentRunOptions
+        {
+            ChatOptions = chatRunOptions.ChatOptions.Clone(),
+            AllowBackgroundResponses = chatRunOptions.AllowBackgroundResponses,
+            ContinuationToken = chatRunOptions.ContinuationToken,
+            ChatClientFactory = chatRunOptions.ChatClientFactory,
+        };
+
+        // Configure JSON schema response format for structured state output
+        firstRunOptions.ChatOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema<AgentState>(
+            schemaName: "AgentState",
+            schemaDescription: "A response containing a recipe with title, skill level, cooking time, ingredients, and instructions");
+
+        // Add current state to the conversation - state is already a JsonElement
+        ChatMessage stateUpdateMessage = new(
+            ChatRole.System,
+            [
+                new TextContent("Here is the current state in JSON format:"),
+                new TextContent(JsonSerializer.Serialize(state, this._jsonSerializerOptions.GetTypeInfo(typeof(JsonElement)))),
+                new TextContent("The new state is:")
+            ]);
+
+        var firstRunMessages = messages.Append(stateUpdateMessage);
+
+        // Collect all updates from first run
+        var allUpdates = new List<AgentResponseUpdate>();
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(firstRunMessages, session, firstRunOptions, cancellationToken).ConfigureAwait(false))
+        {
+            allUpdates.Add(update);
+
+            // Yield all non-text updates (tool calls, etc.)
+            bool hasNonTextContent = update.Contents.Any(c => c is not TextContent);
+            if (hasNonTextContent)
+            {
+                yield return update;
+            }
+        }
+
+        var response = allUpdates.ToAgentResponse();
+
+        // Try to deserialize the structured state response
+        if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        {
+            // Serialize and emit as STATE_SNAPSHOT via DataContent
+            byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
+                stateSnapshot,
+                this._jsonSerializerOptions.GetTypeInfo(typeof(JsonElement)));
+            yield return new AgentResponseUpdate
+            {
+                Contents = [new DataContent(stateBytes, "application/json")]
+            };
+        }
+        else
+        {
+            yield break;
+        }
+
+        // Second run: Generate user-friendly summary
+        var secondRunMessages = messages.Concat(response.Messages).Append(
+            new ChatMessage(
+                ChatRole.System,
+                [new TextContent("Please provide a concise summary of the state changes in at most two sentences.")]));
+
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(secondRunMessages, session, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return update;
+        }
+    }
+
+    private static bool TryDeserialize<T>(string json, JsonSerializerOptions jsonSerializerOptions, out T structuredOutput)
+    {
+        try
+        {
+            T? deserialized = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
+            if (deserialized is null)
+            {
+                structuredOutput = default!;
+                return false;
+            }
+
+            structuredOutput = deserialized;
+            return true;
+        }
+        catch
+        {
+            structuredOutput = default!;
+            return false;
+        }
+    }
+}

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}