Merge branch 'main' into feature-featurecollections-messagestore

dotnet/samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj

@@ -15,11 +15,6 @@
     <PackageReference Include="Microsoft.Extensions.Hosting" />
   </ItemGroup>
 
-  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible($(TargetFramework), 'net10.0'))">
-    <PackageReference Include="System.Net.ServerSentEvents" />
-    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" />
-  </ItemGroup>
-
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />

dotnet/samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/Program.cs

@@ -10,7 +10,7 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

dotnet/samples/GettingStarted/AGUI/README.md

@@ -0,0 +1,304 @@
+# AG-UI Getting Started Samples
+
+This directory contains samples that demonstrate how to build AG-UI (Agent UI Protocol) servers and clients using the Microsoft Agent Framework.
+
+## Prerequisites
+
+- .NET 9.0 or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (`az login`)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+## Environment Variables
+
+All samples require the following environment variables:
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+For the client samples, you can optionally set:
+
+```bash
+export AGUI_SERVER_URL="http://localhost:8888"
+```
+
+## Samples
+
+### Step01_GettingStarted
+
+A basic AG-UI server and client that demonstrate the foundational concepts.
+
+#### Server (`Step01_GettingStarted/Server`)
+
+A basic AG-UI server that hosts an AI agent accessible via HTTP. Demonstrates:
+
+- Creating an ASP.NET Core web application
+- Setting up an AG-UI server endpoint with `MapAGUI`
+- Creating an AI agent from an Azure OpenAI chat client
+- Streaming responses via Server-Sent Events (SSE)
+
+**Run the server:**
+
+```bash
+cd Step01_GettingStarted/Server
+dotnet run --urls http://localhost:8888
+```
+
+#### Client (`Step01_GettingStarted/Client`)
+
+An interactive console client that connects to an AG-UI server. Demonstrates:
+
+- Creating an AG-UI client with `AGUIChatClient`
+- Managing conversation threads
+- Streaming responses with `RunStreamingAsync`
+- Displaying colored console output for different content types
+- Supporting both interactive and automated modes
+
+**Prerequisites:** The Step01_GettingStarted server (or any AG-UI server) must be running.
+
+**Run the client:**
+
+```bash
+cd Step01_GettingStarted/Client
+dotnet run
+```
+
+Type messages and press Enter to interact with the agent. Type `:q` or `quit` to exit.
+
+### Step02_BackendTools
+
+An AG-UI server with function tools that execute on the backend.
+
+#### Server (`Step02_BackendTools/Server`)
+
+Demonstrates:
+
+- Creating function tools using `AIFunctionFactory.Create`
+- Using `[Description]` attributes for tool documentation
+- Defining explicit request/response types for type safety
+- Setting up JSON serialization contexts for source generation
+- Backend tool rendering (tools execute on the server)
+
+**Run the server:**
+
+```bash
+cd Step02_BackendTools/Server
+dotnet run --urls http://localhost:8888
+```
+
+#### Client (`Step02_BackendTools/Client`)
+
+A client that works with the backend tools server. Try asking: "Find Italian restaurants in Seattle" or "Search for Mexican food in Portland".
+
+**Run the client:**
+
+```bash
+cd Step02_BackendTools/Client
+dotnet run
+```
+
+### Step03_FrontendTools
+
+Demonstrates frontend tool rendering (tools defined on client, executed on server).
+
+#### Server (`Step03_FrontendTools/Server`)
+
+A basic AG-UI server that accepts tool definitions from the client.
+
+**Run the server:**
+
+```bash
+cd Step03_FrontendTools/Server
+dotnet run --urls http://localhost:8888
+```
+
+#### Client (`Step03_FrontendTools/Client`)
+
+A client that defines and sends tools to the server for execution.
+
+**Run the client:**
+
+```bash
+cd Step03_FrontendTools/Client
+dotnet run
+```
+
+### Step04_HumanInLoop
+
+Demonstrates human-in-the-loop approval workflows for sensitive operations. This sample includes both a server and client component.
+
+#### Server (`Step04_HumanInLoop/Server`)
+
+An AG-UI server that implements approval workflows. Demonstrates:
+
+- Wrapping tools with `ApprovalRequiredAIFunction`
+- Converting `FunctionApprovalRequestContent` to approval requests
+- Middleware pattern with `ServerFunctionApprovalServerAgent`
+- Complete function call capture and restoration
+
+**Run the server:**
+
+```bash
+cd Step04_HumanInLoop/Server
+dotnet run --urls http://localhost:8888
+```
+
+#### Client (`Step04_HumanInLoop/Client`)
+
+An interactive client that handles approval requests from the server. Demonstrates:
+
+- Using `ServerFunctionApprovalClientAgent` middleware
+- Detecting `FunctionApprovalRequestContent`
+- Displaying approval details to users
+- Prompting for approval/rejection
+- Sending approval responses with `FunctionApprovalResponseContent`
+- Resuming conversation after approval
+
+**Run the client:**
+
+```bash
+cd Step04_HumanInLoop/Client
+dotnet run
+```
+
+Try asking the agent to perform sensitive operations like "Approve expense report EXP-12345".
+
+### Step05_StateManagement
+
+An AG-UI server and client that demonstrate state management with predictive updates.
+
+#### Server (`Step05_StateManagement/Server`)
+
+Demonstrates:
+
+- Defining state schemas using C# records
+- Using `SharedStateAgent` middleware for state management
+- Streaming predictive state updates with `AgentState` content
+- Managing shared state between client and server
+- Using JSON serialization contexts for state types
+
+**Run the server:**
+
+```bash
+cd Step05_StateManagement/Server
+dotnet run
+```
+
+The server runs on port 8888 by default.
+
+#### Client (`Step05_StateManagement/Client`)
+
+A client that displays and updates shared state from the server. Try asking: "Create a recipe for chocolate chip cookies" or "Suggest a pasta dish".
+
+**Run the client:**
+
+```bash
+cd Step05_StateManagement/Client
+dotnet run
+```
+
+## How AG-UI Works
+
+### Server-Side
+
+1. Client sends HTTP POST request with messages
+2. ASP.NET Core endpoint receives the request via `MapAGUI`
+3. Agent processes messages using Agent Framework
+4. Responses are streamed back as Server-Sent Events (SSE)
+
+### Client-Side
+
+1. `AGUIAgent` sends HTTP POST request to server
+2. Server responds with SSE stream
+3. Client parses events into `AgentRunResponseUpdate` objects
+4. Updates are displayed based on content type
+5. `ConversationId` maintains conversation context
+
+### Protocol Features
+
+- **HTTP POST** for requests
+- **Server-Sent Events (SSE)** for streaming responses
+- **JSON** for event serialization
+- **Thread IDs** (as `ConversationId`) for conversation context
+- **Run IDs** (as `ResponseId`) for tracking individual executions
+
+## Troubleshooting
+
+### Connection Refused
+
+Ensure the server is running before starting the client:
+
+```bash
+# Terminal 1
+cd AGUI_Step01_ServerBasic
+dotnet run --urls http://localhost:8888
+
+# Terminal 2 (after server starts)
+cd AGUI_Step02_ClientBasic
+dotnet run
+```
+
+### Port Already in Use
+
+If port 8888 is already in use, choose a different port:
+
+```bash
+# Server
+dotnet run --urls http://localhost:8889
+
+# Client (set environment variable)
+export AGUI_SERVER_URL="http://localhost:8889"
+dotnet run
+```
+
+### Authentication Errors
+
+Make sure you're authenticated with Azure:
+
+```bash
+az login
+```
+
+Verify you have the `Cognitive Services OpenAI Contributor` role on the Azure OpenAI resource.
+
+### Missing Environment Variables
+
+If you see "AZURE_OPENAI_ENDPOINT is not set" errors, ensure environment variables are set in your current shell session before running the samples.
+
+### Streaming Not Working
+
+Check that the client timeout is sufficient (default is 60 seconds). For long-running operations, you may need to increase the timeout in the client code.
+
+## Next Steps
+
+After completing these samples, explore more AG-UI capabilities:
+
+### Currently Available in C#
+
+The samples above demonstrate the AG-UI features currently available in C#:
+
+- ✅ **Basic Server and Client**: Setting up AG-UI communication
+- ✅ **Backend Tool Rendering**: Function tools that execute on the server
+- ✅ **Streaming Responses**: Real-time Server-Sent Events
+- ✅ **State Management**: State schemas with predictive updates
+- ✅ **Human-in-the-Loop**: Approval workflows for sensitive operations
+
+### Coming Soon to C#
+
+The following advanced AG-UI features are available in the Python implementation and are planned for future C# releases:
+
+- ⏳ **Generative UI**: Custom UI component generation
+- ⏳ **Advanced State Patterns**: Complex state synchronization scenarios
+
+For the most up-to-date AG-UI features, see the [Python samples](../../../../python/samples/) for working examples.
+
+### Related Documentation
+
+- [AG-UI Overview](https://learn.microsoft.com/agent-framework/integrations/ag-ui/) - Complete AG-UI documentation
+- [Getting Started Tutorial](https://learn.microsoft.com/agent-framework/integrations/ag-ui/getting-started) - Step-by-step walkthrough
+- [Backend Tool Rendering](https://learn.microsoft.com/agent-framework/integrations/ag-ui/backend-tool-rendering) - Function tools tutorial
+- [Human-in-the-Loop](https://learn.microsoft.com/agent-framework/integrations/ag-ui/human-in-the-loop) - Approval workflows tutorial
+- [State Management](https://learn.microsoft.com/agent-framework/integrations/ag-ui/state-management) - State management tutorial
+- [Agent Framework Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview) - Core framework concepts

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Program.cs

@@ -0,0 +1,94 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
+
+Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");
+
+// Create the AG-UI client agent
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(httpClient, serverUrl);
+
+AIAgent agent = chatClient.CreateAIAgent(
+    name: "agui-client",
+    description: "AG-UI Client Agent");
+
+AgentThread thread = agent.GetNewThread();
+List<ChatMessage> messages =
+[
+    new(ChatRole.System, "You are a helpful assistant.")
+];
+
+try
+{
+    while (true)
+    {
+        // Get user input
+        Console.Write("\nUser (:q or quit to exit): ");
+        string? message = Console.ReadLine();
+
+        if (string.IsNullOrWhiteSpace(message))
+        {
+            Console.WriteLine("Request cannot be empty.");
+            continue;
+        }
+
+        if (message is ":q" or "quit")
+        {
+            break;
+        }
+
+        messages.Add(new ChatMessage(ChatRole.User, message));
+
+        // Stream the response
+        bool isFirstUpdate = true;
+        string? threadId = null;
+
+        await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread))
+        {
+            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+
+            // First update indicates run started
+            if (isFirstUpdate)
+            {
+                threadId = chatUpdate.ConversationId;
+                Console.ForegroundColor = ConsoleColor.Yellow;
+                Console.WriteLine($"\n[Run Started - Thread: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.ResetColor();
+                isFirstUpdate = false;
+            }
+
+            // Display streaming text content
+            foreach (AIContent content in update.Contents)
+            {
+                if (content is TextContent textContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Cyan;
+                    Console.Write(textContent.Text);
+                    Console.ResetColor();
+                }
+                else if (content is ErrorContent errorContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.WriteLine($"\n[Error: {errorContent.Message}]");
+                    Console.ResetColor();
+                }
+            }
+        }
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
+        Console.ResetColor();
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"\nAn error occurred: {ex.Message}");
+}

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Program.cs

@@ -0,0 +1,34 @@
+// 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.AI;
+using OpenAI.Chat;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.AddAGUI();
+
+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.");
+
+// Create the AI agent
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+AIAgent agent = chatClient.AsIChatClient().CreateAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant.");
+
+// Map the AG-UI agent endpoint
+app.MapAGUI("/", agent);
+
+await app.RunAsync();

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/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/GettingStarted/AGUI/Step01_GettingStarted/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" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Server/appsettings.Development.json

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

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Server/appsettings.json

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

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Client/Program.cs

@@ -0,0 +1,126 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
+
+Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");
+
+// Create the AG-UI client agent
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(httpClient, serverUrl);
+
+AIAgent agent = chatClient.CreateAIAgent(
+    name: "agui-client",
+    description: "AG-UI Client Agent");
+
+AgentThread thread = agent.GetNewThread();
+List<ChatMessage> messages =
+[
+    new(ChatRole.System, "You are a helpful assistant.")
+];
+
+try
+{
+    while (true)
+    {
+        // Get user input
+        Console.Write("\nUser (:q or quit to exit): ");
+        string? message = Console.ReadLine();
+
+        if (string.IsNullOrWhiteSpace(message))
+        {
+            Console.WriteLine("Request cannot be empty.");
+            continue;
+        }
+
+        if (message is ":q" or "quit")
+        {
+            break;
+        }
+
+        messages.Add(new ChatMessage(ChatRole.User, message));
+
+        // Stream the response
+        bool isFirstUpdate = true;
+        string? threadId = null;
+
+        await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread))
+        {
+            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+
+            // First update indicates run started
+            if (isFirstUpdate)
+            {
+                threadId = chatUpdate.ConversationId;
+                Console.ForegroundColor = ConsoleColor.Yellow;
+                Console.WriteLine($"\n[Run Started - Thread: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.ResetColor();
+                isFirstUpdate = false;
+            }
+
+            // Display streaming content
+            foreach (AIContent content in update.Contents)
+            {
+                switch (content)
+                {
+                    case TextContent textContent:
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write(textContent.Text);
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionCallContent functionCallContent:
+                        Console.ForegroundColor = ConsoleColor.Green;
+                        Console.WriteLine($"\n[Function Call - Name: {functionCallContent.Name}]");
+
+                        // Display individual parameters
+                        if (functionCallContent.Arguments != null)
+                        {
+                            foreach (var kvp in functionCallContent.Arguments)
+                            {
+                                Console.WriteLine($"  Parameter: {kvp.Key} = {kvp.Value}");
+                            }
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionResultContent functionResultContent:
+                        Console.ForegroundColor = ConsoleColor.Magenta;
+                        Console.WriteLine($"\n[Function Result - CallId: {functionResultContent.CallId}]");
+
+                        if (functionResultContent.Exception != null)
+                        {
+                            Console.WriteLine($"  Exception: {functionResultContent.Exception}");
+                        }
+                        else
+                        {
+                            Console.WriteLine($"  Result: {functionResultContent.Result}");
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case ErrorContent errorContent:
+                        Console.ForegroundColor = ConsoleColor.Red;
+                        Console.WriteLine($"\n[Error: {errorContent.Message}]");
+                        Console.ResetColor();
+                        break;
+                }
+            }
+        }
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
+        Console.ResetColor();
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"\nAn error occurred: {ex.Message}");
+}

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Server/Program.cs

@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Options;
+using OpenAI.Chat;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options =>
+    options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
+builder.Services.AddAGUI();
+
+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.");
+
+// Define the function tool
+[Description("Search for restaurants in a location.")]
+static RestaurantSearchResponse SearchRestaurants(
+    [Description("The restaurant search request")] RestaurantSearchRequest request)
+{
+    // Simulated restaurant data
+    string cuisine = request.Cuisine == "any" ? "Italian" : request.Cuisine;
+
+    return new RestaurantSearchResponse
+    {
+        Location = request.Location,
+        Cuisine = request.Cuisine,
+        Results =
+        [
+            new RestaurantInfo
+            {
+                Name = "The Golden Fork",
+                Cuisine = cuisine,
+                Rating = 4.5,
+                Address = $"123 Main St, {request.Location}"
+            },
+            new RestaurantInfo
+            {
+                Name = "Spice Haven",
+                Cuisine = cuisine == "Italian" ? "Indian" : cuisine,
+                Rating = 4.7,
+                Address = $"456 Oak Ave, {request.Location}"
+            },
+            new RestaurantInfo
+            {
+                Name = "Green Leaf",
+                Cuisine = "Vegetarian",
+                Rating = 4.3,
+                Address = $"789 Elm Rd, {request.Location}"
+            }
+        ]
+    };
+}
+
+// Get JsonSerializerOptions from the configured HTTP JSON options
+Microsoft.AspNetCore.Http.Json.JsonOptions jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;
+
+// Create tool with serializer options
+AITool[] tools =
+[
+    AIFunctionFactory.Create(
+        SearchRestaurants,
+        serializerOptions: jsonOptions.SerializerOptions)
+];
+
+// Create the AI agent with tools
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+ChatClientAgent agent = chatClient.AsIChatClient().CreateAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant with access to restaurant information.",
+    tools: tools);
+
+// Map the AG-UI agent endpoint
+app.MapAGUI("/", agent);
+
+await app.RunAsync();
+
+// Define request/response types for the tool
+internal sealed class RestaurantSearchRequest
+{
+    public string Location { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = "any";
+}
+
+internal sealed class RestaurantSearchResponse
+{
+    public string Location { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = string.Empty;
+    public RestaurantInfo[] Results { get; set; } = [];
+}
+
+internal sealed class RestaurantInfo
+{
+    public string Name { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = string.Empty;
+    public double Rating { get; set; }
+    public string Address { get; set; } = string.Empty;
+}
+
+// JSON serialization context for source generation
+[JsonSerializable(typeof(RestaurantSearchRequest))]
+[JsonSerializable(typeof(RestaurantSearchResponse))]
+internal sealed partial class SampleJsonSerializerContext : JsonSerializerContext;

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/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/GettingStarted/AGUI/Step02_BackendTools/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" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Server/appsettings.Development.json

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

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Server/appsettings.json

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

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Program.cs

@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
+
+Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");
+
+// Define a frontend function tool
+[Description("Get the user's current location from GPS.")]
+static string GetUserLocation()
+{
+    // Access client-side GPS
+    return "Amsterdam, Netherlands (52.37°N, 4.90°E)";
+}
+
+// Create frontend tools
+AITool[] frontendTools = [AIFunctionFactory.Create(GetUserLocation)];
+
+// Create the AG-UI client agent with tools
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(httpClient, serverUrl);
+
+AIAgent agent = chatClient.CreateAIAgent(
+    name: "agui-client",
+    description: "AG-UI Client Agent",
+    tools: frontendTools);
+
+AgentThread thread = agent.GetNewThread();
+List<ChatMessage> messages =
+[
+    new(ChatRole.System, "You are a helpful assistant.")
+];
+
+try
+{
+    while (true)
+    {
+        // Get user input
+        Console.Write("\nUser (:q or quit to exit): ");
+        string? message = Console.ReadLine();
+
+        if (string.IsNullOrWhiteSpace(message))
+        {
+            Console.WriteLine("Request cannot be empty.");
+            continue;
+        }
+
+        if (message is ":q" or "quit")
+        {
+            break;
+        }
+
+        messages.Add(new ChatMessage(ChatRole.User, message));
+
+        // Stream the response
+        bool isFirstUpdate = true;
+        string? threadId = null;
+
+        await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread))
+        {
+            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+
+            // First update indicates run started
+            if (isFirstUpdate)
+            {
+                threadId = chatUpdate.ConversationId;
+                Console.ForegroundColor = ConsoleColor.Yellow;
+                Console.WriteLine($"\n[Run Started - Thread: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.ResetColor();
+                isFirstUpdate = false;
+            }
+
+            // Display streaming content
+            foreach (AIContent content in update.Contents)
+            {
+                if (content is TextContent textContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Cyan;
+                    Console.Write(textContent.Text);
+                    Console.ResetColor();
+                }
+                else if (content is FunctionCallContent functionCallContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Green;
+                    Console.WriteLine($"\n[Client Tool Call - Name: {functionCallContent.Name}]");
+                    Console.ResetColor();
+                }
+                else if (content is FunctionResultContent functionResultContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Magenta;
+                    Console.WriteLine($"[Client Tool Result: {functionResultContent.Result}]");
+                    Console.ResetColor();
+                }
+                else if (content is ErrorContent errorContent)
+                {
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.WriteLine($"\n[Error: {errorContent.Message}]");
+                    Console.ResetColor();
+                }
+            }
+        }
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
+        Console.ResetColor();
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"\nAn error occurred: {ex.Message}");
+}

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Program.cs

@@ -0,0 +1,34 @@
+// 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.AI;
+using OpenAI.Chat;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.AddAGUI();
+
+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.");
+
+// Create the AI agent
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+AIAgent agent = chatClient.AsIChatClient().CreateAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant.");
+
+// Map the AG-UI agent endpoint
+app.MapAGUI("/", agent);
+
+await app.RunAsync();

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/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/GettingStarted/AGUI/Step03_FrontendTools/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" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Server/appsettings.Development.json

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

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Server/appsettings.json

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

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Program.cs

@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:5100";
+
+// Connect to the AG-UI server
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(httpClient, serverUrl);
+
+// Create agent
+ChatClientAgent baseAgent = chatClient.CreateAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant.");
+
+// Use default JSON serializer options
+JsonSerializerOptions jsonSerializerOptions = JsonSerializerOptions.Default;
+
+// Wrap the agent with ServerFunctionApprovalClientAgent
+ServerFunctionApprovalClientAgent agent = new(baseAgent, jsonSerializerOptions);
+
+List<ChatMessage> messages = [];
+AgentThread? thread = null;
+
+Console.ForegroundColor = ConsoleColor.White;
+Console.WriteLine("Ask a question (or type 'exit' to quit):");
+Console.ResetColor();
+
+string? input;
+while ((input = Console.ReadLine()) != null && !input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+{
+    if (string.IsNullOrWhiteSpace(input))
+    {
+        continue;
+    }
+
+    messages.Add(new ChatMessage(ChatRole.User, input));
+    Console.WriteLine();
+
+#pragma warning disable MEAI001
+    List<AIContent> approvalResponses = [];
+
+    do
+    {
+        approvalResponses.Clear();
+
+        List<AgentRunResponseUpdate> chatResponseUpdates = [];
+        await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread, cancellationToken: default))
+        {
+            chatResponseUpdates.Add(update);
+            foreach (AIContent content in update.Contents)
+            {
+                switch (content)
+                {
+                    case FunctionApprovalRequestContent approvalRequest:
+                        DisplayApprovalRequest(approvalRequest);
+
+                        Console.Write($"\nApprove '{approvalRequest.FunctionCall.Name}'? (yes/no): ");
+                        string? userInput = Console.ReadLine();
+                        bool approved = userInput?.ToUpperInvariant() is "YES" or "Y";
+
+                        FunctionApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved);
+
+                        if (approvalRequest.AdditionalProperties != null)
+                        {
+                            approvalResponse.AdditionalProperties = new AdditionalPropertiesDictionary();
+                            foreach (var kvp in approvalRequest.AdditionalProperties)
+                            {
+                                approvalResponse.AdditionalProperties[kvp.Key] = kvp.Value;
+                            }
+                        }
+
+                        approvalResponses.Add(approvalResponse);
+                        break;
+
+                    case TextContent textContent:
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write(textContent.Text);
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionCallContent functionCall:
+                        Console.ForegroundColor = ConsoleColor.Green;
+                        Console.WriteLine($"[Tool Call - Name: {functionCall.Name}]");
+                        if (functionCall.Arguments is { } arguments)
+                        {
+                            Console.WriteLine($"  Parameters: {JsonSerializer.Serialize(arguments)}");
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionResultContent functionResult:
+                        Console.ForegroundColor = ConsoleColor.Magenta;
+                        Console.WriteLine($"[Tool Result: {functionResult.Result}]");
+                        Console.ResetColor();
+                        break;
+
+                    case ErrorContent error:
+                        Console.ForegroundColor = ConsoleColor.Red;
+                        Console.WriteLine($"[Error: {error.Message}]");
+                        Console.ResetColor();
+                        break;
+                }
+            }
+        }
+
+        AgentRunResponse response = chatResponseUpdates.ToAgentRunResponse();
+        messages.AddRange(response.Messages);
+        foreach (AIContent approvalResponse in approvalResponses)
+        {
+            messages.Add(new ChatMessage(ChatRole.Tool, [approvalResponse]));
+        }
+    }
+    while (approvalResponses.Count > 0);
+#pragma warning restore MEAI001
+
+    Console.WriteLine("\n");
+    Console.ForegroundColor = ConsoleColor.White;
+    Console.WriteLine("Ask another question (or type 'exit' to quit):");
+    Console.ResetColor();
+}
+
+#pragma warning disable MEAI001
+static void DisplayApprovalRequest(FunctionApprovalRequestContent approvalRequest)
+{
+    Console.ForegroundColor = ConsoleColor.Yellow;
+    Console.WriteLine();
+    Console.WriteLine("============================================================");
+    Console.WriteLine("APPROVAL REQUIRED");
+    Console.WriteLine("============================================================");
+    Console.WriteLine($"Function: {approvalRequest.FunctionCall.Name}");
+
+    if (approvalRequest.FunctionCall.Arguments != null)
+    {
+        Console.WriteLine("Arguments:");
+        foreach (var arg in approvalRequest.FunctionCall.Arguments)
+        {
+            Console.WriteLine($"  {arg.Key} = {arg.Value}");
+        }
+    }
+
+    Console.WriteLine("============================================================");
+    Console.ResetColor();
+}
+#pragma warning restore MEAI001

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/ServerFunctionApprovalClientAgent.cs

@@ -0,0 +1,265 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ServerFunctionApproval;
+
+/// <summary>
+/// A delegating agent that handles server function approval requests and responses.
+/// Transforms between FunctionApprovalRequestContent/FunctionApprovalResponseContent
+/// and the server's request_approval tool call pattern.
+/// </summary>
+internal sealed class ServerFunctionApprovalClientAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public ServerFunctionApprovalClientAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+    }
+
+    protected override Task<AgentRunResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, thread, options, cancellationToken)
+            .ToAgentRunResponseAsync(cancellationToken);
+    }
+
+    protected override async IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Process and transform approval messages, creating a new message list
+        var processedMessages = ProcessOutgoingServerFunctionApprovals(messages.ToList(), this._jsonSerializerOptions);
+
+        // Run the inner agent and intercept any approval requests
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(
+            processedMessages, thread, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return ProcessIncomingServerApprovalRequests(update, this._jsonSerializerOptions);
+        }
+    }
+
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+    private static FunctionResultContent ConvertApprovalResponseToToolResult(FunctionApprovalResponseContent approvalResponse, JsonSerializerOptions jsonOptions)
+    {
+        return new FunctionResultContent(
+            callId: approvalResponse.Id,
+            result: JsonSerializer.SerializeToElement(
+                new ApprovalResponse
+                {
+                    ApprovalId = approvalResponse.Id,
+                    Approved = approvalResponse.Approved
+                },
+                jsonOptions));
+    }
+
+    private static List<ChatMessage> CopyMessagesUpToIndex(List<ChatMessage> messages, int index)
+    {
+        var result = new List<ChatMessage>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(messages[i]);
+        }
+        return result;
+    }
+
+    private static List<AIContent> CopyContentsUpToIndex(IList<AIContent> contents, int index)
+    {
+        var result = new List<AIContent>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(contents[i]);
+        }
+        return result;
+    }
+
+    private static List<ChatMessage> ProcessOutgoingServerFunctionApprovals(
+        List<ChatMessage> messages,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        List<ChatMessage>? result = null;
+
+        Dictionary<string, FunctionApprovalRequestContent> approvalRequests = [];
+        for (var messageIndex = 0; messageIndex < messages.Count; messageIndex++)
+        {
+            var message = messages[messageIndex];
+            List<AIContent>? transformedContents = null;
+
+            // Process each content item in the message
+            HashSet<string> approvalCalls = [];
+            for (var contentIndex = 0; contentIndex < message.Contents.Count; contentIndex++)
+            {
+                var content = message.Contents[contentIndex];
+
+                // Handle pending approval requests (transform to tool call)
+                if (content is FunctionApprovalRequestContent approvalRequest &&
+                    approvalRequest.AdditionalProperties?.TryGetValue("original_function", out var originalFunction) == true &&
+                    originalFunction is FunctionCallContent original)
+                {
+                    approvalRequests[approvalRequest.Id] = approvalRequest;
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    transformedContents.Add(original);
+                }
+                // Handle pending approval responses (transform to tool result)
+                else if (content is FunctionApprovalResponseContent approvalResponse &&
+                    approvalRequests.TryGetValue(approvalResponse.Id, out var correspondingRequest))
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    transformedContents.Add(ConvertApprovalResponseToToolResult(approvalResponse, jsonSerializerOptions));
+                    approvalRequests.Remove(approvalResponse.Id);
+                    correspondingRequest.AdditionalProperties?.Remove("original_function");
+                }
+                // Skip historical approval content
+                else if (content is FunctionCallContent { Name: "request_approval" } approvalCall)
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    approvalCalls.Add(approvalCall.CallId);
+                }
+                else if (content is FunctionResultContent functionResult &&
+                         approvalCalls.Contains(functionResult.CallId))
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    approvalCalls.Remove(functionResult.CallId);
+                }
+                else if (transformedContents != null)
+                {
+                    transformedContents.Add(content);
+                }
+            }
+
+            if (transformedContents?.Count == 0)
+            {
+                continue;
+            }
+            else if (transformedContents != null)
+            {
+                // We made changes to contents, so use transformedContents
+                var newMessage = new ChatMessage(message.Role, transformedContents)
+                {
+                    AuthorName = message.AuthorName,
+                    MessageId = message.MessageId,
+                    CreatedAt = message.CreatedAt,
+                    RawRepresentation = message.RawRepresentation,
+                    AdditionalProperties = message.AdditionalProperties
+                };
+                result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                result.Add(newMessage);
+            }
+            else if (result != null)
+            {
+                // We're already copying messages, so copy this unchanged message too
+                result.Add(message);
+            }
+            // If result is null, we haven't made any changes yet, so keep processing
+        }
+
+        return result ?? messages;
+    }
+
+    private static AgentRunResponseUpdate ProcessIncomingServerApprovalRequests(
+        AgentRunResponseUpdate update,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        IList<AIContent>? updatedContents = null;
+        for (var i = 0; i < update.Contents.Count; i++)
+        {
+            var content = update.Contents[i];
+            if (content is FunctionCallContent { Name: "request_approval" } request)
+            {
+                updatedContents ??= [.. update.Contents];
+
+                // Serialize the function arguments as JsonElement
+                ApprovalRequest? approvalRequest;
+                if (request.Arguments?.TryGetValue("request", out var reqObj) == true &&
+                    reqObj is JsonElement je)
+                {
+                    approvalRequest = (ApprovalRequest?)je.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest)));
+                }
+                else
+                {
+                    approvalRequest = null;
+                }
+
+                if (approvalRequest == null)
+                {
+                    throw new InvalidOperationException("Failed to deserialize approval request.");
+                }
+
+                var functionCallArgs = (Dictionary<string, object?>?)approvalRequest.FunctionArguments?
+                    .Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(Dictionary<string, object?>)));
+
+                var approvalRequestContent = new FunctionApprovalRequestContent(
+                    id: approvalRequest.ApprovalId,
+                    new FunctionCallContent(
+                        callId: approvalRequest.ApprovalId,
+                        name: approvalRequest.FunctionName,
+                        arguments: functionCallArgs));
+
+                approvalRequestContent.AdditionalProperties ??= [];
+                approvalRequestContent.AdditionalProperties["original_function"] = content;
+
+                updatedContents[i] = approvalRequestContent;
+            }
+        }
+
+        if (updatedContents is not null)
+        {
+            var chatUpdate = update.AsChatResponseUpdate();
+            return new AgentRunResponseUpdate(new ChatResponseUpdate()
+            {
+                Role = chatUpdate.Role,
+                Contents = updatedContents,
+                MessageId = chatUpdate.MessageId,
+                AuthorName = chatUpdate.AuthorName,
+                CreatedAt = chatUpdate.CreatedAt,
+                RawRepresentation = chatUpdate.RawRepresentation,
+                ResponseId = chatUpdate.ResponseId,
+                AdditionalProperties = chatUpdate.AdditionalProperties
+            })
+            {
+                AgentId = update.AgentId,
+                ContinuationToken = update.ContinuationToken,
+            };
+        }
+
+        return update;
+    }
+}
+#pragma warning restore MEAI001
+
+namespace ServerFunctionApproval
+{
+    public sealed class ApprovalRequest
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("function_name")]
+        public required string FunctionName { get; init; }
+
+        [JsonPropertyName("function_arguments")]
+        public JsonElement? FunctionArguments { get; init; }
+
+        [JsonPropertyName("message")]
+        public string? Message { get; init; }
+    }
+
+    public sealed class ApprovalResponse
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("approved")]
+        public required bool Approved { get; init; }
+    }
+}

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Program.cs

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.AspNetCore.Http.Json;
+using Microsoft.AspNetCore.HttpLogging;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Options;
+using OpenAI.Chat;
+using ServerFunctionApproval;
+
+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(ApprovalJsonContext.Default));
+builder.Services.AddAGUI();
+
+WebApplication app = builder.Build();
+
+app.UseHttpLogging();
+
+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.");
+
+// Define approval-required tool
+[Description("Approve the expense report.")]
+static string ApproveExpenseReport(string expenseReportId)
+{
+    return $"Expense report {expenseReportId} approved";
+}
+
+// Get JsonSerializerOptions
+var jsonOptions = app.Services.GetRequiredService<IOptions<JsonOptions>>().Value;
+
+// Create approval-required tool
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+AITool[] tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(ApproveExpenseReport))];
+#pragma warning restore MEAI001
+
+// Create base agent
+ChatClient openAIChatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+ChatClientAgent baseAgent = openAIChatClient.AsIChatClient().CreateAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant in charge of approving expenses",
+    tools: tools);
+
+// Wrap with ServerFunctionApprovalAgent
+var agent = new ServerFunctionApprovalAgent(baseAgent, jsonOptions.SerializerOptions);
+
+app.MapAGUI("/", agent);
+await app.RunAsync();

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/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:5100",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7047;http://localhost:5100",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/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" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/ServerFunctionApprovalServerAgent.cs

@@ -0,0 +1,262 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ServerFunctionApproval;
+
+/// <summary>
+/// A delegating agent that handles function approval requests on the server side.
+/// Transforms between FunctionApprovalRequestContent/FunctionApprovalResponseContent
+/// and the request_approval tool call pattern for client communication.
+/// </summary>
+internal sealed class ServerFunctionApprovalAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public ServerFunctionApprovalAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+    }
+
+    protected override Task<AgentRunResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, thread, options, cancellationToken)
+            .ToAgentRunResponseAsync(cancellationToken);
+    }
+
+    protected override async IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Process and transform incoming approval responses from client, creating a new message list
+        var processedMessages = ProcessIncomingFunctionApprovals(messages.ToList(), this._jsonSerializerOptions);
+
+        // Run the inner agent and intercept any approval requests
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(
+            processedMessages, thread, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return ProcessOutgoingApprovalRequests(update, this._jsonSerializerOptions);
+        }
+    }
+
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+    private static FunctionApprovalRequestContent ConvertToolCallToApprovalRequest(FunctionCallContent toolCall, JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (toolCall.Name != "request_approval" || toolCall.Arguments == null)
+        {
+            throw new InvalidOperationException("Invalid request_approval tool call");
+        }
+
+        var request = toolCall.Arguments.TryGetValue("request", out var reqObj) &&
+            reqObj is JsonElement argsElement &&
+            argsElement.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest))) is ApprovalRequest approvalRequest &&
+            approvalRequest != null ? approvalRequest : null;
+
+        if (request == null)
+        {
+            throw new InvalidOperationException("Failed to deserialize approval request from tool call");
+        }
+
+        return new FunctionApprovalRequestContent(
+            id: request.ApprovalId,
+            new FunctionCallContent(
+                callId: request.ApprovalId,
+                name: request.FunctionName,
+                arguments: request.FunctionArguments));
+    }
+
+    private static FunctionApprovalResponseContent ConvertToolResultToApprovalResponse(FunctionResultContent result, FunctionApprovalRequestContent approval, JsonSerializerOptions jsonSerializerOptions)
+    {
+        var approvalResponse = result.Result is JsonElement je ?
+            (ApprovalResponse?)je.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse))) :
+            result.Result is string str ?
+                (ApprovalResponse?)JsonSerializer.Deserialize(str, jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse))) :
+                result.Result as ApprovalResponse;
+
+        if (approvalResponse == null)
+        {
+            throw new InvalidOperationException("Failed to deserialize approval response from tool result");
+        }
+
+        return approval.CreateResponse(approvalResponse.Approved);
+    }
+#pragma warning restore MEAI001
+
+    private static List<ChatMessage> CopyMessagesUpToIndex(List<ChatMessage> messages, int index)
+    {
+        var result = new List<ChatMessage>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(messages[i]);
+        }
+        return result;
+    }
+
+    private static List<AIContent> CopyContentsUpToIndex(IList<AIContent> contents, int index)
+    {
+        var result = new List<AIContent>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(contents[i]);
+        }
+        return result;
+    }
+
+    private static List<ChatMessage> ProcessIncomingFunctionApprovals(
+        List<ChatMessage> messages,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        List<ChatMessage>? result = null;
+
+        // Track approval ID to original call ID mapping
+        _ = new Dictionary<string, string>();
+#pragma warning disable MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        Dictionary<string, FunctionApprovalRequestContent> trackedRequestApprovalToolCalls = new(); // Remote approvals
+        for (int messageIndex = 0; messageIndex < messages.Count; messageIndex++)
+        {
+            var message = messages[messageIndex];
+            List<AIContent>? transformedContents = null;
+            for (int j = 0; j < message.Contents.Count; j++)
+            {
+                var content = message.Contents[j];
+                if (content is FunctionCallContent { Name: "request_approval" } toolCall)
+                {
+                    result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, j);
+                    var approvalRequest = ConvertToolCallToApprovalRequest(toolCall, jsonSerializerOptions);
+                    transformedContents.Add(approvalRequest);
+                    trackedRequestApprovalToolCalls[toolCall.CallId] = approvalRequest;
+                    result.Add(new ChatMessage(message.Role, transformedContents)
+                    {
+                        AuthorName = message.AuthorName,
+                        MessageId = message.MessageId,
+                        CreatedAt = message.CreatedAt,
+                        RawRepresentation = message.RawRepresentation,
+                        AdditionalProperties = message.AdditionalProperties
+                    });
+                }
+                else if (content is FunctionResultContent toolResult &&
+                    trackedRequestApprovalToolCalls.TryGetValue(toolResult.CallId, out var approval) == true)
+                {
+                    result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, j);
+                    var approvalResponse = ConvertToolResultToApprovalResponse(toolResult, approval, jsonSerializerOptions);
+                    transformedContents.Add(approvalResponse);
+                    result.Add(new ChatMessage(message.Role, transformedContents)
+                    {
+                        AuthorName = message.AuthorName,
+                        MessageId = message.MessageId,
+                        CreatedAt = message.CreatedAt,
+                        RawRepresentation = message.RawRepresentation,
+                        AdditionalProperties = message.AdditionalProperties
+                    });
+                }
+                else if (result != null)
+                {
+                    result.Add(message);
+                }
+            }
+        }
+#pragma warning restore MEAI001
+
+        return result ?? messages;
+    }
+
+    private static AgentRunResponseUpdate ProcessOutgoingApprovalRequests(
+        AgentRunResponseUpdate update,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        IList<AIContent>? updatedContents = null;
+        for (var i = 0; i < update.Contents.Count; i++)
+        {
+            var content = update.Contents[i];
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+            if (content is FunctionApprovalRequestContent request)
+            {
+                updatedContents ??= [.. update.Contents];
+                var functionCall = request.FunctionCall;
+                var approvalId = request.Id;
+
+                var approvalData = new ApprovalRequest
+                {
+                    ApprovalId = approvalId,
+                    FunctionName = functionCall.Name,
+                    FunctionArguments = functionCall.Arguments,
+                    Message = $"Approve execution of '{functionCall.Name}'?"
+                };
+
+                updatedContents[i] = new FunctionCallContent(
+                    callId: approvalId,
+                    name: "request_approval",
+                    arguments: new Dictionary<string, object?> { ["request"] = approvalData });
+            }
+#pragma warning restore MEAI001
+        }
+
+        if (updatedContents is not null)
+        {
+            var chatUpdate = update.AsChatResponseUpdate();
+            // Yield a tool call update that represents the approval request
+            return new AgentRunResponseUpdate(new ChatResponseUpdate()
+            {
+                Role = chatUpdate.Role,
+                Contents = updatedContents,
+                MessageId = chatUpdate.MessageId,
+                AuthorName = chatUpdate.AuthorName,
+                CreatedAt = chatUpdate.CreatedAt,
+                RawRepresentation = chatUpdate.RawRepresentation,
+                ResponseId = chatUpdate.ResponseId,
+                AdditionalProperties = chatUpdate.AdditionalProperties
+            })
+            {
+                AgentId = update.AgentId,
+                ContinuationToken = update.ContinuationToken
+            };
+        }
+
+        return update;
+    }
+}
+
+namespace ServerFunctionApproval
+{
+    // Define approval models
+    public sealed class ApprovalRequest
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("function_name")]
+        public required string FunctionName { get; init; }
+
+        [JsonPropertyName("function_arguments")]
+        public IDictionary<string, object?>? FunctionArguments { get; init; }
+
+        [JsonPropertyName("message")]
+        public string? Message { get; init; }
+    }
+
+    public sealed class ApprovalResponse
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("approved")]
+        public required bool Approved { get; init; }
+    }
+
+    [JsonSerializable(typeof(ApprovalRequest))]
+    [JsonSerializable(typeof(ApprovalResponse))]
+    [JsonSerializable(typeof(Dictionary<string, object?>))]
+    public sealed partial class ApprovalJsonContext : JsonSerializerContext;
+}

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/appsettings.Development.json

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

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/appsettings.json

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

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Client/Program.cs

@@ -0,0 +1,231 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+using RecipeClient;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
+
+Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");
+
+// Create the AG-UI client agent
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(httpClient, serverUrl);
+
+AIAgent baseAgent = chatClient.CreateAIAgent(
+    name: "recipe-client",
+    description: "AG-UI Recipe Client Agent");
+
+// Wrap the base agent with state management
+JsonSerializerOptions jsonOptions = new(JsonSerializerDefaults.Web)
+{
+    TypeInfoResolver = RecipeSerializerContext.Default
+};
+StatefulAgent<AgentState> agent = new(baseAgent, jsonOptions, new AgentState());
+
+AgentThread thread = agent.GetNewThread();
+List<ChatMessage> messages =
+[
+    new(ChatRole.System, "You are a helpful recipe assistant.")
+];
+
+try
+{
+    while (true)
+    {
+        // Get user input
+        Console.Write("\nUser (:q to quit, :state to show state): ");
+        string? message = Console.ReadLine();
+
+        if (string.IsNullOrWhiteSpace(message))
+        {
+            Console.WriteLine("Request cannot be empty.");
+            continue;
+        }
+
+        if (message is ":q" or "quit")
+        {
+            break;
+        }
+
+        if (message.Equals(":state", StringComparison.OrdinalIgnoreCase))
+        {
+            DisplayState(agent.State.Recipe);
+            continue;
+        }
+
+        messages.Add(new ChatMessage(ChatRole.User, message));
+
+        // Stream the response
+        bool isFirstUpdate = true;
+        string? threadId = null;
+        bool stateReceived = false;
+
+        Console.WriteLine();
+
+        await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread))
+        {
+            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+
+            // First update indicates run started
+            if (isFirstUpdate)
+            {
+                threadId = chatUpdate.ConversationId;
+                Console.ForegroundColor = ConsoleColor.Yellow;
+                Console.WriteLine($"[Run Started - Thread: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
+                Console.ResetColor();
+                isFirstUpdate = false;
+            }
+
+            // Display streaming content
+            foreach (AIContent content in update.Contents)
+            {
+                switch (content)
+                {
+                    case TextContent textContent:
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write(textContent.Text);
+                        Console.ResetColor();
+                        break;
+
+                    case DataContent dataContent when dataContent.MediaType == "application/json":
+                        // This is a state snapshot - the StatefulAgent has already updated the state
+                        stateReceived = true;
+                        Console.ForegroundColor = ConsoleColor.Blue;
+                        Console.WriteLine("\n[State Snapshot Received]");
+                        Console.ResetColor();
+                        break;
+
+                    case ErrorContent errorContent:
+                        Console.ForegroundColor = ConsoleColor.Red;
+                        Console.WriteLine($"\n[Error: {errorContent.Message}]");
+                        Console.ResetColor();
+                        break;
+                }
+            }
+        }
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
+        Console.ResetColor();
+
+        // Display final state if received
+        if (stateReceived)
+        {
+            DisplayState(agent.State.Recipe);
+        }
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"\nAn error occurred: {ex.Message}");
+}
+
+static void DisplayState(RecipeState? state)
+{
+    if (state == null)
+    {
+        Console.ForegroundColor = ConsoleColor.Gray;
+        Console.WriteLine("\n[No state available]");
+        Console.ResetColor();
+        return;
+    }
+
+    Console.ForegroundColor = ConsoleColor.Blue;
+    Console.WriteLine("\n" + new string('=', 60));
+    Console.WriteLine("CURRENT STATE");
+    Console.WriteLine(new string('=', 60));
+    Console.ResetColor();
+
+    if (!string.IsNullOrEmpty(state.Title))
+    {
+        Console.WriteLine("\nRecipe:");
+        Console.WriteLine($"  Title: {state.Title}");
+        if (!string.IsNullOrEmpty(state.Cuisine))
+        {
+            Console.WriteLine($"  Cuisine: {state.Cuisine}");
+        }
+
+        if (!string.IsNullOrEmpty(state.SkillLevel))
+        {
+            Console.WriteLine($"  Skill Level: {state.SkillLevel}");
+        }
+
+        if (state.PrepTimeMinutes > 0)
+        {
+            Console.WriteLine($"  Prep Time: {state.PrepTimeMinutes} minutes");
+        }
+
+        if (state.CookTimeMinutes > 0)
+        {
+            Console.WriteLine($"  Cook Time: {state.CookTimeMinutes} minutes");
+        }
+
+        if (state.Ingredients.Count > 0)
+        {
+            Console.WriteLine("\n  Ingredients:");
+            foreach (var ingredient in state.Ingredients)
+            {
+                Console.WriteLine($"    - {ingredient}");
+            }
+        }
+
+        if (state.Steps.Count > 0)
+        {
+            Console.WriteLine("\n  Steps:");
+            for (int i = 0; i < state.Steps.Count; i++)
+            {
+                Console.WriteLine($"    {i + 1}. {state.Steps[i]}");
+            }
+        }
+    }
+
+    Console.ForegroundColor = ConsoleColor.Blue;
+    Console.WriteLine("\n" + new string('=', 60));
+    Console.ResetColor();
+}
+
+// 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(JsonElement))]
+internal sealed partial class RecipeSerializerContext : JsonSerializerContext;

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Client/StatefulAgent.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace RecipeClient;
+
+/// <summary>
+/// A delegating agent that manages client-side state and automatically attaches it to requests.
+/// </summary>
+/// <typeparam name="TState">The state type.</typeparam>
+internal sealed class StatefulAgent<TState> : DelegatingAIAgent
+    where TState : class, new()
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    /// <summary>
+    /// Gets or sets the current state.
+    /// </summary>
+    public TState State { get; set; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="StatefulAgent{TState}"/> class.
+    /// </summary>
+    /// <param name="innerAgent">The underlying agent to delegate to.</param>
+    /// <param name="jsonSerializerOptions">The JSON serializer options for state serialization.</param>
+    /// <param name="initialState">The initial state. If null, a new instance will be created.</param>
+    public StatefulAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions, TState? initialState = null)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+        this.State = initialState ?? new TState();
+    }
+
+    /// <inheritdoc />
+    protected override Task<AgentRunResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, thread, options, cancellationToken)
+            .ToAgentRunResponseAsync(cancellationToken);
+    }
+
+    /// <inheritdoc />
+    protected override async IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Add state to messages
+        List<ChatMessage> messagesWithState = [.. messages];
+
+        // Serialize the state using AgentState wrapper
+        byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
+            this.State,
+            this._jsonSerializerOptions.GetTypeInfo(typeof(TState)));
+        DataContent stateContent = new(stateBytes, "application/json");
+        ChatMessage stateMessage = new(ChatRole.System, [stateContent]);
+        messagesWithState.Add(stateMessage);
+
+        // Stream the response and update state when received
+        await foreach (AgentRunResponseUpdate update in this.InnerAgent.RunStreamingAsync(messagesWithState, thread, options, cancellationToken))
+        {
+            // Check if this update contains a state snapshot
+            foreach (AIContent content in update.Contents)
+            {
+                if (content is DataContent dataContent && dataContent.MediaType == "application/json")
+                {
+                    // Deserialize the state
+                    TState? newState = JsonSerializer.Deserialize(
+                        dataContent.Data.Span,
+                        this._jsonSerializerOptions.GetTypeInfo(typeof(TState))) as TState;
+                    if (newState != null)
+                    {
+                        this.State = newState;
+                    }
+                }
+            }
+
+            yield return update;
+        }
+    }
+}

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/Program.cs

@@ -0,0 +1,59 @@
+// 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.AI;
+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.AddAGUI();
+
+// Configure to listen on port 8888
+builder.WebHost.UseUrls("http://localhost:8888");
+
+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
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+AIAgent baseAgent = chatClient.AsIChatClient().CreateAIAgent(
+    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.MapAGUI("/", agent);
+
+await app.RunAsync();

dotnet/samples/GettingStarted/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/GettingStarted/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/GettingStarted/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" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/SharedStateAgent.cs

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+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<AgentRunResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, thread, options, cancellationToken)
+            .ToAgentRunResponseAsync(cancellationToken);
+    }
+
+    protected override async IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Check if the client sent state in the request
+        if (options is not ChatClientAgentRunOptions { ChatOptions.AdditionalProperties: { } properties } chatRunOptions ||
+            !properties.TryGetValue("ag_ui_state", out object? stateObj) ||
+            stateObj is not JsonElement state ||
+            state.ValueKind != JsonValueKind.Object)
+        {
+            // No state management requested, pass through to inner agent
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, thread, 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, thread, 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<AgentRunResponseUpdate>();
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(firstRunMessages, thread, 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.ToAgentRunResponse();
+
+        // Try to deserialize the structured state response
+        if (response.TryDeserialize(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 AgentRunResponseUpdate
+            {
+                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, thread, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return update;
+        }
+    }
+}

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/appsettings.Development.json

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

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/appsettings.json

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

dotnet/samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj

@@ -11,6 +11,7 @@
 
   <ItemGroup>
     <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Anthropic.Foundry" />
   </ItemGroup>
 
   <ItemGroup>

dotnet/samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Program.cs

@@ -2,10 +2,9 @@
 
 // This sample shows how to create and use an AI agent with Anthropic as the backend.
 
-using System.ClientModel;
 using System.Net.Http.Headers;
 using Anthropic;
-using Anthropic.Core;
+using Anthropic.Foundry;
 using Azure.Core;
 using Azure.Identity;
 using Microsoft.Agents.AI;
@@ -15,8 +14,8 @@ var deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_DEPLOYMENT_NA
 
 // The resource is the subdomain name / first name coming before '.services.ai.azure.com' in the endpoint Uri
 // ie: https://(resource name).services.ai.azure.com/anthropic/v1/chat/completions
-var resource = Environment.GetEnvironmentVariable("ANTHROPIC_RESOURCE");
-var apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
+string? resource = Environment.GetEnvironmentVariable("ANTHROPIC_RESOURCE");
+string? apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
 
 const string JokerInstructions = "You are good at telling jokes.";
 const string JokerName = "JokerAgent";
@@ -24,8 +23,8 @@ const string JokerName = "JokerAgent";
 AnthropicClient? client = (resource is null)
     ? new AnthropicClient() { APIKey = apiKey ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is required when no ANTHROPIC_RESOURCE is provided") }  // If no resource is provided, use Anthropic public API
     : (apiKey is not null)
-        ? new AnthropicFoundryClient(resource, new ApiKeyCredential(apiKey)) // If an apiKey is provided, use Foundry with ApiKey authentication
-        : new AnthropicFoundryClient(resource, new AzureCliCredential()); // Otherwise, use Foundry with Azure Client authentication
+        ? new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(apiKey, resource)) // If an apiKey is provided, use Foundry with ApiKey authentication
+        : new AnthropicFoundryClient(new AnthropicAzureTokenCredential(new AzureCliCredential(), resource)); // Otherwise, use Foundry with Azure Client authentication
 
 AIAgent agent = client.CreateAIAgent(model: deploymentName, instructions: JokerInstructions, name: JokerName);
 
@@ -35,67 +34,41 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 namespace Sample
 {
     /// <summary>
-    /// Provides methods for invoking the Azure hosted Anthropic api.
+    /// Provides methods for invoking the Azure hosted Anthropic models using <see cref="TokenCredential"/> types.
     /// </summary>
-    public class AnthropicFoundryClient : AnthropicClient
+    public sealed class AnthropicAzureTokenCredential : IAnthropicFoundryCredentials
     {
         private readonly TokenCredential _tokenCredential;
-        private readonly string _resourceName;
+        private readonly Lock _lock = new();
+        private AccessToken? _cachedAccessToken;
+
+        /// <inheritdoc/>
+        public string ResourceName { get; }
 
         /// <summary>
-        /// Creates a new instance of the <see cref="AnthropicFoundryClient"/>.
+        /// Creates a new instance of the <see cref="AnthropicAzureTokenCredential"/>.
         /// </summary>
-        /// <param name="resourceName">The service resource subdomain name to use in the anthropic azure endpoint</param>
         /// <param name="tokenCredential">The credential provider. Use any specialization of <see cref="TokenCredential"/> to get your access token in supported environments.</param>
-        /// <param name="options">Set of <see cref="Anthropic.Core.ClientOptions"/> client option configurations</param>
-        /// <exception cref="ArgumentNullException">Resource is null</exception>
-        /// <exception cref="ArgumentNullException">TokenCredential is null</exception>
-        /// <remarks>
-        /// Any <see cref="Anthropic.Core.ClientOptions"/> APIKey or Bearer token provided will be ignored in favor of the <see cref="TokenCredential"/> provided in the constructor
-        /// </remarks>
-        public AnthropicFoundryClient(string resourceName, TokenCredential tokenCredential, Anthropic.Core.ClientOptions? options = null) : base(options ?? new())
+        /// <param name="resourceName">The service resource subdomain name to use in the anthropic azure endpoint</param>
+        internal AnthropicAzureTokenCredential(TokenCredential tokenCredential, string resourceName)
         {
-            this._resourceName = resourceName ?? throw new ArgumentNullException(nameof(resourceName));
+            this.ResourceName = resourceName ?? throw new ArgumentNullException(nameof(resourceName));
             this._tokenCredential = tokenCredential ?? throw new ArgumentNullException(nameof(tokenCredential));
-            this.BaseUrl = new Uri($"https://{this._resourceName}.services.ai.azure.com/anthropic", UriKind.Absolute);
         }
 
-        /// <summary>
-        /// Creates a new instance of the <see cref="AnthropicFoundryClient"/>.
-        /// </summary>
-        /// <param name="resourceName">The service resource subdomain name to use in the anthropic azure endpoint</param>
-        /// <param name="apiKeyCredential">The api key.</param>
-        /// <param name="options">Set of <see cref="Anthropic.Core.ClientOptions"/> client option configurations</param>
-        /// <exception cref="ArgumentNullException">Resource is null</exception>
-        /// <exception cref="ArgumentNullException">Api key is null</exception>
-        /// <remarks>
-        /// Any <see cref="Anthropic.Core.ClientOptions"/> APIKey or Bearer token provided will be ignored in favor of the <see cref="ApiKeyCredential"/> provided in the constructor
-        /// </remarks>
-        public AnthropicFoundryClient(string resourceName, ApiKeyCredential apiKeyCredential, Anthropic.Core.ClientOptions? options = null) :
-            this(resourceName, apiKeyCredential is null
-                ? throw new ArgumentNullException(nameof(apiKeyCredential))
-                : DelegatedTokenCredential.Create((_, _) =>
-                {
-                    apiKeyCredential.Deconstruct(out string dangerousCredential);
-                    return new AccessToken(dangerousCredential, DateTimeOffset.MaxValue);
-                }),
-                options)
-        { }
-
-        public override IAnthropicClient WithOptions(Func<Anthropic.Core.ClientOptions, Anthropic.Core.ClientOptions> modifier)
-            => this;
-
-        protected override ValueTask BeforeSend<T>(
-            HttpRequest<T> request,
-            HttpRequestMessage requestMessage,
-            CancellationToken cancellationToken
-        )
+        /// <inheritdoc/>
+        public void Apply(HttpRequestMessage requestMessage)
         {
-            var accessToken = this._tokenCredential.GetToken(new TokenRequestContext(scopes: ["https://ai.azure.com/.default"]), cancellationToken);
+            lock (this._lock)
+            {
+                // Add a 5-minute buffer to avoid using tokens that are about to expire
+                if (this._cachedAccessToken is null || this._cachedAccessToken.Value.ExpiresOn <= DateTimeOffset.Now.AddMinutes(5))
+                {
+                    this._cachedAccessToken = this._tokenCredential.GetToken(new TokenRequestContext(scopes: ["https://ai.azure.com/.default"]), CancellationToken.None);
+                }
+            }
 
-            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken.Token);
-
-            return default;
+            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("bearer", this._cachedAccessToken.Value.Token);
         }
     }
 }

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Program.cs

@@ -9,9 +9,10 @@ using System.ClientModel.Primitives;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using OpenAI;
+using OpenAI.Chat;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
-var apiKey = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_APIKEY");
+var apiKey = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_API_KEY");
 var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_MODEL_DEPLOYMENT") ?? "Phi-4-mini-instruct";
 
 // Since we are using the OpenAI Client SDK, we need to override the default endpoint to point to Azure Foundry.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/README.md

@@ -27,7 +27,7 @@ Set the following environment variables:
 $env:AZURE_FOUNDRY_OPENAI_ENDPOINT="https://ai-foundry-<myresourcename>.services.ai.azure.com/openai/v1/"
 
 # Optional, defaults to using Azure CLI for authentication if not provided
-$env:AZURE_FOUNDRY_OPENAI_APIKEY="************"
+$env:AZURE_FOUNDRY_OPENAI_API_KEY="************"
 
 # Optional, defaults to Phi-4-mini-instruct
 $env:AZURE_FOUNDRY_MODEL_DEPLOYMENT="Phi-4-mini-instruct"

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Program.cs

@@ -5,7 +5,7 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Program.cs

@@ -5,7 +5,7 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Responses;
 
 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";
@@ -13,7 +13,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
     new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
      .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 
 // Invoke the agent and output the text result.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Program.cs

@@ -34,7 +34,7 @@ namespace SampleApp
         public override AgentThread DeserializeThread(JsonElement serializedThread, JsonSerializerOptions? jsonSerializerOptions = null, IAgentFeatureCollection? featureCollection = null)
             => new CustomAgentThread(serializedThread, jsonSerializerOptions);
 
-        public override async Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+        protected override async Task<AgentRunResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
         {
             // Create a thread if the user didn't supply one.
             thread ??= this.GetNewThread();
@@ -45,7 +45,7 @@ namespace SampleApp
             }
 
             // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();
+            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the thread of the input and output messages.
             await typedThread.MessageStore.AddMessagesAsync(messages.Concat(responseMessages), cancellationToken);
@@ -58,7 +58,7 @@ namespace SampleApp
             };
         }
 
-        public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        protected override async IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
         {
             // Create a thread if the user didn't supply one.
             thread ??= this.GetNewThread();
@@ -69,7 +69,7 @@ namespace SampleApp
             }
 
             // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();
+            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the thread of the input and output messages.
             await typedThread.MessageStore.AddMessagesAsync(messages.Concat(responseMessages), cancellationToken);
@@ -79,7 +79,7 @@ namespace SampleApp
                 yield return new AgentRunResponseUpdate
                 {
                     AgentId = this.Id,
-                    AuthorName = this.DisplayName,
+                    AuthorName = message.AuthorName,
                     Role = ChatRole.Assistant,
                     Contents = message.Contents,
                     ResponseId = Guid.NewGuid().ToString("N"),
@@ -88,7 +88,7 @@ namespace SampleApp
             }
         }
 
-        private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string agentName) => messages.Select(x =>
+        private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string? agentName) => messages.Select(x =>
             {
                 // Clone the message and update its author to be the agent.
                 var messageClone = x.Clone();

dotnet/samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);IDE0059;NU1510</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Google.GenAI" />
+    <PackageReference Include="Mscc.GenerativeAI.Microsoft" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0' or '$(TargetFramework)' == 'net9.0'">
+    <PackageReference Include="System.Net.Security" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/GeminiChatClient.cs

@@ -0,0 +1,558 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using Google.Apis.Util;
+using Google.GenAI;
+using Google.GenAI.Types;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Provides an <see cref="IChatClient"/> implementation based on <see cref="Client"/>.</summary>
+internal sealed class GoogleGenAIChatClient : IChatClient
+{
+    /// <summary>The wrapped <see cref="Client"/> instance (optional).</summary>
+    private readonly Client? _client;
+
+    /// <summary>The wrapped <see cref="Models"/> instance.</summary>
+    private readonly Models _models;
+
+    /// <summary>The default model that should be used when no override is specified.</summary>
+    private readonly string? _defaultModelId;
+
+    /// <summary>Lazily-initialized metadata describing the implementation.</summary>
+    private ChatClientMetadata? _metadata;
+
+    /// <summary>Initializes a new <see cref="GoogleGenAIChatClient"/> instance.</summary>
+    public GoogleGenAIChatClient(Client client, string? defaultModelId)
+    {
+        this._client = client;
+        this._models = client.Models;
+        this._defaultModelId = defaultModelId;
+    }
+
+    /// <summary>Initializes a new <see cref="GoogleGenAIChatClient"/> instance.</summary>
+    public GoogleGenAIChatClient(Models client, string? defaultModelId)
+    {
+        this._models = client;
+        this._defaultModelId = defaultModelId;
+    }
+
+    /// <inheritdoc />
+    public async Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        Utilities.ThrowIfNull(messages, nameof(messages));
+
+        // Create the request.
+        (string? modelId, List<Content> contents, GenerateContentConfig config) = this.CreateRequest(messages, options);
+
+        // Send it.
+        GenerateContentResponse generateResult = await this._models.GenerateContentAsync(modelId!, contents, config).ConfigureAwait(false);
+
+        // Create the response.
+        ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, []))
+        {
+            CreatedAt = generateResult.CreateTime is { } dt ? new DateTimeOffset(dt) : null,
+            ModelId = !string.IsNullOrWhiteSpace(generateResult.ModelVersion) ? generateResult.ModelVersion : modelId,
+            RawRepresentation = generateResult,
+            ResponseId = generateResult.ResponseId,
+        };
+
+        // Populate the response messages.
+        chatResponse.FinishReason = PopulateResponseContents(generateResult, chatResponse.Messages[0].Contents);
+
+        // Populate usage information if there is any.
+        if (generateResult.UsageMetadata is { } usageMetadata)
+        {
+            chatResponse.Usage = ExtractUsageDetails(usageMetadata);
+        }
+
+        // Return the response.
+        return chatResponse;
+    }
+
+    /// <inheritdoc />
+    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        Utilities.ThrowIfNull(messages, nameof(messages));
+
+        // Create the request.
+        (string? modelId, List<Content> contents, GenerateContentConfig config) = this.CreateRequest(messages, options);
+
+        // Send it, and process the results.
+        await foreach (GenerateContentResponse generateResult in this._models.GenerateContentStreamAsync(modelId!, contents, config).WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            // Create a response update for each result in the stream.
+            ChatResponseUpdate responseUpdate = new(ChatRole.Assistant, [])
+            {
+                CreatedAt = generateResult.CreateTime is { } dt ? new DateTimeOffset(dt) : null,
+                ModelId = !string.IsNullOrWhiteSpace(generateResult.ModelVersion) ? generateResult.ModelVersion : modelId,
+                RawRepresentation = generateResult,
+                ResponseId = generateResult.ResponseId,
+            };
+
+            // Populate the response update contents.
+            responseUpdate.FinishReason = PopulateResponseContents(generateResult, responseUpdate.Contents);
+
+            // Populate usage information if there is any.
+            if (generateResult.UsageMetadata is { } usageMetadata)
+            {
+                responseUpdate.Contents.Add(new UsageContent(ExtractUsageDetails(usageMetadata)));
+            }
+
+            // Yield the update.
+            yield return responseUpdate;
+        }
+    }
+
+    /// <inheritdoc />
+    public object? GetService(System.Type serviceType, object? serviceKey = null)
+    {
+        Utilities.ThrowIfNull(serviceType, nameof(serviceType));
+
+        if (serviceKey is null)
+        {
+            // If there's a request for metadata, lazily-initialize it and return it. We don't need to worry about race conditions,
+            // as there's no requirement that the same instance be returned each time, and creation is idempotent.
+            if (serviceType == typeof(ChatClientMetadata))
+            {
+                return this._metadata ??= new("gcp.gen_ai", new("https://generativelanguage.googleapis.com/"), defaultModelId: this._defaultModelId);
+            }
+
+            // Allow a consumer to "break glass" and access the underlying client if they need it.
+            if (serviceType.IsInstanceOfType(this._models))
+            {
+                return this._models;
+            }
+
+            if (this._client is not null && serviceType.IsInstanceOfType(this._client))
+            {
+                return this._client;
+            }
+
+            if (serviceType.IsInstanceOfType(this))
+            {
+                return this;
+            }
+        }
+
+        return null;
+    }
+
+    /// <inheritdoc />
+    void IDisposable.Dispose() { /* nop */ }
+
+    /// <summary>Creates the message parameters for <see cref="Models.GenerateContentAsync(string, List{Content}, GenerateContentConfig?)"/> from <paramref name="messages"/> and <paramref name="options"/>.</summary>
+    private (string? ModelId, List<Content> Contents, GenerateContentConfig Config) CreateRequest(IEnumerable<ChatMessage> messages, ChatOptions? options)
+    {
+        // Create the GenerateContentConfig object. If the options contains a RawRepresentationFactory, try to use it to
+        // create the request instance, allowing the caller to populate it with GenAI-specific options. Otherwise, create
+        // a new instance directly.
+        string? model = this._defaultModelId;
+        List<Content> contents = [];
+        GenerateContentConfig config = options?.RawRepresentationFactory?.Invoke(this) as GenerateContentConfig ?? new();
+
+        if (options is not null)
+        {
+            if (options.FrequencyPenalty is { } frequencyPenalty)
+            {
+                config.FrequencyPenalty ??= frequencyPenalty;
+            }
+
+            if (options.Instructions is { } instructions)
+            {
+                ((config.SystemInstruction ??= new()).Parts ??= []).Add(new() { Text = instructions });
+            }
+
+            if (options.MaxOutputTokens is { } maxOutputTokens)
+            {
+                config.MaxOutputTokens ??= maxOutputTokens;
+            }
+
+            if (!string.IsNullOrWhiteSpace(options.ModelId))
+            {
+                model = options.ModelId;
+            }
+
+            if (options.PresencePenalty is { } presencePenalty)
+            {
+                config.PresencePenalty ??= presencePenalty;
+            }
+
+            if (options.Seed is { } seed)
+            {
+                config.Seed ??= (int)seed;
+            }
+
+            if (options.StopSequences is { } stopSequences)
+            {
+                (config.StopSequences ??= []).AddRange(stopSequences);
+            }
+
+            if (options.Temperature is { } temperature)
+            {
+                config.Temperature ??= temperature;
+            }
+
+            if (options.TopP is { } topP)
+            {
+                config.TopP ??= topP;
+            }
+
+            if (options.TopK is { } topK)
+            {
+                config.TopK ??= topK;
+            }
+
+            // Populate tools. Each kind of tool is added on its own, except for function declarations,
+            // which are grouped into a single FunctionDeclaration.
+            List<FunctionDeclaration>? functionDeclarations = null;
+            if (options.Tools is { } tools)
+            {
+                foreach (var tool in tools)
+                {
+                    switch (tool)
+                    {
+                        case AIFunctionDeclaration af:
+                            functionDeclarations ??= [];
+                            functionDeclarations.Add(new()
+                            {
+                                Name = af.Name,
+                                Description = af.Description ?? "",
+                                ParametersJsonSchema = af.JsonSchema,
+                            });
+                            break;
+
+                        case HostedCodeInterpreterTool:
+                            (config.Tools ??= []).Add(new() { CodeExecution = new() });
+                            break;
+
+                        case HostedFileSearchTool:
+                            (config.Tools ??= []).Add(new() { Retrieval = new() });
+                            break;
+
+                        case HostedWebSearchTool:
+                            (config.Tools ??= []).Add(new() { GoogleSearch = new() });
+                            break;
+                    }
+                }
+            }
+
+            if (functionDeclarations is { Count: > 0 })
+            {
+                Tool functionTools = new();
+                (functionTools.FunctionDeclarations ??= []).AddRange(functionDeclarations);
+                (config.Tools ??= []).Add(functionTools);
+            }
+
+            // Transfer over the tool mode if there are any tools.
+            if (options.ToolMode is { } toolMode && config.Tools?.Count > 0)
+            {
+                switch (toolMode)
+                {
+                    case NoneChatToolMode:
+                        config.ToolConfig = new() { FunctionCallingConfig = new() { Mode = FunctionCallingConfigMode.NONE } };
+                        break;
+
+                    case AutoChatToolMode:
+                        config.ToolConfig = new() { FunctionCallingConfig = new() { Mode = FunctionCallingConfigMode.AUTO } };
+                        break;
+
+                    case RequiredChatToolMode required:
+                        config.ToolConfig = new() { FunctionCallingConfig = new() { Mode = FunctionCallingConfigMode.ANY } };
+                        if (required.RequiredFunctionName is not null)
+                        {
+                            ((config.ToolConfig.FunctionCallingConfig ??= new()).AllowedFunctionNames ??= []).Add(required.RequiredFunctionName);
+                        }
+                        break;
+                }
+            }
+
+            // Set the response format if specified.
+            if (options.ResponseFormat is ChatResponseFormatJson responseFormat)
+            {
+                config.ResponseMimeType = "application/json";
+                if (responseFormat.Schema is { } schema)
+                {
+                    config.ResponseJsonSchema = schema;
+                }
+            }
+        }
+
+        // Transfer messages to request, handling system messages specially
+        Dictionary<string, string>? callIdToFunctionNames = null;
+        foreach (var message in messages)
+        {
+            if (message.Role == ChatRole.System)
+            {
+                string instruction = message.Text;
+                if (!string.IsNullOrWhiteSpace(instruction))
+                {
+                    ((config.SystemInstruction ??= new()).Parts ??= []).Add(new() { Text = instruction });
+                }
+
+                continue;
+            }
+
+            Content content = new() { Role = message.Role == ChatRole.Assistant ? "model" : "user" };
+            content.Parts ??= [];
+            AddPartsForAIContents(ref callIdToFunctionNames, message.Contents, content.Parts);
+
+            contents.Add(content);
+        }
+
+        // Make sure the request contains at least one content part (the request would always fail if empty).
+        if (!contents.SelectMany(c => c.Parts ?? Enumerable.Empty<Part>()).Any())
+        {
+            contents.Add(new() { Role = "user", Parts = new() { { new() { Text = "" } } } });
+        }
+
+        return (model, contents, config);
+    }
+
+    /// <summary>Creates <see cref="Part"/>s for <paramref name="contents"/> and adds them to <paramref name="parts"/>.</summary>
+    private static void AddPartsForAIContents(ref Dictionary<string, string>? callIdToFunctionNames, IList<AIContent> contents, List<Part> parts)
+    {
+        for (int i = 0; i < contents.Count; i++)
+        {
+            var content = contents[i];
+
+            byte[]? thoughtSignature = null;
+            if (content is not TextReasoningContent { ProtectedData: not null } &&
+                i + 1 < contents.Count &&
+                contents[i + 1] is TextReasoningContent nextReasoning &&
+                string.IsNullOrWhiteSpace(nextReasoning.Text) &&
+                nextReasoning.ProtectedData is { } protectedData)
+            {
+                i++;
+                thoughtSignature = Convert.FromBase64String(protectedData);
+            }
+
+            Part? part = null;
+            switch (content)
+            {
+                case TextContent textContent:
+                    part = new() { Text = textContent.Text };
+                    break;
+
+                case TextReasoningContent reasoningContent:
+                    part = new()
+                    {
+                        Thought = true,
+                        Text = !string.IsNullOrWhiteSpace(reasoningContent.Text) ? reasoningContent.Text : null,
+                        ThoughtSignature = reasoningContent.ProtectedData is not null ? Convert.FromBase64String(reasoningContent.ProtectedData) : null,
+                    };
+                    break;
+
+                case DataContent dataContent:
+                    part = new()
+                    {
+                        InlineData = new()
+                        {
+                            MimeType = dataContent.MediaType,
+                            Data = dataContent.Data.ToArray(),
+                            DisplayName = dataContent.Name,
+                        }
+                    };
+                    break;
+
+                case UriContent uriContent:
+                    part = new()
+                    {
+                        FileData = new()
+                        {
+                            FileUri = uriContent.Uri.AbsoluteUri,
+                            MimeType = uriContent.MediaType,
+                        }
+                    };
+                    break;
+
+                case FunctionCallContent functionCallContent:
+                    (callIdToFunctionNames ??= [])[functionCallContent.CallId] = functionCallContent.Name;
+                    callIdToFunctionNames[""] = functionCallContent.Name; // track last function name in case calls don't have IDs
+
+                    part = new()
+                    {
+                        FunctionCall = new()
+                        {
+                            Id = functionCallContent.CallId,
+                            Name = functionCallContent.Name,
+                            Args = functionCallContent.Arguments is null ? null : functionCallContent.Arguments as Dictionary<string, object> ?? new(functionCallContent.Arguments!),
+                        }
+                    };
+                    break;
+
+                case FunctionResultContent functionResultContent:
+                    part = new()
+                    {
+                        FunctionResponse = new()
+                        {
+                            Id = functionResultContent.CallId,
+                            Name = callIdToFunctionNames?.TryGetValue(functionResultContent.CallId, out string? functionName) is true || callIdToFunctionNames?.TryGetValue("", out functionName) is true ?
+                            functionName :
+                            null,
+                            Response = functionResultContent.Result is null ? null : new() { ["result"] = functionResultContent.Result },
+                        }
+                    };
+                    break;
+            }
+
+            if (part is not null)
+            {
+                part.ThoughtSignature ??= thoughtSignature;
+                parts.Add(part);
+            }
+        }
+    }
+
+    /// <summary>Creates <see cref="AIContent"/>s for <paramref name="parts"/> and adds them to <paramref name="contents"/>.</summary>
+    private static void AddAIContentsForParts(List<Part> parts, IList<AIContent> contents)
+    {
+        foreach (var part in parts)
+        {
+            AIContent? content = null;
+
+            if (!string.IsNullOrEmpty(part.Text))
+            {
+                content = part.Thought is true ?
+                  new TextReasoningContent(part.Text) :
+                  new TextContent(part.Text);
+            }
+            else if (part.InlineData is { } inlineData)
+            {
+                content = new DataContent(inlineData.Data, inlineData.MimeType ?? "application/octet-stream")
+                {
+                    Name = inlineData.DisplayName,
+                };
+            }
+            else if (part.FileData is { FileUri: not null } fileData)
+            {
+                content = new UriContent(new Uri(fileData.FileUri), fileData.MimeType ?? "application/octet-stream");
+            }
+            else if (part.FunctionCall is { Name: not null } functionCall)
+            {
+                content = new FunctionCallContent(functionCall.Id ?? "", functionCall.Name, functionCall.Args!);
+            }
+            else if (part.FunctionResponse is { } functionResponse)
+            {
+                content = new FunctionResultContent(
+                  functionResponse.Id ?? "",
+                  functionResponse.Response?.TryGetValue("output", out var output) is true ? output :
+                  functionResponse.Response?.TryGetValue("error", out var error) is true ? error :
+                  null);
+            }
+
+            if (content is not null)
+            {
+                content.RawRepresentation = part;
+                contents.Add(content);
+
+                if (part.ThoughtSignature is { } thoughtSignature)
+                {
+                    contents.Add(new TextReasoningContent(null)
+                    {
+                        ProtectedData = Convert.ToBase64String(thoughtSignature),
+                    });
+                }
+            }
+        }
+    }
+
+    private static ChatFinishReason? PopulateResponseContents(GenerateContentResponse generateResult, IList<AIContent> responseContents)
+    {
+        ChatFinishReason? finishReason = null;
+
+        // Populate the response messages. There should only be at most one candidate, but if there are more, ignore all but the first.
+        if (generateResult.Candidates is { Count: > 0 } &&
+            generateResult.Candidates[0] is { Content: { } candidateContent } candidate)
+        {
+            // Grab the finish reason if one exists.
+            finishReason = ConvertFinishReason(candidate.FinishReason);
+
+            // Add all of the response content parts as AIContents.
+            if (candidateContent.Parts is { } parts)
+            {
+                AddAIContentsForParts(parts, responseContents);
+            }
+
+            // Add any citation metadata.
+            if (candidate.CitationMetadata is { Citations: { Count: > 0 } citations } &&
+                responseContents.OfType<TextContent>().FirstOrDefault() is TextContent textContent)
+            {
+                foreach (var citation in citations)
+                {
+                    textContent.Annotations =
+                    [
+                        new CitationAnnotation()
+                        {
+                            Title = citation.Title,
+                            Url = Uri.TryCreate(citation.Uri, UriKind.Absolute, out Uri? uri) ? uri : null,
+                            AnnotatedRegions =
+                            [
+                                new TextSpanAnnotatedRegion()
+                                {
+                                    StartIndex = citation.StartIndex,
+                                    EndIndex = citation.EndIndex,
+                                }
+                            ],
+                        }
+                    ];
+                }
+            }
+        }
+
+        // Populate error information if there is any.
+        if (generateResult.PromptFeedback is { } promptFeedback)
+        {
+            responseContents.Add(new ErrorContent(promptFeedback.BlockReasonMessage));
+        }
+
+        return finishReason;
+    }
+
+    /// <summary>Creates an M.E.AI <see cref="ChatFinishReason"/> from a Google <see cref="FinishReason"/>.</summary>
+    private static ChatFinishReason? ConvertFinishReason(FinishReason? finishReason)
+    {
+        return finishReason switch
+        {
+            null => null,
+
+            FinishReason.MAX_TOKENS =>
+              ChatFinishReason.Length,
+
+            FinishReason.MALFORMED_FUNCTION_CALL or
+            FinishReason.UNEXPECTED_TOOL_CALL =>
+              ChatFinishReason.ToolCalls,
+
+            FinishReason.FINISH_REASON_UNSPECIFIED or
+            FinishReason.STOP =>
+              ChatFinishReason.Stop,
+
+            _ => ChatFinishReason.ContentFilter,
+        };
+    }
+
+    /// <summary>Creates a <see cref="UsageDetails"/> populated from the supplied <paramref name="usageMetadata"/>.</summary>
+    private static UsageDetails ExtractUsageDetails(GenerateContentResponseUsageMetadata usageMetadata)
+    {
+        UsageDetails details = new()
+        {
+            InputTokenCount = usageMetadata.PromptTokenCount,
+            OutputTokenCount = usageMetadata.CandidatesTokenCount,
+            TotalTokenCount = usageMetadata.TotalTokenCount,
+        };
+
+        AddIfPresent(nameof(usageMetadata.CachedContentTokenCount), usageMetadata.CachedContentTokenCount);
+        AddIfPresent(nameof(usageMetadata.ThoughtsTokenCount), usageMetadata.ThoughtsTokenCount);
+        AddIfPresent(nameof(usageMetadata.ToolUsePromptTokenCount), usageMetadata.ToolUsePromptTokenCount);
+
+        return details;
+
+        void AddIfPresent(string key, int? value)
+        {
+            if (value is int i)
+            {
+                (details.AdditionalCounts ??= [])[key] = i;
+            }
+        }
+    }
+}

dotnet/samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/GoogleGenAIExtensions.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Google.Apis.Util;
+using Google.GenAI;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Provides implementations of Microsoft.Extensions.AI abstractions based on <see cref="Client"/>.</summary>
+public static class GoogleGenAIExtensions
+{
+    /// <summary>
+    /// Creates an <see cref="IChatClient"/> wrapper around the specified <see cref="Client"/>.
+    /// </summary>
+    /// <param name="client">The <see cref="Client"/> to wrap.</param>
+    /// <param name="defaultModelId">The default model ID to use for chat requests if not specified in <see cref="ChatOptions.ModelId"/>.</param>
+    /// <returns>An <see cref="IChatClient"/> that wraps the specified client.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="client"/> is <see langword="null"/>.</exception>
+    public static IChatClient AsIChatClient(this Client client, string? defaultModelId = null)
+    {
+        Utilities.ThrowIfNull(client, nameof(client));
+        return new GoogleGenAIChatClient(client, defaultModelId);
+    }
+
+    /// <summary>
+    /// Creates an <see cref="IChatClient"/> wrapper around the specified <see cref="Models"/>.
+    /// </summary>
+    /// <param name="models">The <see cref="Models"/> client to wrap.</param>
+    /// <param name="defaultModelId">The default model ID to use for chat requests if not specified in <see cref="ChatOptions.ModelId"/>.</param>
+    /// <returns>An <see cref="IChatClient"/> that wraps the specified <see cref="Models"/> client.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="models"/> is <see langword="null"/>.</exception>
+    public static IChatClient AsIChatClient(this Models models, string? defaultModelId = null)
+    {
+        Utilities.ThrowIfNull(models, nameof(models));
+        return new GoogleGenAIChatClient(models, defaultModelId);
+    }
+}

dotnet/samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Program.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use an AI agent with Google Gemini
+
+using Google.GenAI;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Mscc.GenerativeAI.Microsoft;
+
+const string JokerInstructions = "You are good at telling jokes.";
+const string JokerName = "JokerAgent";
+
+string apiKey = Environment.GetEnvironmentVariable("GOOGLE_GENAI_API_KEY") ?? throw new InvalidOperationException("Please set the GOOGLE_GENAI_API_KEY environment variable.");
+string model = Environment.GetEnvironmentVariable("GOOGLE_GENAI_MODEL") ?? "gemini-2.5-flash";
+
+// Using a Google GenAI IChatClient implementation
+// Until the PR https://github.com/googleapis/dotnet-genai/pull/81 is not merged this option
+// requires usage of also both GeminiChatClient.cs and GoogleGenAIExtensions.cs polyfills to work.
+
+ChatClientAgent agentGenAI = new(
+    new Client(vertexAI: false, apiKey: apiKey).AsIChatClient(model),
+    name: JokerName,
+    instructions: JokerInstructions);
+
+AgentRunResponse response = await agentGenAI.RunAsync("Tell me a joke about a pirate.");
+Console.WriteLine($"Google GenAI client based agent response:\n{response}");
+
+// Using a community driven Mscc.GenerativeAI.Microsoft package
+
+ChatClientAgent agentCommunity = new(
+    new GeminiChatClient(apiKey: apiKey, model: model),
+    name: JokerName,
+    instructions: JokerInstructions);
+
+response = await agentCommunity.RunAsync("Tell me a joke about a pirate.");
+Console.WriteLine($"Community client based agent response:\n{response}");

dotnet/samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/README.md

@@ -0,0 +1,37 @@
+# Creating an AIAgent with Google Gemini
+
+This sample demonstrates how to create an AIAgent using Google Gemini models as the underlying inference service.
+
+The sample showcases two different `IChatClient` implementations:
+
+1. **Google GenAI** - Using the official [Google.GenAI](https://www.nuget.org/packages/Google.GenAI) package
+2. **Mscc.GenerativeAI.Microsoft** - Using the community-driven [Mscc.GenerativeAI.Microsoft](https://www.nuget.org/packages/Mscc.GenerativeAI.Microsoft) package
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- Google AI Studio API key (get one at [Google AI Studio](https://aistudio.google.com/apikey))
+
+Set the following environment variables:
+
+```powershell
+$env:GOOGLE_GENAI_API_KEY="your-google-api-key"  # Replace with your Google AI Studio API key
+$env:GOOGLE_GENAI_MODEL="gemini-2.5-fast"  # Optional, defaults to gemini-2.5-fast
+```
+
+## Package Options
+
+### Google GenAI (Official)
+
+The official Google GenAI package provides direct access to Google's Generative AI models. This sample uses an extension method to convert the Google client to an `IChatClient`.
+
+> [!NOTE]
+> Until PR [googleapis/dotnet-genai#81](https://github.com/googleapis/dotnet-genai/pull/81) is merged, this option requires the additional `GeminiChatClient.cs` and `GoogleGenAIExtensions.cs` files included in this sample.
+>
+> We appreciate any community push by liking and commenting in the above PR to get it merged and release as part of official Google GenAI package.
+
+### Mscc.GenerativeAI.Microsoft (Community)
+
+The community-driven Mscc.GenerativeAI.Microsoft package provides a ready-to-use `IChatClient` implementation for Google Gemini models through the `GeminiChatClient` class.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Program.cs

@@ -5,10 +5,13 @@
 // WARNING: The Assistants API is deprecated and will be shut down.
 // For more information see the OpenAI documentation: https://platform.openai.com/docs/assistants/migration
 
+#pragma warning disable CS0618 // Type or member is obsolete - OpenAI Assistants API is deprecated but still used in this sample
+
 using Microsoft.Agents.AI;
 using OpenAI;
+using OpenAI.Assistants;
 
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_APIKEY") ?? throw new InvalidOperationException("OPENAI_APIKEY is not set.");
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
 
 const string JokerName = "Joker";

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/README.md

@@ -11,6 +11,6 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:
 
 ```powershell
-$env:OPENAI_APIKEY="*****" # Replace with your OpenAI API key
+$env:OPENAI_API_KEY="*****" # Replace with your OpenAI API key
 $env:OPENAI_MODEL="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/Program.cs

@@ -5,8 +5,9 @@
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using OpenAI;
+using OpenAI.Chat;
 
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_APIKEY") ?? throw new InvalidOperationException("OPENAI_APIKEY is not set.");
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
 
 AIAgent agent = new OpenAIClient(

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/README.md

@@ -8,6 +8,6 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:
 
 ```powershell
-$env:OPENAI_APIKEY="*****" # Replace with your OpenAI api key
+$env:OPENAI_API_KEY="*****" # Replace with your OpenAI api key
 $env:OPENAI_MODEL="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/Program.cs

@@ -4,13 +4,14 @@
 
 using Microsoft.Agents.AI;
 using OpenAI;
+using OpenAI.Responses;
 
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_APIKEY") ?? throw new InvalidOperationException("OPENAI_APIKEY is not set.");
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
 
 AIAgent agent = new OpenAIClient(
     apiKey)
-     .GetOpenAIResponseClient(model)
+     .GetResponsesClient(model)
      .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 
 // Invoke the agent and output the text result.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/README.md

@@ -8,6 +8,6 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:
 
 ```powershell
-$env:OPENAI_APIKEY="*****" # Replace with your OpenAI api key
+$env:OPENAI_API_KEY="*****" # Replace with your OpenAI api key
 $env:OPENAI_MODEL="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/Program.cs

@@ -9,7 +9,7 @@ using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.InMemory;
-using OpenAI;
+using OpenAI.Chat;
 
 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";
@@ -32,7 +32,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are good at telling jokes.",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
         AIContextProviderFactory = (ctx) => new ChatHistoryMemoryProvider(
             vectorStore,

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/Program.cs

@@ -11,7 +11,7 @@ using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Mem0;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";
@@ -30,7 +30,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions()
     {
-        Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details.",
+        ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
         AIContextProviderFactory = ctx => ctx.SerializedState.ValueKind is not JsonValueKind.Null and not JsonValueKind.Undefined
             // If each thread should have its own Mem0 scope, you can create a new id per thread here:
             // ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/Program.cs

@@ -12,7 +12,6 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
 using OpenAI.Chat;
 using SampleApp;
 
@@ -33,7 +32,7 @@ ChatClient chatClient = new AzureOpenAIClient(
 // and its storage to that user id.
 AIAgent agent = chatClient.CreateAIAgent(new ChatClientAgentOptions()
 {
-    Instructions = "You are a friendly assistant. Always address the user by their name.",
+    ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
     AIContextProviderFactory = ctx => new UserInfoMemory(chatClient.AsIChatClient(), ctx.SerializedState, ctx.JsonSerializerOptions)
 });
 

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Program.cs

@@ -7,15 +7,15 @@ using Microsoft.Extensions.AI;
 using OpenAI;
 using OpenAI.Responses;
 
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_APIKEY") ?? throw new InvalidOperationException("OPENAI_APIKEY is not set.");
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-5";
 
 var client = new OpenAIClient(apiKey)
-        .GetOpenAIResponseClient(model)
+        .GetResponsesClient(model)
         .AsIChatClient().AsBuilder()
         .ConfigureOptions(o =>
         {
-            o.RawRepresentationFactory = _ => new ResponseCreationOptions()
+            o.RawRepresentationFactory = _ => new CreateResponseOptions()
             {
                 ReasoningOptions = new()
                 {

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/OpenAIChatClientAgent.cs

@@ -0,0 +1,96 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using OpenAI.Chat;
+using ChatMessage = OpenAI.Chat.ChatMessage;
+
+namespace OpenAIChatClientSample;
+
+/// <summary>
+/// Provides an <see cref="AIAgent"/> backed by an OpenAI chat completion implementation.
+/// </summary>
+public class OpenAIChatClientAgent : DelegatingAIAgent
+{
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIChatClientAgent"/>
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ChatClient"/></param>
+    /// <param name="instructions">Optional instructions for the agent.</param>
+    /// <param name="name">Optional name for the agent.</param>
+    /// <param name="description">Optional description for the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIChatClientAgent(
+        ChatClient client,
+        string? instructions = null,
+        string? name = null,
+        string? description = null,
+        ILoggerFactory? loggerFactory = null) :
+        this(client, new()
+        {
+            Name = name,
+            Description = description,
+            ChatOptions = new ChatOptions() { Instructions = instructions },
+        }, loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIChatClientAgent"/>
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ChatClient"/></param>
+    /// <param name="options">Options to create the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIChatClientAgent(
+        ChatClient client, ChatClientAgentOptions options, ILoggerFactory? loggerFactory = null) :
+        base(new ChatClientAgent((client ?? throw new ArgumentNullException(nameof(client))).AsIChatClient(), options, loggerFactory))
+    {
+    }
+
+    /// <summary>
+    /// Run the agent with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatCompletion"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual async Task<ChatCompletion> RunAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await this.RunAsync(messages.AsChatMessages(), thread, options, cancellationToken).ConfigureAwait(false);
+
+        return response.AsOpenAIChatCompletion();
+    }
+
+    /// <summary>
+    /// Run the agent streaming with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatCompletion"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual IAsyncEnumerable<StreamingChatCompletionUpdate> RunStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = this.RunStreamingAsync(messages.AsChatMessages(), thread, options, cancellationToken);
+
+        return response.AsChatResponseUpdatesAsync().AsOpenAIStreamingChatCompletionUpdatesAsync(cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    protected sealed override Task<AgentRunResponse> RunCoreAsync(IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreAsync(messages, thread, options, cancellationToken);
+
+    /// <inheritdoc/>
+    protected override IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreStreamingAsync(messages, thread, options, cancellationToken);
+}

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Program.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to create an AI agent directly from an OpenAI.Chat.ChatClient instance using OpenAIChatClientAgent.
+
+using OpenAI;
+using OpenAI.Chat;
+using OpenAIChatClientSample;
+
+string apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+string model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
+
+// Create a ChatClient directly from OpenAIClient
+ChatClient chatClient = new OpenAIClient(apiKey).GetChatClient(model);
+
+// Create an agent directly from the ChatClient using OpenAIChatClientAgent
+OpenAIChatClientAgent agent = new(chatClient, instructions: "You are good at telling jokes.", name: "Joker");
+
+UserChatMessage chatMessage = new("Tell me a joke about a pirate.");
+
+// Invoke the agent and output the text result.
+ChatCompletion chatCompletion = await agent.RunAsync([chatMessage]);
+Console.WriteLine(chatCompletion.Content.Last().Text);
+
+// Invoke the agent with streaming support.
+IAsyncEnumerable<StreamingChatCompletionUpdate> completionUpdates = agent.RunStreamingAsync([chatMessage]);
+await foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)
+{
+    if (completionUpdate.ContentUpdate.Count > 0)
+    {
+        Console.WriteLine(completionUpdate.ContentUpdate[0].Text);
+    }
+}

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/README.md

@@ -0,0 +1,22 @@
+# Creating an Agent from a ChatClient
+
+This sample demonstrates how to create an AI agent directly from an `OpenAI.Chat.ChatClient` instance using the `OpenAIChatClientAgent` class.
+
+## What This Sample Shows
+
+- **Direct ChatClient Creation**: Shows how to create an `OpenAI.Chat.ChatClient` from `OpenAI.OpenAIClient` and then use it to instantiate an agent
+- **OpenAIChatClientAgent**: Demonstrates using the OpenAI SDK primitives instead of the ones from Microsoft.Extensions.AI and Microsoft.Agents.AI abstractions
+- **Full Agent Capabilities**: Shows both regular and streaming invocation of the agent
+
+## Running the Sample
+
+1. Set the required environment variables:
+   ```bash
+   set OPENAI_API_KEY=your_api_key_here
+   set OPENAI_MODEL=gpt-4o-mini
+   ```
+
+2. Run the sample:
+   ```bash
+   dotnet run
+   ```

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/OpenAIResponseClientAgent.cs

@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using OpenAI.Responses;
+
+namespace OpenAIResponseClientSample;
+
+/// <summary>
+/// Provides an <see cref="AIAgent"/> backed by an OpenAI Responses implementation.
+/// </summary>
+public class OpenAIResponseClientAgent : DelegatingAIAgent
+{
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIResponseClientAgent"/>.
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ResponsesClient"/></param>
+    /// <param name="instructions">Optional instructions for the agent.</param>
+    /// <param name="name">Optional name for the agent.</param>
+    /// <param name="description">Optional description for the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIResponseClientAgent(
+        ResponsesClient client,
+        string? instructions = null,
+        string? name = null,
+        string? description = null,
+        ILoggerFactory? loggerFactory = null) :
+        this(client, new()
+        {
+            Name = name,
+            Description = description,
+            ChatOptions = new ChatOptions() { Instructions = instructions },
+        }, loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIResponseClientAgent"/>.
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ResponsesClient"/></param>
+    /// <param name="options">Options to create the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIResponseClientAgent(
+        ResponsesClient client, ChatClientAgentOptions options, ILoggerFactory? loggerFactory = null) :
+        base(new ChatClientAgent((client ?? throw new ArgumentNullException(nameof(client))).AsIChatClient(), options, loggerFactory))
+    {
+    }
+
+    /// <summary>
+    /// Run the agent with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ResponseResult"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual async Task<ResponseResult> RunAsync(
+        IEnumerable<ResponseItem> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await this.RunAsync(messages.AsChatMessages(), thread, options, cancellationToken).ConfigureAwait(false);
+
+        return response.AsOpenAIResponse();
+    }
+
+    /// <summary>
+    /// Run the agent streaming with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ResponseResult"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual async IAsyncEnumerable<StreamingResponseUpdate> RunStreamingAsync(
+        IEnumerable<ResponseItem> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        var response = this.RunStreamingAsync(messages.AsChatMessages(), thread, options, cancellationToken);
+
+        await foreach (var update in response.ConfigureAwait(false))
+        {
+            switch (update.RawRepresentation)
+            {
+                case StreamingResponseUpdate rawUpdate:
+                    yield return rawUpdate;
+                    break;
+
+                case ChatResponseUpdate { RawRepresentation: StreamingResponseUpdate rawUpdate }:
+                    yield return rawUpdate;
+                    break;
+
+                default:
+                    // TODO: The OpenAI library does not currently expose model factory methods for creating
+                    // StreamingResponseUpdates. We are thus unable to manufacture such instances when there isn't
+                    // already one in the update and instead skip them.
+                    break;
+            }
+        }
+    }
+
+    /// <inheritdoc/>
+    protected sealed override Task<AgentRunResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreAsync(messages, thread, options, cancellationToken);
+
+    /// <inheritdoc/>
+    protected sealed override IAsyncEnumerable<AgentRunResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreStreamingAsync(messages, thread, options, cancellationToken);
+}

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Program.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to create OpenAIResponseClientAgent directly from an ResponsesClient instance.
+
+using OpenAI;
+using OpenAI.Responses;
+using OpenAIResponseClientSample;
+
+var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
+
+// Create a ResponsesClient directly from OpenAIClient
+ResponsesClient responseClient = new OpenAIClient(apiKey).GetResponsesClient(model);
+
+// Create an agent directly from the ResponsesClient using OpenAIResponseClientAgent
+OpenAIResponseClientAgent agent = new(responseClient, instructions: "You are good at telling jokes.", name: "Joker");
+
+ResponseItem userMessage = ResponseItem.CreateUserMessageItem("Tell me a joke about a pirate.");
+
+// Invoke the agent and output the text result.
+ResponseResult response = await agent.RunAsync([userMessage]);
+Console.WriteLine(response.GetOutputText());
+
+// Invoke the agent with streaming support.
+IAsyncEnumerable<StreamingResponseUpdate> responseUpdates = agent.RunStreamingAsync([userMessage]);
+await foreach (StreamingResponseUpdate responseUpdate in responseUpdates)
+{
+    if (responseUpdate is StreamingResponseOutputTextDeltaUpdate textUpdate)
+    {
+        Console.WriteLine(textUpdate.Delta);
+    }
+}

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/README.md

@@ -0,0 +1,22 @@
+# Creating an Agent from an OpenAIResponseClient
+
+This sample demonstrates how to create an AI agent directly from an `OpenAI.Responses.OpenAIResponseClient` instance using the `OpenAIResponseClientAgent` class.
+
+## What This Sample Shows
+
+- **Direct OpenAIResponseClient Creation**: Shows how to create an `OpenAI.Responses.OpenAIResponseClient` from `OpenAI.OpenAIClient` and then use it to instantiate an agent
+- **OpenAIResponseClientAgent**: Demonstrates using the OpenAI SDK primitives instead of the ones from Microsoft.Extensions.AI and Microsoft.Agents.AI abstractions
+- **Full Agent Capabilities**: Shows both regular and streaming invocation of the agent
+
+## Running the Sample
+
+1. Set the required environment variables:
+   ```bash
+   set OPENAI_API_KEY=your_api_key_here
+   set OPENAI_MODEL=gpt-4o-mini
+   ```
+
+2. Run the sample:
+   ```bash
+   dotnet run
+   ```

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Program.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to maintain conversation state using the OpenAIResponseClientAgent
+// and AgentThread. By passing the same thread to multiple agent invocations, the agent
+// automatically maintains the conversation history, allowing the AI model to understand
+// context from previous exchanges.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Chat;
+using OpenAI.Conversations;
+
+string apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+string model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
+
+// Create a ConversationClient directly from OpenAIClient
+OpenAIClient openAIClient = new(apiKey);
+ConversationClient conversationClient = openAIClient.GetConversationClient();
+
+// Create an agent directly from the ResponsesClient using OpenAIResponseClientAgent
+ChatClientAgent agent = new(openAIClient.GetResponsesClient(model).AsIChatClient(), instructions: "You are a helpful assistant.", name: "ConversationAgent");
+
+ClientResult createConversationResult = await conversationClient.CreateConversationAsync(BinaryContent.Create(BinaryData.FromString("{}")));
+
+using JsonDocument createConversationResultAsJson = JsonDocument.Parse(createConversationResult.GetRawResponse().Content.ToString());
+string conversationId = createConversationResultAsJson.RootElement.GetProperty("id"u8)!.GetString()!;
+
+// Create a thread for the conversation - this enables conversation state management for subsequent turns
+AgentThread thread = agent.GetNewThread(conversationId);
+
+Console.WriteLine("=== Multi-turn Conversation Demo ===\n");
+
+// First turn: Ask about a topic
+Console.WriteLine("User: What is the capital of France?");
+UserChatMessage firstMessage = new("What is the capital of France?");
+
+// After this call, the conversation state associated in the options is stored in 'thread' and used in subsequent calls
+ChatCompletion firstResponse = await agent.RunAsync([firstMessage], thread);
+Console.WriteLine($"Assistant: {firstResponse.Content.Last().Text}\n");
+
+// Second turn: Follow-up question that relies on conversation context
+Console.WriteLine("User: What famous landmarks are located there?");
+UserChatMessage secondMessage = new("What famous landmarks are located there?");
+
+ChatCompletion secondResponse = await agent.RunAsync([secondMessage], thread);
+Console.WriteLine($"Assistant: {secondResponse.Content.Last().Text}\n");
+
+// Third turn: Another follow-up that demonstrates context continuity
+Console.WriteLine("User: How tall is the most famous one?");
+UserChatMessage thirdMessage = new("How tall is the most famous one?");
+
+ChatCompletion thirdResponse = await agent.RunAsync([thirdMessage], thread);
+Console.WriteLine($"Assistant: {thirdResponse.Content.Last().Text}\n");
+
+Console.WriteLine("=== End of Conversation ===");
+
+// Show full conversation history
+Console.WriteLine("Full Conversation History:");
+ClientResult getConversationResult = await conversationClient.GetConversationAsync(conversationId);
+
+Console.WriteLine("Conversation created.");
+Console.WriteLine($"    Conversation ID: {conversationId}");
+Console.WriteLine();
+
+CollectionResult getConversationItemsResults = conversationClient.GetConversationItems(conversationId);
+foreach (ClientResult result in getConversationItemsResults.GetRawPages())
+{
+    Console.WriteLine("Message contents retrieved. Order is most recent first by default.");
+    using JsonDocument getConversationItemsResultAsJson = JsonDocument.Parse(result.GetRawResponse().Content.ToString());
+    foreach (JsonElement element in getConversationItemsResultAsJson.RootElement.GetProperty("data").EnumerateArray())
+    {
+        string messageId = element.GetProperty("id"u8).ToString();
+        string messageRole = element.GetProperty("role"u8).ToString();
+        Console.WriteLine($"    Message ID: {messageId}");
+        Console.WriteLine($"    Message Role: {messageRole}");
+
+        foreach (var content in element.GetProperty("content").EnumerateArray())
+        {
+            string messageContentText = content.GetProperty("text"u8).ToString();
+            Console.WriteLine($"    Message Text: {messageContentText}");
+        }
+        Console.WriteLine();
+    }
+}
+
+ClientResult deleteConversationResult = conversationClient.DeleteConversation(conversationId);
+using JsonDocument deleteConversationResultAsJson = JsonDocument.Parse(deleteConversationResult.GetRawResponse().Content.ToString());
+bool deleted = deleteConversationResultAsJson.RootElement
+    .GetProperty("deleted"u8)
+    .GetBoolean();
+
+Console.WriteLine("Conversation deleted.");
+Console.WriteLine($"    Deleted: {deleted}");
+Console.WriteLine();

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/README.md

@@ -0,0 +1,90 @@
+# Managing Conversation State with OpenAI
+
+This sample demonstrates how to maintain conversation state across multiple turns using the Agent Framework with OpenAI's Conversation API.
+
+## What This Sample Shows
+
+- **Conversation State Management**: Shows how to use `ConversationClient` and `AgentThread` to maintain conversation context across multiple agent invocations
+- **Multi-turn Conversations**: Demonstrates follow-up questions that rely on context from previous messages in the conversation
+- **Server-Side Storage**: Uses OpenAI's Conversation API to manage conversation history server-side, allowing the model to access previous messages without resending them
+- **Conversation Lifecycle**: Demonstrates creating, retrieving, and deleting conversations
+
+## Key Concepts
+
+### ConversationClient for Server-Side Storage
+
+The `ConversationClient` manages conversations on OpenAI's servers:
+
+```csharp
+// Create a ConversationClient from OpenAIClient
+OpenAIClient openAIClient = new(apiKey);
+ConversationClient conversationClient = openAIClient.GetConversationClient();
+
+// Create a new conversation
+ClientResult createConversationResult = await conversationClient.CreateConversationAsync(BinaryContent.Create(BinaryData.FromString("{}")));
+```
+
+### AgentThread for Conversation State
+
+The `AgentThread` works with `ChatClientAgentRunOptions` to link the agent to a server-side conversation:
+
+```csharp
+// Set up agent run options with the conversation ID
+ChatClientAgentRunOptions agentRunOptions = new() { ChatOptions = new ChatOptions() { ConversationId = conversationId } };
+
+// Create a thread for the conversation
+AgentThread thread = agent.GetNewThread();
+
+// First call links the thread to the conversation
+ChatCompletion firstResponse = await agent.RunAsync([firstMessage], thread, agentRunOptions);
+
+// Subsequent calls use the thread without needing to pass options again
+ChatCompletion secondResponse = await agent.RunAsync([secondMessage], thread);
+```
+
+### Retrieving Conversation History
+
+You can retrieve the full conversation history from the server:
+
+```csharp
+CollectionResult getConversationItemsResults = conversationClient.GetConversationItems(conversationId);
+foreach (ClientResult result in getConversationItemsResults.GetRawPages())
+{
+    // Process conversation items
+}
+```
+
+### How It Works
+
+1. **Create an OpenAI Client**: Initialize an `OpenAIClient` with your API key
+2. **Create a Conversation**: Use `ConversationClient` to create a server-side conversation
+3. **Create an Agent**: Initialize an `OpenAIResponseClientAgent` with the desired model and instructions
+4. **Create a Thread**: Call `agent.GetNewThread()` to create a new conversation thread
+5. **Link Thread to Conversation**: Pass `ChatClientAgentRunOptions` with the `ConversationId` on the first call
+6. **Send Messages**: Subsequent calls to `agent.RunAsync()` only need the thread - context is maintained
+7. **Cleanup**: Delete the conversation when done using `conversationClient.DeleteConversation()`
+
+## Running the Sample
+
+1. Set the required environment variables:
+   ```powershell
+   $env:OPENAI_API_KEY = "your_api_key_here"
+   $env:OPENAI_MODEL = "gpt-4o-mini"
+   ```
+
+2. Run the sample:
+   ```powershell
+   dotnet run
+   ```
+
+## Expected Output
+
+The sample demonstrates a three-turn conversation where each follow-up question relies on context from previous messages:
+
+1. First question asks about the capital of France
+2. Second question asks about landmarks "there" - requiring understanding of the previous answer
+3. Third question asks about "the most famous one" - requiring context from both previous turns
+
+After the conversation, the sample retrieves and displays the full conversation history from the server, then cleans up by deleting the conversation.
+
+This demonstrates that the conversation state is properly maintained across multiple agent invocations using OpenAI's server-side conversation storage.

dotnet/samples/GettingStarted/AgentWithOpenAI/README.md

@@ -10,5 +10,8 @@ Agent Framework provides additional support to allow OpenAI developers to use th
 
 |Sample|Description|
 |---|---|
-|[Creating an AIAgent](./Agent_OpenAI_Step01_Running/)|This sample demonstrates how to create and run a basic agent instructions with native OpenAI SDK types.|
-
+|[Creating an AIAgent](./Agent_OpenAI_Step01_Running/)|This sample demonstrates how to create and run a basic agent with native OpenAI SDK types. Shows both regular and streaming invocation of the agent.|
+|[Using Reasoning Capabilities](./Agent_OpenAI_Step02_Reasoning/)|This sample demonstrates how to create an AI agent with reasoning capabilities using OpenAI's reasoning models and response types.|
+|[Creating an Agent from a ChatClient](./Agent_OpenAI_Step03_CreateFromChatClient/)|This sample demonstrates how to create an AI agent directly from an OpenAI.Chat.ChatClient instance using OpenAIChatClientAgent.|
+|[Creating an Agent from an OpenAIResponseClient](./Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/)|This sample demonstrates how to create an AI agent directly from an OpenAI.Responses.OpenAIResponseClient instance using OpenAIResponseClientAgent.|
+|[Managing Conversation State](./Agent_OpenAI_Step05_Conversation/)|This sample demonstrates how to maintain conversation state across multiple turns using the AgentThread for context continuity.|

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -8,12 +8,11 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Data;
 using Microsoft.Agents.AI.Samples;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.InMemory;
-using OpenAI;
+using OpenAI.Chat;
 
 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";
@@ -62,7 +61,7 @@ AIAgent agent = azureOpenAIClient
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
         AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -7,11 +7,10 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Data;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.Qdrant;
-using OpenAI;
+using OpenAI.Chat;
 using Qdrant.Client;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
@@ -71,7 +70,7 @@ AIAgent agent = azureOpenAIClient
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
         AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/Program.cs

@@ -9,9 +9,8 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Data;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";
@@ -29,7 +28,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
         AIContextProviderFactory = ctx => new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

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

@@ -5,7 +5,7 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -5,7 +5,7 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -8,7 +8,7 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -10,7 +10,8 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 
 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";

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

@@ -8,7 +8,6 @@ using System.Text.Json.Serialization;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
 using OpenAI.Chat;
 using SampleApp;
 
@@ -22,7 +21,7 @@ ChatClient chatClient = new AzureOpenAIClient(
         .GetChatClient(deploymentName);
 
 // Create the ChatClientAgent with the specified name and instructions.
-ChatClientAgent agent = chatClient.CreateAIAgent(new ChatClientAgentOptions(name: "HelpfulAssistant", instructions: "You are a helpful assistant."));
+ChatClientAgent agent = chatClient.CreateAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
 
 // Set PersonInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke the agent with some unstructured input.
 AgentRunResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
@@ -34,12 +33,10 @@ Console.WriteLine($"Age: {response.Result.Age}");
 Console.WriteLine($"Occupation: {response.Result.Occupation}");
 
 // Create the ChatClientAgent with the specified name, instructions, and expected structured output the agent should produce.
-ChatClientAgent agentWithPersonInfo = chatClient.CreateAIAgent(new ChatClientAgentOptions(name: "HelpfulAssistant", instructions: "You are a helpful assistant.")
+ChatClientAgent agentWithPersonInfo = chatClient.CreateAIAgent(new ChatClientAgentOptions()
 {
-    ChatOptions = new()
-    {
-        ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>()
-    }
+    Name = "HelpfulAssistant",
+    ChatOptions = new() { Instructions = "You are a helpful assistant.", ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>() }
 });
 
 // Invoke the agent with some unstructured input while streaming, to extract the structured information from.

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

@@ -6,7 +6,7 @@ using System.Text.Json;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -11,8 +11,9 @@ using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.InMemory;
-using OpenAI;
+using OpenAI.Chat;
 using SampleApp;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 
 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";
@@ -43,7 +44,7 @@ async Task CustomChatMessageStore_UsingFactory_Async()
         .GetChatClient(deploymentName)
         .CreateAIAgent(new ChatClientAgentOptions
         {
-            Instructions = "You are good at telling jokes.",
+            ChatOptions = new() { Instructions = "You are good at telling jokes." },
             Name = "Joker",
             ChatMessageStoreFactory = ctx =>
             {
@@ -95,7 +96,7 @@ async Task CustomChatMessageStore_UsingFactoryAndExistingExternalId_Async()
         .GetChatClient(deploymentName)
         .CreateAIAgent(new ChatClientAgentOptions
         {
-            Instructions = "You are good at telling jokes.",
+            ChatOptions = new() { Instructions = "You are good at telling jokes." },
             Name = "Joker",
             ChatMessageStoreFactory = ctx =>
             {
@@ -139,7 +140,7 @@ async Task CustomChatMessageStore_PerThread_Async()
         .GetChatClient(deploymentName)
         .CreateAIAgent(new ChatClientAgentOptions
         {
-            Instructions = "You are good at telling jokes.",
+            ChatOptions = new() { Instructions = "You are good at telling jokes." },
             Name = "Joker"
         });
 
@@ -174,7 +175,7 @@ async Task CustomChatMessageStore_PerRun_Async()
         .GetChatClient(deploymentName)
         .CreateAIAgent(new ChatClientAgentOptions
         {
-            Instructions = "You are good at telling jokes.",
+            ChatOptions = new() { Instructions = "You are good at telling jokes." },
             Name = "Joker"
         });
 

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

@@ -6,7 +6,7 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Azure.Monitor.OpenTelemetry.Exporter;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Chat;
 using OpenTelemetry;
 using OpenTelemetry.Trace;
 

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

@@ -18,8 +18,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 
 // Add agent options to the service collection.
-builder.Services.AddSingleton(
-    new ChatClientAgentOptions(instructions: "You are good at telling jokes.", name: "Joker"));
+builder.Services.AddSingleton(new ChatClientAgentOptions() { Name = "Joker", ChatOptions = new() { Instructions = "You are good at telling jokes." } });
 
 // Add a chat client to the service collection.
 builder.Services.AddKeyedChatClient("AzureOpenAI", (sp) => new AzureOpenAIClient(

dotnet/samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj

@@ -16,10 +16,6 @@
     <PackageReference Include="ModelContextProtocol" />
   </ItemGroup>
 
-  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible($(TargetFramework), 'net10.0'))">
-    <PackageReference Include="System.Net.ServerSentEvents" />
-  </ItemGroup>
-
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
   </ItemGroup>

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

@@ -5,7 +5,8 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";

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

@@ -7,7 +7,7 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -12,7 +12,7 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Responses;
 
 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-5";
@@ -22,7 +22,7 @@ var stateStore = new Dictionary<string, JsonElement?>();
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
     new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
      .CreateAIAgent(
         name: "SpaceNovelWriter",
         instructions: "You are a space novel writer. Always research relevant facts and generate character profiles for the main characters before writing novels." +

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

@@ -14,7 +14,7 @@ using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
-using OpenAI;
+using OpenAI.Chat;
 
 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";

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

@@ -9,7 +9,8 @@ using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
+using OpenAI.Chat;
+using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 
 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";
@@ -21,7 +22,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are good at telling jokes.",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
         ChatMessageStoreFactory = ctx => new InMemoryChatMessageStore(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions)
     });

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

@@ -5,7 +5,7 @@
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI;
+using OpenAI.Responses;
 
 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";
@@ -13,7 +13,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
     new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
      .CreateAIAgent();
 
 // Enable background responses (only supported by OpenAI Responses at this time).

dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel.Json" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel.PowerFx" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Declarative\Microsoft.Agents.AI.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create an agent from a YAML based declarative representation.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+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";
+
+// Create the chat client
+IChatClient chatClient = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+     .GetChatClient(deploymentName)
+     .AsIChatClient();
+
+// Define the agent using a YAML definition.
+var text =
+    """
+    kind: Prompt
+    name: Assistant
+    description: Helpful assistant
+    instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format.
+    model:
+        options:
+            temperature: 0.9
+            topP: 0.95
+    outputSchema:
+        properties:
+            language:
+                type: string
+                required: true
+                description: The language of the answer.
+            answer:
+                type: string
+                required: true
+                description: The answer text.
+    """;
+
+// Create the agent from the YAML definition.
+var agentFactory = new ChatClientPromptAgentFactory(chatClient);
+var agent = await agentFactory.CreateFromYamlAsync(text);
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent!.RunAsync("Tell me a joke about a pirate in English."));
+
+// Invoke the agent with streaming support.
+await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pirate in French."))
+{
+    Console.WriteLine(update);
+}

dotnet/samples/GettingStarted/Agents/README.md

@@ -45,6 +45,7 @@ Before you begin, ensure you have the following prerequisites:
 |[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|
 |[Deep research with an agent](./Agent_Step18_DeepResearch/)|This sample demonstrates how to use the Deep Research Tool to perform comprehensive research on complex topics|
+|[Declarative agent](./Agent_Step19_Declarative/)|This sample demonstrates how to declaratively define an agent.|
 
 ## Running the samples from the console
 

dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel.Json" />
+    <PackageReference Include="Microsoft.Bot.ObjectModel.PowerFx" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Declarative\Microsoft.Agents.AI.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>