chore: import upstream snapshot with attribution

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>b9c3f1e1-2fb4-5g29-0e52-53e2b7g9gf21</UserSecretsId>
+  </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/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServerSerializerContext.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using AGUIDojoServer.AgenticUI;
+using AGUIDojoServer.BackendToolRendering;
+using AGUIDojoServer.PredictiveStateUpdates;
+using AGUIDojoServer.SharedState;
+
+namespace AGUIDojoServer;
+
+[JsonSerializable(typeof(WeatherInfo))]
+[JsonSerializable(typeof(Recipe))]
+[JsonSerializable(typeof(Ingredient))]
+[JsonSerializable(typeof(RecipeResponse))]
+[JsonSerializable(typeof(Plan))]
+[JsonSerializable(typeof(Step))]
+[JsonSerializable(typeof(StepStatus))]
+[JsonSerializable(typeof(StepStatus?))]
+[JsonSerializable(typeof(JsonPatchOperation))]
+[JsonSerializable(typeof(List<JsonPatchOperation>))]
+[JsonSerializable(typeof(List<string>))]
+[JsonSerializable(typeof(DocumentState))]
+internal sealed partial class AGUIDojoServerSerializerContext : JsonSerializerContext;

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/AgenticPlanningTools.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace AGUIDojoServer.AgenticUI;
+
+internal static class AgenticPlanningTools
+{
+    [Description("Create a plan with multiple steps.")]
+    public static Plan CreatePlan([Description("List of step descriptions to create the plan.")] List<string> steps)
+    {
+        return new Plan
+        {
+            Steps = [.. steps.Select(s => new Step { Description = s, Status = StepStatus.Pending })]
+        };
+    }
+
+    [Description("Update a step in the plan with new description or status.")]
+    public static async Task<List<JsonPatchOperation>> UpdatePlanStepAsync(
+        [Description("The index of the step to update.")] int index,
+        [Description("The new description for the step (optional).")] string? description = null,
+        [Description("The new status for the step (optional).")] StepStatus? status = null)
+    {
+        var changes = new List<JsonPatchOperation>();
+
+        if (description is not null)
+        {
+            changes.Add(new JsonPatchOperation
+            {
+                Op = "replace",
+                Path = $"/steps/{index}/description",
+                Value = description
+            });
+        }
+
+        if (status.HasValue)
+        {
+            // Status must be lowercase to match AG-UI frontend expectations: "pending" or "completed"
+            string statusValue = status.Value == StepStatus.Pending ? "pending" : "completed";
+            changes.Add(new JsonPatchOperation
+            {
+                Op = "replace",
+                Path = $"/steps/{index}/status",
+                Value = statusValue
+            });
+        }
+
+        await Task.Delay(1000);
+
+        return changes;
+    }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/AgenticUIAgent.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace AGUIDojoServer.AgenticUI;
+
+[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by ChatClientAgentFactory.CreateAgenticUI")]
+internal sealed class AgenticUIAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public AgenticUIAgent(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)
+    {
+        // Track function calls that should trigger state events
+        var trackedFunctionCalls = new Dictionary<string, FunctionCallContent>();
+
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))
+        {
+            // Process contents: track function calls and emit state events for results
+            List<AIContent> stateEventsToEmit = new();
+            foreach (var content in update.Contents)
+            {
+                if (content is FunctionCallContent callContent)
+                {
+                    if (callContent.Name == "create_plan" || callContent.Name == "update_plan_step")
+                    {
+                        trackedFunctionCalls[callContent.CallId] = callContent;
+                        break;
+                    }
+                }
+                else if (content is FunctionResultContent resultContent)
+                {
+                    // Check if this result matches a tracked function call
+                    if (trackedFunctionCalls.TryGetValue(resultContent.CallId, out var matchedCall))
+                    {
+                        var bytes = JsonSerializer.SerializeToUtf8Bytes((JsonElement)resultContent.Result!, this._jsonSerializerOptions);
+
+                        // Determine event type based on the function name
+                        if (matchedCall.Name == "create_plan")
+                        {
+                            stateEventsToEmit.Add(new DataContent(bytes, "application/json"));
+                        }
+                        else if (matchedCall.Name == "update_plan_step")
+                        {
+                            stateEventsToEmit.Add(new DataContent(bytes, "application/json-patch+json"));
+                        }
+                    }
+                }
+            }
+
+            yield return update;
+
+            yield return new AgentResponseUpdate(
+                new ChatResponseUpdate(role: ChatRole.System, stateEventsToEmit)
+                {
+                    MessageId = "delta_" + Guid.NewGuid().ToString("N"),
+                    CreatedAt = update.CreatedAt,
+                    ResponseId = update.ResponseId,
+                    AuthorName = update.AuthorName,
+                    Role = update.Role,
+                    ContinuationToken = update.ContinuationToken,
+                    AdditionalProperties = update.AdditionalProperties,
+                })
+            {
+                AgentId = update.AgentId
+            };
+        }
+    }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/JsonPatchOperation.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.AgenticUI;
+
+internal sealed class JsonPatchOperation
+{
+    [JsonPropertyName("op")]
+    public required string Op { get; set; }
+
+    [JsonPropertyName("path")]
+    public required string Path { get; set; }
+
+    [JsonPropertyName("value")]
+    public object? Value { get; set; }
+
+    [JsonPropertyName("from")]
+    public string? From { get; set; }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/Plan.cs

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.AgenticUI;
+
+internal sealed class Plan
+{
+    [JsonPropertyName("steps")]
+    public List<Step> Steps { get; set; } = [];
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/Step.cs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.AgenticUI;
+
+internal sealed class Step
+{
+    [JsonPropertyName("description")]
+    public required string Description { get; set; }
+
+    [JsonPropertyName("status")]
+    public StepStatus Status { get; set; } = StepStatus.Pending;
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AgenticUI/StepStatus.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.AgenticUI;
+
+[JsonConverter(typeof(JsonStringEnumConverter<StepStatus>))]
+internal enum StepStatus
+{
+    Pending,
+    Completed
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/BackendToolRendering/WeatherInfo.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.BackendToolRendering;
+
+internal sealed class WeatherInfo
+{
+    [JsonPropertyName("temperature")]
+    public int Temperature { get; init; }
+
+    [JsonPropertyName("conditions")]
+    public string Conditions { get; init; } = string.Empty;
+
+    [JsonPropertyName("humidity")]
+    public int Humidity { get; init; }
+
+    [JsonPropertyName("wind_speed")]
+    public int WindSpeed { get; init; }
+
+    [JsonPropertyName("feelsLike")]
+    public int FeelsLike { get; init; }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/ChatClientAgentFactory.cs

@@ -0,0 +1,183 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json;
+using AGUIDojoServer.AgenticUI;
+using AGUIDojoServer.BackendToolRendering;
+using AGUIDojoServer.PredictiveStateUpdates;
+using AGUIDojoServer.SharedState;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+namespace AGUIDojoServer;
+
+internal static class ChatClientAgentFactory
+{
+    private static AzureOpenAIClient? s_azureOpenAIClient;
+    private static string? s_deploymentName;
+
+    public static void Initialize(IConfiguration configuration)
+    {
+        string endpoint = configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        s_deploymentName = configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+        // 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.
+        s_azureOpenAIClient = new AzureOpenAIClient(
+            new Uri(endpoint),
+            new DefaultAzureCredential());
+    }
+
+    public static ChatClientAgent CreateAgenticChat()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsAIAgent(
+            name: "AgenticChat",
+            description: "A simple chat agent using Azure OpenAI");
+    }
+
+    public static ChatClientAgent CreateBackendToolRendering()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsAIAgent(
+            name: "BackendToolRenderer",
+            description: "An agent that can render backend tools using Azure OpenAI",
+            tools: [AIFunctionFactory.Create(
+                GetWeather,
+                name: "get_weather",
+                description: "Get the weather for a given location.",
+                AGUIDojoServerSerializerContext.Default.Options)]);
+    }
+
+    public static ChatClientAgent CreateHumanInTheLoop()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsAIAgent(
+            name: "HumanInTheLoopAgent",
+            description: "An agent that involves human feedback in its decision-making process using Azure OpenAI");
+    }
+
+    public static ChatClientAgent CreateToolBasedGenerativeUI()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsAIAgent(
+            name: "ToolBasedGenerativeUIAgent",
+            description: "An agent that uses tools to generate user interfaces using Azure OpenAI");
+    }
+
+    public static AIAgent CreateAgenticUI(JsonSerializerOptions options)
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+        var baseAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
+        {
+            Name = "AgenticUIAgent",
+            Description = "An agent that generates agentic user interfaces using Azure OpenAI",
+            ChatOptions = new ChatOptions
+            {
+                Instructions = """
+                    When planning use tools only, without any other messages.
+                    IMPORTANT:
+                    - Use the `create_plan` tool to set the initial state of the steps
+                    - Use the `update_plan_step` tool to update the status of each step
+                    - Do NOT repeat the plan or summarise it in a message
+                    - Do NOT confirm the creation or updates in a message
+                    - Do NOT ask the user for additional information or next steps
+                    - Do NOT leave a plan hanging, always complete the plan via `update_plan_step` if one is ongoing.
+                    - Continue calling update_plan_step until all steps are marked as completed.
+
+                    Only one plan can be active at a time, so do not call the `create_plan` tool
+                    again until all the steps in current plan are completed.
+                    """,
+                Tools = [
+                    AIFunctionFactory.Create(
+                        AgenticPlanningTools.CreatePlan,
+                        name: "create_plan",
+                        description: "Create a plan with multiple steps.",
+                        AGUIDojoServerSerializerContext.Default.Options),
+                    AIFunctionFactory.Create(
+                        AgenticPlanningTools.UpdatePlanStepAsync,
+                        name: "update_plan_step",
+                        description: "Update a step in the plan with new description or status.",
+                        AGUIDojoServerSerializerContext.Default.Options)
+                ],
+                AllowMultipleToolCalls = false
+            }
+        });
+
+        return new AgenticUIAgent(baseAgent, options);
+    }
+
+    public static AIAgent CreateSharedState(JsonSerializerOptions options)
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        var baseAgent = chatClient.AsAIAgent(
+            name: "SharedStateAgent",
+            description: "An agent that demonstrates shared state patterns using Azure OpenAI");
+
+        return new SharedStateAgent(baseAgent, options);
+    }
+
+    public static AIAgent CreatePredictiveStateUpdates(JsonSerializerOptions options)
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        var baseAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
+        {
+            Name = "PredictiveStateUpdatesAgent",
+            Description = "An agent that demonstrates predictive state updates using Azure OpenAI",
+            ChatOptions = new ChatOptions
+            {
+                Instructions = """
+                    You are a document editor assistant. When asked to write or edit content:
+                    
+                    IMPORTANT:
+                    - Use the `write_document` tool with the full document text in Markdown format
+                    - Format the document extensively so it's easy to read
+                    - You can use all kinds of markdown (headings, lists, bold, etc.)
+                    - However, do NOT use italic or strike-through formatting
+                    - You MUST write the full document, even when changing only a few words
+                    - When making edits to the document, try to make them minimal - do not change every word
+                    - Keep stories SHORT!
+                    - After you are done writing the document you MUST call a confirm_changes tool after you call write_document
+                    
+                    After the user confirms the changes, provide a brief summary of what you wrote.
+                    """,
+                Tools = [
+                    AIFunctionFactory.Create(
+                        WriteDocument,
+                        name: "write_document",
+                        description: "Write a document. Use markdown formatting to format the document.",
+                        AGUIDojoServerSerializerContext.Default.Options)
+                ]
+            }
+        });
+
+        return new PredictiveStateUpdatesAgent(baseAgent, options);
+    }
+
+    [Description("Get the weather for a given location.")]
+    private static WeatherInfo GetWeather([Description("The location to get the weather for.")] string location) => new()
+    {
+        Temperature = 20,
+        Conditions = "sunny",
+        Humidity = 50,
+        WindSpeed = 10,
+        FeelsLike = 25
+    };
+
+    [Description("Write a document in markdown format.")]
+    private static string WriteDocument([Description("The document content to write.")] string document)
+    {
+        // Simply return success - the document is tracked via state updates
+        return "Document written successfully";
+    }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/PredictiveStateUpdates/DocumentState.cs

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.PredictiveStateUpdates;
+
+internal sealed class DocumentState
+{
+    [JsonPropertyName("document")]
+    public string Document { get; set; } = string.Empty;
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/PredictiveStateUpdates/PredictiveStateUpdatesAgent.cs

@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace AGUIDojoServer.PredictiveStateUpdates;
+
+[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by ChatClientAgentFactory.CreatePredictiveStateUpdates")]
+internal sealed class PredictiveStateUpdatesAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+    private const int ChunkSize = 10; // Characters per chunk for streaming effect
+
+    public PredictiveStateUpdatesAgent(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)
+    {
+        // Track the last emitted document state to avoid duplicates
+        string? lastEmittedDocument = null;
+
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))
+        {
+            // Check if we're seeing a write_document tool call and emit predictive state
+            bool hasToolCall = false;
+            string? documentContent = null;
+
+            foreach (var content in update.Contents)
+            {
+                if (content is FunctionCallContent callContent && callContent.Name == "write_document")
+                {
+                    hasToolCall = true;
+                    // Try to extract the document argument directly from the dictionary
+                    if (callContent.Arguments?.TryGetValue("document", out var documentValue) == true)
+                    {
+                        documentContent = documentValue?.ToString();
+                    }
+                }
+            }
+
+            // Always yield the original update first
+            yield return update;
+
+            // If we got a complete tool call with document content, "fake" stream it in chunks
+            if (hasToolCall && documentContent != null && documentContent != lastEmittedDocument)
+            {
+                // Chunk the document content and emit progressive state updates
+                int startIndex = 0;
+                if (lastEmittedDocument != null && documentContent.StartsWith(lastEmittedDocument, StringComparison.Ordinal))
+                {
+                    // Only stream the new portion that was added
+                    startIndex = lastEmittedDocument.Length;
+                }
+
+                // Stream the document in chunks
+                for (int i = startIndex; i < documentContent.Length; i += ChunkSize)
+                {
+                    int length = Math.Min(ChunkSize, documentContent.Length - i);
+                    string chunk = documentContent.Substring(0, i + length);
+
+                    // Prepare predictive state update as DataContent
+                    var stateUpdate = new DocumentState { Document = chunk };
+                    byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
+                        stateUpdate,
+                        this._jsonSerializerOptions.GetTypeInfo(typeof(DocumentState)));
+
+                    yield return new AgentResponseUpdate(
+                        new ChatResponseUpdate(role: ChatRole.Assistant, [new DataContent(stateBytes, "application/json")])
+                        {
+                            MessageId = "snapshot" + Guid.NewGuid().ToString("N"),
+                            CreatedAt = update.CreatedAt,
+                            ResponseId = update.ResponseId,
+                            AdditionalProperties = update.AdditionalProperties,
+                            AuthorName = update.AuthorName,
+                            ContinuationToken = update.ContinuationToken,
+                        })
+                    {
+                        AgentId = update.AgentId
+                    };
+
+                    // Small delay to simulate streaming
+                    await Task.Delay(50, cancellationToken).ConfigureAwait(false);
+                }
+
+                lastEmittedDocument = documentContent;
+            }
+        }
+    }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/Program.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using AGUIDojoServer;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.AspNetCore.HttpLogging;
+using Microsoft.Extensions.Options;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddHttpLogging(logging =>
+{
+    logging.LoggingFields = HttpLoggingFields.RequestPropertiesAndHeaders | HttpLoggingFields.RequestBody
+        | HttpLoggingFields.ResponsePropertiesAndHeaders | HttpLoggingFields.ResponseBody;
+    logging.RequestBodyLogLimit = int.MaxValue;
+    logging.ResponseBodyLogLimit = int.MaxValue;
+});
+
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(AGUIDojoServerSerializerContext.Default));
+builder.Services.AddAGUIServer();
+
+// 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();
+
+app.UseHttpLogging();
+
+// Initialize the factory
+ChatClientAgentFactory.Initialize(app.Configuration);
+
+// Map the AG-UI agent endpoints for different scenarios
+app.MapAGUIServer("/agentic_chat", ChatClientAgentFactory.CreateAgenticChat());
+
+app.MapAGUIServer("/backend_tool_rendering", ChatClientAgentFactory.CreateBackendToolRendering());
+
+app.MapAGUIServer("/human_in_the_loop", ChatClientAgentFactory.CreateHumanInTheLoop());
+
+app.MapAGUIServer("/tool_based_generative_ui", ChatClientAgentFactory.CreateToolBasedGenerativeUI());
+
+var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>();
+app.MapAGUIServer("/agentic_generative_ui", ChatClientAgentFactory.CreateAgenticUI(jsonOptions.Value.SerializerOptions));
+
+app.MapAGUIServer("/shared_state", ChatClientAgentFactory.CreateSharedState(jsonOptions.Value.SerializerOptions));
+
+app.MapAGUIServer("/predictive_state_updates", ChatClientAgentFactory.CreatePredictiveStateUpdates(jsonOptions.Value.SerializerOptions));
+
+await app.RunAsync();
+
+public partial class Program;

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "AGUIDojoServer": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "http://localhost:5018"
+    }
+  }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/SharedState/Ingredient.cs

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.SharedState;
+
+internal sealed class Ingredient
+{
+    [JsonPropertyName("icon")]
+    public string Icon { get; set; } = string.Empty;
+
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = string.Empty;
+
+    [JsonPropertyName("amount")]
+    public string Amount { get; set; } = string.Empty;
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/SharedState/Recipe.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.SharedState;
+
+internal sealed class Recipe
+{
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    [JsonPropertyName("skill_level")]
+    public string SkillLevel { get; set; } = string.Empty;
+
+    [JsonPropertyName("cooking_time")]
+    public string CookingTime { get; set; } = string.Empty;
+
+    [JsonPropertyName("special_preferences")]
+    public List<string> SpecialPreferences { get; set; } = [];
+
+    [JsonPropertyName("ingredients")]
+    public List<Ingredient> Ingredients { get; set; } = [];
+
+    [JsonPropertyName("instructions")]
+    public List<string> Instructions { get; set; } = [];
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/SharedState/RecipeResponse.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer.SharedState;
+
+#pragma warning disable CA1812 // Used for the JsonSchema response format
+internal sealed class RecipeResponse
+#pragma warning restore CA1812
+{
+    [JsonPropertyName("recipe")]
+    public Recipe Recipe { get; set; } = new();
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/SharedState/SharedStateAgent.cs

@@ -0,0 +1,130 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using AGUI.Abstractions;
+using AGUI.Server;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace AGUIDojoServer.SharedState;
+
+[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by ChatClientAgentFactory.CreateSharedState")]
+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)
+    {
+        if (options is not ChatClientAgentRunOptions { ChatOptions: { } chatOptions } chatRunOptions ||
+            !chatOptions.TryGetRunAgentInput(out RunAgentInput? agentInput) ||
+            agentInput.State is not { ValueKind: not JsonValueKind.Undefined } state)
+        {
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                yield return update;
+            }
+            yield break;
+        }
+
+        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<RecipeResponse>(
+            schemaName: "RecipeResponse",
+            schemaDescription: "A response containing a recipe with title, skill level, cooking time, preferences, ingredients, and instructions");
+
+        ChatMessage stateUpdateMessage = new(
+            ChatRole.System,
+            [
+                new TextContent("Here is the current state in JSON format:"),
+                    new TextContent(state.GetRawText()),
+                    new TextContent("The new state is:")
+            ]);
+
+        var firstRunMessages = messages.Append(stateUpdateMessage);
+
+        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();
+
+        if (TryDeserialize(response.Text, this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        {
+            byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
+                stateSnapshot,
+                this._jsonSerializerOptions.GetTypeInfo(typeof(JsonElement)));
+            yield return new AgentResponseUpdate
+            {
+                Contents = [new DataContent(stateBytes, "application/json")]
+            };
+        }
+        else
+        {
+            yield break;
+        }
+
+        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? result = JsonSerializer.Deserialize<T>(json, jsonSerializerOptions);
+            if (result is null)
+            {
+                structuredOutput = default!;
+                return false;
+            }
+
+            structuredOutput = result;
+            return true;
+        }
+        catch
+        {
+            structuredOutput = default!;
+            return false;
+        }
+    }
+}

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/appsettings.Development.json

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

dotnet/samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/appsettings.json

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